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/README.md
CHANGED
|
@@ -1,7 +1,7 @@
|
|
|
1
1
|
<div align="center">
|
|
2
2
|
<h1> ACE - Overseer </h1>
|
|
3
3
|
|
|
4
|
-
|
|
4
|
+
Local task worktrees, assignments, and cleanup in one command surface.
|
|
5
5
|
|
|
6
6
|
<img src="../docs/brand/AgenticCodingEnvironment.Logo.XS.jpg" alt="ACE Logo" width="480">
|
|
7
7
|
<br><br>
|
|
@@ -14,69 +14,87 @@
|
|
|
14
14
|
|
|
15
15
|
> Works with: Claude Code, Codex CLI, OpenCode, Gemini CLI, pi-agent, and more.
|
|
16
16
|
|
|
17
|
-
|
|
18
|
-
|
|
19
|
-
|
|
17
|
+
> **State owner:** the private, gitignored overseer task list in
|
|
18
|
+
> `.ace-tasks/_overseer/`, a normal task folder reached through
|
|
19
|
+
> `ace-task --in _overseer …` (see [docs/lab-flow.md](../docs/lab-flow.md)).
|
|
20
|
+
> Task worktrees live in `.ace-wt/`; assignment plans and steps stay in
|
|
21
|
+
> `.ace-local/assign/` (ace-assign) and are never copied into the overseer
|
|
22
|
+
> list.
|
|
20
23
|
|
|
21
|
-
|
|
24
|
+
[Getting Started](docs/getting-started.md) | [Usage Guide](docs/usage.md) | [Handbook - Skills, Agents, Templates](docs/handbook.md)
|
|
22
25
|
|
|
23
|
-
|
|
24
|
-
|
|
25
|
-
|
|
26
|
+
Starting task work means creating a worktree, opening a terminal, and preparing
|
|
27
|
+
an assignment. ace-overseer collapses that into one command, shows what runs
|
|
28
|
+
where, and cleans up finished worktrees so nothing lingers.
|
|
26
29
|
|
|
27
30
|
## How It Works
|
|
28
31
|
|
|
29
|
-
1. Resolve task refs and create a scoped worktree
|
|
30
|
-
2.
|
|
31
|
-
|
|
32
|
+
1. Resolve task refs and create a scoped worktree under `.ace-wt/`.
|
|
33
|
+
2. Prepare an assignment through `ace-assign create --task ...`; the plan and
|
|
34
|
+
its steps live in `.ace-local/assign/`.
|
|
35
|
+
3. Open a terminal (tmux or Herdr) mapped to the worktree and point the agent
|
|
36
|
+
at `/as-assign-drive`.
|
|
37
|
+
|
|
38
|
+
tmux and Herdr are transports only. They do not own task, assignment, or HITL
|
|
39
|
+
state. The old protected execution path (`--project/--agent`, protected
|
|
40
|
+
status/review/stop/prompt/prune) and the installed ordinary launcher
|
|
41
|
+
(`ace-overseer ordinary`, native journal/attempt-handoff preparation and
|
|
42
|
+
launch) are removed (L1) and are not normal paths. Prune and status read local
|
|
43
|
+
assignment, task, worktree and Git state only.
|
|
32
44
|
|
|
33
45
|
## Use Cases
|
|
34
46
|
|
|
35
|
-
**Kick off task work** - provisions an isolated worktree via
|
|
47
|
+
**Kick off task work** - provisions an isolated worktree via
|
|
48
|
+
[ace-git-worktree](../ace-git-worktree), opens a dedicated terminal, and
|
|
49
|
+
prepares an [ace-assign](../ace-assign) assignment. Draft tasks are blocked
|
|
50
|
+
until reviewed.
|
|
36
51
|
|
|
37
52
|
```bash
|
|
38
53
|
ace-overseer work-on --task 8q4 --preset work-on-task
|
|
39
54
|
```
|
|
40
55
|
|
|
41
|
-
**Bundle related tasks** - pass multiple task refs or a task with subtasks and
|
|
56
|
+
**Bundle related tasks** - pass multiple task refs or a task with subtasks and
|
|
57
|
+
they land in a single worktree. The refs are expanded and forwarded to the
|
|
58
|
+
assignment preset, so every step is prepared in one assignment.
|
|
42
59
|
|
|
43
|
-
**Monitor active work** -
|
|
60
|
+
**Monitor active work** - `ace-overseer status` shows task worktrees with
|
|
61
|
+
assignment progress and git state. Add `--watch` for a live-refreshing view.
|
|
44
62
|
|
|
45
63
|
```bash
|
|
46
64
|
ace-overseer status --watch
|
|
47
65
|
```
|
|
48
66
|
|
|
49
|
-
**
|
|
50
|
-
|
|
51
|
-
|
|
52
|
-
|
|
53
|
-
|
|
54
|
-
|
|
55
|
-
|
|
56
|
-
|
|
57
|
-
|
|
58
|
-
|
|
59
|
-
|
|
60
|
-
|
|
61
|
-
|
|
62
|
-
|
|
63
|
-
|
|
64
|
-
|
|
65
|
-
|
|
66
|
-
|
|
67
|
-
|
|
68
|
-
|
|
69
|
-
|
|
67
|
+
**Clean up finished work** - `ace-overseer prune` removes completed worktrees
|
|
68
|
+
safely after assignment completion, task completion, and a clean working tree.
|
|
69
|
+
Use `--dry-run` to preview candidates, `--yes` to skip confirmation, or
|
|
70
|
+
`--assignment` to prune a single assignment.
|
|
71
|
+
|
|
72
|
+
**Customize the workflow** - the assignment preset controls which steps run and
|
|
73
|
+
in what order; each step references a workflow instruction that defines how it
|
|
74
|
+
executes. Browse [available presets](../ace-assign/.ace-defaults/assign/presets/)
|
|
75
|
+
or create your own.
|
|
76
|
+
|
|
77
|
+
## Planned waves
|
|
78
|
+
|
|
79
|
+
> **Planned (L4):** planner role that prepares the worktree and the whole
|
|
80
|
+
> assignment sequence -- not available yet.
|
|
81
|
+
>
|
|
82
|
+
> **L6 (partial):** the private overseer queue is coordinated through the
|
|
83
|
+
> gitignored `.ace-tasks/_overseer/` list (`ace-task --in _overseer`):
|
|
84
|
+
> managing tasks with lifecycle subtasks (prepare, implement, review,
|
|
85
|
+
> integrate), integration-gated dependencies, and one active executor per
|
|
86
|
+
> worktree. See the
|
|
87
|
+
> [Overseer Queue Workflow](handbook/workflow-instructions/overseer/queue.wf.md)
|
|
88
|
+
> (`ace-bundle wfi://overseer/queue`). Role dispatch and report-driven
|
|
89
|
+
> continuation land with the remaining L6 leaves.
|
|
90
|
+
>
|
|
91
|
+
> **Planned (L7):** aggregated status and pi continuation of already delegated
|
|
92
|
+
> work -- not available yet.
|
|
70
93
|
|
|
71
94
|
## Testing
|
|
72
95
|
|
|
73
|
-
- `ace-test ace-overseer` runs deterministic
|
|
74
|
-
- `ace-test ace-overseer
|
|
75
|
-
- `ace-test ace-overseer all` runs fast + feat deterministic coverage.
|
|
76
|
-
- `ace-test-e2e ace-overseer` runs retained workflow scenarios from `test/e2e/`.
|
|
77
|
-
|
|
78
|
-
The package no longer uses deterministic `*_test.rb` files under `test/e2e/` and
|
|
79
|
-
does not use `ace-test ace-overseer e2e` as a deterministic test path.
|
|
96
|
+
- `bin/ace-test ace-overseer all` runs deterministic package coverage.
|
|
97
|
+
- `bin/ace-test-e2e ace-overseer` runs retained workflow scenarios.
|
|
80
98
|
|
|
81
99
|
---
|
|
82
100
|
[Getting Started](docs/getting-started.md) | [Usage Guide](docs/usage.md) | [Handbook - Skills, Agents, Templates](docs/handbook.md) | Part of [ACE](https://github.com/cs3b/ace)
|
data/docs/getting-started.md
CHANGED
|
@@ -9,11 +9,16 @@ ace-docs:
|
|
|
9
9
|
|
|
10
10
|
# Getting Started with ace-overseer
|
|
11
11
|
|
|
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 stay in `.ace-local/assign/`. See
|
|
15
|
+
> [docs/lab-flow.md](../../docs/lab-flow.md).
|
|
16
|
+
|
|
12
17
|
## Prerequisites
|
|
13
18
|
|
|
14
|
-
- `tmux` installed and available on your PATH
|
|
19
|
+
- `tmux` or Herdr installed and available on your PATH (one terminal backend)
|
|
15
20
|
- ACE toolkit installed in your repository
|
|
16
|
-
- A task reference (for example `
|
|
21
|
+
- A task reference (for example `t.123`) ready to execute
|
|
17
22
|
|
|
18
23
|
## Installation
|
|
19
24
|
|
|
@@ -23,9 +28,9 @@ If the command resolves, your environment is ready.
|
|
|
23
28
|
|
|
24
29
|
## Start Work on a Task
|
|
25
30
|
|
|
26
|
-
Launch a focused task workspace: `ace-overseer work-on --task
|
|
31
|
+
Launch a focused task workspace: `ace-overseer work-on --task t.123`.
|
|
27
32
|
|
|
28
|
-
This flow provisions or reuses a task worktree, opens a
|
|
33
|
+
This flow provisions or reuses a task worktree, opens a terminal window, and prepares assignment context in `.ace-local/assign/`.
|
|
29
34
|
|
|
30
35
|
## Monitor Active Work
|
|
31
36
|
|
data/docs/handbook.md
CHANGED
|
@@ -17,12 +17,6 @@ ace-docs:
|
|
|
17
17
|
- Purpose: orchestrate task worktrees through `work-on`, `status`, and `prune`
|
|
18
18
|
- Execution model: workflow-backed skill invoking `wfi://overseer`
|
|
19
19
|
|
|
20
|
-
### `as-overseer-configure-project`
|
|
21
|
-
|
|
22
|
-
- Path: `handbook/skills/as-overseer-configure-project/SKILL.md`
|
|
23
|
-
- Purpose: adapt delivery supervision to project-owned presets, workflows, and decision policy without destructive overwrite
|
|
24
|
-
- Execution model: workflow-backed skill invoking `wfi://overseer/configure-project`
|
|
25
|
-
|
|
26
20
|
## Workflows
|
|
27
21
|
|
|
28
22
|
### `wfi://overseer`
|
|
@@ -30,18 +24,7 @@ ace-docs:
|
|
|
30
24
|
- Path: `handbook/workflow-instructions/overseer.wf.md`
|
|
31
25
|
- Purpose: canonical workflow for working on tasks, checking active worktrees, and safe cleanup
|
|
32
26
|
- Core sequence: 1) run `ace-overseer work-on --task ...`; 2) inspect state with `ace-overseer status`; 3) preview cleanup with `ace-overseer prune --dry-run`, then confirm with `--yes`.
|
|
33
|
-
|
|
34
|
-
### `wfi://overseer/configure-project`
|
|
35
|
-
|
|
36
|
-
- Path: `handbook/workflow-instructions/overseer/configure-project.wf.md`
|
|
37
|
-
- Purpose: resolve and review effective delivery presets, workflows, and decision guides, then apply repeatable project-local adaptation while preserving customization
|
|
38
|
-
- Output: per-asset `CREATED`, `UPDATED`, `KEPT`, or `BLOCKED` evidence plus a repeat-run zero-write check
|
|
39
|
-
|
|
40
|
-
### `wfi://overseer/maintain-continuation`
|
|
41
|
-
|
|
42
|
-
- Path: `handbook/workflow-instructions/overseer/maintain-continuation.wf.md`
|
|
43
|
-
- Purpose: bootstrap native 600-second progress and 3600-second cleanup duties, then restore the exact persisted session without duplicate registration
|
|
44
|
-
- Evidence: real model turn, persisted ace-wake entries, exact-session restart and consumed wake; Assign remains execution owner
|
|
27
|
+
- The coordinator/continuation workflow and project-adaptation skill were removed with the old lab model; the private `_overseer` queue and continuation behavior are planned for L6/L7.
|
|
45
28
|
|
|
46
29
|
## Related Documentation
|
|
47
30
|
|