hatch3r 1.8.0 → 2.0.0

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

@@ -3,21 +3,23 @@ id: hatch3r-create
 type: command
 orchestrator: true
 agentPipeline: [hatch3r-creator]
-description: Author a custom user-tier artifact (agent, skill, rule, command, or hook) for this project. Generates frontmatter and body skeleton, applies strict + gentle quality gates, writes to .agents/user/{type}/, and offers to sync to all enabled adapters.
-tags: [core, customize]
+description: Author a custom user-tier artifact (agent, skill, rule, command, or hook) for this project. Generates frontmatter and body skeleton, applies strict + gentle quality gates, writes to .hatch3r/overrides/{type}/, and offers to sync to all enabled adapters.
+tags: [customize]
 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
 
@@ -25,7 +27,7 @@ This command runs as an orchestrator. After collecting inputs in Phase 1, it del
 
 # `/hatch3r-create` — Author a User-Tier Artifact
 
-Use this command when you need a project-specific agent, skill, rule, command, or hook that does not exist in the canonical hatch3r corpus. The command writes one new artifact under `.agents/user/{type}/` per invocation, runs the same frontmatter/security/structural gates the framework uses on canonical content (strict — block on failure), and runs style/lean checks as warnings (gentle — save proceeds, warnings reported).
+Use this command when you need a project-specific agent, skill, rule, command, or hook that does not exist in the canonical hatch3r corpus. The command writes one new artifact under `.hatch3r/overrides/{type}/` per invocation, runs the same frontmatter/security/structural gates the framework uses on canonical content (strict — block on failure), and runs style/lean checks as warnings (gentle — save proceeds, warnings reported).
 
 The 5 supported types: **agent** (sub-agent invokable from orchestrators), **skill** (workflow recipe), **rule** (always or glob-scoped guidance), **command** (slash command, inline or orchestrator), **hook** (event-triggered agent invocation).
 
@@ -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
@@ -75,7 +110,7 @@ Cache the selection as `type`.
 Validate the name against the regex `^[a-z][a-z0-9-]*$`. Reject and re-ask if:
 
 - The name fails the regex (uppercase, underscores, leading digit, etc.).
-- The name starts with `hatch3r-` — this prefix is reserved for canonical framework content. Show: "Names starting with `hatch3r-` are reserved for canonical framework artifacts. Choose a different prefix or omit the prefix entirely. The framework will namespace the file path under `.agents/user/{type}/` automatically."
+- The name starts with `hatch3r-` — this prefix is reserved for canonical framework content. Show: "Names starting with `hatch3r-` are reserved for canonical framework artifacts. Choose a different prefix or omit the prefix entirely. The framework will namespace the file path under `.hatch3r/overrides/{type}/` automatically."
 
 Cache the validated name as `name`.
 
@@ -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`."
@@ -124,10 +165,10 @@ Cache as `adapters` (array, or `null` for full parity).
 Branch on the cached `type`:
 
 - **agent:** Ask for `model` preference (default: `standard`; options: `fast | standard | reasoning`). Ask for an optional tool-allowlist hint (free-text). Cache as `model` and `toolHint`. Then ask for a structured `tools` declaration (see §1.6a below) and cache as `tools`.
-- **skill:** Confirm the subdirectory layout. Show: "Skill files are stored as `.agents/user/skills/{name}/SKILL.md` (a new directory will be created). Continue?" — ASK Y/n.
+- **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 `.agents/user/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`.
+- **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 | 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:
 
@@ -222,23 +265,70 @@ Print the absolute path(s) and the next-step pointer:
 
 ```
 Created:
-  /abs/path/.agents/user/{type}/{name}.md
-  /abs/path/.agents/user/rules/{name}.mdc   (rule only — paired companion)
+  /abs/path/.hatch3r/overrides/{type}/{name}.md
+  /abs/path/.hatch3r/overrides/rules/{name}.mdc   (rule only — paired companion)
 
 Next step:
   Run `hatch3r sync` to propagate this artifact to all enabled adapter outputs
   (.cursor/, .claude/, .github/copilot-instructions.md, etc.).
 
