ace-overseer 0.20.2 → 0.21.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 6e3a4a8238f2c6d3918f0969096daf1487799948a6f9f9699fda45ebc3c601e2
-  data.tar.gz: e68abeacd2ac6b7f17366e420146c3906c999be87c8bf1eef66fde2afc026c64
+  metadata.gz: 9a94cecc6258f74a611ffb1091359b4a7e2c10709e8a185019929b1a353111ba
+  data.tar.gz: 50d41733c822af101ef77dc369f4450d5466df43e04a0894b22864328b94ba70
 SHA512:
-  metadata.gz: dfb6ec252b2b70ea209115f2e4ea9dbae5c30e78b4c399daeb23e1a5977f87d312830112a11055d2b2121a776e140dbc57d7a39a49773dc5a6c1faf63293e8bc
-  data.tar.gz: '01385d38011ba32f632622f18931bcbfff19639cbe03c25f70655888b9e6e5041576622bbf73d94be252f21c468742207b8ae780e7345b5ec17a1969a0e08820'
+  metadata.gz: d7b93b7a2444123a261351df666dbbb6ff47b16d1972c5e46230cff1418c87c0982ad7adb7309dac7a1f008348f0593042f32168bec1133557b49cc103ac880c
+  data.tar.gz: a48575ea94be30eeb49f8a0244477b47a3c304328ba2cb6ae71ee2b1a4d0b8d3413c846388a648daa3c875165c2b01d6c18e91ec725f8637cbeef85081d69f03

data/CHANGELOG.md

@@ -7,6 +7,19 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.21.1] - 2026-10-14
+
+### Changed
+
+- Package the coordination-contract role-guide updates in the project-overseer and configure-project workflows: serial preparation and serial integration per delivery candidate, queue-item closure as reconciled merge receipt, release-batch lifecycle with separate publication authority, and overseer-owned close-on-accept for delegated panes and worktabs.
+- Follow the ace-lab 0.6 producer line in the dependency manifest; no code or behavior change (constraint-only correction so the coordinated h8x graph resolves).
+
+## [0.21.0] - 2026-10-12
+
+### Added
+
+- Add the `as-overseer-configure-project` skill and packaged `wfi://overseer/configure-project` workflow for idempotent, customization-preserving delivery supervision adaptation.
+
 ## [0.20.2] - 2026-10-10
 
 ### Fixed

data/docs/handbook.md

@@ -17,6 +17,12 @@ ace-docs:
 - Purpose: orchestrate task worktrees through `work-on`, `status`, and `prune`
 - Execution model: workflow-backed skill invoking `wfi://overseer`
 
+### `as-overseer-configure-project`
+
+- Path: `handbook/skills/as-overseer-configure-project/SKILL.md`
+- Purpose: adapt delivery supervision to project-owned presets, workflows, and decision policy without destructive overwrite
+- Execution model: workflow-backed skill invoking `wfi://overseer/configure-project`
+
 ## Workflows
 
 ### `wfi://overseer`
@@ -25,6 +31,12 @@ ace-docs:
 - Purpose: canonical workflow for working on tasks, checking active worktrees, and safe cleanup
 - 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`.
 
+### `wfi://overseer/configure-project`
+
+- Path: `handbook/workflow-instructions/overseer/configure-project.wf.md`
+- Purpose: resolve and review effective delivery presets, workflows, and decision guides, then apply repeatable project-local adaptation while preserving customization
+- Output: per-asset `CREATED`, `UPDATED`, `KEPT`, or `BLOCKED` evidence plus a repeat-run zero-write check
+
 ## Related Documentation
 
 - [Getting Started](getting-started.md)

data/handbook/skills/as-overseer-configure-project/SKILL.md

@@ -0,0 +1,32 @@
+---
+name: as-overseer-configure-project
+description: Adapt project delivery supervision presets, workflows, and decision guidance without replacing local policy
+# bundle: wfi://overseer/configure-project
+# agent: general-purpose
+user-invocable: true
+allowed-tools:
+  - Bash(ace-nav:*)
+  - Bash(ace-bundle:*)
+  - Read
+  - Write
+  - Edit
+  - Glob
+argument-hint: "[project-root]"
+last_modified: "2026-10-11"
+source: ace-overseer
+integration:
+  targets:
+    - claude
+    - codex
+    - gemini
+    - opencode
+    - pi
+  providers: {}
+skill:
+  kind: workflow
+  execution:
+    workflow: wfi://overseer/configure-project
+---
+
+Load and run `ace-bundle wfi://overseer/configure-project` in the target project, then follow the loaded workflow as the source of truth and execute it end-to-end instead of only summarizing it.
+

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

