hatch3r 1.9.0 → 2.0.0

package/dist/content/commands/hatch3r-codebase-map.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: 8
-  rationale: Eight parallel analyzer domains in Step 3 across business + technical dimensions (modules, dependencies, conventions, stack, technical-debt, business-domain, market-context, production-readiness); docs-writers fan out in a second parallel batch in Step 7 (one per document category).
+  rationale: Eight parallel analyzer domains in Step 3 across business + technical dimensions (modules, dependencies, conventions, stack, technical-debt, business-domain, market-context, production-readiness); docs-writers fan out in a second parallel batch in Step 7 (one per document category). 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.
 
 # Codebase Map — Brownfield Codebase Analysis & Spec Generation
 
@@ -31,6 +33,8 @@ Analyze an existing codebase to reverse-engineer project documentation across **
 | 2. Document Generation | `hatch3r-docs-writer` (parallel: technical spec, business spec, ADRs, health report) | Yes | Yes |
 | 3. AGENTS.md | `hatch3r-docs-writer` (AGENTS.md generation/rework) | 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.
+
 ---
 
 ## Shared Context
@@ -46,6 +50,12 @@ Analyze an existing codebase to reverse-engineer project documentation across **
 
 ---
 
+## Confidence Propagation Contract
+
+> Orchestration boilerplate: see `commands/shared/orchestration-frame.md` → Confidence Propagation Contract. Readiness kind: map.
+
+---
+
 ## Workflow
 
 Execute these steps in order. **Do not skip any step.** Ask the user at every checkpoint marked with ASK. When in doubt, **ASK** — it is better to ask one question too many than to make one wrong assumption. Discovery questions are never wasted.
@@ -60,6 +70,25 @@ Classify the codebase analysis request before delegating:
 
 If Tier 1, run the reduced analyzer set and skip Step 5 (ADRs) unless decisions are obvious. If Tier 2, run the standard pipeline below. If Tier 3, run the full pipeline including the production-readiness scorecard and confirm scope with the user before file writes.
 
+### Step 0.5: Emit Pre-Execution Cost Preview
+
+Before the first analyzer dispatch (Step 1), surface the cost preview so a multi-analyzer scan 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 ~2, Tier 2 ~6, Tier 3 up to 8>
+  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 single-subsystem map scored as Deep, or a monorepo scored as Light.
+
 ---
 
 ### Step 1: Initial Scan, Scope & Discovery
@@ -640,7 +669,7 @@ Grading Baseline: {what "good" looks like for this stage}
   3. {risk} — {mitigation}
 
 ## Stage-Appropriate Recommendations
-{Ordered list of actions calibrated to the company stage — do not recommend enterprise-grade solutions for pre-revenue startups}
+{Ordered list of actions calibrated to the company stage — do not recommend enterprise-tier (per CONSTITUTION §6 Decision 4) solutions for solo-tier pre-revenue startups}
 ```
 
 ---
@@ -1214,6 +1243,53 @@ Which would you like to run next? (or none)"
 
 ---
 
+## Resumability (Decision 27/30)
+
+codebase-map is long-running — a Tier 3 brownfield analysis fans out eight parallel hatch3r-researcher analyzer domains in Step 3 (modules, dependencies, conventions, stack, technical-debt, business-domain, market-context, production-readiness), then runs a second parallel batch of docs-writers in Step 7 (one per document category: technical spec, business spec, ADRs, health report) plus a single AGENTS.md generation pass. 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 eight-analyzer + docs-writer-batch fan-out.
+
+> Orchestration boilerplate: see `commands/shared/orchestration-frame.md` → Checkpoint Contract. Per-command slots: workspace `.codebase-map-workspace/`; step range the Step 0 → Step 9 progression; `wave` = analyzer-batch index across the 8 parallel domains, then docs-writer-batch index; snapshot/rollback paths `docs/specs/business/`, `docs/specs/technical/`, `docs/adr/`, and `AGENTS.md`. Write points: after Step 1 repo fingerprint locks, after Step 2 scope ASK, after the Step 3 eight-analyzer fan-out returns (all domains complete), after Step 4 synthesis confirmed by ASK, after each Step 5 file write under `docs/specs/business/` and `docs/specs/technical/`, after Step 6 ADR generation, after the Step 7 docs-writer batch returns, and after Step 8 AGENTS.md regeneration.
+
+---
+
+## Per-Turn Pipeline-State Header (Bypass Protection)
+
+> Orchestration boilerplate: see `commands/shared/orchestration-frame.md` → Per-Turn Pipeline-State Header. Phase mapping for codebase-map: `1` = repo discovery + scope detection, `2` = explore sub-agent dispatch + module enumeration, `3` = aggregation + cross-reference graph build, `4` = map 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: map document, module index, dependency-graph artifacts.
+
+## 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 analyzer 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: 8` × tier heuristic in `rules/hatch3r-cost-visibility.md` Pre-Execution Estimate): Tier 1 ≈ 2 (reduced analyzer set); Tier 2 ≈ 6; Tier 3 up to 8 parallel analyzers. 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 analyzer once with the same prompt. If it fails again, present partial results from the other analyzers and note the gap. Ask the user whether to continue with partial data or abort.
@@ -1237,6 +1313,6 @@ Which would you like to run next? (or none)"
 - **Handle monorepos by detecting workspace configuration** (`workspaces` in `package.json`, `pnpm-workspace.yaml`, `turbo.json`, `nx.json`, `lerna.json`, Cargo workspaces, Go workspaces) and analyzing each package as a separate module.
 - **If `todo.md` already exists,** ASK before overwriting or appending.
 - **Sub-agents must not create files.** They return structured text results to the orchestrator. Only the orchestrator writes files in Step 7.
