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.
- checksums.yaml +4 -4
- data/.ace-defaults/overseer/config.yml +9 -0
- data/CHANGELOG.md +24 -804
- data/README.md +60 -42
- data/docs/getting-started.md +9 -4
- data/docs/handbook.md +1 -18
- data/docs/usage.md +297 -209
- data/handbook/workflow-instructions/overseer/queue.wf.md +210 -0
- data/handbook/workflow-instructions/overseer.wf.md +17 -32
- data/lib/ace/overseer/atoms/dependency_readiness.rb +48 -0
- data/lib/ace/overseer/atoms/handoff_readiness.rb +75 -0
- data/lib/ace/overseer/atoms/report_interpretation.rb +236 -0
- data/lib/ace/overseer/atoms/status_formatter.rb +0 -1
- data/lib/ace/overseer/cli/commands/handoff.rb +69 -0
- data/lib/ace/overseer/cli/commands/process_reports.rb +50 -0
- data/lib/ace/overseer/cli/commands/prune.rb +3 -50
- data/lib/ace/overseer/cli/commands/status.rb +8 -55
- data/lib/ace/overseer/cli/commands/work_on.rb +6 -50
- data/lib/ace/overseer/cli.rb +10 -14
- data/lib/ace/overseer/models/assignment_prune_candidate.rb +5 -5
- data/lib/ace/overseer/models/prune_candidate.rb +5 -5
- data/lib/ace/overseer/molecules/assignment_prune_safety_checker.rb +22 -84
- data/lib/ace/overseer/molecules/git_preservation_checker.rb +33 -21
- data/lib/ace/overseer/molecules/handoff_probe.rb +101 -0
- data/lib/ace/overseer/molecules/hitl_inbox.rb +43 -0
- data/lib/ace/overseer/molecules/prune_safety_checker.rb +43 -88
- data/lib/ace/overseer/molecules/worktree_context_collector.rb +4 -18
- data/lib/ace/overseer/organisms/handoff_orchestrator.rb +122 -0
- data/lib/ace/overseer/organisms/prune_orchestrator.rb +2 -2
- data/lib/ace/overseer/organisms/report_processor.rb +241 -0
- data/lib/ace/overseer/organisms/status_attention.rb +306 -0
- data/lib/ace/overseer/organisms/status_collector.rb +267 -3
- data/lib/ace/overseer/organisms/status_sources.rb +276 -0
- data/lib/ace/overseer/organisms/work_on_orchestrator.rb +49 -9
- data/lib/ace/overseer/version.rb +1 -1
- data/lib/ace/overseer.rb +12 -1
- metadata +46 -27
- data/handbook/skills/as-overseer-configure-project/SKILL.md +0 -32
- data/handbook/workflow-instructions/overseer/configure-project.wf.md +0 -238
- data/handbook/workflow-instructions/overseer/maintain-continuation.wf.md +0 -115
- data/handbook/workflow-instructions/roles/lab-coordinator.wf.md +0 -106
- data/handbook/workflow-instructions/roles/project-overseer.wf.md +0 -182
- data/handbook/workflow-instructions/roles/second-commander.wf.md +0 -95
- data/lib/ace/overseer/cli/commands/ordinary.rb +0 -37
- data/lib/ace/overseer/cli/commands/prompt.rb +0 -63
- data/lib/ace/overseer/cli/commands/review.rb +0 -44
- data/lib/ace/overseer/cli/commands/stop.rb +0 -33
- data/lib/ace/overseer/molecules/launch_request.rb +0 -216
- data/lib/ace/overseer/molecules/original_launch_child.rb +0 -165
- data/lib/ace/overseer/molecules/proposal_tick.rb +0 -56
- data/lib/ace/overseer/molecules/protected_selection.rb +0 -46
- data/lib/ace/overseer/organisms/launch_recovery.rb +0 -65
- data/lib/ace/overseer/organisms/ordinary_work_on.rb +0 -186
- data/lib/ace/overseer/organisms/protected_prune.rb +0 -116
- data/lib/ace/overseer/organisms/protected_review.rb +0 -167
- data/lib/ace/overseer/organisms/protected_status.rb +0 -157
- data/lib/ace/overseer/organisms/protected_steering.rb +0 -78
- 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:
|
|
4
|
+
purpose: CLI reference for local overseer worktrees, assignments, and cleanup.
|
|
5
5
|
ace-docs:
|
|
6
|
-
last-updated: 2026-
|
|
7
|
-
last-checked: 2026-
|
|
6
|
+
last-updated: 2026-10-17
|
|
7
|
+
last-checked: 2026-10-17
|
|
8
8
|
---
|
|
9
9
|
|
|
10
10
|
# Usage
|
|
11
11
|
|
|
12
|
-
|
|
13
|
-
|
|
14
|
-
|
|
15
|
-
|
|
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
|
-
##
|
|
17
|
+
## Command Surface
|
|
25
18
|
|
|
26
|
-
|
|
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
|
-
|
|
74
|
-
|
|
75
|
-
|
|
76
|
-
|
|
77
|
-
|
|
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
|
-
|
|
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
|
-
|
|
105
|
-
|
|
106
|
-
Invocation: `ace-overseer status [--format table|json] [--watch]`.
|
|
32
|
+
## `ace-overseer work-on`
|
|
107
33
|
|
|
108
|
-
|
|
34
|
+
Create or reuse local worktrees and prepare one assignment.
|
|
109
35
|
|
|
110
|
-
|
|
111
|
-
|
|
112
|
-
|
|
113
|
-
|
|
114
|
-
|
|
115
|
-
|
|
116
|
-
|
|
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
|
-
|
|
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
|
-
|
|
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
|
-
|
|
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
|
-
|
|
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
|
-
|
|
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
|
-
|
|
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
|
-
-
|
|
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
|
-
|
|
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
|
-
|
|
143
|
-
|
|
144
|
-
|
|
160
|
+
```bash
|
|
161
|
+
ace-overseer status
|
|
162
|
+
ace-overseer status --format json
|
|
163
|
+
ace-overseer status --watch
|
|
164
|
+
```
|
|
145
165
|
|
|
146
|
-
|
|
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
|
-
|
|
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
|
-
|
|
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
|
-
|
|
263
|
+
## `ace-overseer prune`
|
|
153
264
|
|
|
154
|
-
|
|
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
|
-
|
|
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
|
-
|
|
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
|
-
|
|
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
|
-
|
|
291
|
+
> **Planned (L6):** private queue and worktree handoff between roles -- not
|
|
292
|
+
> available yet.
|
|
163
293
|
|
|
164
|
-
## Terminal
|
|
294
|
+
## Terminal runtime configuration
|
|
165
295
|
|
|
166
|
-
Work-on opens the task
|
|
167
|
-
runtime-neutral
|
|
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)
|
|
172
|
-
# ACE_RUNTIME
|
|
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"
|
|
305
|
+
"work-on-task": "work-on-task"
|
|
176
306
|
```
|
|
177
307
|
|
|
178
|
-
|
|
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
|
-
|
|
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-
|
|
186
|
-
|
|
187
|
-
|
|
188
|
-
|
|
189
|
-
|
|
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
|
-
|
|
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
|
-
|
|
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
|
-
|
|
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
|
-
|
|
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
|
-
|
|
247
|
-
|
|
248
|
-
|
|
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
|
-
|
|
343
|
+
Preview and prune finished work:
|
|
261
344
|
|
|
262
|
-
|
|
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
|
+
```
|