hatch3r 1.8.0 → 2.0.0

package/dist/content/commands/hatch3r-handoff.md

@@ -0,0 +1,213 @@
+---
+id: hatch3r-handoff
+type: command
+orchestrator: true
+agentPipeline: [hatch3r-handoff-preparer]
+description: Prepare, resume, list, complete, and prune cross-session handoff documents.
+argument-hint: "prepare | resume [id] | list | complete <id> | prune"
+tags: [orchestration, maintenance]
+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]
+sub_agents_spawned:
+  count: 1
+  rationale: Single hatch3r-handoff-preparer delegation for the `prepare` Tier-2 subcommand; `resume`, `list`, `complete`, `prune` run inline with no sub-agent fan-out (filesystem-read or single-file rename per the Triage table). Cost-dominance per CONSTITUTION §2 P8 — token cost never serializes independent work.
+---
+
+## §0 Detect Ambiguity (P8 B1)
+
+> Orchestration boilerplate: see `commands/shared/orchestration-frame.md` → §0 Detect Ambiguity (P8 B1). Triggers: contradictory inputs, missing target, unknown convention.
+
+## Agent Pipeline
+
+The `prepare` subcommand delegates to `hatch3r-handoff-preparer` via the Task tool. The other four subcommands (`resume`, `list`, `complete`, `prune`) run inline within this command — they read, list, transition status, or archive files and do not require a sub-agent.
+
+**Parallel-safety conditions** (per `rules/hatch3r-agent-orchestration.md` §Parallel Safety): any parallel fan-out holds all three — read-only or disjoint writes, deterministic aggregation, no shared mutable state.
+
+## Learnings Consultation
+
+Before starting, scan `.hatch3r/learnings/` for entries whose `topic`/`applies-to` cover handoff, context-switch, resume, or session-state. Apply the consult procedure in `rules/hatch3r-learning-system.md` → Mandatory Consultation Gate + Consultation Efficiency (INDEX-first scan; surface top 5 by confidence). Skip if the directory has fewer than 3 files.
+
+# Handoff Management — Cross-Session Work Continuity
+
+Manage canonical handoff documents at `.hatch3r/handoffs/active/` for mid-work state capture and resumption across sessions, tools, or developers.
+
+---
+
+## Step 0: Triage
+
+Classify the handoff request by subcommand and operation size before routing:
+
+- **Tier 1 (trivial)**: `list`, `complete`, `prune --dry-run`. Filesystem-read or single-file rename; no body composition, no validation gate, no sub-agent. Run inline.
+- **Tier 2 (standard)**: `prepare`, `resume`, `prune` (non-dry-run). Body composition with readiness gate (`prepare`), drift check + status transition (`resume`), or batch archival (`prune`). `prepare` delegates to `hatch3r-handoff-preparer` via the Task tool; the others run inline.
+
+There is no Tier 3 for this command — multi-issue or epic-scale handoffs are out of scope; the caller decomposes into per-work-item handoffs upstream.
+
+### Step 0.5: Emit Pre-Execution Cost Preview
+
+The `prepare` subcommand is the only one that dispatches a sub-agent. Before invoking `hatch3r-handoff-preparer`, surface the cost preview per `rules/hatch3r-cost-visibility.md` Pre-Execution Estimate. The Tier-1 read/list/rename subcommands (`list`, `complete`, `prune --dry-run`) run inline with `expected_sa_count: 0` and may emit a one-line cost note instead of the full block:
+
+```yaml
+cost_estimate:
+  expected_sa_count: <prepare ~1; list/complete/prune-dry-run = 0>
+  estimated_input_tokens_static_frame: <int>
+  estimated_web_research_queries: 0                # handoff is local-only — no web research
+  triage_tier: light | standard
+  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)
+
+This command has no Tier 3, so `--effort` maps only `light` ↔ `standard`. The override is the recovery path mandated by hatch3r's universal `--effort` override contract ("User overridable via `--effort` flag"):
+
+- `--effort=light|standard` forces the named tier, bypassing the subcommand-derived auto-classification (Step 0). `--effort=deep` is rejected — Tier 3 is out of scope for this command.
+- 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 subcommand-derived classification stands.
+
+## Confidence Propagation Contract
+
+The `prepare` subcommand's `hatch3r-handoff-preparer` delegation prompt MUST include the confidence expression requirement below (verbatim), per the quality charter §1 rule (the inline subcommands produce no graded findings and are exempt).
+
+> 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.
+
+The preparer's readiness assessment and the `resume` drift-check verdict carry a high/medium/low confidence rating; dropping the signal into the Iteration Summary is a gate failure.
+
+## Workflow
+
+Execute these steps in order. **Do not skip any step.** Ask the user at every checkpoint marked with **ASK**.
+
+### Step 1: Detect Subcommand
+
+Read the first positional argument and route to the matching subcommand. If absent or unrecognized:
+
+**ASK:** "Which handoff action? `prepare | resume | list | complete | prune`."
+
+### Step 2: Route
+
+| Subcommand | Semantics |
+|------------|-----------|
+| `prepare` | Capture current session state into a new handoff document |
+| `resume`  | Load and surface a previously-prepared handoff for continuation |
+| `list`    | Show active (and optionally archived) handoffs in a table |
+| `complete`| Transition a handoff to `completed` and move to `archived/` |
+| `prune`   | Archive expired actives and prune archives older than 90 days |
+
+---
+
+## Subcommand: prepare
+
+1. Parse optional flags: `--work-item <ref>` (e.g. `gh:owner/repo#42`, `ado:org/project:work-item/123`, `gl:owner/repo!42`), `--summary "<text>"`.
+2. Invoke `hatch3r-handoff-preparer` via the Task tool. Pass `work_item` and `summary` if provided.
+3. The preparer returns the written path plus an Iteration Summary block. Surface both to the user.
+
+**ASK** (before invocation): "Capturing handoff for {current branch}. Confirm or specify `--work-item` / `--summary`."
+
+## Subcommand: resume
+
+1. Parse optional `<id>` positional. If provided, route directly to `skills/hatch3r-handoff-resume` with that id.
+2. If `<id>` absent, call `listHandoffs({ status: ["open","in-progress","blocked","handed-off"] })` from `src/content/handoffs/index.ts` and present a numbered table (id, status, branch, summary, updated).
+
+**ASK:** "Which handoff to resume? (number, or `cancel`)"
+
+3. Invoke `skills/hatch3r-handoff-resume` with the chosen id. The skill performs validation, drift check, and status transition.
+
+## Subcommand: list
+
+1. Parse flags: `--status <status>`, `--work-item <ref>`, `--include-archived`.
+2. Call `listHandoffs(filter)` and render:
+
+```
+ID                                              STATUS         BRANCH                SUMMARY                                  UPDATED
+2026-05-17_T1430_a3f2c_issue-42-cache-refactor  in-progress    feat/cache-refactor   Token caching for board-fill researcher  2026-05-17 14:30
+```
+
+3. If empty, display: `No active handoffs. Run 'hatch3r-handoff prepare' to capture one.`
+
+## Subcommand: complete
+
+1. Parse positional `<id>` (required). If absent, **ASK** the user to pick from `list`.
+2. Read the handoff via `readHandoff(id)`. Display the `summary` and `Work Remaining` section.
+3. Parse optional `--reason "<text>"` for the archival notice.
+
+**ASK:** "Mark `{id}` completed and archive? (y/N). Reason will be recorded: `{reason or 'no reason given'}`."
+
+4. On confirm: transition `status` to `completed`, stamp `updated` to now, prepend the archival notice (mirrors learnings archival format), then atomic-rename to `.hatch3r/handoffs/archived/<id>.md`.
+
+## Subcommand: prune
+
+1. Parse `--dry-run` flag.
+2. Scan `.hatch3r/handoffs/active/`: collect entries whose `expires_after` ISO-8601 timestamp is at-or-before now (preparer default stamps `created + 30 days`).
+3. Scan `.hatch3r/handoffs/archived/`: collect entries where `updated` is older than 90 days.
+4. Present a two-section preview (Active expirations to archive, Archives to delete).
+5. If `--dry-run`: print the preview and exit.
+
+**ASK:** "Proceed with prune? Will archive {n} active and delete {m} archived. (y/N)"
+
+6. On confirm: archive each expired active (prepend `Expired on {date}` notice, move to `archived/`); delete each over-90-day archive.
+
+---
+
+## Per-Turn Pipeline-State Header (Bypass Protection)
+
+> Orchestration boilerplate: see `commands/shared/orchestration-frame.md` → Per-Turn Pipeline-State Header. Phase mapping for handoff: `1` = action detection (prepare / load / resume / complete / prune), `2` = handoff-preparer / handoff-loader sub-agent dispatch, `3` = validation + integrity verification, `4` = report + 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: handoff document written under `.hatch3r/handoffs/active/`.
+
+## 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 `prepare` subcommand invokes `hatch3r-handoff-preparer`. Inline subcommands emit a one-line `expected_sa_count: 0` cost note.
+- **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: 1` × tier heuristic in `rules/hatch3r-cost-visibility.md` Pre-Execution Estimate): `prepare` ≈ 1 (one preparer delegation); `resume` ≈ 0 (inline drift check + status transition); `list`/`complete`/`prune` ≈ 0 (filesystem read or single-file rename). This command is local-only — `estimated_web_research_queries` is always 0. 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
+
+- `.hatch3r/handoffs/active/` missing or empty: emit `No active handoffs. Run 'hatch3r-handoff prepare' to capture one.` and exit 0.
+- Ambiguous `<id>` (multiple partial matches): list the matches and **ASK** the user to pick one.
+- Write conflict (concurrent prepare for same `work_item`): surface the existing handoff path and **ASK** whether to overwrite (only if existing handoff is older than 24 hours per `writeHandoff` policy).
+- `complete` or `prune` requested on a missing id: report the path that was looked up and suggest `hatch3r-handoff list`.
+
+## Guardrails
+
+- **Never delete** a handoff without explicit user confirmation. Prune deletes only archives older than 90 days, and only after the confirm prompt.
+- **Never modify** a file already in `.hatch3r/handoffs/archived/`. Archived entries are immutable history.
+- **Never include secrets** (API keys, tokens, credentials) in any handoff body. The preparer scans for credential-shaped strings; reject the write if any are detected.
+- **Never write** outside `.hatch3r/handoffs/active/` for new handoffs. Archival is the only path into `archived/`.
+- **Always emit the Iteration Summary block** at the end of the iteration per `rules/hatch3r-iteration-summary.md`.
+
+## References
+
+- `agents/shared/user-question-protocol.md` (B1 gate — applies at §0 Detect Ambiguity above plus every mid-workflow ASK checkpoint per Finding D7-M14)
+- `agents/shared/quality-charter.md` §1, §3, §7, §8 (confidence, ambiguity, measurable criteria)
+- `rules/hatch3r-agent-orchestration.md` (Per-Turn Pipeline-State Header, End-of-Turn Delegation Attestation, Mandatory Delegation Directive)

package/{commands → dist/content/commands}/hatch3r-healthcheck.md

@@ -1,31 +1,84 @@
 ---
 id: hatch3r-healthcheck
 type: command
-orchestrator: false
+orchestrator: true
+agentPipeline: [hatch3r-implementer, hatch3r-ui, hatch3r-security]
 description: Open a QA and reliability epic surveying coverage gaps, flaky tests, and regression blind spots with one testing sub-issue per module plus cross-module wiring audit
 tags: [maintenance]
 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: [2, 3]
+supports_resume: true
+sub_agents_spawned:
+  count: 3
+  rationale: Module-taxonomy discovery and audit-sub-issue authoring delegate to `hatch3r-implementer`; the two cross-cutting QA axes fan out in parallel to `hatch3r-ui` (CQ1 — accessibility / axe-core / design-token / four-state coverage gaps) and `hatch3r-security` (CQ3 — dependency-CVE + supply-chain regression risks). Fan-out is disjoint across the two audit axes; serialization would not preserve P8 B2 task decomposition. 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
 
-This command creates QA audit issues and epics. It does not spawn implementation sub-agents.
+This command discovers the module taxonomy via static analysis, then delegates issue-body authoring and two cross-cutting audit axes to parallel sub-agents via the Task tool. Pipeline:
 
 | Stage | Agent(s) | Parallel | Required |
 |-------|----------|----------|----------|
 | 1. Context & Pre-flight | Orchestrator (inline) | No | Yes |
-| 2. Issue Creation | Orchestrator (GitHub MCP) | No | Yes |
-| 3. Board Sync | Orchestrator (Projects v2 sync) | No | Yes |
+| 2. Module Audit Authoring | `hatch3r-implementer` (one Task call per module sub-issue body) | Yes (across modules) | Yes |
+| 3. Cross-Cutting QA Axes | `hatch3r-ui` (CQ1) + `hatch3r-security` (CQ3, supply-chain slice) (parallel sub-issue authoring) | Yes | Yes |
+| 4. Issue Creation | Orchestrator (GitHub MCP) | No | Yes |
+| 5. Board Sync | Orchestrator (Projects v2 sync) | 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.
 
 All issue operations MUST follow the Projects v2 Enforcement rules defined in `hatch3r-board-shared`.
 
+Sub-agent fan-out scales with module count per `rules/fan-out-discipline.md` (P8 B2). For each discovered module, a `hatch3r-implementer` Task call authors that module's audit sub-issue body in parallel; the two cross-cutting audits (`hatch3r-ui` for CQ1 accessibility coverage, `hatch3r-security` for the CQ3 supply-chain slice) run as one parallel batch.
+
+## Triage
+
+Classify the healthcheck request before fan-out:
+
+- **Tier 2 (standard)**: single repository with discovered module count <=8; parallel module sub-agents bounded by `max_phase4_parallel`.
+- **Tier 3 (deep)**: monorepo with module count >8 OR cross-module wiring depth >=3; same fan-out shape, longer review loop.
+
+Tier is derived from Module Discovery output (Step 2). Tier 1 is not supported — single-target QA fixes belong to `hatch3r-quick-change`.
+
+### Pre-Execution Cost Preview
+
+Before the first sub-agent dispatch (Step 4 module audit-authoring fan-out), surface the cost preview so a wide module fan-out is never started blind. Emit the `cost_estimate` block per `rules/hatch3r-cost-visibility.md` Pre-Execution Estimate, calibrated to the Tier derived from module count:
+
+```yaml
+cost_estimate:
+  expected_sa_count: <module count + 2 cross-cutting axes; Tier 2 ~module-count<=8, Tier 3 module-count>8, bounded by max_phase4_parallel per batch>
+  estimated_input_tokens_static_frame: <int>
+  estimated_web_research_queries: <int>
+  triage_tier: standard | deep
+  estimated_duration_min: <int>
+```
+
+Post-execution actuals + delta land in the Step 6 finalization 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)
+
+Auto-tiering derives from discovered module count, which can misclassify — a monorepo with many small modules over-scored, or a dense single-package repo under-scored. The user override is the recovery path mandated by hatch3r's universal `--effort` override contract ("User overridable via `--effort` flag"):
+
+- `--effort=standard|deep` forces the named tier, bypassing the module-count auto-classification. `--effort=light` is rejected — Tier 1 is unsupported here (single-target QA fixes route to `hatch3r-quick-change`).
+- 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 module-count auto-classification stands.
+
+## 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 authored module-audit sub-issue body and each cross-cutting axis finding MUST carry a high/medium/low confidence rating sourced from the authoring sub-agent. Dropping the signal between stages is a gate failure.
+
 # Healthcheck — Full Product QA & Testing Audit
 
 Create a healthcheck epic on **{owner}/{repo}** with one sub-issue per logical project module, plus cross-module wiring and vision/roadmap alignment audits. Each sub-issue is a deep static-analysis audit task that, when picked up by the board workflow, produces a findings epic with actionable sub-issues for achieving full QA and testing coverage. The command only creates the initial audit epic — it does NOT execute any audits.
@@ -34,7 +87,7 @@ Create a healthcheck epic on **{owner}/{repo}** with one sub-issue per logical p
 
 ## Shared Context
 
-**Read the project's shared board context at the start of the run** (e.g., `.agents/commands/hatch3r-board-shared.md` or equivalent). It contains GitHub Context, Project Reference, Projects v2 sync procedure, and Board Overview template. Cache all values for the duration of this run.
+**Read the project's shared board context at the start of the run** (e.g., `commands/hatch3r-board-shared/SKILL.md` or equivalent). It contains GitHub Context, Project Reference, Projects v2 sync procedure, and Board Overview template. Cache all values for the duration of this run.
 
 ## Token-Saving Directives
 
@@ -313,6 +366,53 @@ All issue and epic operations in this command MUST follow the Projects v2 Enforc
 
 ---
 
+## Resumability (Decision 27/30)
+
+healthcheck is long-running — module discovery (Step 2) seeds a per-module hatch3r-implementer fan-out for audit sub-issue authoring (Step 4) bounded by `max_phase4_parallel`, alongside parallel hatch3r-ui (CQ1) + hatch3r-security (CQ3 supply-chain slice) cross-cutting axes (Step 5), then Step 6 batch-creates GitHub issues and Step 7 syncs Projects v2 board state. Per hatch3r's workspace-checkpointed resumability contract, checkpoint progress so an interrupted run re-enters at the last completed step rather than re-creating issues or re-running implementers for modules already audited.
+
+> Orchestration boilerplate: see `commands/shared/orchestration-frame.md` → Checkpoint Contract. Per-command slots: workspace `.healthcheck-workspace/`; step range the Step 1 → Step 7 progression; `wave` = per-module implementer-batch index across modules and the cross-cutting axes batch; snapshot/rollback paths any module-audit-spec writes under `docs/audits/`. Write points: after Step 2 module discovery locks `discoveredModules`, after each Step 4 implementer batch returns per `max_phase4_parallel` slot (so completed audit-sub-issue bodies survive a crash and are not re-authored), after the Step 5 cross-cutting axes batch returns, after each Step 6 GitHub issue create call records its `issueId` in `createdIssueIds` (so already-created issues survive a crash and are not re-created — the resume path skips issues with an entry in `createdIssueIds`), after Step 6 epic-link creation, and after Step 7 Projects v2 board sync completes.
+
+---
+
+## Per-Turn Pipeline-State Header (Bypass Protection)
+
+> Orchestration boilerplate: see `commands/shared/orchestration-frame.md` → Per-Turn Pipeline-State Header. Phase mapping for healthcheck: `1` = scope + maturity-tier detection, `2` = specialist sub-agent dispatch across health dimensions, `3` = severity-graded aggregation + finding-registry update, `4` = epic/issue write + iteration-summary.
+
+## 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: findings epic, child issues, registry updates.
+
+## 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 the Pre-Execution Cost Preview above before the first module audit-authoring dispatch (Step 4).
+- **Post-execution `cost_actuals` + `delta`** — appended to the Step 6 finalization 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: 3`, which is the static floor; actual fan-out scales with discovered module count per `rules/fan-out-discipline.md` P8 B2): one `hatch3r-implementer` Task per module sub-issue body + `hatch3r-ui` (CQ1) + `hatch3r-security` (CQ3 supply-chain slice) for the two cross-cutting axes. Tier 2 (module count ≤8) and Tier 3 (module count >8) both bound the parallel module batch by `max_phase4_parallel`. 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
 
 - `search_issues` failure: retry once, then warn and proceed (assume no existing healthcheck).