-- **Stage-adaptive recommendations.** Never recommend enterprise-grade solutions for pre-revenue startups. Never recommend MVP shortcuts for scale/enterprise companies. Calibrate all recommendations to the company stage from Step 1g.
+- **Stage-adaptive recommendations.** Never recommend enterprise-tier (per CONSTITUTION §6 Decision 4) solutions for solo-tier pre-revenue startups. Never recommend MVP shortcuts for scaleup-tier or enterprise-tier companies. Calibrate all recommendations to the company stage from Step 1g.
 - **Business specs must cross-reference technical specs.** Use stable IDs from both glossaries to link business entities to technical modules.
 - **Never overwrite `AGENTS.md`** without explicit user confirmation.

package/dist/content/commands/hatch3r-create.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: standard
 triage_tiers: [1, 2, 3]
+supports_resume: true
 sub_agents_spawned:
   count: 1
-  rationale: Single hatch3r-creator delegation in Phase 2 — body composition plus the strict + gentle gate funnel run as one atomic Task per artifact; multi-artifact runs invoke one creator per artifact in parallel.
+  rationale: Single hatch3r-creator delegation in Phase 2 — body composition plus the strict + gentle gate funnel run as one atomic Task per artifact; multi-artifact runs invoke one creator per artifact in 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.
 
 ## Agent Pipeline
 
@@ -47,6 +49,39 @@ If Tier 1, run Phase 1 with reduced prompts (skip optional dimensions). If Tier
 
 **Parallel-dispatch directive:** When two or more steps below are independent (no shared files, no data dependency), issue all tool calls or sub-agent spawns in a single turn. Sequential dispatch of independent work is a finding under P7 (efficiency charter §P2).
 
+**Parallel-safety conditions** (per `rules/hatch3r-agent-orchestration.md` §Parallel Safety): every parallel fan-out (multi-artifact runs spawning one creator per artifact) holds all three — read-only or disjoint writes, deterministic aggregation, no shared mutable state.
+
+### Step 0.5: Emit Pre-Execution Cost Preview
+
+Before the Phase 2 `hatch3r-creator` delegation, surface the cost preview per `rules/hatch3r-cost-visibility.md` Pre-Execution Estimate. One artifact = one creator; a multi-artifact run scales `expected_sa_count` with the artifact count:
+
+```yaml
+cost_estimate:
+  expected_sa_count: <1 per artifact authored>
+  estimated_input_tokens_static_frame: <int>
+  estimated_web_research_queries: <int>            # Decision 14 reputable-source recon for new agent/skill/rule bodies; 0 for trivial edits
+  triage_tier: light | standard | deep
+  estimated_duration_min: <int>
+```
+
+The Phase 1 input-collection ASKs are user-driven and excluded from the duration estimate. Post-execution actuals + delta land in the Phase 3 housekeeping 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 can misclassify — a snippet rule scored as Deep, or a tool-allowlisted agent scored as 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 (which controls Phase 1 dimension-probing depth).
+- 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.
+
+## Confidence Propagation Contract
+
+The Phase 2 `hatch3r-creator` delegation prompt MUST include the confidence expression requirement below (verbatim), per the quality 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.
+
+The creator's strict/gentle gate verdict and any Decision-14 reputable-source synthesis carry a high/medium/low confidence rating; the Phase 3 validate report MUST preserve the signal. Strict-gate pass/fail (a hard gate) is distinct from and additional to this confidence signal.
+
 ---
 
 ### Phase 1 — Collect & Plan
