Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
6 changes: 6 additions & 0 deletions docs/design/openclaw-ethos-preprompt-recall.md
Original file line number Diff line number Diff line change
Expand Up @@ -334,6 +334,7 @@ following shape at the bridge boundary:
```

Rules:

- preserve provenance back to the ledger event id
- keep the episode concise and semantic
- do not dump full task objects or raw debug metadata into Ethos
Expand All @@ -355,6 +356,7 @@ Durable facts should carry explicit freshness/authority semantics:
```

Retrieval policy should prefer:

1. `active`
2. `disputed` (visible but clearly marked)
3. `superseded`
Expand Down Expand Up @@ -385,12 +387,14 @@ structured recall trace record that the UI can display safely:
```

Rules:

- operator-visible, not model-visible
- enough detail for debugging
- no raw prompt dump theater
- no raw Ethos metadata leakage into Mission Control cards

Finalized runtime contract in OpenClaw:

- emit these records through the existing task-ledger/event substrate
- use `entity: "recall"` + `kind: "trace"` rather than inventing a separate sink
- keep Mission Control consumption on ledger snapshot/event reads, not prompt scraping
Expand Down Expand Up @@ -468,6 +472,7 @@ turning the UI into a prompt dump or leaking raw Ethos metadata.
### Likely files to touch

#### OpenClaw source

- `src/hooks/bundled/ethos-context/handler.ts`
- emit structured recall trace records/events
- `src/hooks/bundled/ethos-context/handler.test.ts`
Expand All @@ -480,6 +485,7 @@ turning the UI into a prompt dump or leaking raw Ethos metadata.
of a dedicated trace channel

#### Mission Control

- gateway task-ledger sync surfaces
- `src/gateway/server-methods/tasks.ts`
- extend `tasks.snapshot` / `tasks.events` consumers if Mission Control needs
Expand Down
58 changes: 58 additions & 0 deletions docs/design/task-ledger-mission-control-automation-roadmap.md
Original file line number Diff line number Diff line change
Expand Up @@ -5,6 +5,7 @@
Turn the task-ledger/task-bus stack into a more automatic, trustworthy operational spine for OpenClaw, while documenting the portable pieces we want to carry into Mercury.

This roadmap is based on real operator pain observed during Story 4 / Story 5 work:

- task truth lagging behind agent reality
- Mission Control accurately reflecting stale ledger state
- old blocked tasks dominating current agent status
Expand All @@ -16,6 +17,7 @@ This roadmap is based on real operator pain observed during Story 4 / Story 5 wo
Make the **ledger more authoritative** and Mission Control more of a **live projection** over that authority.

That means:

- agents should publish lifecycle changes more automatically
- heartbeats should carry stronger current-task context
- Mission Control should project the ledger honestly, with freshness/confidence cues
Expand All @@ -27,6 +29,7 @@ Today the biggest issue is not that Mission Control is "just wrong."
The bigger issue is that the upstream task-ledger/task-bus flow is only partially automated.

That creates a recurring failure mode:

1. agent starts real work
2. task state stays `todo` or old blocked work remains attached
3. Mission Control projects the ledger faithfully
Expand All @@ -41,18 +44,23 @@ So the roadmap focus should be upstream automation first, then projection qualit
## P0.1 Automatic task lifecycle publishing from agent execution

### Goal

Stop depending on humans to manually reconcile the most common task transitions.

### Required behavior

When an agent enters a real scoped implementation lane, the runtime should be able to publish:

- `todo -> in_progress`
- `in_progress -> blocked` with reason
- `in_progress -> qa`
- `qa -> done`
- task notes with verification context

### Suggested shape

Introduce a thin standard command surface around the ledger publisher:

- `task.start(...)`
- `task.block(...)`
- `task.note(...)`
Expand All @@ -62,20 +70,25 @@ Introduce a thin standard command surface around the ledger publisher:
These should route through the canonical ledger write path, not bypass it.

### Why this matters

This removes the biggest source of Mission Control drift: real work starts, but the canonical task state never changes.

### Mercury portability

Portable almost as-is. Mercury should also have a small task command API around its canonical publisher.

---

## P0.2 Explicit current-task contract in agent heartbeats

### Goal

Make agent activity reliably attributable to current work.

### Required heartbeat fields

Every meaningful agent heartbeat should carry:

- `agentId`
- `status`
- `currentTaskId`
Expand All @@ -87,47 +100,64 @@ Every meaningful agent heartbeat should carry:
- `phase` / run metadata where relevant

### Why this matters

Mission Control should not have to guess which task an agent is carrying from a mix of old assignments and latest activity.

### Mercury portability

Portable conceptually. Names can differ, but the same contract should exist.

---

## P0.3 Controlled task-reality reconciliation

### Goal

Catch and repair obvious truth drift between session reality and ledger reality.

### Example drift cases

- agent has an active run, but assigned task is still `todo`
- task is `in_progress`, but assigned agent has been idle for hours
- agent has old blocked tasks plus one newer active task
- worktree/branch exists for a task, but no `in_progress` transition was published
- agent heartbeat `currentTaskId` disagrees with latest task assignment reality

### Required behavior

Create a reconciliation layer that can:

- detect drift
- emit warnings
- suggest safe fixes
- optionally apply deterministic safe reconciliations

Escalation and reassignment rules should stay ledger-native:

- activation misses should have explicit thresholds, not vague "follow up later" residue
- repeated proof-checkpoint misses / status loops should escalate on a fixed threshold and become reassignment-eligible on a later threshold
- stale or superseded ownership should define a ledger takeover path: publish the ownership change in the task ledger first, then let the gaining owner heartbeat the task
- Mission Control actions should remain a control surface over those ledger writes, never a second truth store

### Important rule

Do not hide this inside silent UI reads.
Reconciliation should be an explicit operational behavior with explainable output.

### Mercury portability

Portable and desirable. This is one of the strongest candidates to carry into Mercury early.

---

## P0.4 Mission Control freshness + confidence cues

### Goal

Make the operator surface honest about projection quality.

### UI should show

- snapshot age
- last ledger event age
- per-panel freshness
Expand All @@ -138,9 +168,11 @@ Make the operator surface honest about projection quality.
- whether projection looks stale or reconciled

### Why this matters

If the dashboard may lag, the UI should say so clearly instead of implying unwarranted certainty.

### Mercury portability

Portable. Any operator dashboard benefits from explicit projection-confidence cues.

---
Expand All @@ -150,9 +182,11 @@ Portable. Any operator dashboard benefits from explicit projection-confidence cu
## P1.1 First-class task relations

### Goal

Let the ledger express structure instead of treating tasks as isolated cards.

### Fields to add or normalize

- `parentTaskId`
- `dependsOn`
- `blockedBy`
Expand All @@ -161,40 +195,48 @@ Let the ledger express structure instead of treating tasks as isolated cards.
- `workstream`

### Why this matters

This makes rollups, blockers, and stale superseded work far easier to reason about.
It also reduces the chance that old blocked tasks visually dominate newer active work.

### Mercury portability

Strongly portable.

---

## P1.2 Better lifecycle metadata for task participation

### Goal

Improve rollups and automation by distinguishing active from non-participating children.

### Important lifecycle modes

- `parked`
- `superseded`
- `cancelled`
- `abandoned`
- `blocked`

### Why this matters

Parent rollups and current-task logic become much safer when non-participating work is clearly marked.

### Mercury portability

Portable and important.

---

## P1.3 Operator-side reconcile actions in Mission Control

### Goal

Let the operator fix obvious state mismatches from the dashboard without inventing dashboard-owned truth.

### Good candidate actions

- mark started
- mark blocked/unblocked
- add note
Expand All @@ -204,9 +246,11 @@ Let the operator fix obvious state mismatches from the dashboard without inventi
- open active lane/session/worktree

### Rule

Mission Control remains a control surface over the ledger, not an independent truth store.

### Mercury portability

Portable, but should come after publisher discipline and reconciliation rules exist.

---
Expand All @@ -216,9 +260,11 @@ Portable, but should come after publisher discipline and reconciliation rules ex
## P2.1 Nightly operational hygiene

### Goal

Use a scheduled maintenance pass to improve both memory quality and operational truth hygiene.

### Candidate checks

- stale `in_progress` tasks
- orphaned blocked tasks
- inactive agent/task mismatches
Expand All @@ -227,33 +273,39 @@ Use a scheduled maintenance pass to improve both memory quality and operational
- memory dedupe / summary regeneration / provenance-preserving compaction

### Why this matters

Nightly maintenance should operate over the real episode/fact/task substrate instead of placeholder schemas.

### Mercury portability

Portable in principle; exact maintenance jobs may differ.

---

## P2.2 Smarter rollup and stuck-lane handling

### Goal

Reduce human cleanup for long-running projects.

### Candidate automation

- parent task rollup suggestions
- stuck-lane detection
- no-heartbeat-with-open-task warnings
- blocked-too-long escalation
- QA aging detection

### Mercury portability

Portable, but only after base lifecycle correctness is in place.

---

# Recommended implementation order

## OpenClaw / Mission Control

1. **Automatic lifecycle publishing**
2. **Heartbeat current-task contract hardening**
3. **Drift detection + reconciliation warnings**
Expand All @@ -263,6 +315,7 @@ Portable, but only after base lifecycle correctness is in place.
7. **Nightly operational hygiene expansion**

## Mercury carryover order

1. canonical event log + snapshot
2. task command publisher API
3. explicit agent heartbeat contract
Expand All @@ -277,23 +330,27 @@ Portable, but only after base lifecycle correctness is in place.
# Suggested acceptance criteria by layer

## Ledger / publisher layer

- agents can publish start/block/qa/done through a stable API
- duplicate publishes remain idempotent
- canonical snapshot updates deterministically
- provenance is preserved for every meaningful transition

## Agent activity layer

- heartbeats include `currentTaskId`, lane, session, worktree, branch
- latest active work is distinguishable from older blocked assignments
- agent status no longer depends on ambiguous fallback inference alone

## Mission Control layer

- board reflects canonical task state without manual reconciliation drift
- agent lanes show current task truth and freshness/confidence
- activity feed remains historical, not mistaken for current truth
- reconcile warnings surface when source/projection drift is detected

## Operator workflow layer

- operator can correct safe state mismatches without editing raw data
- all control actions publish back through the ledger
- UI never becomes the canonical source of truth
Expand All @@ -320,6 +377,7 @@ If Mercury adopts those principles early, it avoids a huge class of “board say
# Bottom line

To make the task-ledger/task-bus/Mission Control stack better and more automated:

- automate more lifecycle truth at the source
- enrich heartbeats with explicit current-work context
- add controlled reconciliation instead of silent guessing
Expand Down
Loading
Loading