hatch3r 1.4.0 → 1.5.1

package/commands/hatch3r-recipe.md

@@ -3,6 +3,7 @@ id: hatch3r-recipe
 type: command
 description: Execute shareable workflow recipes that compose agents, skills, and commands into guided sequences for common development scenarios
 tags: [core]
+quality_charter: agents/shared/quality-charter.md
 ---
 
 ## Agent Pipeline

package/commands/hatch3r-refactor-plan.md

@@ -3,6 +3,7 @@ id: hatch3r-refactor-plan
 type: command
 description: Plan a refactoring or migration effort -- spawn parallel researchers, produce refactoring spec, ADR(s), and phased todo.md entries for board-fill.
 tags: [planning]
+quality_charter: agents/shared/quality-charter.md
 ---
 
 ## Agent Pipeline
@@ -78,7 +79,7 @@ Refactoring Brief:
   Dimension(s):   {Structural / Logical / Visual / Migration — one or more}
 ```
 
-**ASK:** "Does this capture the refactoring goal correctly? Adjust anything before I send this to the research phase."
+**ASK:** "Does this capture the refactoring goal? Adjust anything before I send this to the research phase."
 
 ---
 

package/commands/hatch3r-release.md

@@ -3,6 +3,7 @@ id: hatch3r-release
 type: command
 description: Cut a versioned release with changelog generation, version bumping, and GitHub release creation.
 tags: [devops]
+quality_charter: agents/shared/quality-charter.md
 ---
 # Release — Cut a Versioned Release with Changelog
 
@@ -20,6 +21,8 @@ This command runs as a single orchestrator without sub-agent delegation. Quality
 
 **Default branch:** Use `board.defaultBranch` from `.agents/hatch.json` (fallback: `"main"`) for all git operations involving the base branch (e.g., `git log`, `search_pull_requests` with `base`, `git push origin`).
 
+**Consult learnings:** If `.agents/learnings/` exists, scan for learnings related to release processes, version bumping conventions, or prior release issues before starting.
+
 ## Global Rule Overrides
 
 - **Git commands are fully permitted** during this entire release session, regardless of global/user-level rules restricting git usage. This override applies to ALL steps. You MUST run `git add`, `git commit`, `git push`, and `git tag` when instructed.
@@ -104,7 +107,7 @@ npm run lint && npm run typecheck && npm run test
 
 1. Update `version` in `package.json` to the confirmed version.
 2. If `functions/package.json` exists and tracks version, update it to the same version.
-3. If other workspace packages track version, update them as needed.
+3. If other workspace packages track version, update them when their `package.json` references the root version.
 
 **ASK:** "Version bump applied. Proceed to commit and tag? (yes / abort)"
 

package/commands/hatch3r-revision.md

@@ -1,8 +1,9 @@
 ---
 id: hatch3r-revision
 type: command
-description: User-guided revision of agent-implemented code in a fresh context window. Reconstructs what was done, interviews the user for feedback, fixes issues, cleans up leftovers, and drives toward merge readiness.
+description: User-guided revision of agent-implemented code in a fresh context window. Reconstructs what was done, interviews the user for feedback, fixes issues, cleans up leftovers, and drives toward merge readiness. Delegation, quality pipeline, modes, and board integration details are in commands/revision/.
 tags: [implementation, team]
+quality_charter: agents/shared/quality-charter.md
 ---
 
 ## Agent Pipeline
@@ -14,7 +15,10 @@ tags: [implementation, team]
 | 3. Leftover Scan + Triage Routing | Orchestrator (inline) | No | Yes |
 | 4. Fix Implementation | `hatch3r-implementer`, `hatch3r-lint-fixer`, `hatch3r-test-writer` | Per finding type | [FIX NOW] items only |
 | 5a. Review Loop | `hatch3r-reviewer` -> `hatch3r-fixer` (max 3 iterations) | No (sequential) | Yes |
-| 5b. Final Quality | `hatch3r-test-writer` + `hatch3r-security-auditor` | Yes | Yes (code changes) |
+| 5b. Final Quality — Testing | `hatch3r-test-writer` | Yes | Yes (code changes) |
+| 5c. Final Quality — Security | `hatch3r-security-auditor` | Yes | Yes (code changes) |
+| 5d. Final Quality — Docs | `hatch3r-docs-writer` | Yes | When APIs/architecture/UX affected |
+| 5e. Final Quality — Conditional | `hatch3r-lint-fixer`, `hatch3r-a11y-auditor`, `hatch3r-perf-profiler` | Yes | When triggered |
 
 ## Browser Automation
 
@@ -36,7 +40,7 @@ The user is the reviewer. The agent is the interviewer and fixer.
 
 ## Shared Context
 
-**If board context exists** (current branch has an associated PR linked to GitHub issues), **read the `hatch3r-board-shared` command at the start of the run.** It contains Board Configuration, GitHub Context, Project Reference, and tooling directives. Cache all values for the duration of this run.
+**If board context exists** (current branch has an associated PR linked to issues), **read the `hatch3r-board-shared` command at the start of the run.** It contains Board Configuration, Platform Detection, Platform Context, Board Sync Procedure, and tooling directives. Cache all values for the duration of this run.
 
 If no board context exists (plain instruction, no PR, no linked issues), skip shared context loading and work from the git diff alone.
 
@@ -51,6 +55,10 @@ If no board context exists (plain instruction, no PR, no linked issues), skip sh
 3. **Do NOT re-read shared context files** -- their content is available via always-applied rules or inline in this command.
 4. **Limit documentation reads.** Read project documentation selectively -- TOC/headers first, full content only for relevant sections.
 
+## Run Cache
+
+Initialize the run cache at the start of the workflow. See `commands/revision/revision-board-integration.md` for the full schema. The cache tracks: diff, findings with triage routing and fix status, quality agents spawned, errors encountered.
+
 ---
 
 ## Workflow
@@ -67,16 +75,22 @@ Rebuild full context in the fresh window. No prior implementation context is ass
 2. Determine the default branch from `.agents/hatch.json` (`board.defaultBranch`). Fall back to `main` if unavailable.
 3. Compute the diff: `git diff {defaultBranch}...HEAD --stat` for a summary, then `git diff {defaultBranch}...HEAD` for the full diff.
 4. Parse the diff summary: files changed, lines added/removed, file types affected.
-5. Identify affected areas from the file paths (e.g., `src/routes/` → API, `src/components/` → UI, `tests/` → testing).
+5. Identify affected areas from the file paths (e.g., `src/routes/` -> API, `src/components/` -> UI, `tests/` -> testing).
 
 #### 1b. Find Associated PR and Issues
 
-1. Search for an open PR on this branch: `gh pr list --head {branch} --state open --json number,title,body,url --limit 1`.
-2. If a PR exists:
+> Platform-specific CLI commands: see `commands/board/shared-{platform}.md` for PR/issue lookup
+
+1. Detect the platform from `.agents/hatch.json` (`board.platform`). Fall back to GitHub if unavailable.
+2. Search for an open PR on this branch using the platform CLI:
+   - **GitHub:** `gh pr list --head {branch} --state open --json number,title,body,url --limit 1`
+   - **Azure DevOps:** `az repos pr list --source-branch {branch} --status active --top 1`
+   - **GitLab:** `glab mr list --source-branch {branch} --state opened --per-page 1`
+3. If a PR exists:
    - Read the PR body.
    - Extract linked issues from `Closes #N`, `Fixes #N`, `Relates to #N` references.