@@ -87,9 +122,9 @@ Reject and re-ask if the description is shorter than 60 characters. Cache as `de
 
 #### 1.4: Tags
 
-Present the known tag set: `core, customization, planning, implementation, review, performance, a11y, security, board`.
+Present the known capability tags (the registered set in `src/content/tags.ts::TAG_REGISTRY` — single source of truth): `orchestration, planning, implementation, review, devops, maintenance, board, performance, ai` plus the content-quality vectors `security, reliability, testing, scalability, maintainability, enhancability` and work-type tags `spec, migration`. Lead with a capability tag (it is the primary classification — `tags[0]` groups the artifact in the picker per `.claude/rules/content-authoring.md` item 12). Append context facets (`ctx:team-only`, `ctx:greenfield-only`, `ctx:brownfield-only`) and floor facets (`floor:security`, `floor:ui-ux`, `floor:protocol`, `floor:content-quality`) after the primary, never first.
 
-**ASK:** "Select one or more tags (comma-separated). You may add custom project tags after the known set, e.g., `implementation, my-team`."
+**ASK:** "Select one or more tags (comma-separated), capability tag first. You may add custom project tags after the known set, e.g., `implementation, my-team`."
 
 Cache as `tags` (array).
 
@@ -113,6 +148,12 @@ Which pillar(s) does this artifact serve? (one or more — comma-separated)
 
 Reject empty input and re-ask. Validate every entry against the `P1..P8` enum. Cache as `pillars` (array). The frontmatter emitter writes the array as `pillars: [P1, P4]`; the strict gate also accepts a `**Pillars:** ...` line in the body.
 
+#### 1.4b: Pillar Rationale (Optional, D20-F20.1.D4)
+
+**ASK:** "(Optional — press Enter to skip) One-sentence rationale per pillar selected above: which measurable improvement does this artifact produce on each? E.g., `P4: removes the 3rd duplicate review skill; P6: adds a secrets-scan deny pattern`."
+
+This operationalizes the Pillar Compliance Test #1+#2 (`CLAUDE.md` → Two-Axis Pillar Framework) for user content — declaration alone earns existence at the strict gate, but a stated measurable improvement is the discipline the framework holds itself to. Cache as `pillarRationale` (`Record<P_id, string>`); when supplied, embed it verbatim under the `**Pillars:** ...` body line. Skippable — no strict-gate dependency.
+
 #### 1.5: Adapter Scope (Optional)
 
 **ASK:** "Restrict this artifact to specific adapters? Press Enter to default to ALL enabled adapters (full parity), or list adapter names like `claude, cursor`."
@@ -127,7 +168,7 @@ Branch on the cached `type`:
 - **skill:** Confirm the subdirectory layout. Show: "Skill files are stored as `.hatch3r/overrides/skills/{name}/SKILL.md` (a new directory will be created). Continue?" — ASK Y/n.
 - **rule:** Ask for scope: `always` (loaded every session) or `conditional` (loaded by glob match). If `conditional`, ASK for a comma-separated glob list (e.g., `src/**/*.ts, src/**/*.tsx`). Then ASK for `precedence` (one of `critical | high | normal | low`, default `normal`). Cache as `ruleScope`, `ruleGlobs`, `rulePrecedence`.
 - **command:** ASK whether this is an orchestrator command. If yes, ASK for the agent pipeline as a comma-separated list of agent IDs (each ID must reference an existing agent — canonical or under `.hatch3r/overrides/agents/`). Cache as `isOrchestrator` and `agentPipeline`.
-- **hook:** ASK for the hook event from the enum: `pre-commit | post-merge | ci-failure | file-save | session-start | pre-push`. Reject any value outside this enum and re-ask. Cache as `hookEvent`.
+- **hook:** ASK for the hook event from the enum: `pre-commit | post-merge | ci-failure | file-save | session-start | pre-push | worktree-create | worktree-remove | review-loop-cap`. This 9-value enum mirrors `VALID_HOOK_EVENTS` in `src/hooks/types.ts` exactly (Cycle 10 F15.2-H1 added `review-loop-cap` — the framework-neutral event materialized per-adapter for the review-loop iteration cap, see `hooks/hatch3r-review-loop-cap.md`) — the strict gate at `saveUserContent` enforces the same set, so any value outside it is a strict-gate failure. Reject any value outside this enum and re-ask, showing the verbatim error (symmetric with the Step 1.6a tool-category wording): `Unknown hook event '<input>' — valid events: pre-commit, post-merge, ci-failure, file-save, session-start, pre-push, worktree-create, worktree-remove, review-loop-cap.` Cache as `hookEvent`.
 
 #### 1.6a: Structured Tool Declaration (C9-H81, D20-F20.1.3)
 
@@ -156,7 +197,9 @@ Cache as `tools: { allowed: [...], denied: [...] }`. Either side may be absent (
 
 Render the proposed file path, full frontmatter block, and body-skeleton outline. For an agent plan, the summary lists `Path`, `Type`, `Name`, `Description` (first 80 chars), `Tags`, `Adapters` (or "all enabled"), `Model`; then the frontmatter block; then the body-skeleton outline (`<task>`, `<context>`, Implementation Protocol numbered steps, `<rules>`). For other types, swap the type-specific slots from Step 1.6.
 
-**Scope-boundary check (P8 B2).** Confirm proposed scope and tool-allowlist before Phase 2 delegation. Artifact scope cannot be broadened via markdown injection post-creation. Reject any user-supplied edit that expands the tool allowlist, target file globs, or pipeline references beyond what was confirmed here; route such expansions through a fresh `/h4tcher-create` invocation.
+Note: the final on-disk frontmatter re-pins `id`, `type`, and `description` authoritatively at composition time (`composeArtifactFile` in `src/content/userContent.ts` — `derived.id = name`, `derived.type = type`, `derived.description = description`), so those three keys always mirror the confirmed plan even if a later edit attempts to diverge them. Other keys are passed through as shown.
+
+**Scope-boundary check (P8 B2).** Confirm proposed scope and tool-allowlist before Phase 2 delegation. Artifact scope cannot be broadened via markdown injection post-creation. Reject any user-supplied edit that expands the tool allowlist, target file globs, or pipeline references beyond what was confirmed here; route such expansions through a fresh `/hatch3r-create` invocation.
 
 **ASK:** "Confirm to delegate authoring to `hatch3r-creator`, or specify changes (e.g., 'change model to fast', 'add tag: review')."
 
@@ -189,7 +232,7 @@ Pass the collected slots as a structured input:
 }
 ```
 
