hatch3r 1.5.0 → 1.6.0

package/commands/hatch3r-onboard.md

@@ -1,6 +1,8 @@
 ---
 id: hatch3r-onboard
 type: command
+orchestrator: true
+agentPipeline: [hatch3r-researcher, hatch3r-docs-writer]
 description: Generate a comprehensive onboarding guide for a new developer joining the project -- spawn parallel researchers to analyze codebase structure, architecture, and conventions, then produce a tailored onboarding document with setup instructions, architecture walkthrough, coding conventions, key workflows, tribal knowledge, and a quick-reference cheat sheet.
 tags: [brownfield, team]
 quality_charter: agents/shared/quality-charter.md

package/commands/hatch3r-project-spec.md

@@ -1,7 +1,9 @@
 ---
 id: hatch3r-project-spec
 type: command
-description: Generate complete business and technical project documentation (specs, ADRs, todo.md) from a project vision using parallel researcher sub-agents with dual business/technical scoping.
+orchestrator: true
+agentPipeline: [hatch3r-researcher, hatch3r-docs-writer]
+description: Translate a greenfield vision into future-state design artifacts -- ADRs, domain model, API contracts, per-module technical specs, and a board-ready todo.md
 tags: [planning, greenfield]
 quality_charter: agents/shared/quality-charter.md
 ---

package/commands/hatch3r-quick-change.md

@@ -1,6 +1,8 @@
 ---
 id: hatch3r-quick-change
 type: command
+orchestrator: true
+agentPipeline: [hatch3r-implementer, hatch3r-lint-fixer, hatch3r-reviewer, hatch3r-fixer, hatch3r-test-writer, hatch3r-security-auditor]
 description: Lightweight command for small changes not worth tracking on the board. Adaptive ceremony with inline or sub-agent implementation, batch support, and soft scope guards.
 tags: [core, implementation]
 quality_charter: agents/shared/quality-charter.md
@@ -65,6 +67,14 @@ It retains:
 4. **No learnings capture.** Quick changes are too small to produce meaningful learnings. Existing learnings are consulted via a lightweight file-path scan (Step 2c) with a 150-token budget — no new learnings are written.
 5. **Minimal rule loading.** Load `scope: always` rules only when spawning sub-agents in Steps 4b or 6.
 
+## Confidence Propagation Contract
+
+Every sub-agent delegation prompt in this command MUST include the confidence expression requirement below (verbatim). Sub-agents are invoked with the `quality_charter: agents/shared/quality-charter.md` reference in their frontmatter, but the orchestrator repeats the directive to override runtime prompt defaults per the charter §1 rule.
+
+> 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.
+
+Downstream propagation: every ASK checkpoint that reports verification quality, every gate that evaluates a sub-agent verdict, and every output block that surfaces merge-readiness MUST carry a high/medium/low confidence rating sourced from the upstream sub-agent. Dropping the signal between stages is a gate failure.
+
 ---
 
 ## Workflow
@@ -259,9 +269,11 @@ The reviewer prompt MUST include:
 - 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.
+- Requirement that the reviewer output include a top-level `confidence: high | medium | low` field (not just per-finding) so the gate in step 2 can evaluate it deterministically.
 
-2. Process reviewer output:
-   - If **0 Critical and 0 Warning** findings: review loop is clean. Proceed to Step 6b.
+2. Process reviewer output (confidence-aware gate):
+   - If **0 Critical + 0 Warning AND reviewer confidence != low**: review loop is clean. Proceed to Step 6b.
+   - If **0 Critical + 0 Warning AND reviewer confidence == low**: trigger a second reviewer pass before exiting. Do not proceed to 6b until the second pass returns non-low confidence OR the user explicitly accepts the low-confidence PASS.
    - If Critical or Warning findings remain: spawn `hatch3r-fixer` sub-agent to address them, then re-run the reviewer (next iteration).
      The fixer prompt MUST include: the reviewer findings, all `scope: always` rule directives, and the confidence expression requirement (high/medium/low per the quality charter).
    - **Suggestions**: skip. The point of quick-change is speed.

package/commands/hatch3r-recipe.md

