ace-overseer 0.23.0 → 0.25.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (58) hide show
  1. checksums.yaml +4 -4
  2. data/.ace-defaults/overseer/config.yml +9 -0
  3. data/CHANGELOG.md +24 -804
  4. data/README.md +60 -42
  5. data/docs/getting-started.md +9 -4
  6. data/docs/handbook.md +1 -18
  7. data/docs/usage.md +297 -209
  8. data/handbook/workflow-instructions/overseer/queue.wf.md +210 -0
  9. data/handbook/workflow-instructions/overseer.wf.md +17 -32
  10. data/lib/ace/overseer/atoms/dependency_readiness.rb +48 -0
  11. data/lib/ace/overseer/atoms/handoff_readiness.rb +75 -0
  12. data/lib/ace/overseer/atoms/report_interpretation.rb +236 -0
  13. data/lib/ace/overseer/atoms/status_formatter.rb +0 -1
  14. data/lib/ace/overseer/cli/commands/handoff.rb +69 -0
  15. data/lib/ace/overseer/cli/commands/process_reports.rb +50 -0
  16. data/lib/ace/overseer/cli/commands/prune.rb +3 -50
  17. data/lib/ace/overseer/cli/commands/status.rb +8 -55
  18. data/lib/ace/overseer/cli/commands/work_on.rb +6 -50
  19. data/lib/ace/overseer/cli.rb +10 -14
  20. data/lib/ace/overseer/models/assignment_prune_candidate.rb +5 -5
  21. data/lib/ace/overseer/models/prune_candidate.rb +5 -5
  22. data/lib/ace/overseer/molecules/assignment_prune_safety_checker.rb +22 -84
  23. data/lib/ace/overseer/molecules/git_preservation_checker.rb +33 -21
  24. data/lib/ace/overseer/molecules/handoff_probe.rb +101 -0
  25. data/lib/ace/overseer/molecules/hitl_inbox.rb +43 -0
  26. data/lib/ace/overseer/molecules/prune_safety_checker.rb +43 -88
  27. data/lib/ace/overseer/molecules/worktree_context_collector.rb +4 -18
  28. data/lib/ace/overseer/organisms/handoff_orchestrator.rb +122 -0
  29. data/lib/ace/overseer/organisms/prune_orchestrator.rb +2 -2
  30. data/lib/ace/overseer/organisms/report_processor.rb +241 -0
  31. data/lib/ace/overseer/organisms/status_attention.rb +306 -0
  32. data/lib/ace/overseer/organisms/status_collector.rb +267 -3
  33. data/lib/ace/overseer/organisms/status_sources.rb +276 -0
  34. data/lib/ace/overseer/organisms/work_on_orchestrator.rb +49 -9
  35. data/lib/ace/overseer/version.rb +1 -1
  36. data/lib/ace/overseer.rb +12 -1
  37. metadata +46 -27
  38. data/handbook/skills/as-overseer-configure-project/SKILL.md +0 -32
  39. data/handbook/workflow-instructions/overseer/configure-project.wf.md +0 -238
  40. data/handbook/workflow-instructions/overseer/maintain-continuation.wf.md +0 -115
  41. data/handbook/workflow-instructions/roles/lab-coordinator.wf.md +0 -106
  42. data/handbook/workflow-instructions/roles/project-overseer.wf.md +0 -182
  43. data/handbook/workflow-instructions/roles/second-commander.wf.md +0 -95
  44. data/lib/ace/overseer/cli/commands/ordinary.rb +0 -37
  45. data/lib/ace/overseer/cli/commands/prompt.rb +0 -63
  46. data/lib/ace/overseer/cli/commands/review.rb +0 -44
  47. data/lib/ace/overseer/cli/commands/stop.rb +0 -33
  48. data/lib/ace/overseer/molecules/launch_request.rb +0 -216
  49. data/lib/ace/overseer/molecules/original_launch_child.rb +0 -165
  50. data/lib/ace/overseer/molecules/proposal_tick.rb +0 -56
  51. data/lib/ace/overseer/molecules/protected_selection.rb +0 -46
  52. data/lib/ace/overseer/organisms/launch_recovery.rb +0 -65
  53. data/lib/ace/overseer/organisms/ordinary_work_on.rb +0 -186
  54. data/lib/ace/overseer/organisms/protected_prune.rb +0 -116
  55. data/lib/ace/overseer/organisms/protected_review.rb +0 -167
  56. data/lib/ace/overseer/organisms/protected_status.rb +0 -157
  57. data/lib/ace/overseer/organisms/protected_steering.rb +0 -78
  58. data/lib/ace/overseer/organisms/protected_work_on.rb +0 -102
data/docs/usage.md CHANGED
@@ -1,262 +1,350 @@
1
1
  ---
2
2
  doc-type: user