@@ -0,0 +1,233 @@
+---
+name: overseer-configure-project
+description: Adapt delivery supervision to a project's existing presets, workflows, and decision policy
+allowed-tools: Bash, Read, Write, Edit, Glob
+doc-type: workflow
+title: Configure Project Delivery Supervision
+purpose: Resolve and safely adapt project delivery supervision without replacing project policy or duplicating canonical work.
+ace-docs:
+  last-updated: '2026-10-12'
+  last-checked: '2026-10-12'
+---
+
+# Configure Project Delivery Supervision
+
+## Goal
+
+Make the four ACE delivery-supervision presets usable under the target project's
+own workflow and decision policy while preserving existing customization and
+producing an idempotent, attributable change report.
+
+## Prerequisites
+
+- Run from the target project root and identify that root explicitly before any write.
+- Use the installed `ace-nav`, `ace-bundle`, and `ace-assign` package set that the
+  project will actually run; source-checkout resolution is not installed-runtime proof.
+- Have reviewed project policy for dependency ordering, integration groups, release
+  cuts, demo/production delivery, evidence freshness, and authority ownership.
+- Treat missing policy, authority, transport, or a durable result path as a blocker.
+  This workflow does not grant permissions and does not publish, merge, deploy, or
+  perform host-owned root operations.
+
+## Project Context Loading
+
+Read existing project-owned sources before proposing a change:
+
+- `.ace/assign/presets/` for project-local preset overrides.
+- `.ace/overseer/config.yml` and other existing `.ace/overseer/` configuration.
+- `.ace-handbook/workflow-instructions/` for project workflows.
+- `.ace-handbook/guides/` and registered project guide sources for decision guides.
+- Current task, Assign, review, release, and delivery records that already own work.
+- Repository guidance such as `AGENTS.md`, architecture decisions, and delivery docs.
+
+Resolve rather than infer protocol ownership. Run `ace-nav explain <URI>` followed by
+`ace-nav resolve <URI>` for every applicable `wfi://` workflow and for
+`guide://delivery-supervision`. Load resolved workflow content with `ace-bundle <URI>`.
+If the expected project decision guide uses another registered URI, record that URI
+and use it consistently instead of creating an alias or duplicate guide.
+
+## High-Level Execution Plan
+
+1. Inventory the effective package defaults and all project-owned overrides.
+2. Review the resolved assets against the supervision invariants below.
+3. Plan the smallest path-keyed set of project-local changes.
+4. Apply only justified additions or surgical updates while preserving local policy.
+5. Resolve everything again, repeat the inventory, and report exact outcomes.
+
+## Process Steps
+
+### 1. Establish the effective source inventory
+
+For each baseline preset, resolve the same project-first ownership used by ACE:
+
+- `supervise-delivery`
+- `integrate-batch`
+- `deliver-release`
+- `close-delivery`
+
+An existing `.ace/assign/presets/<name>.yml` is the effective project-local preset.
+Otherwise use the installed `ace-assign` gem's
+`.ace-defaults/assign/presets/<name>.yml`. Use `gem contents ace-assign` when an
+installed package path is needed. Do not create a project copy merely to select the
+unchanged package default.
+
+Inventory applicable project workflows by exact `wfi://` URI and decision guides by
+exact `guide://` URI. For every resolved item record its URI or preset name, resolved
+path, owning source, and content digest. Record unresolved items as blockers rather
+than silently substituting a remembered or similarly named file.
+
+Before making task-related recommendations, reconcile existing implementation and
+delivery tasks. Do not create or duplicate tasks. Delivery records reference producer
+tasks; they never reparent, reopen, or clone producer work.
+
+### 2. Review the effective supervision contract
+
+Review project-local preset overrides, resolved workflows, and decision guides as one
+contract. Preserve stronger project requirements. Require these minimum invariants:
+
+- Worker and implementation-parent terminal behavior remains PR-ready; delivery stays
+  a separate explicit decision scope.
+- One canonical Assign tree and attempt/evidence ledger owns state. No second queue,
+  journal, daemon, timer, or fabricated runtime context is introduced.
+- Integration decisions record the ordered eligible set, selected entry, every
+  deferred entry with reason, actor, timestamp, evidence references, and policy/plan
+  revision. Completion order is never integration order.
+- Dependency, candidate head, target head, evidence, authority, or transport movement
+  triggers a fresh decision. A moved candidate receives fresh relevant tests and an
+  independent review bound to its new exact head.
+- `WAIT(reference, next-check)` requires an existing durable operation reference and
+  exact reconciliation path. Missing provision is `BLOCKED(provision, owner)`.
+  Uncertain effects are reconciled through the original operation and never replayed
+  blindly.
+- Release preparation binds the exact accepted source set, package versions, and
+  artifact digests. Later merges cannot enter an accepted cut silently. Publication
+  remains a separate-authority placeholder.
+- Closure preserves evidence and work, positively proves no surviving writers, keeps
+  producer references and delivery tags discoverable, and closes only accepted scope.
+  Host-owned root effects remain referenced external operations.
+
+If a project decision is absent, do not invent it. Report the precise missing policy,
+the owner needed to decide it, and the assets that remain usable without that choice.
+
+### 3. Build an idempotent change plan
+
+Key every proposed mutation by one target path per logical override. Classify each
+inventory item before editing:
+
+- `KEPT`: the effective default or customization already satisfies the contract.
+- `CREATED`: no project asset exists and authoritative project policy requires a new
+  project-local override.
+- `UPDATED`: an existing project asset needs a minimal, reviewed change.
+- `BLOCKED`: policy, provenance, ownership, authority, or safe merge information is
+  missing.
+
+Never overwrite an existing project customization with a packaged baseline. Preserve
+unknown keys, comments, project-only steps, stronger gates, and established URIs.
+Patch only the necessary fields. If two files claim the same logical override, stop
+and report the collision instead of choosing one or creating a third.
+
+Before every write, retain the path and before digest. If the desired bytes are
+byte-identical, make the operation a no-op. Never append duplicate steps, mappings,
+source registrations, task references, or configuration entries. A second execution
+with unchanged inputs must plan zero writes.
+
+### 4. Apply safe project-local adaptation
+
+Create a project-local preset, workflow, or decision guide only when the project's
+reviewed policy differs from the packaged contract or supplies policy that cannot be
+generic. Use the project's existing registered locations and naming conventions.
+Never edit an installed gem in place.
+
+When updating YAML or Markdown, preserve unrelated content and ordering wherever
+possible. Re-read the complete file immediately after the write. Record the after
+digest and a concise semantic delta. If safe preservation is not possible, leave the
+file unchanged and classify it `BLOCKED` with the collision or ownership reason.
+
+The adaptation may select and specialize supervision behavior, but it does not grant
+permissions, does not publish, and does not exercise merge, deployment, installation,
+or root authority.
+
+Executable population rule (Captain lifecycle audit, 2026-10-12): project
+adaptation must POPULATE an executable project-specific delivery template +
+decision guide -- not prose placeholders -- and ACTUAL service/capability
+checks: every configured service or command is verified to exist and run in
+the project runtime (invoke its status/read-only path and record the
+observed result; a configured-but-nonfunctional entry is `BLOCKED` with the
+observed failure, never shipped as if working). Release and publication
+REUSE the existing canonical skills as the execution mechanisms -- `as-release`,
+`as-release-bump-version`, `as-release-rubygems-publish`,
+`as-github-release-publish` -- the adaptation configures and binds them to
+the project; it never duplicates or re-implements them. Workers stay
+prepare-only (PR-ready terminal); publication remains the separately
+authorized overseer step.
+
+### 5. Verify resolution and repeatability
+
+Repeat the complete source inventory after edits:
+
+1. Run `ace-nav explain` and `ace-nav resolve` for every selected `wfi://` and
+   `guide://` URI.
+2. Load every selected workflow with `ace-bundle` and verify it came from the intended
+   owner.
+3. Re-read all four effective presets and confirm the invariant review still passes.
+4. Re-run the change-plan calculation from current bytes. It must report zero planned
+   writes and no duplicate paths, steps, mappings, registrations, or task references.
+5. Keep genuine unresolved policy or provisioning as `BLOCKED`; idempotence never
+   turns a blocker into assumed success.
+6. For every configured service/command or bound release/publication skill,
+   execute its read-only/status path once and record the observed result as
+   executable evidence; a failed or missing executable is `BLOCKED` with the
+   exact failure and responsible owner.
+
+## Required Report
+
+Return one report with these fields for every inspected or changed asset:
+
+```text
+STATUS: CREATED | UPDATED | KEPT | BLOCKED
+KIND: preset | workflow | decision-guide | configuration
+IDENTITY: exact preset name, protocol URI, or configuration key
+OWNER: package default or project-owned source
+PATH: resolved or intended path
+BEFORE: before digest, MISSING, or UNRESOLVED
+AFTER: after digest, UNCHANGED, or NOT-WRITTEN
+CHANGE: concrete semantic change or reason it was kept
+EVIDENCE: resolution and review references
+BLOCKER: missing policy/provision and responsible owner, or NONE
+```
+
+Finish with counts for `CREATED`, `UPDATED`, `KEPT`, and `BLOCKED`, followed by the
+repeat-run planned-write count. List any remaining authority, transport, publication,
+installation, deployment, or root-operation gates separately from source adaptation.
+
+## Success Criteria
+
+- All four delivery presets resolve from either an intentional project override or the
+  installed package default and pass the supervision-invariant review.
+- Applicable workflows and the project delivery decision guide resolve through their
+  registered protocol sources with intended ownership.
+- Existing project customization and unknown fields remain intact; no file is
+  destructively replaced by a generic baseline.
+- The repeated run produces no duplicate task, step, mapping, source registration,
+  configuration entry, or file, and plans zero writes for unchanged inputs.
+- The report names every concrete change and every unresolved blocker with its owner
+  and evidence; it claims no permission, publication, deployment, installation, or
+  host-owned root effect.
+- The adapted delivery template and decision guide are executable (real steps,
+  bound release/publication skills, verified service/command checks) -- every
+  configured service or command has recorded observed-run evidence, and no
+  release/publication skill is duplicated or re-implemented.
+
+## Error Handling
+
+- **Missing package preset:** report `BLOCKED(package, ace-assign owner)` and do not
+  fabricate a local substitute.
+- **Unresolved workflow or guide:** preserve any existing file, report the failed URI,
+  source registrations inspected, and responsible project/package owner.
+- **Conflicting project overrides:** make no write; report every competing path and
+  require the project owner to choose the canonical source.
+- **Unsafe merge with customization:** keep the current file byte-for-byte and report
+  the exact invariant gap and proposed minimal delta.
+- **Uncertain external effect:** retain the original operation reference and reconcile
+  it through its owner; never repeat the effect as part of configuration.
+

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

