hatch3r 1.3.0 → 1.5.0

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

@@ -3,6 +3,7 @@ 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.
 tags: [implementation, team]
+quality_charter: agents/shared/quality-charter.md
 ---
 
 ## Agent Pipeline
@@ -11,8 +12,8 @@ tags: [implementation, team]
 |-------|----------|----------|----------|
 | 1. Context Reconstruction | Orchestrator (inline) | No | Yes |
 | 2. User Feedback | User interview (ASK checkpoints) | No | Yes |
-| 3. Leftover Scan | Orchestrator (inline) | No | Yes |
-| 4. Fix Implementation | `hatch3r-implementer`, `hatch3r-lint-fixer`, `hatch3r-test-writer` | Per finding type | Yes |
+| 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) |
 
@@ -122,7 +123,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):
@@ -180,7 +181,7 @@ For each leftover found, record:
 
 ---
 
-### Step 5: Findings Consolidation and Triage
+### Step 5: Findings Consolidation and Triage Routing
 
 Merge user feedback (Step 3) and proactive scan results (Step 4) into a single prioritized list:
 
@@ -189,35 +190,126 @@ Merge user feedback (Step 3) and proactive scan results (Step 4) into a single p
 - **Cleanup**: Leftovers detected by scan -- dead code, TODOs, type issues, error handling gaps
 - **Cosmetic**: Style improvements, naming, comment cleanup, minor readability enhancements
 
-Present the consolidated findings:
+#### 5a. Suggest Routing
+
+For each finding, suggest whether it should be fixed in this revision session or deferred to the board for later implementation via `board-fill`.
+
+**Routing heuristics:**
+
+| Severity | Condition | Default Route |
+|----------|-----------|---------------|
+| Critical | Any | FIX NOW (warn if user overrides) |
+| Important | Affects files already in the diff + matches acceptance criteria | FIX NOW |
+| Important | Outside PR scope / requires new files / architectural change | DEFER |
+| Cleanup | Quick fix in diff files (single line, import cleanup, typo) | FIX NOW |
+| Cleanup | Substantial scope / new files needed / cross-cutting | DEFER |
+| Cosmetic | Any | DEFER |
+
+Present the consolidated findings with routing markers:
 
 ```
 Revision Findings ({N} total):
 
 Critical ({n}):
-  1. {description} — {file:line}
+  1. {description} — {file:line} → [FIX NOW]
   2. ...
 
 Important ({n}):
-  1. {description} — {file:line}
-  2. ...
+  1. {description} — {file:line} → [FIX NOW]
+     (in diff files, matches acceptance criteria)
+  2. {description} — {file:line} → [DEFER]
+     (outside PR scope, requires new files)
+  ...
 
 Cleanup ({n}):
-  1. {description} — {file:line}
-  2. ...
+  1. {description} — {file:line} → [FIX NOW]
+     (quick fix, file already in diff)
+  2. {description} — {file:line} → [DEFER]
+     (substantial scope, cross-cutting)
+  ...
 
 Cosmetic ({n}):
-  1. {description} — {file:line}
-  2. ...
+  1. {description} — {file:line} → [DEFER]
+  ...
 ```
 