3
3
  title: ace-overseer Usage
4
- purpose: Full CLI reference for ace-overseer commands and options.
4
+ purpose: CLI reference for local overseer worktrees, assignments, and cleanup.
5
5
  ace-docs:
6
- last-updated: 2026-08-30
7
- last-checked: 2026-08-30
6
+ last-updated: 2026-10-17
7
+ last-checked: 2026-10-17
8
8
  ---
9
9
 
10
10
  # Usage
11
11
 
12
- ## Command Surface
13
-
14
- - `ace-overseer work-on`
15
- - `ace-overseer ordinary`
16
- - `ace-overseer status`
17
- - `ace-overseer prune`
18
- - `ace-overseer projects`
19
- - `ace-overseer agents`
20
- - `ace-overseer prompt`
21
- - `ace-overseer review`
22
- - `ace-overseer stop`
12
+ > **State owner:** `.ace-tasks/_overseer/` (private, gitignored task folder
13
+ > reached via `ace-task --in _overseer`) and `.ace-wt/` (one worktree per
14
+ > project task). Assignment plans live in `.ace-local/assign/` and are not
15
+ > copied here. See [docs/lab-flow.md](../../docs/lab-flow.md).
23
16
 
24
- ## `ace-overseer work-on`
17
+ ## Command Surface
25
18
 
26
- Without `--project`, create/reuse local worktrees and prepare assignments.
27
- With `--project`, prepare exactly one reviewed leaf and retain its original
28
- foreground protected launcher; no local fallback occurs on protected refusal.
29
-
30
- - `--task`, `-t`: local repeatable/comma-separated task refs; protected mode requires one leaf.
31
- - `--preset`, `-p`: local assignment preset; forbidden in protected mode.
32
- - `--runtime`: terminal backend `auto`, `tmux` or `herdr`; overrides existing config. Protected tmux refuses before allocation.
33
- - `--project`: explicit protected project ID.
34
- - `--agent`: exact visible protected mapping ID, requiring project. Automatic selection is ordered and advances only after attributable readonly preflight denial.
35
- - `--mutation`: stable invocation ID; otherwise generated once and printed before effects.
36
- - `--base-head`: optional explicit reviewed code HEAD; must match the captured source HEAD, which is rechecked after preparation and before fork.
37
- - `--dependency-report`: repeatable `task:assignment:step` identities for selected dependency reports; omission is an explicit empty selection.
38
- - `--recover-request FILE`: readonly original canonical attribution from retained inputs; rejects all launch/mode overrides.
39
- - `--quiet`, `-q`: suppress nonessential output; retained input identity and original child observation remain visible.
40
- - `--debug`, `-d`, `--help`, `-h`: diagnostics/help.
41
-
42
- Fresh protected start exclusively publishes private request JSON, derived exact
43
- definition sidecar and original prepared Git bundle, then prints their paths and
44
- hashes before any child. Missing/corrupt input or changed code HEAD refuses.
45
- The living coordinator retains and observes the same original child through
46
- readiness/uncertainty without a lifetime timeout, replacement or cancellation.
47
- The fixed launch driver uses one 30-second phase budget; each protocol call
48
- receives only the remaining time. The parent separately retains its earlier
49
- 30-second total readiness deadline, including CLI input reads and canonical
50
- ready verification; neither deadline refreshes. Late readiness preserves the
51
- same original child as uncertain, without a retry or replacement.
52
-
53
- Use independent status/steering while it remains foreground. Reap is local
54
- observation, never canonical terminal/release or physical cleanup permission.
55
- Recovery reports absent/mismatched local inputs separately from original canonical
56
- reservation attribution, without upload, reconstruction or retry.
57
-
58
- ## `ace-overseer ordinary`
59
-
60
- Ordinary execution is explicit and uses the root-selected project's Assign owner.
61
- `work-on --project` keeps its protected contract and never falls back here.
62
- The native supervisor prepares each reviewed leaf in its own existing worktree
63
- and prepared pane, registers exact captured inputs, then launches its explicit
64
- provider profile:
65
-
66
- ```sh
67
- ace-overseer ordinary --operation prepare --project atlas --task 8wr.t.abc --checkout /lab/projects/atlas \
68
- --provider pi:zai/glm-5.3-flash:high --output /private/ordinary/task-one
69
- ace-overseer ordinary --operation launch --project atlas --context /private/ordinary/task-one/context.json
70
- ace-overseer ordinary --operation resume --project atlas --context /private/ordinary/task-one/context.json
71
- ```
19
+ Local work uses five primary commands (`projects` lists configured lab projects):
72
20
 
