hatch3r 1.9.0 → 2.0.0

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

@@ -0,0 +1,238 @@
+---
+id: hatch3r-diagnose
+type: command
+orchestrator: true
+agentPipeline: [hatch3r-researcher, hatch3r-fixer]
+description: "Troubleshoot a hatch3r framework issue (setup, config, adapter wiring, drift). Gathers state, delegates root-cause analysis to hatch3r-researcher, proposes a fix, and applies it via hatch3r-fixer after one confirmation gate."
+argument-hint: "[symptom]"
+tags: [maintenance, devops, ctx:brownfield-only]
+quality_charter: agents/shared/quality-charter.md
+efficiency_patterns: agents/shared/efficiency-patterns.md
+cache_friendly: true
+parallel_tool_default: true
+efficiency_tier: standard
+triage_tiers: [1, 2, 3]
+sub_agents_spawned:
+  count: 2
+  rationale: One hatch3r-researcher (root-cause mode against the captured state bundle) plus one hatch3r-fixer (applies the single proposed remediation). Independent symptom domains fan out to N parallel researchers; serialization holds only on the diagnose -> fix dependency edge. Cost-dominance per CONSTITUTION §2 P8 — token cost never serializes the diagnosis from the fix when both are needed.
+---
+
+## §0 Detect Ambiguity (P8 B1)
+
+Before any action, scan the user's request for unresolved questions in symptom scope, target adapter, or expected-vs-actual behavior. If the symptom maps to two or more distinct failure domains (e.g., "sync is broken" could mean adapter output drift OR a manifest schema mismatch OR a path-traversal guard rejection), ask the user via the platform-native question tool per `agents/shared/user-question-protocol.md` — do not guess which subsystem to probe. Proceed without asking ONLY when the symptom names a single subsystem and a single expected behavior. Any residual ambiguity discovered mid-diagnosis re-invokes the same protocol. Source: `.claude/rules/clarification-default.md`.
+
+## Agent Pipeline
+
+| Stage | Agent(s) | Parallel | Required |
+|-------|----------|----------|----------|
+| 1. Capture state bundle | Orchestrator (inline, read-only) | No | Yes |
+| 2. Triage symptom domain | Orchestrator (inline) | No | Yes |
+| 3. Root-cause analysis | `hatch3r-researcher` (`root-cause` + `symptom-trace` modes) | Per independent symptom domain | Yes |
+| 4. Propose remediation + ASK gate | Orchestrator (inline) | No | Yes |
+| 5. Apply fix | `hatch3r-fixer` | Per fix group | When user accepts a code/config fix |
+| 6. Verify + Iteration Summary | Orchestrator (inline) | No | Yes |
+
+**Parallel-safety conditions** (per `rules/hatch3r-agent-orchestration.md` §Parallel Safety): when the captured state surfaces two or more independent symptom domains (e.g., one adapter's output drift AND an unrelated manifest field), fan out one `hatch3r-researcher` per domain — each reads a disjoint file set, aggregation is deterministic (union of root-cause records), and no shared mutable state exists. A single symptom domain spawns one researcher.
+
+---
+
+# Diagnose -- Troubleshoot a hatch3r Framework Issue
+
+Closes the **symptom -> root cause -> fix** loop on a hatch3r setup, configuration, adapter-wiring, or drift problem in a repo where hatch3r is installed. Captures a read-only state bundle, delegates root-cause analysis to `hatch3r-researcher`, presents one remediation with an ASK gate, then delegates the fix to `hatch3r-fixer` and verifies.
+
+Use `hatch3r-diagnose` when a hatch3r command misbehaves, adapter output looks wrong, `hatch3r status`/`hatch3r verify` reports drift, or the install is in an unexpected state. Use `/hatch3r-healthcheck` for a routine read-only health report with no fix step; use `/hatch3r-debug` for application-code debugging unrelated to the hatch3r framework itself.
+
+---
+
+## Argument Parsing
+
+Optional positional argument: `<symptom>` (free-text description of the problem).
+
+- If supplied: seed the Step 2 triage with the described symptom.
+- If omitted: capture the full state bundle (Step 1) and ASK the user which symptom to investigate before delegating — a blind full-surface diagnosis is over-fan-out per `rules/hatch3r-fan-out-discipline.md`.
+
+---
+
+## Step 1: Capture State Bundle (read-only)
+
+Gather the diagnostic state once; cache and pass it into the Step 3 researcher prompt so the sub-agent does not re-read. All commands are read-only.
+
+| Probe | Command | Captures |
+|-------|---------|----------|
+| Version | `npx hatch3r --version` | installed CLI version |
+| Manifest | read `.hatch3r/hatch.json` | `schemaVersion`, adapters, `managedFiles`, board config |
+| Drift | `npx hatch3r status` (and `npx hatch3r verify` if status is ambiguous) | adapter-output drift vs bundled canonical content |
+| Validation | `npx hatch3r validate` | content-structure / frontmatter / cross-ref failures |
+| On-disk adapters | list `.cursor/`, `CLAUDE.md`, `.github/` adapter outputs present | which adapters actually materialized |
+| Recent changes | `git log --oneline -10` + `git status --short` | uncommitted edits to managed files |
+
+Record each probe's exit code and the first failing line. A non-zero exit on `status`/`verify`/`validate` is the primary lead; an unexpected `schemaVersion` (not 3) or a missing adapter output is a secondary lead.
+
+---
+
+## Step 2: Triage Symptom Domain
+
+Classify the captured state into one or more domains before delegating. The domain determines which researcher modes and which file globs the Step 3 prompt scopes to.
+
+| Domain | Lead signal | Researcher scope |
+|--------|-------------|------------------|
+| Setup / install | missing adapter output, first-run failure, Node version mismatch | `src/cli/commands/init.ts`, `.hatch3r/hatch.json`, install logs |
+| Config / manifest | unexpected `schemaVersion`, malformed `.hatch3r/hatch.json`, override not applied | `.hatch3r/hatch.json`, `.hatch3r/overrides/`, `src/content/` precedence |
+| Adapter wiring | adapter output absent/malformed, customization layer ignored | `src/adapters/`, `.customize.yaml`, `.customize.md`, managed-block markers |
+| Drift | `hatch3r status`/`verify` reports on-disk vs canonical mismatch | the specific drifted file path + `src/merge/managedBlocks.ts` |
+
+Triage tier (calibrates fan-out and the Step 0.5 cost preview):
+
+- **Tier 1** — single domain, single drifted file or one obvious config typo. One researcher, no parallel fan-out.
+- **Tier 2** — single domain, multiple files, root cause not obvious from the state bundle alone. One researcher at `standard` depth.
+- **Tier 3** — two or more independent symptom domains. One researcher per domain in parallel (per the Parallel-safety conditions above).
+
+### Step 0.5: Emit Pre-Execution Cost Preview
+
+Before the Step 4 ASK gate (the only mutation gate), surface the cost preview so a multi-domain diagnosis is never approved blind. Emit the `cost_estimate` block per `rules/hatch3r-cost-visibility.md` Pre-Execution Estimate, calibrated to the Step 2 tier.
+
+```yaml
+cost_estimate:
+  expected_sa_count: <Tier 1 ~1 researcher (+1 fixer if a fix lands); Tier 3 = N researchers + 1 fixer>
+  estimated_input_tokens_static_frame: <int>
+  estimated_web_research_queries: <int>   # usually 0 — diagnosis reads local state, not the web
+  triage_tier: light | standard | deep
+  estimated_duration_min: <int>
+```
+
+Post-execution actuals + delta land in the Step 6 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)
+
+`--effort=light|standard|deep` forces the named tier, bypassing the Step 2 auto-classification. The override wins; record both the auto-detected tier and the override so the cost block reports the budget delta. No override passed → the auto-classification stands.
+
+---
+
+## Step 3: Root-Cause Analysis (sub-agent delegation)
+
+Delegate to `hatch3r-researcher` via the Task tool with the `root-cause` and `symptom-trace` modes (`agents/modes/root-cause.md`, `agents/modes/symptom-trace.md`). Launch one researcher per independent symptom domain in parallel.
+
+Each researcher prompt MUST include:
+
+1. The Step 1 state bundle verbatim (probe outputs + exit codes) so the sub-agent does not re-run probes.
+2. The Step 2 domain classification and the scoped file globs for that domain.
+3. The user's symptom description (or the answer to the Step 1 ASK).
+4. All `scope: always` rule directives from `rules/` (loaded once at session start).
+5. The confidence expression requirement (verbatim): rate every finding high/medium/low per `agents/shared/quality-charter.md` §1 — high = root cause reproduced against the captured state; medium = pattern-based; low = best judgment, recommend human review.
+6. Explicit: do NOT create files, modify code, create branches/commits, or change board status — return a structured root-cause record only (the researcher's standing contract).
+
+Await all researchers. Each returns a root-cause record with a `causal_chain` (≥3 steps: symptom → driver → root) and a proposed remediation. If a researcher returns `BLOCKED_AMBIGUITY` or `BLOCKED_PREMISE_CHALLENGE`, halt and surface the blocker to the user per the researcher's BLOCKED Output Schema — do not proceed to a fix on a contested premise.
+
+---
+
+## Step 4: Propose Remediation + ASK Checkpoint (only mutation gate)
+
+Consolidate the researcher root-cause records into one remediation table. Each row: `[#] {domain} • {root cause one-line} • {proposed fix} • {confidence} • {reversible? yes/no}`.
+
+```
+hatch3r-diagnose — PR #n/a (Tier {1|2|3})
+
+Findings:
+  [1] adapter-wiring • CLAUDE.md managed block hand-edited, so `hatch3r status` reports drift • re-run `hatch3r sync` to regenerate the block (discards the hand-edit) • high • reversible
+  [2] config • .hatch3r/hatch.json schemaVersion is 2; current is 3 • run `hatch3r update` to migrate the manifest • high • reversible (snapshot taken)
+
+Tier: 2
+Confidence: high — root cause reproduced against the captured state bundle.
+```
+
+ASK (only gate), per `agents/shared/user-question-protocol.md`:
+
+> Diagnosed {N} root cause(s). Review the proposed remediation:
+> - `accept` — apply every proposed fix via hatch3r-fixer
+> - `fix N` — apply only finding N
+> - `explain N` — print the full causal chain + counter-argument for finding N
+> - `skip` — report the diagnosis only; apply nothing
+>
+> (accept / fix N / explain N / skip)
+
+If a proposed fix is irreversible (deletes a file, drops a manifest field, force-resets a managed block over uncommitted edits), the ASK MUST state that explicitly and default to `skip` per the irreversible-action trigger in `.claude/rules/clarification-default.md`. After the user accepts, the run is autonomous through Step 6.
+
+---
+
+## Step 5: Apply Fix (sub-agent delegation)
+
+For each accepted finding, delegate to `hatch3r-fixer` via the Task tool. Group same-file fixes into one fixer invocation; dispatch disjoint-file fixes in parallel.
+
+Each fixer prompt MUST include:
+
+1. The finding as a structured reviewer-style record: `[CRITICAL|WARNING] {file} — {root cause} — {suggested fix}` (the fixer consumes Critical/Warning findings per its Fix Protocol).
+2. The researcher's causal chain so the fixer fixes the root cause, not the symptom.
+3. All `scope: always` rule directives.
+4. The confidence expression requirement (verbatim).
+5. Explicit: do NOT create branches, commits, or PRs — the fixer's standing boundary; this command stops before commit for human review.
+
+Await the fixer's structured result. Capture its `Delegation proof ID` per file (quoted verbatim in the Step 6 attestation) and its `Reviewer re-run required` signal. When a fix touches framework source under `src/`, honor the fixer's reviewer-loop continuation signal — but this command does not run the full Phase 3 review loop; it surfaces `Reviewer re-run required: true` as a Suggested Next Action in Step 6 rather than auto-spawning a reviewer.
+
+---
+
+## Step 6: Verify + Iteration Summary
+
+Re-run the relevant Step 1 probe(s) to confirm the fix cleared the symptom: re-run `hatch3r status` after a drift/adapter fix, `hatch3r validate` after a content fix, `npx tsc --noEmit` after a `src/` fix. Record each re-run command and its exit code.
+
+### 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: `<path>` via `hatch3r-fixer` when Step 5 applied a fix. A skip-path run (Step 4 `skip`, diagnosis-only) mutated nothing — state `inline_edits_by_orchestrator: none` and `mutating_subagent_invocations: 0`.
+
+### Iteration Summary (mandatory output)
+
+Emit the canonical iteration summary per `rules/hatch3r-iteration-summary.md`:
+
+```markdown
+## Iteration Summary
+
+**Status:** SUCCESS | PARTIAL | FAILED | BLOCKED
+**Outcome:** {one sentence — e.g., "Diagnosed manifest schema drift; migrated .hatch3r/hatch.json to schemaVersion 3; hatch3r status now clean."}
+
+**Done:**
+- {finding} → fixed via hatch3r-fixer (proof: {id}); verified by {re-run command} exit 0
+
+**Not Done / Deferred / Unverified:**
+- (or: `None — full scope completed`)
+
+**Open Questions / Blockers:**
+- (or: `None`)
+
+**Fan-out + Cost:** sub_agents_spawned: { count, rationale } + cost_estimate / cost_actuals / delta
+**Confidence:** {high | medium | low} — {basis from researcher + fixer outputs}
+**Suggested Next Action:** {one line — e.g., "Commit the manifest migration; re-run /hatch3r-diagnose if drift reappears."}
+```
+
+Status decision rules:
+- **SUCCESS** — every accepted fix applied and the re-run probe confirms the symptom cleared.
+- **PARTIAL** — some fixes applied, others BLOCKED, or a re-run probe still reports a residual symptom.
+- **FAILED** — the fixer returned BLOCKED on every finding; no change landed.
+- **BLOCKED** — a researcher returned `BLOCKED_PREMISE_CHALLENGE`, or an irreversible fix needs a user decision not yet given.
+
+---
+
+## Per-Turn Pipeline-State Header (Bypass Protection)
+
+> Orchestration boilerplate: see `commands/shared/orchestration-frame.md` → Per-Turn Pipeline-State Header. Phase mapping for diagnose: `1` = state capture + triage, `2` = researcher root-cause dispatch, `3` = fixer apply + verify + summary. Tier 1 runs are exempt per the Tier 1 exemption.
+
+---
+
+## Guardrails
+
+1. **One ASK gate.** Step 4 is the only user-facing checkpoint. State capture (Step 1) and root-cause analysis (Step 3) are read-only and need no gate.
+2. **No commit or push.** This command stops before commit so the maintainer reviews every change. Git operations are out of scope.
+3. **Read-only probes.** Step 1 runs only read-only hatch3r and git commands; it never mutates the install or the manifest.
+4. **No blind full-surface diagnosis.** A symptom must be named (argument or Step 1 ASK) before delegating — fan-out scales with named symptom domains, not the whole install.
+5. **Irreversible-fix consent.** Any fix that deletes a file, drops a manifest field, or overwrites uncommitted managed-block edits requires an explicit ASK with `skip` as the default.
+
+## Resumability (Decision 27/30)
+
+diagnose is checkpoint-light — Step 1 state capture and Step 3 root-cause analysis are read-only, so an interrupted run re-captures cheaply; the only mutation point is Step 5 (fixer apply), so checkpoint there to avoid re-applying a fix already landed.
+
+> Orchestration boilerplate: see `commands/shared/orchestration-frame.md` → Checkpoint Contract. Per-command slots: workspace `.diagnose-workspace/`; step range the Step 1 → Step 6 progression; `wave` = the per-finding fix index in Step 5; snapshot/rollback paths every file a Step 5 fixer touches. Write points: after Step 1 state capture, after the Step 3 researcher batch returns, after the Step 4 ASK decision, and after each Step 5 fixer returns. The read-only steps record their result so a resume skips re-running probes when the baseline SHA is unchanged.
+
+## References
+
+- `agents/hatch3r-researcher.md` -> `root-cause` / `symptom-trace` modes, BLOCKED Output Schema (accessed 2026-06-02, in-repo canonical, official-docs) — the diagnosis-stage delegate and its structured root-cause-record contract.
+- `agents/hatch3r-fixer.md` -> Fix Protocol, Return Structured Result, Delegation proof ID (accessed 2026-06-02, in-repo canonical, official-docs) — the fix-stage delegate and the forgery-resistant attribution token quoted in the attestation.
+- `agents/shared/user-question-protocol.md` (accessed 2026-06-02, in-repo canonical, official-docs) — B1 gate format for the Step 1 symptom ASK and the Step 4 remediation ASK.
+- `rules/hatch3r-agent-orchestration.md` -> Per-Turn Pipeline-State Header, End-of-Turn Delegation Attestation (accessed 2026-06-02, in-repo canonical, official-docs) — bypass-protection block formats.

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

@@ -2,22 +2,24 @@
 id: hatch3r-feature-plan
 type: command
 orchestrator: true
-agentPipeline: [hatch3r-researcher, hatch3r-docs-writer]
+agentPipeline: [hatch3r-researcher, hatch3r-docs-writer, hatch3r-ui, hatch3r-ux, hatch3r-security, hatch3r-reliability, hatch3r-testability, hatch3r-scalability, hatch3r-performance, hatch3r-maintainability, hatch3r-enhancability]
 description: Design a new capability -- draft user stories, acceptance criteria, data model, API surface, and sub-issue breakdown as an epic-shaped todo.md for greenfield features
 tags: [planning, orchestration]
 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 feature brief — codebase-impact, feature-design, architecture, risk-pitfalls — dispatched concurrently in Step 3; a docs-writer composes the spec on their merged output.
+  count: 13
+  rationale: Four parallel hatch3r-researcher modes per feature brief — codebase-impact, feature-design, architecture, risk-pitfalls — dispatched concurrently in Step 3; a docs-writer composes the spec on their merged output; the 9 CQ vector specialists (ui/ux/security/reliability/testability/scalability/performance/maintainability/enhancability) advise pre-write on the measurable floors that the spec must encode (axe-core threshold, OAuth depth, OTel + SLO scaffolding, mandate-map test class, etc.). 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` (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.
+
 # Feature Plan — Single Feature Specification from Idea to Board-Ready Epic
 
 Take a single feature idea and produce a complete feature specification (`docs/specs/`), architectural decision records (`docs/adr/`) when needed, and structured `todo.md` entries (epic + sub-items) ready for `hatch3r-board-fill`. Spawns parallel researcher sub-agents (codebase impact, feature design, architecture, risk & pitfalls) to analyze the feature 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.
@@ -45,6 +49,16 @@ Take a single feature idea and produce a complete feature specification (`docs/s
 
 ---
 
+## Confidence Propagation Contract
+
+Every sub-agent delegation prompt in this command MUST include the confidence expression requirement below (verbatim). Sub-agents are invoked with the `quality_charter: agents/shared/quality-charter.md` reference in their frontmatter, but the orchestrator repeats the directive to override runtime prompt defaults per the charter §1 rule.
+
+> Confidence expression requirement: rate every recommendation and finding as high/medium/low confidence per the quality charter (`agents/shared/quality-charter.md`). High = verified against current code. Medium = pattern-based, not fully verified. Low = best judgment, recommend human review.
+
+Downstream propagation: every ASK checkpoint that reports verification quality, every gate that evaluates a sub-agent verdict, and every output block that surfaces spec readiness MUST carry a high/medium/low confidence rating sourced from the upstream sub-agent. Dropping the signal between stages is a gate failure.
+
+---
+
 ## Workflow
 
 Execute these steps in order. **Do not skip any step.** Ask the user at every checkpoint marked with ASK.
@@ -59,6 +73,29 @@ Classify the feature-planning request before delegating:
 
 If Tier 1, run the reduced researcher set and skip Step 6 (ADRs). If Tier 2, run the standard pipeline below. If Tier 3, run the full pipeline including ADR generation and confirm spec scope explicitly before writing files.
 
+### Step 0.5: Emit Pre-Execution Cost Preview
+
+Before the first sub-agent dispatch (Step 3), surface the cost preview so a multi-researcher feature-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 ~6, Tier 3 up to 13>
+  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)
+
+Auto-tiering can misclassify — a single-module feature scored as Deep, or a cross-cutting feature 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.
+- The override wins over the auto-detected tier; record both the auto-detected tier and the override in the run context so the Cost estimate block reports the budget delta.
+- No override passed → the Step 0 auto-classification stands.
+
 ---
 
 ### Step 1: Gather Feature Description