@@ -1,6 +1,7 @@
 ---
 id: hatch3r-recipe
 type: command
+orchestrator: false
 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

package/commands/hatch3r-refactor-plan.md

@@ -1,6 +1,8 @@
 ---
 id: hatch3r-refactor-plan
 type: command
+orchestrator: true
+agentPipeline: [hatch3r-researcher, hatch3r-docs-writer]
 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

package/commands/hatch3r-release.md

@@ -1,6 +1,7 @@
 ---
 id: hatch3r-release
 type: command
+orchestrator: false
 description: Cut a versioned release with changelog generation, version bumping, and GitHub release creation.
 tags: [devops]
 quality_charter: agents/shared/quality-charter.md

package/commands/hatch3r-revision.md

@@ -1,7 +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.
+orchestrator: true
+agentPipeline: [hatch3r-implementer, hatch3r-lint-fixer, hatch3r-test-writer, hatch3r-reviewer, hatch3r-fixer, hatch3r-security-auditor, hatch3r-docs-writer, hatch3r-a11y-auditor, hatch3r-perf-profiler]
+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
 ---
@@ -15,7 +17,10 @@ quality_charter: agents/shared/quality-charter.md
 | 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
 
@@ -37,7 +42,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.
 
@@ -52,6 +57,18 @@ 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.
 
+## Confidence Propagation Contract
+
+Every sub-agent delegation prompt in this command (including those defined in `commands/revision/revision-delegation.md` and `commands/revision/revision-quality.md`) MUST include the confidence expression requirement below (verbatim). Sub-agents are invoked with the `quality_charter: agents/shared/quality-charter.md` reference in their frontmatter, but the orchestrator repeats the directive to override runtime prompt defaults per the charter §1 rule.
+
+> 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.
+
+Downstream propagation: every ASK checkpoint that reports verification quality, every gate that evaluates a sub-agent verdict, and every output block that surfaces merge-readiness MUST carry a high/medium/low confidence rating sourced from the upstream sub-agent. Dropping the signal between stages is a gate failure.
+
+## 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
@@ -68,16 +85,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
 
@@ -96,6 +119,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})
@@ -265,7 +289,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.
 
@@ -299,7 +323,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.
 
@@ -307,99 +331,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 |
+> Full details: see `commands/revision/revision-delegation.md`
 
-If findings span multiple independent areas, spawn one `hatch3r-implementer` per area to parallelize.
+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.
 
-#### 6b. Spawn Sub-Agents
-
-Use the Task tool with `subagent_type: "generalPurpose"`. Launch as many independent sub-agents in parallel as the platform supports.
-
-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.
-
-#### 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).
+> Full details: see `commands/revision/revision-quality.md`
 
