hatch3r 1.8.0 → 2.0.0

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

@@ -2,17 +2,18 @@
 id: hatch3r-quick-change
 type: command
 orchestrator: true
-agentPipeline: [hatch3r-implementer, hatch3r-lint-fixer, hatch3r-reviewer, hatch3r-fixer, hatch3r-test-writer, hatch3r-security-auditor]
-description: Lightweight command for small changes not worth tracking on the board. Adaptive ceremony with inline or sub-agent implementation, batch support, and soft scope guards.
-tags: [core, implementation]
+agentPipeline: [hatch3r-implementer, hatch3r-lint-fixer, hatch3r-reviewer, hatch3r-fixer, hatch3r-ui, hatch3r-ux, hatch3r-security, hatch3r-reliability, hatch3r-testability, hatch3r-scalability, hatch3r-performance, hatch3r-maintainability, hatch3r-enhancability]
+description: "Lightweight workflow for small changes not tracked on the board: adaptive ceremony, inline or sub-agent implementation, batch support."
+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]
 sub_agents_spawned:
-  count: 6
-  rationale: Six-stage pipeline per agentPipeline — implementer (one per independent area in batch mode), lint-fixer, reviewer ↔ fixer review loop, then parallel test-writer + security-auditor; final-quality runs in parallel where independent.
+  count: 13
+  rationale: Four-stage core pipeline (implementer + lint-fixer + reviewer ↔ fixer) plus 9 CQ vector specialists (ui/ux/security/reliability/testability/scalability/performance/maintainability/enhancability) dispatched conditionally per their trigger conditions; the always-on testing + security gates collapse onto `hatch3r-testability` (CQ5) and `hatch3r-security` (CQ3) respectively. Tier 1 trivial edits skip CQ specialists per Phase Skip Criteria. Cost-dominance per CONSTITUTION §2 P8 — token cost never serializes independent work.
 ---
 
 ## §0 Detect Ambiguity (P8 B1)
@@ -27,7 +28,9 @@ Before any action, scan the user's change description for unresolved questions i
 | 2. Implementation | `hatch3r-implementer` (nontrivial items) | Per item | Nontrivial only |
 | 3. Lint Fix | `hatch3r-lint-fixer` | No | When lint/type errors |
 | 4a. Review Loop | `hatch3r-reviewer` -> `hatch3r-fixer` (max 3 iterations) | No (sequential) | Nontrivial only |
-| 4b. Final Quality | `hatch3r-test-writer` + `hatch3r-security-auditor` | Yes | Nontrivial code changes |
+| 4b. Final Quality | `hatch3r-testability` + `hatch3r-security` | Yes | Nontrivial code changes |
+
+**Parallel-safety conditions** (per `rules/hatch3r-agent-orchestration.md` §Parallel Safety): every parallel fan-out above holds all three — read-only or disjoint writes, deterministic aggregation, no shared mutable state.
 
 ## Browser Automation
 
@@ -53,14 +56,14 @@ This command intentionally skips:
 - Board context (`hatch3r-board-shared`)
 - GitHub issues and PRs
 - Researcher sub-agent
-- Full review pipeline (security-auditor, test-writer, docs-writer)
+- Full review pipeline (deep security audit, full test authoring, docs-writer)
 - Learnings capture (consultation of existing learnings retained — see Step 2c)
 
 It retains:
 - Quality checks (lint, typecheck, test) -- always mandatory
 - Adaptive sub-agent delegation (implementer for nontrivial items)
 - Light code review (reviewer for nontrivial items only)
-- `scope: always` rules from `.agents/rules/`
+- `scope: always` rules from `rules/`
 - Soft scope guards to prevent misuse
 - Lightweight learnings consultation (file-path scan, 150-token budget)
 
@@ -98,6 +101,39 @@ Classify the change request before delegating. Detailed tier scoring runs in Ste
 
 If Tier 1, run inline. If Tier 2, run the implementer-only pipeline below. If Tier 3, exit and recommend `hatch3r-workflow`.
 