-**ASK:** "Here are all findings. Adjust priorities? Remove any? Add anything I missed? Proceed with fixes? (proceed / adjust / add more)"
+#### 5b. Routing ASK
+
+**ASK:** "Here are all findings with suggested routing. Review:
+- Change routing by number (e.g., 'defer Important.2', 'fix Cosmetic.3')
+- 'accept' to proceed with suggested routing
+- 'fix all' to implement everything now (skip board deferral)
+- Adjust priorities, remove, or add findings as before
+
+(accept / fix all / adjust / add more)"
+
+If the user attempts to defer a Critical finding, execute the Critical Deferral Protocol:
+
+1. **Structured warning.** Present the specific risk:
+
+   ```
+   Critical Deferral Warning:
+     Finding: {description}
+     Risk: {specific consequence of deferral — e.g., "unvalidated auth tokens may allow unauthorized access"}
+     Policy: Critical findings should resolve before merge (CONSTITUTION.md, quality philosophy).
+   ```
+
+2. **Require rationale.** Do not accept a bare "yes" or "defer" — the user must provide a written reason explaining why deferral is acceptable in this context.
+
+   **ASK:** "To defer this Critical finding, please provide a written rationale explaining why it is safe to merge without resolving it. This will be recorded in todo.md for board-fill triage."
+
+3. **Record rationale.** When recording the deferred Critical finding in todo.md (Step 5c), include the user's rationale and a `Critical-deferred` tag:
+
+   ```markdown
+   - {finding description} (severity: Critical, file: {file:line}) [Critical-deferred]
+     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.
+
+The user is never blocked — this protocol adds accountability, not a veto.
+
+"fix all" preserves backward compatibility -- zero additional friction for simple revisions where everything should just be fixed.
+
+#### 5c. File Deferred Findings to todo.md
+
+If any findings are routed to [DEFER]:
+
+1. **Append to `todo.md`** as a single epic context block. All deferred findings from this revision session are grouped together regardless of count -- board-fill will create one epic from them.
+
+   **If a PR exists** (from Step 1b):
+
+   ```markdown
+   # Follow-ups from PR #{pr_number} revision ({date})
+   # Epic: group all items below into one epic during board-fill
+   - {finding description} (severity: {severity}, file: {file:line})
+   - {finding description} (severity: {severity}, file: {file:line})
+   - ...
+   ```
+
+   **If no PR exists** (working outside board pipeline):
+
+   ```markdown
+   # Follow-ups from {branch} revision ({date})
+   # Epic: group all items below into one epic during board-fill
+   - {finding description} (severity: {severity}, file: {file:line})
+   - ...
+   ```
+
+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.
+
+If no findings are routed to [DEFER] (including the "fix all" shortcut), skip this sub-step entirely.
 
 ---
 
 ### Step 6: Fix Implementation (Sub-Agent Delegation)
 
-Delegate fixes to specialist sub-agents via the Task tool. Group findings by specialist and parallelize where possible.
+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
 
@@ -240,6 +332,7 @@ Each sub-agent prompt MUST include:
 - 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
 
@@ -264,6 +357,8 @@ Run the project's quality checks. Refer to `package.json` scripts, `README.md`,
 
 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:
@@ -274,6 +369,7 @@ 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.
@@ -281,6 +377,8 @@ The reviewer prompt MUST include:
 
 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
@@ -293,13 +391,14 @@ After the review loop is clean, spawn both agents in parallel via the Task tool:
 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.
+- 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.
 
 ---
@@ -318,6 +417,16 @@ git push
 - Single category: `revision: fix {description}` (e.g., `revision: fix auth token refresh and clean up dead code`)
 - Multiple categories: `revision: address {N} issues from user testing` with a body listing the categories
 - Reference linked issue numbers when available: `revision: fix validation edge cases (#42)`
+- When deferred findings exist, include them in the commit message body:
+  ```
+  revision: address {N} findings, defer {M} to board
+
+  Fixed:
+  - {fixed finding summaries}
+
+  Deferred to todo.md for board-fill:
+  - {deferred finding summaries}
+  ```
 
 If `git push` fails (e.g., remote branch does not exist yet), use `git push -u origin {branch}`.
 
@@ -333,15 +442,24 @@ Evaluate whether the branch is ready to merge.
 Merge Readiness:
   [x/·] Quality checks passing (lint, types, tests)
   [x/·] All critical findings addressed
-  [x/·] All important findings addressed
-  [x/·] Cleanup findings addressed
+  [x/·] All important findings addressed or tracked ({N} fixed, {M} deferred)
+  [x/·] Cleanup findings addressed or tracked ({N} fixed, {M} deferred)
   [x/·] Acceptance criteria met (if available)
   [x/·] No unresolved TODOs in changed files
   [x/·] No remaining lint/type errors in changed files
 
+Deferred to Board ({M} items — in todo.md, pending board-fill):
+  - {description} (severity: {severity})
+  - ...
+
+  Overall Revision Confidence: {high/medium/low}
+    Highest-risk remaining area: {description or "none"}
+
 Verdict: READY / NOT READY ({remaining items})
 ```
 
+A deferred finding counts as "tracked" not "unaddressed" -- it does not block merge readiness.
+
 #### 9b. Present Assessment
 
 **ASK:** "Revision complete. {verdict}. Options: (a) ready to merge, (b) run another revision cycle with new feedback, (c) done for now."
@@ -393,3 +511,6 @@ Capture revision-specific learnings. Focus on patterns that inform future implem
 - **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.

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
@@ -113,6 +114,10 @@ The rule's canonical definition remains in `.agents/rules/` but no adapter outpu
 - Invalid YAML produces warnings but does not prevent rule application (graceful degradation)
 - Customization files should be committed to the repository
 
+## Unified Skill
+
+This command's workflow is handled by the `hatch3r-customize` skill with `type: rule`. The skill provides root-cause analysis, multi-stakeholder review, and quality gate steps that extend the workflow above.
+
 ## Related
 
 - Agent customization: `hatch3r-agent-customize` command

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
@@ -92,6 +93,10 @@ enabled: false
 - Invalid YAML produces warnings but does not prevent skill execution (graceful degradation)
 - Customization files should be committed to the repository
 
+## Unified Skill
+
+This command's workflow is handled by the `hatch3r-customize` skill with `type: skill`. The skill provides root-cause analysis, multi-stakeholder review, and quality gate steps that extend the workflow above.
+
 ## Related
 
 - Agent customization: `hatch3r-agent-customize` command

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
 
@@ -230,6 +231,7 @@ The implementer sub-agent prompt MUST include:
 - **Reference conventions** from `similar-implementation` output (Tier 2/3) — triggers the implementer's Convention Lock step.
 - **Resolved requirements** from `requirements-elicitation` answers (Tier 2/3) — explicit decisions on ambiguities.
 - **Blast radius data** from enhanced `codebase-impact` (Tier 3) — transitive dependency trace and API consumer map.
+- 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.
 
 Await the implementer sub-agent. Collect its structured result.
 
@@ -248,7 +250,7 @@ npm run lint && npm run typecheck && npm run test
 
 Fix any issues before proceeding. If quality checks fail, loop back and resolve before advancing to Phase 4.
 
-**ASK:** "Implementation complete. All quality checks pass. Proceed to Review? (yes / fix issues first)"
+**ASK:** "Implementation complete. All quality checks pass. Confidence in implementation quality: {high/medium/low — based on test coverage depth, edge case handling, and researcher coverage}. Proceed to Review? (yes / fix issues first)"
 
 ---
 
@@ -266,11 +268,14 @@ Spawn a `hatch3r-reviewer` sub-agent via the Task tool (`subagent_type: "general
 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.
+
 Each reviewer/fixer sub-agent prompt MUST include:
 - The agent protocol to follow.
 - All `scope: always` rule directives from `.agents/rules/`.
 - The diff or file changes to review/fix.
 - The task's acceptance criteria.
+- 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.
 
 #### 4b. Final Quality (Parallel Specialists)
 
@@ -296,13 +301,20 @@ Each specialist sub-agent prompt MUST include:
 - All `scope: always` rule directives from `.agents/rules/`.
 - The diff or file changes to review.
 - The task's acceptance criteria.
+- 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.
 
 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.
 
+For each criterion, rate verification confidence: high (tested and confirmed via code, tests, or browser), medium (logically satisfied but not independently verified), low (uncertain, recommend human testing).
+
 #### 4d. Present Review
 
 ```
@@ -313,6 +325,8 @@ Review Results:
   Test Coverage: {test-writer results}
   Documentation: {docs-writer results / not applicable}
   Performance: {pass/issues}
+  Overall Confidence: {high/medium/low}
+    Lowest-confidence area: {description or "none"}
 ```
 
 **ASK:** "Review complete. {summary}. Ready to finalize? (yes / address review issues / request human review)"