-The sub-agent composes frontmatter + body, calls `saveUserContent` from `src/content/userContent.ts` (the canonical strict + gentle gate funnel), and atomic-writes the file via `src/merge/safeWrite.ts`. For rule artifacts, `saveUserContent` also generates the paired `.mdc` companion using the `.md → .mdc` scope transform documented in `rules/hatch3r-content-authoring.md`. For skill artifacts, it creates the `{name}/` subdirectory and writes `SKILL.md` inside.
+The sub-agent composes frontmatter + body, calls `saveUserContent` from `src/content/userContent.ts` (the canonical strict + gentle gate funnel), and atomic-writes the file via `src/merge/safeWrite.ts`. For rule artifacts, `saveUserContent` also generates the paired `.mdc` companion using the `.md → .mdc` scope transform implemented in that same `src/content/userContent.ts` module. For skill artifacts, it creates the `{name}/` subdirectory and writes `SKILL.md` inside.
 
 Wait for the sub-agent's structured return:
 
@@ -235,6 +278,53 @@ Edit your artifact directly anytime — `.hatch3r/overrides/` is preserved acros
 
 ---
 
+## Resumability (Decision 27/30)
+
+create is long-running in multi-artifact mode — Phase 1 collects every artifact's frontmatter inputs upfront, Phase 2 delegates one `hatch3r-creator` Task per artifact (parallel when artifacts are independent), and Phase 3 runs `hatch3r validate` plus the strict + gentle gate funnel. Per hatch3r's workspace-checkpointed resumability contract, checkpoint progress so an interrupted run re-enters at the last completed step rather than re-prompting collected inputs or re-running already-completed creator delegations.
+
+> Orchestration boilerplate: see `commands/shared/orchestration-frame.md` → Checkpoint Contract. Per-command slots: workspace `.create-workspace/`; step range the command's step progression; `wave` = creator-batch index in multi-artifact mode; snapshot/rollback paths `.hatch3r/overrides/{type}/` and adapter sync targets. Write points: after each Phase 1 ASK is confirmed and `artifactPlan` is fully assembled, after the plan-summary ASK in Step 1.7, after each Phase 2 creator delegation returns (one checkpoint per artifact so already-saved overrides under `.hatch3r/overrides/{type}/` survive a crash and are not re-authored on resume), after Phase 3 strict-gate funnel passes, and after the optional adapter sync.
+
+---
+
+## Per-Turn Pipeline-State Header (Bypass Protection)
+
+> Orchestration boilerplate: see `commands/shared/orchestration-frame.md` → Per-Turn Pipeline-State Header. Phase mapping for create: `1` = type + name detection + collision scan, `2` = creator sub-agent dispatch (artifact composition + gate funnel), `3` = validation + override verification, `4` = post-write reporting + 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: user-tier artifact written under `.hatch3r/overrides/`.
+
+## 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 Phase 2 `hatch3r-creator` delegation.
+- **Post-execution `cost_actuals` + `delta`** — appended to the Phase 3 housekeeping 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` × artifact count): one `hatch3r-creator` per artifact authored. `estimated_web_research_queries` reflects the Decision 14 reputable-source reconnaissance for new agent/skill/rule bodies (≥2 sources), and is 0 for trivial frontmatter-only or single-line edits. 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`.
+
+---
+
 ## Constraints / Anti-Patterns
 
 - **Never overwrite an existing user file.** Collision with an existing path under `.hatch3r/overrides/{type}/` is a strict-gate failure raised by `hatch3r-creator` (status `BLOCKED` with the conflicting path).