-#### 7c. Review Loop
-
-Run an iterative review loop (max 3 iterations) until 0 Critical + 0 Warning findings remain:
-
-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`).
 
 ---
 
@@ -430,6 +374,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
@@ -460,7 +406,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."
 
@@ -490,27 +446,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

@@ -1,7 +1,9 @@
 ---
 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.
+orchestrator: true
+agentPipeline: [hatch3r-researcher, hatch3r-docs-writer]
+description: Sequence delivery phases over time into a dependency-ordered milestone plan with business and technical lenses, emitting a todo.md rollout schedule rather than design docs
 tags: [planning, greenfield]
 quality_charter: agents/shared/quality-charter.md
 ---

package/commands/hatch3r-rule-customize.md

@@ -1,7 +1,8 @@
 ---
 id: hatch3r-rule-customize
 type: command
-description: Configure per-rule customization including scope overrides, description changes, enable/disable control, and project-specific markdown instructions
+orchestrator: false
+description: Edit rule scope globs, toggle always-on versus conditional activation, and adjust precedence tier via .hatch3r/rules/ YAML overrides plus markdown appends
 tags: [customize]
 quality_charter: agents/shared/quality-charter.md
 ---

package/commands/hatch3r-security-audit.md

@@ -1,7 +1,8 @@
 ---
 id: hatch3r-security-audit
 type: command
-description: Create a full-product security audit epic with one sub-issue per project module
+orchestrator: false
+description: Open an OWASP ASI security epic reviewing auth boundaries, input validation, and supply-chain risks with one hardening sub-issue per module plus trust-boundary audit
 tags: [maintenance, security]
 quality_charter: agents/shared/quality-charter.md
 ---

package/commands/hatch3r-skill-customize.md

@@ -1,7 +1,8 @@
 ---
 id: hatch3r-skill-customize
 type: command
-description: Configure per-skill customization including description overrides, enable/disable control, and project-specific markdown instructions
+orchestrator: false
+description: Rewrite skill dispatch descriptions for model auto-selection, gate per-preset exposure, and control slash-command surfacing via .hatch3r/skills/ YAML overrides
 tags: [customize]
 quality_charter: agents/shared/quality-charter.md
 ---

package/commands/hatch3r-test-plan.md

@@ -1,6 +1,8 @@
 ---
 id: hatch3r-test-plan
 type: command
+orchestrator: true
+agentPipeline: [hatch3r-researcher, hatch3r-docs-writer]
 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

package/commands/hatch3r-workflow.md

@@ -1,6 +1,8 @@
 ---
 id: hatch3r-workflow
 type: command
+orchestrator: true
+agentPipeline: [hatch3r-researcher, hatch3r-implementer, hatch3r-reviewer, hatch3r-fixer, hatch3r-test-writer, hatch3r-security-auditor, hatch3r-docs-writer, hatch3r-lint-fixer, hatch3r-a11y-auditor, hatch3r-perf-profiler]
 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
@@ -47,6 +49,14 @@ If **no**: all browser verification steps are skipped silently throughout the en
 
 Follow the **Token-Saving Directives** in `hatch3r-board-shared`.
 
+## Confidence Propagation Contract
+
+Every sub-agent delegation prompt in this command MUST include the confidence expression requirement below (verbatim). Sub-agents are invoked with the `quality_charter: agents/shared/quality-charter.md` reference in their frontmatter, but the orchestrator repeats the directive to override runtime prompt defaults per the charter §1 rule.
+
+> 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.
+
+Downstream propagation: every ASK checkpoint that reports verification quality, every gate that evaluates a sub-agent verdict, and every output block that surfaces merge-readiness MUST carry a high/medium/low confidence rating sourced from the upstream sub-agent. Dropping the signal between stages is a gate failure.
+
 ---
 
 ## Workflow
@@ -262,13 +272,15 @@ Fix any issues before proceeding. If quality checks fail, loop back and resolve
 
 Spawn a `hatch3r-reviewer` sub-agent via the Task tool (`subagent_type: "generalPurpose"`). Include the diff and acceptance criteria in the prompt.
 
-1. **Review:** Await the reviewer result. Check for Critical and Warning findings.
-2. **If 0 Critical + 0 Warning:** Review loop is clean. Proceed to 4b.
+1. **Review:** Await the reviewer result. Extract Critical and Warning findings AND the reviewer's top-level `confidence` field (high/medium/low).
+2. **Confidence-aware gate:**
+   - **0 Critical + 0 Warning AND reviewer confidence != low:** Review loop is clean. Proceed to 4b.
+   - **0 Critical + 0 Warning AND reviewer confidence == low:** Trigger a second reviewer pass before exiting. Do not proceed to 4b until the second pass returns non-low confidence OR the user explicitly accepts the low-confidence PASS at the ASK checkpoint in step 5.
 3. **If Critical or Warning findings exist:** Spawn a `hatch3r-fixer` sub-agent with the reviewer output. The fixer applies fixes for all Critical and Warning findings.
 4. **Re-review:** After the fixer completes, spawn `hatch3r-reviewer` again to verify fixes.
 5. **Repeat** steps 2-4 for a maximum of **3 iterations**. If still not clean after 3 iterations, **ASK** the user how to proceed (force continue / manual fix / abort).
 
-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.
+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. The reviewer sub-agent output MUST include a top-level `confidence: high | medium | low` field (not just per-finding) so step 2 can evaluate it deterministically.
 
 Each reviewer/fixer sub-agent prompt MUST include:
 - The agent protocol to follow.

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).