ace-coworker 0.6.1 → 0.7.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 6901776c6bcef11b2bfb48ddaeb2377dd830f352d01c79bddc59254a4f799849
-  data.tar.gz: 604583cbbb6eab225faccd01025cc5efdce6cad789bc7faca87091713cdf7a7b
+  metadata.gz: 7b1ca4d493124efc790ec4f9e9ebe719b341906f45d0f8913c1005bb2ff86a94
+  data.tar.gz: adeebb47b7350576f6aabb79974efd1e8683869b8623d5f6b84fbb8d5f86abb9
 SHA512:
-  metadata.gz: be41301547584600fba77e414d603bed84caa025bdae72601644bbbd6b62569167ed72cb20da61ecb45c8c6deeefcb5367beb11f5914f1e3471f2180d847bea6
-  data.tar.gz: 8e29e8818c437ae80ffd3de61976dafe166db7c215d47003176e3e5ae43ea995d4db969aa8e7168be44c8207db3a93a41e1052760d9b6be6f6a49eed184dbfa4
+  metadata.gz: c8e78949c6ca07838eb12e7580704aedf918f59436a1fcd5354da812308c442e8b4eff4a42fb75334af231d04206ad511e4ce7d48a3fcc9299155f098d61de98
+  data.tar.gz: 60d8735e3fbb344584e9ded3d27dfac0cd32d0f34d5a46f305342dcab3b8715c361bd88e2ef5888672a1a786a3685eb0d19c0a70172c0ec6a6252571c3c65194

data/.ace-defaults/coworker/roles/second-captain.yml

@@ -0,0 +1,18 @@
+---
+# Second Captain role preset (shipped gem defaults, overridable per project
+# via .ace/coworker/roles/second-captain.yml). Advisory ONLY: delegated per
+# HITL case to propose a marked answer with rationale and grounds (task
+# 8xs.t.pu0.b). Never answers in the human's name, never approves or gates
+# work, never touches secret/OTP cases.
+name: second-captain
+description: Advisory Second Captain; proposes one marked answer with rationale and grounds into the exact HITL case and stops — never a human decision, approval, or gate
+instructions: wfi://coworker/second-captain
+start_prompt: >-
+  Work as the {{role}} on case {{case}} (task {{task}}): read the exact HITL
+  case and its referenced evidence, write one marked suggestion with
+  rationale and grounds through assignment {{assignment}}, reporting to the
+  overseer at {{overseer}} — then stop.
+reporting:
+  channel: hitl
+errors:
+  on_failure: report

data/CHANGELOG.md

@@ -5,7 +5,37 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
-## [Unreleased]
+## [0.7.0] - 2026-10-30
+
+### Fixed (review rounds 3/3b)
+
+- The integration gate rejects anonymous formal approvals (empty approver);
+  `commission --hitl-case CASE_ID` renders `{{case}}` for per-case presets.
+
+### Added
+
+- `second-captain` advisory role preset + `wfi://coworker/second-captain`
+  workflow (task 8xs.t.pu0.b): delegated per HITL case to write one marked
+  suggestion and stop; never answers in the human's name, approves, gates
+  work, or touches secret cases.
+
+### Changed
+
+- Integration gate binds ALL evidence to the exact candidate head (task
+  8xs.t.pu0.8): test evidence must carry the head it covered (bare
+  executed/passed blocks; a different tested head is stale evidence), and the
+  formal approval — `--approval-head`/`--approval-by` — must name the same
+  head and come from an account other than the author. The integrator
+  re-reads the HEAD immediately before merging through the merge adapter's
+  expected-head condition, so the gate-to-merge race refuses a stale
+  candidate. CI stays advisory.
+
+## [0.6.2] - 2026-10-23
+
+### Added
+
+- Formal reviewer-owned, exact-head provider approval and read-only approval verification through the forge-neutral review flow; comments do not substitute for approval.
+
 
 ## [0.6.1] - 2026-10-20
 

data/README.md

@@ -23,8 +23,9 @@ ace-coworker resume [--dry-run]                # Resume interrupted work in this
 ace-coworker prepare --task REF --roles worker,reviewer [--to ADDR] [--dry-run]
 ace-coworker roles                             # List role presets (gem + project)
 ace-coworker commission --role worker --task REF --assignment ID --overseer ADDR