-Edit your artifact directly anytime — `.agents/user/` is preserved across
+Edit your artifact directly anytime — `.hatch3r/overrides/` is preserved across
 `hatch3r update` and `hatch3r clean`.
 ```
 
 ---
 
+## 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 `.agents/user/{type}/` is a strict-gate failure raised by `hatch3r-creator` (status `BLOCKED` with the conflicting path).
-- **Never write to canonical content directories.** All output goes under `.agents/user/`. Writes to `agents/`, `skills/`, `rules/`, `commands/`, or `hooks/` are rejected.
+- **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).
+- **Never write to canonical content directories.** All output goes under `.hatch3r/overrides/`. Writes to `agents/`, `skills/`, `rules/`, `commands/`, or `hooks/` are rejected.
 - **Never bypass strict gates.** Strict failures (frontmatter, ID collision, deny patterns, paired-file parity, orchestrator contract, hook event enum, ≤10KB size, quality_charter reference, pillar declaration, structured `tools` field shape + category membership) block the save.
 - **Structured tool allowlist required (strict shape).** When `tools` is supplied for an `agent` artifact, every entry in `tools.allowed` and `tools.denied` must resolve to a canonical category from `ALL_TOOL_CATEGORIES` in `src/pipeline/agentToolAllowlist.ts` (`read | search | write | execute | web | mcp | git | board`). Overlap between the two lists is rejected. Strict-gate enforced at `saveUserContent` (C9-H81, D20-F20.1.3; depends on C9-H49 Hybrid allowlist).
 - **Pillar coverage required (strict).** Every user artifact must declare at least one of P1–P8 — via `pillars: [...]` in frontmatter (collected at Step 1.4a) or a `**Pillars:** ...` line in the body. The strict gate at `saveUserContent` blocks the save when neither is present (C9-H80, D20-F20.1.2).
@@ -250,3 +340,11 @@ Edit your artifact directly anytime — `.agents/user/` is preserved across
 ## 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/{commands → 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: [core, implementation]
+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,8 +60,8 @@ 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)
-- `scope: always` rules from `.agents/rules/`
+- 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
@@ -127,8 +162,8 @@ You can also paste an error log, stack trace, or screenshot description and I'll
 1. Check for existing documentation:
    - `docs/specs/` — project specifications (read TOC/headers first, expand relevant sections only)
    - `README.md` — project overview and setup instructions
-   - `AGENTS.md` or `.agents/rules/` — agent rules and project conventions
-2. If `.agents/learnings/` exists, scan for learnings relevant to the affected area. Match by area and tags against the bug description.
+   - `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. 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.
@@ -166,7 +201,7 @@ The researcher prompt MUST include:
 - The affected files and modules identified in Stage 1b.
 - Instruction to follow the **hatch3r-researcher agent protocol** with mode `symptom-trace`.
 - Instruction to identify specific instrumentation points: decision branches, data flow boundaries, error handlers, state transitions, and external call sites in the affected area.
-- All `scope: always` rule directives from `.agents/rules/`.
+- All `scope: always` rule directives from `rules/`.
 
 The researcher must produce a structured list of recommended instrumentation points:
 
@@ -186,7 +221,7 @@ Spawn a `hatch3r-implementer` sub-agent via the Task tool (`subagent_type: "gene
 The implementer prompt MUST include:
 - The researcher's instrumentation points from Stage 2a.
 - The confirmed bug context from Stage 1c.
-- All `scope: always` rule directives from `.agents/rules/`.
+- All `scope: always` rule directives from `rules/`.
 - Explicit instruction: do NOT create branches, commits, or PRs.
 
 **Debug logging rules** (include these verbatim in the implementer prompt):
@@ -281,7 +316,7 @@ The researcher prompt MUST include:
 - The structured log analysis from Stage 3b (full parsed output).
 - The instrumentation point list from Stage 2a (to correlate expected vs. actual behavior).
 - Instruction to follow the **hatch3r-researcher agent protocol** with mode `root-cause` and depth `deep`.
-- All `scope: always` rule directives from `.agents/rules/`.
+- All `scope: always` rule directives from `rules/`.
 - Instruction to produce ranked hypotheses with evidence from the log data.
 
 **Knowledge hierarchy for the researcher:** project specs → codebase → Context7 MCP → web research. Use `gh` CLI (e.g., `gh issue list`, `gh pr list`) for reading GitHub data; prefer `gh` over GitHub MCP tools.
@@ -324,7 +359,7 @@ Spawn a `hatch3r-implementer` sub-agent via the Task tool (`subagent_type: "gene
 The implementer prompt MUST include:
 - The confirmed diagnosis from Stage 4b (root cause, evidence, recommended fix approach).
 - The full list of files modified in Stage 2b (debug logging locations) for cleanup reference.
-- All `scope: always` rule directives from `.agents/rules/`.
+- All `scope: always` rule directives from `rules/`.
 - Explicit instruction: do NOT create branches, commits, or PRs.
 
 **Fix implementation rules** (include these verbatim in the implementer prompt):
@@ -355,7 +390,7 @@ Run a review-fix loop, maximum 3 iterations, until the reviewer reports a clean
    - The diff of all changes (use `git diff` on the working tree).
    - The original bug context from Stage 1c.
    - The diagnosis from Stage 4b.
-   - All `scope: always` rule directives from `.agents/rules/`.
+   - All `scope: always` rule directives from `rules/`.
    - Instruction to verify: correctness of the fix, no remaining debug artifacts, code quality, no regressions introduced.
 
 2. If the reviewer reports findings (critical or warning level):
@@ -373,26 +408,26 @@ 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.
-   - All `scope: always` rule directives from `.agents/rules/`.
+   - 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 `.agents/rules/`.
+   - All `scope: always` rule directives from `rules/`.
 
 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)