ace-coworker 0.7.0 → 0.9.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 7b1ca4d493124efc790ec4f9e9ebe719b341906f45d0f8913c1005bb2ff86a94
-  data.tar.gz: adeebb47b7350576f6aabb79974efd1e8683869b8623d5f6b84fbb8d5f86abb9
+  metadata.gz: 2c6668db21df711cc2665adeec0c98ba62f6c97c23ac39443ef56d215aa238f1
+  data.tar.gz: 04db562bdca8c30274c76200be45cde3d84c1f3dfff0de32dfbf7ca87cc7e717
 SHA512:
-  metadata.gz: c8e78949c6ca07838eb12e7580704aedf918f59436a1fcd5354da812308c442e8b4eff4a42fb75334af231d04206ad511e4ce7d48a3fcc9299155f098d61de98
-  data.tar.gz: 60d8735e3fbb344584e9ded3d27dfac0cd32d0f34d5a46f305342dcab3b8715c361bd88e2ef5888672a1a786a3685eb0d19c0a70172c0ec6a6252571c3c65194
+  metadata.gz: 217666331556adc073a8a3bc08f4ea305adb0d5106a86bc1b4deed68cf42f41e15c22f45b1a521301f65c4329958b3e4e8891e39648933372ed3f829910414a9
+  data.tar.gz: f67a4eae9eb31296d6283ce395f122c04b825a0df4f810cd153a596288965de5fcf89071b6920026963288297ef0fa5194ffc88787b55dc80b77104d10af344a

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

@@ -18,3 +18,8 @@ steps:
       - "Work as the reviewer on task {{task}}: review the delivered change independently of the worker; fix confirmed defects yourself inside this assignment and check each fix diff with a delta round."
       - "Record every full round with `ace-coworker rounds record --type full` and every fix-diff check with `--type delta`; the RoundRule verdict decides the outcome, aborted or incomplete rounds are never clean."
       - "Acceptance (3/2/10): at least 3 completed full rounds, the last 2 consecutive rounds clean (no confirmed High/Critical), and no unresolved earlier High/Critical; a rule-satisfying round 10 ends in success, no acceptance after 10 full rounds escalates to the overseer via ace-hitl."
+  - name: publish-approval
+    instructions:
+      - "For a forge issue, publish formal approval on the original PR after the full review accepts its current HEAD and the required tests pass at that HEAD."
+      - "Finish this step with the verified provider receipt and test evidence. For a local-only task record the local review and tests and that no provider publication applies."
+      - "Report success only after this step is done. Missing publication evidence keeps a forge-linked assignment incomplete."

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

@@ -7,7 +7,7 @@ role: worker
 description: "Worker process for task {{task}}"
 outcome: >-
   Verified implementation of task {{task}} on the task branch: every
-  modified package passes its required tests (bin/ace-test <pkg> all) and
+  modified package passes its required tests with the selected runtime and
   the work is committed.
 steps:
   - name: work-on-task
@@ -17,5 +17,10 @@ steps:
       - "Acceptance: the required tests of every modified package pass; failed required tests block success (ace-assign fail), never a forced done."
   - name: verify-test
     instructions:
-      - "Run bin/ace-test <package> all for every modified package and record the real test counts in the task results file."
-      - "Acceptance: 0 failures across all modified packages."
+      - "Run the required checks from the worker workflow on the committed candidate with the selected runtime. Record the executed commands, results and exact HEAD in the task results file."
+      - "Acceptance: every required check has run and passed."
+  - name: publish-pr
+    instructions:
+      - "For a forge issue, publish the tested branch and create or reconcile its non-draft PR against the commissioned base."
+      - "Finish this step with the forge-verified PR identity, source branch, base and tested HEAD. For local-only work record the tested commit and that no PR applies."
+      - "Missing or uncertain PR publication keeps a forge-linked assignment incomplete."

data/CHANGELOG.md

@@ -5,6 +5,22 @@ 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.9.0] - 2026-11-10
+
+### Added
+
+- Preserve actual executor bindings when preparing or commissioning again; prevent identity replacement. Delegate project setup to workers, retain exact-HEAD review/integration gates, and keep reports tied to the selected commission.
+
+## [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)