@@ -100,7 +137,7 @@ After the feature brief is confirmed, probe for missing requirements across key
    - **Observability**: Logging? Metrics? Error tracking for the new behavior?
    - **Testing**: What constitutes "working"? Acceptance test scenarios?
    - **Rollout**: Feature flags? Phased rollout? Rollback strategy?
-3. Skip dimensions that the feature brief already addresses clearly.
+3. Skip dimensions that the feature brief already addresses with a stated answer.
 
 **ASK:** "Before research begins, I have {N} questions to confirm coverage of all feature dimensions:
 {numbered question list — each with the dimension label and why the answer matters}
@@ -412,6 +449,35 @@ Confirm, or tell me what to adjust."
 
 ---
 
+### Step 7.5: Deterministic Plan-Lint (Evaluator gate before write)
+
+Steps 3-4 are the Planner (researchers) and Steps 5-7 are the Generator (spec/ADR/todo drafting). Before any file is written in Step 8, run an Evaluator pass over the drafted plan — the third role of Anthropic's Planner/Generator/Evaluator pattern (the gather-context → take-action → verify-work loop in `agents/shared/quality-charter.md`). The human ASK checkpoints in Steps 4-7 catch judgment-level disagreements; this gate catches structural defects the human eye skips on a long spec. It is rules-based (string/reference assertions over the drafted artifacts), not LLM-as-judge — the `rules-based > visual > LLM-as-judge` hierarchy applies, so each assertion below either passes or names the offending row.
+
+Run all three assertions against the drafted spec (Step 5), ADR(s) (Step 6), and todo entries (Step 7). Each is a binary predicate over text already drafted; none require re-invoking a sub-agent.
+
+| # | Assertion | Pass condition | Fail action |
+|---|-----------|----------------|-------------|
+| L1 | **Acceptance criteria are testable predicates.** Every cell in the Sub-Features `Acceptance Criteria` column (Step 5) and every acceptance-criteria summary in a todo entry (Step 7) states an observable subject plus a verifiable condition. | No criterion is a bare adjective or unfalsifiable phrase (`works`, `is fast`, `handles errors`, `looks good`, `as expected`) with no measurable subject + condition. A criterion phrased as a checklist item with a concrete trigger and outcome passes. | List each non-testable criterion by sub-feature title; rewrite it as `given <state>, when <action>, then <observable outcome>` (or a measurable threshold) before proceeding. |
+| L2 | **Every `Depends On` resolves to a listed prerequisite.** Each entry in the spec Dependencies table `Depends On` column (Step 5) and each "depends on N" reference in the Implementation Order maps to either another sub-feature/sub-task listed in this spec, an entry in the same Dependencies table, or a named existing artifact marked `Status: Exists`. | Zero dangling dependencies — no `Depends On` value that names nothing in the spec and is not flagged `Needs building` or `Exists`. | Name each unresolved dependency and its source row; add the missing prerequisite to the Dependencies table (with `Type` + `Status`) or correct the reference before proceeding. |
+| L3 | **Edge Cases carry zero empty `expected behavior`.** Every row in the spec `## Edge Cases` section (Step 5) and every row of an Edge-Case Ledger carried from `hatch3r-architect` / `agents/hatch3r-edge-case-analyst.md` has a non-empty `expected behavior` value. | No edge case is listed with a blank, `{expected behavior}` placeholder, or `TBD`/`TODO` expected-behavior cell. | List each edge case with a missing `expected behavior`; fill it from the risk-assessment researcher output, or move the row to `Out of Scope` with a one-line justification before proceeding. |
+
+Emit the lint verdict with the spec-readiness confidence rating per the Confidence Propagation Contract:
+
+```
+plan_lint:
+  L1_testable_acceptance_criteria: pass | fail (<N> non-testable: <titles>)
+  L2_dependencies_resolve:         pass | fail (<N> dangling: <names>)
+  L3_edge_cases_have_expected:     pass | fail (<N> empty: <ids>)
+  verdict: pass | fail
+  confidence: high | medium | low   # sourced from upstream researcher confidence per the Confidence Propagation Contract
+```
+
+**On `fail`:** do not advance to Step 8. Apply the per-assertion Fail action above to repair the drafted content in place, re-present the corrected rows under the relevant Step 5-7 ASK, then re-run this gate. A failing plan-lint is never written to disk — the gate is the last checkpoint before mutation, so structural defects cannot reach the implementer.
+
+**On `pass`:** proceed to Step 8.
+
+---
+
 ### Step 8: Write All Files
 
 After all content is confirmed:
