ace-coworker 0.6.2 → 0.8.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 7420999db530cb82bcb5ec29ec372684ec0f60561b84c230a8e5bb3ac0200843
-  data.tar.gz: 7acd12950816f9ec0d9f034ff7f68e7667c5c9eeac94989f8dbd4238a7290c6c
+  metadata.gz: b33e4050f914bca417193b67ba22d076a9a7866a89d1d3465fe6fb344f7bca7d
+  data.tar.gz: 1cba8a3b7b85957083d95da14d5cf2fb44988ebc2b7efdc8537b24eda096612b
 SHA512:
-  metadata.gz: b602e3377b4396d3e990fdfb5c3f79cb42b0b82522460039199866afee03e59dfd4cbb41d4069e4a128bfe88aec7b78648985c48ef561095d912f97d77452378
-  data.tar.gz: f3aa2e8c21ee006eb2b83326c33deb24f94a39318b509c264dba26ed3520c636981c8ad9e0df5198ef643db51d201d2ac10f4358cabc6432d1fde62d17281da2
+  metadata.gz: 9c4cb31c35e64be7767cf08f12fc9609c788d9d174c7dec0e72077e16721a17670028f57ed0641d422402d70af8f8f2c32bb3304e5b455cf1b8fb20aef340965
+  data.tar.gz: 8f66afb6f9f8c9d8ceb877ff369b920860a509705356a9b6eca0f1a42aada2b2879dba2e4c028a23956dc528515f7fc48768e56a7b50e5b9d181df211f4027ff

data/.ace-defaults/coworker/roles/bootstrap-verifier.yml

@@ -0,0 +1,12 @@
+---
+name: bootstrap-verifier
+description: Independently verify the prepared canonical project without repairing it
+instructions: wfi://coworker/bootstrap-verifier
+start_prompt: >-
+  Work as {{role}} on task {{task}} and pinned assignment {{assignment}}.
+  Read the explicit canonical target and allowed operations from the commission.
+  Report verified evidence to {{overseer}}; never update its private task tree.
+reporting:
+  channel: hitl
+errors:
+  on_failure: report

data/.ace-defaults/coworker/roles/bootstrap-worker.yml

@@ -0,0 +1,12 @@
+---
+name: bootstrap-worker
+description: Prepare the explicitly commissioned canonical project configuration
+instructions: wfi://coworker/bootstrap-worker
+start_prompt: >-
+  Work as {{role}} on task {{task}} and pinned assignment {{assignment}}.
+  Read the explicit canonical target and allowed operations from the commission.
+  Report verified evidence to {{overseer}}; never update its private task tree.
+reporting:
+  channel: hitl
+errors:
+  on_failure: report

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/.ace-defaults/coworker/sequences/bootstrap-verifier.yml

@@ -0,0 +1,11 @@
+---
+role: bootstrap-verifier
+description: "Independently verify the prepared canonical project without repairing it for task {{task}}"
+outcome: "Task {{task}} has an evidence-backed bootstrap-verifier result for its exact canonical target."
+steps:
+  - name: bootstrap-verifier
+    workflow: wfi://coworker/bootstrap-verifier
+    instructions:
+      - "Independently verify the prepared canonical project without repairing it for task {{task}} under the scoped bootstrap role workflow."
+      - "Record actual checks, canonical target, operational runtime paths/versions and failures in the task evidence."
+      - "Fail the assignment on missing scope, missing required access or failed acceptance; never force success."

data/.ace-defaults/coworker/sequences/bootstrap-worker.yml

@@ -0,0 +1,11 @@
+---
+role: bootstrap-worker
+description: "Prepare the explicitly commissioned canonical project configuration for task {{task}}"
+outcome: "Task {{task}} has an evidence-backed bootstrap-worker result for its exact canonical target."
+steps:
+  - name: bootstrap-worker
+    workflow: wfi://coworker/bootstrap-worker
+    instructions:
+      - "Prepare the explicitly commissioned canonical project configuration for task {{task}} under the scoped bootstrap role workflow."
+      - "Record actual checks, canonical target, operational runtime paths/versions and failures in the task evidence."
+      - "Fail the assignment on missing scope, missing required access or failed acceptance; never force success."