-   - For each linked issue: `gh issue view {N} --json title,body,labels` to read acceptance criteria and labels.
-3. If no PR exists: note this and work from the branch diff alone.
+   - For each linked issue: fetch title, body, labels, and acceptance criteria using the platform CLI.
+4. If no PR exists: note this and work from the branch diff alone.
 
 #### 1c. Load Project Rules
 
@@ -95,6 +109,7 @@ Present a reconstruction summary to the user:
 ```
 Revision Context:
   Branch: {branch}
+  Platform: {GitHub / Azure DevOps / GitLab}
   PR: #{N} — {title} ({url}) | No PR found
   Linked issues: #{N} — {title} (×{count}) | None
   Diff: {files_changed} files changed (+{additions} / -{deletions})
@@ -122,7 +137,7 @@ Based on the user's initial response and the diff scope, ask targeted follow-up
 
 **If UI changes detected** (components, styles, templates in diff):
 - "Any visual mismatches -- spacing, alignment, colors, typography?"
-- "Does it behave correctly at different viewport sizes?"
+- "Does it render and respond as expected at different viewport sizes?"
 - "Any interaction issues -- hover states, focus, transitions, animations?"
 
 **If API/backend changes detected** (routes, services, middleware in diff):
@@ -264,7 +279,7 @@ If the user attempts to defer a Critical finding, execute the Critical Deferral
      Deferral rationale: {user's stated rationale}
    ```
 
-4. **Flag for triage.** The `Critical-deferred` tag ensures board-fill surfaces this item with elevated visibility during the next triage cycle. Board-fill should treat `Critical-deferred` items as priority:p0 candidates regardless of other signals.
+4. **Flag for triage.** The `Critical-deferred` tag signals board-fill to surface this item with elevated visibility during the next triage cycle. Board-fill should treat `Critical-deferred` items as priority:p0 candidates regardless of other signals.
 
 The user is never blocked — this protocol adds accountability, not a veto.
 