data/README.md

@@ -97,3 +97,21 @@ ADR-022 config cascade, dry-cli commands).
 ## License
 
 MIT — see [LICENSE](../LICENSE).
+
+### Local observation reporting
+
+A role preset or serialized coworker start config can select
+`reporting: {channel: hitl, delivery: observe}`. The default delivery mode is
+`adapter`. Observation mode creates the canonical HITL report, verifies its
+exact task, assignment, outcome and configured recipient through the HITL
+owner API, and returns `published for observation; acceptance pending`.
+It does not invoke a transport adapter or claim that the overseer accepted the
+work. The coordinator must have observation armed and accept the report through
+its existing task/assignment workflow.
+
+Resume checks the current publication, including archived reports, before
+considering reporting complete. Missing or mismatched publications are not
+success; changing to adapter delivery still requires transport. `--no-send`
+continues to defer reporting and does not mark observation publication complete.
+An observation source error is a failure, never permission to silently skip
+reporting. The executor brief displays the configured delivery mode.

data/docs/usage.md

@@ -285,8 +285,14 @@ worktree`).
 ace-coworker status [--config PATH] [--assignment ID] [--format table|json] [-q] [-d]
 ```
 
-Readiness query — always exit `0`. Absent config renders
-`not ready: .ace-local/coworker/config.yml not found`. Otherwise renders the
+Executor readiness query — a rendered state exits `0`, including not-ready.
+Absent config renders `not ready: .ace-local/coworker/config.yml not found`.
+A missing or mismatched assignment, or a failed assignment status probe,
+also renders `not ready: …` and JSON `ready: false`; successful YAML parsing alone is not readiness.
+This describes one commissioned executor, not project bootstrap readiness.
+Use its returned start configuration from its execution worktree; do not copy
+that config to another checkout to make a project-level status appear ready.
+A resolved assignment renders the
 resolved role/task/assignment/overseer, the assignment progress, and the
 completion verdict with remaining-work reasons (empty plan, failed steps,
 pending/active steps).