73
- Preparation validates the explicit checkout against the installed Git common directory, then uses WorktreeProvisioner, WindowOpener and PreparedWorkBuilder. Project configuration resolves inside the selected checkout/worktree even when the native supervisor runs from another project. The
74
- provider/model/thinking selection must resolve through the existing LLM builder.
75
- It retains exact IDs, HEAD, scope and worker pane before registration. If the
76
- registration reply is lost, inspect canonical status through that original
77
- context; if registration is absent, replay the original `prepared/request.json`
78
- with `ace-lab assignment request`. Do not create another preparation to bypass
79
- uncertainty. Partial preparation errors preserve their files for inspection.
80
-
81
- Launch verifies the actual current native supervisor against canonical ownership,
82
- retains a dispatch intent before native send and sends the worker's ordinary
83
- `/as-assign-drive` entry. Acknowledgement means accepted send, not process start.
84
- The worker must register its own actual start through the installed owner.
85
- An existing dispatch intent plus no start stays `dispatch_uncertain`; neither
86
- launch nor resume sends a second command. `status` and `resume` are read-only
87
- observations of the original assignment/attempt and current supervisor selection.
88
-
89
- The returned native `/watch add` command watches a result hint file. Install it
90
- once in the supervisor session, persist through a harmless turn, then resume the
91
- exact session without replaying add commands or restoring intentional removals.
92
- A watch is only a wake hint; canonical `ace-lab assignment drive --operation status`
93
- and `adopt` decide outcome. Existing progress-audit duties also reconcile lost
94
- hints. A replaced coordinator first performs explicit canonical supervisor
95
- adoption as documented in Lab usage; worker identities and requests survive it.
96
-
97
- For two workers, repeat prepare with two reviewed leaf tasks and separate output
98
- directories. Verify two distinct panes/attempts, two canonical starts and results,
99
- and sequential reviewed ordinary merges. This source interface does not claim
100
- installed watches, real provider turns, review, release or merge acceptance.
21
+ - `ace-overseer work-on` - prepare a worktree, assignment, and terminal.
22
+ - `ace-overseer handoff` - hand the task worktree to the next role in the prepared sequence.
23
+ - `ace-overseer process-reports` - interpret ace-hitl reports and continue the queue.
24
+ - `ace-overseer status` - show active task worktrees and assignment progress.
25
+ - `ace-overseer prune` - remove completed task worktrees safely.
101
26
 
102
- ## `ace-overseer status`
27
+ `--project`/`--agent` protected execution and the installed `ordinary`
28
+ launcher are removed in L1 and are not normal paths. Status and prune read
29
+ local assignment/task/worktree/Git state only; there is no journal, attempt or
30
+ authority execution model. tmux and Herdr are transports, never state owners.
103
31
 
104
- Show status for active task worktrees.
105
-
106
- Invocation: `ace-overseer status [--format table|json] [--watch]`.
32
+ ## `ace-overseer work-on`
107
33
 
108
- Options:
34
+ Create or reuse local worktrees and prepare one assignment.
109
35
 
110
- - `--format`: output format (`table`, `json`)
111
- - `--watch`, `-w`: auto-refresh dashboard
112
- - `--runtime`: local backend selection; protected inventory is runtime-independent
113
- - `--project`: select protected canonical assignment inventory for this explicit project
114
- - `--quiet`, `-q`: suppress non-essential output
115
- - `--debug`, `-d`: show debug output
116
- - `--help`, `-h`: show help
36
+ | Option | Purpose |
37
+ |--------|---------|
38
+ | `--task`, `-t` | Task ref(s); repeatable and comma-separated |
39
+ | `--preset`, `-p` | Assignment preset name (default `work-on-task`) |
40
+ | `--runtime` | Terminal backend: `auto`, `tmux` or `herdr` |
41
+ | `--quiet`, `-q` | Suppress non-essential output |
42
+ | `--debug`, `-d` | Show debug output |
117
43
 
118
- ## `ace-overseer prune`
44
+ ```bash
45
+ ace-overseer work-on --task 8q4
46
+ ace-overseer work-on --task t.123,t.124 --preset work-on-task --runtime herdr
47
+ ```
119
48
 