@@ -298,7 +313,7 @@ If any findings are routed to [DEFER]:
 2. Present summary:
    `"Deferred {N} findings to todo.md. Run /hatch3r-board-fill to triage them into an epic with full dependency analysis."`
 
-3. Cache the deferred findings list for use in Steps 8 and 9.
+3. Cache the deferred findings list for use in Steps 8 and 9. Update run cache `deferred_findings`.
 
 If no findings are routed to [DEFER] (including the "fix all" shortcut), skip this sub-step entirely.
 
@@ -306,99 +321,19 @@ If no findings are routed to [DEFER] (including the "fix all" shortcut), skip th
 
 ### Step 6: Fix Implementation (Sub-Agent Delegation)
 
-Delegate [FIX NOW] findings to specialist sub-agents via the Task tool. Group findings by specialist and parallelize where possible. [DEFER] findings have been appended to `todo.md` in Step 5c and are excluded from this step.
-
-If all findings were deferred (no [FIX NOW] items), skip Step 6 entirely and proceed to Step 7.
-
-#### 6a. Group Findings by Specialist
-
-| Finding Category | Sub-Agent | Protocol |
-|-----------------|-----------|----------|
-| Bugs, missing features, error handling, logic fixes | `hatch3r-implementer` | hatch3r-implementer agent protocol |
-| Dead code, unused imports, type fixes, lint errors | `hatch3r-lint-fixer` | hatch3r-lint-fixer agent protocol |
-| Missing tests, insufficient coverage | `hatch3r-test-writer` | hatch3r-test-writer agent protocol |
-
-If findings span multiple independent areas, spawn one `hatch3r-implementer` per area to parallelize.
-
-#### 6b. Spawn Sub-Agents
-
-Use the Task tool with `subagent_type: "generalPurpose"`. Launch as many independent sub-agents in parallel as the platform supports.
+> Full details: see `commands/revision/revision-delegation.md`
 
-Each sub-agent prompt MUST include:
-- The specific findings to address (file paths, line numbers, descriptions, expected behavior).
-- Instruction to follow the corresponding agent protocol (e.g., "Follow the hatch3r-implementer agent protocol").
-- All `scope: always` rule directives from `.agents/rules/` -- sub-agents do not inherit rules automatically.
-- Acceptance criteria from linked issues (if available from Step 1b).
-- Relevant learnings from `.agents/learnings/` (if found in Step 1d).
-- Explicit instruction: do NOT create branches, commits, or PRs.
-- Confidence expression requirement: rate every recommendation and finding as high/medium/low confidence per the quality charter (`agents/shared/quality-charter.md`). High = verified against current code. Medium = pattern-based, not fully verified. Low = best judgment, recommend human review.
+Delegate [FIX NOW] findings to specialist sub-agents. The delegation protocol covers complexity assessment (using `hatch3r-deep-context` scoring), blast-radius-aware finding grouping, expanded sub-agent prompt templates, and cross-agent conflict resolution.
 
-#### 6c. Await and Integrate Results
-
-1. Await all sub-agents. Collect their structured results (files changed, tests written, issues encountered).
-2. If any sub-agent reports BLOCKED or PARTIAL, **ASK** the user how to proceed (skip, provide guidance, fix manually).
-3. If sub-agents modified overlapping files, review for conflicts and resolve.
-4. Apply all changes to the working tree.
+If all findings were deferred (no [FIX NOW] items), skip Step 6 entirely and proceed to Step 7.
 
 ---
 
 ### Step 7: Quality Verification
 
-Run the project's quality checks. Refer to `package.json` scripts, `README.md`, or `AGENTS.md` for the appropriate commands.
-
-#### 7a. Run Quality Gates
-
-1. Lint check (e.g., `npm run lint`)
-2. Type check (e.g., `npm run typecheck`)
-3. Test suite (e.g., `npm run test`)
-
-#### 7b. Verify User-Reported Issues
-
-Walk through each critical and important finding from Step 5. Verify it is addressed by the changes made in Step 6. If acceptance criteria exist from linked issues, verify each criterion.
-
-For each verified finding and acceptance criterion, rate verification confidence: high (fix confirmed via tests or direct observation), medium (code change addresses the issue but edge cases not independently tested), low (fix applied but uncertain of completeness).
-
-#### 7c. Review Loop
-
-Run an iterative review loop (max 3 iterations) until 0 Critical + 0 Warning findings remain:
+> Full details: see `commands/revision/revision-quality.md`
 
