ace-overseer 0.15.6 → 0.16.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: f64d7b81728d6636ebc933e6c30f119bc6aba514a8652562f393e5ab7f3a5540
-  data.tar.gz: abdc381e8d76669ba78bb871280704efd979a62df58aeecc703d912cd99a5275
+  metadata.gz: 9f1239c62289b213199cac3a316f72301a82477c6d688a70d991eea76880f2cc
+  data.tar.gz: 4b847ed09a40f56ad43fc52b74db62325230f8c2cd393f2a175491fe21fd262f
 SHA512:
-  metadata.gz: d079fea537a3941ecb55459d52793bf1a6a5d55e411e05dabc4154561536de0cdda61c4b4a8fb6c4fc10170f19fd255e0b66a1da4d0823d332e62aac8511d9d2
-  data.tar.gz: a718d278ba5223bc08589f6627b6fb72f92d433703b7ef69c83a4cc8f06182afc79241754a383f743f5c98b690ce77bbe250c3cd04d97b9a8e5c931e86b38146
+  metadata.gz: 6babe8200aa8f1c2275218d038dc6764a1d64e2af1a252659a38f0445ffd1c8bacfd23be81ae62c99eb22b37be34577a30fa4dc1ec2532a8a995d0c4339b4518
+  data.tar.gz: 668e65a1f12a922b02f1884d1e51eaec6aaf3bfd8fe5647911b1731ce51d4070dab43e79a98069ae8b93ef9fb7c357d168bc05d9af905cd1bbaa070d91f15812

data/.ace-defaults/nav/protocols/wfi-sources/ace-overseer.yml

@@ -0,0 +1,13 @@
+---
+# WFI Sources Protocol Configuration for ace-overseer gem
+# This enables workflow discovery from the installed ace-overseer gem
+
+name: ace-overseer
+type: gem
+description: Overseer workflow instructions from ace-overseer gem
+priority: 10
+
+config:
+  relative_path: handbook/workflow-instructions
+  pattern: "*.wf.md"
+  enabled: true

data/CHANGELOG.md

@@ -14,6 +14,12 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 - Kept tmux as the default runtime while allowing `work-on`, `status`, and dry-run `prune` to delegate through the system-owned `/usr/local/bin/lab` boundary.
 
 
+## [0.16.0] - 2026-09-20
+
+### Added
+- Shipped the overseer lifecycle workflow so `wfi://overseer` resolves for gem consumers: the gem now registers `.ace-defaults/nav/protocols/wfi-sources/ace-overseer.yml` (ace-hitl pattern) and ships real workflow instructions for `work-on`, `status`, and `prune` in `handbook/workflow-instructions/overseer.wf.md`, with prune-safety and status-truth executed-check contracts as first-class non-negotiable steps.
+- Added a packaging test proving the built gem ships both the workflow-instructions payload and the wfi source registration so a future gemspec glob change cannot silently drop them.
+
 ## [0.15.6] - 2026-09-02
 
 ### Technical

data/handbook/workflow-instructions/overseer.wf.md

@@ -1,16 +1,126 @@
 ---
+name: overseer-workflow
+description: Orchestrate task worktrees with ace-overseer (work-on, status, prune) under binding prune-safety and status-truth executed-check contracts
+allowed-tools: Bash, Read
 doc-type: workflow
 title: Overseer Workflow
-purpose: overseer workflow
+purpose: Binding process contract for the overseer lifecycle (work-on, status, prune) with executed-check contracts for prune safety and status truth.
 ace-docs:
-  last-updated: 2026-03-12
-  last-checked: 2026-03-21
+  last-updated: '2026-09-20'
+  last-checked: '2026-09-20'
 ---
 
 # Overseer Workflow
 
+## Goal
+
+Orchestrate task worktrees with `ace-overseer` (work-on, status, prune) as the
+binding process contract. Two executed-check contracts in this workflow are
+non-negotiable: **prune safety** and **status truth**. They exist because a
+described or remembered check is how worktrees and commits get silently
+destroyed and stale blockers masquerade as state. Every step below is executed,
+never assumed.
+
 ## Instructions
 