120
- Remove stale or completed task worktrees.
49
+ Work-on is idempotent: rerunning with the same task refs reuses the existing
50
+ worktree and assignment instead of creating duplicates. Draft tasks are
51
+ blocked until reviewed.
52
+
53
+ Work-on only starts steps whose recorded `dependencies` are satisfied by real
54
+ task-tree state: every predecessor must have status `done` (accepted *and*
55
+ integrated result). A finished worker, "work done" message, or open PR does
56
+ not unlock a dependent step -- model merge requirements by depending on the
57
+ predecessor's integration step. Cancelled, skipped, missing, or cyclic
58
+ predecessors block the start with explicit reasons, before any worktree or
59
+ assignment side effect. For a manager task with active subtasks, BOTH the
60
+ manager's own `dependencies` and each active subtask's `dependencies` are
61
+ gated. Two intentional edges: re-attaching to an already-started step whose
62
+ dependencies are (now) unsatisfied is refused like any other start -- open
63
+ the existing window directly instead of `work-on`; and the gate is strictly
64
+ `done`, whereas `ace-task list --sort smart` also treats an archived
65
+ predecessor as satisfied -- with normal auto-archive the two agree, but on
66
+ archived-non-terminal dirty data `list` may say ready while `work-on`
67
+ blocks (work-on is the authority for starting).
68
+
69
+ > Planner preparation of a worktree and a whole role-sequence (one
70
+ > assignment and start config per role) is delivered by `ace-coworker
71
+ > prepare`; `ace-overseer handoff` walks that sequence leg by leg.
72
+
73
+ ## `ace-overseer handoff`
74
+
75
+ Hand the SAME task worktree to the next role in the prepared role sequence
76
+ (L6.4). The gate reads only real state: the worktree's role-sequence
77
+ assignments (ace-assign files, in composition order), their current states,
78
+ the per-leg start configs (`ace-coworker prepare`), and the worktree's
79
+ executor truth via the coworker active-executor rule. Nothing is re-prepared;
80
+ the next role starts from the existing start config.
81
+
82
+ | Option | Purpose |
83
+ |--------|---------|
84
+ | `--task`, `-t` | Task ref whose worktree receives the next role |
85
+ | `--runtime` | Terminal backend: `auto`, `tmux` or `herdr` |
86
+ | `--dry-run` | Check handoff readiness without opening a window |
87
+ | `--quiet`, `-q` | Suppress non-essential output |
88
+ | `--debug`, `-d` | Show debug output |
121
89
 
122
- Invocation: `ace-overseer prune [TARGETS] [OPTIONS]`.
90
+ ```bash
91
+ ace-overseer handoff --task 8q4 # worker finished -> reviewer
92
+ ace-overseer handoff --task 8q4 --dry-run # check only
93
+ ```
123
94
 
124
- Arguments:
95
+ Rules enforced mechanically: the handoff is ready only when every earlier leg
96
+ reached ace-assign state `completed` (a failed, in-flight, stalled, paused
97
+ predecessor, or an unknown/unreadable state refuses with reasons); no executor
98
+ may hold the worktree (commissioned, in-flight, or unparseable config all
99
+ block -- a busy worktree never gets a second executor and unknown state is
100
+ never a free resource); the next leg must have its existing start config. On
101
+ success a terminal window opens in the worktree and the exact start command
102
+ is printed (`ace-coworker start --config .ace-local/coworker/prepare/<role>.yml`).
103
+ When every leg is completed the command reports the sequence complete and
104
+ opens nothing. Handoff never creates a worktree; two different tasks hand off
105
+ independently in their own worktrees.
106
+
107
+ ## `ace-overseer process-reports`
108
+
109
+ Process incoming ace-hitl reports/questions and continue the overseer queue
110
+ (L6.5). Every event is matched against the private `_overseer` tree, the
111
+ outcome is recorded through the existing `ace-task update` surface, and the
112
+ queue continues by reusing the existing gates — no new state, no dedup table.
113
+
114
+ | Option | Purpose |
115
+ |--------|---------|
116
+ | `--dry-run` | Interpret events without writes or continuation |
117
+ | `--quiet`, `-q` | Suppress non-essential output |
118
+ | `--debug`, `-d` | Show debug output |
125
119
 
126
- - `TARGETS`: optional task refs or folder names to prune
120
+ ```bash
121
+ ace-overseer process-reports # interpret, record, continue
122
+ ace-overseer process-reports --dry-run # what would happen, zero effects
123
+ ```
127
124
 
128
- Options:
125
+ Matching and outcome rules (enforced mechanically):
126
+
127
+ - A report matches the current order by the `assignment` recorded on a step.
128
+ An explicit assignment that matches no step is `unmatched` — there is no
129
+ task-only fallback, so a stale report for a different assignment never
130
+ completes whichever step happens to remain. A report WITHOUT an assignment
131
+ (a planner readiness report) matches only the preparation role: the
132
+ managing task's `project_task` plus exactly one non-terminal step whose
133
+ own assignment is blank. A report fitting no open allocation is reported
134
+ as `unmatched` and kept for clarification — never treated as success.
135
+ - Success records `processed_report`/`report_result` on the step and marks
136
+ it `done`, then continues with the next unblocked step (same
137
+ `DependencyReadiness` gate as `work-on`): `ace-overseer handoff` for the
138
+ next role when the family records a worktree, otherwise the `work-on`
139
+ gate. A refused continuation is reported as blocked with reasons. The
140
+ handoff outcome carries the actionable start command (the same one the
141
+ Handoff CLI prints); the window is ensured, the agent runs the command.
142
+ - A repeated delivery of an already-processed report is `duplicate`: the
143
+ recorded result and existing allocation answer it; nothing re-runs
144
+ (delivery repetition is never work repetition). A duplicate whose
145
+ recorded result is success still re-checks the continuation from current
146
+ task/assignment state — the report result is persisted BEFORE dispatch,
147
+ so a failed handoff (or a crash between the write and the dispatch) must
148
+ not suppress the next role forever. Duplicate starts stay impossible: the
149
+ gates read real allocation state.
150
+ - An `error` result records the cause on the step but keeps it open; a
151
+ question surfaces its `ace-hitl update <id> --answer` path. Neither
152
+ advances a step nor triggers a continuation.
129
153
 
