ATOCore/docs/openclaw-atocore-promotion-pipeline.md

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

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