@@ -443,6 +509,59 @@ If yes, instruct the user to invoke the `hatch3r-board-fill` command. Note that
 
 ---
 
+## Resumability (Decision 27/30)
+
+feature-plan is long-running — a Tier 3 cross-cutting feature fans out four parallel hatch3r-researcher modes (codebase-impact, feature-design, architecture, risk-pitfalls) in Step 3, then assembles the spec via docs-writer with the 9 CQ vector specialists (ui/ux/security/reliability/testability/scalability/performance/maintainability/enhancability) advising pre-write on the measurable floors the spec must encode. Per hatch3r's workspace-checkpointed resumability contract, checkpoint progress so an interrupted run re-enters at the last completed step rather than re-running the four-researcher + nine-specialist fan-out.
+
+> Orchestration boilerplate: see `commands/shared/orchestration-frame.md` → Checkpoint Contract. Per-command slots: workspace `.feature-plan-workspace/`; step range Step 0 → Step 8; `wave` = researcher-batch index, then CQ-specialist-batch index; doc dirs `docs/specs/`, `docs/adr/`, `todo.md`; `meta` adds `featureSlug`. Write points: after Step 1 feature-brief context locks, after Step 2 scope ASK, after the Step 3 four-researcher fan-out returns, after the CQ-specialist advisory batch returns, after Step 4 spec synthesis is confirmed by ASK, after each Step 5 file write, after Step 6 todo.md epic + sub-item generation, and after the optional Step 7 chain-to-`hatch3r-board-fill` handoff.
+
+---
+
+## Per-Turn Pipeline-State Header (Bypass Protection)
+
+> Orchestration boilerplate: see `commands/shared/orchestration-frame.md` → Per-Turn Pipeline-State Header. Phase mapping for feature-plan: `1` = feature intake + scope decomposition, `2` = researcher/spec sub-agent dispatch, `3` = plan synthesis + acceptance-criteria drafting + Step 7.5 deterministic plan-lint (Evaluator gate), `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, sub-plan files, criteria spec.
+
+## 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: 13` × tier heuristic in `rules/hatch3r-cost-visibility.md` Pre-Execution Estimate): Tier 1 ≈ 2 (reduced researcher set + docs-writer); Tier 2 ≈ 6; Tier 3 up to 13 (4-5 parallel researcher modes + docs-writer + the 9 CQ vector specialists advising pre-write). 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`.
+
+---
+
+## References
+
+- Anthropic. "Building agents with the Claude Agent SDK." `https://www.anthropic.com/engineering/building-agents-with-the-claude-agent-sdk` (accessed 2026-06-06, Anthropic engineering, official-vendor). Source for the Planner/Generator/Evaluator decomposition and the gather-context → take-action → verify-work loop behind Step 7.5: the Evaluator role evaluates the drafted plan before execution, and the `rules-based > visual > LLM-as-judge` hierarchy is why the Step 7.5 plan-lint is binary string/reference assertions rather than an LLM critique.
+
+---
+
 ## 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).
