hatch3r 1.8.0 → 2.0.0

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

@@ -4,20 +4,22 @@ type: command
 orchestrator: true
 agentPipeline: [hatch3r-researcher, hatch3r-docs-writer]
 description: Sequence delivery phases over time into a dependency-ordered milestone plan with business and technical lenses, emitting a todo.md rollout schedule rather than design docs
-tags: [planning, greenfield]
+tags: [planning, ctx:greenfield-only]
 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: 2
-  rationale: Two parallel hatch3r-researcher modes (business-priority + technical-readiness) in Step 3 to inform sequencing; one hatch3r-docs-writer in Step 6 assembles todo.md on their merged output (serialized on the research → assembly dependency edge).
+  rationale: Two parallel hatch3r-researcher modes (business-priority + technical-readiness) in Step 3 to inform sequencing; one hatch3r-docs-writer in Step 6 assembles todo.md on their merged output (serialized on the research → assembly dependency edge). 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.
 
 # Roadmap — Generate Phased Roadmap from Specs & Vision
 
@@ -31,16 +33,26 @@ Generate a dependency-aware, priority-ordered roadmap with **two parallel dimens
 | 2. Document Generation | `hatch3r-docs-writer` (todo.md generation) | No | Yes |
 | 3. AGENTS.md | `hatch3r-docs-writer` (AGENTS.md generation/rework) | No | Yes |
 
+**Parallel-safety conditions** (per `rules/hatch3r-agent-orchestration.md` §Parallel Safety): every parallel fan-out above holds all three — read-only or disjoint writes, deterministic aggregation, no shared mutable state.
+
 ---
 
 ## Shared Context
 
-**Read the `hatch3r-board-shared` command at the start of the run.** It contains Board Configuration, GitHub Context, Project Reference, Projects v2 sync procedure, and tooling directives. Cache all values for the duration of this run.
+**Read the `hatch3r-board-shared` skill at the start of the run.** It contains Board Configuration, GitHub Context, Project Reference, Projects v2 sync procedure, and tooling directives. Cache all values for the duration of this run.
 
 ## Token-Saving Directives
 
 Follow the **Token-Saving Directives** in `hatch3r-board-shared`.
 
+## 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 business-priority and technical-readiness recommendation (market-timing, revenue-impact ordering, debt-velocity estimate) carries a high/medium/low confidence rating sourced from the researcher sub-agent — web-sourced market estimates are medium at best unless tied to a cited benchmark. The Step 4 roadmap presentation and Step 6 summary MUST preserve the signal. Dropping it between stages is a gate failure.
+
 ---
 
 ## Workflow
@@ -57,6 +69,29 @@ Classify the roadmap request before delegating:
 
 If Tier 1, run the reduced researcher set and skip Step 7 (AGENTS.md) unless requested. If Tier 2, run the standard pipeline below. If Tier 3, run the full pipeline with deep research, surface market-timing intelligence, and confirm phased plan with the user before file writes.
 
+### Step 0.5: Emit Pre-Execution Cost Preview
+
+Before the first sub-agent dispatch (Step 3 parallel researchers), surface the cost preview so a deep-research roadmap 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 ~1 (technical-readiness only), Tier 2 ~2-3, Tier 3 up to 3 (+ AGENTS.md docs-writer)>
+  estimated_input_tokens_static_frame: <int>
+  estimated_web_research_queries: <int>            # market + benchmark research; Tier 3 is web-heavy
+  triage_tier: light | standard | deep
+  estimated_duration_min: <int>
+```
+
+The Step 1 business-discovery interview is user-driven and excluded from the duration estimate. Post-execution actuals + delta land in the Step 6 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 focused single-dimension roadmap scored as Deep, or an enterprise multi-quarter roadmap 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 researcher count and web-research 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.
+
 ---
 
 ### Step 1: Load Project Context & Business Discovery
@@ -159,7 +194,7 @@ Gaps: {list any missing context}
 | **Impact** | critical path, quality of life, nice-to-have, revenue-blocking, scale-blocking |
 | **Dependencies** | What must come first? (both technical and business dependencies) |
 
-7. Present a categorized summary table of all extracted work items, clearly separated into business-driven, technically-driven, and cross-cutting.
+7. Present a categorized summary table of all extracted work items, with separate sections for business-driven, technically-driven, and cross-cutting items.
 
 ---
 
@@ -326,7 +361,7 @@ Map technically-driven milestones across the timeline:
 
 | Milestone Type | Examples |
 |---------------|---------|
-| **Infrastructure readiness** | MVP infra, scaling infra, multi-region, enterprise-grade |
+| **Infrastructure readiness** | MVP infra (solo tier), scaling infra (team/scaleup tier), multi-region, enterprise tier per CONSTITUTION §6 Decision 4 |
 | **Production hardening** | Monitoring, alerting, incident response, SLA readiness |
 | **Technical debt paydown** | Prioritized by business impact (velocity improvement) |
 | **Platform capabilities** | APIs, integrations, extensibility, developer experience |
@@ -388,7 +423,7 @@ Business-Critical Path: {biz milestone 1} → {biz milestone 2} → {launch}
 
 ### Step 5: Generate todo.md
 
-Write `todo.md` in the exact format that `hatch3r-board-fill` expects, with `[BIZ]`/`[TECH]`/`[BOTH]` tags.
+Write `todo.md` in the canonical **Todo Grammar** defined in `hatch3r-board-shared` — the single source of truth that `hatch3r-board-fill` Step 1 parses. Emit `## P{N} — {Label}` priority headers and `- [ ] **[BIZ|TECH|BOTH] {title}**: {description}. Ref: {path}.` item lines exactly as the grammar specifies; the template below is the authoring example for this command.
 
 **Format specification:**
 