@@ -250,3 +340,11 @@ Edit your artifact directly anytime — `.hatch3r/overrides/` is preserved acros
 ## Quality Charter
 
 This command and the `hatch3r-creator` sub-agent both inherit the standards in `agents/shared/quality-charter.md` — confidence levels, root-cause orientation, measurable acceptance criteria, and graceful failure with corrective messages.
+
+## 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)
+- `agents/hatch3r-creator.md` (delegated authoring sub-agent)
+- `agents/shared/user-content-templates.md` (frontmatter shapes + body skeletons)

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

@@ -2,17 +2,19 @@
 id: hatch3r-debug
 type: command
 orchestrator: true
-agentPipeline: [hatch3r-researcher, hatch3r-implementer, hatch3r-reviewer, hatch3r-fixer, hatch3r-test-writer, hatch3r-security-auditor]
+agentPipeline: [hatch3r-researcher, hatch3r-implementer, hatch3r-reviewer, hatch3r-fixer, hatch3r-testability, hatch3r-security]
 description: Standalone debug-and-fix workflow — add strategic debug logging, collect runtime logs from the user, perform root cause analysis, implement the fix, and clean up all debug artifacts.
 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: 6
-  rationale: Six-stage pipeline per agentPipeline — researcher → implementer → reviewer ↔ fixer review loop (max 3 iterations) → parallel final-quality pass (test-writer + security-auditor); serialization only across true dependency edges (logs → root cause → fix → verify).
+  rationale: Six-stage pipeline per agentPipeline — researcher → implementer → reviewer ↔ fixer review loop (max 3 iterations) → parallel final-quality pass (testability (CQ5) + security (CQ3)); serialization only across true dependency edges (logs → root cause → fix → verify). Cost-dominance per CONSTITUTION §2 P8 — token cost never serializes independent work.
 ---
 ## §0 Detect Ambiguity (P8 B1)
 
