ATOCore/docs/openclaw-atocore-audit-note.md

# OpenClaw x AtoCore V1 Audit Note

## Scope

This note is the Phase 1 audit for a safe OpenClaw x AtoCore operating model.
It covers only what was directly verified in `/home/papa/ATOCore` and `/home/papa/clawd` on 2026-04-23, plus explicit assumptions called out as assumptions.

This phase does not change code, runtime behavior, skills, helpers, or automation.

## Files requested and verified

The following requested AtoCore files were present and reviewed:

- `docs/openclaw-integration-contract.md`
- `docs/architecture/llm-client-integration.md`
- `docs/architecture/representation-authority.md`
- `docs/operating-model.md`
- `docs/current-state.md`
- `docs/master-plan-status.md`
- `docs/operations.md`
- `AGENTS.md`
- `CLAUDE.md`
- `DEV-LEDGER.md`

No requested files were missing.

## What was directly verified

### 1. OpenClaw instruction surface

In `/home/papa/clawd/AGENTS.md`, OpenClaw is currently instructed to:

- use the `atocore-context` skill for project-dependent work
- treat AtoCore as additive and fail-open
- prefer `auto-context` for project knowledge questions
- prefer `project-state` for trusted current truth
- use `refresh-project` if the human explicitly asked to refresh or ingest project changes
- use `discrawl` automatically when Antoine asks about prior Discord discussions

This is already close to the intended additive read path, but it also exposes mutating project operations in a general operator workflow.

### 2. OpenClaw helper skill surface

The current helper skill is:

- `/home/papa/clawd/skills/atocore-context/SKILL.md`
- `/home/papa/clawd/skills/atocore-context/scripts/atocore.sh`

The skill describes AtoCore as a read-only additive context service, but the helper script currently exposes the following commands:

- `health`
- `sources`
- `stats`
- `projects`
- `project-template`
- `detect-project`
- `auto-context`
- `debug-context`
- `propose-project`
- `register-project`
- `update-project`
- `refresh-project`
- `project-state`
- `query`
- `context-build`
- `ingest-sources`

That means the helper is not actually read-only. It can drive registry mutation and ingestion-related operations.

### 3. AtoCore shared operator client surface

The shared operator client in `/home/papa/ATOCore/scripts/atocore_client.py` exposes a broader surface than the OpenClaw helper, including:

- all of the project and context operations above
- `project-state-set`
- `project-state-invalidate`
- `capture`
- `extract`
- `reinforce-interaction`
- `list-interactions`
- `get-interaction`
- `queue`
- `promote`
- `reject`
- `batch-extract`
- `triage`

This matches the architectural intent in `docs/architecture/llm-client-integration.md`: a shared operator client should be the canonical reusable surface for multiple frontends.

### 4. Actual layering status today

The intended layering is documented in `docs/architecture/llm-client-integration.md` as:

- AtoCore HTTP API
- shared operator client
- thin per-agent frontends

But the current OpenClaw helper is still its own Bash implementation. It does not shell out to the shared operator client today.

So the shared-client pattern is documented, but not yet applied to OpenClaw.

### 5. AtoCore availability and fail-open behavior

The OpenClaw helper successfully reached the live AtoCore instance during this audit.

Verified live behavior:

- `health` worked
- `projects` worked
- the helper still has fail-open logic when network access fails

This part is consistent with the stated additive and fail-open stance.

### 6. Discrawl availability

The `discrawl` CLI is installed locally and available.

Verified during audit:

- binary present
- version `0.3.0`
- OpenClaw workspace instructions explicitly route project-history recall through `discrawl`

This supports the desired framing of Discord and Discrawl as an evidence stream.

### 7. Screenpipe status

`screenpipe` was not present as a local command in this environment during the audit.

For V1, Screenpipe is deferred and out of scope. No active Screenpipe input lane was verified or adopted in the final V1 policy.

## Current implementation shape

### What OpenClaw can do safely right now

The current safe, directly verified OpenClaw -> AtoCore path is:

- project detection
- context build
- query and retrieval
- project-state read
- service inspection
- fail-open fallback

That is the mature part of the integration.

### What OpenClaw can also do today, but should be treated as controlled operator actions

The current helper also exposes:

- project proposal preview
- project registration
- project update
- project refresh
- ingest-sources

These should not be treated as background or conversational automation. They are operator actions and need explicit approval policy.

### What exists in AtoCore but is not exposed through the OpenClaw helper

The shared operator client already supports:

- interaction capture
- candidate extraction
- queue review
- promote or reject
- trusted project-state write and invalidate

The current OpenClaw helper does not expose that surface.

This is important for V1 design: the write-capable lanes already exist in AtoCore, but they are not yet safely shaped for Discord-originated automation.

## Conflicts with the target V1 stance

The following conflicts are real and should be named explicitly.

### Conflict 1 - the OpenClaw helper is described as read-only, but it is not read-only

`SKILL.md` frames the integration as read-only additive context.
`atocore.sh` exposes mutating operations:

- `register-project`
- `update-project`
- `refresh-project`
- `ingest-sources`

