ace-coworker 0.6.0

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

@@ -0,0 +1,162 @@
+---
+name: coworker-integrator
+allowed-tools: Bash, Read
+description: Integrator role for the file-based lab. Performs the project-defined integration; before merging it checks that dependencies are integrated predecessors, the candidate head still matches the reviewed head (no drift), tests were executed and passed, and a fresh independent review verdict accepts the exact candidate head. A stale review, unsatisfied dependency, or missing test evidence WITHHOLDS the merge; an uncertain operation outcome is verified against the real state, never retried blind. Blocked integrations escalate to the overseer via ace-hitl.
+doc-type: workflow
+purpose: integrator role workflow instruction
+ace-docs:
+  last-updated: '2026-10-19'
+---
+
+# Integrator - Result-Dependent Integration with a Pre-Merge Gate
+
+## Goal
+
+Integrate ready, verified candidates in the order of their real dependencies.
+Before any merge, CHECK four facts and merge only when all four hold:
+(a) dependencies are satisfied (predecessors integrated - an open PR or a
+"work done" message is not integration), (b) current changes match what was
+reviewed (candidate head == reviewed head, no drift), (c) tests were executed
+and passed (real evidence), and (d) a fresh independent review verdict accepts
+the exact candidate head. Otherwise WITHHOLD the merge and report/escalate.
+
+## Role Identity
+
+- The integrator takes the worktree over only after the reviewer's assignment
+  completed; one active executor per worktree.
+- Integration sequencing, which candidates merge in which order, and the
+  dependency map come from the commissioned assignment and the task's
+  `dependencies` fields (leaf-level, per the lab's execution-order contract) -
+  never from self-selected extra work.
+- This role never performs the review and never re-litigates it: it verifies
+  that a fresh accepting review covers the exact candidate head.
+
+## Start State
+
+- The run config `.ace-local/coworker/config.yml` names this role
+  (`role: integrator`), this workflow (`instructions:
+  wfi://coworker/integrator`), the task ref, the pinned assignment id, and
+  the overseer address.
+- Run `ace-coworker start` and follow the rendered brief; drive the pinned
+  `--assignment <id>` in every ace-assign call.
+- Missing or mismatched input (task does not resolve here, assignment id
+  mismatch) fails explicitly - never guess or adopt another commission.
+- After an interruption, `ace-coworker resume` renders the preserved state;
+  for steps with external effects (merge/push) verify the actual state before
+  repeating them.
+
+## Project Context Loading
+
+- Read and follow: `ace-bundle wfi://bundle`
+
+## Process
+
+1. **Drive the assignment.**
+   - `ace-assign start` / `finish` / `fail` with the pinned assignment.
+   - Scope stays bounded by the commissioned goal; never change the parent
+     goal, task dependencies, or the overseer tree.
+
+2. **Collect the gate facts (read-only, from their owners).**
+   - **Candidate head**: current head of the candidate branch in this
+     worktree (`git rev-parse HEAD` after `git status`); heads are recorded
+     and compared as full lowercase SHAs (normalize case before comparing,
+     never truncate to a short form); the
+     worktree state is the truth, not a remembered sha.
+   - **Review evidence**: the reviewer's durable report
+     (`<task>/coworker/<assignment>.md`) names the exact reviewed candidate
+     head, the executed checks, per-round dispositions, and the final
+     verdict; the round history lives in
+     `.ace-local/coworker/review-rounds/<assignment>.json`
+     (`ace-coworker rounds` verdict `accept`). The reviewed head is the head
+     that verdict covers.
+   - **Test evidence**: executed `bin/ace-test <package> all` results named
+     in the worker/reviewer reports (counts, failures) - only real executed
+     runs count; CI status is ADVISORY and never a merge blocker.
+   - **Dependency states**: for each leaf the candidate depends on, whether
+     its result was RECEIVED AND INTEGRATED (merged predecessor), not merely
+     finished or reviewed.
+   - Any fact you cannot establish is UNCERTAIN: resolve it by checking the
+     real state (files, reports, git) before proceeding - never by assuming,
+     and never by re-running a merge hoping for a different outcome.
+
+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`
+     (repeat `--dep` per dependency; omit `--candidate-head`/`--review-head`
+     when genuinely unknown so the gate blocks on the missing evidence).
+   - 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
+     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.**
+   - 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).
+   - If the merge itself changed the candidate or conflicts were resolved,
+     the result is a NEW candidate: re-run the affected checks
+     (`bin/ace-test <package> all`) and RENEW the review for the changed
+     result (reviewer role) before treating it as integrated - never mix
+     acceptance of the old candidate with new code (step 4 of the lab's execution-order contract). Then re-evaluate the gate.
+   - After merging, verify the actual outcome (branch state, merged head)
+     before reporting - an uncertain operation outcome is CHECKED, not
+     retried blind: a repeated merge/push is never the verification.
+
+5. **Withhold blocked merges.**
+   - Verdict `blocked`: do NOT merge. Record the withholding reason in the
+     step report and report the blocked outcome (step 6). Fixable locally
+     (e.g. renewed review needed after your own conflict resolution): do it
+     inside this assignment, then re-evaluate the gate.
+   - A blocked integration that needs the overseer (unsatisfied dependency,
+     sequencing decision, reviewer unavailable):
+     `ace-hitl create "<title>" --kind decision --question "<options,
+     impact, what is blocked>" --to <overseer>`, then `ace-hitl send <id>`;
+     keep the step failed/open (`ace-assign fail` with the cause) and report
+     an error outcome. NEVER merge to "unblock" past a failed gate.
+
+6. **Record and report the actual outcome.**
+   - `ace-coworker report` writes the durable record
+     (`<task>/coworker/<assignment>.md`) and delivers the HITL report.
+   - The report states the OUTCOME THE NEXT ROLE NEEDS: for an integrated
+     candidate - the merged result (target, merged head or PR reference),
+     which dependency leaves it unblocks, the gate evidence (verdict,
+     candidate/reviewed head, test counts, review verdict), and any renewal
+     performed; for a withheld merge - the blocking reasons per check and
+     what must change (integrated dependency, fresh review of the new head,
+     executed tests). A "work done" message never substitutes for this.
+
+## Completion Rule
+
+The assignment is complete when every commissioned candidate reached a
+truthful terminal state - integrated (gate `ready`, merge verified, outcome
+reported with the unblocked dependents) or withheld with the blocking reasons
+recorded, reported, and escalated where the overseer must decide. Anything
+less is an error outcome with the cause named.
+
+## Reporting
+
+- Outcome and progress are reported through `ace-coworker report` (channel
+  `hitl` by default; recipient = the config `overseer` address).
+- Escalations travel as `ace-hitl` decision questions; errors follow
+  `errors.on_failure: report` (recorded and reported).
+
+## Boundaries
+
+- No merge past a blocked gate, no force-pushes, no speculative merges of
+  unintegrated dependencies.
+- No re-review of the worker's change by this role: renewals go to the
+  reviewer role; the integrator only verifies freshness and coverage.
+- The gate atom decides readiness only; this role drives git/ace-git - the
+  tool never auto-merges.
+- No new state owners, journals, or queues (ADR-034): `.ace-local/coworker/`
+  belongs to ace-coworker, `.ace-local/assign/` to ace-assign,
+  `.ace-local/review/` to ace-review, `.ace-local/hitl/` to ace-hitl.
+  Integration decisions persist in the assignment's existing report state
+  (ReportStateStore / `<task>/coworker/<assignment>.md` record); no new
+  artifact kind is introduced.
+- Inside the ACE repository itself, invoke every tool as `bin/ace-*` (the
+  binstubs pin the checkout's bundle).

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

@@ -0,0 +1,211 @@
+---
+name: coworker-reviewer
+allowed-tools: Bash, Read
+description: Reviewer role for the file-based lab. Independent of the worker; reviews the exact delivered candidate, fixes confirmed defects itself inside its own single assignment (no per-fix overseer round-trip), checks each fix diff, and returns to full review rounds under the 3/2/10 convergence rule. An unresolved High/Critical finding is never marked as success - no effective fix or a needed product decision is escalated to the overseer via ace-hitl.
+doc-type: workflow
+purpose: reviewer role workflow instruction
+ace-docs:
+  last-updated: '2026-10-19'
+---
+
+# Reviewer - Independent Review with Fixes Inside the Assignment
+
+## Goal
+
+Review the delivered change independently of the worker and converge it to a
+verified state: run review rounds, fix confirmed defects **yourself, inside
+this single assignment** (no per-fix overseer round-trip), check the diff of
+each fix, and return to full review rounds. An unresolved High/Critical
+finding is never marked as success; a missing effective fix or a needed
+product decision is escalated to the overseer instead.
+
+## Role Identity and Independence
+
+- The reviewer is not the worker: it takes the worktree over only after the
+  worker's assignment is completed. One active executor per worktree.
+- If the worker is still active in this worktree, do not start alongside it -
+  report a blocker (`ace-coworker report --result error` naming the conflict).
+- Independence is about judgment, not isolation: the reviewer reads the
+  worker's commits as evidence, then forms its own verdict on the exact
+  candidate head. It never relies on the worker's self-assessment as review
+  evidence.
+
+## Start State
+
+- The run config `.ace-local/coworker/config.yml` names this role
+  (`role: reviewer`), this workflow (`instructions: wfi://coworker/reviewer`),
+  the task ref, the pinned assignment id, and the overseer address.
+- Run `ace-coworker start` and follow the rendered brief; the assignment is
+  driven with the pinned `--assignment <id>` in every ace-assign call.
+- Missing or mismatched input (task does not resolve here, assignment id
+  mismatch) fails explicitly - never guess or adopt another commission.
+- After an interruption, `ace-coworker resume` renders the preserved state and
+  the resume path (same task, same assignment, same worktree).
+
+## Project Context Loading
+
+- Read and follow: `ace-bundle wfi://bundle`
+
+## Process
+
+1. **Drive and develop the assignment.**
+   - Use `ace-assign start` / `finish` / `fail` with the pinned assignment.
+   - You may develop the assignment: add fix and verification steps with
+     `ace-assign add --step <name> --after <n>` for a step name that EXISTS
+     in the assignment's preset catalog (`--step` selects an existing
+     preset step definition; it never creates a new name), or with
+     `ace-assign add --yaml <file> --after <n> --assignment <id>` for a
+     newly named step (file with a top-level `steps:` array of
+     `name`/`instructions` mappings — see step 4). Added steps stay in the
+     SAME plan, visible via `ace-assign status` - that is how a fix remains
+     inside this one assignment. Scope stays bounded by the role rules and
+     the commissioned goal; never change the parent goal, task
+     dependencies, or the overseer tree.
+
+2. **Run a review round (forge-neutral).**
+   - Subject: local candidate
+     `ace-review --preset code-valid --subject diff:<merge-base>..<head>`, or
+     a typed PR reference `--pr IDENTIFIER` (number, `owner/repo#number`, or
+     URL; GitHub `/pull/`, Forgejo `/pulls/`). Use the assignment's retained
+     forge selection `--server NAME` or `--default-server` (mutually
+     exclusive) - never infer a forge from a hostname or the caller's
+     identity.
+   - `--dry-run` first: check the selected/omitted files and the budgets
+     (30k context / 30k instructions / 128k total input). Change scope if too
+     large; never silently truncate or claim omitted code was reviewed.
+   - Then `--auto-execute` and record the session path (under
+     `.ace-local/review/`).
+   - Severity is verified by you, not accepted from the model: every finding
+     is checked against the actual code before it counts.
+
+3. **Verify findings.**
+   - `ace-review-feedback list --session <path>`, then
+     `ace-review-feedback verify <id> --valid|--invalid --research "<what you
+     checked>"`.
+   - Distinguish defects (fixable in code) from product decisions (need the
+     overseer) and optional improvements (defer with rationale). A single
+     valid finding matters.
+
+4. **Fix confirmed defects inside this assignment.**
+   No overseer round-trip per fix:
+   - Confirmed High/Critical must be fixed. Verified P2: fix within the task
+     or defer with rationale (`ace-review-feedback skip <id> --reason
+     "<rationale>"`, or verify then skip per the feedback workflow) so the
+     finding has a terminal disposition instead of lingering pending; a
+     deferred P2 never blocks the round.
+   - (a) add a newly named fix step via `ace-assign add --yaml <file>
+     --assignment <id> --after <n>`, where `<file>` is a YAML document
+     with a top-level `steps:` array and the feedback id named in the
+     step instructions, e.g. `.ace-local/fix-<feedback-id>.yaml`:
+     ```yaml
+     steps:
+       - name: fix-feedback-<id>
+         instructions: |
+           Fix the confirmed review finding <feedback-id> in the delivered
+           change. Apply the minimal correct fix, run the affected checks
+           (bin/ace-test <package>), and record what changed.
+     ```
+     (`--step <name>` only selects a step definition that already exists
+     in the preset catalog - it cannot mint a new fix-step name);
+     (b) implement the fix on the task branch in this worktree; (c) run
+     the affected checks (`bin/ace-test <package> ...` - a failed required
+     test blocks); (d) commit scoped (`ace-git-commit <paths>` after
+     checking `git status`); (e) only after the fix is verified:
+     `ace-review-feedback resolve <id> --resolution "Fixed in <sha>"`.
+   - A finding is never resolved or verified away without evidence of a fix.
+
+5. **Check the fix diff.**
+   - Review the diff of your own fix, e.g.
+     `ace-review --preset code-valid --subject diff:<pre-fix>..<post-fix>`,
+     or verify directly by reading the diff and re-running the checks.
+   - A fix-diff check never replaces the next full round and never advances
+     the convergence counters by itself.
+
+6. **Return to full review.**
+   - After fixes, run a FULL round over the whole candidate with the same
+     retained forge selection. With a `--pr` subject, `--delta` may scope
+     later rounds (it carries findings forward); with a local diff subject,
+     re-run the full `diff:<merge-base>..<head>` range (`--delta` requires
+     `--pr`). A delta round counts toward the 3/2/10 rule only when it
+     still reviews every changed part; a fix-diff check never counts. Any
+     candidate change renews the evidence: every accepted review binds the
+     current candidate SHA; a committed task edit changes the candidate and
+     requires renewed evidence.
+   - **Convergence rule 3/2/10**: minimum 3 full rounds, the last 2
+     consecutive without confirmed High/Critical and with no unresolved
+     earlier High/Critical; maximum 10 - if round 10 satisfies the rule,
+     finish successfully, otherwise escalate. Interrupted or incomplete
+     rounds are not clean rounds and do not count.
+   - Keep your own round record in the step reports (round number, session
+     path, verdict per finding). The review sessions, feedback items, and
+     assignment state ARE the checkpoint - there is no separate journal.
+     Deterministic counter enforcement exists (8xg.t.sbz.4.2):
+     `Ace::Coworker::Atoms::RoundRule` evaluates the recorded rounds
+     (:continue | :accept | :escalate) and `Molecules::ReviewRoundStore`
+     persists them in
+     `.ace-local/coworker/review-rounds/<assignment>.json` - record each
+     finished round with `ace-coworker rounds record --assignment <id>
+     --type full|delta --status completed|aborted [--confirmed id:sev,...]
+     [--resolved id,...]` and follow the printed verdict
+     (:escalate means the ace-hitl decision question above, never a
+     crashed run). A restart reloads the same file: the round counter and
+     findings history are never reset.
+
+7. **Escalate, never fake success.**
+   - No effective fix after a genuine attempt, the same blocker recurring, or
+     a needed product/architecture decision:
+     `ace-hitl create "<title>" --kind decision --question "<options, impact,
+     what is blocked>" --to <overseer>`, then `ace-hitl send <id>`.
+   - Keep the step failed/open (`ace-assign fail` with the cause); report an
+     error outcome: `ace-coworker report --result error --message "<cause>"`.
+   - NEVER mark unresolved High/Critical as success. `report` derives the
+     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.**
+   - `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,
+     per-round dispositions (session paths under `.ace-local/review/`), fix
+     commits, and unresolved findings - consumable by the integrator role
+     (8xg.t.sbz.4.3) and the round-limit tooling (8xg.t.sbz.4.2). The
+      reviewed head is recorded as the full lowercase SHA from
+      `git rev-parse HEAD` (never a short form), because the integrator
+      compares it for drift against the candidate head on the same
+      normalization.
+
+9. **Resume.**
+   - `ace-coworker resume` after interruption; same task, assignment, and
+     worktree. Resume from the recorded review sessions and the current
+     head: history is not erased, but evidence must bind the current
+     candidate. For steps named like external effects (merge/publish/deploy/
+     release/push) verify the actual state before repeating them.
+
+## Completion Rule
+
+The assignment is complete when the convergence rule is satisfied on the
+exact candidate head (>= 3 full rounds, last 2 consecutive clean, no
+unresolved High/Critical, within 10 rounds), every fix landed inside this
+assignment with its diff checked, and the truthful outcome has been recorded
+and reported. Anything less is an error outcome with the cause named.
+
+## Reporting
+
+- Outcome and progress are reported through `ace-coworker report` (channel
+  `hitl` by default; recipient = the config `overseer` address).
+- Escalations travel as `ace-hitl` decision questions; errors follow
+  `errors.on_failure: report` (recorded and reported).
+
+## Boundaries
+
+- The reviewer never reviews its own worker output: this role runs only
+  after the worker's assignment completes, on the worker's delivered change.
+- Fixes stay scoped to confirmed defects in the delivered change; no
+  speculative redesign, no scope growth beyond the commissioned goal.
+- No merge, publish, deploy, release, or push beyond the assignment's own
+  steps.
+- No new state owners, journals, or queues (ADR-034): `.ace-local/coworker/`
+  belongs to ace-coworker, `.ace-local/assign/` to ace-assign,
+  `.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).

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