@@ -587,3 +593,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,76 @@
+---
+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 prepared commission and assignment define this leg. Execute them directly;
+do not start a separate `ace-task plan` turn for the commissioned work.
+
+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. Run each `ace-*` check directly, without a pipe or
+redirection, and record its actual exit status and output in task docs; when
+it prints a file path, read that file. Never use the exit status of `head`, another pipeline command or `echo` as the check's result.
+Failed, unavailable or inconclusive 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.
+For `reporting.delivery: observe`, publish from the assignment worktree.
+The Lab Overseer's inbox is outside your mount by design. Validate the
+configured recipient address, never try to read, create or write its folder.
+Publication returns an event ID and leaves acceptance to the Lab Overseer.
+If the commission asks for a destination-folder write probe, report the
+conflicting check to the coordinator instead of attempting the write.
+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.
+`ace-lab prepare`, `ace-lab install` and `ace-lab verify` are host deployment
+commands in every directory. Do not run them, even in dry-run mode. If the
+assignment requires one, fail the step and report the exact conflicting check
+to the commissioning Overseer for correction. End the turn after reporting.
+Independently check the commissioned eyes configuration and its configured
+HITL recipient using checks available to the verifier role. Check the file
+with the installed ace-wake validator. The project Overseer start scope is
+`project`; the eyes JSON observes its current project with `"scope": "current"`.
+Do not require full
+observation of private overseer tasks, host systemd or host-wide verification:
+the authorized coordinator confirms those sources at final project acceptance.
+Record any incidental restricted-source results without treating expected access
+denial as a configuration defect. A failed check required by the commissioned
+preparation scope remains a 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,89 @@
+---
+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 prepared commission and assignment define this leg. Execute them directly;
+do not start a separate `ace-task plan` turn for the commissioned work.
+
+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. Run each `ace-*` check directly, without a pipe or
+redirection, and record its actual exit status and output in task docs; when
+it prints a file path, read that file. Never use the exit status of `head`, another pipeline command or `echo` as the check's result.
+Failed, unavailable or inconclusive 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.
+For `reporting.delivery: observe`, publish from the assignment worktree.
+The Lab Overseer's inbox is outside your mount by design. Validate the
+configured recipient address, never try to read, create or write its folder.
+Publication returns an event ID and leaves acceptance to the Lab Overseer.
+If the commission asks for a destination-folder write probe, report the
+conflicting check to the coordinator instead of attempting the write.
+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.
+
+`ace-lab prepare`, `ace-lab install` and `ace-lab verify` are host deployment
+commands in every directory. Do not run them, even in dry-run mode. Validate
+the commissioned project files and the effective installed runtime directly.
+If the assignment requires a host deployment command, fail the step and
+report the exact conflicting check to the commissioning Overseer for
+correction. End the turn after reporting.
+
+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.
+Prepare the commissioned project eyes configuration using its explicit path
+and actual configured HITL recipient. Validate its schema and the runtime paths
+available to your worker role. The Overseer start configuration uses
+`scope: project`. The eyes JSON uses `"scope": "current"` for this project
+and `"recipient"` for its configured recipient. Validate the candidate JSON
+against the installed ace-wake validator before writing it to the target path.
+Full observation includes private overseer tasks:
+the authorized coordinator confirms all sources after independent verification
+and project start. Do not require access to that private tree, host systemd or
+host-wide verification to complete your scoped preparation. Report missing
+capabilities required by your commission; never widen permissions.
+
+Checkout preparation does not run project after-create hooks, mise trust or
+bootstrap commands. Read the project's worktree setup configuration and perform
+only the setup required by this commission, under your worker identity and
+selected runtime. Record executed and inapplicable phases with evidence. The
+standalone worktree bootstrap command does not replay after-create hooks; do not
+claim those hooks ran merely because bootstrap succeeded.

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

@@ -69,9 +69,11 @@ the exact candidate head. Otherwise WITHHOLD the merge and report/escalate.
      `.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.
+   - **Test evidence**: commands and results from the worker and reviewer
+     reports for all checks required by the issue and project. Compare the
+     test scope with those requirements before accepting the reports.
+     Installed mode uses installed `ace-test`, and ACE development mode
+     uses `bin/ace-test`. Only executed checks count. CI status is advisory.
    - **Dependency states**: for each leaf the candidate depends on, whether
      its result was RECEIVED AND INTEGRATED (merged predecessor), not merely
      finished or reviewed.
@@ -98,6 +100,19 @@ the exact candidate head. Otherwise WITHHOLD the merge and report/escalate.
      verdict says accept.
 
 4. **Consume formal approval, then merge only a ready candidate.**
+   - For every forge issue run the gate with `--require-approval`. Set
+     `--approval-head` and `--approval-by` from the verified approval below,
+     and `--author` from `ace-git pr show PR --format json` on the same
+     server. Without that evidence, the gate stays blocked.
+     Stop before any merge attempt and report the missing handoff through
+     the existing assignment and report. The integrator does not publish
+     a replacement PR or substitute its own approval.
+   - A forge issue is delivered through its commissioned PR. Require the
+     worker's PR reference and the reviewer's approval for that same PR and
+     exact tested HEAD. Verify that the review covers the current forge
+     target/merge-base and the full PR delta. Missing or changed scope goes
+     back to the overseer for a renewed review. The local integration route
+     below is reserved for local-only commissions.
    - 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
@@ -112,12 +127,15 @@ the exact candidate head. Otherwise WITHHOLD the merge and report/escalate.
      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
+   - With verdict `ready` and the verified provider approval, merge the PR via
+     `ace-git pr merge PR --expected-head SHA --method METHOD` with the retained
+     server selection and commissioned merge method.
+   - For local-only commissions with verdict `ready`, perform 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
+     the result is a NEW candidate: re-run the affected checks with the
+     selected toolchain 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)
@@ -176,5 +194,5 @@ less is an error outcome with the cause named.
   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).
+- In ACE development mode, use `bin/ace-*`. With `ACE_TOOLCHAIN=installed`,
+  use installed commands and packaged instructions even inside an ACE checkout.

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

@@ -5,7 +5,7 @@ description: Reviewer role for the file-based lab. Independent of the worker; re
 doc-type: workflow
 purpose: reviewer role workflow instruction
 ace-docs:
-  last-updated: '2026-10-19'
+  last-updated: '2026-11-06'
 ---
 
 # Reviewer - Independent Review with Fixes Inside the Assignment
@@ -42,6 +42,12 @@ product decision is escalated to the overseer instead.
 - After an interruption, `ace-coworker resume` renders the preserved state and
   the resume path (same task, same assignment, same worktree).
 
+For a forge issue, ensure the pinned assignment has a final
+`publish-approval` step before starting review. Add it through `ace-assign add`
+if the commission has not prepared it. Keep that step open while reviewing
+and testing. The round verdict `accept` completes review rounds only. An
+assignment with an open publication step cannot produce a success report.
+
 ## Project Context Loading
 
 - Read and follow: `ace-bundle wfi://bundle`
