hatch3r 1.9.0 → 2.0.0

package/dist/content/commands/hatch3r-board-pickup.md

@@ -2,22 +2,24 @@
 id: hatch3r-board-pickup
 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: Pick up one or more epics/issues from the project board for development. Handles dependency-aware selection, collision detection, branching, parallel sub-agent delegation, and batch execution. Supports GitHub, Azure DevOps, and GitLab. Platform-specific details are in commands/board/pickup-{platform}.md.
+agentPipeline: [hatch3r-researcher, hatch3r-implementer, hatch3r-reviewer, hatch3r-fixer, hatch3r-testability, hatch3r-security, hatch3r-docs-writer, hatch3r-lint-fixer, hatch3r-ui, hatch3r-ux, hatch3r-performance]
+description: "Pick up epics/issues from the project board: dependency-aware selection, collision detection, branching, batch execution. Multi-platform."
 tags: [board, ctx:team-only]
 quality_charter: agents/shared/quality-charter.md
 efficiency_patterns: agents/shared/efficiency-patterns.md
 cache_friendly: true
 parallel_tool_default: true
+efficiency_tier: standard
 triage_tiers: [1, 2, 3]
+supports_resume: true
 sub_agents_spawned:
-  count: 10
-  rationale: Full delivery pipeline — researcher, implementer (one per independent issue in batch mode), reviewer ↔ fixer review loop, then a parallel final-quality batch (test-writer, security-auditor, docs-writer, lint-fixer, a11y-auditor, perf-profiler) bounded by max_phase4_parallel.
+  count: 11
+  rationale: Full delivery pipeline — researcher, implementer (one per independent issue in batch mode), reviewer ↔ fixer review loop, then a parallel final-quality batch (testability (CQ5), security (CQ3), docs-writer, lint-fixer, hatch3r-ui (CQ1), hatch3r-ux (CQ2), performance (CQ7)) bounded by max_phase4_parallel. Cost-dominance per CONSTITUTION §2 P8 — token cost never serializes independent work.
 ---
 
 ## §0 Detect Ambiguity (P8 B1)
 
-Before any action, scan the user's request and provided context for unresolved questions in scope, acceptance criteria, irreversibility, or constraint conflicts (contradictory inputs, missing target, unknown convention). If any are found, ask the user via the platform-native question tool per `agents/shared/user-question-protocol.md` — do not proceed under silent assumption. This is the default path, not an exception. Acceptable to proceed without asking ONLY when scope is single-target, single-concern, and the brief alone is testable. Any residual ambiguity discovered mid-workflow invokes the same protocol.
+> Orchestration boilerplate: see `commands/shared/orchestration-frame.md` → §0 Detect Ambiguity (P8 B1). Triggers: contradictory inputs, missing target, unknown convention.
 
 # Board Pickup -- Develop Issues from the Project Board
 
@@ -32,10 +34,12 @@ Pick up an epic (with all sub-issues), a single sub-issue, a standalone issue, o
 | 1. Research | `hatch3r-researcher` (modes by task type) | Per issue | Yes |
 | 2. Implementation | `hatch3r-implementer` (one per issue) | Yes (per dependency level) | Yes |
 | 3a. Review Loop | `hatch3r-reviewer` -> `hatch3r-fixer` (max 3 iterations until clean) | No (sequential loop) | Yes |
-| 3b. Final Quality — Testing | `hatch3r-test-writer` | Yes | Yes (code changes) |
-| 3c. Final Quality — Security | `hatch3r-security-auditor` | Yes | Yes (code changes) |
+| 3b. Final Quality — Testing | `hatch3r-testability` | Yes | Yes (code changes) |
+| 3c. Final Quality — Security | `hatch3r-security` | Yes | Yes (code changes) |
 | 3d. Final Quality — Docs | `hatch3r-docs-writer` | Yes | When APIs/architecture/UX affected |
-| 3e. Final Quality — Conditional | `hatch3r-lint-fixer`, `hatch3r-a11y-auditor`, `hatch3r-perf-profiler` | Yes | When triggered |
+| 3e. Final Quality — Conditional | `hatch3r-lint-fixer`, `hatch3r-ui`, `hatch3r-performance` | Yes | When triggered |
+
+**Parallel-safety conditions** (per `rules/hatch3r-agent-orchestration.md` §Parallel Safety): every parallel fan-out above holds all three — read-only or disjoint writes, deterministic aggregation, no shared mutable state.
 
 ## Browser Automation
 
@@ -93,6 +97,35 @@ Classify the pickup request before delegating:
 
 If Tier 1, run the standard delegation path (Step 6a) with reduced research depth. If Tier 2, run the standard pipeline below with parallel fanout where dependencies allow. If Tier 3, run the full pipeline with deep research and confirm batch composition with the user before branching.
 