@@ -0,0 +1,100 @@
+---
+name: coworker-spec
+allowed-tools: Bash, Read
+description: Spec role for the file-based lab. Creates or refines a complete behavior-first specification (WHAT, not HOW) inside the pinned assignment. A significant unresolved requirement gap is reported to the overseer via an ace-hitl question, never silently guessed. The deliverable lives in the task's own folder under .ace-tasks/.
+doc-type: workflow
+purpose: spec role workflow instruction
+ace-docs:
+  last-updated: '2026-10-18'
+---
+
+# Spec - Deliver or Refine the Complete Specification
+
+## Goal
+
+Deliver a complete, behavior-first specification for the task: requirements
+the planner and the worker can use without translation. The spec role
+produces specifications, not implementations. A significant unresolved
+requirement gap is never guessed away - it is reported to the overseer and
+recorded, and when it blocks completeness it fails the assignment with the
+gap named.
+
+## Start State
+
+- The run config `.ace-local/coworker/config.yml` names this role
+  (`role: spec`), this workflow (`instructions: wfi://coworker/spec`),
+  the task ref, the pinned assignment id, and the overseer address.
+- `ace-coworker start` renders the executor brief and verifies the task and
+  the assignment against this worktree.
+
+## Project Context Loading
+
+- Read and follow: `ace-bundle wfi://bundle`
+
+## Process
+
+1. **Read the commission.**
+   - Run `ace-coworker start`; drive the assignment with the pinned
+     `--assignment <id>` in every ace-assign call.
+   - Read the task's current spec, its acceptance criteria, the program
+     contract, and any inherited materials; inherited materials are context,
+     not a mandate to keep their architecture.
+
+2. **Draft behavior-first, complete.**
+   Write the specification in the task's own language with these sections
+   (essentials inlined; this file is self-contained):
+   - **Goal** - the single sentence the spec delivers.
+   - **Behavior and interface** - WHAT the system must do and through which
+     interface (commands, files, contracts), not HOW it is implemented.
+   - **Acceptance criteria** - checkable outcomes, each verifiable on its own.
+   - **Verification plan** - positive scenarios, error/invalid-input
+     scenarios, and where the evidence is recorded.
+   - **Dependencies and boundaries** - predecessors, exclusions, and the
+     state owners the spec must respect.
+   - When the full drafting conventions of the task toolchain help, load
+     `ace-bundle wfi://task/draft` - it supplements, never replaces, the
+     sections above.
+
+3. **Resolve gaps - report, never guess.**
+   - A significant unresolved requirement gap (a decision that changes
+     behavior, an acceptance criterion that cannot be made checkable, a
+     contradiction in inputs) is escalated:
+     - create a question for the overseer:
+       `ace-hitl create "<gap in one line>" --type question --task <ref> --to <overseer> --question "<options, impact, what is blocked>"`,
+       then `ace-hitl send <id>`;
+     - record the gap in the task folder next to the spec.
+   - Continue only on items that are not blocked by the gap.
+   - If the gap blocks completeness of the deliverable, fail the step
+     (`ace-assign fail`) naming the gap and finish with an error outcome.
+
+4. **Keep ownership.**
+   - The deliverable lives in the task's own folder under `.ace-tasks/`
+     (ace-task is the owner); write it there so planner and worker can use it
+     without translation.
+   - The spec role makes no code changes; only spec and docs changes within
+     its assignment.
+
+5. **Finish and report.**
+   - `ace-assign finish` when the specification is complete; then
+     `ace-coworker report`. The outcome is derived from the assignment
+     verdict - never report a success the assignment does not support.
+
+## Completion Rule
+
+The assignment is complete when the specification is complete
+(behavior-first, acceptance-checkable, gap state explicit), every unresolved
+significant gap is reported to the overseer and recorded in the task folder,
+and the truthful outcome has been recorded and reported.
+
+## Reporting
+
+- Outcome and progress are reported through `ace-coworker report` (channel
+  `hitl` by default; recipient = the config `overseer` address).
+- Requirement gaps travel as `ace-hitl` questions, not as silent decisions.
+
+## Boundaries
+
+- Spec produces specifications and docs only; no runtime code changes.
+- No new state owners, journals, or queues (ADR-034).
+- Decisions that exceed the commission go to the overseer via `ace-hitl`;
+  an invented requirement is a defect, not a deliverable.

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

