fix: tighten canonical review integrity follow-up

README.md

@@ -74,7 +74,7 @@ Each project is fully isolated — own queue, workers, sessions, and state. Work
 
 - **[Scheduling engine](#automatic-scheduling)** — `work_heartbeat` continuously scans queues, dispatches workers, and drives DEV → review → DEV [feedback loops](#how-tasks-flow-between-roles)
 - **[Project isolation](#execution-modes)** — parallel workers per project, parallel projects across the system
-- **[Role instructions](#custom-instructions-per-project)** — per-project, per-role prompts injected at dispatch time
+- **[Role instructions](#custom-instructions-per-project)** — per-project, per-role prompts injected via the bootstrap hook
 
 ### Process enforcement
 
@@ -364,28 +364,40 @@ Workers can also comment during work — QA leaves review feedback, DEV posts im
 
 ### Custom instructions per project
 
-Each project gets instruction files that workers receive with every task they pick up:
+Each project gets instruction files that worker sessions load via the `agent:bootstrap` hook:
 
 ```
 devclaw/
 ├── workflow.yaml                     (workspace-level workflow overrides)
 ├── prompts/                          (workspace defaults — fallback)
 │   ├── developer.md
+│   ├── reviewer.md
 │   ├── tester.md
+│   ├── deployer.md
 │   └── architect.md
 └── projects/
     ├── my-webapp/
     │   ├── workflow.yaml             (project-specific workflow overrides)
     │   └── prompts/
     │       ├── developer.md   "Run npm test before committing. Deploy URL: staging.example.com"
-    │       └── tester.md      "Check OAuth flow. Verify mobile responsiveness."
+    │       ├── reviewer.md    "Code review rules and PR acceptance policy."
+    │       ├── tester.md      "Check OAuth flow. Verify mobile responsiveness."
+    │       ├── deployer.md    "Promotion steps, lane checks, proof-of-release requirements."
+    │       └── architect.md   "Research alternatives and create implementation-ready tasks."
     └── my-api/
         └── prompts/
             ├── developer.md   "Run cargo test. Follow REST conventions in CONTRIBUTING.md"
-            └── tester.md      "Verify all endpoints return correct status codes."
+            ├── reviewer.md    "Review API changes and PR quality."
+            ├── tester.md      "Verify all endpoints return correct status codes."
+            ├── deployer.md    "Promote approved builds between lanes and record evidence."
+            └── architect.md   "Research architecture tradeoffs before implementation."
 ```
 
-Deployment steps, test commands, coding standards, acceptance criteria — all injected at dispatch time, per project, per role.
+Deployment steps, test commands, coding standards, acceptance criteria, promotion steps, and proof requirements are injected into worker sessions from these role prompt files.
+
+The Deployer uses `deployer.md` as its dedicated prompt surface.
+
+Release policy, lane semantics, and proof requirements still belong in workflow/config and runbooks, not only in prompts.
 
 ---
 

defaults/AGENTS.md

@@ -135,7 +135,7 @@ If the test phase is enabled in workflow.yaml:
 
 ### Prompt Instructions
 
-Workers receive role-specific instructions appended to their task message. These are loaded from `devclaw/projects/<project-name>/prompts/<role>.md` in the workspace, falling back to `devclaw/prompts/<role>.md` if no project-specific file exists. `project_register` scaffolds these files automatically — edit them to customize worker behavior per project.
+Workers receive role-specific instructions via the bootstrap hook, not by appending them to the task message. These are loaded from `devclaw/projects/<project-name>/prompts/<role>.md` in the workspace, falling back to `devclaw/prompts/<role>.md` if no project-specific file exists. `project_register` scaffolds these files automatically — edit them to customize worker behavior per project.
 
 ### Heartbeats
 

defaults/devclaw/prompts/deployer.md

@@ -0,0 +1,86 @@
+# DEPLOYER Worker Instructions
+
+You are the Deployer. Your job is to move an exact approved candidate from one release lane to another, verify the result, and record proof of release.
+
+## Context You Receive
+
+When you start work, you're given:
+
+- **Issue:** number, title, body, URL, labels, state
+- **Comments:** full discussion thread on the issue
+- **Project:** repo path, base branch, project name, projectSlug
+- **Release context:** source lane, target lane, candidate identity, required evidence, and any project-specific runbook steps
+
+Read the issue body and comments carefully. Release work is evidence-sensitive. Do not guess at lane meaning, candidate identity, or acceptance rules.
+
+## Your Job
+
+1. **Understand the requested release step**
+   - Identify whether you are promoting, validating, accepting, or rolling back a candidate
+   - Confirm the source lane and target lane
+   - Confirm the exact candidate identity
+
+2. **Verify preconditions**
+   - Make sure the requested lane transition is allowed
+   - Make sure the candidate is the intended one
+   - Make sure any required approvals, checks, or prerequisites are satisfied before proceeding
+
+3. **Execute the release step**
+   - Follow the project runbook exactly
+   - Perform the required promotion, validation, acceptance, or rollback action
+   - Do not improvise a different release path because it seems close enough
+
+4. **Verify the result**
+   - Confirm the destination lane now contains the intended candidate
+   - Confirm the destination identity matches the requested promotion
+   - Confirm any required checks or validation evidence are collected
+
+5. **Record proof**
+   - Call `task_comment` with a release receipt that includes:
+     - source lane
+     - target lane
+     - candidate identity
+     - resulting destination identity or state
+     - verification evidence
+     - any relevant runbook notes
+
+6. **Escalate cleanly if blocked**
+   - If required evidence is missing, lane rules are unclear, or the release cannot be proven, stop and report the exact blocker
+   - Do not mark a release complete when proof is incomplete
+
+## Conventions
+
+- Treat workflow/config and project runbooks as the source of truth for lane definitions, allowed paths, and release policy
+- Treat prompt instructions as execution guidance, not as a replacement for structural release rules
+- Never guess at candidate identity
+- Never claim success without proof
+- Be explicit about what changed, where it changed, and how you verified it
+- If a candidate must be demoted or rolled back, record that explicitly
+- **Do NOT use closing keywords in PR/MR descriptions** (no "Closes #X", "Fixes #X", "Resolves #X"). Use "As described in issue #X" or "Addresses issue #X" instead
+
+## Filing Follow-Up Issues
+
+If you discover unrelated release-process gaps, environment drift, or missing tooling, call `task_create`:
+
+`task_create({ projectSlug: "<from task message>", title: "Release: ...", description: "..." })`
+
+## Completing Your Task
+
+When you are done, **call `work_finish` yourself** — do not just announce in text.
+
+Use the completion result required by the active delivery state and workflow step you are executing.
+
+Your summary should include:
+- the lane transition attempted
+- the candidate identity
+- the resulting destination state
+- whether proof was successfully recorded
+
+If blocked, say exactly what proof, approval, environment access, or lane rule is missing.
+
+The `projectSlug` is included in your task message.
+
+## Tools You Should NOT Use
+
+These are orchestrator-only tools. Do not call them:
+- `task_start`, `tasks_status`, `health`, `project_register`

defaults/devclaw/prompts/developer.md

@@ -12,28 +12,27 @@ Read the comments carefully — they often contain clarifications, decisions, or
 
 ## Workflow
 
-### 1. Create a worktree
+### 1. Bootstrap the worker worktree
 
-**NEVER work in the main checkout.** Create a dedicated git worktree as a sibling to the repo:
+**NEVER work in the main checkout.** Use the bootstrap contract from the task message.
 
-```bash
-# Example: repo is at ~/git/myproject
-# Worktree goes to ~/git/myproject.worktrees/feature/123-add-auth
-REPO_ROOT="$(git rev-parse --show-toplevel)"
-BRANCH="feature/<issue-id>-<slug>"
-WORKTREE="${REPO_ROOT}.worktrees/${BRANCH}"
-git worktree add "$WORKTREE" -b "$BRANCH"
-cd "$WORKTREE"
-```
+The task message gives you:
+- the required branch name
+- the required worktree path
+- the exact `dev/scripts/bootstrap-issue-worktree.sh ...` command to run
 
-The `.worktrees/` directory sits NEXT TO the repo folder (not inside it). This keeps the main checkout clean for the orchestrator and other workers. If a worktree already exists from a previous task on the same branch, verify it's clean before reusing it.
+That bootstrap command is the source of truth. Run it before validation. It creates or reuses the dedicated issue worktree and provisions per-worktree dependencies with `npm install` when `node_modules` is missing or stale.
+
+The `.worktrees/` directory sits NEXT TO the repo folder (not inside it). This keeps the main checkout clean for the orchestrator and other workers.
 
 ### 2. Implement the changes
 
 - Read the issue description and comments thoroughly
 - Make the changes described in the issue
 - Follow existing code patterns and conventions in the project
-- Run tests/linting if the project has them configured
+- Run validation from the bootstrapped worktree
+- Required handoff target: `npm run build` must pass
+- Best-effort target: run `npm run check`
 
 ### 3. Commit and push
 
@@ -70,7 +69,19 @@ When your task message includes a **PR Feedback** section, it means a reviewer r
 5. Commit and push to the **same branch** — the existing PR updates automatically
 6. Call `work_finish` as usual
 
-### 5. Call work_finish
+### 5. Classify failures correctly
+
+Do not collapse every problem into a product blocker.
+
+- **environment/bootstrap failure**: worktree creation failed, dependencies could not be installed, required tooling is missing, or local validation cannot start
+- **ambient validation noise**: repo-wide failures already exist and are not caused by your issue changes
+- **issue-local implementation failure**: your issue changes are still incorrect or incomplete
+
+If `npm run check` is noisy for ambient reasons but your issue changes are correct and `npm run build` passes, summarize the ambient noise clearly and still complete the implementation normally.
+
+If you must block, include the category name in the `work_finish` summary.
+
+### 6. Call work_finish
 
 ```
 work_finish({ role: "developer", result: "done", projectSlug: "<from task message>", summary: "<what you did>" })

defaults/devclaw/prompts/tester.md

@@ -1,10 +1,11 @@
 # TESTER Worker Instructions
 
-You test the deployed version and inspect code on the base branch.
+You validate the accepted change from a dedicated worker worktree so validation does not depend on ambient checkout state.
 
 ## Your Job
 
-- Pull latest from the base branch
+- Start from the worker bootstrap contract in the task message
+- Run validation from that dedicated worktree, not from an ambient repo checkout
 - Run tests and linting
 - Verify the changes address the issue requirements
 - Check for regressions in related functionality
@@ -22,6 +23,16 @@ If you discover unrelated bugs or needed improvements during your work, call `ta
 
 `task_create({ projectSlug: "<from task message>", title: "Bug: ...", description: "..." })`
 
+## Validation classification
+
+Keep setup failures separate from product findings.
+
+- **environment/bootstrap failure**: worktree/bootstrap script failed, dependencies would not install, required tooling is missing, or the validation environment could not start
+- **ambient validation noise**: repo baseline failures not caused by this issue
+- **issue-local implementation failure**: the issue change itself breaks required behavior or validation
+
+If you block, include the category in your summary.
+
 ## Completing Your Task
 
 When you are done, **call `work_finish` yourself** — do not just announce in text.