130
- - `--assignment`, `-a`: prune a specific assignment by ID
131
- - `--force`, `-f`: skip the interactive confirmation for already-safe candidates; never bypasses preservation, dirtiness, lifecycle or revalidation blocks
132
- - `--yes`, `-y`: skip interactive confirmation
133
- - `--dry-run`: run the same proof classification as apply, changing no worktrees, refs, assignment state or metadata (a dry-run receipt is not reusable authorization)
134
- - `--preservation FILE`: YAML manifest (`version: 1`, `candidates:`) declaring cross-repository destinations for migrated work; a claim to verify, never proof by itself
135
- - Local prune uses the configured runtime; protected physical cleanup uses its canonical cleanup owner.
136
- - `--quiet`, `-q`: suppress progress output; blocked/failed results still print and signal through the exit code
137
- - `--debug`, `-d`: show debug output
138
- - `--help`, `-h`: show help
154
+ ## `ace-overseer status`
139
155
 
140
- ### Prune safety (enforced)
156
+ Show the overseer's one-view status: every configured source is collected
157
+ live, read-only, into one table or JSON payload. Nothing is persisted — the
158
+ view is always computed from the source owners' current state.
141
159
 
142
- Every candidate is deleted only after executed proofs; missing, failed or
143
- ambiguous evidence preserves the candidate, and `--force`/`--yes` never
144
- override a block:
160
+ ```bash
161
+ ace-overseer status
162
+ ace-overseer status --format json
163
+ ace-overseer status --watch
164
+ ```
145
165
 