@@ -5,8 +5,8 @@ doc-type: workflow
 title: Coordinate Project Work
 purpose: Canonical project-overseer role charter for scoped ACE orchestration.
 ace-docs:
-  last-updated: '2026-10-07'
-  last-checked: '2026-10-07'
+  last-updated: '2026-10-14'
+  last-checked: '2026-10-14'
 ---
 # Coordinate Project Work
 
@@ -50,6 +50,14 @@ the actual selected project. Do not treat remembered status as current evidence.
    effects. After a lost reply, inspect those identities without repeating the
    launch. Automatic selection advances only after attributable zero-effect
    refusal before registration; explicit mapping selection never substitutes.
+   Launch defaults (Captain, 2026-10-12): workers run Pi `zai/glm-5.3-flash:high`;
+   independent reviewers run Pi `zai/glm-5.3:high` under their own separate agent
+   identity. Codex or any other harness is NOT a default or silent fallback and
+   requires an explicit Captain exception. Selection precedence: Captain policy
+   defaults > project launch overrides > explicit Captain exception. Every
+   dispatch receipt records the ACTUAL harness, provider/model (incl. thinking
+   level) and agent/pane/session; a documented default without a matching actual
+   launch violates this policy.
 3. Keep conversation available while delegates work. On each wake, inspect the
    task queue, canonical execution evidence and scoped HITL proposal/callback
    state. Report unavailable observations and deferred resolution explicitly;
