Add rebased OpenClaw x AtoCore V1 review docs
This commit is contained in:
184
docs/openclaw-atocore-write-policy-matrix.md
Normal file
184
docs/openclaw-atocore-write-policy-matrix.md
Normal file
@@ -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.
|
||||
Reference in New Issue
Block a user