@@ -40,7 +42,9 @@ Standalone debug-and-fix command that instruments the codebase with strategic de
 | 4. Root Cause Analysis | `hatch3r-researcher` (mode: `root-cause`) | No | Yes |
 | 5a. Fix | `hatch3r-implementer` | No | Yes |
 | 5b. Review Loop | `hatch3r-reviewer` → `hatch3r-fixer` (max 3) | No | Yes |
-| 5c. Final Quality | `hatch3r-test-writer` + `hatch3r-security-auditor` | Yes | Yes |
+| 5c. Final Quality | `hatch3r-testability` + `hatch3r-security` | Yes | 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.
 
 ---
 
@@ -56,7 +60,7 @@ This command intentionally skips:
 It retains:
 - Quality checks (lint, typecheck, test) — always mandatory
 - Sub-agent delegation for all non-trivial work
-- Full review pipeline in Stage 5 (reviewer, test-writer, security-auditor)
+- Full review pipeline in Stage 5 (reviewer, testability (CQ5), security (CQ3))
 - `scope: always` rules from `rules/`
 - Debug artifact cleanup guarantee
 
@@ -88,6 +92,14 @@ If the user declines, skip all browser steps. Do not ask again during the sessio
 4. **No shared context loading.** Do NOT read `hatch3r-board-shared`. This is a standalone command.
 5. **Targeted file reads only.** Read only files in the affected area identified in Stage 1.
 
+## 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 diagnosis quality (Stage 4b root cause confidence), every gate that evaluates a sub-agent verdict (Stage 5c review loop), and the Stage 5f fix summary MUST carry a high/medium/low confidence rating sourced from the upstream sub-agent. Dropping the signal between stages is a gate failure.
+
 ---
 
 ## Workflow
@@ -104,6 +116,29 @@ Classify the debug request before delegating:
 
 If Tier 1, run the standard stages with reduced researcher depth. If Tier 2, run the full pipeline below. If Tier 3, expand researcher modes (add `regression` if relevant) and confirm the diagnosis with the user before Stage 5.
 
+### Pre-Execution Cost Preview
+
+Before the first sub-agent dispatch (Stage 2a researcher), surface the cost preview so a multi-stage debug session is never started blind. Emit the `cost_estimate` block per `rules/hatch3r-cost-visibility.md` Pre-Execution Estimate, calibrated to the Triage tier:
+
+```yaml
+cost_estimate:
+  expected_sa_count: <triage tier → Tier 1 ~3, Tier 2 ~5, Tier 3 up to 6>
+  estimated_input_tokens_static_frame: <int>
+  estimated_web_research_queries: <int>
+  triage_tier: light | standard | deep
+  estimated_duration_min: <int>
+```
+
+The log-collection checkpoint (Stage 3) is user-driven and excluded from the duration estimate. Post-execution actuals + delta land in the Stage 5f fix 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 can misclassify — a single-file bug scored as Deep, or an intermittent cross-module bug scored as 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 Triage auto-classification (which sets researcher depth and mode breadth).
+- 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 Triage auto-classification stands.
+
 ---
 
 ### Stage 1: Gather Bug Context
@@ -128,7 +163,7 @@ You can also paste an error log, stack trace, or screenshot description and I'll
    - `docs/specs/` — project specifications (read TOC/headers first, expand relevant sections only)
    - `README.md` — project overview and setup instructions
    - `AGENTS.md` or `rules/` — agent rules and project conventions
-2. If `.hatch3r/learnings/` exists, scan for learnings relevant to the affected area. Match by area and tags against the bug description.
+2. If `.hatch3r/learnings/` exists, scan for learnings relevant to the affected area. Match by area and tags against the bug description. Learnings are **consulted only** in this command — debug fixes the immediate defect and does not write new learnings (deliberate skip, parallel to `hatch3r-quick-change` Token-Saving Directive 4); durable bug-pattern learnings are captured by `hatch3r-workflow` Phase 4e and `hatch3r-revision` Step 10 when a fix lands through those flows. Iteration-summary item 9 ("Learnings Captured") therefore reads `None` for a standalone debug run.
 3. Scan the affected code area — read the primary files involved, trace imports and dependencies one level deep.
 
 **Knowledge hierarchy:** project specs → codebase exploration → Context7 MCP (`resolve-library-id` then `query-docs`) → web research. Exhaust each level before escalating to the next.