@@ -563,6 +598,53 @@ Which would you like to run next? (or none)"
 
 ---
 
+## Resumability (Decision 27/30)
+
+roadmap is long-running — a Tier 3 brownfield discovery fans out parallel researcher sub-agents across Business-Priority and Technical-Readiness intelligence (Steps 2–3), then generates a dual-lens phased roadmap, todo.md, AGENTS.md, and a cross-command handoff (Steps 4–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 multi-mode researcher fan-out.
+
+> Orchestration boilerplate: see `commands/shared/orchestration-frame.md` → Checkpoint Contract. Per-command slots: workspace `.roadmap-workspace/`; step range the Step 0 → Step 8 progression; `wave` = researcher-batch index across business + technical lenses; snapshot/rollback paths `docs/roadmap/`, `todo.md`, and `AGENTS.md`; `meta` adds `roadmapSlug`. Write points: after Step 1 context + business discovery completes, after Step 2 categorization locks, after Step 3 researcher fan-out returns, after the Step 4 dual-lens roadmap synthesis is confirmed by ASK, and after each Step 5–7 file write (roadmap doc, todo.md, AGENTS.md) so already-generated artifacts survive a crash and are not regenerated on resume. Also after Step 8 cross-command handoff dispatch.
+
+---
+
+## Per-Turn Pipeline-State Header (Bypass Protection)
+
+> Orchestration boilerplate: see `commands/shared/orchestration-frame.md` → Per-Turn Pipeline-State Header. Phase mapping for roadmap: `1` = vision intake + horizon scoping, `2` = researcher/spec sub-agent dispatch (themes, milestones, dependencies), `3` = roadmap synthesis + sequencing, `4` = roadmap 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: roadmap doc, milestone files, theme specs.
+
+## 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 (Step 3).
+- **Post-execution `cost_actuals` + `delta`** — appended to the Step 6 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: 2` × tier heuristic in `rules/hatch3r-cost-visibility.md` Pre-Execution Estimate): Tier 1 ≈ 1 (technical-readiness researcher only, condensed todo.md); Tier 2 ≈ 2-3 (both researchers + todo.md docs-writer); Tier 3 up to 3 (both researchers with deep web research + AGENTS.md docs-writer). This command is web-research-heavy at Tier 3 — `estimated_web_research_queries` typically dominates the cost delta. 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
 
 - **No specs or docs found:** Fall back to user-provided vision. Warn that the roadmap will be less detailed without structured specs. Offer to run `hatch3r-project-spec` or `hatch3r-codebase-map` first.
@@ -575,9 +657,9 @@ Which would you like to run next? (or none)"
 - **Stage assessment unclear:** Default to "early-revenue" if the user is unsure. This provides balanced prioritization without over- or under-engineering the roadmap.
 - **No business specs found:** If only technical specs exist (legacy layout), generate a technical-only roadmap and recommend running `hatch3r-project-spec` or `hatch3r-codebase-map` to create business specs.
 
-## Adapter Breadth as Differentiation
+## Adapter Parity Within the Supported Set
 
-Hatch3r's breadth across 13+ adapters (Claude, Cursor, Windsurf, Cline, Copilot, Codex, Gemini, Amp, Aider, Goose, Kiro, OpenCode, Zed) is a core differentiation strategy. To maintain this moat, recommend periodic adapter parity audits as part of any roadmap that includes hatch3r-internal work. The audit should verify that no adapter has fallen behind in feature support (e.g., missing MCP, hooks, or skills support that other adapters already handle). Adapter parity gaps should be tracked as `[TECH]` items at P2 priority or higher.
+hatch3r supports 3 adapters as of 1.9.0 (Cursor, Claude Code, Copilot). Adapter parity within that supported set is enforced by capability-matrix tests; no adapter-parity work should land in roadmaps unless those tests detect a regression. If a regression is detected, track the gap as a `[TECH]` item at P2 priority or higher.
 
 ## Guardrails
 
@@ -585,13 +667,13 @@ Hatch3r's breadth across 13+ adapters (Claude, Cursor, Windsurf, Cline, Copilot,
 - **When in doubt, ASK.** It is better to ask one question too many than to make one wrong assumption. Discovery questions are never wasted.
 - **Never write files without user review and confirmation.** All generated content is presented first.
 - **Never overwrite todo.md without explicit user confirmation.**
-- **todo.md format must be compatible with board-fill** — markdown checklist with bold titles, priority headers matching `## P{N} — {Label}`, items tagged with `[BIZ]`/`[TECH]`/`[BOTH]`.
+- **todo.md format must match the canonical Todo Grammar** in `hatch3r-board-shared` — the single source of truth `hatch3r-board-fill` Step 1 parses (`## P{N} — {Label}` headers; `- [ ] **[BIZ|TECH|BOTH] {title}**: {description}` items).
 - **Keep items at the right granularity** — epic-level for complex features (XL effort), standalone for simple tasks (S/M effort).
 - **Always reference source documentation** (specs, ADRs) where items were derived from. Use `docs/specs/business/` or `docs/specs/technical/` paths matching the item's category.
 - **Do not duplicate work already tracked in GitHub issues.**
-- **Effort estimates are rough and clearly labeled as estimates.**
+- **Effort estimates are rough; label each estimate explicitly with the `(estimate)` suffix.**
 - **Respect existing priority conventions in the project.**
-- **Stage-adaptive prioritization.** Never recommend enterprise-grade solutions for pre-revenue startups. Never recommend MVP shortcuts for scale/enterprise companies. Calibrate all prioritization to the company stage from Step 1d.
+- **Stage-adaptive prioritization.** Never recommend enterprise-tier (per CONSTITUTION §6 Decision 4) solutions for solo-tier pre-revenue startups. Never recommend MVP shortcuts for scaleup-tier or enterprise-tier companies. Calibrate all prioritization to the company stage from Step 1d.
 - **Business milestones must map to technical enablers.** Every business milestone should have its technical prerequisites identified and scheduled ahead of it.
 - **Technical items must justify business impact.** Every technical item (refactor, debt paydown, infrastructure) should state what business outcome it enables or unblocks.
 - **Never overwrite `AGENTS.md`** without explicit user confirmation.

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

@@ -1,31 +1,84 @@
 ---
 id: hatch3r-security-audit
 type: command
-orchestrator: false
+orchestrator: true
+agentPipeline: [hatch3r-implementer, hatch3r-security]
 description: Open an OWASP ASI security epic reviewing auth boundaries, input validation, and supply-chain risks with one hardening sub-issue per module plus trust-boundary audit
-tags: [maintenance, security]
+tags: [maintenance, floor:security]
 quality_charter: agents/shared/quality-charter.md
 efficiency_patterns: agents/shared/efficiency-patterns.md
 cache_friendly: true
 parallel_tool_default: true
+efficiency_tier: deep
+triage_tiers: [2, 3]
+supports_resume: true
+sub_agents_spawned:
+  count: 2
+  rationale: Module-taxonomy discovery and audit-sub-issue authoring delegate to `hatch3r-implementer`; the cross-cutting security axis fans out in parallel to `hatch3r-security` (CQ3 OWASP ASI01-10 coverage + supply-chain + dependency-CVE posture). Fan-out is disjoint across module and cross-cutting axes; serialization would violate P8 B2 task decomposition. Cost-dominance per CONSTITUTION §2 P8 — token cost never serializes independent work.
 ---
 
 ## §0 Detect Ambiguity (P8 B1)
 
-Before any action, scan the user's request and provided context for unresolved questions in scope, acceptance criteria, irreversibility, or constraint conflicts (contradictory inputs, missing target, unknown convention). If any are found, ask the user via the platform-native question tool per `agents/shared/user-question-protocol.md` — do not proceed under silent assumption. This is the default path, not an exception. Acceptable to proceed without asking ONLY when scope is single-target, single-concern, and the brief alone is testable. Any residual ambiguity discovered mid-workflow invokes the same protocol.
+> Orchestration boilerplate: see `commands/shared/orchestration-frame.md` → §0 Detect Ambiguity (P8 B1). Triggers: contradictory inputs, missing target, unknown convention.
 
 ## Agent Pipeline
 
-This command creates audit issues and epics. It does not spawn implementation sub-agents.
+This command discovers the module taxonomy via static analysis, then delegates security-audit sub-issue authoring and two cross-cutting security axes to parallel sub-agents via the Task tool. Pipeline:
 
 | Stage | Agent(s) | Parallel | Required |
 |-------|----------|----------|----------|
 | 1. Context & Pre-flight | Orchestrator (inline) | No | Yes |
-| 2. Issue Creation | Orchestrator (GitHub MCP) | No | Yes |
-| 3. Board Sync | Orchestrator (Projects v2 sync) | No | Yes |
+| 2. Module Audit Authoring | `hatch3r-implementer` (one Task call per module sub-issue body) | Yes (across modules) | Yes |
+| 3. Cross-Cutting Security Axis | `hatch3r-security` (sub-issue authoring covering OWASP ASI01-10 + supply-chain) | No | Yes |
+| 4. Issue Creation | Orchestrator (GitHub MCP) | No | Yes |
+| 5. Board Sync | Orchestrator (Projects v2 sync) | No | Yes |
+
+**Parallel-safety conditions** (per `rules/hatch3r-agent-orchestration.md` §Parallel Safety): every parallel fan-out above holds all three — read-only or disjoint writes, deterministic aggregation, no shared mutable state.
 
 All issue operations MUST follow the Projects v2 Enforcement rules defined in `hatch3r-board-shared`.
 
+Sub-agent fan-out scales with module count per `rules/fan-out-discipline.md` (P8 B2). For each discovered module, a `hatch3r-implementer` Task call authors that module's security-audit sub-issue body in parallel; the cross-cutting audit (`hatch3r-security` for OWASP ASI01-10 + supply-chain) runs alongside the module batch.
+
+## Triage
+
+Classify the security-audit request before fan-out:
+
+- **Tier 2 (standard)**: single repository with discovered module count <=8; parallel module sub-agents bounded by `max_phase4_parallel`.
+- **Tier 3 (deep)**: monorepo with module count >8 OR cross-module trust-boundary depth >=3; same fan-out shape, longer review loop.
+
+Tier is derived from Module Discovery output (Step 2). Tier 1 is not supported — single-target security fixes belong to `hatch3r-quick-change` with a `hatch3r-security` Phase 4 gate.
+
+### Pre-Execution Cost Preview
+
+Before the first sub-agent dispatch (Step 4 module audit-authoring fan-out), surface the cost preview so a wide module fan-out is never started blind. Emit the `cost_estimate` block per `rules/hatch3r-cost-visibility.md` Pre-Execution Estimate, calibrated to the Tier derived from module count:
+
+```yaml
+cost_estimate:
+  expected_sa_count: <module count + 2 cross-cutting axes; Tier 2 ~module-count<=8, Tier 3 module-count>8, bounded by max_phase4_parallel per batch>
+  estimated_input_tokens_static_frame: <int>
+  estimated_web_research_queries: <int>
+  triage_tier: standard | deep
+  estimated_duration_min: <int>
+```
+
+Post-execution actuals + delta land in the Step 6 finalization summary's Fan-out + Cost section per `rules/hatch3r-cost-visibility.md` Post-Execution Actuals. Token telemetry sources from `src/pipeline/observability.ts`.
+
+### Effort Override (Decision 17)
+
+Auto-tiering derives from discovered module count, which can misclassify — a monorepo with many small modules over-scored, or a dense single-package repo under-scored. The user override is the recovery path mandated by hatch3r's universal `--effort` override contract ("User overridable via `--effort` flag"):
+
+- `--effort=standard|deep` forces the named tier, bypassing the module-count auto-classification. `--effort=light` is rejected — Tier 1 is unsupported here (single-target security fixes route to `hatch3r-quick-change`).
+- The override wins over the auto-detected tier; record both the auto-detected tier and the override in the run context so the Cost estimate block reports the budget delta.
+- No override passed → the module-count auto-classification stands.
+
+## Confidence Propagation Contract
+
+Every sub-agent delegation prompt in this command MUST include the confidence expression requirement below (verbatim). Sub-agents are invoked with the `quality_charter: agents/shared/quality-charter.md` reference in their frontmatter, but the orchestrator repeats the directive to override runtime prompt defaults per the charter §1 rule.
+
+> Confidence expression requirement: rate every recommendation and finding as high/medium/low confidence per the quality charter (`agents/shared/quality-charter.md`). High = verified against current code. Medium = pattern-based, not fully verified. Low = best judgment, recommend human review.
+
+Downstream propagation: every authored module-audit sub-issue body and each cross-cutting axis finding MUST carry a high/medium/low confidence rating sourced from the authoring sub-agent. Severity classifications (critical/high/medium/low) are distinct from and additional to this confidence signal. Dropping the confidence signal between stages is a gate failure.
+
 # Security Audit — Full Product Security Audit
 
 Create a security audit epic on **{owner}/{repo}** with one sub-issue per logical project module, plus cross-module trust boundary and OWASP alignment audits. Each sub-issue is a deep static-analysis security audit task that, when picked up by the board workflow, produces a findings epic with actionable sub-issues for hardening application security. The command only creates the initial audit epic — it does NOT execute any audits.
@@ -34,7 +87,7 @@ Create a security audit epic on **{owner}/{repo}** with one sub-issue per logica
 
 ## Shared Context
 
-**Read the project's shared board context at the start of the run** (e.g., `.agents/commands/hatch3r-board-shared.md` or equivalent). It contains GitHub Context, Project Reference, Projects v2 sync procedure, and Board Overview template. Cache all values for the duration of this run.
+**Read the project's shared board context at the start of the run** (e.g., `commands/hatch3r-board-shared/SKILL.md` or equivalent). It contains GitHub Context, Project Reference, Projects v2 sync procedure, and Board Overview template. Cache all values for the duration of this run.
 
 ## Token-Saving Directives
 
@@ -373,6 +426,53 @@ All issue and epic operations in this command MUST follow the Projects v2 Enforc
 
 ---
 
+## Resumability (Decision 27/30)
+
+security-audit is long-running — a Tier 2/3 audit fans out across N module sub-issues plus cross-cutting OWASP ASI controls, creates a security epic + sub-issues on the board, and synchronizes Projects v2 state. Per hatch3r's workspace-checkpointed resumability contract, checkpoint progress so an interrupted run re-enters at the last completed step rather than re-creating already-created issues or re-running the module scan.
+
+> Orchestration boilerplate: see `commands/shared/orchestration-frame.md` → Checkpoint Contract. Per-command slots: workspace `.security-audit-workspace/`; step range the Step 0 → Step 7 progression; `wave` = per-module sub-issue batch index for Step 4; snapshot/rollback paths board-touching state. Write points: after Step 2 module enumeration locks, after Step 3 epic creation returns the epic issue number, after each Step 4 module sub-issue is created (one write per sub-issue so a mid-batch crash preserves prior issue numbers), after each Step 5 cross-cutting sub-issue is created, after Step 6 dependency linking, and after Step 7 Projects v2 sync.
+
+---
+
+## Per-Turn Pipeline-State Header (Bypass Protection)
+
+> Orchestration boilerplate: see `commands/shared/orchestration-frame.md` → Per-Turn Pipeline-State Header. Phase mapping for security-audit: `1` = scope + threat-model intake, `2` = hatch3r-security sub-agent dispatch across security domains (auth / webauthn / supply-chain / OWASP ASI / CVE), `3` = severity-graded aggregation + finding-registry update, `4` = findings-epic 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: findings epic, child issues, registry updates, security advisories.
+
+## Iteration Summary (mandatory output)
+
+Emit the canonical 9-section iteration summary per `rules/hatch3r-iteration-summary.md` as the final user-facing output. The validation gate at `.claude/rules/capability-lifecycle.md` blocks SUCCESS declarations without this block (CONSTITUTION §6 Decision 23).
+
+The 9 sections:
+
+1. **Request** — verbatim restatement of the user's ask in one sentence.
+2. **Fan-out + Cost** — `sub_agents_spawned: { count, rationale }` plus the `cost_estimate` / `cost_actuals` / `delta` blocks (see Cost Visibility below).
+3. **Web Research** — every URL fetched with access date + trust tier per `agents/shared/rigor-contract.md` (0 acceptable when no research was needed).
+4. **Files Mutated** — list with diff summary (lines added / removed / files created).
+5. **Gates Passed / Failed** — explicit list per `.claude/rules/capability-lifecycle.md` Gate Checklist.
+6. **Pillar Impact Attribution** — `progress_toward_pillar: <axis>.<pillar_id>+<delta>` per CONSTITUTION §6 Decision 17.
+7. **Verification Commands** — exact commands run with exit codes plus key output lines (≤200 chars).
+8. **Open Questions / Blockers** — explicit `None` if fully closed.
+9. **Learnings Captured** — IDs of any learnings written to `.hatch3r/learnings/` this run per `rules/hatch3r-learning-system.md`.
+
+### Cost Visibility (Decision 24)
+
+> Orchestration boilerplate: see `commands/shared/orchestration-frame.md` → Cost Estimate for the 5-field `cost_estimate` schema and the post-execution `cost_actuals` + `delta` contract; both land in Section 2 above.
+
+## Cost estimate (Decision 24)
+
+This command emits cost transparency per `rules/hatch3r-cost-visibility.md` and CONSTITUTION §6 Decision 24/29:
+
+- **Pre-execution `cost_estimate`** — emitted in the Pre-Execution Cost Preview above before the first module audit-authoring dispatch (Step 4).
+- **Post-execution `cost_actuals` + `delta`** — appended to the Step 6 finalization summary's Fan-out + Cost section per `rules/hatch3r-iteration-summary.md` §2.
+
+Per-tier `expected_sa_count` calibration (from frontmatter `sub_agents_spawned.count: 2`, which is the static floor; actual fan-out scales with discovered module count per `rules/fan-out-discipline.md` P8 B2): one `hatch3r-implementer` Task per module sub-issue body + `hatch3r-security` for the cross-cutting axis (OWASP ASI01-10 + supply-chain). Tier 2 (module count ≤8) and Tier 3 (module count >8) both bound the parallel module batch by `max_phase4_parallel`. Deltas beyond 25% absolute value carry `flagged_for_review: true`. Token telemetry sources from `src/pipeline/observability.ts`; estimation primitives from `src/pipeline/costEstimator.ts`.
+
+---
+
 ## Error Handling
 
 - `search_issues` failure: retry once, then warn and proceed (assume no existing security audit).

package/dist/content/commands/hatch3r-slo-scaffold.md

@@ -0,0 +1,246 @@
+---
+id: hatch3r-slo-scaffold
+type: command
+orchestrator: true
+agentPipeline: [hatch3r-implementer, hatch3r-reliability]
+description: "Generate baseline SLI/SLO scaffolding for a user-facing service — availability + latency p95/p99 objectives, 28-day error budget, and Google-SRE multi-window multi-burn-rate alert rules in OpenSLO openslo/v1. Implementer writes the files; hatch3r-reliability gates them against the CQ4 floor."
+argument-hint: "[service-name]"
+tags: [devops, reliability, floor:content-quality]
+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-implementer writes the SLI/SLO/alert scaffold files (code mutation flows through the implementer per the Mandatory Delegation Directive); one hatch3r-reliability gates the result against the CQ4 floor (SLO completeness, multi-burn-rate alert correctness). N services fan out to N parallel implementers; the implement -> gate edge is the only serialization. Cost-dominance per CONSTITUTION §2 P8.
+---
+
+## §0 Detect Ambiguity (P8 B1)
+
+Before any action, scan the request for unresolved questions in service scope, SLI source, and objective targets. If the request names two or more services, or omits the availability/latency targets, or does not name the metric source (Prometheus, OTel-derived, or platform-native), ask the user via the platform-native question tool per `agents/shared/user-question-protocol.md` — the burn-rate alert math depends on the target and window, so a guessed target produces an alert rule that fires wrong. Proceed without asking ONLY when one service, one metric source, and explicit availability + latency targets are all given. Source: `.claude/rules/clarification-default.md`.
+
+## Agent Pipeline
+
+| Stage | Agent(s) | Parallel | Required |
+|-------|----------|----------|----------|
+| 1. Parse service spec + targets | Orchestrator (inline) | No | Yes |
+| 2. Confirm targets + ASK gate | Orchestrator (inline) | No | Yes |
+| 3. Generate scaffold | `hatch3r-implementer` | Per service | Yes |
+| 4. Gate against CQ4 floor | `hatch3r-reliability` | Per service | Yes |
+| 5. Verify + Iteration Summary | Orchestrator (inline) | No | Yes |
+
+**Parallel-safety conditions** (per `rules/hatch3r-agent-orchestration.md` §Parallel Safety): when the spec covers two or more services, fan out one `hatch3r-implementer` per service — each writes a disjoint SLO file set, aggregation is deterministic (union of generated paths), no shared mutable state. The `hatch3r-reliability` gate runs once per generated service after its implementer returns.
+
+---
+
+# SLO Scaffold -- Baseline SLI/SLO + Burn-Rate Alerts for a Service
+
+Generates a versioned baseline reliability scaffold for one or more user-facing services: an availability SLI/SLO, a latency p95 and p99 SLI/SLO, a 28-day rolling error budget, and the Google-SRE multi-window multi-burn-rate alert rules that consume them. Output is OpenSLO `openslo/v1` (vendor-neutral, Git-reviewable) plus the matching Prometheus alert-rule expressions.
+
+Use `/hatch3r-slo-scaffold` when a service has no SLO definition and you want the CQ4 baseline (one of the CONSTITUTION §2B reliability floors: "User-facing service SLO defined: 100%"). Use the `hatch3r-reliability-verify` skill to re-verify an existing SLO config without regenerating it; use `/hatch3r-benchmark` for performance measurement rather than SLO authoring.
+
+---
+
+## Argument Parsing
+
+Optional positional argument: `<service-name>`.
+
+- If supplied: seed Step 1 with that service.
+- If omitted: ASK for the service name(s), metric source, and targets before delegating — generating an SLO without a target is meaningless.
+
+---
+
+## Step 0: Triage
+
+Classify the scaffold before delegating, using the Light / Standard / Deep vocabulary in `agents/shared/triage-vocabulary.md` (the `triage_tiers: [1, 2, 3]` array maps `1 = Light`, `2 = Standard`, `3 = Deep`). The chosen tier sets the Step 2 `Tier {1|2|3}` label and the Step 0.5 cost preview.
+
+- **Tier 1 (Light)** — one user-facing service with explicit availability + p95 + p99 targets and one named metric source (e.g. Prometheus). Fan-out: one `hatch3r-implementer` + one `hatch3r-reliability` gate.
+- **Tier 2 (Standard)** — one service with a non-obvious SLI definition (a composite or multi-route service) where the good-event query must be derived rather than read off the RED defaults. Fan-out: one `hatch3r-implementer` at standard depth + one `hatch3r-reliability` gate.
+- **Tier 3 (Deep)** — two or more services, OR a mixed metric-source fleet (some Prometheus, some OTel-derived). Fan-out: one `hatch3r-implementer` per service in parallel + one `hatch3r-reliability` gate per generated service.
+
+A missing availability/latency target or an unnamed metric source fires the §0 B1 gate (`agents/shared/user-question-protocol.md`) before tiering — the burn-rate math derives from the target + window, so a guessed target produces an alert rule that fires wrong. Classify upward on uncertainty (a signal that could read as Tier 2 or Tier 3 takes Tier 3, per the highest-tier rule in `agents/shared/triage-vocabulary.md`).
+
+---
+
+## Step 1: Parse Service Spec + Targets
+
+Collect the inputs that determine the objective values and the alert-rule constants. Cache them for the Step 3 implementer prompt.
+
+| Input | Default if unspecified | Notes |
+|-------|------------------------|-------|
+| Service name | (required — ASK) | becomes OpenSLO `spec.service` |
+| Availability target | (required — ASK) | e.g. `99.9` → `target: 0.999`; drives the budget |
+| Latency p95 target | (required — ASK) | e.g. p95 ≤ 300 ms |
+| Latency p99 target | (required — ASK) | e.g. p99 ≤ 800 ms |
+| Metric source | Prometheus | OpenSLO `metricSource.type`: Prometheus, OpenTelemetry-derived, or platform-native |
+| SLI definition | ratioMetric (good/total) | RED-derived: good = non-5xx requests, total = all requests |
+| Time window | 28d rolling | OpenSLO `timeWindow.duration: 28d`, `isRolling: true` |
+| Output directory | `slo/` | one `<service>.slo.yaml` per service |
+
+The availability target sets the error budget: budget = (1 − target) × window. The burn-rate alert thresholds are derived from the budget per the Google SRE Workbook recipe (Step 3) — they are NOT free parameters.
+
+---
+
+## Step 2: Confirm Targets + ASK Checkpoint (only mutation gate)
+
+Present the resolved spec and the derived budget so the maintainer confirms before files are written.
+
+```
+hatch3r-slo-scaffold — service: {name} (Tier {1|2|3})
+
+Resolved spec:
+  availability target: 99.9%   → 28-day error budget: 0.1% (≈ 40m19s downtime / 28d)
+  latency p95: ≤ 300 ms
+  latency p99: ≤ 800 ms
+  metric source: Prometheus (ratioMetric good/total)
+  window: 28d rolling
+  output: slo/{name}.slo.yaml + slo/{name}.alerts.yaml
+
+Burn-rate alert tiers (Google SRE Workbook ch. 5):
+  page  — 2% budget / 1h  → 14.4x burn  (1h long + 5m short windows both breach)
+  page  — 5% budget / 6h  → 6x burn     (6h long + 30m short)
+  ticket — 10% budget / 3d → 1x burn     (3d long + 6h short)
+
+Tier: 1
+```
+
+ASK (only gate), per `agents/shared/user-question-protocol.md`:
+
+> Generate the SLO scaffold for {name} with the targets above?
+> - `accept` — generate the scaffold and run the CQ4 gate
+> - `edit` — change a target, window, or metric source first
+> - `skip` — cancel; write nothing
+>
+> (accept / edit / skip)
+
+After the user accepts, the run is autonomous through Step 5.
+
+### Step 0.5: Emit Pre-Execution Cost Preview
+
+Before the Step 2 ASK gate, emit the cost preview per `rules/hatch3r-cost-visibility.md`:
+
+```yaml
+cost_estimate:
+  expected_sa_count: <N services × 1 implementer + N × 1 reliability gate>
+  estimated_input_tokens_static_frame: <int>
+  estimated_web_research_queries: <int>   # 0 — the burn-rate recipe is fixed by the references below
+  triage_tier: light | standard | deep
+  estimated_duration_min: <int>
+```
+
+Post-execution actuals + delta land in the Step 5 Iteration Summary's Fan-out + Cost section. `--effort=light|standard|deep` (Decision 17) forces the tier; record both auto and override.
+
+---
+
+## Step 3: Generate Scaffold (sub-agent delegation)
+
+Delegate to `hatch3r-implementer` via the Task tool, one per service. Code mutation flows through the implementer per the Mandatory Delegation Directive — the orchestrator does not write files inline.
+
+Each implementer prompt MUST include the resolved spec, the target file paths, and this scaffold contract:
+
+**SLI/SLO (`slo/<service>.slo.yaml`, OpenSLO `openslo/v1`):**
+
+1. One `kind: SLO` per objective: availability, latency-p95, latency-p99. Each carries `spec.service`, `spec.timeWindow` (`duration: 28d`, `isRolling: true`), `spec.budgetingMethod: Occurrences`, and `spec.objectives[].target`.
+2. Availability SLI is a `ratioMetric` (`good`/`total` counters: good = non-5xx responses, total = all responses) per the RED method. Latency SLIs are `ratioMetric` where good = requests faster than the threshold (e.g. `histogram_quantile`-backed good-event count) — never an averaged latency, because an average hides the tail the p95/p99 objective targets.
+3. `metricSource.type` set from Step 1; the metric query left as a `# TODO: project metric name` placeholder so the implementer does not invent a metric that does not exist (a low-confidence guess flagged in Notes per the implementer's confidence contract).
+
+**Alert rules (`slo/<service>.alerts.yaml`, Prometheus):** the Google SRE Workbook multi-window multi-burn-rate recipe — three tiers, each requiring BOTH a long-window and a short-window burn-rate breach so a transient spike does not page:
+
+| Tier | Budget consumed | Long window | Short window | Burn rate | Severity |
+|------|-----------------|-------------|--------------|-----------|----------|
+| Fast | 2% / 1h | 1h | 5m | 14.4× | page |
+| Mid | 5% / 6h | 6h | 30m | 6× | page |
+| Slow | 10% / 3d | 3d | 6h | 1× | ticket |
+
+The burn-rate constants (14.4×, 6×, 1×) are fixed by the recipe for a 28-day window — they are not tunable per service; the per-service input is only the SLO target that scales the budget. Every alert rule annotation carries a `runbook_url` placeholder (a rule without a runbook is a CQ4 finding per `agents/hatch3r-reliability.md` Boundaries).
+
+Also include in the prompt: all `scope: always` rule directives; the confidence expression requirement (verbatim, high/medium/low per `agents/shared/quality-charter.md` §1); and the explicit boundary "do NOT create branches, commits, or PRs". Await the implementer's structured result; capture `Files changed` and the `Delegation proof ID` per file.
+
+---
+
+## Step 4: Gate Against CQ4 Floor (sub-agent delegation)
+
+After each service's implementer returns, delegate to `hatch3r-reliability` via the Task tool to gate the generated scaffold against the CQ4 reliability floor — the SLO-definition-review invocation in that agent's "When to invoke".
+
+The reliability prompt MUST include the generated file paths and require these checklist items (from `agents/hatch3r-reliability.md` Audit checklist):
+
+1. **SLO completeness** — availability + latency p95 + latency p99 all declared in the versioned file (checklist item 2).
+2. **Multi-burn-rate alert correctness** — exactly 3 tiers, each with a long + short window pair, constants 14.4×/6×/1× for the 28-day window per Google SRE Workbook ch. 5 (checklist item 2); naked single-threshold alerts are rejected.
+3. **Latency SLI is a histogram-backed ratio, not an average** (checklist item 3).
+4. **Every alert carries a `runbook_url` annotation** (Boundaries: "Never deploy an alert rule without a runbook URL").
+
+The reliability gate validates syntax where tooling is available (`promtool check rules` on the alert file, `sloth validate`/OpenSLO validation on the SLO file) and returns its `proof_trace` + verdict. If the gate returns Critical or High findings, surface them and route the fix back through `hatch3r-implementer` (max 1 regeneration pass), then re-gate. A persistent High finding ends the run at `PARTIAL`.
+
+---
+
+## Step 5: Verify + Iteration Summary
+
+Run the available validation commands and record exit codes: `promtool check rules slo/<service>.alerts.yaml`, and OpenSLO/`sloth validate` on the SLO file when the tool is present (note "tool absent" otherwise — do not claim a pass you did not run).
+
+### 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: `slo/<service>.slo.yaml`, `slo/<service>.alerts.yaml` — both `via hatch3r-implementer`.
+
+### 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., "Scaffolded availability + p95 + p99 SLOs and 3-tier burn-rate alerts for checkout-service; reliability gate PASS."}
+
+**Done:**
+- slo/{service}.slo.yaml → 3 SLOs (availability, p95, p99) via hatch3r-implementer (proof: {id})
+- slo/{service}.alerts.yaml → 3-tier multi-burn-rate alerts via hatch3r-implementer (proof: {id})
+
+**Not Done / Deferred / Unverified:**
+- Metric-name placeholders (`# TODO`) — fill with the project's real metric names before deploy
+- (or: `None — full scope completed`)
+
+**Open Questions / Blockers:**
+- (or: `None`)
+
+**Fan-out + Cost:** sub_agents_spawned: { count, rationale } + cost_estimate / cost_actuals / delta
+**Pillar Impact Attribution:** progress_toward_pillar: content-quality.CQ4+{delta}
+**Confidence:** {high | medium | low} — {basis from implementer output + reliability gate verdict}
+**Suggested Next Action:** {one line — e.g., "Replace metric-name TODOs, then wire slo/*.alerts.yaml into the Prometheus rule_files."}
+```
+
+Status decision rules:
+- **SUCCESS** — scaffold generated, reliability gate PASS, validation commands (where tooling exists) exit 0.
+- **PARTIAL** — generated but the reliability gate left a residual High finding, or validation tooling reported a syntax issue not yet resolved.
+- **FAILED** — the implementer returned BLOCKED on every service; nothing written.
+- **BLOCKED** — targets contradictory or a metric source the maintainer must decide on.
+
+---
+
+## Per-Turn Pipeline-State Header (Bypass Protection)
+
+> Orchestration boilerplate: see `commands/shared/orchestration-frame.md` → Per-Turn Pipeline-State Header. Phase mapping: `1` = spec parse + confirm, `2` = implementer scaffold generation, `3` = reliability gate + verify + summary. Tier 1 single-service runs are exempt per the Tier 1 exemption.
+
+---
+
+## Guardrails
+
+1. **One ASK gate.** Step 2 is the only user-facing checkpoint; after `accept`, the run proceeds through Step 5.
+2. **No commit or push.** Generated files are left staged for human review; git operations are out of scope.
+3. **Burn-rate constants are fixed by the recipe.** Do not invent per-service burn rates — the 28-day-window 14.4×/6×/1× tiers come from the Google SRE Workbook; only the SLO target (which scales the budget) is a per-service input.
+4. **No averaged latency SLIs.** Latency objectives are histogram-backed ratios (good = under-threshold request count); an average hides the tail the p95/p99 objective exists to bound.
+5. **Runbook URL required on every alert.** A scaffold whose alert rules lack a `runbook_url` annotation fails the Step 4 CQ4 gate.
+
+## Resumability (Decision 27/30)
+
+slo-scaffold fans out one implementer per service, so checkpoint at the per-service boundary — an interrupted multi-service run re-enters at the first un-scaffolded service rather than regenerating the SLO/alert file sets it already wrote.
+
+> Orchestration boilerplate: see `commands/shared/orchestration-frame.md` → Checkpoint Contract. Per-command slots: workspace `.slo-scaffold-workspace/`; step range the Step 1 → Step 5 progression; `wave` = the per-service index in Step 3/4; snapshot/rollback paths every `slo/<service>.slo.yaml` / `slo/<service>.alerts.yaml` a Step 3 implementer touches. Write points: after the Step 1 spec parse, after the Step 2 accept gate, after each Step 3 implementer return (per service), and after each Step 4 reliability gate.
+
+## References
+
+- [Google SRE — "Alerting on SLOs" (Site Reliability Workbook ch. 5)](https://sre.google/workbook/alerting-on-slos/) (accessed 2026-06-02, Google SRE, official-docs) — the multi-window multi-burn-rate recipe: 2%/1h @ 14.4×, 5%/6h @ 6×, 10%/3d @ 1× for a 30-day budget, each tier requiring a long + short window breach; source for the Step 3 alert table and the "no naked single-threshold alert" guardrail.
+- [OpenSLO — specification README (`openslo/v1`)](https://github.com/OpenSLO/OpenSLO/blob/main/README.md) (accessed 2026-06-02, OpenSLO project, established-library) — the `apiVersion: openslo/v1`, `kind: SLO`, `spec.service`, `timeWindow` (`duration` + `isRolling`), `budgetingMethod`, `objectives[].target`, and `ratioMetric` (good/total) vs `thresholdMetric` field shapes used by the Step 3 SLI/SLO scaffold contract.
+- [Grafana Labs — "How to implement multi-window, multi-burn-rate alerts"](https://grafana.com/blog/how-to-implement-multi-window-multi-burn-rate-alerts-with-grafana-cloud/) (accessed 2026-06-02, Grafana Labs, vendor-note) — cross-vendor confirmation of the Google SRE long+short window pairing and burn-rate constants applied to Prometheus-style rules; corroborates the second source per Decision 14's ≥2-independent-source requirement.
+- `agents/hatch3r-reliability.md` -> Audit checklist items 2-3, Boundaries (accessed 2026-06-02, in-repo canonical, official-docs) — the CQ4 floor the Step 4 gate enforces.