ace-overseer 0.15.6 → 0.17.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: f64d7b81728d6636ebc933e6c30f119bc6aba514a8652562f393e5ab7f3a5540
-  data.tar.gz: abdc381e8d76669ba78bb871280704efd979a62df58aeecc703d912cd99a5275
+  metadata.gz: 860e9ff0d0d664c563c1fa9139d5f0d18b2e4c869239424e881dd2a018ad12bc
+  data.tar.gz: 55c0694f24f3a4d8ea9492df5f552e42fb2171cc75bd848988b642171f1b1e3c
 SHA512:
-  metadata.gz: d079fea537a3941ecb55459d52793bf1a6a5d55e411e05dabc4154561536de0cdda61c4b4a8fb6c4fc10170f19fd255e0b66a1da4d0823d332e62aac8511d9d2
-  data.tar.gz: a718d278ba5223bc08589f6627b6fb72f92d433703b7ef69c83a4cc8f06182afc79241754a383f743f5c98b690ce77bbe250c3cd04d97b9a8e5c931e86b38146
+  metadata.gz: 6bb2d12eb03983cc5b10f9b71f72fea46c25c39e6394e02060a9e505767400d2a57a1da1794140235a9e1b6f0f01fa01f89287755b5d7af6490497312e1375ed
+  data.tar.gz: 830f8f444002616d28121d391b95d85cc50a07c18b6bf0f63a4e7186d332cb7a118d7b3ef059e7d11d24e7e37f37a2305eeb15bcda5a63ecc2fc42469dd5f204

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

@@ -7,12 +7,22 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.17.0] - 2026-09-29
+
 ### Added
 - Added an explicit Lab runtime adapter for listing projects and agents, preparing and dispatching Works, forwarding prompts over stdin, starting exact-head reviews, and stopping workers.
+- Added installed-consumer probe coverage: the suite builds the current gem artifacts, installs them into an isolated consumer environment (fresh gem home, unrelated cwd, sanitized HOME), and proves `ace-nav resolve wfi://overseer` and `ace-bundle wfi://overseer` succeed from packaged content only, with a registration-removal fixture proving the probe detects masking.
 
 ### Changed
 - 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.
+- Strengthened the overseer prune-safety contract: migrated-work preservation now requires a declared, verified destination plus tree/artifact or patch equivalence (the subject-only successor search is gone), plus a positive executed no-active-writer check from overseer/assignment/Lab status; ambiguity preserves.
+
 
+## [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
 

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

@@ -1,16 +1,178 @@
 ---
+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-28'
+  last-checked: '2026-09-28'
 ---
 
 # 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 plus an executed no-active-writer check** for every
+candidate:
+
+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), preservation requires a **declared, verified destination**
+   plus content equivalence. A matching commit subject is never sufficient
+   proof:
+
+   1. Declare the destination concretely: successor repository plus
+      branch/PR/commit that received the work.
+   2. Verify the destination actually accepted the work, executed in this
+      session:
+
+      ```bash
+      git -C <successor-repo> merge-base --is-ancestor <dest-ref> <dest-branch>
+      ```
+
+      rc=0 proves the destination landed on the declared branch (or read
+      the merged/accepted state from the forge hosting the PR).
+
+   3. Prove the destination carries the same work by content, not by
+      name. Pass with exactly one of:
+
+      - Tree/artifact equivalence -- the squashed result is the same
+        content:
+
+          ```bash
+          test "$(git -C <successor-repo> rev-parse '<dest-ref>^{tree}')" \
+            = "$(git rev-parse '<work-head>^{tree}')"
+          ```
+
+      - Patch equivalence -- the same changes, compared inside the
+        successor repository. Fetch the source proof refs first and
+        range-diff with separate source and destination bases:
+
+          ```bash
+          git -C <successor-repo> fetch <source-repo> <source-base> <work-head>
+          git -C <successor-repo> range-diff \
+            <source-base>...<work-head> <dest-base>...<dest-ref>
+          ```
+
+          with no substantive differences; or diff the normalized patches
+          (`git show --format=` output of each side) and require an empty
+          diff.
+
+   4. Ambiguity preserves: conflicting hashes, an unverifiable destination,
+      or a failed equivalence check means no proof -- block the prune per
+      step 5.
+
+3. Prove no active writer before destruction, executed in this session
+   against the authoritative lifecycle state:
+
+   ```bash
+   ace-overseer status --format json
+   ```
+
+   For assignment-backed candidates also check `ace-assign status`; for Lab
+   runtime candidates check `ace-overseer status --runtime lab`. A running
+   assignment, an in-flight Lab work, or any unaccounted writer blocks the
+   prune. Missing or unreadable lifecycle state counts as an active writer
+   -- preserve.
+
+4. A described or remembered proof is never sufficient -- run the commands
+   and observe the results in this session.
+
+5. Any commit without a proven copy, any failed or ambiguous equivalence,
+   or any active-writer evidence **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.
+   Preserve on ambiguity.
+
+## Non-Negotiable Contracts Summary
+
+| Contract     | Claim | Executed proof |
+|--------------|-------|----------------|
+| Prune safety | "The work is preserved and nothing is actively writing" | `git merge-base --is-ancestor <work-head> <base>` (rc=0), or verified destination + tree/artifact or patch equivalence; plus `ace-overseer status --format json` (assignment/Lab status where applicable) showing no active writer |
+| 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 (ancestor containment, or a verified destination with tree/artifact or patch equivalence) and an executed no-active-writer check; candidates without complete 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.17.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.17.0
 platform: ruby
 authors:
 - Michal Czyz
 bindir: exe
 cert_chain: []
-date: 2026-09-05 00:00:00.000000000 Z
+date: 2026-09-29 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