+                         [--hitl-case CASE_ID]  # renders {{case}} in per-case presets
 ace-coworker gate --candidate-head SHA --review-head SHA --review-verdict accept
-                 --tests executed,passed --dep LEAF=integrated
+                 --tests executed,passed --tests-head SHA --dep LEAF=integrated
 ```
 
 - `prepare` — the planner side: accept a preparation commission (task +

data/docs/usage.md

@@ -171,28 +171,42 @@ errors, non-zero exit).
 ```
 ace-coworker gate --review-verdict accept|continue|escalate
                   [--candidate-head SHA] [--review-head SHA]
-                  [--tests executed,passed] [--dep LEAF=integrated|missing ...]
+                  [--tests executed,passed] [--tests-head SHA]
+                  [--approval-head SHA --approval-by ACCOUNT] [--author ACCOUNT]
+                  [--dep LEAF=integrated|missing ...]
                   [--format table|json] [-q] [-d]
 ```
 
-The integrator role's pre-merge gate (8xg.t.sbz.4.3): a pure, stateless
-evaluation of the four project-defined checks. `--candidate-head` is the
-current candidate head (omit it when genuinely unknown - the gate then
-blocks on the missing evidence instead of guessing); `--review-head` is the
-candidate head the independent review verdict covers; `--tests` takes the
-`executed,passed` evidence flags (any other token is an error, not
-silent missing evidence); each `--dep NAME=integrated|missing` pair
-states one dependency leaf (`missing` or any other value = not
-integrated; the pair must contain `=`, and repeating a name is an
-error). Empty or omitted `--dep` means the caller enumerated no
-dependencies - the gate trusts the caller's dependency enumeration.
-Prints `ready` or `blocked` with per-check reasons (dependencies, candidate
-drift, review freshness/verdict, executed+passing tests). `blocked` is a
-legitimate gate outcome (exit 0) - the role withholds the merge and
-escalates; only malformed input (an invalid `--dep` pair, a duplicate
-`--dep` name, or an invalid `--tests` token) fails with a non-zero exit.
-Heads are recorded and compared as full lowercase SHAs. Nothing is persisted and no git operation is performed: the
-gate decides readiness only.
+The integrator role's pre-merge gate (8xg.t.sbz.4.3; HEAD binding of
+evidence per 8xs.t.pu0.8): a pure, stateless evaluation of the
+project-defined checks. `--candidate-head` is the current candidate head
+(omit it when genuinely unknown - the gate then blocks on the missing
+evidence instead of guessing); `--review-head` is the candidate head the
+independent review verdict covers; `--tests-head` is the head the
+executed test run covered — test evidence without a head, or bound to a
+different head, BLOCKS the merge (a code change or rebase after the tests
+invalidates that basis); `--approval-head`/`--approval-by` supply the
+formal approval's head and account for lanes that require one (an
+approval bound to another head blocks, and an approval by the AUTHOR's
+own account blocks — the formal approver is a different configured lane
+account); each `--dep NAME=integrated|missing` pair states one
+dependency leaf (`missing` or any other value = not integrated; the pair
+must contain `=`, and repeating a name is an error). Empty or omitted
+`--dep` means the caller enumerated no dependencies - the gate trusts the
+caller's dependency enumeration. Prints `ready` or `blocked` with
+per-check reasons (dependencies, candidate drift, review
+freshness/verdict, executed+passing+HEAD-bound tests, formal approval).
+`blocked` is a legitimate gate outcome (exit 0) - the role withholds the
+merge and escalates; only malformed input (an invalid `--dep` pair, a
+duplicate `--dep` name, or an invalid `--tests` token) fails with a
+non-zero exit. Heads are recorded and compared as full lowercase SHAs.
+Nothing is persisted and no git operation is performed: the gate decides
+readiness only — the integrator reads the current HEAD immediately
+before merging and passes it as the merge adapter's expected-head
+condition, so a candidate that moves between gate and merge is refused
+by the adapter (the race never merges a stale candidate). CI status is
+advisory (Captain's decision): a red CI does not block a merge backed by
+executed passing tests and an accepting independent review.
 
 ### `ace-coworker commission`
 
@@ -562,3 +576,14 @@ would-be outcome.
 - Reporting via `ace-hitl` and resume-after-interruption ship with
   `ace-coworker` 0.4.0+; role presets resolve their `wfi://` instruction
   sources through `ace-nav` (runtime dependency since 0.5.0).