-1. Spawn `hatch3r-reviewer` sub-agent via the Task tool (`subagent_type: "generalPurpose"`).
-
-The reviewer prompt MUST include:
-- The diff of all changes made (use `git diff` on the working tree).
-- All `scope: always` rule directives from `.agents/rules/`.
-- Iteration number and previous findings (if not the first iteration).
-- Confidence expression requirement: rate every recommendation and finding as high/medium/low confidence per the quality charter (`agents/shared/quality-charter.md`). High = verified against current code. Medium = pattern-based, not fully verified. Low = best judgment, recommend human review.
-
-2. Process reviewer output:
-   - If **0 Critical and 0 Warning** findings: review loop is clean. Proceed to Step 7d.
-   - If Critical or Warning findings remain: spawn `hatch3r-fixer` sub-agent to address them, then re-run the reviewer (next iteration).
-
-3. If 3 iterations complete and findings remain, **ASK** the user whether to proceed or fix manually.
-
-After each reviewer iteration, assess the reviewer's findings confidence: if the reviewer rates any finding as low-confidence, flag it separately in the ASK prompt so the user can prioritize human review of uncertain findings.
-
-4. After any fixes, re-run quality gates (Step 7a) to verify nothing broke.
-
-#### 7d. Final Quality
-
-After the review loop is clean, spawn both agents in parallel via the Task tool:
-
-1. `hatch3r-test-writer` — write or update tests for code changes.
-2. `hatch3r-security-auditor` — security review of code changes.
-
-Both prompts MUST include:
-- The diff of all changes made.
-- All `scope: always` rule directives from `.agents/rules/`.
-- Confidence expression requirement: rate every recommendation and finding as high/medium/low confidence per the quality charter (`agents/shared/quality-charter.md`). High = verified against current code. Medium = pattern-based, not fully verified. Low = best judgment, recommend human review.
-
-Apply any resulting changes (new tests, security fixes). Re-run quality gates (Step 7a) if changes were made.
-
-#### 7e. Handle Failures
-
-- If quality checks fail: identify the specific failures, fix them directly (for simple issues) or loop back to Step 6 with specific failures.
-- Max 2 retry loops on quality check failures. After 2 retries, **ASK** the user for guidance: "Quality checks still failing. Fix confidence: {high/medium/low — based on whether root cause is identified}."
-- If a user-reported issue was not fully addressed: **ASK** the user whether to attempt another fix or defer.
+Two-stage quality pipeline: Stage 1 runs a sequential review loop (`hatch3r-reviewer` -> `hatch3r-fixer`, max 3 iterations). Stage 2 spawns final quality specialists in parallel — mandatory (`hatch3r-test-writer`, `hatch3r-security-auditor`), evaluated (`hatch3r-docs-writer`), and conditional (`hatch3r-a11y-auditor`, `hatch3r-perf-profiler`, `hatch3r-lint-fixer`).
 
 ---
 
@@ -429,6 +364,8 @@ git push
 
 If `git push` fails (e.g., remote branch does not exist yet), use `git push -u origin {branch}`.
 
+**Post-commit board integration:** If board context exists, update the PR description with a revision summary. See `commands/revision/revision-board-integration.md` for the full procedure.
+
 ---
 
 ### Step 9: Merge Readiness Assessment
@@ -459,7 +396,17 @@ Verdict: READY / NOT READY ({remaining items})
 
 A deferred finding counts as "tracked" not "unaddressed" -- it does not block merge readiness.
 
-#### 9b. Present Assessment
+#### 9b. Board Housekeeping
+
+> Full details: see `commands/revision/revision-board-integration.md`
+
+When board context exists, run the board housekeeping steps:
+- **9b.i. Refresh Board Dashboard** (mandatory when `meta:board-overview` exists).
+- **9b.ii. Lightweight Reconciliation** — verify PR body integrity, deferred findings in todo.md, and issue status consistency.
+
+When no board context exists, skip 9b entirely.
+
+#### 9c. Present Assessment
 
 **ASK:** "Revision complete. {verdict}. Options: (a) ready to merge, (b) run another revision cycle with new feedback, (c) done for now."
 
@@ -489,27 +436,8 @@ Capture revision-specific learnings. Focus on patterns that inform future implem
 
 ---
 