@@ -77,6 +85,70 @@ the actual selected project. Do not treat remembered status as current evidence.
    scope, missing evidence and requested decision. Preserve failed callbacks;
    unavailable delivery is not a policy refusal or successful handoff.
 
+## Integration Coordination Contract
+
+Every integration invocation — native integrate command, service call or
+assignment integration step — resolves FRESH repository, PR, candidate exact
+head, target base/head, review/test evidence, dependencies and the authorized
+executor before any mutation, and rechecks target/head immediately before the
+mutation. A detected race invalidates eligibility for that invocation.
+
+If the target (current main) is NOT an ancestor of the candidate head, the
+integration MUST NOT merge and MUST NOT silently rewrite: it returns an
+actionable typed `needs-rebase` outcome to the queue owner. The queue owner
+then delegates `wfi://git/rebase` (as-git-rebase, including CHANGELOG
+preservation) in the candidate's ISOLATED worktree, obtains new exact-head
+checks and an independent review of the resulting exact head, updates the PR,
+verifies remote candidate identity and resubmits. A common old base does NOT
+make sibling heads sequentially fast-forwardable.
+
+The low-level privileged integrator ENFORCES gates and returns typed outcomes
+(`merged` / `needs-rebase` / `blocked` / `uncertain`); it never authors,
+rebases or reviews its own candidate. Relay alone is not execution — the queue
+owner monitors until receipt and continuation. An `uncertain` outcome triggers
+reconciliation against the original durable reference, never blind retry.
+
+The project overseer continuously owns and watches the integration queue.
+States `ready` / `needs-rebase` / `reviewing` / `integrating` / `merged` /
+`blocked` / `uncertain` reconcile against actual forge/process receipts; a
+persisted queue adopts on restart without duplicate execution; worker PR-ready
+remains distinct from delivery done. Use the existing goal/wake/watch
+primitives — no new heartbeat service or alternate scheduler.
+
+Integration is serial in PREPARATION as well as in effect — not merely a
+serial merge. The accepted receipt for one candidate causes preparation of
+ONLY the next selected candidate — never a mass rebase of the remaining
+queue. Each candidate, on its turn, runs the full cycle: resolve fresh
+target main; delegate `wfi://git/rebase` in that candidate's isolated
+worktree IF the target moved; run the applicable checks; obtain an
+INDEPENDENT EXPLICIT review of the resulting exact head (patch identity may
+support a short delta review but never substitutes the explicit independent
+head approval); verify the remote PR head/base; issue ONE scoped integrator
+request; wait/reconcile the actual integration receipt; refresh main; then
+select and prepare ONLY the next candidate. Queued later PRs keep their
+existing branches and heads untouched until their turn, and prior batch work
+is never rolled back or reset.
+
+Pane and worktab lifecycle is OVERSEER-OWNED cleanup duty — not user or host
+babysitting: the project overseer cleans up its own worker/reviewer panes and
+worktabs as a lifecycle duty; the Lab coordinator owns only its own
+coordination panes/routes. CLOSE-ON-ACCEPT: close an accepted work pane — and
+close the tab when that was its last pane; keep at most 4 panes per tab; and
+never hold an idle tab merely reserved for pending work. The closure gate
+binds to identity and ACTUAL state, never to visual idleness: reconcile the
+exact pane/session/assignment/attempt identity and the actual process state;
+close only after the result is ACCEPTED and the work/evidence is durably
+preserved; never close an active or uncertain attempt merely because it looks
+idle. Review-completed MAY allow pane closure while the PR still waits for
+merge — the review record persists; WORKTREE cleanup is SEPARATE and happens
+only when the preservation/delivery criteria are met. Each wake and restart
+runs a BOUNDED reconcile pass that reports orphan/stale pane/session IDs — it
+never blind-closes.
+
+Hard prohibitions: never push directly to main; never switch the canonical
+checkout to a topic branch; never reuse a stale review as approval for a
+different or moved head.
+
 ## Shared Decision and Responsiveness Contract
 
 Confirmed Hermes delivery starts the sixteen-hour proposal window. Only the