+### Step 0.5: Emit Pre-Execution Cost Preview
+
+Before the first sub-agent dispatch (Step 6 delegation), surface the cost preview so a multi-issue batch pickup is never started blind. Emit the `cost_estimate` block per `rules/hatch3r-cost-visibility.md` Pre-Execution Estimate, calibrated to the Step 0 triage tier and the selected batch size:
+
+```yaml
+cost_estimate:
+  expected_sa_count: <triage tier → Tier 1 ~2, Tier 2 ~6, Tier 3 up to 12 × batch-issue count>
+  estimated_input_tokens_static_frame: <int>
+  estimated_web_research_queries: <int>
+  triage_tier: light | standard | deep
+  estimated_duration_min: <int>
+```
+
+Post-execution actuals + delta land in the Step 7 / post-impl iteration summary's Fan-out + Cost section per `rules/hatch3r-cost-visibility.md` Post-Execution Actuals. Token telemetry sources from `src/pipeline/observability.ts`.
+
+### Effort Override (Decision 17)
+
+> Orchestration boilerplate: see `commands/shared/orchestration-frame.md` → Effort Override (Decision 17). Misclassification example: an isolated sub-issue scored as Deep, or a cross-cutting epic scored as Light.
+
+### Confidence Floor (Decision 16 / D13-SA13.3-F13.3.3)
+
+`--effort` calibrates work-effort depth; `--confidence-floor` calibrates the confidence threshold at which the Step 7 review gate (the canonical **Confidence-Aware Review Gate** in `agents/shared/confidence-gate.md`, run by `commands/board/pickup-delegation.md` / `pickup-delegation-multi.md`) blocks. They are orthogonal. This is the user's pre-flight assertiveness knob — the forced-second-pass on low confidence is post-hoc; the floor sets the bar before the run:
+
+- `--confidence-floor=any|medium|high` (default `any`). Resolution order: explicit flag wins over the persisted `hatch3r config confidence_floor=...` default, which wins over the built-in `any`.
+- **`any`** (current behavior): force a second reviewer pass only when reviewer confidence `== low` with 0 Critical + 0 Warning.
+- **`medium`**: force a second pass on ANY finding rated `confidence == low`, even with 0 Critical + 0 Warning.
+- **`high`**: force a second pass on any finding rated `confidence != high`, AND ASK the user on every low-confidence finding regardless of severity.
+- Per P1 maturity tier (Decision 16): solo defaults `any`, enterprise defaults `high`. Pass the resolved floor verbatim into the Step 7 review-gate evaluation (`agents/shared/confidence-gate.md`, which the delegation sub-files run) alongside the confidence value sourced from the upstream reviewer (Confidence Propagation Contract). The floor never relaxes a Safety Guardrail.
+
 ---
 
 ### Step 1: List Available Work (Dependency-Aware)
@@ -295,6 +328,8 @@ Use the issue type to select the appropriate hatch3r skill: `type:bug` → the h
 
 Before delegating: scan `.hatch3r/learnings/` for matching `area`/`tags`, include relevant learnings (especially `pitfall` category) in sub-agent context. Skip silently if no learnings directory exists.
 
+**Cross-PR finding memory (D13-SA13.1-F08).** Also scan `.hatch3r/review-findings/` (skip silently if absent) for entries whose `applies-to` glob matches the issue's target files; carry the 5 most-recent matches (by `created` descending) forward into the Step 7a reviewer prompt as a `## Cross-PR Findings` block so the reviewer — which declares `consults_cross_pr_findings: true` — weighs prior same-file findings as organisational memory. After the Step 7a review loop terminates clean, append one `.hatch3r/review-findings/<id>.md` entry per Critical/Warning finding resolved (atomic write via `src/merge/safeWrite.ts`), mirroring the Step 10 learnings-capture pattern.
+
 > **Audit epics:** Audit epics produce findings (issues) rather than code changes — adjust delegation and skip Steps 7-8a if no code changes.
 
 **Do NOT execute the skill's PR creation steps.** Steps 7-8 handle board-specific requirements (epic linking, label transitions, board sync).
@@ -313,7 +348,7 @@ Before delegating: scan `.hatch3r/learnings/` for matching `area`/`tags`, includ
 
 Execute Steps 7-10 in order after all implementation completes:
 
-- **Step 7:** Quality verification (lint, type check, tests, AC).
+- **Step 7:** Quality verification (lint, type check, tests, AC). **Post-write duplication scan (Decision 21 / D13-SA13.2-F7):** when batch mode ran 2+ parallel implementers (Step 6c), run `npx jscpd --min-lines 40 --threshold 80 --reporters json --silent <changed-paths>` on the combined diff before the review gate clears — parallel implementers can each emit near-duplicate code that passes its own review independently. Any cross-file clone **≥40 lines OR ≥80% byte-similar** routes back to `hatch3r-fixer` for a DRY refactor (max 1 iteration), then re-runs the quality check. Skip when a single issue/implementer ran.
 - **Step 7a:** Commit and push all changes to the remote branch.
 - **Step 8:** Create PR/MR with proper `Closes #N` references. See platform sub-files for CLI commands.
 - **Step 8a:** Transition labels to `status:in-review` and sync board. See platform sub-files.
@@ -322,8 +357,57 @@ Execute Steps 7-10 in order after all implementation completes:
 
 ---
 