@@ -456,6 +575,7 @@ If yes, instruct the user to invoke the `hatch3r-board-fill` command. Note that
 
 - **Never skip ASK checkpoints.** Every step with an ASK must pause for user confirmation.
 - **Never write files without user review and confirmation.** All generated content is presented first.
+- **Never write files on a failing Step 7.5 plan-lint.** The Evaluator gate (acceptance criteria testable, dependencies resolve, edge cases carry expected behavior) must report `verdict: pass` before Step 8 — repair the drafted content and re-run the gate; a failing plan never reaches the implementer.
 - **Always delegate research to the hatch3r-researcher agent protocol.** Researcher sub-agents handle Context7 MCP, web research, and the tooling hierarchy internally.
 - **Stay within the feature scope** defined by the user in Step 1. Do not invent sub-features the user did not describe or imply. Flag scope expansion opportunities but do not act on them without explicit approval.
 - **todo.md must be compatible with board-fill format** — markdown checklist with bold titles, grouped by priority, referencing source specs.

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

@@ -4,28 +4,32 @@ type: command
 orchestrator: true
 agentPipeline: [hatch3r-handoff-preparer]
 description: Prepare, resume, list, complete, and prune cross-session handoff documents.
+argument-hint: "prepare | resume [id] | list | complete <id> | prune"
 tags: [orchestration, maintenance]
 quality_charter: agents/shared/quality-charter.md
 efficiency_patterns: agents/shared/efficiency-patterns.md
 cache_friendly: true
 parallel_tool_default: true