+### Pre-Execution Cost Preview
+
+Before any sub-agent dispatch (Step 4b implementer), surface the cost preview so a nontrivial change is never started blind. Emit the `cost_estimate` block per `rules/hatch3r-cost-visibility.md` Pre-Execution Estimate, calibrated to the Triage tier. Tier 1 trivial inline edits skip the sub-agent path entirely, so `expected_sa_count: 0` is the correct value for them.
+
+```yaml
+cost_estimate:
+  expected_sa_count: <Tier 1 inline ~0, Tier 2 ~3 (researcher + implementer + reviewer), up to 13 when CQ specialists trigger>
+  estimated_input_tokens_static_frame: <int>
+  estimated_web_research_queries: <int>
+  triage_tier: light | standard | deep
+  estimated_duration_min: <int>
+```
+
+Post-execution actuals + delta land in the Step 8 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 multi-file change scored as Tier 1, or a one-line edit scored as Tier 2. The user override is the recovery path mandated by hatch3r's universal `--effort` override contract ("User overridable via `--effort` flag"):
+
+- `--effort=light|standard` forces the named tier, bypassing the Triage auto-classification. `--effort=deep` is rejected here — quick-change hard-blocks Tier 3 and routes to `hatch3r-workflow`.
+- 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.
+
+### Confidence Floor (Decision 16 / D13-SA13.3-F13.3.3)
+
+`--effort` calibrates work-effort depth; `--confidence-floor` calibrates the confidence threshold at which the Step 6a review gate blocks. They are orthogonal. This is the user's pre-flight assertiveness knob (the forced-second-pass on low confidence in Step 6a is post-hoc; the floor sets the bar before the run):
+
+- `--confidence-floor=any|medium|high` (default `any`). Resolution order: explicit flag wins over the persisted `hatch3r config confidence_floor=...` default, which wins over the built-in `any`.
+- **`any`** (current behavior): Step 6a forces a second reviewer pass only when reviewer confidence `== low` with 0 Critical + 0 Warning.
+- **`medium`**: force a second pass on ANY finding rated `confidence == low`, even with 0 Critical + 0 Warning.
+- **`high`**: force a second pass on any finding rated `confidence != high`, AND ASK the user on every low-confidence finding regardless of severity.
+- Per P1 maturity tier (Decision 16): solo defaults `any`, enterprise defaults `high`. Tier 1 trivial inline edits skip the review loop entirely, so the floor applies only to nontrivial items that reach Step 6a. The floor never relaxes a quality gate.
+
 ---
 
 ## Workflow
@@ -137,9 +173,9 @@ Aggregate across the batch for total estimated scope.
 
 **Hard block — Tier 3 (Deep):** If any item scores Tier 3, quick-change is not appropriate.
 
-**ASK:** "This change scores Tier 3 (Deep complexity): {reason}. Quick-change does not provide the research depth needed. Options: (a) switch to `/h4tcher-workflow`, (b) narrow the scope."
+**ASK:** "This change scores Tier 3 (Deep complexity): {reason}. Quick-change does not provide the research depth needed. Options: (a) switch to `/hatch3r-workflow`, (b) narrow the scope."
 
-Do NOT offer a "proceed anyway" option for Tier 3. The user must switch to `/h4tcher-workflow` or narrow scope.
+Do NOT offer a "proceed anyway" option for Tier 3. The user must switch to `/hatch3r-workflow` or narrow scope.
 
 **Soft guard — Tier 2 (Standard) or threshold triggers:** If any item scores Tier 2, or if any of these threshold triggers fire (any one is sufficient):
 - Estimated total exceeds **5 files**
@@ -163,7 +199,7 @@ Quick Change Scope:
 
 #### 2c. Lightweight Learnings Scan (Optional)
 
-If `.agents/learnings/` exists:
+If `.hatch3r/learnings/` exists:
 
 1. Collect the file paths from the affected areas identified in Step 1.
 2. Scan learning file frontmatter for `area` or `tags` that match the affected file paths or directories.
@@ -179,7 +215,7 @@ If `.agents/learnings/` exists:
 
 **Token budget:** Max 150 tokens for this entire step. Read frontmatter only — do not read learning bodies unless the frontmatter matches. Limit to 3 surfaced learnings. If more than 3 match, show the 3 with highest confidence.
 
-If `.agents/learnings/` does not exist, skip this step silently.
+If `.hatch3r/learnings/` does not exist, skip this step silently.
 
 **ASK:** "Proceed with these changes? (yes / adjust)"
 
@@ -231,7 +267,7 @@ No sub-agent delegation. No researcher. Implement and move on.
 
 For each nontrivial item (or group of related nontrivial items):
 