+## Resumability (Decision 27/30)
+
+board-pickup is long-running — a Tier 3 batch picks up multiple epics/sub-issues, branches, delegates parallel implementers per dependency level (Step 6), runs the reviewer ↔ fixer review loop (Step 7a), and fans out the Phase 4 specialist batch (Step 7b–7c) across 11 sub-agents in `agentPipeline`. Per hatch3r's workspace-checkpointed resumability contract, checkpoint progress so an interrupted run re-enters at the last completed step rather than re-claiming issues, re-creating branches, or repeating implementer work that already wrote code.
+
+> Orchestration boilerplate: see `commands/shared/orchestration-frame.md` → Checkpoint Contract. Per-command slots: workspace `.board-pickup-workspace/`; step range the Step 0 → Step 10 progression; `wave` = dependency-level batch index when parallel implementers run; snapshot/rollback paths `.hatch3r/handoffs/` entries written by `hatch3r-handoff` and pre-commit working-tree state. Write points: after Step 1 work selection ASK, after Step 2 scope + dependency lock, after Step 3 collision detection, after Step 4 board-status update (issues moved to In Progress), after Step 5 branch creation (atomic with `branchName` persistence), after each Step 6 implementer batch returns per dependency level (so completed implementations survive a crash and are not re-implemented on resume), after each Step 7a review-loop iteration, after each Step 7b/7c parallel-specialist batch completes, after Step 8 git commit, and after Step 9 PR-readiness gate.
+
+---
+
+## Per-Turn Pipeline-State Header (Bypass Protection)
+
+> Orchestration boilerplate: see `commands/shared/orchestration-frame.md` → Per-Turn Pipeline-State Header. Phase mapping for board-pickup: `1` = ready-queue selection + branch checkout, `2` = researcher + implementer dispatch, `3` = reviewer/fixer review-loop + Phase 4 specialists, `4` = PR creation + board sync + iteration-summary. Tier 1 runs are exempt per the Tier 1 exemption.
+
+## End-of-Turn Delegation Attestation (Bypass Protection)
+
+> Orchestration boilerplate: see `commands/shared/orchestration-frame.md` → End-of-Turn Delegation Attestation. Per-command mutated-file slot: implementer code changes, test additions, fixer corrections.
+
+## Iteration Summary (mandatory output)
+
+Emit the canonical 9-section iteration summary per `rules/hatch3r-iteration-summary.md` as the final user-facing output. The validation gate at `.claude/rules/capability-lifecycle.md` blocks SUCCESS declarations without this block (CONSTITUTION §6 Decision 23).
+
+The 9 sections:
+
+1. **Request** — verbatim restatement of the user's ask in one sentence.
+2. **Fan-out + Cost** — `sub_agents_spawned: { count, rationale }` plus the `cost_estimate` / `cost_actuals` / `delta` blocks (see Cost Visibility below).
+3. **Web Research** — every URL fetched with access date + trust tier per `agents/shared/rigor-contract.md` (0 acceptable when no research was needed).
+4. **Files Mutated** — list with diff summary (lines added / removed / files created).
+5. **Gates Passed / Failed** — explicit list per `.claude/rules/capability-lifecycle.md` Gate Checklist.
+6. **Pillar Impact Attribution** — `progress_toward_pillar: <axis>.<pillar_id>+<delta>` per CONSTITUTION §6 Decision 17.
+7. **Verification Commands** — exact commands run with exit codes plus key output lines (≤200 chars).
+8. **Open Questions / Blockers** — explicit `None` if fully closed.
+9. **Learnings Captured** — IDs of any learnings written to `.hatch3r/learnings/` this run per `rules/hatch3r-learning-system.md`.
+
+### Cost Visibility (Decision 24)
+
+> Orchestration boilerplate: see `commands/shared/orchestration-frame.md` → Cost Estimate for the 5-field `cost_estimate` schema and the post-execution `cost_actuals` + `delta` contract; both land in Section 2 above.
+
+## Cost estimate (Decision 24)
+
+This command emits cost transparency per `rules/hatch3r-cost-visibility.md` and CONSTITUTION §6 Decision 24/29:
+
+- **Pre-execution `cost_estimate`** — emitted in Step 0.5 before the first sub-agent dispatch (Step 6 delegation).
+- **Post-execution `cost_actuals` + `delta`** — appended to the Step 7 / post-impl iteration summary's Fan-out + Cost section per `rules/hatch3r-iteration-summary.md` §2.
+
+Per-tier `expected_sa_count` calibration (from frontmatter `sub_agents_spawned.count: 11` × tier heuristic in `rules/hatch3r-cost-visibility.md` Pre-Execution Estimate): Tier 1 ≈ 2 (researcher + implementer, reviewer/fixer/testability/security when triggered); Tier 2 ≈ 6 (researcher + implementer + review loop + mandatory final-quality); Tier 3 up to 11 per issue (full pipeline including the Phase-4b CQ specialist batch bounded by `max_phase4_parallel`), scaling with batch-issue count. Deltas beyond 25% absolute value carry `flagged_for_review: true`. Token telemetry sources from `src/pipeline/observability.ts`; estimation primitives from `src/pipeline/costEstimator.ts`.
+
+---
+
 ## Auto-Advance Mode, Error Handling, and Guardrails
 
 > Full details: see `commands/board/pickup-modes.md`
 
 The modes file contains: auto-advance mode (`--auto`/`--unattended`), safety guardrails, error handling, and operational guardrails for board-pickup.
+
+**Concurrent invocation guardrail:** before Step 6 delegation, acquire `.hatch3r/.lock` and detect-then-warn on a conflicting active pipeline (same branch / open `.hatch3r/hatch.json` board transaction) per `rules/hatch3r-agent-orchestration.md` → Parallel Safety → Concurrent Invocation Handling. Batch-mode parallel implementers (Step 6c) are one pipeline by design; the guardrail governs a *second* concurrent top-level invocation against the same repo. Cross-task learnings consolidate at completion, never mid-pipeline.

package/dist/content/commands/hatch3r-bug-pipeline.md

