diff --git a/DEV-LEDGER.md b/DEV-LEDGER.md index ac3f726..b631741 100644 --- a/DEV-LEDGER.md +++ b/DEV-LEDGER.md @@ -146,6 +146,10 @@ One branch `codex/extractor-eval-loop` for Day 1-5, a second `codex/retrieval-ha ## Session Log +- **2026-04-23 Codex** Phase 2 policy/doc cleanup for the OpenClaw x AtoCore operating model. Normalized the 5 Phase 1 docs to clean ASCII, removed Screenpipe from V1 active scope, added `docs/openclaw-atocore-v1-proof-runbook.md`, and added a non-applied shared-client consolidation preview at `docs/openclaw-atocore-shared-client-consolidation-preview.md`. Also updated OpenClaw governance text in `/home/papa/clawd/AGENTS.md` and `/home/papa/clawd/skills/atocore-context/SKILL.md` so Discord-originated AtoCore actions are read-only by default and mutating actions require explicit current-thread/session approval. No code/runtime/schema changes, no deploy, no tests run. + +- **2026-04-23 Codex** Phase 1 OpenClaw × AtoCore operating-model audit/design/doc pass only. Read AGENTS/CLAUDE/DEV-LEDGER plus requested integration docs, verified OpenClaw helper surface vs shared operator client, confirmed live fail-open read path, confirmed discrawl presence, and confirmed Screenpipe was not installed locally. Wrote 5 new docs: `docs/openclaw-atocore-audit-note.md`, `docs/openclaw-atocore-v1-architecture.md`, `docs/openclaw-atocore-write-policy-matrix.md`, `docs/openclaw-atocore-promotion-pipeline.md`, `docs/openclaw-atocore-nightly-screener-runbook.md`. No code/runtime/skill changes, no deploy, no tests run. + - **2026-04-12 Claude** Wave 2 trusted operational ingestion + codex audit response. Read 6 vault docs, created 8 new Trusted Project State entries (p04 +2, p05 +3, p06 +3). Fixed R6 (project fallback in LLM extractor) per codex audit. Fixed misscoped p06 offline memory on live Dalidou. Merged codex/audit-2026-04-12. Switched default LLM model from haiku to sonnet. Harness 15/18 -> 16/18. Tests 278 -> 280. main_tip 146f2e4 -> 39d73e9. - **2026-04-12 Codex (audit branch `codex/audit-2026-04-12`)** audited `c5bad99..146f2e4` against code, live Dalidou, and the 36 active memories. Confirmed: `claude -p` invocation is not shell-injection-prone (`subprocess.run(args)` with no shell), off-host backup wiring matches the ledger, and R1 remains unresolved in practice. Added R5-R8. Corrected Orientation `main_tip` (`146f2e4`, not `5c69f77`) and tightened the harness note: p06-firmware-interface is a ranking-tie issue, p06-offline-design comes from a project-scope miss in live triage, and p06-tailscale is retrieved-chunk bleed rather than memory-band budget contention. diff --git a/docs/openclaw-atocore-audit-note.md b/docs/openclaw-atocore-audit-note.md new file mode 100644 index 0000000..a1b7a38 --- /dev/null +++ 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. diff --git a/docs/openclaw-atocore-nightly-screener-runbook.md b/docs/openclaw-atocore-nightly-screener-runbook.md new file mode 100644 index 0000000..e242be5 --- /dev/null +++ b/docs/openclaw-atocore-nightly-screener-runbook.md @@ -0,0 +1,354 @@ +# OpenClaw x AtoCore Nightly Screener Runbook + +## Purpose + +The nightly screener is the V1 bridge between broad evidence capture and narrow trusted state. + +Its job is to: + +- gather raw evidence from approved V1 sources +- reduce noise +- produce reviewable candidate material +- prepare operator review work +- never silently create trusted truth + +## Scope + +The nightly screener is a screening and preparation job. +It is not a trusted-state writer. +It is not a registry operator. +It is not a hidden reviewer. + +V1 active inputs are: + +- Discord and Discrawl evidence +- OpenClaw interaction evidence +- PKM, repos, and KB references +- read-only AtoCore context for comparison and deduplication + +## Explicit approval rule + +If the screener output points at a mutating operator action, that action still requires: + +- direct human instruction +- in the current thread or current session +- for that specific action +- with no inference from evidence or screener output alone + +The screener may recommend review. It may not manufacture approval. + +## Inputs + +The screener may consume the following inputs when available. + +### 1. Discord and Discrawl evidence + +Examples: + +- recent archived Discord messages +- thread excerpts relevant to known projects +- conversation clusters around decisions, requirements, constraints, or repeated questions + +### 2. OpenClaw interaction evidence + +Examples: + +- captured interactions +- recent operator conversations relevant to projects +- already-logged evidence bundles + +### 3. Read-only AtoCore context inputs + +Examples: + +- project registry lookup for project matching +- project_state read for comparison only +- memory or entity lookups for deduplication only + +These reads may help the screener rank or classify candidates, but they must not be used as a write side effect. + +### 4. Optional canonical-source references + +Examples: + +- PKM notes +- repo docs +- KB-export summaries + +These may be consulted to decide whether a signal appears to duplicate or contradict already-canonical truth. + +## Outputs + +The screener should produce output in four buckets. + +### 1. Nightly screener report + +A compact report describing: + +- inputs seen +- items skipped +- candidate counts +- project match confidence distribution +- failures or unavailable sources +- items requiring human review + +### 2. Evidence bundle or manifest + +A structured bundle of the source snippets that justified each candidate or unresolved item. +This is the reviewer's provenance package. + +### 3. Candidate manifests + +Separate candidate manifests for: + +- memory candidates +- entity candidates later +- unresolved "needs canonical-source update first" items + +### 4. Operator action queue + +A short list of items needing explicit human action, such as: + +- review these candidates +- decide whether to refresh project X +- decide whether to curate project_state +- decide whether a Discord-originated claim should first be reflected in PKM, repo, or KB + +## Required non-output + +The screener must not directly produce any of the following: + +- active memories without review +- active entities without review +- project_state writes +- registry mutation +- refresh operations +- ingestion operations +- promote or reject decisions + +## Nightly procedure + +### Step 1 - load last-run checkpoint + +Read the last successful screener checkpoint so the run knows: + +- what time range to inspect +- what evidence was already processed +- which items were already dropped or bundled + +If no checkpoint exists, use a conservative bounded time window and mark the run as bootstrap mode. + +### Step 2 - gather evidence + +Collect available evidence from each configured source. + +Per-source rule: + +- source unavailable -> note it, continue +- source empty -> note it, continue +- source noisy -> keep raw capture bounded and deduplicated + +### Step 3 - normalize and deduplicate + +For each collected item: + +- normalize timestamps, source ids, and project hints +- remove exact duplicates +- group repeated or near-identical evidence when practical +- keep provenance pointers intact + +The goal is to avoid flooding review with repeated copies of the same conversation. + +### Step 4 - attempt project association + +For each evidence item, try to associate it with: + +- a registered project id, or +- `unassigned` if confidence is low + +Rules: + +- high confidence match -> attach project id +- low confidence match -> mark as uncertain +- no good match -> leave unassigned + +Do not force a project assignment just to make the output tidier. + +### Step 5 - classify signal type + +Classify each normalized item into one of these buckets: + +- noise / ignore +- evidence only +- memory candidate +- entity candidate +- needs canonical-source update first +- needs explicit operator decision + +If the classification is uncertain, choose the lower-trust bucket. + +### Step 6 - compare against higher-trust layers + +For non-noise items, compare against the current higher-trust landscape. + +Check for: + +- already-active equivalent memory +- already-active equivalent entity later +- existing project_state answer +- obvious duplication of canonical source truth +- obvious contradiction with canonical source truth + +This comparison is read-only. +It is used only to rank and annotate output. + +### Step 7 - build candidate bundles + +For each candidate: + +- include the candidate text or shape +- include provenance snippets +- include source type +- include project association confidence +- include reason for candidate classification +- include conflict or duplicate notes if found + +### Step 8 - build unresolved operator queue + +Some items should not become candidates yet. +Examples: + +- "This looks like current truth but should first be updated in PKM, repo, or KB." +- "This Discord-originated request asks for refresh or ingest." +- "This might be a decision, but confidence is too low." + +These belong in a small operator queue, not in trusted state. + +### Step 9 - persist report artifacts only + +Persist only: + +- screener report +- evidence manifests +- candidate manifests +- checkpoint metadata + +If candidate persistence into AtoCore is enabled later, it still remains a candidate-only path and must not skip review. + +### Step 10 - exit fail-open + +If the screener could not reach AtoCore or some source system: + +- write the failure or skip into the report +- keep the checkpoint conservative +- do not fake success +- do not silently mutate anything elsewhere + +## Failure modes + +### Failure mode 1 - AtoCore unavailable + +Behavior: + +- continue in fail-open mode if possible +- write a report that the run was evidence-only or degraded +- do not attempt write-side recovery actions + +### Failure mode 2 - Discrawl unavailable or stale + +Behavior: + +- note Discord archive input unavailable or stale +- continue with other sources +- do not invent Discord evidence summaries + +### Failure mode 3 - candidate explosion + +Behavior: + +- rank candidates +- keep only a bounded top set for review +- put the remainder into a dropped or deferred manifest +- do not overwhelm the reviewer queue + +### Failure mode 4 - low-confidence project mapping + +Behavior: + +- leave items unassigned or uncertain +- do not force them into a project-specific truth lane + +### Failure mode 5 - contradiction with trusted truth + +Behavior: + +- flag the contradiction in the report +- keep the evidence or candidate for review if useful +- do not overwrite project_state + +### Failure mode 6 - direct operator-action request found in evidence + +Examples: + +- "register this project" +- "refresh this source" +- "promote this memory" + +Behavior: + +- place the item into the operator action queue +- require explicit human approval +- do not perform the mutation as part of the screener + +## Review handoff format + +Each screener run should hand off a compact review package containing: + +1. a run summary +2. candidate counts by type and project +3. top candidates with provenance +4. unresolved items needing explicit operator choice +5. unavailable-source notes +6. checkpoint status + +The handoff should be short enough for a human to review without reading the entire raw archive. + +## Safety rules + +The screener must obey these rules every night. + +1. No direct project_state writes. +2. No direct registry mutation. +3. No direct refresh or ingest. +4. No direct promote or reject. +5. No treating Discord or Discrawl as trusted truth. +6. No hiding source uncertainty. +7. No inventing missing integrations. +8. No bringing deferred sources into V1 through policy drift or hidden dependency. + +## Minimum useful run + +A useful screener run can still succeed even if it only does this: + +- gathers available Discord and OpenClaw evidence +- filters obvious noise +- produces a small candidate manifest +- notes unavailable archive inputs if any +- leaves trusted state untouched + +That is still a correct V1 run. + +## Deferred from V1 + +Screenpipe is deferred from V1. It is not an active input, not a required dependency, and not part of the runtime behavior of this V1 screener. + +## Bottom line + +The nightly screener is not the brain of the system. +It is the filter. + +Its purpose is to make human review easier while preserving the trust hierarchy: + +- broad capture in +- narrow reviewed truth out +- no hidden mutations in the middle diff --git a/docs/openclaw-atocore-promotion-pipeline.md b/docs/openclaw-atocore-promotion-pipeline.md new file mode 100644 index 0000000..ebe5fd4 --- /dev/null +++ b/docs/openclaw-atocore-promotion-pipeline.md @@ -0,0 +1,360 @@ +# OpenClaw x AtoCore V1 Promotion Pipeline + +## Purpose + +This document defines the V1 promotion pipeline for signals coming from Discord, Discrawl, OpenClaw, PKM, and repos. + +The rule is simple: + +- raw capture is evidence +- screening turns evidence into candidate material +- review promotes candidates into canonical homes +- trusted state is curated explicitly, not inferred automatically + +## V1 scope + +V1 active inputs are: + +- Discord live conversation +- Discrawl archive retrieval +- OpenClaw interaction logs and evidence bundles +- PKM notes +- repos, KB exports, and repo docs + +Read-only AtoCore context may be consulted for comparison and deduplication. + +## Explicit approval rule + +When this pipeline refers to approval or review for a mutating action, it means: + +- the human directly instructs the specific action +- the instruction is in the current thread or current session +- the approval is for that specific action +- the approval is not inferred from evidence, archives, or screener output + +## Pipeline summary + +```text +raw capture + -> evidence bundle + -> nightly screening + -> candidate queue + -> human review + -> canonical home + -> optional trusted-state curation +``` + +## Stage 0 - raw capture + +### Inputs + +Raw capture may come from: + +- Discord live conversation +- Discrawl archive retrieval +- OpenClaw interaction logs +- PKM notes +- repos / KB exports / repo docs + +### Rule at this stage + +Nothing captured here is trusted truth yet. +Everything is either: + +- raw evidence, or +- a pointer to an already-canonical source + +## Stage 1 - evidence bundle + +The first durable V1 destination for raw signals is the evidence lane. + +Examples of evidence bundle forms: + +- AtoCore interaction records +- Discrawl retrieval result sets +- nightly screener input bundles +- local archived artifacts or manifests +- optional source snapshots used only for review preparation + +### What evidence is for + +Evidence exists so the operator can later answer: + +- what did we actually see? +- where did this claim come from? +- what context supported the candidate? +- what should the reviewer inspect before promoting anything? + +### What evidence is not for + +Evidence is not: + +- active memory +- active entity +- trusted project_state +- registry truth + +## Stage 2 - screening + +The nightly screener or an explicit review flow reads evidence and classifies it. + +### Screening outputs + +Each observed signal should be classified into one of these lanes: + +1. Ignore / noise + - chatter + - duplicate archive material + - ambiguous fragments + - low-signal scraps + +2. Keep as evidence only + - useful context, but too ambiguous or too raw to promote + +3. Memory candidate + - stable enough to review as episodic, personal, or loose project signal + +4. Entity candidate + - structured enough to review as a future decision, requirement, constraint, or validation fact + +5. Needs canonical-source update first + - appears to assert current trusted truth but should first be reflected in the real canonical home, such as PKM, repo, or KB tool + +### Key screening rule + +If the screener cannot confidently tell whether a signal is: + +- raw evidence, +- a loose durable memory, +- or a structured project truth, + +then it must pick the lower-trust lane. + +In V1, uncertainty resolves downward. + +## Stage 3 - candidate queue + +Only screened outputs may enter the candidate queue. + +### Memory-candidate lane + +Use this lane for reviewed-signal candidates such as: + +- preferences +- episodic facts +- identity facts +- loose stable project signal that is useful to remember but not yet a formal structured entity + +Examples: + +- "Antoine prefers operator summaries without extra ceremony." +- "The team discussed moving OpenClaw toward a shared operator client." +- "Discord history is useful as evidence but not as direct truth." + +### Entity-candidate lane + +Use this lane for future structured facts such as: + +- decisions +- requirements +- constraints +- validation claims + +Examples: + +- "Decision: use the shared operator client instead of duplicated frontend logic." +- "Constraint: Discord-originated paths must not directly mutate project_state." + +### What cannot enter directly from raw capture + +The following must not be created directly from raw Discord or Discrawl evidence without a screening step: + +- active memories +- active entities +- project_state entries +- registry mutations +- promote or reject decisions + +## Stage 4 - human review + +This is the load-bearing stage. + +A human reviewer, mediated by OpenClaw and eventually using the shared operator client, decides whether the candidate: + +- should be promoted +- should be rejected +- should stay pending +- should first be rewritten into the actual canonical source +- should become project_state only after stronger curation + +### Review questions + +For every candidate, the reviewer should ask: + +1. Is this actually stable enough to preserve? +2. Is this fact ambiguous, historical, or current? +3. What is the one canonical home for this fact type? +4. Is memory the right home, or should this be an entity later? +5. Is project_state justified, or is this still only evidence or candidate material? +6. Does the source prove current truth, or only past conversation? + +## Stage 5 - canonical promotion + +After review, the signal can move into exactly one canonical home. + +## Promotion rules by fact shape + +### A. Personal, episodic, or loose project signal + +Promotion destination: + +- AtoCore memory + +Use when the fact is durable and useful, but not a formal structured engineering record. + +### B. Structured engineering fact + +Promotion destination: + +- future AtoCore entity + +Use when the fact is really a: + +- decision +- requirement +- constraint +- validation claim + +### C. Current trusted project answer + +Promotion destination: + +- AtoCore project_state + +But only after explicit curation. + +A candidate does not become project_state just because it looks important. +The reviewer must decide that it now represents the trusted current answer. + +### D. Human or tool source truth + +Promotion destination: + +- PKM / repo / KB tool of origin + +If a Discord-originated signal claims current truth but the canonical home is not AtoCore memory or entity, the right move may be: + +1. update the canonical source first +2. then optionally refresh or ingest, with explicit approval if the action is mutating +3. then optionally curate a project_state answer + +This prevents Discord from becoming the hidden source of truth. + +## Stage 6 - optional trusted-state curation + +`project_state` is not the general destination for important facts. +It is the curated destination for current trusted project answers. + +Examples that may justify explicit project_state curation: + +- current selected architecture +- current next milestone +- current status summary +- current trusted decision outcome + +Examples that usually do not justify immediate project_state curation: + +- a raw Discord debate +- a speculative suggestion +- a historical conversation retrieved through Discrawl + +## Discord-originated pipeline examples + +### Example 1 - raw discussion about operator-client refactor + +1. Discord message enters the evidence lane. +2. Nightly screener marks it as either evidence-only or decision candidate. +3. Human review checks whether it is an actual decision or just discussion. +4. If stable and approved, it becomes a memory or future entity. +5. It reaches project_state only if explicitly curated as the trusted current answer. + +### Example 2 - Discord thread says "refresh this project now" + +1. Discord message is evidence of operator intent. +2. It does not auto-trigger refresh. +3. OpenClaw asks for or recognizes explicit human approval. +4. Approved operator action invokes the shared operator client. +5. Refresh result may later influence candidates or trusted state, but the raw Discord message never performed the mutation by itself. + +### Example 3 - archived thread says a requirement might be current + +1. Discrawl retrieval enters the evidence lane. +2. Screener marks it as evidence-only or a requirement candidate. +3. Human review checks the canonical source alignment. +4. If accepted later, it becomes an entity candidate or active entity. +5. project_state remains a separate explicit curation step. + +## Promotion invariants + +The pipeline must preserve these invariants. + +### Invariant 1 - raw evidence is not trusted truth + +No raw Discord or Discrawl signal can directly become trusted project_state. + +### Invariant 2 - unreviewed signals can at most become candidates + +Automatic processing stops at evidence or candidate creation. + +### Invariant 3 - each fact has one canonical home + +A fact may be supported by many evidence items, but after review it belongs in one canonical place. + +### Invariant 4 - operator mutations require explicit approval + +Registry mutation, refresh, ingest, promote, reject, and project_state writes are operator actions. + +### Invariant 5 - OpenClaw orchestrates; it does not become storage + +OpenClaw should coordinate the pipeline, not silently become the canonical data layer. + +## Decision table + +| Observed signal type | Default pipeline outcome | Canonical destination if accepted | +|---|---|---| +| Ambiguous or raw conversation | Evidence only | none | +| Historical archive context | Evidence only or candidate | memory or entity only after review | +| Personal preference | Memory candidate | AtoCore memory | +| Episodic fact | Memory candidate | AtoCore memory | +| Loose stable project signal | Memory candidate | AtoCore memory | +| Structured decision / requirement / constraint | Entity candidate | future AtoCore entity | +| Claimed current trusted answer | Needs explicit curation | project_state, but only after review | +| Tool-origin engineering fact | Canonical source update first | repo / KB / PKM tool of origin | + +## What the pipeline deliberately prevents + +This V1 pipeline deliberately prevents these bad paths: + +- Discord -> project_state directly +- Discrawl archive -> project_state directly +- Discord -> registry mutation directly +- Discord -> refresh or ingest directly without explicit approval +- raw chat -> promote or reject directly +- OpenClaw turning evidence into truth without a review gate + +## Deferred from V1 + +Screenpipe is deferred from V1. It is not an active input lane in this pipeline and it is not a runtime dependency of this pipeline. If it is revisited later, it should be handled in a separate future design and not treated as an implicit part of this pipeline. + +## Bottom line + +The promotion pipeline is intentionally conservative. + +Its job is not to maximize writes. +Its job is to preserve trust while still letting Discord, Discrawl, OpenClaw, PKM, and repos contribute useful signal. + +That means the safe default path is: + +- capture broadly +- trust narrowly +- promote deliberately diff --git a/docs/openclaw-atocore-shared-client-consolidation-preview.md b/docs/openclaw-atocore-shared-client-consolidation-preview.md new file mode 100644 index 0000000..24f5f39 --- /dev/null +++ b/docs/openclaw-atocore-shared-client-consolidation-preview.md @@ -0,0 +1,96 @@ +# OpenClaw x AtoCore Shared-Client Consolidation Preview + +## Status + +Proposal only. Not applied. + +## Why this exists + +The current OpenClaw helper script duplicates AtoCore-calling logic that already exists in the shared operator client: + +- request handling +- fail-open behavior +- project detection +- project lifecycle command surface + +The preferred direction is to consolidate OpenClaw toward the shared operator client pattern documented in `docs/architecture/llm-client-integration.md`. + +## Goal + +Keep the OpenClaw skill and operator policy in OpenClaw, but stop maintaining a separate Bash implementation of the AtoCore client surface when the shared client already exists in `/home/papa/ATOCore/scripts/atocore_client.py`. + +## Non-goals for this preview + +- no implementation in this phase +- no runtime change in this phase +- no new helper command in this phase +- no change to approval policy in this preview + +## Preview diff + +This is a conceptual diff preview only. +It is not applied. + +```diff +--- a/skills/atocore-context/scripts/atocore.sh ++++ b/skills/atocore-context/scripts/atocore.sh +@@ +-#!/usr/bin/env bash +-set -euo pipefail +- +-BASE_URL="${ATOCORE_BASE_URL:-http://dalidou:8100}" +-TIMEOUT="${ATOCORE_TIMEOUT_SECONDS:-30}" +-REFRESH_TIMEOUT="${ATOCORE_REFRESH_TIMEOUT_SECONDS:-1800}" +-FAIL_OPEN="${ATOCORE_FAIL_OPEN:-true}" +- +-request() { +- # local curl-based request logic +-} +- +-detect_project() { +- # local project detection logic +-} +- +-case "$cmd" in +- health) request GET /health ;; +- projects) request GET /projects ;; +- auto-context) ... ;; +- register-project) ... ;; +- refresh-project) ... ;; +- ingest-sources) ... ;; +-esac ++#!/usr/bin/env bash ++set -euo pipefail ++ ++CLIENT="${ATOCORE_SHARED_CLIENT:-/home/papa/ATOCore/scripts/atocore_client.py}" ++ ++if [[ ! -f "$CLIENT" ]]; then ++ echo "Shared AtoCore client not found: $CLIENT" >&2 ++ exit 1 ++fi ++ ++exec python3 "$CLIENT" "$@" +``` + +## Recommended implementation shape later + +If and when this is implemented, the safer shape is: + +1. keep policy and approval guidance in OpenClaw instructions and skill text +2. delegate actual AtoCore client behavior to the shared operator client +3. avoid adding any new helper command unless explicitly approved +4. keep read-path and approved-operator-path distinctions in the OpenClaw guidance layer + +## Risk notes + +Potential follow-up concerns to handle before applying: + +- path dependency on `/home/papa/ATOCore/scripts/atocore_client.py` +- what should happen if the AtoCore repo is unavailable from the OpenClaw machine +- whether a thin compatibility wrapper is needed for help text or argument normalization +- ensuring OpenClaw policy still blocks unapproved Discord-originated mutations even if the shared client exposes them + +## Bottom line + +The duplication is real and consolidation is still the right direction. +But in this phase it remains a proposal only. diff --git a/docs/openclaw-atocore-v1-architecture.md b/docs/openclaw-atocore-v1-architecture.md new file mode 100644 index 0000000..c85d3bb --- /dev/null +++ b/docs/openclaw-atocore-v1-architecture.md @@ -0,0 +1,362 @@ +# OpenClaw x AtoCore V1 Architecture + +## Purpose + +This document defines the safe V1 operating model for how Discord, Discrawl, OpenClaw, PKM, repos, and AtoCore work together. + +The goal is to let these systems contribute useful signal into AtoCore without turning AtoCore into a raw dump and without blurring trust boundaries. + +## V1 scope + +V1 active inputs are: + +- Discord and Discrawl evidence +- OpenClaw interaction evidence +- PKM, repos, and KB sources +- read-only AtoCore context for comparison and deduplication + +## Core stance + +The V1 stance is simple: + +- Discord and Discrawl are evidence streams. +- OpenClaw is the operator and orchestrator. +- PKM, repos, and KB tools remain the canonical human and tool truth. +- AtoCore memories hold reviewed episodic, personal, and loose project signal. +- AtoCore project_state holds the current trusted project answer, manually or tightly gated only. +- Future AtoCore entities hold reviewed structured decisions, requirements, constraints, and related facts. + +## Architectural principles + +1. AtoCore remains additive and fail-open from the OpenClaw side. +2. Every fact type has exactly one canonical home. +3. Raw evidence is not trusted truth. +4. Unreviewed signals become evidence or candidates, not active truth. +5. Discord-originated paths never directly mutate project_state, registry state, refresh state, ingestion state, or review decisions without explicit human approval. +6. OpenClaw is not canonical storage. It retrieves, compares, summarizes, requests approval, and performs approved operator actions. +7. The shared operator client is the canonical mutating operator surface. Frontends should reuse it instead of reimplementing AtoCore-calling logic. + +## Explicit approval rule + +In this V1 policy, explicit approval means all of the following: + +- the human directly instructs the specific mutating action +- the instruction appears in the current thread or current session +- the approval is for that specific action, not vague intent +- the approval is not inferred from Discord evidence, Discrawl recall, screener output, or general discussion + +Examples of explicit approval: + +- "refresh p05 now" +- "register this project" +- "promote that candidate" +- "write this to project_state" + +Examples that are not explicit approval: + +- "we should probably refresh this sometime" +- "I think this is the current answer" +- archived discussion saying a mutation might be useful +- a screener report recommending a mutation + +## System roles + +### Discord + +Discord is a live conversational source. +It contains fresh context, discussion, uncertainty, and project language grounded in real work. +It is not authoritative by itself. + +Discord-originated material should be treated as: + +- raw evidence +- candidate material after screening +- possible justification for a later human-reviewed promotion into a canonical home + +Discord should never be treated as direct trusted project truth just because someone said it in chat. + +### Discrawl + +Discrawl is a retrieval and archive layer over Discord history. +It turns prior conversation into searchable evidence. +That is useful for recall, context building, and finding prior decisions or open questions. + +Discrawl is still evidence, not authority. +A retrieved Discord thread may show what people thought or said. It does not by itself become trusted project_state. + +### OpenClaw + +OpenClaw is the orchestrator and operator. +It is where the human interacts, where approvals happen, and where cross-source reasoning happens. + +OpenClaw's job is to: + +- retrieve +- compare +- summarize +- ask for approval when mutation is requested +- call the shared operator client for approved writes +- fail open when AtoCore is unavailable + +OpenClaw is not the canonical place where project facts live long-term. + +### PKM + +PKM is a canonical human-authored prose source. +It is where notes, thinking, and ongoing project writing live. + +PKM is the canonical home for: + +- project prose notes +- working notes +- long-form summaries +- journal-style project history + +PKM is not the place where OpenClaw should be taught how to operate AtoCore. Operator instructions belong in repo docs and OpenClaw instructions and skills. + +### Repos and KB tools + +Repos and KB tools are canonical human and tool truth for code and structured engineering artifacts. + +They are the canonical home for: + +- source code +- repo design docs +- structured tool outputs +- KB-CAD and KB-FEM facts where those systems are the tool of origin + +### AtoCore memories + +AtoCore memories are for reviewed, durable machine-usable signal that is still loose enough to belong in memory rather than in a stricter structured layer. + +Examples: + +- episodic facts +- preferences +- identity facts +- reviewed loose project facts + +AtoCore memories are not a place to dump raw Discord capture. + +### AtoCore project_state + +AtoCore project_state is the trusted current answer layer. +It is the place for questions like: + +- what is the current selected architecture? +- what is the current next focus? +- what is the trusted status answer right now? + +Because this layer answers current-truth questions, it must remain manually curated or tightly gated. + +### Future AtoCore entities + +Future entities are the canonical home for structured engineering facts that deserve stronger representation than freeform memory. + +Examples: + +- decisions +- requirements +- constraints +- validation claims +- structured relationships later + +These should be promoted from evidence or candidates only after review. + +## Logical flow + +```text +Discord live chat --. +Discrawl archive ----+--> evidence bundle / interactions / screener input +OpenClaw evidence ---' + | + v + nightly screener + | + .--------+--------. + v v + memory candidates entity candidates (later) + | | + '--------+--------' + v + human review in OpenClaw + | + .-----------------+-----------------. + v v v + active memory active entity explicit curation + | + v + project_state +``` + +The load-bearing rule is that review happens before trust. + +## Canonical-home table + +Every named fact type below has exactly one canonical home. + +| Fact type | Canonical home | Why | +|---|---|---| +| Raw Discord message | Discord / Discrawl archive | It is conversational evidence, not normalized truth | +| Archived Discord thread history | Discrawl archive | It is the retrieval form of Discord evidence | +| OpenClaw operator instructions | OpenClaw repo docs / skills / instructions | Operating behavior should live in code-adjacent instructions, not PKM | +| Project prose notes | PKM | Human-authored project prose belongs in PKM | +| Source code | Repo | Code truth lives in version control | +| Repo design or architecture doc | Repo | The documentation belongs with the code or system it describes | +| Structured KB-CAD / KB-FEM fact | KB tool of origin | Tool-managed structured engineering facts belong in their tool of origin | +| Personal identity fact | AtoCore memory (`identity`) | AtoCore memory is the durable machine-usable home | +| Preference fact | AtoCore memory (`preference`) | Same reason | +| Episodic fact | AtoCore memory (`episodic`) | It is durable recall, not project_state | +| Loose reviewed project signal | AtoCore memory (`project`) | Good fit for reviewed but not fully structured project signal | +| Engineering decision | Future AtoCore entity (`Decision`) | Decisions need structured lifecycle and supersession | +| Requirement | Future AtoCore entity (`Requirement`) | Requirements need structured management | +| Constraint | Future AtoCore entity (`Constraint`) | Constraints need structured management | +| Current trusted project answer | AtoCore `project_state` | This layer is explicitly for current trusted truth | +| Project registration metadata | AtoCore project registry | Registry state is its own canonical operator layer | +| Review action (promote / reject / invalidate) | AtoCore audit trail / operator action log | Review decisions are operator events, not source facts | + +## What this means for Discord-originated facts + +A Discord-originated signal can end in more than one place, but not directly. + +### If the signal is conversational, ambiguous, or historical + +It stays in the evidence lane: + +- Discord +- Discrawl archive +- optional screener artifact +- optional candidate queue + +It does not become trusted project_state. + +### If the signal is a stable personal or episodic fact + +It may be promoted to AtoCore memory after review. + +Examples: + +- "Antoine prefers concise operator summaries." +- "We decided in discussion to keep AtoCore additive." + +These belong in reviewed memory, not in project_state. + +### If the signal expresses a structured engineering fact + +It may become an entity candidate and later an active entity. + +Examples: + +- a requirement +- a decision +- a constraint + +Again, not directly from raw chat. The chat is evidence for the candidate. + +### If the signal is the current trusted answer + +It still should not jump directly from Discord into project_state. +Instead, a human should explicitly curate it into project_state after checking it against the right canonical home. + +That canonical home may be: + +- PKM for prose and project notes +- repo for code and design docs +- KB tools for structured engineering facts +- active entity if the engineering layer is the canonical home + +## Approval boundaries + +### Reads + +The following may be invoked automatically when useful: + +- `health` +- `projects` +- `detect-project` +- `auto-context` +- `query` +- `project-state` read +- Discrawl retrieval + +These are additive and fail-open. + +### Mutations requiring explicit human approval + +The following are operator actions, not conversational automation: + +- `register-project` +- `update-project` +- `refresh-project` +- `ingest-sources` +- `project-state-set` +- `project-state-invalidate` +- `capture` when used as a durable write outside conservative logging policy +- `extract` with persistence +- `promote` +- `reject` +- future entity promotion or rejection + +For Discord-originated paths, approval must satisfy the explicit approval rule above. + +## Shared operator client rule + +The preferred V1 architecture is: + +- AtoCore HTTP API as system interface +- shared operator client as reusable mutating surface +- OpenClaw as a thin frontend and operator around that client + +That avoids duplicating: + +- project detection logic +- request logic +- failure handling +- mutation surface behavior +- approval wrappers + +OpenClaw should keep its own high-level operating instructions, but it should not keep growing a parallel AtoCore mutation implementation. + +## V1 boundary summary + +### Allowed automatic behavior + +- read-only retrieval +- context build +- Discrawl recall +- evidence collection +- nightly screening into reviewable output +- fail-open fallback when AtoCore is unavailable + +### Allowed only after explicit human review or approval + +- candidate persistence from evidence +- candidate promotion or rejection +- project refresh or ingestion +- registry mutation +- trusted project_state writes + +### Not allowed as automatic behavior + +- direct Discord -> project_state writes +- direct Discord -> register / update / refresh / ingest / promote / reject +- hidden mutation inside the screener +- treating PKM as the main operator-instruction layer for AtoCore behavior + +## Deferred from V1 + +Screenpipe is deferred. +It is not an active input lane in V1 and it must not become a runtime, skill, or policy dependency in V1. +If it is revisited later, it must be treated as a separate future design decision, not as an implicit V1 extension. + +## Bottom line + +The safe V1 architecture is not "everything can write into AtoCore." +It is a layered system where: + +- evidence comes in broadly +- trust rises slowly +- canonical homes stay singular +- OpenClaw remains the operator +- AtoCore remains the additive machine-memory and trusted-state layer +- the shared operator client becomes the one reusable write-capable surface diff --git a/docs/openclaw-atocore-v1-proof-runbook.md b/docs/openclaw-atocore-v1-proof-runbook.md new file mode 100644 index 0000000..2158f16 --- /dev/null +++ b/docs/openclaw-atocore-v1-proof-runbook.md @@ -0,0 +1,207 @@ +# OpenClaw x AtoCore V1 Proof Runbook + +## Purpose + +This is the concise proof and operator runbook for the final V1 policy. +It shows, in concrete paths, that: + +- a Discord-originated signal cannot reach `project_state` without candidate or review gating +- Discord cannot directly execute `register-project`, `update-project`, `refresh-project`, `ingest-sources`, `promote`, or `reject` without explicit approval + +## Explicit approval definition + +For V1, explicit approval means: + +- the human directly instructs the specific mutating action +- the instruction is in the current thread or current session +- the approval is for that exact action +- the approval is not inferred from evidence, archives, or screener output + +Examples: + +- "refresh p05 now" +- "register this project" +- "promote that candidate" +- "write this to project_state" + +Non-examples: + +- "this looks like the current answer" +- "we should probably refresh this" +- an old Discord thread saying a refresh might help +- a screener report recommending a mutation + +## Proof 1 - Discord cannot directly reach project_state + +Blocked path: + +```text +Discord message + -> evidence + -> optional candidate + -> review + -> optional explicit curation + -> project_state +``` + +What is blocked: + +- Discord -> project_state directly +- Discrawl archive -> project_state directly +- screener output -> project_state directly + +What is allowed: + +1. Discord message enters the evidence lane. +2. It may become a memory or entity candidate after screening. +3. A human reviews the candidate. +4. If the fact is truly the current trusted answer, the human may explicitly curate it into `project_state`. + +Conclusion: + +`project_state` is reachable only after review and explicit curation. There is no direct Discord-originated write path. + +## Proof 2 - Discord cannot directly execute mutating operator actions + +Blocked direct actions: + +- `register-project` +- `update-project` +- `refresh-project` +- `ingest-sources` +- `promote` +- `reject` +- `project-state-set` +- `project-state-invalidate` + +Blocked path: + +```text +Discord message + -> evidence or operator request context + -X-> direct mutation +``` + +Allowed path: + +```text +Discord message + -> OpenClaw recognizes requested operator action + -> explicit approval check + -> approved operator action + -> shared operator client or helper call +``` + +Conclusion: + +Discord can request or justify a mutation, but it cannot perform it on its own. + +## Proof 3 - Discrawl does not create approval + +Discrawl is evidence retrieval. +It may surface: + +- prior discussions +- earlier decisions +- unresolved questions +- prior suggestions to mutate state + +It does not create approval for mutation. + +Blocked path: + +```text +Discrawl recall + -X-> refresh-project + -X-> promote + -X-> project_state write +``` + +Allowed path: + +```text +Discrawl recall + -> evidence for human review + -> explicit approval in current thread/session if mutation is desired + -> approved operator action +``` + +Conclusion: + +Archive recall informs review. It does not authorize writes. + +## Proof 4 - Screener has no hidden mutation lane + +The screener may: + +- gather evidence +- classify evidence +- prepare candidates +- prepare operator queues +- report contradictions or missing context + +The screener may not: + +- write `project_state` +- mutate registry state +- refresh or ingest directly +- promote or reject directly + +Blocked path: + +```text +screener output + -X-> hidden mutation +``` + +Allowed path: + +```text +screener output + -> review queue or operator queue + -> explicit approval if mutation is wanted + -> approved operator action +``` + +Conclusion: + +The screener is a filter, not a hidden writer. + +## Minimal operator decision table + +| Situation | Allowed next step | Blocked next step | +|---|---|---| +| Discord says "this is the current answer" | evidence, then review, then possible explicit curation | direct `project_state` write | +| Discord says "refresh p05" without direct instruction | ask for explicit approval | direct `refresh-project` | +| Discord says "refresh p05 now" | approved operator action may run | none, if approval is explicit | +| Discrawl finds an old thread asking for registration | use as review context only | direct `register-project` | +| Screener recommends promotion | ask for explicit review decision | direct `promote` | + +## Practical runbook + +### Case A - current-truth claim from Discord + +1. Treat the message as evidence. +2. Check the canonical home. +3. If needed, prepare a candidate or review note. +4. Do not write `project_state` unless the human explicitly approves that curation step. + +### Case B - requested refresh from Discord + +1. Determine whether the message is a direct instruction or only discussion. +2. If not explicit, ask for approval. +3. Only perform `refresh-project` after explicit approval in the current thread or session. + +### Case C - candidate promotion request + +1. Candidate exists or is proposed. +2. Review the evidence and the candidate text. +3. Only perform `promote` or `reject` after explicit review decision. + +## Bottom line + +The V1 rule is easy to test: + +If the path starts from Discord or Discrawl and ends in trusted or operator state, there must be a visible approval or review step in the middle. + +If that visible step is missing, the action is not allowed. diff --git a/docs/openclaw-atocore-write-policy-matrix.md b/docs/openclaw-atocore-write-policy-matrix.md new file mode 100644 index 0000000..478d5d2 --- /dev/null +++ b/docs/openclaw-atocore-write-policy-matrix.md @@ -0,0 +1,184 @@ +# OpenClaw x AtoCore V1 Write-Policy Matrix + +## Purpose + +This matrix defines what each source is allowed to write to each target in V1. + +Policy meanings: + +- `auto-write` = allowed automatically without a human approval gate +- `candidate-only` = may create reviewable candidate material, but not active truth +- `human-review` = allowed only after explicit human review or explicit human approval +- `never-auto-write` = never allowed as an automatic write path + +## Explicit approval rule + +In this matrix, `human-review` is concrete, not vague. +For Discord-originated or Discrawl-originated paths it means: + +- the human directly instructs the specific mutating action +- the instruction is in the current thread or current session +- the approval is for that specific action +- the approval is not inferred from evidence, archives, screener output, or general discussion + +Examples of explicit approval: + +- "refresh p05 now" +- "register this project" +- "promote this candidate" +- "write this to project_state" + +Non-examples: + +- "this looks important" +- "we should probably refresh this" +- archived discussion that once mentioned a similar mutation +- a screener note recommending promotion + +## V1 scope note + +V1 active inputs are: + +- Discord and Discrawl +- OpenClaw interaction evidence +- PKM, repos, and KB sources +- read-only AtoCore context for comparison and deduplication + +## Targets + +The targets below are the only ones that matter for this policy. + +- Evidence artifacts +- Memory candidates +- Active memories +- Entity candidates +- Active entities +- Trusted project_state +- Registry / refresh / ingest mutations +- Review actions + +## Matrix + +| Source | Target | Policy | Notes / gate | +|---|---|---|---| +| Discord live message | Evidence artifacts | auto-write | Safe evidence capture or archive only | +| Discord live message | Memory candidates | candidate-only | Only after screening or extraction; never direct active write | +| Discord live message | Active memories | human-review | Promote only after review of the candidate and evidence | +| Discord live message | Entity candidates | candidate-only | Only when structured signal is extracted from evidence | +| Discord live message | Active entities | human-review | Review required before promotion | +| Discord live message | Trusted project_state | human-review | Only via explicit curation; never directly from raw chat | +| Discord live message | Registry / refresh / ingest mutations | human-review | Requires explicit approval in the current thread or session | +| Discord live message | Review actions | human-review | Discord cannot silently promote or reject on its own | +| Discrawl archive result | Evidence artifacts | auto-write | Archive or search result is evidence by design | +| Discrawl archive result | Memory candidates | candidate-only | Extract reviewed signal from archived conversation | +| Discrawl archive result | Active memories | human-review | Promotion required | +| Discrawl archive result | Entity candidates | candidate-only | Archived discussion may justify candidate creation | +| Discrawl archive result | Active entities | human-review | Promotion required | +| Discrawl archive result | Trusted project_state | human-review | Must be explicitly curated; never inferred directly from archive | +| Discrawl archive result | Registry / refresh / ingest mutations | human-review | Archive recall cannot directly mutate operator state | +| Discrawl archive result | Review actions | human-review | Archive evidence informs review; it does not perform review | +| OpenClaw read/query flow | Evidence artifacts | auto-write | Conservative interaction or evidence logging is acceptable | +| OpenClaw read/query flow | Memory candidates | candidate-only | Only through explicit extraction path | +| OpenClaw read/query flow | Active memories | human-review | Requires operator review | +| OpenClaw read/query flow | Entity candidates | candidate-only | Future extraction path | +| OpenClaw read/query flow | Active entities | human-review | Requires operator review | +| OpenClaw read/query flow | Trusted project_state | never-auto-write | Read/query flow must stay additive | +| OpenClaw read/query flow | Registry / refresh / ingest mutations | never-auto-write | Read/query automation must not mutate operator state | +| OpenClaw read/query flow | Review actions | never-auto-write | Read automation cannot silently promote or reject | +| OpenClaw approved operator action | Evidence artifacts | auto-write | May create operator or audit artifacts | +| OpenClaw approved operator action | Memory candidates | human-review | Candidate persistence is itself an approved operator action | +| OpenClaw approved operator action | Active memories | human-review | Promotion allowed only through reviewed operator action | +| OpenClaw approved operator action | Entity candidates | human-review | Same rule for future entities | +| OpenClaw approved operator action | Active entities | human-review | Promotion allowed only through reviewed operator action | +| OpenClaw approved operator action | Trusted project_state | human-review | Allowed only as explicit curation | +| OpenClaw approved operator action | Registry / refresh / ingest mutations | human-review | Explicit approval required | +| OpenClaw approved operator action | Review actions | human-review | Explicit review required | +| PKM note | Evidence artifacts | human-review | Snapshotting into evidence is optional, not the primary path | +| PKM note | Memory candidates | candidate-only | Extraction from PKM is allowed into the candidate lane | +| PKM note | Active memories | human-review | Promotion required | +| PKM note | Entity candidates | candidate-only | Extract structured signal into the candidate lane | +| PKM note | Active entities | human-review | Promotion required | +| PKM note | Trusted project_state | human-review | Only via explicit curation of current truth | +| PKM note | Registry / refresh / ingest mutations | human-review | A human may choose to refresh based on PKM changes | +| PKM note | Review actions | human-review | PKM may support the decision, but not execute it automatically | +| Repo / KB source | Evidence artifacts | human-review | Optional audit or screener snapshot only | +| Repo / KB source | Memory candidates | candidate-only | Extract loose durable signal if useful | +| Repo / KB source | Active memories | human-review | Promotion required | +| Repo / KB source | Entity candidates | candidate-only | Strong future path for structured facts | +| Repo / KB source | Active entities | human-review | Promotion required | +| Repo / KB source | Trusted project_state | human-review | Explicit curation only | +| Repo / KB source | Registry / refresh / ingest mutations | human-review | A human may refresh or ingest based on source changes | +| Repo / KB source | Review actions | human-review | Source can justify review; it does not perform review | +| AtoCore active memory | Evidence artifacts | never-auto-write | Active memory is already above the evidence layer | +| AtoCore active memory | Memory candidates | never-auto-write | Do not recursively re-candidate active memory | +| AtoCore active memory | Active memories | never-auto-write | Already active | +| AtoCore active memory | Entity candidates | human-review | Graduation proposal only with review | +| AtoCore active memory | Active entities | human-review | Requires graduation plus promotion | +| AtoCore active memory | Trusted project_state | human-review | A human may explicitly curate current truth from memory | +| AtoCore active memory | Registry / refresh / ingest mutations | never-auto-write | Memory must not mutate registry or ingestion state | +| AtoCore active memory | Review actions | human-review | Human reviewer decides | +| AtoCore active entity | Evidence artifacts | never-auto-write | Already above the evidence layer | +| AtoCore active entity | Memory candidates | never-auto-write | Do not backflow structured truth into memory candidates automatically | +| AtoCore active entity | Active memories | never-auto-write | Canonical home is the entity, not a new memory | +| AtoCore active entity | Entity candidates | never-auto-write | Already active | +| AtoCore active entity | Active entities | never-auto-write | Already active | +| AtoCore active entity | Trusted project_state | human-review | Explicit curation may publish the current trusted answer | +| AtoCore active entity | Registry / refresh / ingest mutations | never-auto-write | Entities do not operate the registry | +| AtoCore active entity | Review actions | human-review | Human reviewer decides | + +## Discord-originated trace examples + +### Example 1 - conversational decision in Discord + +Allowed path: + +1. Discord live message -> Evidence artifacts (`auto-write`) +2. Evidence artifacts -> Memory candidates or Entity candidates (`candidate-only`) +3. Candidate -> Active memory or Active entity (`human-review`) +4. If it becomes the current trusted answer, a human may explicitly curate it into Trusted project_state (`human-review`) + +There is no direct Discord -> project_state automatic path. + +### Example 2 - archived Discord thread via Discrawl + +Allowed path: + +1. Discrawl result -> Evidence artifacts (`auto-write`) +2. Discrawl result -> Memory candidates or Entity candidates (`candidate-only`) +3. Human review decides promotion +4. Optional explicit curation into project_state later + +Again, there is no direct archive -> trusted truth path. + +### Example 3 - Discord request to refresh a project + +Allowed path: + +1. Discord message is evidence of requested operator intent +2. No mutation happens automatically +3. OpenClaw requires explicit approval in the current thread or session for `refresh-project` +4. Only then may OpenClaw perform the approved operator action + +There is no direct Discord -> refresh path without explicit approval. + +## V1 interpretation rules + +1. Evidence can flow in broadly. +2. Truth can only rise through review. +3. project_state is the narrowest lane. +4. Registry and ingestion operations are operator actions, not evidence effects. +5. Discord-originated paths can inform operator actions, but they cannot silently execute them. +6. Deferred sources that are out of V1 scope have no automatic or manual role in this V1 matrix. + +## Deferred from V1 + +Screenpipe is deferred and intentionally omitted from this V1 matrix. + +## Bottom line + +If a source is noisy, conversational, or archived, its maximum automatic privilege in V1 is: + +- evidence capture, or +- candidate creation + +Everything above that requires explicit human review or explicit human approval.