package/dist/content/commands/hatch3r-incident-response.md

@@ -0,0 +1,228 @@
+---
+id: hatch3r-incident-response
+type: command
+orchestrator: true
+agentPipeline: [hatch3r-incident-responder, hatch3r-reliability]
+description: Drive a live production incident through a structured lifecycle -- triage + topology, bounded-autonomy mitigation, stakeholder communication, then a blameless post-mortem with runbook -- via delegated sub-agents.
+tags: [devops, 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]
+sub_agents_spawned:
+  count: 2
+  rationale: One hatch3r-incident-responder specialist drives the live lifecycle (triage → bounded-autonomy mitigation → communication → blameless post-mortem); one hatch3r-reliability specialist runs the post-incident telemetry/SLO reconstruction in parallel once the incident is stabilized. Tier 1 spawns only the incident-response specialist (count 1); a security-suspected incident adds hatch3r-security. Cost-dominance per CONSTITUTION §2 P8 — token cost never serializes independent work.
+---
+
+## §0 Detect Ambiguity (P8 B1)
+
+Before any action, scan the incident report for unresolved questions in scope, impact, irreversibility, or constraint conflicts (user-facing vs internal-only, blast radius unknown, rollback safety unverified, stakeholder-notification scope unspecified, or a mitigation that writes data / changes a schema with downstream consumers). If any are found, ask 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. Live incidents are high-blast-radius, so irreversibility detection on every proposed mitigation is mandatory. Residual ambiguity discovered mid-incident invokes the same protocol.
+
+## Agent Pipeline
+
+| Stage | Agent(s) | Parallel | Required |
+|-------|----------|----------|----------|
+| 1. Triage + topology + mitigate + communicate | `hatch3r-incident-responder` (executes `skills/hatch3r-incident-response/SKILL.md` Steps 1-3) | No | Yes |
+| 2. Post-incident telemetry/SLO reconstruction | `hatch3r-reliability` (CQ4) | Yes (with Stage 3 drafting) | Tier 3, or any P0/P1 with an SLO-burn |
+| 3. Blameless post-mortem + runbook + follow-ups | `hatch3r-incident-responder` (SKILL.md Steps 5-6) | No | When post-mortem required (P0/P1) |
+
+**Parallel-safety conditions** (per `rules/hatch3r-agent-orchestration.md` §Parallel Safety): the Stage 2 reliability reconstruction is read-only against telemetry while Stage 3 drafts the post-mortem — disjoint writes, deterministic aggregation (the reconstruction feeds the post-mortem root-cause section), no shared mutable state.
+
+---
+
+# Incident Response — Triage, Mitigate, Communicate, Learn
+
+Drives a live production incident end-to-end through delegated sub-agents. The orchestrator never edits files or applies mitigations inline; it delegates the live lifecycle to `hatch3r-incident-responder`, runs the post-incident reliability reconstruction in parallel, and integrates the blameless post-mortem.
+
+The detailed runbook — severity table, Bounded Autonomy & Escalation matrix, Telemetry Sources adapter, topology-capture, and the six-step post-mortem template — lives in `skills/hatch3r-incident-response/SKILL.md`. This command orchestrates that runbook through sub-agents; it does not restate it.
+
+**When to use this command vs. the `hatch3r-incident-response` skill vs. the `hatch3r-incident-responder` agent:**
+
+- Use this **command** when: a live incident is open and the response is nontrivial (multi-service blast radius, a mitigation that needs a human gate, or a P0/P1 requiring incident-command discipline and a post-incident reliability reconstruction).
+- Use the **skill** directly when: you are running the runbook yourself inline and want the step-by-step procedure without sub-agent delegation overhead.
+- Use the **agent** directly when: another orchestrator (e.g. a reviewer pass) needs the incident-response specialist for post-incident reconstruction only.
+
+---
+
+## Token-Saving Directives
+
+1. **Read telemetry once per scope.** The incident-response specialist captures the topology + telemetry snapshot once (Stage 1); pass it into the Stage 2 reliability prompt rather than re-querying.
+2. **Targeted reads only.** Read only files on the failure path identified during triage — not the full codebase.
+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 carry the `quality_charter: agents/shared/quality-charter.md` reference in 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 live telemetry. Medium = topology/pattern-based, not directly reproduced. Low = best judgment, recommend human review.
+
+Downstream propagation: every status update, every mitigation gate, and the post-mortem root-cause section MUST carry a high/medium/low rating sourced from the upstream sub-agent. Dropping the signal between stages is a gate failure. A Low-confidence root cause blocks closing the incident.
+
+---
+
+## Workflow
+
+Execute these steps in order. **Do not skip any step.** Ask the user at every checkpoint marked ASK, using the platform-native question tool per `agents/shared/user-question-protocol.md`.
+
+## Step 0: Triage
+
+Classify the incident before delegating, using the `skills/hatch3r-incident-response/SKILL.md` Step 1 severity table:
+
+- **Tier 1 (P3 / minor):** single contained flow, reversible mitigation, no stakeholder paging. Spawn only `hatch3r-incident-responder`; skip Stage 2 reliability reconstruction. Post-mortem optional (recommended only if recurrence-prone).
+- **Tier 2 (P2 / partial degradation):** limited blast radius, reversible mitigation acceptable with a diff preview. Spawn `hatch3r-incident-responder`; run the post-mortem (Stage 3). Add Stage 2 reliability reconstruction if an SLO burned.
+- **Tier 3 (P0/P1 / major incident):** outage, security incident, or wide blast radius. Full pipeline — incident-response specialist with incident-command discipline (no autonomous mutation on P0; human gate on P0/P1 mitigations), parallel `hatch3r-reliability` reconstruction, and a mandatory blameless post-mortem.
+
+Severity-to-tier is recomputed as blast radius is confirmed: an unconfirmed blast radius classifies upward (P3→P2, P2→P1), never downward.
+
+### Step 0.5: Emit Pre-Execution Cost Preview
+
+Before the first sub-agent dispatch (Step 1), surface the cost preview so a delegated incident response is never started blind. Emit the `cost_estimate` block per `rules/hatch3r-cost-visibility.md` Pre-Execution Estimate, calibrated to the Step 0 tier:
+
+```yaml
+cost_estimate:
+  expected_sa_count: <Tier 1 ~1, Tier 2 ~1-2, Tier 3 ~2 (3 if security-suspected)>
+  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 contained nuisance scored Deep, or a creeping outage 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.
+- The override wins over the auto-detected tier; record both so the cost estimate block reports the budget delta.
+- The override does NOT suppress the severity-upgrade safety rule: a `--effort=light` run whose blast radius confirms P0/P1 still runs the Tier-3 incident-command discipline (no autonomous mutation on P0; human gate on mitigation). Safety dominates the cost override.
+- No override passed → the Step 0 auto-classification stands.
+
+---
+
+### Step 1: Triage + Mitigate + Communicate (Live Lifecycle)
+
+Spawn `hatch3r-incident-responder` via the Task tool (`subagent_type: "generalPurpose"`) to execute `skills/hatch3r-incident-response/SKILL.md` Steps 1-4 (classify severity, capture topology, mitigate under the Bounded Autonomy & Escalation matrix, communicate to stakeholders).
+
+The specialist prompt MUST include: the incident brief (symptoms, detection time, observed impact, affected environment, any recent deploys/config changes), the Step 0 tier + severity, all `scope: always` rule directives from `rules/`, a `correlation_id` (UUID v4 per `rules/hatch3r-agent-orchestration.md` → Correlation ID), the confidence expression requirement above, and the bounded-autonomy gate contract (verbatim):
+
+> Bounded-autonomy gate: prefer the reversible mitigation (flag flip, kill-switch, config revert, scale-up, deploy rollback) over an irreversible one. Emit a diff preview (exact command/flag/config delta) before executing any auto-applied mutation. On a P0 incident, do NOT self-execute — investigate, build the timeline, propose the diff, and return for human approval. On P1, auto-apply only high-confidence reversible actions with a diff preview; medium/low-confidence or irreversible actions escalate to a human gate. Record every action in the incident timeline with actor, timestamp, and gate decision.
+
+**ASK (mitigation gate — fires on every P0, and on any P1/irreversible action):** "Incident severity {P0-P3}. Proposed mitigation: {one-line + diff preview} (confidence {high/medium/low}, reversible: {yes/no}). Apply? (apply / adjust mitigation / escalate to on-call / investigate further)". For reversible high-confidence mitigations on P2/P3, the specialist may auto-apply with a diff preview and report it — no ASK required.
+
+After the specialist returns, verify the mitigation against telemetry (error rate dropped, affected flow recovered) before declaring the incident stabilized. If the mitigation introduced a new issue, roll it back immediately and re-derive — per the skill's Error Handling.
+
+---
+
+### Step 2: Post-Incident Reliability Reconstruction (Tier 3 / SLO-burn; parallel with Step 3)
+
+Once the incident is stabilized, spawn `hatch3r-reliability` via the Task tool to reconstruct which CQ4 floors held at incident time — SLO burn, span coverage on the failing path, RED/USE signal availability, resilience-pattern presence on the implicated outbound call. This runs read-only against telemetry, in parallel with the Step 3 post-mortem drafting.
+
+The reliability prompt MUST include: the stabilized incident summary + topology map from Step 1, the failing service + route, all `scope: always` rule directives, the `correlation_id`, and the confidence expression requirement. Its output feeds the post-mortem's root-cause and action-item sections (e.g. "readiness probe gated on liveness signal — add dependency-health gate" as a follow-up).
+
+Skip this stage for Tier 1, and for Tier 2 incidents where no SLO burned.
+
+---
+
+### Step 3: Blameless Post-Mortem + Runbook + Follow-Ups
+
+Spawn `hatch3r-incident-responder` to execute `skills/hatch3r-incident-response/SKILL.md` Steps 5-6: write the blameless post-mortem (summary, timeline, root cause, impact, action items, lessons), author an alert-linked runbook for the failure mode, and file one follow-up issue per action item via the project's platform CLI.
+
+The specialist prompt MUST include: the Step 1 timeline + mitigation record, the Step 2 reliability reconstruction (when run), all `scope: always` rule directives, the `correlation_id`, the confidence expression requirement, and the blameless-post-mortem contract (verbatim):
+
+> Blameless post-mortem contract: assume every responder acted on the best information available. Focus on contributing causes, not individual fault. Do not name individuals as the cause. The root-cause section carries a confidence rating; a Low-confidence root cause keeps the post-mortem open (do not declare the incident closed). Strip secrets, PII, and proprietary code from the document.
+
+Skip the post-mortem for Tier 1 incidents unless the failure mode is recurrence-prone.
+
+---
+
+### Step 4: Summary + Git Action
+
+1. Present a concise completion summary:
+
+```
+Incident Response Complete:
+  Severity:        {P0-P3}
+  Blast radius:    {impacted node | upstream callers | downstream deps}
+  Mitigation:      {one-line — reversible/irreversible, gate decision}
+  Recovery:        {telemetry-verified: error rate dropped / flow recovered}
+  Post-mortem:     {path/issue — blameless, root cause confidence high/medium/low}
+  Follow-ups:      {N issues filed}
+  Confidence:      {high/medium/low — overall incident verdict}
+```
+
+2. **ASK:** "Incident stabilized and post-mortem drafted. How should I handle the post-mortem + follow-up artifacts in git? (a) commit only, (b) commit and push, (c) skip git — leave in working tree". Applied mitigations on live infrastructure are NOT a git action — they are already recorded in the incident timeline.
+
+Commit message format: `docs: post-mortem for {incident-slug}` (post-mortem + runbook are documentation/follow-up artifacts). For pushes, fall back to `git push -u origin {branch}` when no upstream exists.
+
+---
+
+## Per-Turn Pipeline-State Header (Bypass Protection)
+
+> Orchestration boilerplate: see `commands/shared/orchestration-frame.md` → Per-Turn Pipeline-State Header. Phase mapping for incident-response: `1` = triage + topology + mitigate + communicate (incident-response specialist), `2` = post-incident reliability reconstruction (reliability), `3` = blameless post-mortem + runbook + follow-ups (incident-response specialist), `4` = summary + git + 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: post-mortem document, runbook, follow-up issue drafts, config/flag diffs authored for review. This command has no Tier-1 inline carve-out for file mutations: post-mortem and runbook authoring always flow through the `hatch3r-incident-responder` 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
+
+- **Cannot reproduce the incident locally:** use production telemetry to build the timeline per the skill's Error Handling; record the local-reproduction gap as a post-mortem action item.
+- **Mitigation introduces a new issue:** roll back the mitigation immediately, reassess, apply a more targeted fix; document both the original incident and the mitigation regression in the post-mortem.
+- **Specialist sub-agent failure (Step 1):** the incident is live — surface the partial state and **ASK** immediately (provide missing context / escalate to on-call human / abort delegation and hand the live incident to the operator). Never silently retry a live-mitigation step.
+- **Root cause unconfirmed (all hypotheses Low-confidence):** do not close the incident. State the verdict ("Root cause unconfirmed; top hypothesis confidence=low") and keep the post-mortem open with an investigation action item.
+- **Root cause spans multiple services or teams:** document the cross-service dependency chain, assign follow-ups to the responsible teams, and recommend a joint post-mortem per the skill's Error Handling.
+- **Suspected security breach surfaced mid-incident:** add `hatch3r-security` to the pipeline for the threat assessment; this command retains ownership of the timeline and mitigation discipline.
+
+## Resumability (Decision 27/30)
+
+A live incident is long-running and a responder hand-off mid-incident is common, so checkpoint the lifecycle — a resumed run re-enters at the last completed stage rather than re-applying a mitigation already executed or re-filing follow-up issues already filed. Applied live-infra mitigations are recorded in the incident timeline, not the checkpoint, so resumption never re-executes a flag flip or rollback.
+
+> Orchestration boilerplate: see `commands/shared/orchestration-frame.md` → Checkpoint Contract. Per-command slots: workspace `.incident-workspace/`; step range the Step 0 → Step 4 progression; `wave` = the post-mortem drafting iteration; snapshot/rollback paths every authored artifact (post-mortem document, runbook, follow-up drafts). Write points: after the Step 0 triage, after the Step 1 mitigation record (the mitigation timeline is the source of truth — the checkpoint references it, never re-executes it), after the Step 2 reliability reconstruction, and after the Step 3 post-mortem + follow-ups.
+
+## Guardrails
+
+- **Reversibility-first.** Prefer reversible mitigations; an irreversible action escalates one severity band and always routes to a human gate.
+- **No autonomous mutation on P0.** P0 incidents: investigate, build the timeline, propose the diff, page for approval — never self-execute.
+- **Diff preview before apply.** Any auto-applied mutation emits the exact change before execution, never after.
+- **Always delegate.** All file mutation (post-mortem, runbook, follow-up drafts) flows through `hatch3r-incident-responder` via the Task tool — no inline edits from the orchestrator turn.
+- **Blameless post-mortems.** Never assign individual blame; focus on contributing causes.
+- **Confidence propagation.** Every status update, mitigation gate, and post-mortem root-cause section carries a confidence rating from the upstream sub-agent. Dropping the signal is a gate failure.
+- **Hygiene.** Strip secrets, PII, and proprietary code from the post-mortem, the incident channel, and logs.
+- **This command composes existing hatch3r artifacts** (`hatch3r-incident-responder` agent + skill, `hatch3r-reliability`) — it orchestrates the runbook through sub-agents; it does not replace the skill or restate the runbook.
+
+---
+
+## References
+
+- `skills/hatch3r-incident-response/SKILL.md` — the runbook this command orchestrates (severity table, Bounded Autonomy & Escalation matrix, Telemetry Sources, topology capture, six-step post-mortem); accessed 2026-06-02, trust tier: official-docs (in-repo canonical).
+- `agents/hatch3r-incident-responder.md` — the specialist this command delegates the live lifecycle and post-mortem to; accessed 2026-06-02, trust tier: official-docs (in-repo canonical).
+- `commands/hatch3r-bug-pipeline.md` — orchestrator command structure + Per-Turn Header / Delegation Attestation / Iteration Summary / Cost Visibility block patterns mirrored here; accessed 2026-06-02, trust tier: official-docs (in-repo canonical).
+- PagerDuty — "Incident Response Documentation: Severity Levels" (https://response.pagerduty.com/before/severity_levels/) — accessed 2026-06-02, PagerDuty, **official-docs**. Source for the severity-to-response escalation mapping (SEV-1/SEV-2 → major-incident response with incident-commander paging) that the Step 0 tiering and Step 1 mitigation gate map onto the skill's P0-P3 table.
+- Atlassian — "The Atlassian Incident Management Handbook" (https://www.atlassian.com/incident-management/handbook) — accessed 2026-06-02, Atlassian, **official-docs**. Source for incident-command authority (single owner empowered to coordinate, page, and gate) and the blameless-post-mortem-for-SEV2+ practice with a post-incident review within 24-48 hours encoded in Step 3.