@@ -0,0 +1,240 @@
+---
+id: hatch3r-bug-pipeline
+type: command
+orchestrator: true
+agentPipeline: [hatch3r-researcher, hatch3r-implementer, hatch3r-reviewer, hatch3r-fixer]
+description: Run a known-cause bug fix through a 3-phase test-first pipeline -- reproduce + root-cause, regression-test + fix together, then root-cause-depth review -- with full sub-agent delegation.
+tags: [implementation, orchestration]
+quality_charter: agents/shared/quality-charter.md
+efficiency_patterns: agents/shared/efficiency-patterns.md
+cache_friendly: true
+parallel_tool_default: true
+efficiency_tier: standard
+triage_tiers: [1, 2, 3]
+supports_resume: true
+sub_agents_spawned:
+  count: 4
+  rationale: One researcher (merged reproduce + root-cause), one implementer (regression test + fix authored together, TDD-style), then a reviewer ↔ fixer loop on root-cause depth; the canonical four-phase Final Quality specialists collapse onto the implementer's bundled regression test plus the reviewer's root-cause-depth gate. Cost-dominance per CONSTITUTION §2 P8 — token cost never serializes independent work.
+---
+
+## §0 Detect Ambiguity (P8 B1)
+
+Before any action, scan the bug report for unresolved questions in scope, acceptance criteria, irreversibility, or constraint conflicts (no reproduction steps, expected-vs-actual behavior unstated, severity unclear, affected environment unknown, or a fix that touches a schema / public API with downstream consumers). If any are found, ask the user via the platform-native question tool per `agents/shared/user-question-protocol.md` — do not proceed under silent assumption. This is the default path, not an exception. Acceptable to proceed without asking ONLY when the bug is single-module, reproduction is known, and the brief alone is testable. Residual ambiguity discovered mid-pipeline invokes the same protocol.
+
+## Agent Pipeline
+
+| Stage | Agent(s) | Parallel | Required |
+|-------|----------|----------|----------|
+| 1. Reproduce + Root-Cause | `hatch3r-researcher` (modes: `symptom-trace`, `root-cause`; `codebase-impact` for Tier 3) | Per mode | Yes |
+| 2. Regression-Test + Fix | `hatch3r-implementer` (failing test first, then minimal fix) | Per independent module | Yes |
+| 3. Root-Cause-Depth Review | `hatch3r-reviewer` -> `hatch3r-fixer` (max 4 iterations) | No (sequential) | Yes |
+
+**Parallel-safety conditions** (per `rules/hatch3r-agent-orchestration.md` §Parallel Safety): every parallel fan-out above holds all three — read-only or disjoint writes, deterministic aggregation, no shared mutable state.
+
+# Bug Pipeline — Test-First 3-Phase Fix Delegation
+
+A bug-shaped variant of the four-phase pipeline for the case where the symptom is known and the fix is in hand but the change still needs full delegation rigor. The default four-phase pipeline writes the regression test in Phase 4, *after* the fix already landed; for a bug the regression test should drive the fix. This command compresses the pipeline to the bug's natural shape: **reproduce + root-cause (Phase 1) → regression-test + fix authored together, TDD-style (Phase 2) → root-cause-depth review (Phase 3)**, with security as the primary review lens because regressions frequently sit on a validation or auth edge.
+
+**When to use this command vs. the `hatch3r-bug-fix` skill vs. `hatch3r-bug-plan`:**
+
+- Use `hatch3r-bug-pipeline` when: the root cause is known or strongly hypothesized, a fix is in hand, but the change is nontrivial (multi-file, behavior change, security-adjacent) and must go through delegated implementer + reviewer ↔ fixer rigor rather than inline edits.
+- Use the `hatch3r-bug-fix` skill when: the fix is localized and trivial enough for single-pass inline work (single file, clear root cause, low risk).
+- Use `hatch3r-bug-plan` when: the root cause is unknown, multiple modules might be involved, or the fix needs multi-PR phasing — that command produces an investigation report, not a fix.
+
+---
+
+## Token-Saving Directives
+
+1. **Do not re-read cached files.** Once researcher output (symptom trace + ranked root cause) is collected, reference it in memory — do not re-invoke.
+2. **Targeted reads only.** Read only files on the failure path identified by the researcher.
+3. **Structured output only.** Every sub-agent prompt requires structured markdown output — no prose dumps.
+
+---
+
+## 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 fix-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
+
+Execute these steps in order. **Do not skip any step.** Ask the user at every checkpoint marked with ASK, using the platform-native question tool per `agents/shared/user-question-protocol.md`.
+
+## Step 0: Triage
+
+Classify the bug before delegating:
+
+- **Tier 1 (trivial)**: single-file, clear root cause, reproduction known. Route to the `hatch3r-bug-fix` skill and exit — this pipeline's delegation overhead is not warranted.
+- **Tier 2 (standard)**: multi-file or behavior-changing fix with a known or strongly-hypothesized root cause. Run the full 3-phase pipeline below.
+- **Tier 3 (deep)**: multi-module, security-adjacent, or high blast-radius fix. Run the full pipeline with researcher depth `deep`, the `codebase-impact` mode added in Phase 1, and a user scope confirmation before Phase 2.
+
+If the root cause is genuinely unknown, recommend `hatch3r-bug-plan` (investigation-first) instead and exit.
+
+### Step 0.5: Emit Pre-Execution Cost Preview
+
+Before the first sub-agent dispatch (Step 2), surface the cost preview so a delegated bug fix is never started blind. Emit the `cost_estimate` block per `rules/hatch3r-cost-visibility.md` Pre-Execution Estimate, calibrated to the Step 0 triage tier:
+
+```yaml
+cost_estimate:
+  expected_sa_count: <Tier 1 routes out (0), Tier 2 ~3, Tier 3 ~4>
+  estimated_input_tokens_static_frame: <int>
+  estimated_web_research_queries: <int>      # 0 when no research is needed
+  triage_tier: light | standard | deep
+  estimated_duration_min: <int>
+```
+
+Post-execution actuals + delta land in the iteration summary's Fan-out + Cost section per `rules/hatch3r-cost-visibility.md` Post-Execution Actuals. Token telemetry sources from `src/pipeline/observability.ts`; estimation primitives from `src/pipeline/costEstimator.ts`.
+
+### Effort Override (Decision 17)
+
+Auto-tiering can misclassify — a single-module bug scored Deep, or a multi-module regression scored Light. The user override is the recovery path mandated by hatch3r's universal `--effort` override contract ("User overridable via `--effort` flag"):
+
+- `--effort=light|standard|deep` forces the named tier, bypassing the Step 0 auto-classification. `--effort=light` routes to the `hatch3r-bug-fix` skill.
+- The override wins over the auto-detected tier; record both the auto-detected tier and the override in the run context so the cost estimate block reports the budget delta.
+- No override passed → the Step 0 auto-classification stands.
+
+---
+
+### Step 1: Reproduce + Root-Cause (Phase 1)
+
+Spawn `hatch3r-researcher` following the **hatch3r-researcher agent protocol** with the merged reproduce-and-diagnose modes. This single phase replaces the default pipeline's separate research and blast-radius passes — for a bug, "where does it diverge" and "why" are one investigation.
+
+**Modes:** `symptom-trace` (execution path from user action to the divergence point) and `root-cause` (ranked hypotheses with code evidence). For Tier 3, add `codebase-impact` (blast radius across modules + data-integrity risk).
+
+**Depth:** `quick` for Tier 1 (if it was not routed out), `standard` for Tier 2, `deep` for Tier 3.
+
+The researcher prompt MUST include: the bug brief (symptoms, expected behavior, reproduction context, severity, prior attempts), the assigned modes + depth, the **hatch3r-researcher agent protocol** instruction, a `correlation_id` (UUID v4 per `rules/hatch3r-agent-orchestration.md` → Correlation ID), and the confidence expression requirement above.
+
+Apply the **Research Completeness Checklist** (`rules/hatch3r-agent-orchestration.md`) before handing off to Phase 2: affected files identified, blast radius assessed (Tier 3), existing tests located (or absence noted), dependencies mapped. If any item is unconfirmed, re-run the researcher with additional modes or surface to the user.
+
+**ASK:** "Top root-cause hypothesis: {hypothesis} (confidence {high/medium/low}). Reproduction path: {summary}. Proceed to author a failing regression test + fix? (yes / adjust hypothesis / re-run researcher)"
+
+---
+
+### Step 2: Regression-Test + Fix Authored Together (Phase 2)
+
+Spawn `hatch3r-implementer` via the Task tool (`subagent_type: "generalPurpose"`). Unlike the default pipeline — where hatch3r-testability runs in Phase 4 after the fix — this phase authors the failing regression test FIRST, then the minimal fix that makes it pass.
+
+The implementer prompt MUST include the confirmed root cause + reproduction path from Step 1, all `scope: always` rule directives from `rules/`, the `correlation_id`, the confidence expression requirement, an explicit instruction NOT to create branches / commits / PRs, and the following test-first contract (verbatim):
+
+> Test-first contract: (1) Write a regression test that reproduces the exact bug scenario and FAILS against current code with the reported symptom — not a setup error. (2) Confirm the test fails for the right reason. (3) Implement the minimal fix at the root cause; do not refactor unrelated code, do not suppress the symptom (no `eslint-disable`, no `as any`, no `test.skip`). (4) Confirm the regression test now passes and no existing test regressed. (5) Return the failing-then-passing evidence in your structured result.
+
+The implementer also returns the **midpoint research-gap checkpoint** result per `rules/hatch3r-agent-orchestration.md` → Mid-Implementation Research Gap Checkpoint: if the fix touches a file outside the researcher's affected-files set, an undocumented dependency, or confidence drops below medium, log the gap and either request a targeted researcher re-run (blocking) or document the assumption for Phase 3 reviewer attention (non-blocking).
+
+If the fix spans **independent modules** (no shared files), spawn one implementer per module and run them in parallel. **Overlapping files** run sequentially through a single implementer to avoid conflicts.
+
+Await the implementer result. If it reports BLOCKED, **ASK** the user for guidance.
+
+After the implementer returns, run the project quality gates (lint, typecheck, full test suite — see `package.json` scripts). The regression test must pass and the existing suite must stay green before Phase 3.
+
+---
+
+### Step 3: Root-Cause-Depth Review (Phase 3)
+
+Run an iterative review loop (max 4 iterations, matching `DEFAULT_MAX_REVIEW_ITERATIONS` in `src/pipeline/reviewLoop.ts`) until 0 Critical + 0 Warning findings remain. The review lens for a bug fix is **root-cause depth and regression-test validity**, not feature completeness.
+
+1. Spawn `hatch3r-reviewer` via the Task tool. The prompt MUST include the working-tree diff (`git diff`), the confirmed root cause from Step 1, the failing-then-passing test evidence from Step 2, all `scope: always` rule directives, the iteration number + prior findings (if not the first pass), the `correlation_id`, the confidence expression requirement, and a top-level `confidence: high | medium | low` output requirement so the gate can evaluate it deterministically. Focus the reviewer on:
+   - **Root-cause depth** — does the fix address the cause or only mask the symptom? Reject suppression patterns (`eslint-disable`, `as any`, `as unknown as`, `@ts-ignore`, `test.skip`, empty catch blocks) per `rules/hatch3r-agent-orchestration.md` → Root-Cause Depth Requirements.
+   - **Regression-test validity** — does the test actually fail without the fix and assert the corrected behavior, not an incidental side effect?
+   - **Security edge** — regressions frequently sit on a validation, auth, or input-handling boundary; verify the fix does not open one.
+
+2. Process reviewer output:
+   - **0 Critical + 0 Warning AND reviewer confidence != low** → review loop clean; proceed to Step 4.
+   - **0 Critical + 0 Warning AND reviewer confidence == low** → trigger a second reviewer pass before exiting; do not proceed until it returns non-low confidence OR the user explicitly accepts the low-confidence PASS.
+   - **Critical or Warning findings remain** → spawn `hatch3r-fixer` with the full reviewer output + all `scope: always` directives + the confidence expression requirement, then re-run the reviewer (next iteration). After fixes, re-run quality gates.
+
+3. If 4 iterations complete and findings remain, surface a structured summary (iteration count, remaining Critical findings with file:line, remaining Warnings, fix-manually-vs-accept-risk recommendation) and **ASK** the user whether to proceed or fix manually. Never present raw reviewer output unsummarized.
+
+---
+
+### Step 4: Summary + Git Action
+
+1. Present a concise completion summary:
+
+```
+Bug Pipeline Complete:
+  Root cause:        {one-line root cause}
+  Regression test:   {test name/path — failed before, passes after}
+  Files changed:     {file list}
+  Quality:           lint {pass/fail}, types {pass/fail}, tests {pass/fail}
+  Review:            {N iterations, clean}
+  Confidence:        {high/medium/low — overall assessment of fix correctness}
+```
+
+2. **ASK:** "All changes complete. Quality gates pass. How should I handle git? (a) commit only, (b) commit and push, (c) skip git — leave changes in working tree"
+
+Commit message format: `fix: {short root-cause-oriented description}`. For pushes, fall back to `git push -u origin {branch}` when no upstream exists.
+
+---
+
+## Resumability (Decision 27/30)
+
+bug-pipeline is multi-phase — a Tier 2/3 run dispatches a researcher (Step 1), one or more implementers authoring regression test + fix (Step 2), and a reviewer ↔ fixer loop (Step 3). Per hatch3r's workspace-checkpointed resumability contract, checkpoint progress so an interrupted run re-enters at the last completed step rather than re-running the researcher or re-implementing a fix that already landed.
+
+> Orchestration boilerplate: see `commands/shared/orchestration-frame.md` → Checkpoint Contract. Per-command slots: workspace `.bug-pipeline-workspace/`; step range the Step 0 → Step 4 progression; `wave` = review-loop iteration index in Step 3; snapshot/rollback paths the working-tree state. Write points: after Step 1 researcher returns and the root-cause ASK is confirmed, after each Step 2 implementer returns per module (so a landed fix + regression test survive a crash), after Step 2 quality gates pass, after each Step 3 review-loop iteration, and after the Step 4 git action.
+
+---
+
+## Per-Turn Pipeline-State Header (Bypass Protection)
+
+> Orchestration boilerplate: see `commands/shared/orchestration-frame.md` → Per-Turn Pipeline-State Header. Phase mapping for bug-pipeline: `1` = reproduce + root-cause (researcher), `2` = regression-test + fix (implementer), `3` = root-cause-depth review (reviewer ↔ fixer), `4` = summary + git + iteration-summary. Tier 1 runs route out to the `hatch3r-bug-fix` skill and are exempt per the Tier 1 exemption.
+
+## End-of-Turn Delegation Attestation (Bypass Protection)
+
+> Orchestration boilerplate: see `commands/shared/orchestration-frame.md` → End-of-Turn Delegation Attestation. Per-command mutated-file slot: regression test, fix, fixer changes. This command has no Tier-1 inline carve-out: Tier 1 bugs route to the `hatch3r-bug-fix` skill, so every mutation here flows through a sub-agent.
+
+## Iteration Summary (mandatory output)
+
+Emit the canonical 9-section iteration summary per `rules/hatch3r-iteration-summary.md` as the final user-facing output. The validation gate at `.claude/rules/capability-lifecycle.md` blocks SUCCESS declarations without this block (CONSTITUTION §6 Decision 23).
+
+The 9 sections:
+
+1. **Request** — verbatim restatement of the user's ask in one sentence.
+2. **Fan-out + Cost** — `sub_agents_spawned: { count, rationale }` plus the `cost_estimate` / `cost_actuals` / `delta` blocks (see Cost Visibility below).
+3. **Web Research** — every URL fetched with access date + trust tier per `agents/shared/rigor-contract.md` (0 acceptable when no research was needed).
+4. **Files Mutated** — list with diff summary (lines added / removed / files created).
+5. **Gates Passed / Failed** — explicit list per `.claude/rules/capability-lifecycle.md` Gate Checklist.
+6. **Pillar Impact Attribution** — `progress_toward_pillar: <axis>.<pillar_id>+<delta>` per CONSTITUTION §6 Decision 17.
+7. **Verification Commands** — exact commands run with exit codes plus key output lines (≤200 chars).
+8. **Open Questions / Blockers** — explicit `None` if fully closed.
+9. **Learnings Captured** — IDs of any learnings written to `.hatch3r/learnings/` this run per `rules/hatch3r-learning-system.md`.
+
+### Cost Visibility (Decision 24)
+
+> Orchestration boilerplate: see `commands/shared/orchestration-frame.md` → Cost Estimate for the 5-field `cost_estimate` schema and the post-execution `cost_actuals` + `delta` contract; both land in Section 2 above.
+
+---
+
+## Error Handling
+
+- **Researcher cannot confirm a root cause:** if all hypotheses are low-confidence, do not author a speculative fix. State the verdict ("Root cause unconfirmed; top hypothesis confidence=low") and recommend switching to `hatch3r-bug-plan` for a full investigation. **ASK** how to proceed.
+- **Regression test passes before the fix:** the test does not reproduce the bug. Halt Phase 2, return to Step 1, and re-derive the reproduction path with the researcher — a test that cannot fail proves nothing.
+- **Implementer sub-agent failure:** retry once. If the retry fails, present the partial state and **ASK** (provide the missing context manually / route to `hatch3r-bug-plan` / abort).
+- **Reviewer flags a superficial fix:** the fixer must address the root cause, not re-suppress the symptom. If the same suppression pattern reappears across two iterations, surface it to the user — do not let it ship.
+- **Quality gate failure after fixer:** re-run gates after every fixer pass. After 2 unresolved retries within Step 3, surface the specific failures and **ASK** (fix manually / keep iterating / abort).
+- **File write failure:** report the error and provide the full file content so the user can apply it manually.
+
+## Guardrails
+
+- **Never skip the regression test.** A bug fix without a failing-then-passing test is incomplete — the test is the proof the fix works and the guard against recurrence.
+- **Never suppress the symptom.** Reject `eslint-disable`, `as any`, `test.skip`, and empty catch blocks as fixes per `rules/hatch3r-agent-orchestration.md` → Root-Cause Depth Requirements.
+- **Always delegate code mutation.** All code changes flow through `hatch3r-implementer` (Phase 2) or `hatch3r-fixer` (Phase 3) via the Task tool — no inline edits from the orchestrator turn.
+- **Never skip quality gates.** Lint, typecheck, and the full test suite run after Phase 2 and after every fixer pass.
+- **Never auto-commit without ASK (Step 4).** The user always decides the git action.
+- **Stay within the bug scope.** Do not expand the fix into adjacent refactors or feature work. Flag tangential findings but do not act on them without explicit approval.
+- **This command composes existing hatch3r agents** (researcher, implementer, reviewer, fixer) — it does not replace them or the default four-phase pipeline; it is the bug-shaped variant for known-cause, fix-in-hand work.
+
+---
+
+## References
+
+- `commands/hatch3r-bug-plan.md` — sibling investigation-first command (unknown root cause); accessed 2026-05-31; trust tier: official-docs (in-repo canonical).
+- `commands/hatch3r-quick-change.md` — orchestrator command structure + Per-Turn Header / Delegation Attestation / Iteration Summary block patterns mirrored here; accessed 2026-05-31; trust tier: official-docs (in-repo canonical).
+- `rules/hatch3r-agent-orchestration.md` — four-phase pipeline definition, Mandatory Delegation Directives, Root-Cause Depth Requirements, Mid-Implementation Research Gap Checkpoint; accessed 2026-05-31; trust tier: official-docs (in-repo canonical).
+- `skills/hatch3r-bug-fix/SKILL.md` — Step 2c test-first (TDD) approach this pipeline promotes to a first-class phase; accessed 2026-05-31; trust tier: official-docs (in-repo canonical).
+- hatch3r orchestration-domain analysis — source rationale for the bug-fix workflow's natural 3-phase shape; accessed 2026-05-31; trust tier: official-docs (in-repo canonical).