@@ -373,14 +408,14 @@ Run a review-fix loop, maximum 3 iterations, until the reviewer reports a clean
 
 After the review loop completes clean (or the user proceeds), spawn these two sub-agents **in parallel** via the Task tool (`subagent_type: "generalPurpose"`):
 
-1. **`hatch3r-test-writer`** — write regression tests for the fix. The prompt MUST include:
+1. **`hatch3r-testability`** (CQ5) — confirm regression tests for the fix meet the mandate map / coverage floor and represent the failure mode. The prompt MUST include:
    - The bug context from Stage 1c (what was broken).
    - The fix diff (what was changed).
    - The root cause from Stage 4b.
-   - Instruction to write tests that would have caught this bug — regression tests targeting the specific failure mode.
+   - Instruction to verify tests that would have caught this bug — regression tests targeting the specific failure mode.
    - All `scope: always` rule directives from `rules/`.
 
-2. **`hatch3r-security-auditor`** — security review of the fix. The prompt MUST include:
+2. **`hatch3r-security`** (CQ3) — security review of the fix. The prompt MUST include:
    - The fix diff.
    - The affected files and data flows.
    - All `scope: always` rule directives from `rules/`.
@@ -389,10 +424,10 @@ Await both sub-agents. Apply any findings (additional tests, security fixes).
 
 #### 5e. Final Quality Checks
 
-Run the project's quality gates:
+Run the project's quality gates (resolved to the project's language-aware command set at sync time; fallback when detection is unknown: `npm run lint && npm run typecheck && npm run test`):
 
 ```bash
-npm run lint && npm run typecheck && npm run test
+${HATCH3R:VERIFY_GATE_ALL}
 ```
 
 Adapt commands to project conventions (check `package.json`, `Makefile`, `README.md`). Fix any failures before proceeding. Max 2 retry loops on quality check failures. After 2 retries:
@@ -423,16 +458,63 @@ If the user chooses to commit:
 
 ---
 
+## Resumability (Decision 27/30)
+
+debug is long-running across a user-checkpoint boundary — Stage 2 instruments the codebase with strategic `[HATCH3R-DEBUG]` log lines, Stage 3 pauses for the user to reproduce the issue and provide runtime logs, Stage 4 root-cause-analyzes from the collected evidence, and Stage 5 implements the fix and removes all debug artifacts through the implementer → reviewer ↔ fixer review loop and the parallel testability + security final-quality gate. Per hatch3r's workspace-checkpointed resumability contract, checkpoint progress so an interrupted run re-enters at the last completed stage rather than re-instrumenting log statements that already shipped or re-implementing a fix the user has already accepted.
+
+> Orchestration boilerplate: see `commands/shared/orchestration-frame.md` → Checkpoint Contract. Per-command slots: workspace `.debug-workspace/`; step range the Stage 1 → Stage 5 progression; `wave` = review-loop iteration index in Stage 5b; snapshot/rollback paths `instrumentedFiles` (pre-instrumentation) and pre-fix working-tree state. Write points: after Stage 1 context capture, after Stage 2 debug-logging implementer returns (so instrumented files are recorded and a crash leaves the cleanup contract intact), after Stage 3 user-log collection ASK, after Stage 4 root-cause synthesis is confirmed, after each Stage 5b review-loop iteration, after the Stage 5c parallel testability + security gate completes, and after the mandatory Stage 5 debug-artifact cleanup pass (the cleanup-complete signal closes the cleanup guarantee).
+
+---
+
+## Per-Turn Pipeline-State Header (Bypass Protection)
+
+> Orchestration boilerplate: see `commands/shared/orchestration-frame.md` → Per-Turn Pipeline-State Header. Phase mapping for debug: `1` = symptom + scope intake, `2` = debugger sub-agent dispatch + hypothesis enumeration, `3` = root-cause validation, `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: debug notes, reproduction scripts, instrumentation diff.
+
+## 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 researcher dispatch.
+- **Post-execution `cost_actuals` + `delta`** — appended to the Stage 5f fix 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: 6` × tier heuristic in `rules/hatch3r-cost-visibility.md` Pre-Execution Estimate): Tier 1 ≈ 3 (researcher + implementer + one review pass); Tier 2 ≈ 5 (researcher ×2 + implementer + reviewer/fixer); Tier 3 up to 6 (full pipeline including the parallel testability + security final-quality pass). 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
 
 - **Researcher sub-agent failure (Stage 2a or 4a):** Retry the failed sub-agent once. If it fails again, present partial results and ASK the user whether to proceed with manual analysis or abort.