-## Error Handling
-
-- **Git diff failure**: If `git diff` fails (e.g., no commits on branch, detached HEAD), **ASK** the user for the correct branch or base ref.
-- **No changes detected**: If the diff is empty, inform the user and exit. There is nothing to revise.
-- **PR/issue fetch failure**: Proceed without PR/issue context. Work from the diff alone. Warn the user that acceptance criteria are unavailable.
-- **Sub-agent failure**: Retry once. If the retry fails, fall back to direct implementation for that finding.
-- **Quality check failure after 2 retries**: Present the specific failures and **ASK** the user whether to proceed with a partial fix commit or continue debugging.
-- **Push failure**: Present the error. Common fixes: `git push -u origin {branch}` for new branches, `git pull --rebase` for diverged branches.
-- **Context degradation (>25 turns)**: Suggest starting a fresh chat with a progress summary. The revision command is designed for fresh contexts -- it can be re-run.
-
-## Guardrails
-
-- **Never skip ASK checkpoints.** Every significant decision requires user confirmation.
-- **Never skip the proactive scan (Step 4)** -- even if the user reports no issues. Agents leave leftovers.
-- **Always run quality checks (Step 7)** before committing. Never commit code that fails lint, typecheck, or tests.
-- **Stay within the revision scope.** Fix what was reported and what the scan found. Do not refactor unrelated code, add new features, or expand beyond the original implementation's intent.
-- **Always commit and push** at the end of a revision cycle. The user invoked this command to get fixes merged -- do not exit without committing (unless the user explicitly abandons).
-- **Respect the original implementation's architecture.** Revision fixes issues within the existing patterns. If the architecture itself is flawed, note it as a finding but do not restructure -- suggest a separate refactor instead.
-- **One sub-agent per concern.** Delegate to specialist sub-agents based on finding type. Do not ask the implementer to also fix lint issues or write tests.
-- **Git safety.** Never force-push. Never rewrite history. Always create new commits for revision changes.
-- **This command composes existing hatch3r agents** -- it does not replace them. The reviewer, implementer, lint-fixer, and test-writer agents handle the actual work.
-- **Critical findings default to FIX NOW.** If the user overrides this, execute the Critical Deferral Protocol (Step 5b): structured warning with specific risk, require written rationale, record in todo.md with `Critical-deferred` tag, and flag for elevated triage in board-fill. The user is never blocked — rationale adds accountability, not a veto.
-- **Deferred findings go to `todo.md`, not directly to GitHub issues.** The board-fill pipeline handles triage, epic creation, dependency analysis, and readiness assessment. Revision does not shortcut this process.
-- **Always format deferred items as a single epic block** in `todo.md`, regardless of count. This ensures board-fill groups them together during the next run.
+## Auto-Advance Mode, Error Handling, and Guardrails
+
+> Full details: see `commands/revision/revision-modes.md`
+
+The modes file contains: auto-advance mode (`--auto`), safety guardrails, error handling, and session report format for revision.

package/commands/hatch3r-roadmap.md

@@ -3,6 +3,7 @@ id: hatch3r-roadmap
 type: command
 description: Generate a dual-lens phased roadmap (business milestones + technical milestones) from specs and vision using parallel researcher sub-agents, output to todo.md in the format that hatch3r-board-fill expects.
 tags: [planning, greenfield]
+quality_charter: agents/shared/quality-charter.md
 ---
 # Roadmap — Generate Phased Roadmap from Specs & Vision
 
@@ -353,7 +354,7 @@ Business-Critical Path: {biz milestone 1} → {biz milestone 2} → {launch}
 
 **ASK:** "Here is the proposed dual-lens roadmap with business and technical milestones. Review:
 - Are the business milestones and their timelines realistic?
-- Are the technical prerequisites correctly mapped?
+- Are the technical prerequisites mapped with accurate dependency links?
 - Adjust priorities, add/remove items, change grouping?
 (confirm / adjust)"
 
@@ -396,7 +397,7 @@ Write `todo.md` in the exact format that `hatch3r-board-fill` expects, with `[BI
 **Format requirements:**
 
 - Each item on one line as `- [ ] **[BIZ/TECH/BOTH] {bold title}**: {description}`.
-- Include `Ref:` with source spec/ADR path when the item was derived from a specific document. Use `docs/specs/business/` or `docs/specs/technical/` paths as appropriate.
+- Include `Ref:` with source spec/ADR path when the item was derived from a specific document. Use `docs/specs/business/` or `docs/specs/technical/` paths matching the item's category.
 - For business items: include revenue/conversion/retention impact where known.
 - For technical items: include what business milestone they enable where applicable.
 - For time-sensitive items: include deadline or market window.
@@ -465,7 +466,7 @@ If yes or review-first: spawn a `hatch3r-docs-writer` sub-agent via the Task too
 ```markdown
 # {Project Name} — Agent Instructions
 