@@ -63,6 +69,12 @@ product decision is escalated to the overseer instead.
      dependencies, or the overseer tree.
 
 2. **Run a review round (forge-neutral).**
+   - A task linked to a forge issue requires the worker's published PR and
+     exact tested HEAD before review starts. Read both from the accepted
+     worker assignment's step reports and reconcile them with the configured
+     forge. The issue link makes this a PR review even when the commission
+     omits the PR or calls the work local. If the PR or tested HEAD is
+     missing, report a blocked handoff to the overseer for worker publication.
    - 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
@@ -70,6 +82,32 @@ product decision is escalated to the overseer instead.
      forge selection `--server NAME` or `--default-server` (mutually
      exclusive) - never infer a forge from a hostname or the caller's
      identity.
+   - Use the session's configured project-scoped credentials for forge reads,
+     fetches and approval. When the deployment uses temporary grants, obtain
+     a grant through its configured adapter and use `ace-lab auth exec` for
+     the individual forge operation (one argument per repeated `--cmd`).
+     Keep review, model calls and tests in the ordinary installed session;
+     they do not need a forge grant. A static project token needs no lease
+     service and must not be revoked after each operation.
+   - Run the task's required checks from the assignment worktree on the
+     candidate you will approve. Confirm the scope against the issue and
+     project requirements, and record the executed commands and results.
+     Use installed `ace-test` when `ACE_TOOLCHAIN=installed`. Check the
+     test commands and their prerequisites before installing development dependencies.
+     A checkout binstub or Gemfile alone does not require `bundle install`.
+     If a required installed test tool is missing, report the readiness failure.
+     In ACE development mode use the checkout's `bin/ace-test`.
+   - For a commissioned PR, review the **full forge PR delta**. Prefer its
+     typed PR reference. If using a local diff range, first resolve the actual
+     target branch and candidate HEAD from the configured forge, fetch those
+     exact refs through your granted access, and compute their merge-base.
+     Record the full base and head SHAs and compare the selected files with the
+     forge PR diff. Local `main` may contain unpublished coordination/task
+     commits and is not evidence of the forge base. Include those commits when
+     they are part of the PR; a worker-only slice is not a full review round.
+     Missing base/head evidence or omitted PR changes blocks acceptance. After
+     candidate/base changes, re-establish the complete range for subsequent
+     full rounds; a fix-only check does not replace it.
    - `--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.
@@ -103,12 +141,12 @@ product decision is escalated to the overseer instead.
          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.
+           with the selected toolchain, 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
+     the affected checks with the selected toolchain (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>"`.
@@ -122,15 +160,19 @@ product decision is escalated to the overseer instead.
      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.