data/CHANGELOG.md

@@ -7,6 +7,39 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.8.0] - 2026-10-31
+
+### Added
+
+- Scoped bootstrap-worker and independent bootstrap-verifier roles use existing
+  assignments to prepare an explicitly commissioned canonical project outside
+  the lab task worktree, without relaxing ordinary product worker boundaries.
+
+## [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

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`
 
@@ -573,3 +587,18 @@ 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.
+
+## Operational bootstrap roles
+
+`bootstrap-worker` and `bootstrap-verifier` prepare and independently verify
+a canonical project named explicitly in a lab task. Their evidence and
+assignments remain in the lab task worktree; only the commissioned target
+configuration may be accessed outside it. They preserve installed runtime
+selection and session-scoped access. They never edit the overseer private
+tree or start the project's overseer. Ordinary worker/reviewer roles retain
+their product-worktree boundaries.
+
+Prepare with `ace-coworker prepare --task <ref> --roles
+bootstrap-worker,bootstrap-verifier --to <configured-owner>`. Preparation and
+`ace-coworker start` do not launch a model process; the coordinator must launch
+a separate agent with the returned brief and confirm its first turn.

data/handbook/workflow-instructions/coworker/bootstrap-verifier.wf.md

@@ -0,0 +1,52 @@
+---
+name: coworker-bootstrap-verifier
+description: Scoped operational bootstrap-verifier for a canonical project bootstrap
+allowed-tools: Bash, Read
+doc-type: workflow
+title: bootstrap-verifier
+purpose: Execute one lab-owned bootstrap assignment with explicit target scope.
+---
+# bootstrap-verifier
+
+## Commission and scope
+
+Read the prepared start config with `ace-coworker start --config <returned path>`.
+Use its pinned assignment ID for every ace-assign operation. Read the executable
+lab task and its explicit canonical target path, allowed configuration paths,
+operations, runtime selection and acceptance criteria. Missing or ambiguous
+scope is an error report, never a guessed directory or permission.
+
+The assignment and evidence belong to the prepared lab task worktree. This
+operational role may act on the explicitly commissioned canonical target
+outside that worktree; this exception does not authorize other projects or
+product implementation. Resolve target paths before effects and reject symlink
+escapes outside the commissioned root. Preserve unrelated changes and secrets.
+Never write `.ace-tasks/_overseer`; the coordinator alone owns its private tree.
+
+Operational tools use the selected installed ACE closure, not target binstubs
+or its development Gemfile. Record actual executable/gem/instruction paths.
+Additional credentials or privileges are session-scoped through the existing
+auth handoff; do not make permanent group grants or copy credentials into
+project config, task evidence or prompts. Missing access is a report to the
+coordinator, not permission to borrow an account or change ownership.
+
+## Assignment and report
+
+Drive the pinned ace-assign step through start/finish/fail. Store evidence in
+the executable task's docs. Failed or unavailable required checks block success.
+Use `ace-coworker report --config <returned path>` for the truthful assignment
+outcome. A process exit, prepared config or printed CLI brief is not completion.
+After interruption, read current state before repeating any external effect;
+resume the same assignment, never silently create a replacement.
+
+## Independent verification
+
+Run as a separate agent from the worker. Read the worker evidence, then check
+the actual target files and installed runtime independently. Verify requested
+configuration, allowed-change boundaries, executable resolution and dependency
+readiness with the task's explicit checks; compare actual results with the
+worker's claims. Do not repair the target or accept your own preparation.
+Report discrepancies as failure for the coordinator to return to the worker.
+
+Do not start the project overseer: the coordinator owns the final reconcile,
+first-turn and eyes acceptance. Your success accepts preparation only.

data/handbook/workflow-instructions/coworker/bootstrap-worker.wf.md

@@ -0,0 +1,53 @@
+---
+name: coworker-bootstrap-worker
+description: Scoped operational bootstrap-worker for a canonical project bootstrap
+allowed-tools: Bash, Read
+doc-type: workflow
+title: bootstrap-worker
+purpose: Execute one lab-owned bootstrap assignment with explicit target scope.
+---
+# bootstrap-worker
+
+## Commission and scope
+
+Read the prepared start config with `ace-coworker start --config <returned path>`.
+Use its pinned assignment ID for every ace-assign operation. Read the executable
+lab task and its explicit canonical target path, allowed configuration paths,
+operations, runtime selection and acceptance criteria. Missing or ambiguous
+scope is an error report, never a guessed directory or permission.
+
+The assignment and evidence belong to the prepared lab task worktree. This
+operational role may act on the explicitly commissioned canonical target
+outside that worktree; this exception does not authorize other projects or
+product implementation. Resolve target paths before effects and reject symlink
+escapes outside the commissioned root. Preserve unrelated changes and secrets.
+Never write `.ace-tasks/_overseer`; the coordinator alone owns its private tree.
+
+Operational tools use the selected installed ACE closure, not target binstubs
+or its development Gemfile. Record actual executable/gem/instruction paths.
+Additional credentials or privileges are session-scoped through the existing
+auth handoff; do not make permanent group grants or copy credentials into
+project config, task evidence or prompts. Missing access is a report to the
+coordinator, not permission to borrow an account or change ownership.
+
+## Assignment and report
+
+Drive the pinned ace-assign step through start/finish/fail. Store evidence in
+the executable task's docs. Failed or unavailable required checks block success.
+Use `ace-coworker report --config <returned path>` for the truthful assignment
+outcome. A process exit, prepared config or printed CLI brief is not completion.
+After interruption, read current state before repeating any external effect;
+resume the same assignment, never silently create a replacement.
+
+## Prepare the target
+
+Change only commissioned configuration and dependency installation paths.
+Do not edit product code, replace tracked binstubs to bypass installed mode,
+or rewrite existing project dependency declarations. A product/tool defect
+requires a separate code-change commission. Use the existing configuration
+and installation tools; do not invent a second configuration owner.
+
+Verify the requested configuration and installed dependency readiness. Record
+before/after state and exact checks without secrets. Do not start another
+project overseer yourself: after independent verification the lab coordinator
+owns reconcile/start. Leave unrelated work and live services untouched.

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

@@ -82,12 +82,16 @@ 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

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.2"
+    VERSION = "0.8.0"
   end
 end

metadata

@@ -1,13 +1,13 @@
 --- !ruby/object:Gem::Specification
 name: ace-coworker
 version: !ruby/object:Gem::Version
-  version: 0.6.2
+  version: 0.8.0
 platform: ruby
 authors:
 - Michal Czyz
 bindir: exe
 cert_chain: []
-date: 2026-10-23 00:00:00.000000000 Z
+date: 2026-10-31 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: ace-support-cli
@@ -234,10 +234,15 @@ extensions: []
 extra_rdoc_files: []
 files:
 - ".ace-defaults/coworker/config.yml"
+- ".ace-defaults/coworker/roles/bootstrap-verifier.yml"
+- ".ace-defaults/coworker/roles/bootstrap-worker.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/bootstrap-verifier.yml"
+- ".ace-defaults/coworker/sequences/bootstrap-worker.yml"
 - ".ace-defaults/coworker/sequences/integrator.yml"
 - ".ace-defaults/coworker/sequences/reviewer.yml"
 - ".ace-defaults/coworker/sequences/spec.yml"
@@ -248,8 +253,11 @@ files:
 - Rakefile
 - docs/usage.md
 - exe/ace-coworker
+- handbook/workflow-instructions/coworker/bootstrap-verifier.wf.md
+- handbook/workflow-instructions/coworker/bootstrap-worker.wf.md
 - 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