146
- - Preservation: source HEAD is contained in the surviving accepted base branch, or a declared destination is verified -- accepted on its surviving destination branch -- with full-tree equality or an exact content transition (paths, modes, symlinks, binary content) across separate bases. Patch-range proofs additionally require the independently recorded attempt baseline, and that baseline itself must survive on an accepted ref.
166
+ | Option | Purpose |
167
+ |--------|---------|
168
+ | `--format` | `table` (default) or `json` |
169
+ | `--watch`, `-w` | Auto-refresh the worktree dashboard |
170
+ | `--runtime` | Terminal backend used for pane checks |
171
+ | `--quiet`, `-q` | Suppress non-essential output |
172
+ | `--debug`, `-d` | Show debug output |
173
+
174
+ ### Sources
175
+
176
+ Sources are configured under `status_sources` in the overseer config
177
+ (`.ace/overseer/config.yml`; defaults in the gem's
178
+ `.ace-defaults/overseer/config.yml`). Each key is one source; setting
179
+ `enabled: false` disables it.
180
+
181
+ | Source | Information | Owner interface used |
182
+ |--------|-------------|----------------------|
183
+ | `worktrees` | worktrees with assignment progress and git state | `ace-git-worktree` WorktreeManager + worktree assignment context |
184
+ | `forge` | recent forge pull requests and issues (explicit unavailable marker when the provider has no issue-listing API) | `ace-git` Providers `recent_pull_requests` / `recent_issues` (forge-neutral) |
185
+ | `project_tasks` | project task ids, statuses, dependencies (full descendant tree) | `ace-task` TaskManager (`.ace-tasks/`) |
186
+ | `overseer_tree` | private overseer tasks including lifecycle steps and their recorded reports | `ace-task` TaskManager (`.ace-tasks/_overseer/`) |
187
+ | `herdr` | live workspaces/tabs/panes | `ace-herdr` ControlSurface + StatusComposer (read-only) |
188
+ | `coworkers` | per-worktree executor truth | `ace-coworker` WorktreeExecutorProbe + ActiveExecutorRule |
189
+
190
+ `forge` is disabled by default (`enabled: false`). Enable it in project or
191
+ user config when the forge server is configured; with no server, a missing
192
+ provider CLI, or no network it degrades to a per-source error entry, never
193
+ to "no open pull requests".
194
+
195
+ ### Attention: blockers, failures, missing data
196
+
197
+ The same one-shot view opens with a derived `-- attention` section that
198
+ splits what needs the overseer's decision from healthy progress. It is
199
+ computed live from the collected sources plus the read-only ace-hitl
200
+ inbox — no new fetchers, no second dashboard, nothing persisted
201
+ (`Organisms::StatusAttention`):
202
+
203
+ - **BLOCKER** — a startable task (`pending` in the project or `_overseer`
204
+ tree) whose dependencies are not satisfied, or a task explicitly
205
+ `blocked`, with the concrete reason per dependency
206
+ (`Atoms::DependencyReadiness`: predecessor status, missing or cyclic
207
+ dependency) and the next action.
208
+ - **FAILURE** — a source `error` (with origin), a `failed`/`stalled`
209
+ assignment, a per-worktree executor probe error, an escalation: a
210
+ pending ace-hitl `question` awaiting an answer, or an unprocessed
211
+ incoming ace-hitl `report` (next action: run
212
+ `ace-overseer process-reports`).
213
+ - **MISSING DATA** — a disabled source, unknown `status_sources` keys,
214
+ an unreadable task tree (dependency readiness unverified), an
215
+ unrecognized task status, an unknown executor state (`unknown`/
216
+ `unparseable` — the worktree cannot be treated as free), or an
217
+ unreachable hitl inbox.
218
+
219
+ Every row carries a `next_action`. Absence of data is never success: a
220
+ disabled or errored source confirms neither a free worktree nor a
221
+ finished task (program contract). When nothing needs attention the
222
+ section says so explicitly (`-- attention: none`).
223
+
224
+ ### JSON contract
225
+
226
+ ```json
227
+ {
228
+ "sources": {
229
+ "worktrees": {"status": "ok", "origin": "...", "data": {"worktrees": [...]}},
230
+ "forge": {"status": "disabled"},
231
+ "herdr": {"status": "error", "origin": "...", "error": "..."}
232
+ },
233
+ "unknown_keys": ["forg"],
234
+ "attention": {
235
+ "blockers": [
236
+ {"kind": "dependency", "tree": "project", "task_id": "8x1",
237
+ "title": "...", "reasons": ["8x0: predecessor not integrated yet (status: running)"],
238
+ "next_action": "unblock the predecessor(s), then start or continue 8x1"}
239
+ ],
240
+ "failures": [
241
+ {"kind": "escalation", "subject": "q7", "task": "8x1", "assignment": "asg1",
242
+ "detail": "Which branch?", "next_action": "answer question q7 via ace-hitl"}
243
+ ],
244
+ "missing_data": [
245
+ {"kind": "source_disabled", "subject": "forge",
246
+ "detail": "source disabled: absence of its data does not confirm a free worktree or a finished task",
247
+ "next_action": "enable 'forge' under status_sources or accept that its view stays unknown"}
248
+ ]
249
+ }
250
+ }
251
+ ```
147
252
 
148
- - No active writer: recorded attempts must be terminal (active or uncertain attempts block; unreadable attempt state blocks); assignment/driver/start paths and prune share a durable exclusion that survives removal of the target, so no second writer can enter during deletion; dirty tracked or untracked files are work and block deletion, even with `--force`.
253
+ Every entry carries `status` (`ok` | `disabled` | `error`); `ok` entries
254
+ add `origin` (explicit provenance) and `data`; `error` entries add `origin`
255
+ and `error`. A failing or disabled source is rendered next to the healthy
256
+ results — missing data never reads as a free worktree or a finished task.
257
+ In the `coworkers` data an unknown or unparseable commission reports
258
+ `active: true` with state `unknown`/`unparseable` (never free).
149
259
 
150
- - Assignment cache: cleanup removes only the assignment cache directory after the durable journal evidence (`refs/ace/execution`, never deleted) confirms every attempt terminal; the journal checkout is never removed.
260
+ `--watch` keeps refreshing the worktree dashboard (the quick-refresh
261
+ section); the full source view is the one-shot `status` run.
151
262
 
152
- - Exit codes: dry-run always exits 0 (blocked candidates are listed); apply exits nonzero when any selected candidate is blocked or removal fails, while independent safe candidates still complete.
263
+ ## `ace-overseer prune`
153
264
 
154
- - Unmatched explicit targets are errors; empty automatic selection is a no-op; cancelled confirmation deletes nothing.
265
+ Remove completed task worktrees. A candidate is removed only when the
266
+ assignment is complete, the task is marked done, and the git working tree is
267
+ clean. `--force`/`--yes` never override those blocks.
155
268
 
156
- ## Example Flows
269
+ ```bash
270
+ ace-overseer prune --dry-run
271
+ ace-overseer prune --yes
272
+ ace-overseer prune 8q4 --dry-run
273
+ ace-overseer prune --assignment abc123
274
+ ```
157
275
 