+efficiency_tier: standard
 triage_tiers: [1, 2]
 sub_agents_spawned:
   count: 1
-  rationale: Single hatch3r-handoff-preparer delegation for the `prepare` Tier-2 subcommand; `resume`, `list`, `complete`, `prune` run inline with no sub-agent fan-out (filesystem-read or single-file rename per the Triage table).
+  rationale: Single hatch3r-handoff-preparer delegation for the `prepare` Tier-2 subcommand; `resume`, `list`, `complete`, `prune` run inline with no sub-agent fan-out (filesystem-read or single-file rename per the Triage table). Cost-dominance per CONSTITUTION §2 P8 — token cost never serializes independent work.
 ---
 
 ## §0 Detect Ambiguity (P8 B1)
 
-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
 
 The `prepare` subcommand delegates to `hatch3r-handoff-preparer` via the Task tool. The other four subcommands (`resume`, `list`, `complete`, `prune`) run inline within this command — they read, list, transition status, or archive files and do not require a sub-agent.
 
+**Parallel-safety conditions** (per `rules/hatch3r-agent-orchestration.md` §Parallel Safety): any parallel fan-out holds all three — read-only or disjoint writes, deterministic aggregation, no shared mutable state.
+
 ## Learnings Consultation
 
-Before starting, scan `.hatch3r/learnings/` for entries tagged `handoff`, `context-switch`, `resume`, or `session-state`. Apply the protocol in `rules/hatch3r-learning-consult.md` (frontmatter-first scan; surface top 5 by confidence). Skip if the directory has fewer than 3 files.
+Before starting, scan `.hatch3r/learnings/` for entries whose `topic`/`applies-to` cover handoff, context-switch, resume, or session-state. Apply the consult procedure in `rules/hatch3r-learning-system.md` → Mandatory Consultation Gate + Consultation Efficiency (INDEX-first scan; surface top 5 by confidence). Skip if the directory has fewer than 3 files.
 
 # Handoff Management — Cross-Session Work Continuity
 