-1. Read `scope: always` rules from `.agents/rules/`.
+1. Read `scope: always` rules from `rules/`.
 
 2. **Lightweight research (Tier 2 items only):** If the item scored Tier 2 in Step 2b and the user chose to proceed with lightweight research, spawn a `hatch3r-researcher` sub-agent with:
    - **Modes:** `similar-implementation` at `quick` depth (1 reference implementation)
@@ -246,6 +282,7 @@ The implementer prompt MUST include:
 - Explicit instruction: do NOT create branches, commits, or PRs.
 - **Reference conventions** from `similar-implementation` output (if step 2 ran) — triggers the implementer's Convention Lock step.
 - If no researcher ran: explicit instruction that no researcher context is available; work from the change description and codebase alone.
+- `correlation_id` (UUID v4 per top-level task per `rules/hatch3r-agent-orchestration.md` → Correlation ID; batch items share one id with a sub-task index).
 - 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.
 
 If multiple nontrivial items affect **independent areas** (no shared files), spawn one implementer per area and run them in parallel.
@@ -291,13 +328,14 @@ For nontrivial items, run an iterative review loop (max 3 iterations) until 0 Cr
 The reviewer prompt MUST include:
 - The diff of all changes made (use `git diff` on the working tree).
 - Focus areas: **correctness and code quality only**. Skip security deep-dive, performance profiling, and documentation review.
-- All `scope: always` rule directives from `.agents/rules/`.
+- All `scope: always` rule directives from `rules/`.
 - Iteration number and previous findings (if not the first iteration).
+- `correlation_id` (UUID v4 per top-level task per `rules/hatch3r-agent-orchestration.md` → Correlation ID).
 - 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.
 - Requirement that the reviewer output include a top-level `confidence: high | medium | low` field (not just per-finding) so the gate in step 2 can evaluate it deterministically.
 
-2. Process reviewer output (confidence-aware gate):
-   - If **0 Critical + 0 Warning AND reviewer confidence != low**: review loop is clean. Proceed to Step 6b.
+2. Process reviewer output (confidence-aware gate — the second-pass trigger tightens with the `--confidence-floor` set in the Effort Override section above; `any` = default below, `medium`/`high` raise the bar):
+   - If **0 Critical + 0 Warning AND reviewer confidence != low**: review loop is clean. Proceed to Step 6b. (Floor `medium`: also force a second pass if any individual finding is `confidence == low`. Floor `high`: force a second pass if reviewer confidence `!= high` OR any finding is `!= high`, AND ASK on every low-confidence finding.)
    - If **0 Critical + 0 Warning AND reviewer confidence == low**: trigger a second reviewer pass before exiting. Do not proceed to 6b until the second pass returns non-low confidence OR the user explicitly accepts the low-confidence PASS.
    - If Critical or Warning findings remain: spawn `hatch3r-fixer` sub-agent to address them, then re-run the reviewer (next iteration).
      The fixer prompt MUST include: the reviewer findings, all `scope: always` rule directives, and the confidence expression requirement (high/medium/low per the quality charter).
@@ -312,16 +350,25 @@ The reviewer prompt MUST include:
 
 After the review loop is clean, spawn both agents in parallel via the Task tool:
 
-1. `hatch3r-test-writer` — write or update tests for nontrivial code changes.
-2. `hatch3r-security-auditor` — lightweight security review of nontrivial code changes.
+1. `hatch3r-testability` (CQ5) — confirm tests for nontrivial code changes meet the mandate map / coverage floor.
+2. `hatch3r-security` (CQ3) — lightweight security review of nontrivial code changes (OAuth/OIDC, secrets, supply-chain).
 
 Both prompts MUST include:
 - The diff of all changes made.
-- All `scope: always` rule directives from `.agents/rules/`.
+- All `scope: always` rule directives from `rules/`.
+- `correlation_id` (UUID v4 per top-level task per `rules/hatch3r-agent-orchestration.md` → Correlation ID).
 - Confidence expression requirement: rate every recommendation and finding as high/medium/low confidence per the quality charter (`agents/shared/quality-charter.md`). High = verified against current code. Medium = pattern-based, not fully verified. Low = best judgment, recommend human review.
 
 Apply any resulting changes (new tests, security fixes). Re-run quality checks (Step 5a) if changes were made.
 
