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/README.md CHANGED
@@ -1,7 +1,7 @@
1
1
  <div align="center">
2
2
  <h1> ACE - Overseer </h1>
3
3
 
4
- One command surface for local tmux work and isolated Lab workers.
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
- [Getting Started](docs/getting-started.md) | [Usage Guide](docs/usage.md) | [Handbook - Skills, Agents, Templates](docs/handbook.md)
18
-
19
- ![ace-overseer demo](docs/demo/ace-overseer-getting-started.gif)
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
- Starting task work means creating a worktree, opening a terminal window, and preparing an assignment - three manual steps before you even begin coding. ace-overseer collapses that into a single command, tracks what is running where, and cleans up finished worktrees so nothing lingers. You can jump straight to a focused worktree any time with a single invocation.
24
+ [Getting Started](docs/getting-started.md) | [Usage Guide](docs/usage.md) | [Handbook - Skills, Agents, Templates](docs/handbook.md)
22
25
 
23
- Explicit `--project` selects provisioned protected Assign execution. Omitting it
24
- preserves ordinary local worktree/assignment mode. Runtime selects a terminal
25
- backend; it cannot select credentials or execution authority.
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. Route assignment creation through `ace-assign create --task ...`, which expands the assignment preset into concrete steps under `.ace-local/assign/`, then open a dedicated terminal window mapped to that worktree.
31
- 3. Instruct the agent inside the terminal window to act as an orchestrator and drive the assignment step-by-step.
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 [ace-git-worktree](../ace-git-worktree), opens a dedicated [ace-tmux](../ace-tmux) window, and prepares an [ace-assign](../ace-assign) assignment - all in one shot. Supports regular tasks and subtask trees. Draft tasks are blocked until reviewed. Use `/as-overseer` or from the CLI:
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 they all land in a single worktree. The refs are expanded and forwarded to the assignment preset, so every step for every task is prepared in one assignment. Drive through them with `/as-assign-drive`.
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** - [`ace-overseer status`](docs/usage.md#ace-overseer-status) shows a dashboard of all task worktrees with assignment progress, git state, and PR links. Add `--watch` for a live-refreshing view that updates assignments every 15 seconds and git status every 5 minutes.
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
- **Start protected work** - prepare one reviewed leaf under the explicit project,
50
- retain exact inputs, and keep its original foreground launcher:
51
-
52
- ```bash
53
- ace-overseer work-on --task TASK --project ace --agent builder --runtime herdr
54
- ace-overseer status --project ace --agent builder --format json
55
- ace-overseer work-on --recover-request .ace-local/overseer/launch-requests/INVOCATION.json
56
- ```
57
-
58
- The start command prints and flushes retained request, definition and bundle
59
- identity even under `--quiet`. It observes the same original child through
60
- uncertainty; use independent status/steering invocations while that foreground
61
- owner remains alive. Recovery is read-only and never rebuilds inputs or relaunches.
62
- Domain installation supplies credentials and fixed entries; ACE's existing
63
- Assign authority owns admission, execution evidence and progress.
64
-
65
- **Clean up finished work** - [`ace-overseer prune`](docs/usage.md#ace-overseer-prune) removes completed worktrees safely. It checks three conditions before removing: assignment completed, task marked done, and git working tree clean. Use `--dry-run` to preview what would be pruned, `--force` for worktrees that fail safety checks, or `--assignment` to prune a single stale assignment.
66
-
67
- **Customize the workflow** - the full pipeline is defined in two layers: the [assignment preset](../ace-assign/.ace-defaults/assign/presets/work-on-task.yml) controls which steps run and in what order (onboard, implement, test, release, review, PR), while each step references a [workflow instruction](../ace-task/handbook/workflow-instructions/task/work.wf.md) that defines how it executes. Browse [available presets](../ace-assign/.ace-defaults/assign/presets/) or create your own to tailor the pipeline to your project.
68
-
69
- For explicit end-to-end validation paths, see [Public Verification Paths](docs/usage.md#public-verification-paths).
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 fast coverage from `test/fast/`.
74
- - `ace-test ace-overseer feat` runs deterministic feature coverage from `test/feat/` when present.
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)
@@ -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 `8q4.t.umu.1`) ready to execute
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 8q4.t.umu.1`.
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 tmux window, and prepares assignment context.
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