package/dist/content/commands/hatch3r-bug-plan.md

@@ -9,15 +9,17 @@ quality_charter: agents/shared/quality-charter.md
 efficiency_patterns: agents/shared/efficiency-patterns.md
 cache_friendly: true
 parallel_tool_default: true
+efficiency_tier: deep
 triage_tiers: [1, 2, 3]
+supports_resume: true
 sub_agents_spawned:
   count: 4
-  rationale: Four parallel hatch3r-researcher modes per bug brief — symptom-trace, root-cause-hypothesis, impact-assessment, regression-research — dispatched concurrently in Step 3; a docs-writer assembles the investigation report on their merged output.
+  rationale: Four parallel hatch3r-researcher modes per bug brief — symptom-trace, root-cause-hypothesis, impact-assessment, regression-research — dispatched concurrently in Step 3; a docs-writer assembles the investigation report on their merged output. Cost-dominance per CONSTITUTION §2 P8 — token cost never serializes independent work.
 ---
 
 ## §0 Detect Ambiguity (P8 B1)
 
-Before any action, scan the user's request and provided context for unresolved questions in scope, acceptance criteria, irreversibility, or constraint conflicts (contradictory inputs, missing target, unknown convention). If any are found, ask the user via the platform-native question tool per `agents/shared/user-question-protocol.md` — do not proceed under silent assumption. This is the default path, not an exception. Acceptable to proceed without asking ONLY when scope is single-target, single-concern, and the brief alone is testable. Any residual ambiguity discovered mid-workflow invokes the same protocol.
+> Orchestration boilerplate: see `commands/shared/orchestration-frame.md` → §0 Detect Ambiguity (P8 B1). Triggers: contradictory inputs, missing target, unknown convention.
 
 ## Agent Pipeline
 
