Add rebased OpenClaw x AtoCore V1 review docs

2026-04-23 16:11:00 +00:00
parent c53e61eb67
commit 87ededb71c
8 changed files with 2104 additions and 0 deletions
--- a/docs/openclaw-atocore-audit-note.md
+++ b/docs/openclaw-atocore-audit-note.md
@@ -0,0 +1,317 @@
+# 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.