@@ -42,6 +46,37 @@ Classify the handoff request by subcommand and operation size before routing:
 
 There is no Tier 3 for this command — multi-issue or epic-scale handoffs are out of scope; the caller decomposes into per-work-item handoffs upstream.
 
+### Step 0.5: Emit Pre-Execution Cost Preview
+
+The `prepare` subcommand is the only one that dispatches a sub-agent. Before invoking `hatch3r-handoff-preparer`, surface the cost preview per `rules/hatch3r-cost-visibility.md` Pre-Execution Estimate. The Tier-1 read/list/rename subcommands (`list`, `complete`, `prune --dry-run`) run inline with `expected_sa_count: 0` and may emit a one-line cost note instead of the full block:
+
+```yaml
+cost_estimate:
+  expected_sa_count: <prepare ~1; list/complete/prune-dry-run = 0>
+  estimated_input_tokens_static_frame: <int>
+  estimated_web_research_queries: 0                # handoff is local-only — no web research
+  triage_tier: light | standard
+  estimated_duration_min: <int>
+```
+
+Post-execution actuals + delta land in the Iteration Summary's Fan-out + Cost section per `rules/hatch3r-cost-visibility.md` Post-Execution Actuals. Token telemetry sources from `src/pipeline/observability.ts`.
+
+### Effort Override (Decision 17)
+
+This command has no Tier 3, so `--effort` maps only `light` ↔ `standard`. The override is the recovery path mandated by hatch3r's universal `--effort` override contract ("User overridable via `--effort` flag"):
+
+- `--effort=light|standard` forces the named tier, bypassing the subcommand-derived auto-classification (Step 0). `--effort=deep` is rejected — Tier 3 is out of scope for this command.
+- The override wins over the auto-detected tier; record both the auto-detected tier and the override in the run context so the Cost estimate block reports the budget delta.
+- No override passed → the subcommand-derived classification stands.
+
+## Confidence Propagation Contract
+
+The `prepare` subcommand's `hatch3r-handoff-preparer` delegation prompt MUST include the confidence expression requirement below (verbatim), per the quality charter §1 rule (the inline subcommands produce no graded findings and are exempt).
+
+> Confidence expression requirement: rate every recommendation and finding as high/medium/low confidence per the quality charter (`agents/shared/quality-charter.md`). High = verified against current code. Medium = pattern-based, not fully verified. Low = best judgment, recommend human review.
+
+The preparer's readiness assessment and the `resume` drift-check verdict carry a high/medium/low confidence rating; dropping the signal into the Iteration Summary is a gate failure.
+
 ## Workflow
 
 Execute these steps in order. **Do not skip any step.** Ask the user at every checkpoint marked with **ASK**.