@@ -27,6 +29,8 @@ Before any action, scan the user's request and provided context for unresolved q
 | 2. Document Generation | `hatch3r-docs-writer` (investigation report, ADRs) | Yes | Yes |
 | 3. Todo Generation | Orchestrator (inline) | No | Yes |
 
+**Parallel-safety conditions** (per `rules/hatch3r-agent-orchestration.md` §Parallel Safety): every parallel fan-out above holds all three — read-only or disjoint writes, deterministic aggregation, no shared mutable state.
+
 # Bug Plan — Complex Bug Investigation from Symptom to Board-Ready Fix Items
 
 Take a complex or ambiguous bug report and produce a structured investigation report (`docs/investigations/`), architectural decision records (`docs/adr/`) when the fix requires significant design choices, and structured `todo.md` entries (scoped fix items) ready for `hatch3r-board-fill`. Spawns parallel researcher sub-agents (symptom tracing, root cause investigation, impact assessment, regression research) to diagnose the bug from multiple angles before generating artifacts. AI proposes all outputs; user confirms before any files are written. Optionally chains into `hatch3r-board-fill` to create GitHub issues immediately.
@@ -50,6 +54,12 @@ Take a complex or ambiguous bug report and produce a structured investigation re
 
 ---
 
+## Confidence Propagation Contract
+
+> Orchestration boilerplate: see `commands/shared/orchestration-frame.md` → Confidence Propagation Contract. Readiness kind: investigation.
+
+---
+
 ## Workflow
 
 Execute these steps in order. **Do not skip any step.** Ask the user at every checkpoint marked with ASK.
