Add OpenClaw x AtoCore V1 governance docs

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