158
- Start task work: `ace-overseer work-on --task 8q4.t.umu.1`.
276
+ | Option | Purpose |
277
+ |--------|---------|
278
+ | `TARGETS` | Task refs or folder names to prune |
279
+ | `--assignment`, `-a` | Prune a specific assignment by ID |
280
+ | `--dry-run` | Show candidates only; no cleanup side effects |
281
+ | `--yes`, `-y` | Skip the confirmation prompt |
282
+ | `--force`, `-f` | Skip confirmation for already-safe candidates; never bypasses safety blocks |
283
+ | `--preservation FILE` | YAML manifest declaring verified cross-repository destinations |
284
+ | `--quiet`, `-q` | Suppress progress output |
285
+ | `--debug`, `-d` | Show debug output |
159
286
 
160
- Check dashboard: `ace-overseer status`.
287
+ Dry-run exits 0 even when it lists blocked candidates. Apply exits non-zero
288
+ when any selected candidate is blocked or removal fails; independent safe
289
+ candidates still complete. Unmatched explicit targets are errors.
161
290
 
162
- Preview then prune: `ace-overseer prune --dry-run`, then `ace-overseer prune --yes`.
291
+ > **Planned (L6):** private queue and worktree handoff between roles -- not
292
+ > available yet.
163
293
 
164
- ## Terminal Runtime Configuration
294
+ ## Terminal runtime configuration
165
295
 
166
- Work-on opens the task's terminal window and prune closes it through the
167
- runtime-neutral `ace-runtime` contract. Select the terminal runtime in
296
+ Work-on opens the task terminal and prune closes its window through the
297
+ runtime-neutral [ace-runtime](../ace-runtime) contract. Select the backend in
168
298
  `.ace/overseer/config.yml`:
169
299
 
170
300
  ```yaml
171
- # tmux | herdr | auto (default) — auto detects tmux first, then herdr;
172
- # ACE_RUNTIME env wins over this key; nothing detected fails explicitly
301
+ # tmux | herdr | auto (default): auto detects tmux first, then herdr.
302
+ # ACE_RUNTIME wins over this key; nothing detected fails explicitly.
173
303
  runtime: auto
174
304
  window_presets:
175
- "work-on-task": "work-on-task" # preset applied to the opened window/tab
305
+ "work-on-task": "work-on-task"
176
306
  ```
177
307
 
178
- The preset key is `window_presets` (renamed from `tmux_window_presets`
179
- pre-1.0; there is no legacy alias). The same configured runtime closes a
180
- worktree's window during accepted prunes.
308
+ ## Private overseer queue (L6)
181
309
 
182
- Prune migrated work with a declared destination:
310
+ The overseer role coordinates delegated work in its own gitignored list,
311
+ separate from project tasks. No queue engine is added: order, dependencies,
312
+ and allocations live in ordinary task files under `.ace-tasks/_overseer/`
313
+ (see ADR-034 and `docs/lab-flow.md`).
183
314
 
184
315
  ```bash
185
- mkdir -p .ace-local/prune
186
- cat > .ace-local/prune/destinations.yml <<'YAML'
187
- version: 1
188
- candidates:
189
- - worktree_path: /abs/path/.ace-wt/task.230
190
- source_repo: /abs/path
191
- source_base: <base-sha>
192
- source_head: <head-sha>
193
- destination_repo: /abs/successor
194
- destination_base: <dest-base-sha>
195
- destination_head: <accepted-head-sha>
196
- destination_branch: refs/heads/main
197
- YAML
198
- ace-overseer prune task.230 --preservation .ace-local/prune/destinations.yml --dry-run
316
+ mkdir -p .ace-tasks/_overseer # prepared once by project config
317
+ ace-task list --in _overseer # the overseer's own view
318
+ ace-task create "Manage: <scope>" --in _overseer
319
+ ace-task create "Integrate <scope>" --child-of <manager-ref>
320
+ ace-task update <B-step> --set dependencies=<A-integrate-ref>
199
321
  ```
200
322
 
201
- ## Protected execution and review
323
+ Binding rules: cross-task merge requirements depend on the integration step
324
+ (never on worker completion); one active executor per task worktree across
325
+ roles (`ace-overseer handoff` enforces the role-sequence handoff in the same
326
+ worktree mechanically); implementation completion does not close a managing
327
+ task while review or integration remains; coworker reports arrive via ace-hitl
328
+ and only the overseer writes its list (`ace-overseer process-reports`
329
+ interprets them mechanically and continues the queue through the work-on and
330
+ handoff gates).
202
331
 
203
- The existing Assign authority and installed mapping grant admit execution. Public
204
- topology supplies visible IDs only. Runtime names and charter selection cannot
205
- change OS credentials, grants or reviewer identity.
332
+ Full procedure: `ace-bundle wfi://overseer/queue`.
206
333
 