-> Auto-generated by hatch3r-roadmap on {today's date}. Review and adjust as needed.
+> Auto-generated by hatch3r-roadmap on {today's date}. Review and adjust before use.
 
 ## Project Purpose
 
@@ -560,7 +561,7 @@ Hatch3r's breadth across 13+ adapters (Claude, Cursor, Windsurf, Cline, Copilot,
 - **Never overwrite todo.md without explicit user confirmation.**
 - **todo.md format must be compatible with board-fill** — markdown checklist with bold titles, priority headers matching `## P{N} — {Label}`, items tagged with `[BIZ]`/`[TECH]`/`[BOTH]`.
 - **Keep items at the right granularity** — epic-level for complex features (XL effort), standalone for simple tasks (S/M effort).
-- **Always reference source documentation** (specs, ADRs) where items were derived from. Use `docs/specs/business/` or `docs/specs/technical/` paths as appropriate.
+- **Always reference source documentation** (specs, ADRs) where items were derived from. Use `docs/specs/business/` or `docs/specs/technical/` paths matching the item's category.
 - **Do not duplicate work already tracked in GitHub issues.**
 - **Effort estimates are rough and clearly labeled as estimates.**
 - **Respect existing priority conventions in the project.**

package/commands/hatch3r-rule-customize.md

@@ -3,6 +3,7 @@ id: hatch3r-rule-customize
 type: command
 description: Configure per-rule customization including scope overrides, description changes, enable/disable control, and project-specific markdown instructions
 tags: [customize]
+quality_charter: agents/shared/quality-charter.md
 ---
 
 ## Agent Pipeline

package/commands/hatch3r-security-audit.md

@@ -3,6 +3,7 @@ id: hatch3r-security-audit
 type: command
 description: Create a full-product security audit epic with one sub-issue per project module
 tags: [maintenance, security]
+quality_charter: agents/shared/quality-charter.md
 ---
 
 ## Agent Pipeline

package/commands/hatch3r-skill-customize.md

@@ -3,6 +3,7 @@ id: hatch3r-skill-customize
 type: command
 description: Configure per-skill customization including description overrides, enable/disable control, and project-specific markdown instructions
 tags: [customize]
+quality_charter: agents/shared/quality-charter.md
 ---
 
 ## Agent Pipeline

package/commands/hatch3r-test-plan.md

@@ -3,6 +3,7 @@ id: hatch3r-test-plan
 type: command
 description: Plan a comprehensive test strategy -- spawn parallel researchers, produce test plan spec with coverage targets, priority ordering, test case outlines, and structured todo.md entries for board-fill.
 tags: [core, planning]
+quality_charter: agents/shared/quality-charter.md
 ---
 
 ## Agent Pipeline
@@ -58,7 +59,7 @@ Test Planning Brief:
   Constraints: {list}
 ```
 
-**ASK:** "Does this capture the test planning scope correctly? Adjust anything before I send this to the research phase."
+**ASK:** "Does this capture the test planning scope? Adjust anything before I send this to the research phase."
 
 #### Step 1b: Dimension Probing (Test Strategy Elicitation)
 
@@ -76,7 +77,7 @@ After the test planning brief is confirmed, probe for missing requirements acros
    - **Flaky test tolerance**: Existing flaky tests? Quarantine process in place? Retry budget in CI?
 3. Skip dimensions that the brief already addresses clearly.
 
-**ASK:** "Before research begins, I have {N} questions to ensure the test plan covers everything:
+**ASK:** "Before research begins, I have {N} questions to confirm the test plan covers all relevant dimensions:
 {numbered question list -- each with the dimension label and why the answer matters}
 
 Answer these now, or say 'use defaults' for any where you're comfortable with a reasonable default."

package/commands/hatch3r-workflow.md

@@ -3,6 +3,7 @@ id: hatch3r-workflow
 type: command
 description: Guided development lifecycle with 4 phases (Analyze, Plan, Implement, Review) and scale-adaptive Quick Mode for small tasks.
 tags: [core, implementation]
+quality_charter: agents/shared/quality-charter.md
 ---
 # Development Workflow -- Guided Lifecycle for Structured Implementation
 
@@ -304,6 +305,10 @@ Each specialist sub-agent prompt MUST include:
 
 Await all specialist sub-agents. Apply their feedback (fixes, additional tests, documentation updates).
 
+#### 4b.1. Re-Review After Phase 4 Fixes
+
+If any Phase 4 specialist produced fixes (not just findings), run a lightweight re-review to catch regressions introduced by the specialist changes. Spawn `hatch3r-reviewer` with a focused prompt covering only the files modified by Phase 4 specialists. If the re-review finds Critical findings, spawn `hatch3r-fixer` and re-review once more (max 1 additional iteration). This prevents Phase 4 fixes from bypassing the review gate.
+
 #### 4c. Verify Against Acceptance Criteria
 
 Check each acceptance criterion from the original task or issue. Mark as met or not-met with evidence.

package/commands/revision/revision-board-integration.md

@@ -0,0 +1,87 @@
+---
+id: hatch3r-revision-board-integration
+type: command
+description: Board integration for revision. Covers run cache schema, post-commit PR updates, dashboard refresh (Step 9a), and lightweight reconciliation (Step 9b).
+tags: [implementation, team]
+quality_charter: agents/shared/quality-charter.md
+---
+# Revision — Board Integration
+
+Board integration protocols for `hatch3r-revision`. Referenced from the core command file. All board integration steps are conditional — they execute only when board context exists (PR with linked issues found in Step 1b). When no board context exists, skip all steps in this file silently.
+
+---
+
+## Run Cache
+
+Initialize at the start of the revision workflow (before Step 1). Maintain throughout the run:
+
+| Key | Type | Description |
+|-----|------|-------------|
+| `diff_cache` | `string` | Cached diff from Step 1 (reused per token-saving directives) |
+| `findings` | `Map<id, {description, severity, route, status}>` | All findings with triage routing and fix status |
+| `fixed_findings` | `id[]` | Finding IDs resolved in this run |
+| `deferred_findings` | `id[]` | Finding IDs written to todo.md |
+| `quality_agents` | `{agent, status, findings_count}[]` | Specialist agents spawned and their results |
+| `pr_updated` | `boolean` | Whether PR description was updated with revision summary |
+| `errors` | `{step, message, recoverable}[]` | All errors encountered during the run |
+
+---
+
+## Post-Commit Board Integration (After Step 8)
+
+After committing and pushing revision changes, update the PR if board context exists:
+
+1. **Update PR description** with a revision summary appended to the existing body:
+
+   ```markdown
+   ---
+   ## Revision Summary ({date})
+   
+   **Fixed ({N}):**
+   - {finding description} ({severity})
+   - ...
+   
+   **Deferred to todo.md ({M}):**
+   - {finding description} ({severity})
+   - ...
+   
+   **Quality agents:** {list of agents spawned}
+   **Overall confidence:** {high/medium/low}
+   ```
+
+2. Do NOT change issue status labels. Revision does not alter the issue lifecycle — the original PR's `Closes #N` references handle that on merge.
+
+3. Do NOT modify `Closes #N` / `Relates to #N` references in the PR body. The original references from board-pickup are authoritative.
+
+---
+
+## Step 9a: Refresh Board Dashboard
+
+**This step is mandatory when board context exists. Skip silently when no board context.**
+
+If a `meta:board-overview` issue exists on the board, refresh it now using cached board data. Use the same procedure as `hatch3r-board-pickup` Step 9a: update with current board state reflecting any changes from this revision session.
+
+Do NOT re-fetch all issues. Use cached data from Step 1 combined with mutations from this run (findings fixed, PR updated). Skip silently if no `meta:board-overview` issue exists.
+
+---
+
+## Step 9b: Lightweight Reconciliation
+
+**This step is mandatory when board context exists. Skip silently when no board context.**
+
+Run a focused reconciliation (not the full board-shared reconciliation procedure, since revision does not create or update issues):
+
+1. **PR body integrity:** Verify the PR body still contains correct `Closes #N` references for all linked issues after the revision summary was appended. If any references were accidentally removed or corrupted, restore them.
+
+2. **Deferred findings integrity:** If findings were deferred in Step 5c, verify they are written to `todo.md` with correct severity tags and epic grouping format. Report any write failures.
+
+3. **Orphaned status check:** For each issue linked to this PR, verify the issue still has `status:in-review` label. If any issue has drifted to a different status (e.g., manually changed during the revision session), warn the user.
+
+Output a reconciliation report:
+
+```
+Reconciliation:
+  PR body: {ok / {N} references restored}
+  Deferred findings: {ok / {N} write failures}
+  Issue status: {ok / {N} status drift warnings}
+```

package/commands/revision/revision-delegation.md

@@ -0,0 +1,93 @@
+---
+id: hatch3r-revision-delegation
+type: command
+description: Fix delegation protocol for revision Step 6. Covers complexity-aware grouping, blast radius context, sub-agent prompt templates, and cross-agent conflict resolution.
+tags: [implementation, team]
+quality_charter: agents/shared/quality-charter.md
+---
+# Revision — Fix Delegation (Step 6)
+
+Delegation details for Step 6 of `hatch3r-revision`. Referenced from the core command file.
+
+---
+
+## 6.pre: Complexity Assessment
+
+Before delegating [FIX NOW] findings, score the aggregate fix batch using `hatch3r-deep-context` complexity signals. Score across the full set of findings, not per-finding:
+
+| Signal | Weight | Detection |
+|--------|--------|-----------|
+| Findings span multiple modules/layers | +3 | Count distinct directories across all [FIX NOW] findings |
+| Any finding involves behavioral contract changes (API, types, events) | +2 | Check finding descriptions for interface/signature changes |
+| Findings touch security-sensitive areas (auth, payments, data access) | +2 | Match affected files against security-sensitive directories |
+| Total affected files > 5 | +2 | Count distinct files across all findings |
+| Any finding requires new dependencies or integrations | +2 | Check whether fixes introduce new imports or services |
+
+### Tier Assignment
+
+| Total Weight | Tier | Action |
+|-------------|------|--------|
+| 0–2 | 1 (Light) | Proceed directly to 6a. No research needed |
+| 3–5 | 2 (Standard) | Spawn `hatch3r-researcher` with `similar-implementation` at `quick` depth before delegating. Use discovered reference patterns to inform fix conventions |
+| 6+ | 3 (Deep) | Spawn `hatch3r-researcher` with `codebase-impact` at `deep` depth. **Warn the user** that fix scope may warrant a new board issue rather than a revision fix |
+
+For Tier 2/3: cache researcher output (reference conventions, blast radius data) for inclusion in sub-agent prompts below.
+
+---
+
+## 6a. Group Findings by Specialist
+
+| Finding Category | Sub-Agent | Protocol |
+|-----------------|-----------|----------|
+| Bugs, missing features, error handling, logic fixes | `hatch3r-implementer` | hatch3r-implementer agent protocol |
+| Dead code, unused imports, type fixes, lint errors | `hatch3r-lint-fixer` | hatch3r-lint-fixer agent protocol |
+| Missing tests, insufficient coverage | `hatch3r-test-writer` | hatch3r-test-writer agent protocol |
+
+### Blast-Radius-Aware Grouping
+
+When multiple findings affect the same file or module, batch them to a single sub-agent to avoid cross-agent file conflicts:
+
+1. Build a file-to-findings map from all [FIX NOW] items.
+2. Findings in the same file go to the same sub-agent instance, even if they span categories (use the highest-priority specialist: implementer > lint-fixer > test-writer).
+3. Findings in disjoint files can run in parallel sub-agents.
+4. If findings span independent areas within the same specialist type, spawn one sub-agent per area to parallelize.
+
+---
+
+## 6b. Spawn Sub-Agents
+
+Use the Task tool with `subagent_type: "generalPurpose"`. Launch independent sub-agents in parallel.
+
+Each sub-agent prompt MUST include:
+
+1. The specific findings to address (file paths, line numbers, descriptions, expected behavior).
+2. Instruction to follow the corresponding agent protocol (e.g., "Follow the hatch3r-implementer agent protocol").
+3. All `scope: always` rule directives from `.agents/rules/` — sub-agents do not inherit rules automatically.
+4. Acceptance criteria from linked issues (if available from Step 1b).
+5. Relevant learnings from `.agents/learnings/` (if found in Step 1d).
+6. Explicit instruction: do NOT create branches, commits, or PRs.
+7. Confidence expression requirement: rate every recommendation and finding as high/medium/low confidence per the quality charter (`agents/shared/quality-charter.md`). High = verified against current code. Medium = pattern-based, not fully verified. Low = best judgment, recommend human review.
+8. Revision-specific constraint: "You are fixing existing code, not implementing new features. Stay within the architecture established by the original implementation."
+
+**When Tier 2/3 research was performed (6.pre):**
+
+9. Reference conventions from `similar-implementation` output — triggers the implementer's Convention Lock step.
+10. Blast radius data from `codebase-impact` output (Tier 3) — transitive dependency trace informing which consumers and contracts the fix must preserve.
+
+---
+
+## 6c. Await and Integrate Results
+
+1. Await all sub-agents. Collect their structured results (files changed, tests written, issues encountered).
+2. If any sub-agent reports BLOCKED or PARTIAL, **ASK** the user how to proceed (skip, provide guidance, fix manually).
+
+### Cross-Agent Conflict Resolution
+
+When sub-agents modified overlapping files:
+
+- **Disjoint regions** (different functions, different sections): accept both sets of changes.
+- **Overlapping regions** (same function or block): merge using the larger-scope change as the base, applying the smaller change on top. If merging is ambiguous, present both versions to the user.
+- **Semantic conflicts** (contradictory logic): surface to the user with both sub-agents' rationale. Do not auto-resolve semantic conflicts.
+
+3. Apply all resolved changes to the working tree.
+4. Update the run cache with fix results (files changed, findings addressed).