+   - For a forge PR, publish scoped fix commits to the existing PR source
+     branch before the next full round. Use the reviewer session's own
+     project-scoped credentials. Read the current PR source repository, branch and
+     HEAD from the forge. Proceed only if that HEAD is the last known PR
+     revision and the update is a fast-forward. Push the exact candidate
+     to that branch without force and re-read the PR to verify its HEAD.
+     An unexpected remote change or denied push blocks this handoff.
+   - Run a FULL round over the whole current candidate with the retained
+     forge selection and the verified forge base and HEAD. Re-read the forge
+     through the configured project access and recompute the
+     merge-base if either changes. A fix-only diff or scoped delta is
+     separate from a full round. A committed task edit also changes the
+     candidate and requires renewed review and test 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,
@@ -171,6 +213,11 @@ product decision is escalated to the overseer instead.
      `--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.
+   - Finish the `publish-approval` step with the verified receipt and
+     executed test evidence in its assignment step report. Then run
+     `ace-coworker report`. The approval receipt and its forge-verified
+     reviewer identity are the handoff. The worker's PR description does
+     not have to be editable by the reviewer.
    - 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
@@ -227,8 +274,9 @@ and reported. Anything less is an error outcome with the cause named.
 - 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).
+- With `ACE_TOOLCHAIN=installed`, use installed executables and packaged
+  instructions; the checkout is reviewed project data, never your runtime.
+  In development mode inside the ACE repository, use `bin/ace-*`.
 
 
 Deployment must provide a dedicated automation reviewer identity and one writer

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

@@ -50,6 +50,15 @@ false "work done".
      goal, the task dependencies, or the overseer tree.
 
 3. **Implement.**
+   - Checkout preparation delegates project setup to you. Inspect the project's
+     worktree configuration for after-create hooks, toolchain trust and bootstrap;
+     perform the setup needed by this assignment under your worker identity.
+     Preserve installed ACE as the operational runtime while preparing project
+     development dependencies separately. Check the commissioned test command
+     and its prerequisites before installing development dependencies. A checkout
+     Gemfile or binstub alone does not require `bundle install` in installed mode.
+     Record executed or inapplicable phases;
+     the standalone bootstrap command does not replay after-create hooks.
    - 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`
@@ -58,8 +67,15 @@ false "work done".
    - 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`.
+   - Run the task's required checks from the assignment worktree. If the
+     task and project leave the test scope unspecified, run
+     `ace-test <changed-package> all` for every changed package. Use
+     installed `ace-test` when `ACE_TOOLCHAIN=installed`. When the task
+     requires monorepo validation, run installed `ace-test-suite`.
+     Record the required commands and their results for the reviewer.
+     If a required installed test tool is missing, report the readiness failure.
+   - In ACE development mode use the checkout's `bin/ace-test` and
+     `bin/ace-test-suite` for the same checks.
    - **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
@@ -68,6 +84,23 @@ false "work done".
        error outcome naming the cause.
 
 5. **Finish and report.**
+   - Keep the final `publish-pr` step open while implementing and testing.
+     If a forge-linked assignment lacks that step, add it through
+     `ace-assign add` before completing the test step.
+   - For a task linked to a forge issue, publish the tested candidate on a
+     source branch and create or reconcile its pull request against the
+     commissioned target branch. Use the worker's scoped access and the
+     configured forge. Use `ace-git pr create --head BRANCH --base TARGET
+     --expected-head SHA --title TITLE --body-file BODY --no-draft` with the retained
+     server selection. Link the originating issue in the PR body. The full
+     pushed HEAD must match the tested HEAD. Record the PR reference, target
+     branch and exact HEAD in the worker report. If publication is unavailable
+     or uncertain, report the impediment and reconcile before retrying.
+     If the existing PR is a draft, use `ace-git pr ready PR --expected-head
+     SHA` and re-read it. Finish `publish-pr` only after verifying the
+     open, non-draft PR at
+     the exact tested HEAD. Record the evidence in that step's report.
+     For local-only work record the tested commit and that no PR applies.
    - 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
@@ -80,7 +113,8 @@ false "work done".
 ## 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),
+test declared by the task passes. When the task does not specify checks,
+run each changed package's required suite (or its monorepo gate),
 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.