+#### 6c. Post-Write Duplication Scan (Decision 21)
+
+When the batch ran **2+ parallel implementers** (independent areas, per Step 4b), run a duplication scan before finishing — parallel implementers can each emit near-duplicate helpers that pass their own path independently (D13-SA13.2-F7). Skip when only one implementer ran or all items were trivial (no cross-file clone possible).
+
+1. Run `npx jscpd --min-lines 40 --threshold 80 --reporters json --silent <changed-paths>`. The gate fires on any cross-file clone block **≥40 lines OR ≥80% byte-similar**.
+2. **If detected:** route the report to `hatch3r-fixer` for a DRY refactor, then re-run quality checks (Step 5a). Max 1 iteration; if it persists, surface the clone locations to the user.
+3. **If not detected:** proceed to Step 7.
+
 ---
 
 ### Step 7: Git Action
@@ -379,6 +426,53 @@ Quick Change Complete:
 
 ---
 
+## Resumability (Decision 27/30)
+
+quick-change runs adaptive ceremony — trivial items execute inline with no checkpoint surface, but a Tier 2/3 batch of multiple nontrivial items can grow to span per-item implementer delegation (Step 4), lint-fix (Step 5), the reviewer ↔ fixer review loop (Step 6), parallel CQ specialist Phase 4 batch (Step 6 final-quality), and the commit phase (Step 7). Per hatch3r's workspace-checkpointed resumability contract, checkpoint progress on nontrivial batches so an interrupted run re-enters at the last completed step rather than re-implementing items that already wrote code.
+
+> Orchestration boilerplate: see `commands/shared/orchestration-frame.md` → Checkpoint Contract. Per-command slots: workspace `.quick-change-workspace/`; step range the Step 1 → Step 8 progression; `wave` = per-item implementer-batch index when batch mode is active; snapshot/rollback paths per-item working-tree state. Write points: Tier 1 trivial inline items skip checkpoint emission (the resume cost would exceed the re-run cost). For nontrivial items: after Step 1 input + batch parsing, after Step 2 tier assessment + soft-guard pass, after Step 3 per-item classification, after each Step 4 implementer batch returns per item (so completed implementations survive a crash and are not re-implemented on resume), after Step 5 lint-fix, after each Step 6 review-loop iteration, after the Step 6 final-quality batch, and after Step 7 git commit.
+
+---
+
+## Per-Turn Pipeline-State Header (Bypass Protection)
+
+> Orchestration boilerplate: see `commands/shared/orchestration-frame.md` → Per-Turn Pipeline-State Header. Phase mapping for quick-change: `1` = scope intake + complexity scoring, `2` = inline edit OR implementer dispatch (Tier 1 carve-out per `rules/hatch3r-agent-orchestration.md` Mandatory Delegation Directive applies only at Tier 1), `3` = lint + typecheck + test verification, `4` = Step 8 summary + 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: target edit, test additions. quick-change is the one command with a Tier-1 inline-edit carve-out (per `rules/hatch3r-agent-orchestration.md` Mandatory Delegation Directive): a Tier-1 inline edit by the orchestrator sets `inline_edits_by_orchestrator: <carve-out: Tier-1 inline edit per quick-change scope>` instead of `none`.
+
+## Iteration Summary (mandatory output)
+
+Emit the canonical 9-section iteration summary per `rules/hatch3r-iteration-summary.md` as the final user-facing output (the Step 8 Summary above is the quick-change-specific rendering — both the Step 8 block and the 9-section canonical contract apply). 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 sub-agent dispatch.
+- **Post-execution `cost_actuals` + `delta`** — appended to the Step 8 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: 13` × tier heuristic in `rules/hatch3r-cost-visibility.md` Pre-Execution Estimate): Tier 1 trivial inline ≈ 0 (no sub-agent); Tier 2 ≈ 3 (researcher + implementer + reviewer, plus lint-fixer/fixer/testability/security when triggered); up to 13 when the conditional CQ vector specialists fire per their trigger conditions. 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
 
 - **Quality check failure after 2 retries**: Present the specific failures and ASK the user whether to commit partial progress, keep trying, or abort.
@@ -386,7 +480,7 @@ Quick Change Complete:
 - **Reviewer flags critical issues**: Present them and ASK whether to fix or proceed without fixing.
 - **Scope creep during implementation**: If actual changes exceed the soft guard thresholds (5 files / 200 lines), warn the user and suggest deferring remaining items to a `hatch3r-workflow` session.
 - **Push failure**: Present the error. Use `git push -u origin {branch}` for new branches. For diverged branches, suggest `git pull --rebase` and ASK before proceeding.
-- **Context degradation (>15 turns)**: Quick changes should complete fast. If the session exceeds 15 turns, suggest starting fresh or switching to `hatch3r-workflow`.
+- **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 fast-completion command is ~15 turns, at which point suggest starting fresh or switching to `hatch3r-workflow`.
 
 ## Guardrails
 
@@ -398,4 +492,5 @@ Quick Change Complete:
 - **No board operations.** Never create issues, update project boards, or sync with GitHub Projects.
 - **No PR creation.** Quick changes commit directly; PRs are the user's responsibility if needed.
 - **Respect `scope: always` rules** when delegating to sub-agents. Sub-agents do not inherit rules automatically.
+- **Concurrent invocation:** for Tier 2/3 batches, acquire `.hatch3r/.lock` and detect-then-warn on a conflicting active pipeline (same branch / open `.hatch3r/hatch.json` transaction) per `rules/hatch3r-agent-orchestration.md` → Parallel Safety → Concurrent Invocation Handling. Tier 1 inline edits with no checkpoint surface are exempt.
 - **This command composes existing hatch3r agents** (implementer, reviewer, lint-fixer) -- it does not replace them.

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

@@ -9,15 +9,17 @@ quality_charter: agents/shared/quality-charter.md
 efficiency_patterns: agents/shared/efficiency-patterns.md
 cache_friendly: true
 parallel_tool_default: true
+efficiency_tier: deep
 triage_tiers: [1, 2, 3]
+supports_resume: true
 sub_agents_spawned:
   count: 4
-  rationale: Four parallel hatch3r-researcher modes per refactoring brief — current-state, refactoring-strategy, impact-and-risk, migration-path — dispatched concurrently in Step 3; a docs-writer composes the refactoring spec on their merged output.
+  rationale: Four parallel hatch3r-researcher modes per refactoring brief — current-state, refactoring-strategy, impact-and-risk, migration-path — dispatched concurrently in Step 3; a docs-writer composes the refactoring spec on their merged output. Cost-dominance per CONSTITUTION §2 P8 — token cost never serializes independent work.
 ---
 
 ## §0 Detect Ambiguity (P8 B1)
 
-Before any action, scan the user's request and provided context for unresolved questions in scope, acceptance criteria, irreversibility, or constraint conflicts (contradictory inputs, missing target, unknown convention). If any are found, ask the user via the platform-native question tool per `agents/shared/user-question-protocol.md` — do not proceed under silent assumption. This is the default path, not an exception. Acceptable to proceed without asking ONLY when scope is single-target, single-concern, and the brief alone is testable. Any residual ambiguity discovered mid-workflow invokes the same protocol.
+> Orchestration boilerplate: see `commands/shared/orchestration-frame.md` → §0 Detect Ambiguity (P8 B1). Triggers: contradictory inputs, missing target, unknown convention.
 
 ## Agent Pipeline
 
@@ -27,6 +29,8 @@ Before any action, scan the user's request and provided context for unresolved q
 | 2. Document Generation | `hatch3r-docs-writer` (refactoring spec, ADRs) | Yes | Yes |
 | 3. Todo Generation | Orchestrator (inline) | No | Yes |
 
+**Parallel-safety conditions** (per `rules/hatch3r-agent-orchestration.md` §Parallel Safety): every parallel fan-out above holds all three — read-only or disjoint writes, deterministic aggregation, no shared mutable state.
+
 # Refactor Plan — Refactoring & Migration Specification from Problem to Phased Execution
 
 Take a refactoring goal or migration need and produce a complete refactoring specification (`docs/specs/`), architectural decision records (`docs/adr/`) when the approach involves significant design choices, and structured `todo.md` entries (phased work items) ready for `hatch3r-board-fill`. Spawns parallel researcher sub-agents (current state analysis, refactoring strategy, impact & risk assessment, migration path planning) to design the refactoring from multiple angles before generating artifacts. AI proposes all outputs; user confirms before any files are written. Optionally chains into `hatch3r-board-fill` to create GitHub issues immediately.
@@ -44,7 +48,7 @@ The command produces phased todo.md entries that map to the appropriate executio
 
 ## Shared Context
 
-**Read the `hatch3r-board-shared` command at the start of the run** if it exists. While this command does not perform board operations directly, it establishes patterns and context (GitHub owner/repo, tooling directives) that downstream commands like `hatch3r-board-fill` rely on. Cache any values found.
+**Read the `hatch3r-board-shared` skill at the start of the run** if it exists. While this command does not perform board operations directly, it establishes patterns and context (GitHub owner/repo, tooling directives) that downstream commands like `hatch3r-board-fill` rely on. Cache any values found.
 
 ## Token-Saving Directives
 
@@ -54,6 +58,12 @@ The command produces phased todo.md entries that map to the appropriate executio
 
 ---
 
+## Confidence Propagation Contract
+
+> Orchestration boilerplate: see `commands/shared/orchestration-frame.md` → Confidence Propagation Contract. Readiness kind: plan.
+
+---
+
 ## Workflow
 
 Execute these steps in order. **Do not skip any step.** Ask the user at every checkpoint marked with ASK.
@@ -68,6 +78,25 @@ Classify the refactor-planning request before delegating:
 
 If Tier 1, run the reduced researcher set and skip ADR generation unless decisions are obvious. If Tier 2, run the standard pipeline below. If Tier 3, run the full pipeline including ADR generation and confirm phasing with the user before writing files.
 
+### Step 0.5: Emit Pre-Execution Cost Preview
+
+Before the first researcher dispatch (Step 3), surface the cost preview so a multi-researcher refactor-planning run 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 ~4, Tier 3 up to 4>
+  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 localized refactor scored as Deep, or a cross-cutting refactor scored as Light.
+
 ---
 
 ### Step 1: Gather Refactoring Goal
@@ -114,10 +143,10 @@ Refactoring Brief:
    - `docs/specs/` — project specifications (read TOC/headers first, expand relevant sections only)
    - `docs/adr/` — architectural decision records (scan for decisions relevant to the target area)
    - `README.md` — project overview
-   - `.agents/hatch.json` — board configuration
+   - `.hatch3r/hatch.json` — board configuration
    - Existing `todo.md` — current backlog (check for overlap or related items)
 2. Scan GitHub issues via `search_issues` for existing work related to the refactoring area. Note in-progress work, dependencies, or prior refactoring attempts.
-3. If `.agents/learnings/` exists, scan for learnings relevant to the target area. Match by area and tags against the refactoring brief.
+3. If `.hatch3r/learnings/` exists, scan for learnings relevant to the target area. Match by area and tags against the refactoring brief.
 4. Scan test coverage in the target area — identify which parts have strong test coverage (safe to refactor) vs. weak coverage (need tests first).
 5. Present a context summary:
 
@@ -440,12 +469,59 @@ If yes, instruct the user to invoke the `hatch3r-board-fill` command. Note that
 
 ---
 
+## Resumability (Decision 27/30)
+
+refactor-plan is long-running — a Tier 3 refactor brief fans out 5 parallel researcher sub-agents (Step 3), drives an ASK checkpoint synthesis (Step 4), and writes a multi-file spec + ADRs + todo.md (Steps 5–8). Per hatch3r's workspace-checkpointed resumability contract, checkpoint progress so an interrupted run re-enters at the last completed step rather than re-running the researcher batch.
+
+> Orchestration boilerplate: see `commands/shared/orchestration-frame.md` → Checkpoint Contract. Per-command slots: workspace `.refactor-plan-workspace/`; step range the Step 0 → Step 8 progression; `wave` = researcher-batch index; snapshot/rollback paths `docs/specs/`, `docs/adr/`, and `todo.md`; `meta` adds `refactorSlug`. Write points: after Step 1 brief confirmation, after Step 3 researcher fan-out completes, after the Step 4 ASK synthesis is confirmed, and after each Step 5–8 file write so already-generated spec/ADR/todo entries survive a crash and are not regenerated on resume.
+
+---
+
+## Per-Turn Pipeline-State Header (Bypass Protection)
+
+> Orchestration boilerplate: see `commands/shared/orchestration-frame.md` → Per-Turn Pipeline-State Header. Phase mapping for refactor-plan: `1` = scope + blast-radius intake, `2` = researcher sub-agent dispatch (consumer map, contract inventory), `3` = plan synthesis + sequencing, `4` = plan write + iteration-summary. Tier 1 runs are exempt per the Tier 1 exemption.
+
+## End-of-Turn Delegation Attestation (Bypass Protection)
+
+> Orchestration boilerplate: see `commands/shared/orchestration-frame.md` → End-of-Turn Delegation Attestation. Per-command mutated-file slot: plan document, sequencing spec, regression-test scaffolding.
+
+## Iteration Summary (mandatory output)
+
+Emit the canonical 9-section iteration summary per `rules/hatch3r-iteration-summary.md` as the final user-facing output. The validation gate at `.claude/rules/capability-lifecycle.md` blocks SUCCESS declarations without this block (CONSTITUTION §6 Decision 23).
+
+The 9 sections:
+
+1. **Request** — verbatim restatement of the user's ask in one sentence.
+2. **Fan-out + Cost** — `sub_agents_spawned: { count, rationale }` plus the `cost_estimate` / `cost_actuals` / `delta` blocks (see Cost Visibility below).
+3. **Web Research** — every URL fetched with access date + trust tier per `agents/shared/rigor-contract.md` (0 acceptable when no research was needed).
+4. **Files Mutated** — list with diff summary (lines added / removed / files created).
+5. **Gates Passed / Failed** — explicit list per `.claude/rules/capability-lifecycle.md` Gate Checklist.
+6. **Pillar Impact Attribution** — `progress_toward_pillar: <axis>.<pillar_id>+<delta>` per CONSTITUTION §6 Decision 17.
+7. **Verification Commands** — exact commands run with exit codes plus key output lines (≤200 chars).
+8. **Open Questions / Blockers** — explicit `None` if fully closed.
+9. **Learnings Captured** — IDs of any learnings written to `.hatch3r/learnings/` this run per `rules/hatch3r-learning-system.md`.
+
+### Cost Visibility (Decision 24)
+
+> Orchestration boilerplate: see `commands/shared/orchestration-frame.md` → Cost Estimate for the 5-field `cost_estimate` schema and the post-execution `cost_actuals` + `delta` contract; both land in Section 2 above.
+
+## Cost estimate (Decision 24)
+
+This command emits cost transparency per `rules/hatch3r-cost-visibility.md` and CONSTITUTION §6 Decision 24/29:
+
+- **Pre-execution `cost_estimate`** — emitted in Step 0.5 before the first researcher dispatch.
+- **Post-execution `cost_actuals` + `delta`** — appended to the iteration summary's Fan-out + Cost section per `rules/hatch3r-iteration-summary.md` §2.
+
+Per-tier `expected_sa_count` calibration (from frontmatter `sub_agents_spawned.count: 4` × tier heuristic in `rules/hatch3r-cost-visibility.md` Pre-Execution Estimate): Tier 1 ≈ 2 (reduced researcher set); Tier 2/3 spawn up to 4 parallel researcher modes (current-state + refactoring-strategy + migration-path + risk). Deltas beyond 25% absolute value carry `flagged_for_review: true`. Token telemetry sources from `src/pipeline/observability.ts`; estimation primitives from `src/pipeline/costEstimator.ts`.
+
+---
+
 ## Error Handling
 
 - **Sub-agent failure:** Retry the failed sub-agent once. If it fails again, present partial results from the remaining sub-agents and ask the user how to proceed (continue without that researcher's input / provide the missing information manually / abort).
 - **Conflicting researcher outputs:** Present both options side by side with trade-offs. Ask the user to decide. Do not silently pick one.
 - **File write failure:** Report the error and provide the full file content so the user can create the file manually.
-- **Missing project context:** If no `hatch3r-board-shared` or `.agents/hatch.json` exists, proceed without board context — this command does not require board configuration.
+- **Missing project context:** If no `hatch3r-board-shared` or `.hatch3r/hatch.json` exists, proceed without board context — this command does not require board configuration.
 - **No existing specs or docs:** Proceed without spec references. Warn that the refactoring spec will be less contextualized without existing project documentation. Recommend running `hatch3r-project-spec` or `hatch3r-codebase-map` first for best results.
 - **Duplicate detection:** If the refactoring overlaps significantly with existing todo.md items or GitHub issues found in Step 2, present the overlap and ASK whether to proceed (augment existing / replace / abort).
 - **Weak test coverage:** If the current state analyzer finds weak test coverage in the target area, the migration path planner MUST include a Phase 0 for test scaffolding. Do not proceed with refactoring phases without adequate coverage.