@@ -64,6 +74,25 @@ Classify the bug investigation before delegating:
 
 If Tier 1, recommend the `hatch3r-bug-fix` skill and exit. If Tier 2, run the standard parallel-researcher pipeline below. If Tier 3, run the full pipeline including ADR generation in Step 6 and confirm fix phases with the user before writing files.
 
+### Step 0.5: Emit Pre-Execution Cost Preview
+
+Before the first sub-agent dispatch (Step 3), surface the cost preview so a multi-researcher investigation is never started blind. Emit the `cost_estimate` block per `rules/hatch3r-cost-visibility.md` Pre-Execution Estimate, calibrated to the Step 0 triage tier:
+
+```yaml
+cost_estimate:
+  expected_sa_count: <triage tier → Tier 1 routes out (0), Tier 2 ~4, Tier 3 up to 5>
+  estimated_input_tokens_static_frame: <int>
+  estimated_web_research_queries: <int>
+  triage_tier: light | standard | deep
+  estimated_duration_min: <int>
+```
+
+Post-execution actuals + delta land in the iteration summary's Fan-out + Cost section per `rules/hatch3r-cost-visibility.md` Post-Execution Actuals. Token telemetry sources from `src/pipeline/observability.ts`.
+
+### Effort Override (Decision 17)
+
+> Orchestration boilerplate: see `commands/shared/orchestration-frame.md` → Effort Override (Decision 17). Misclassification example: a clear single-module bug scored as Deep, or a multi-module incident scored as Light.
+
 ---
 
 ### Step 1: Gather Bug Report
@@ -423,6 +452,53 @@ If yes, instruct the user to invoke the `hatch3r-board-fill` command. Note that
 
 ---
 