207
- ```bash
208
- ace-overseer work-on --task TASK --project ace --agent builder --runtime herdr
209
- ace-overseer status --project ace --agent builder --format json
210
- ace-overseer work-on --recover-request .ace-local/overseer/launch-requests/INVOCATION.json
211
- ```
212
-
213
- Retain the printed input paths/hashes and original mapping/invocation. Missing
214
- readiness, lost output, child exit or pane state never authorize replacement or
215
- physical cleanup. Recovery is strictly read-only. Protected physical cleanup
216
- requires its designated preservation/no-writer owner.
217
-
218
- - `ace-overseer review --project PROJECT --agent AGENT --assignment A --attempt T --head HEAD --candidate-generation N --expected-generation G --mutation REQUEST --accept-mutation ACCEPT`: request independent review of the exact canonical candidate and submit its executed receipt. Run under the installed reviewer principal. `accepted` means the authority accepted that receipt; `uncertain` requires explicit status inspection.
219
- - `ace-overseer review --status --project PROJECT --agent AGENT --assignment A --attempt T --mutation REQUEST`: inspect the original request without rerunning review or uploading anything.
220
- - `ace-overseer review --cancel --project PROJECT --agent AGENT --assignment A --attempt T --head HEAD --candidate-generation N --review-event EVENT --expected-generation G --mutation CANCEL`: revoke the exact reservation using its status-provided event. Cancellation does not terminate the old reviewer. After cancellation, start a new review explicitly with new mutation IDs and the observed generation.
221
-
222
- ## Public Verification Paths
223
-
224
- Use these user-visible checks when validating behavior end-to-end:
225
-
226
- - Preset override path:
227
-
228
- 1. `ace-overseer work-on --task <task-ref> --preset <preset-name>`
229
- 2. `ace-git-worktree list` (confirm worktree exists for `<task-ref>`)
230
- 3. `ace-overseer status --format json` (confirm the task appears with assignment/preset details)
231
-
232
- - Idempotent rerun oracle:
233
-
234
- 1. Run `ace-overseer work-on --task <task-ref>` twice
235
- 2. Verify one task entry remains in `ace-overseer status --format json`
236
- 3. Verify only one matching worktree exists in `ace-git-worktree list`
237
-
238
- - Prune lifecycle minimal flow:
334
+ ## Example flows
239
335
 
240
- 1. `ace-task done <task-ref>`
241
- 2. `ace-overseer prune --dry-run`
242
- 3. `ace-overseer prune --yes`
243
- 4. `ace-git-worktree list` to confirm removed vs retained task worktrees
244
- 5. `ace-overseer prune --dry-run` to confirm no remaining safe candidates
336
+ Start task work and check the dashboard:
245
337
 
246
- Assignment JSON includes `recovery`: current liveness, recovery decision/reason, last verified observation, exact attempt identities, checkpoints and unresolved effect/inbox references. Unreadable evidence is explicitly unknown; dashboard rows needing reconciliation use a question mark instead of a success indicator. An older verified observation remains audit history and does not make a current unknown observation live.
247
-
248
- ## Exact protected steering (reviewed target interface)
249
-
250
- `ace-overseer prompt --project ace --agent builder --assignment A --attempt T --mutation steer-001 --expected-generation 12 --file instruction.txt`
251
-
252
- Use exactly one explicit `--file PATH` or `--stdin` input selection. Prompt text remains bounded UTF-8 (16,384 bytes), preserved exactly and omitted from operational output. Redirecting stdin alone does not select input.
253
-
254
- `ace-overseer prompt --status --project ace --agent builder --assignment A --attempt T --mutation steer-001`
255
-
256
- Status rejects both input selectors and expected generation before reading input; it uses the original prompt mutation and never resends. An explicit identical replay retains the original generation and text; changed input refuses.
257
-
258
- `ace-overseer stop --project ace --agent builder --assignment A --attempt T --mutation stop-001 --expected-generation 14`
338
+ ```bash
339
+ ace-overseer work-on --task t.123
340
+ ace-overseer status --format json
341
+ ```
259
342
 
260
- Exact project/mapping/assignment/attempt selection is mandatory. Immutable stop replay does not refresh settlement. Canonical terminal plus reservation release remains separate from local child exit. Legacy Lab Work forwarding and prepare/prune delegation are removed.
343
+ Preview and prune finished work:
261
344
 
262
- Public topology: `ace-overseer projects` and `ace-overseer agents --project PROJECT` emit the maintained classified topology envelope for the verified caller. Visibility grants no execution authority. Local prune uses the configured runtime and existing preservation/no-writer owner; it accepts no protected cleanup or legacy runtime selector.
345
+ ```bash
346
+ ace-task update t.123 --set status=done
347
+ ace-overseer prune --dry-run
348
+ ace-overseer prune --yes
349
+ ace-overseer prune --dry-run
350
+ ```