+
+
+For commissioned PR work the reviewer publishes formal approval only after the
+accepted review-round verdict and executed tests, using `ace-git pr approve`.
+Its receipt stays with the existing report. The integrator verifies that receipt
+against read-only `ace-git pr approval` and the current candidate before the
+existing integration gate. A comment, local verdict or draft-ready transition
+does not substitute for provider approval. Accounts and credentials come from
+deployment, independently of the role preset; no identity switching or token
+borrowing is performed by coworker. Missing permission or uncertain publication
+blocks successful integration handoff.

data/handbook/workflow-instructions/coworker/integrator.wf.md

@@ -82,18 +82,36 @@ the exact candidate head. Otherwise WITHHOLD the merge and report/escalate.
 3. **Evaluate the gate (deterministic).**
    - `ace-coworker gate --candidate-head <sha> --review-head <sha>
      --review-verdict accept|continue|escalate --tests executed,passed
-     --dep <leaf>=integrated --dep <leaf>=missing`
+     --tests-head <sha> --dep <leaf>=integrated --dep <leaf>=missing`
      (repeat `--dep` per dependency; omit `--candidate-head`/`--review-head`
      when genuinely unknown so the gate blocks on the missing evidence).
+     `--tests-head` is REQUIRED whenever test evidence is supplied: it is
+     the candidate head the executed test run covered, and the gate
+     blocks on stale test evidence without it.
    - The gate (`Ace::Coworker::Atoms::IntegrationGate`) is pure: it returns
      `ready` or `blocked` with per-check reasons (dependencies, candidate
-     drift, review freshness/verdict, executed+passing tests). `blocked` is a
+     drift, review freshness/verdict, executed+passing tests bound to the
+     tested head). `blocked` is a
      legitimate outcome with exit 0; only invalid input fails the command.
    - A candidate change after the review (candidate head != reviewed head)
      invalidates the review: the gate reports a stale review even when the
      verdict says accept.
 
-4. **Merge only a ready candidate.**
+4. **Consume formal approval, then merge only a ready candidate.**
+   - For PR integration, read the reviewer's receipt from the existing report
+     and verify current provider evidence without minting another approval:
+     `ace-git pr approval PR --expected-head SHA --review-id REVIEW_ID
+     --server SERVER --format json` (or the retained `--default-server`). Here
+     REVIEW_ID is the numeric provider review ID, not the publication correlation.
+   - Require effective `approved` evidence and compare repository, PR, full head,
+     reviewer identity, correlation and evidence SHA256 with the accepted
+     reviewer report/receipt. The authenticated reviewer must differ from the
+     PR author. A stale/dismissed/nonofficial review, comment, unavailable
+     evidence or missing account permissions withholds integration. Return to
+     the reviewer/overseer; do not issue approval on the reviewer's behalf,
+     copy their token or bypass branch protection. This read does not replace
+     the dependency/test/current-head gate or authorize a merge by itself.
+
    - Verdict `ready`: perform the project-defined integration with the
      existing tools (`git` / `ace-git`, scoped to the commissioned paths;
      never force-push; fetch first and resolve conflicts explicitly).

data/handbook/workflow-instructions/coworker/reviewer.wf.md

@@ -162,7 +162,27 @@ product decision is escalated to the overseer instead.
      outcome from the ace-assign verdict and refuses a forced success on an
      incomplete assignment - the tool floor, not a courtesy.
 
-8. **Record and hand off.**
+8. **Publish formal approval, then hand off.**
+   - For a commissioned PR review, only AFTER the review-round verdict is
+     `accept`, required executed tests pass, and the accepted report binds the
+     current full head, publish through the configured reviewer account:
+     `ace-git pr approve PR --expected-head SHA --body-file REVIEW_REPORT
+     --correlation REVIEW_ID --server SERVER --format json` (or the retained
+     `--default-server` selection). Keep the report and returned receipt in the
+     existing task/review/assignment artifacts. Use one stable REVIEW_ID for
+     this repository/PR publication; changed report/head needs a new publication.
+   - A comment, local acceptance or `pr ready` is not formal approval. Confirm
+     the receipt's exact repo/PR/head/reviewer/evidence digest and effective
+     approval. Missing permission, unsupported capability or unknown outcome
+     blocks successful integration handoff; report the concrete cause via the
+     existing HITL/report path. Resume by reconciling the same publication,
+     never blindly repeating a POST or switching credentials.
+   - Reviewer purpose and provider permissions are independent: deployment
+     selects the OS/provider identity. Never borrow worker/admin credentials;
+     the PR author cannot approve their own PR. Local-only reviews have no
+     remote approval to publish and must not claim one.
+
+8a. **Record and hand off.**
    - `ace-coworker report` writes the durable record
      (`<task>/coworker/<assignment>.md`) and delivers the HITL report.
    - The final report names: the exact candidate head, executed checks,
@@ -209,3 +229,12 @@ and reported. Anything less is an error outcome with the cause named.
   `.ace-local/review/` to ace-review, `.ace-local/hitl/` to ace-hitl.
 - Inside the ACE repository itself, invoke every tool as `bin/ace-*` (the
   binstubs pin the checkout's bundle).
+
+
+Deployment must provide a dedicated automation reviewer identity and one writer
+per actor/repository/PR before formal publication. Missing evidence of that
+mapping/ownership blocks live use; a role name grants no account permission.
+Do not share that identity with manual clients or another host writer. Preserve
+and report unrelated pending reviews/comments instead of publishing over them.
+Resume only when the provider's path preserves the accepted commit/content;
+unsafe or unsupported pending recovery remains blocked with retained evidence.

data/handbook/workflow-instructions/coworker/second-captain.wf.md

@@ -0,0 +1,88 @@
+---
+name: coworker-second-captain
+description: Second Captain advisory coworker role — propose an answer with rationale and grounds into the exact HITL case; never answer in the human's name, never approve, never gate work
+allowed-tools: Bash, Read
+doc-type: workflow
+title: Second Captain Workflow
+purpose: Bind the advisory role's behavior: one marked suggestion per case/revision with rationale and grounds in the same HITL thread, non-blocking on delivery, discarded when the human answered first, excluded from secret cases.
+ace-docs:
+  last-updated: '2026-10-30'
+  last-checked: '2026-10-30'
+---
+# Second Captain Workflow
+
+## Goal
+
+You are the Second Captain: an advisory coworker delegated for ONE HITL
+case (task 8xs.t.pu0.b). You draft a proposed answer so the Captain sees a
+marked suggestion with its reasoning in the same thread. You are an agent,
+not a second human: you never answer in the Captain's name, never approve
+or release gated work, and your suggestion is never treated as human
+consent.
+
+## Instructions
+
+Run the loaded workflow as the source of truth and execute it end-to-end
+instead of only summarizing it.
+
+### 1) Read the exact case
+
+Open the delegated case file. Work ONLY from the case content and the
+grounds it references (task/assignment/report evidence). If the grounds are
+insufficient for a defensible proposal, say so in the suggestion — never
+fabricate precedent or confidence.
+
+### 2) Learn from every real decision
+
+When the Captain answers a case that carried your suggestion, compare the
+decision with your proposal and write ONE lesson at that case (task
+8xs.t.pu0.c):
+
+```bash
+ace-hitl lesson CASE_ID --by second-captain \
+  --relation accepted|rejected|modified \
+  --takeaway "what the next suggestion should learn"
+```
+
+A case without your suggestion has NOTHING to compare — never fabricate
+agreement. Identical reprocessing is a no-op. The lesson cites the exact
+question/suggestion/decision revisions; it never overwrites them and never
+changes the decision's author.
+
+### 3) Ground the next suggestion in citable history
+
+Before proposing, read the decision history available to THIS project
+(`ace-hitl history`): answered, non-secret cases with their suggestions,
+decisions and lessons. Cite the real case ids you relied on and note the
+limits of the similarity; a NEWER explicit Captain correction outranks an
+older suggestion. When you have no applicable precedent, SAY SO — a visible
+lack of grounds is honest, a fabricated precedent is not. Secret/OTP values
+never enter your proposals, takeaways, or citations.
+
+### 4) Write the suggestion into the case
+
+```bash
+ace-hitl suggest CASE_ID --by second-captain \
+  --text "proposed answer" \
+  --rationale "why this is the defensible choice — cite case ids you relied on" \
+  --refs task:8xs.t.pu0,assignment:job-7
+```
+
+One suggestion per case/revision; an identical repeat is a no-op. The
+suggestion lands as its own marked section in the case — never as the
+Answer.
+
+### 5) Stop
+
+Your assignment ends with the written suggestion. Do not wake the Captain,
+do not open a new case, do not apply or await the answer.
+
+## Boundaries
+
+- A question marked `secret: true` (e.g. OTP) is NEVER delegated to you; if
+  you receive one, report the mismatch and stop.
+- If the Captain already answered, DISCARD your late proposal, mark your
+  assignment complete, and do not notify anyone — the human decision stands
+  and needs no second approval.
+- Your advisory rights cover reading the case and its referenced evidence
+  only — no merges, no releases, no token use.

data/lib/ace/coworker/atoms/config_schema.rb

@@ -52,6 +52,7 @@ module Ace
             "task" => str(raw["task"]),
             "assignment" => str(raw["assignment"]),
             "overseer" => str(raw["overseer"]),
+            "case" => str(raw["case"]),
             "reporting" => {"channel" => nested_str(raw, "reporting", "channel").empty? ? "hitl" : nested_str(raw, "reporting", "channel")},
             "errors" => {"on_failure" => nested_str(raw, "errors", "on_failure").empty? ? "report" : nested_str(raw, "errors", "on_failure")}
           }.compact

data/lib/ace/coworker/atoms/integration_gate.rb

@@ -3,26 +3,39 @@
 module Ace
   module Coworker
     module Atoms
-      # Pure pre-merge integration gate (8xg.t.sbz.4.3 / contract): the
-      # integrator merges only a candidate whose (a) dependencies are
-      # integrated predecessors, (b) current head matches the reviewed
-      # head (no drift), (c) tests were executed and passed, and (d) a
-      # fresh independent review verdict accepts the EXACT candidate
-      # head. Any unknown or contradictory fact is a blocking reason -
-      # uncertainty must be verified against the real worktree/reports,
-      # never guessed or retried blind. Explicit :blocked outcome with
-      # reasons, never an exception. No IO, no writes, no merges: the
-      # gate decides readiness only; the role drives git/ace-git.
+      # Pure pre-merge integration gate (8xg.t.sbz.4.3 / contract, HEAD
+      # binding per 8xs.t.pu0.8): the integrator merges only a candidate
+      # whose (a) dependencies are integrated predecessors, (b) current
+      # head matches the reviewed head (no drift), (c) tests were
+      # executed, passed, AND BOUND TO THE EXACT CANDIDATE HEAD (bare
+      # executed/passed without a head covers nothing), (d) a fresh
+      # independent review verdict accepts the EXACT candidate head, and
+      # (e) the formal approval — when required — also names this head
+      # and was given by a NAMED, DIFFERENT account than the author (an
+      # anonymous approval proves nothing). Any
+      # unknown or contradictory fact is a blocking reason - a code
+      # change or rebase after tests or review invalidates those bases
+      # for the old candidate; uncertainty must be verified against the
+      # real worktree/reports, never guessed or retried blind. Explicit
+      # :blocked outcome with reasons, never an exception. No IO, no
+      # writes, no merges: the gate decides readiness only; the role
+      # drives git/ace-git (the merge adapter's expected-head condition
+      # refuses a candidate that moved between gate and merge).
       module IntegrationGate
         ACCEPT_VERDICTS = %w[accept].freeze
 
         # @param input [Hash] string-keyed facts:
         #   "candidate_head" => String (current head of the candidate)
         #   "review" => {"head" => String reviewed head, "verdict" => String}
-        #   "tests" => {"executed" => bool, "passed" => bool}
+        #   "tests" => {"executed" => bool, "passed" => bool,
+        #               "head" => String head the test run covered}
+        #   "approval" => {"head" => String, "by" => String account} (a
+        #     nil/empty approval skips the formal-approval check; lanes
+        #     that require it must supply it)
+        #   "author" => String candidate author account (optional)
         #   "dependencies" => {name => bool (integrated predecessor)}
         # @return [Hash] {verdict: :ready | :blocked, reasons: [String],
-        #   failed_checks: [:dependencies|:candidate|:review|:tests|:input]}
+        #   failed_checks: [:dependencies|:candidate|:review|:tests|:approval|:input]}
         def self.evaluate(input)
           unless input.is_a?(Hash) && input.keys.all? { |k| k.is_a?(String) }
             return {verdict: :blocked,
@@ -70,6 +83,40 @@ module Ace
             reasons << "tests not passing: executed tests failed or their outcome is unknown"
             failed << :tests
           end
+          tests_head = str(tests["head"])
+          if tests_head.empty?
+            reasons << "test evidence not bound to a candidate head: executed/passed covers no " \
+              "verifiable candidate - re-run the tests on the current head and record it"
+            failed << :tests
+          elsif !candidate_head.empty? && tests_head.downcase != candidate_head.downcase
+            reasons << "stale test evidence: candidate #{candidate_head} is not the tested head #{tests_head}"
+            failed << :tests
+          end
+
+          approval = hash(input["approval"])
+          unless approval.empty?
+            approval_head = str(approval["head"])
+            approved_by = str(approval["by"])
+            if approval_head.empty?
+              reasons << "formal approval not bound to a candidate head: the approval covers no " \
+                "verifiable candidate"
+              failed << :approval
+            elsif !candidate_head.empty? && approval_head.downcase != candidate_head.downcase
+              reasons << "stale formal approval: candidate #{candidate_head} is not the approved " \
+                "head #{approval_head}"
+              failed << :approval
+            end
+            author = str(input["author"])
+            if approved_by.empty?
+              reasons << "formal approval is anonymous: no approving account is recorded — " \
+                "the author≠approver guarantee is vacuous; record the approving lane account"
+              failed << :approval
+            elsif !author.empty? && approved_by.downcase == author.downcase
+              reasons << "formal approval by the author's own account '#{approved_by}': the formal " \
+                "approver must be a different configured lane account"
+              failed << :approval
+            end
+          end
 
           {verdict: reasons.empty? ? :ready : :blocked,
            reasons: reasons, failed_checks: failed.uniq}

data/lib/ace/coworker/atoms/prompt_template.rb

@@ -7,7 +7,9 @@ module Ace
       # placeholders from a context hash; unknown placeholders stay literal.
       # No IO.
       class PromptTemplate
-        PLACEHOLDERS = %w[task assignment role overseer].freeze
+        # `case` carries the HITL case id for per-case delegation roles
+        # (e.g. second-captain); roles without it simply never reference it.
+        PLACEHOLDERS = %w[task assignment role overseer case].freeze
         PLACEHOLDER_PATTERN = /\{\{(#{PLACEHOLDERS.map { |p| Regexp.escape(p) }.join('|')})\}\}/.freeze
 
         # @param template [String] preset start_prompt with {{placeholders}}

data/lib/ace/coworker/cli/commands/commission.rb

@@ -15,6 +15,7 @@ module Ace
           option :task, desc: "Task reference that must resolve in this worktree (required)"
           option :assignment, desc: "Assignment id pinned to the role (required)"
           option :overseer, desc: "Overseer reporting address (required)"
+          option :"hitl-case", desc: "HITL case id for per-case delegation roles (renders the preset's {{case}})"
           option :"start-prompt", desc: "Literal start prompt overriding the preset template"
           option :config, desc: "Config path (default from cascade: .ace-local/coworker/config.yml)"
           option :force, type: :boolean, default: false, desc: "Allow overwriting an existing config"
@@ -47,7 +48,7 @@ module Ace
             orchestrator = @orchestrator || build_orchestrator(options[:config])
             result = orchestrator.call(
               role: role, task: task, assignment: assignment, overseer: overseer,
-              start_prompt: options[:"start-prompt"],
+              start_prompt: options[:"start-prompt"], hitl_case: options[:"hitl-case"],
               force: options[:force] == true, dry_run: options[:"dry-run"] == true
             )
 

data/lib/ace/coworker/cli/commands/gate.rb

@@ -13,26 +13,34 @@ module Ace
 
           example [
             "gate --candidate-head 1a2b3c4 --review-head 1a2b3c4 --review-verdict accept \\",
-            "     --tests executed,passed --dep 8xg.t.sbz.4.2=integrated",
+            "     --tests executed,passed --tests-head 1a2b3c4 --dep 8xg.t.sbz.4.2=integrated \\",
+            "     --approval-head 1a2b3c4 --approval-by lab-merge-ace --author lab-overseer",
             "gate --candidate-head 1a2b3c4 --review-head 0d0e0f --review-verdict accept \\",
-            "     --tests executed,passed --dep 8xg.t.sbz.4.2=missing"
+            "     --tests executed,passed --tests-head 1a2b3c4 --dep 8xg.t.sbz.4.2=missing"
           ]
 
           option :candidate_head, desc: "Current head of the candidate branch (omit when unknown)"
           option :review_head, desc: "Candidate head the review verdict covers"
           option :review_verdict, required: true, desc: "Independent review verdict (accept, continue, escalate)"
           option :tests, type: :array, default: [], desc: "Test evidence flags: executed, passed"
+          option :tests_head, desc: "Candidate head the executed test run covered (required with test evidence)"
+          option :approval_head, desc: "Candidate head the formal approval covers (lanes requiring formal approval)"
+          option :approval_by, desc: "Account that gave the formal approval"
+          option :author, desc: "Candidate author account (the formal approver must differ)"
           option :dep, type: :array, default: [], desc: "Dependency states as name=integrated|missing pairs"
           option :format, default: "table", desc: "Output format (table, json)"
           option :quiet, aliases: ["-q"], type: :boolean, default: false, desc: "Suppress non-essential output"
           option :debug, aliases: ["-d"], type: :boolean, default: false, desc: "Show debug output"
 
-          def call(candidate_head: nil, review_head: nil, review_verdict: nil, tests: [], dep: [],
-                   format: "table", **options)
+          def call(candidate_head: nil, review_head: nil, review_verdict: nil, tests: [],
+            tests_head: nil, approval_head: nil, approval_by: nil, author: nil, dep: [],
+            format: "table", **options)
             result = Atoms::IntegrationGate.evaluate(
               "candidate_head" => candidate_head.to_s,
               "review" => {"head" => review_head.to_s, "verdict" => review_verdict.to_s},
-              "tests" => tests_flags(tests),
+              "tests" => tests_flags(tests).merge("head" => tests_head.to_s),
+              "approval" => approval_for(approval_head, approval_by),
+              "author" => author.to_s,
               "dependencies" => dependency_states(dep)
             )
 
@@ -47,6 +55,14 @@ module Ace
 
           private
 
+          # A formal approval participates only when the lane supplied
+          # approval evidence; omitted approval facts skip the check.
+          def approval_for(approval_head, approval_by)
+            return {} if approval_head.to_s.strip.empty? && approval_by.to_s.strip.empty?
+
+            {"head" => approval_head.to_s, "by" => approval_by.to_s}
+          end
+
           def tests_flags(tests)
             flags = Array(tests).flat_map { |value| value.to_s.split(",") }.map { |f| f.strip.downcase }.reject(&:empty?)
             flags.each do |flag|

data/lib/ace/coworker/organisms/commission_orchestrator.rb

@@ -56,7 +56,8 @@ module Ace
         # @raise [Error] on unknown role, identity mismatch, invalid
         #   assembly, a refused overwrite, a config path escaping the
         #   project root, or a directory config target
-        def call(role:, task:, assignment:, overseer:, start_prompt: nil, force: false, dry_run: false)
+        def call(role:, task:, assignment:, overseer:, start_prompt: nil, hitl_case: nil,
+          force: false, dry_run: false)
           preset = @preset_loader.fetch(role)
 
           # Canonicalize the task identity first: the assignment match and
@@ -69,10 +70,17 @@ module Ace
           canonical_task = resolved.id.to_s
           @assignment_metadata.verify_task_match!(assignment, canonical_task)
 
-          prompt = start_prompt.to_s.strip.empty? ? render_prompt(preset, role, canonical_task, assignment, overseer) : start_prompt
+          hitl_case = hitl_case.to_s.strip
+          if start_prompt.to_s.strip.empty? && preset["start_prompt"].to_s.include?("{{case}}") && hitl_case.empty?
+            raise Error,
+              "the '#{role}' start_prompt delegates to a HITL case ({{case}}); " \
+                "pass the exact case id (--hitl-case CASE_ID) or a literal --start-prompt"
+          end
+
+          prompt = start_prompt.to_s.strip.empty? ? render_prompt(preset, role, canonical_task, assignment, overseer, hitl_case) : start_prompt
 
           config = build_config(preset, role: role, task: canonical_task, assignment: assignment,
-            overseer: overseer, prompt: prompt)
+            overseer: overseer, prompt: prompt, hitl_case: hitl_case)
           errors = Atoms::ConfigSchema.errors(config)
           unless errors.empty?
             raise Error, "commissioned config is invalid: #{errors.join('; ')}"
@@ -91,12 +99,13 @@ module Ace
 
         private
 
-        def render_prompt(preset, role, task, assignment, overseer)
+        def render_prompt(preset, role, task, assignment, overseer, hitl_case)
           Atoms::PromptTemplate.render(preset["start_prompt"],
-            {"task" => task, "assignment" => assignment, "role" => role, "overseer" => overseer})
+            {"task" => task, "assignment" => assignment, "role" => role,
+             "overseer" => overseer, "case" => hitl_case})
         end
 
-        def build_config(preset, role:, task:, assignment:, overseer:, prompt:)
+        def build_config(preset, role:, task:, assignment:, overseer:, prompt:, hitl_case: "")
           config = {
             "role" => role,
             "instructions" => preset["instructions"],
@@ -105,6 +114,7 @@ module Ace
             "assignment" => assignment,
             "overseer" => overseer
           }
+          config["case"] = hitl_case unless hitl_case.empty?
           config["toolchain"] = "installed" if Ace::Support::Cli::Toolchain.installed?
           config["reporting"] = {"channel" => preset["reporting"]} unless preset["reporting"].to_s.empty?
           config["errors"] = {"on_failure" => preset["errors"]} unless preset["errors"].to_s.empty?

data/lib/ace/coworker/version.rb

@@ -2,6 +2,6 @@
 
 module Ace
   module Coworker
-    VERSION = "0.6.1"
+    VERSION = "0.7.0"
   end
 end

metadata

@@ -1,13 +1,13 @@
 --- !ruby/object:Gem::Specification
 name: ace-coworker
 version: !ruby/object:Gem::Version
-  version: 0.6.1
+  version: 0.7.0
 platform: ruby
 authors:
 - Michal Czyz
 bindir: exe
 cert_chain: []
-date: 2026-10-20 00:00:00.000000000 Z
+date: 2026-10-30 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: ace-support-cli
@@ -159,14 +159,14 @@ dependencies:
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '0.62'
+        version: 0.62.2
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '0.62'
+        version: 0.62.2
 - !ruby/object:Gem::Dependency
   name: ace-support-test-helpers
   requirement: !ruby/object:Gem::Requirement
@@ -236,6 +236,7 @@ files:
 - ".ace-defaults/coworker/config.yml"
 - ".ace-defaults/coworker/roles/integrator.yml"
 - ".ace-defaults/coworker/roles/reviewer.yml"
+- ".ace-defaults/coworker/roles/second-captain.yml"
 - ".ace-defaults/coworker/roles/spec.yml"
 - ".ace-defaults/coworker/roles/worker.yml"
 - ".ace-defaults/coworker/sequences/integrator.yml"
@@ -250,6 +251,7 @@ files:
 - exe/ace-coworker
 - handbook/workflow-instructions/coworker/integrator.wf.md
 - handbook/workflow-instructions/coworker/reviewer.wf.md
+- handbook/workflow-instructions/coworker/second-captain.wf.md
 - handbook/workflow-instructions/coworker/spec.wf.md
 - handbook/workflow-instructions/coworker/worker.wf.md
 - lib/ace/coworker.rb