+## Resumability (Decision 27/30)
+
+bug-plan is long-running — a Tier 2/3 investigation fans out four parallel hatch3r-researcher modes (symptom-trace, root-cause-hypothesis, impact-assessment, regression-research) in Step 3, then assembles the investigation report under `docs/investigations/`, ADRs under `docs/adr/`, and structured `todo.md` entries via the docs-writer. Per hatch3r's workspace-checkpointed resumability contract, checkpoint progress so an interrupted run re-enters at the last completed step rather than re-running the four-researcher fan-out.
+
+> Orchestration boilerplate: see `commands/shared/orchestration-frame.md` → Checkpoint Contract. Per-command slots: workspace `.bug-plan-workspace/`; step range the Step 0 → Step 8 progression; `wave` = researcher-batch index across the 4 parallel modes; snapshot/rollback paths `docs/investigations/`, `docs/adr/`, and `todo.md`; `meta` adds `bugSlug`. Write points: after Step 1 bug-brief context locks, after Step 2 hypothesis space ASK, after the Step 3 four-researcher fan-out returns (all modes complete), after Step 4 root-cause synthesis is confirmed by ASK, after each Step 5 file write (investigation report, ADRs) so already-generated artifacts survive a crash, after Step 6 todo.md entry generation, and after the optional Step 7 chain-to-`hatch3r-board-fill` handoff.
+
+---
+
+## Per-Turn Pipeline-State Header (Bypass Protection)
+
+> Orchestration boilerplate: see `commands/shared/orchestration-frame.md` → Per-Turn Pipeline-State Header. Phase mapping for bug-plan: `1` = reproduction + scope detection, `2` = researcher/debugger dispatch, `3` = root-cause synthesis + fix-plan drafting, `4` = plan write + iteration-summary. Tier 1 runs are exempt per the Tier 1 exemption.
+
+## End-of-Turn Delegation Attestation (Bypass Protection)
+
+> Orchestration boilerplate: see `commands/shared/orchestration-frame.md` → End-of-Turn Delegation Attestation. Per-command mutated-file slot: plan document, fix-spec, regression-test scaffolding.
+
+## Iteration Summary (mandatory output)
+
+Emit the canonical 9-section iteration summary per `rules/hatch3r-iteration-summary.md` as the final user-facing output. The validation gate at `.claude/rules/capability-lifecycle.md` blocks SUCCESS declarations without this block (CONSTITUTION §6 Decision 23).
+
+The 9 sections:
+
+1. **Request** — verbatim restatement of the user's ask in one sentence.
+2. **Fan-out + Cost** — `sub_agents_spawned: { count, rationale }` plus the `cost_estimate` / `cost_actuals` / `delta` blocks (see Cost Visibility below).
+3. **Web Research** — every URL fetched with access date + trust tier per `agents/shared/rigor-contract.md` (0 acceptable when no research was needed).
+4. **Files Mutated** — list with diff summary (lines added / removed / files created).
+5. **Gates Passed / Failed** — explicit list per `.claude/rules/capability-lifecycle.md` Gate Checklist.
+6. **Pillar Impact Attribution** — `progress_toward_pillar: <axis>.<pillar_id>+<delta>` per CONSTITUTION §6 Decision 17.
+7. **Verification Commands** — exact commands run with exit codes plus key output lines (≤200 chars).
+8. **Open Questions / Blockers** — explicit `None` if fully closed.
+9. **Learnings Captured** — IDs of any learnings written to `.hatch3r/learnings/` this run per `rules/hatch3r-learning-system.md`.
+
+### Cost Visibility (Decision 24)
+
+> Orchestration boilerplate: see `commands/shared/orchestration-frame.md` → Cost Estimate for the 5-field `cost_estimate` schema and the post-execution `cost_actuals` + `delta` contract; both land in Section 2 above.
+
+## Cost estimate (Decision 24)
+
+This command emits cost transparency per `rules/hatch3r-cost-visibility.md` and CONSTITUTION §6 Decision 24/29:
+
+- **Pre-execution `cost_estimate`** — emitted in Step 0.5 before the first researcher dispatch.
+- **Post-execution `cost_actuals` + `delta`** — appended to the iteration summary's Fan-out + Cost section per `rules/hatch3r-iteration-summary.md` §2.
+
+Per-tier `expected_sa_count` calibration (from frontmatter `sub_agents_spawned.count: 4` × tier heuristic in `rules/hatch3r-cost-visibility.md` Pre-Execution Estimate): Tier 1 routes to the `hatch3r-bug-fix` skill (no fanout); Tier 2/3 spawn up to 4 parallel researcher modes plus the docs-writer. Deltas beyond 25% absolute value carry `flagged_for_review: true`. Token telemetry sources from `src/pipeline/observability.ts`; estimation primitives from `src/pipeline/costEstimator.ts`.
+
+---
+
 ## Error Handling
 
 - **Sub-agent failure:** Retry the failed sub-agent once. If it fails again, present partial results from the remaining sub-agents and ask the user how to proceed (continue without that researcher's input / provide the missing information manually / abort).
@@ -431,7 +507,7 @@ If yes, instruct the user to invoke the `hatch3r-board-fill` command. Note that
 - **Missing project context:** If no `hatch3r-board-shared` or `.hatch3r/hatch.json` exists, proceed without board context — this command does not require board configuration.
 - **No existing specs or docs:** Proceed without spec references. Warn that the investigation will be less contextualized without existing project documentation. Recommend running `hatch3r-project-spec` or `hatch3r-codebase-map` first for best results.
 - **Duplicate detection:** If the bug overlaps significantly with existing todo.md items, GitHub issues, or prior investigation reports found in Step 2, present the overlap and ASK whether to proceed (augment existing / replace / abort).
-- **No clear root cause:** If all hypotheses are low-confidence, state this clearly. Recommend a focused debugging session (using `hatch3r-bug-fix` skill with the top hypothesis) rather than generating speculative fix items. ASK the user how to proceed.
+- **No clear root cause:** If all hypotheses are low-confidence, state this in the report (named verdict: "Root cause unconfirmed; top hypothesis confidence=low"). Recommend a focused debugging session (using `hatch3r-bug-fix` skill with the top hypothesis) rather than generating speculative fix items. ASK the user how to proceed.
 
 ## Guardrails