@@ -117,6 +152,45 @@ ID                                              STATUS         BRANCH
 
 ---
 
+## Per-Turn Pipeline-State Header (Bypass Protection)
+
+> Orchestration boilerplate: see `commands/shared/orchestration-frame.md` → Per-Turn Pipeline-State Header. Phase mapping for handoff: `1` = action detection (prepare / load / resume / complete / prune), `2` = handoff-preparer / handoff-loader sub-agent dispatch, `3` = validation + integrity verification, `4` = report + iteration-summary. Tier 1 runs are exempt per the Tier 1 exemption.
+
+## End-of-Turn Delegation Attestation (Bypass Protection)
+
+> Orchestration boilerplate: see `commands/shared/orchestration-frame.md` → End-of-Turn Delegation Attestation. Per-command mutated-file slot: handoff document written under `.hatch3r/handoffs/active/`.
+
+## Iteration Summary (mandatory output)
+
+Emit the canonical 9-section iteration summary per `rules/hatch3r-iteration-summary.md` as the final user-facing output. The validation gate at `.claude/rules/capability-lifecycle.md` blocks SUCCESS declarations without this block (CONSTITUTION §6 Decision 23).
+
+The 9 sections:
+
+1. **Request** — verbatim restatement of the user's ask in one sentence.
+2. **Fan-out + Cost** — `sub_agents_spawned: { count, rationale }` plus the `cost_estimate` / `cost_actuals` / `delta` blocks (see Cost Visibility below).
+3. **Web Research** — every URL fetched with access date + trust tier per `agents/shared/rigor-contract.md` (0 acceptable when no research was needed).
+4. **Files Mutated** — list with diff summary (lines added / removed / files created).
+5. **Gates Passed / Failed** — explicit list per `.claude/rules/capability-lifecycle.md` Gate Checklist.
+6. **Pillar Impact Attribution** — `progress_toward_pillar: <axis>.<pillar_id>+<delta>` per CONSTITUTION §6 Decision 17.
+7. **Verification Commands** — exact commands run with exit codes plus key output lines (≤200 chars).
+8. **Open Questions / Blockers** — explicit `None` if fully closed.
+9. **Learnings Captured** — IDs of any learnings written to `.hatch3r/learnings/` this run per `rules/hatch3r-learning-system.md`.
+
+### Cost Visibility (Decision 24)
+
+> Orchestration boilerplate: see `commands/shared/orchestration-frame.md` → Cost Estimate for the 5-field `cost_estimate` schema and the post-execution `cost_actuals` + `delta` contract; both land in Section 2 above.
+
+## Cost estimate (Decision 24)
+
+This command emits cost transparency per `rules/hatch3r-cost-visibility.md` and CONSTITUTION §6 Decision 24/29:
+
+- **Pre-execution `cost_estimate`** — emitted in Step 0.5 before the `prepare` subcommand invokes `hatch3r-handoff-preparer`. Inline subcommands emit a one-line `expected_sa_count: 0` cost note.
+- **Post-execution `cost_actuals` + `delta`** — appended to the Iteration Summary's Fan-out + Cost section per `rules/hatch3r-iteration-summary.md` §2.
+
+Per-tier `expected_sa_count` calibration (from frontmatter `sub_agents_spawned.count: 1` × tier heuristic in `rules/hatch3r-cost-visibility.md` Pre-Execution Estimate): `prepare` ≈ 1 (one preparer delegation); `resume` ≈ 0 (inline drift check + status transition); `list`/`complete`/`prune` ≈ 0 (filesystem read or single-file rename). This command is local-only — `estimated_web_research_queries` is always 0. Deltas beyond 25% absolute value carry `flagged_for_review: true`. Token telemetry sources from `src/pipeline/observability.ts`; estimation primitives from `src/pipeline/costEstimator.ts`.
+
+---
+
 ## Error Handling
 
 - `.hatch3r/handoffs/active/` missing or empty: emit `No active handoffs. Run 'hatch3r-handoff prepare' to capture one.` and exit 0.
@@ -131,3 +205,9 @@ ID                                              STATUS         BRANCH
 - **Never include secrets** (API keys, tokens, credentials) in any handoff body. The preparer scans for credential-shaped strings; reject the write if any are detected.
 - **Never write** outside `.hatch3r/handoffs/active/` for new handoffs. Archival is the only path into `archived/`.
 - **Always emit the Iteration Summary block** at the end of the iteration per `rules/hatch3r-iteration-summary.md`.
+
+## References
+
+- `agents/shared/user-question-protocol.md` (B1 gate — applies at §0 Detect Ambiguity above plus every mid-workflow ASK checkpoint per Finding D7-M14)
+- `agents/shared/quality-charter.md` §1, §3, §7, §8 (confidence, ambiguity, measurable criteria)
+- `rules/hatch3r-agent-orchestration.md` (Per-Turn Pipeline-State Header, End-of-Turn Delegation Attestation, Mandatory Delegation Directive)