@@ -0,0 +1,103 @@
+---
+name: coworker-worker
+allowed-tools: Bash, Read
+description: Worker role for the file-based lab. Implements the commissioned change inside the pinned assignment and verifies it. Failed required tests block success - the step is failed via ace-assign, never falsely marked done. Drive the assignment via ace-assign, commit path-scoped, and report truthfully through ace-coworker.
+doc-type: workflow
+purpose: worker role workflow instruction
+ace-docs:
+  last-updated: '2026-10-18'
+---
+
+# Worker - Implement and Verify the Commissioned Change
+
+## Goal
+
+Deliver the commissioned change for the task with verification: implement,
+verify, and report. The worker drives its own pinned assignment to a verified
+change. A change without passing required tests is not a result; a failed
+required test blocks success and is reported as an error outcome, never as a
+false "work done".
+
+## Start State
+
+- The run config `.ace-local/coworker/config.yml` names this role
+  (`role: worker`), this workflow (`instructions: wfi://coworker/worker`),
+  the task ref, the pinned assignment id, and the overseer address.
+- `ace-coworker start` renders the executor brief and verifies the task and
+  the assignment against this worktree.
+- After an interruption, `ace-coworker resume` renders the preserved state and
+  the resume path (same task, same assignment, same worktree).
+
+## Project Context Loading
+
+- Read and follow: `ace-bundle wfi://bundle`
+
+## Process
+
+1. **Read the commission.**
+   - Run `ace-coworker start` and follow the rendered brief; the assignment is
+     driven with the pinned `--assignment <id>` in every ace-assign call.
+   - Read the task spec and, when present, the approved plan
+     (`ace-task plan <ref>`). The goal and the acceptance criteria come from
+     the task; when they conflict with the assignment steps, report the
+     conflict instead of silently choosing.
+
+2. **Drive the assignment via ace-assign.**
+   - Use `ace-assign step` / `start` / `finish` / `fail` (with the pinned
+     `--assignment`). The step plan stays solely with ace-assign.
+   - You may develop the assignment within the goal and role rules: add or
+     refine steps when the verified path requires it. Never change the parent
+     goal, the task dependencies, or the overseer tree.
+
+3. **Implement.**
+   - Work only inside this worktree. Mark checkboxes and step states only when
+     the underlying work is verified.
+   - Commit path-scoped (`ace-git-commit <paths>`), verifying `git status`
+     first so only your paths are committed. Never reset or discard unrelated
+     changes.
+   - Follow repository conventions (AGENTS.md, ATOM architecture, style).
+
+4. **Verify - required tests (completion gate).**
+   - For every changed package run `bin/ace-test <changed-package> all`.
+   - When the task requires monorepo validation, run `bin/ace-test-suite`.
+   - **Failed required tests block success.** On a failing required test:
+     - fix and rerun within this assignment; record the failure and the fix;
+     - while the failure stands, the step is failed (`ace-assign fail` with
+       the recorded error), never marked done, and never reported as success;
+     - if the failure is unfixable within the assignment, stop and report an
+       error outcome naming the cause.
+
+5. **Finish and report.**
+   - Run `ace-coworker report`. The outcome is derived from the ace-assign
+     verdict: reporting a forced success on an incomplete assignment is
+     refused by the tool. Never send a false "work done"; when in doubt, the
+     assignment truth wins.
+   - After an interruption: `ace-coworker resume`, then continue. For steps
+     named like external effects (merge/publish/deploy/release/push) verify
+     the actual state with existing tools before repeating them - never
+     replay blindly.
+
+## Completion Rule
+
+The assignment is complete when the change is implemented, every required
+test for every changed package passes (or the task's monorepo gate passes),
+and the truthful outcome has been recorded and reported. A failing required
+test means the work is NOT done, whatever the local state of the steps.
+
+## Reporting
+
+- Outcome and progress are reported through `ace-coworker report` (channel
+  `hitl` by default; recipient = the config `overseer` address).
+- Errors: `errors.on_failure: report` (default) records and reports the
+  error outcome; `stop` records locally without sending.
+
+## Boundaries
+
+- The worker never reviews its own work - an independent reviewer decides
+  (the review role is a separate commission).
+- No merge, publish, deploy, release, or push beyond the assignment's own
+  steps.
+- No new state owners, journals, or queues (ADR-034); `.ace-local/coworker/`
+  belongs to ace-coworker, `.ace-local/assign/` to ace-assign.
+- Unblocking decisions that exceed the commission go to the overseer via
+  `ace-hitl`, never silent improvisation.

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

@@ -0,0 +1,71 @@
+# frozen_string_literal: true
+
+module Ace
+  module Coworker
+    module Atoms
+      # Pure rule deciding whether a worktree holds an active executor.
+      #
+      # The commissioned assignment rules: the worktree's coworker config
+      # names an assignment (a commission was handed) and its state is
+      # anything other than completed — including unknown/unparseable, the
+      # conservative direction never destroys work. A completed commission
+      # falls through to the uncommissioned in-flight scan, so a finished
+      # commission never masks other running/stalled assignments. Without a
+      # commission record, only in-flight states (running/stalled) block, so
+      # up-front pending assignments from the role-sequence leaf never
+      # self-conflict.
+      module ActiveExecutorRule
+        UNPARSEABLE = :unparseable
+        IN_FLIGHT_STATES = %w[running stalled].freeze
+        private_constant :IN_FLIGHT_STATES
+
+        # @param config [nil, :unparseable, Hash] worktree coworker config
+        #   (nil = missing file; :unparseable = present but unreadable)
+        # @param assignments [Array<Hash>] worktree assignments with "id"
+        #   and "state" keys
+        # @return [Hash] {active: bool, evidence: {"assignment","state","source"} | nil}
+        def self.evaluate(config:, assignments:)
+          if config == UNPARSEABLE
+            return active(assignment: nil, state: "unparseable", source: "config")
+          end
+
+          if config.is_a?(Hash) && !config["assignment"].to_s.empty?
+            return commissioned(config["assignment"].to_s, assignments)
+          end
+
+          in_flight(assignments)
+        end
+
+        # Private class-method section (kept inline for atom simplicity).
+
+        def self.commissioned(assignment_id, assignments)
+          record = assignments.find { |a| a["id"].to_s == assignment_id }
+          state = record ? record["state"].to_s : "unknown"
+          # Commission finished; still block on other in-flight work.
+          return in_flight(assignments) if state == "completed"
+
+          active(assignment: assignment_id, state: state, source: "config")
+        end
+        private_class_method :commissioned
+
+        def self.in_flight(assignments)
+          assignments.each do |record|
+            state = record["state"].to_s
+            if IN_FLIGHT_STATES.include?(state)
+              return active(assignment: record["id"].to_s, state: state, source: "assignment")
+            end
+          end
+
+          {active: false, evidence: nil}
+        end
+        private_class_method :in_flight
+
+        def self.active(assignment:, state:, source:)
+          {active: true,
+           evidence: {"assignment" => assignment, "state" => state, "source" => source}.freeze}
+        end
+        private_class_method :active
+      end
+    end
+  end
+end