That mismatch needs a policy fix in Phase 2. For Phase 1 it must be documented as a conflict.

### Conflict 2 - OpenClaw duplicates client logic instead of using the shared operator client

The architecture docs prefer a shared operator client reused across frontends.
The OpenClaw helper currently reimplements request logic and project detection in Bash.

That is a direct conflict with the preferred shared-client pattern.

### Conflict 3 - mutating project operations are too close to the conversational surface

The helper makes registry and ingestion operations reachable from the OpenClaw side without a dedicated Discord-specific approval gate.

Even if the human explicitly asks for a refresh, the current shape does not yet distinguish between:

- a direct trusted operator action in a controlled session
- a Discord-originated conversational path that should require an explicit human approval step before mutation

The Phase 2 V1 policy needs that distinction.

### Conflict 4 - current docs overstate or blur write capabilities

`docs/current-state.md` says OpenClaw can seed AtoCore through project-scoped memory entries and staged document ingestion.
That was not directly verified through the current OpenClaw helper surface in `/home/papa/clawd`.

The helper script does not expose:

- `capture`
- `extract`
- `promote`
- `reject`
- `project-state-set`

So there is at least a documentation and runtime-surface mismatch.

### Conflict 5 - there was no single OpenClaw-facing evidence lane description before this doc set

The target architecture needs a clean distinction between:

- raw evidence
- reviewable candidates
- active memories and entities
- trusted project_state

Today that distinction exists conceptually across several AtoCore docs, but before this Phase 1 doc set there was no single OpenClaw-facing operating model that told an operator exactly where Discord and Discrawl signals are allowed to land.

That is the main gap this doc set closes.

## What is already aligned with the target V1 stance

Several important pieces are already aligned.

### Aligned 1 - additive plus fail-open

Both AtoCore and OpenClaw docs consistently say AtoCore should be additive and fail-open from the OpenClaw side.
That is the right baseline and was verified live.

### Aligned 2 - project_state is already treated as special and curated

AtoCore architecture docs already treat `project_state` as the highest-trust curated layer.
This supports the rule that raw signals must not directly auto-write trusted project state.

### Aligned 3 - canonical-home thinking already exists

`docs/architecture/representation-authority.md` already establishes that each fact type needs one canonical home.
That is exactly the right foundation for the Discord and Discrawl design.

### Aligned 4 - reflection and candidate lifecycle already exists in AtoCore

The shared operator client and AtoCore docs already have a candidate workflow:

- capture
- extract
- queue
- promote or reject

That means V1 does not need to invent a new trust model. It needs to apply the existing one correctly to Discord and Discrawl signals.

## Recommended V1 operating interpretation

Until implementation work begins, the safest V1 operating interpretation is:

1. Discord and Discrawl are evidence sources, not truth sources.
2. OpenClaw is the orchestrator and operator, not canonical storage.
3. AtoCore memories may hold reviewed episodic, personal, and loose project signal.
4. Future AtoCore entities should hold reviewed structured decisions, requirements, and constraints.
5. `project_state` remains manual or tightly gated only.
6. Registry mutation, refresh, ingestion, and candidate promotion or rejection require explicit human approval on Discord-originated paths.
7. The shared operator client should become the only write-capable operator surface reused by OpenClaw and other frontends.
8. Screenpipe remains deferred and out of V1 scope.

## Assumption log

The following points were not directly verified and must stay labeled as assumptions.

1. Screenpipe integration shape is unverified and deferred.
   - The `screenpipe` command was not present locally.
   - No verified Screenpipe pipeline files were found in the inspected workspaces.
   - V1 therefore excludes Screenpipe from active policy and runtime scope.

2. No direct Discord -> AtoCore auto-mutation path was verified in code.
   - The OpenClaw workspace clearly contains read and query context behavior and a Discrawl retrieval rule.
   - It does not clearly expose a verified Discord-triggered path that auto-calls `project-state-set`, `promote`, `reject`, or `register-project`.
   - The risk is therefore policy and proximity of commands, not a proven live mutation bug.

3. OpenClaw runtime use of the shared operator client was not verified because it is not implemented yet.
   - The shared client exists in the AtoCore repo.
   - The OpenClaw helper is still its own Bash implementation.

4. A dedicated evidence store was not verified as a first-class AtoCore schema layer.
   - Existing AtoCore surfaces clearly support interactions and candidate memories.
   - This V1 model therefore uses evidence artifacts, interactions, and archive bundles as an architectural lane, without claiming a new implemented table already exists.

5. Future entities remain future.
   - The entity layer is architected in AtoCore docs.
   - This audit did not verify a production entity promotion flow being used by OpenClaw.

## Bottom line

The good news is that the trust foundations already exist.

The main conclusion is that the current system is closest to a safe V1 when interpreted this way:

- keep AtoCore additive and fail-open
- treat Discord and Discrawl as evidence only
- route reviewed signal into memory candidates first
- reserve `project_state` for explicit curation only
- move OpenClaw toward the shared operator client instead of maintaining a separate write-capable helper surface
- keep Screenpipe out of V1

That gives a coherent path to Phase 2 without pretending the current implementation is already there.