-- **Implementer sub-agent failure (Stage 2b or 5a):** Retry once. If the retry fails, fall back to direct implementation and warn the user that the change may be less thorough.
+- **Implementer sub-agent failure (Stage 2b or 5a):** Per the shared sub-agent-failure clause in `rules/hatch3r-agent-orchestration.md` -> Cross-Phase Error Propagation: retry once, then re-spawn `hatch3r-fixer` with the failure context, then `BLOCKED_OTHER` + ASK. Never fall back to inline implementation (issue #73 bypass mode).
 - **Quality check failure after 2 retries:** Present specific failures and ASK the user whether to commit partial progress, keep trying, or abort.
 - **User provides insufficient logs (Stage 3):** If the log output contains zero `[HATCH3R-DEBUG]` lines, warn the user that the debug logging may not have been reached during reproduction. Suggest verifying that the correct code path was exercised, then ASK for new logs.
-- **No clear root cause (Stage 4):** If all hypotheses are low-confidence, state this clearly. Recommend adding more targeted debug logging (loop back to Stage 2 with refined instrumentation points) or switching to `hatch3r-bug-plan` for a broader investigation. ASK the user how to proceed.
+- **No clear root cause (Stage 4):** If all hypotheses are low-confidence, state this in the diagnosis report (named verdict: "Root cause unconfirmed; top hypothesis confidence=low"). Recommend adding more targeted debug logging (loop back to Stage 2 with refined instrumentation points) or switching to `hatch3r-bug-plan` for a broader investigation. ASK the user how to proceed.
 - **Debug artifacts remain after cleanup (Stage 5b):** If `[HATCH3R-DEBUG]` occurrences are found after the implementer's cleanup pass, remove them directly. Do not proceed until zero occurrences remain.
 - **Review loop exhaustion (Stage 5c):** After 3 iterations without a clean review, present remaining findings and ASK the user for direction.
-- **Context degradation (>20 turns):** Suggest starting a fresh chat with a progress summary capturing the current stage, diagnosis, and remaining work.
+- **Context degradation:** per the canonical Context-Degradation Policy (`rules/hatch3r-agent-orchestration-detail.md` -> Context-Degradation Policy) — compress at `>50%` context window, restart at `>75%`; the coarse turn-count fallback for this command is ~20 turns, at which point suggest a fresh chat with a progress summary capturing the current stage, diagnosis, and remaining work.
 
 ## Guardrails
 
@@ -447,6 +529,12 @@ If the user chooses to commit:
 - **Prefer `gh` CLI for GitHub reads** (e.g., `gh issue view`, `gh pr list`). Fall back to GitHub MCP tools only if `gh` is unavailable.
 - **No board operations.** Never create issues, update project boards, or sync with GitHub Projects. This is a standalone command.
 - **Respect `scope: always` rules** when delegating to sub-agents. Sub-agents do not inherit rules automatically — include them in every prompt.
-- **This command composes existing hatch3r agents** (researcher, implementer, reviewer, fixer, test-writer, security-auditor) — it does not replace them.
+- **This command composes existing hatch3r agents** (researcher, implementer, reviewer, fixer, testability, security) — it does not replace them.
 - **Browser verification is opt-in.** Ask once at command start. Never enable browser steps without user consent.
 - **Never force a diagnosis.** If the logs are inconclusive, say so. Do not fabricate a root cause to proceed.
+
+## 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)