data/lib/ace/overseer/version.rb

@@ -2,6 +2,6 @@
 
 module Ace
   module Overseer
-    VERSION = "0.20.2"
+    VERSION = "0.21.1"
   end
 end

metadata

@@ -1,13 +1,13 @@
 --- !ruby/object:Gem::Specification
 name: ace-overseer
 version: !ruby/object:Gem::Version
-  version: 0.20.2
+  version: 0.21.1
 platform: ruby
 authors:
 - Michal Czyz
 bindir: exe
 cert_chain: []
-date: 2026-10-10 00:00:00.000000000 Z
+date: 2026-10-14 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: ace-support-cli
@@ -71,14 +71,14 @@ dependencies:
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: 0.66.1
+        version: '0.67'
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: 0.66.1
+        version: '0.67'
 - !ruby/object:Gem::Dependency
   name: ace-git
   requirement: !ruby/object:Gem::Requirement
@@ -169,14 +169,14 @@ dependencies:
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: 0.5.1
+        version: '0.6'
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: 0.5.1
+        version: '0.6'
 - !ruby/object:Gem::Dependency
   name: ace-review
   requirement: !ruby/object:Gem::Requirement
@@ -271,8 +271,10 @@ files:
 - docs/handbook.md
 - docs/usage.md
 - exe/ace-overseer
+- handbook/skills/as-overseer-configure-project/SKILL.md
 - handbook/skills/as-overseer/SKILL.md
 - handbook/workflow-instructions/overseer.wf.md
+- handbook/workflow-instructions/overseer/configure-project.wf.md
 - handbook/workflow-instructions/roles/lab-coordinator.wf.md
 - handbook/workflow-instructions/roles/project-overseer.wf.md
 - handbook/workflow-instructions/roles/second-commander.wf.md