-1. For work-on flows, run `ace-overseer work-on --task $ARGUMENTS`.
-2. Use `ace-overseer status` to inspect active worktrees.
-3. Use `ace-overseer prune --dry-run` before destructive cleanup, then `ace-overseer prune --yes` when confirmed.
+Run the loaded workflow as the source of truth and execute it end-to-end
+instead of only summarizing it.
+
+### 1) Work-on: start focused task work
+
+Provision a worktree, open a tmux window, and prepare the assignment:
+
+```bash
+ace-overseer work-on --task <task-ref>
+```
+
+- Repeatable/comma-separated refs fan out into the same batch: `ace-overseer work-on --task 230 --task 231,232`
+- Optional preset: `ace-overseer work-on --task <task-ref> --preset <preset-name>`
+- After launch, switch to the tmux window and run `/ace-assign-drive`.
+- Lab runtime variant (reserved agent + Herdr workspace): `ace-overseer work-on --runtime lab --work <work-id> --agent <agent-id>` -- `--task`/`--preset` are not supported with the Lab runtime.
+
+Never improvise worktree provisioning by hand when `work-on` exists; ad-hoc
+worktrees bypass the assignment lifecycle that `status` and `prune` rely on.
+
+### 2) Status: inspect active worktrees
+
+```bash
+ace-overseer status                     # table dashboard
+ace-overseer status --format json       # machine-readable snapshot
+```
+
+Lab runtime: `ace-overseer status --runtime lab [--project <project>]` (no
+`--watch`; continuous status lives in each project Herdr session).
+
+#### Status truth (non-negotiable executed check)
+
+Recorded blockers are **claims, not state**. During any status review:
+
+1. For each pending owner-blocked task, look for an executable non-secret
+   check that can confirm or refute the blocker, and run it when one exists.
+2. Close or correct stale tasks **in the same change** -- do not accept a
+   recorded blocker as state and do not defer the correction to a later pass.
+3. Report what you executed (command + observed output) as the evidence for
+   each kept or closed blocker. A described or remembered check is never
+   sufficient.
+
+### 3) Prune: remove finished worktrees safely
+
+Always preview before destructive cleanup:
+
+```bash
+ace-overseer prune --dry-run
+```
+
+Then apply only when confirmed:
+
+```bash
+ace-overseer prune --yes
+```
+
+- Targeted: `ace-overseer prune <task-ref|folder>...` or `ace-overseer prune --assignment <assignment-id>`
+- Lab runtime: `ace-overseer prune <work-id>... --runtime lab --dry-run`, rerun with `--yes` to delegate each destruction to Lab.
+
+#### Prune safety (non-negotiable executed check)
+
+Prune/removal of a worktree or branch happens **only after an executed
+preservation proof** for every commit that would be removed:
+
+1. Prove the work is already merged into its base:
+
+   ```bash
+   git merge-base --is-ancestor <work-head> <base>
+   ```
+
+   Exit code 0 proves every commit on the work branch is contained in the base.
+
+2. If the work was migrated elsewhere (squash-merge, cherry-pick, hand-off),
+   prove the copy exists with a subject-level search in the successor
+   repository:
+
+   ```bash
+   git -C <successor-repo> log --all --grep "<subject>"
+   ```
+
+   The search must return the commit(s) carrying the work. No output means no
+   proof.
+
+3. A described or remembered proof is never sufficient -- run the command and
+   observe the result in this session.
+
+4. Any commit without a proven copy **blocks the prune** for that worktree.
+   Report the blocked candidate (ref, head SHA, missing proof) to the operator;
+   never silently drop it and never force past a failed proof.
+
+## Non-Negotiable Contracts Summary
+
+| Contract     | Claim                             | Executed proof                                                                                                                                                            |
+|--------------|-----------------------------------|---------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
+| Prune safety | "The work is preserved"           | `git merge-base --is-ancestor <work-head> <base>` (rc=0), or `git -C <successor-repo> log --all --grep "<subject>"` returning the migrated commit                          |
+| Status truth | "The task is blocked on the owner" | An executable non-secret check run in this session; stale tasks closed/corrected in the same change                                                                       |
+
+## Success Criteria
+
+- Work starts only through `ace-overseer work-on` (or the Lab-runtime equivalent), never through ad-hoc manual worktree provisioning.
+- Every status review re-verified pending owner-blocked tasks with an executed check and corrected stale state in the same change.
+- Every pruned worktree/branch had an executed preservation proof; candidates without proof were reported as blocked, not removed.

data/lib/ace/overseer/version.rb

@@ -2,6 +2,6 @@
 
 module Ace
   module Overseer
-    VERSION = "0.15.6"
+    VERSION = "0.16.0"
   end
 end

metadata

@@ -1,13 +1,13 @@
 --- !ruby/object:Gem::Specification
 name: ace-overseer
 version: !ruby/object:Gem::Version
-  version: 0.15.6
+  version: 0.16.0
 platform: ruby
 authors:
 - Michal Czyz
 bindir: exe
 cert_chain: []
-date: 2026-09-05 00:00:00.000000000 Z
+date: 2026-09-22 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: ace-support-cli
@@ -201,6 +201,7 @@ extensions: []
 extra_rdoc_files: []
 files:
 - ".ace-defaults/nav/protocols/skill-sources/ace-overseer.yml"
+- ".ace-defaults/nav/protocols/wfi-sources/ace-overseer.yml"
 - ".ace-defaults/overseer/config.yml"
 - CHANGELOG.md
 - LICENSE