hatch3r 1.9.0 → 2.0.0

package/dist/content/rules/hatch3r-code-standards.mdc

@@ -1,13 +1,18 @@
 ---
-description: TypeScript typing discipline, naming, file size caps, Result types, barrel exports, import ordering, and monorepo boundary rules
+description: Language-agnostic code floor — naming, file/function size caps, cyclomatic complexity, Result-type error handling, module boundaries, monorepo rules, dead-code prevention, and untrusted-content hygiene
 alwaysApply: true
+precedence: high
 ---
 # Code Standards
 
+**Pillars:** P2 (Scientific & Practical Quality), P6 (Security & Trust Governance), CQ8 (Maintainability Quality)
+
+This rule is the language-agnostic code floor: it applies on every project regardless of stack. TypeScript/JavaScript-specific mechanics (`satisfies`, branded types, barrel `index.ts` exports, `eslint-plugin-import` ordering) live in the language-gated companion `rules/hatch3r-typescript-patterns.md` (`scope: conditional`, `lang:typescript`) so those idioms do not bind as a floor on Go, Rust, Python, Ruby, or Java repos where they are nonsensical (D14-14 / SA14.1-F3).
+
 ## Core Conventions
 
 - Enable strict type checking. No type escape hatches (e.g., `any`, `@ts-ignore`, or equivalent) without a linked issue.
-- Functions: `camelCase`. Types/Interfaces: `PascalCase`. Constants: `SCREAMING_SNAKE`.
+- Functions: `camelCase`. Types/Interfaces: `PascalCase`. Constants: `SCREAMING_SNAKE`. (Apply the closest equivalent when the language convention differs.)
 - Component files: `PascalCase` (match framework convention). Logic files: `camelCase` (or language convention).
 - Max function length: 50 lines. Max file: 400 lines. Cyclomatic complexity: 10.
 - Use framework-recommended component patterns (e.g., typed props and emits).
@@ -16,40 +21,11 @@ alwaysApply: true
 - All animations must respect `prefers-reduced-motion`.
 - Run lint and typecheck before committing.
 
-## TypeScript-Specific Patterns
-
-### `satisfies` Over `as`
-
-- Use `satisfies` to validate a value conforms to a type while preserving its narrower inferred type. Prefer `satisfies Config` over `as Config` because `as` silences type errors and loses narrowing.
-- Use `as const` for literal types in configuration objects, action types, and discriminant values. Combine with `satisfies` when both literal inference and shape validation are needed: `const config = { ... } as const satisfies Config`.
-
-### Discriminated Unions
-
-- Model domain variants with discriminated unions over polymorphic classes or `type` string checks. Every variant must share a common literal discriminant field (e.g., `kind`, `type`, `status`).
-- Use exhaustive `switch` with a `never` default case so the compiler errors when a new variant is added but not handled.
-
-### Branded Types
-
-- Use branded types for domain identifiers that must not be accidentally interchanged (e.g., `UserId`, `OrderId`, `Currency`). Implement via intersection with a unique symbol: `type UserId = string & { readonly __brand: unique symbol }`.
-- Provide factory functions (`createUserId(raw: string): UserId`) that validate the input before branding. Never brand raw values without validation.
-
-### Strict Utility Types
-
-- Prefer `Readonly<T>` for function parameters and return types that should not be mutated by the caller.
-- Use `Record<string, never>` instead of `{}` to represent an empty object type. `{}` matches any non-nullish value.
-- Avoid `Omit` with string literals that do not exist on the source type — use `satisfies` or a helper type that enforces key existence.
-
 ## Architecture Patterns
 
-### Barrel Exports
-
-- Use barrel files (`index.ts`) at module boundaries to define the public API of a module. Re-export only the types and functions intended for external consumption.
-- Never import from a module's internal files directly — import from the barrel. Enforce with ESLint `no-restricted-imports` or equivalent.
-- Keep barrel files thin — only re-exports, no logic. A barrel with logic is a code smell.
-
 ### Module Boundaries
 
-- Define clear module boundaries: each module owns its types, logic, and tests. Cross-module imports go through barrel exports.
+- Define clear module boundaries: each module owns its types, logic, and tests. Cross-module imports go through the module's public API.
 - Circular imports between modules are forbidden. Use dependency inversion (interfaces at the boundary) to break cycles.
 - Shared types used across modules live in a `types/` or `shared/` directory, not duplicated in each module.
 
@@ -65,7 +41,7 @@ alwaysApply: true
 
 - For operations that can fail in expected ways (validation, parsing, external calls), prefer returning a `Result<T, E>` discriminated union over throwing exceptions. Exceptions are for unexpected/unrecoverable failures.
 - Define a project-wide `Result` type: `type Result<T, E = Error> = { ok: true; value: T } | { ok: false; error: E }`.
-- Callers must handle both variants — the type system enforces exhaustive error handling.
+- Callers must handle both variants — the type system forces every error path to be handled before the value is read.
 
 ### Custom Error Classes
 
@@ -100,18 +76,6 @@ The following patterns are always wrong and must be flagged in review:
 | `// @ts-ignore` without linked issue | Permanent type-safety hole | Fix the type error or add `// @ts-expect-error` with issue link |
 | `try { ... } catch { return defaultValue; }` for all errors | Treats transient errors (network) same as permanent ones (validation) | Discriminate error types: retry transient, fail permanent |
 
-## Import Ordering
-
-Enforce consistent import ordering via linter rules (e.g., `eslint-plugin-import`). The canonical order:
-
-1. **Built-in modules** — `node:fs`, `node:path`, etc.
-2. **External packages** — `zod`, `express`, etc.
-3. **Internal aliases** — `@/utils`, `@/types`, etc.
-4. **Relative imports** — `./sibling`, `../parent`, etc.
-5. **Type-only imports** — `import type { ... }` (grouped separately where the linter supports it)
-
-Separate each group with a blank line. Sort alphabetically within each group.
-
 ## Monorepo Conventions
 
 When working in a monorepo (multiple packages or apps in a single repository):
@@ -123,7 +87,19 @@ When working in a monorepo (multiple packages or apps in a single repository):
 ## Dead Code Prevention
 
 - Remove unused imports, variables, functions, and type definitions immediately. Do not comment them out "for later."
-- Use the TypeScript compiler (`noUnusedLocals`, `noUnusedParameters`) and ESLint (`no-unused-vars`) to catch dead code automatically.
+- Use the compiler's unused-symbol diagnostics (e.g., TypeScript `noUnusedLocals`/`noUnusedParameters`, Go `go vet`, Rust `dead_code`) and the linter (`no-unused-vars` or equivalent) to catch dead code automatically.
 - After removing a feature or completing a refactor, search for all references to the removed code. Delete orphaned tests, fixtures, and documentation.
 - Feature-flagged code that has been fully rolled out (flag removed) must have the flag-off branch deleted in the same PR.
 - Commented-out code is never acceptable in committed code. Use version control history to retrieve old implementations.
+
+## Untrusted Content Hygiene (Prompt-Injection Defense)
+
+Per OWASP ASI01 (Prompt Injection) and ASI06 (Memory Poisoning), every source path that ingests external content into an LLM context — user-supplied prompts, web-scraped pages, MCP tool outputs, learnings files, retrieved documents — MUST treat that content as untrusted by default.
+
+- **Strip or escape role-control tokens** before concatenating untrusted content into a model prompt. Pattern catalog: `agents/shared/injection-patterns.md` (canonical) and the executable form in `src/pipeline/promptGuard.ts::INJECTION_PATTERNS`. At minimum block: role headers (`system:`/`assistant:`/`user:` at line start), chat templates (`[ INST ]`, `<| im_start |>`), template literals (`{{...}}`, `<%...%>`), null bytes / ANSI escapes, Unicode tag smuggling (`U+E0000–U+E007F`).
+- **Quote untrusted content with explicit boundary markers** when including it in the prompt — wrap in `<UNTRUSTED_INPUT>...</UNTRUSTED_INPUT>` or equivalent, instruct the model to treat the content as data, never as instructions.
+- **Validate before persisting to long-term memory** (learnings, handoffs, manifest fields). Stored content is read back into future prompts, so injection in storage is a delayed-trigger attack vector — apply the `LEARNINGS_INJECTION_PATTERNS` screen (`src/content/learningsValidation.ts`) before write.
+- **Apply byte budgets** on every external-content ingestion path — 500KB pipeline input / 1MB pipeline output per `src/pipeline/promptGuard.ts`. Reject content above the budget rather than truncating silently.
+- **Never echo untrusted content as if it were a system instruction** in agent output (prevents reflective injection through reviewer/fixer reads of upstream phase output).
+
+Reference: `rules/hatch3r-security-patterns.md` (security-domain detail), `rules/hatch3r-typescript-patterns.md` (TypeScript/JavaScript-specific typing, barrel, and import mechanics), the agentic-security audit domain (audit checklist), OWASP Agentic Security Initiative ASI01 + ASI06.

package/dist/content/rules/hatch3r-component-conventions.md

@@ -5,11 +5,14 @@ description: Component structure, styling tokens, loading/error/empty states, fo
 scope: conditional
 globs: "src/**/*.vue,src/**/*.tsx,src/**/*.jsx"
 tags: [implementation, floor:ui-ux, lang:typescript]
+precedence: high
 quality_charter: agents/shared/quality-charter.md
 cache_friendly: true
 ---
 # Component Conventions
 
+**Pillars:** P2 (Scientific & Practical Quality), CQ1 (UI Quality)
+
 ## Library and Token Detection (Mandatory Pre-Author Step)
 
 Before authoring any new UI primitive, complete this scan and reuse > extend > create:

package/dist/content/rules/hatch3r-component-conventions.mdc

@@ -2,9 +2,12 @@
 description: Component structure, styling tokens, loading/error/empty states, form validation timing, and accessible label patterns for Vue, React, and JSX
 globs: ["src/**/*.vue", "src/**/*.tsx", "src/**/*.jsx"]
 alwaysApply: false
+precedence: high
 ---
 # Component Conventions
 
+**Pillars:** P2 (Scientific & Practical Quality), CQ1 (UI Quality)
+
 ## Library and Token Detection (Mandatory Pre-Author Step)
 
 Before authoring any new UI primitive, complete this scan and reuse > extend > create:

package/dist/content/rules/hatch3r-container-hardening.md

@@ -2,7 +2,8 @@
 id: hatch3r-container-hardening
 type: rule
 description: Container image hardening — digest pinning, distroless / Wolfi base, non-root user, SBOM-in-image, cosign signing + verification, multi-stage builds, CVE scanning
-scope: "**/Dockerfile*,**/docker-compose*,**/*.containerfile,**/charts/**,**/k8s/**,**/kubernetes/**,**/manifests/**"
+scope: conditional
+globs: "**/Dockerfile*,**/docker-compose*,**/*.containerfile,**/charts/**,**/k8s/**,**/kubernetes/**,**/manifests/**"
 tags: [devops, floor:security]
 precedence: high
 quality_charter: agents/shared/quality-charter.md
@@ -51,6 +52,8 @@ Every image carries a CycloneDX 1.6 SBOM, generated at build time and either emb
 
 ## Image Signing — cosign
 
+> Maturity tier: team+ — solo projects with no external consumers may defer signing. Cosign keyless + admission enforcement becomes mandatory once images are pulled by anyone outside the build pipeline.
+
 Every image is signed with cosign keyless mode via OIDC. Sigstore Fulcio issues a short-lived signing certificate scoped to the workflow identity; Rekor records the signature for tamper-evident audit.
 
 - Sign in CI: `cosign sign --yes <registry>/<image>@<digest>`. Workflow grants `id-token: write` permission; no long-lived signing key.
@@ -59,6 +62,8 @@ Every image is signed with cosign keyless mode via OIDC. Sigstore Fulcio issues
 
 ## CVE Scanning in CI
 
+> Maturity tier: team+ — solo projects may run a single scanner ad hoc. Two-scanner CI gating with suppression lifecycle earns its cost once a team owns the release pipeline.
+
 Two scanners are run per image build: `trivy` for breadth (Wolfi advisory database, OS+language deps) and `grype` for Chainguard parity. Release is blocked on unpatched Critical or High CVEs without a documented suppression record.
 
 - `trivy image --severity HIGH,CRITICAL --exit-code 1 <image>:<tag>` fails the job on any High/Critical.
@@ -76,6 +81,8 @@ The same digest-not-tag rule extends beyond `FROM` lines to every place the imag
 
 ## Reproducible Builds
 
+> Maturity tier: scaleup+ — team projects may defer the `repro-build` verification step until a compliance or supply-chain audit requests it. Solo and team projects still pin syntax + package versions; the digest-comparison gate is the scaleup add.
+
 Build inputs are pinned so the same `git checkout` produces the same image digest.
 
 - `# syntax=docker/dockerfile:1.<minor>.<patch>` — pin to a specific BuildKit syntax version.
@@ -110,6 +117,8 @@ Runtime image targets under 200 MB compressed. Builds exceeding 500 MB compresse
 
 ## Verification Gate at Release
 
+> Maturity tier: team+ — solo projects may defer the full five-gate release block. The non-root + digest-pin gates remain mandatory at every tier; cosign verification, dual-scanner thresholds, and SBOM attachment fire once a team owns admission policy.
+
 Every release pipeline executes the following gates before publish, all green:
 
 - `cosign verify` against the workflow OIDC identity.
@@ -118,7 +127,7 @@ Every release pipeline executes the following gates before publish, all green:
 - Pod spec runs as non-root (`runAsNonRoot: true`), read-only root filesystem, dropped capabilities.
 - SBOM attached and downloadable via `cosign download sbom`.
 
-Cross-reference `agents/hatch3r-security-auditor.md` for runtime security audit; `agents/hatch3r-devops.md` for delivery integration; `rules/hatch3r-secrets-management.md` for OIDC trust-policy conditions; `rules/hatch3r-dependency-management.md` for SBOM tooling and SLSA provenance.
+Cross-reference `agents/hatch3r-security.md` (CQ3) for runtime security audit; `agents/hatch3r-devops.md` for delivery integration; `rules/hatch3r-secrets-management.md` for OIDC trust-policy conditions; `rules/hatch3r-dependency-management.md` for SBOM tooling and SLSA provenance.
 
 ## References
 

package/dist/content/rules/hatch3r-container-hardening.mdc

@@ -47,6 +47,8 @@ Every image carries a CycloneDX 1.6 SBOM, generated at build time and either emb
 
 ## Image Signing — cosign
 
+> Maturity tier: team+ — solo projects with no external consumers may defer signing. Cosign keyless + admission enforcement becomes mandatory once images are pulled by anyone outside the build pipeline.
+
 Every image is signed with cosign keyless mode via OIDC. Sigstore Fulcio issues a short-lived signing certificate scoped to the workflow identity; Rekor records the signature for tamper-evident audit.
 
 - Sign in CI: `cosign sign --yes <registry>/<image>@<digest>`. Workflow grants `id-token: write` permission; no long-lived signing key.
@@ -55,6 +57,8 @@ Every image is signed with cosign keyless mode via OIDC. Sigstore Fulcio issues
 
 ## CVE Scanning in CI
 
+> Maturity tier: team+ — solo projects may run a single scanner ad hoc. Two-scanner CI gating with suppression lifecycle earns its cost once a team owns the release pipeline.
+
 Two scanners are run per image build: `trivy` for breadth (Wolfi advisory database, OS+language deps) and `grype` for Chainguard parity. Release is blocked on unpatched Critical or High CVEs without a documented suppression record.
 
 - `trivy image --severity HIGH,CRITICAL --exit-code 1 <image>:<tag>` fails the job on any High/Critical.
@@ -72,6 +76,8 @@ The same digest-not-tag rule extends beyond `FROM` lines to every place the imag
 
 ## Reproducible Builds
 
+> Maturity tier: scaleup+ — team projects may defer the `repro-build` verification step until a compliance or supply-chain audit requests it. Solo and team projects still pin syntax + package versions; the digest-comparison gate is the scaleup add.
+
 Build inputs are pinned so the same `git checkout` produces the same image digest.
 
 - `# syntax=docker/dockerfile:1.<minor>.<patch>` — pin to a specific BuildKit syntax version.
@@ -106,6 +112,8 @@ Runtime image targets under 200 MB compressed. Builds exceeding 500 MB compresse
 
 ## Verification Gate at Release
 
+> Maturity tier: team+ — solo projects may defer the full five-gate release block. The non-root + digest-pin gates remain mandatory at every tier; cosign verification, dual-scanner thresholds, and SBOM attachment fire once a team owns admission policy.
+
 Every release pipeline executes the following gates before publish, all green:
 
 - `cosign verify` against the workflow OIDC identity.
@@ -114,7 +122,7 @@ Every release pipeline executes the following gates before publish, all green:
 - Pod spec runs as non-root (`runAsNonRoot: true`), read-only root filesystem, dropped capabilities.
 - SBOM attached and downloadable via `cosign download sbom`.
 
-Cross-reference `agents/hatch3r-security-auditor.md` for runtime security audit; `agents/hatch3r-devops.md` for delivery integration; `rules/hatch3r-secrets-management.md` for OIDC trust-policy conditions; `rules/hatch3r-dependency-management.md` for SBOM tooling and SLSA provenance.
+Cross-reference `agents/hatch3r-security.md` (CQ3) for runtime security audit; `agents/hatch3r-devops.md` for delivery integration; `rules/hatch3r-secrets-management.md` for OIDC trust-policy conditions; `rules/hatch3r-dependency-management.md` for SBOM tooling and SLSA provenance.
 
 ## References
 

package/dist/content/rules/hatch3r-contract-testing.md

@@ -2,7 +2,8 @@
 id: hatch3r-contract-testing
 type: rule
 description: Consumer-driven and spec-driven contract testing between services — Pact, Schemathesis, Dredd, pact-broker can-i-deploy gate
-scope: "**/contracts/**,**/pacts/**,**/api/**,**/openapi*,**/asyncapi*,**/*.proto,**/__tests__/contract/**"
+scope: conditional
+globs: "**/contracts/**,**/pacts/**,**/api/**,**/openapi*,**/asyncapi*,**/*.proto,**/__tests__/contract/**"
 tags: [review, implementation]
 precedence: high
 quality_charter: agents/shared/quality-charter.md

package/dist/content/rules/hatch3r-cost-visibility.md

@@ -0,0 +1,135 @@
+---
+id: hatch3r-cost-visibility
+type: rule
+description: Pre-execution cost estimate + post-execution actuals + delta surfacing in iteration summary. Every orchestrator command emits cost data.
+tags: [cost, telemetry, observability, floor:content-quality]
+precedence: high
+scope: always
+---
+# hatch3r Cost Visibility
+
+**Pillars:** P7 (Speed & Token Efficiency), P5 (Governance Self-Quality)
+
+Source: the cost-visibility design decision and the cost-transparency principle (pillar P7; see `agents/shared/principles.md`).
+
+Every orchestrator command (`commands/hatch3r-*.md` with `orchestrator: true`) and every meaningful skill run that mutates state MUST emit cost data — pre-execution estimate at plan time and post-execution actuals + delta at completion time. The delta lands in the iteration summary's Fan-out + Cost section per `rules/hatch3r-iteration-summary.md` §2.
+
+## Pre-Execution Estimate
+
+Emit at plan time, before fan-out begins:
+
+```yaml
+cost_estimate:
+  expected_sa_count: <int>
+  estimated_input_tokens_static_frame: <int>
+  estimated_web_research_queries: <int>
+  triage_tier: light | standard | deep
+  estimated_duration_min: <int>
+```
+
+Derived from:
+
+- Frontmatter `sub_agents_spawned` declaration when present (static intent declared by the artifact).
+- Triage-tier heuristics: Light = 1-3 SAs, Standard = 4-9 SAs, Deep = 10+ SAs.
+- Past-cycle telemetry baseline from `src/pipeline/observability.ts` — phase-level `inputTokens` + `outputTokens` averaged across recent runs of the same artifact ID.
+- Static-prompt frame character count divided by `CHARS_PER_TOKEN` (default 4) per `src/pipeline/observability.ts::estimateTokens`.
+
+Triage tier maps directly to `triage_tiers` frontmatter declared per Decision 17 (CONSTITUTION §6 Decision #20 in 2.0.0 mapping) — the runtime-selected tier is the one emitted in the estimate block.
+
+## Post-Execution Actuals
+
+Emit at completion time, after the last sub-agent returns:
+
+```yaml
+cost_actuals:
+  actual_sa_count: <int>
+  actual_input_tokens: <int>
+  actual_output_tokens: <int>
+  actual_web_research_queries: <int>
+  actual_duration_min: <float>
+delta:
+  sa_count_delta: <int>
+  input_tokens_delta_percent: <float>
+  duration_delta_percent: <float>
+```
+
+`sa_count_delta` is `actual_sa_count - expected_sa_count` (signed integer). `input_tokens_delta_percent` is `(actual - estimated) / estimated * 100` rounded to one decimal. `duration_delta_percent` follows the same formula on duration.
+
+## Surfacing in Iteration Summary
+
+Per `rules/hatch3r-iteration-summary.md` §2 Fan-out + Cost: both blocks appear in the iteration summary's Cost section. Deltas exceeding 25% (absolute value) flag for review — they signal under- or over-estimation patterns that the next cycle should investigate. The flag is informational, not a gate failure.
+
+A run with no Cost section in its iteration summary fails the iteration-summary validation gate (`.claude/rules/capability-lifecycle.md` Gate Checklist).
+
+### Worked Example
+
+A Tier 2 capability-add run that spawns 5 sub-agents (1 researcher + 4 implementers) emits at plan time:
+
+```yaml
+cost_estimate:
+  expected_sa_count: 5
+  estimated_input_tokens_static_frame: 18000
+  estimated_web_research_queries: 2
+  triage_tier: standard
+  estimated_duration_min: 12
+```
+
+At completion (one extra implementer spawned due to scope expansion discovered mid-run, two extra web queries):
+
+```yaml
+cost_actuals:
+  actual_sa_count: 6
+  actual_input_tokens: 22400
+  actual_output_tokens: 8900
+  actual_web_research_queries: 4
+  actual_duration_min: 15.3
+delta:
+  sa_count_delta: 1
+  input_tokens_delta_percent: 24.4
+  duration_delta_percent: 27.5
+```
+
+`duration_delta_percent` exceeds 25% — flagged informational for next-cycle EVOLVE review. `input_tokens_delta_percent` is 24.4% — under threshold, no flag.
+
+## Source of Telemetry
+
+`src/pipeline/observability.ts` records:
+
+- Input + output tokens per LLM call via `createPhaseTokenEstimate` → `PhaseTokenEstimate`.
+- Per-pipeline aggregation via `createTokenSummary` → `PipelineTokenSummary` (`totalInputTokens`, `totalOutputTokens`, `grandTotal`).
+- Cost estimation via `estimateCost` → `CostEstimate` with `DEFAULT_INPUT_COST_PER_1M = 3.0` USD and `DEFAULT_OUTPUT_COST_PER_1M = 15.0` USD as default rates.
+- Opt-in `EfficiencyEvent` JSONL telemetry via `recordEfficiencyEvent` (env-gated by `HATCH3R_EFFICIENCY_TELEMETRY=1`) — fields: `artifactId`, `phase`, `tokensIn`, `tokensOut`, `latencyMs`, `modelHint?`, `cacheHit?`.
+- Sub-agent spawn count per orchestrator phase (consumed by `rules/hatch3r-agent-orchestration.md` Per-Turn Pipeline-State Header).
+- Web research query count per cycle (incremented by adapter web-research integrations).
+- Duration per phase via phase timeout instrumentation (`src/pipeline/phaseTimeout.ts`).
+
+Implementation contract: `src/pipeline/costEstimator.ts` (to be authored under Bucket 2.3) consumes the baseline from past `EfficiencyEvent` records and emits `cost_estimate`; `src/pipeline/observability.ts` already provides the actuals primitives.
+
+## End-User Visibility
+
+Cost data appears in user-facing iteration summaries by default. Suppressing via the `--quiet` CLI flag still records telemetry to `.hatch3r/telemetry/<session-id>.json` for later review — the channel is preserved per the Silent Failure Contract (P5). Suppression at the user surface does not suppress at the persistence layer.
+
+Telemetry I/O failures route through `src/pipeline/failureLog.ts` per the Silent Failure Contract — never silently swallowed.
+
+## Acceptance Criteria
+
+A change to a `commands/hatch3r-*.md` orchestrator or to a meaningful state-mutating skill satisfies this rule when ALL hold:
+
+1. The artifact emits `cost_estimate` before the first sub-agent spawn.
+2. The artifact emits `cost_actuals` + `delta` before declaring iteration-summary status.
+3. The iteration summary's Fan-out + Cost section (per `rules/hatch3r-iteration-summary.md` §2) carries both blocks.
+4. Telemetry persists to `.hatch3r/telemetry/<session-id>.json` even under `--quiet`.
+5. Delta thresholds beyond 25% absolute value carry an explicit `flagged_for_review: true` annotation in the iteration summary.
+
+## Emission-Rate Telemetry (current status: per-run gate only; cross-run rate not yet wired)
+
+The acceptance criteria above are checked per run. They do NOT measure the cost-block emission rate across runs, and no automated cross-run measurement exists today.
+
+The SPACE-shaped activity/performance instrumentation (`src/pipeline/spaceTelemetry.ts`) provides the recording primitive `recordSpaceMetric`, the in-process aggregator `getSpaceSummary`, and the across-runs reader `loadSpaceMetricsFromDisk`, but they are not invoked on the cost-visibility path: orchestrator commands and skills are LLM-interpreted markdown with no binding to compiled `src/`, and no command, skill, hook, or `src/` code emits a `costVisibilityEmitted` metric. The cross-run emission-rate loop is therefore unwired — a future capability, not a live measurement (origin: D10-SA10.8-F-6; gap corrected D10-18). The module records on the `activity` and `performance` axes only; its `satisfaction` and `communication` axes are reserved with no feeder, so "SPACE" names the data shape, not full five-axis coverage (D10-40).
+
+To wire it, a host-runtime bridge (a Claude Code / Cursor / Copilot post-turn hook or an MCP shim) would need to call `recordSpaceMetric({ metricId: "costVisibilityEmitted", axis: "activity", value: <1 if both cost_estimate and cost_actuals were produced else 0> })` after each orchestrator/meaningful-skill turn, persisting one JSONL line per run to `.hatch3r/telemetry/space-<YYYY-MM-DD>.jsonl`; the audit cycle could then read the persisted JSONL across runs via `loadSpaceMetricsFromDisk` + `summarizeSpaceMetricRecords` (NOT `getSpaceSummary`, which sees only the current process's ring buffer) to check the 100% cost-visibility emission target against observed runs instead of only mandating it. `recordSpaceMetric` already routes I/O failures through `src/pipeline/failureLog.ts` and never throws (Silent Failure Contract), so building the bridge adds no failure surface. Until that bridge ships, cost-visibility compliance is enforced by the per-run acceptance criteria above plus audit-cycle spot checks, not by an aggregate metric.
+
+## Pillar Service
+
+- **P7** — surfaces token + duration measurements to the user; closes the loop on the P7 token-economy goal. Estimation accuracy improves cycle-over-cycle via the past-cycle telemetry baseline.
+- **P5** — every orchestrator measures itself; deltas become first-class governance signals consumed by the governance evolve-cycle.

package/dist/content/rules/hatch3r-cost-visibility.mdc

@@ -0,0 +1,135 @@
+---
+id: hatch3r-cost-visibility
+type: rule
+description: Pre-execution cost estimate + post-execution actuals + delta surfacing in iteration summary. Every orchestrator command emits cost data.
+tags: [cost, telemetry, observability, floor:content-quality]
+precedence: high
+alwaysApply: true
+---
+# hatch3r Cost Visibility
+
+**Pillars:** P7 (Speed & Token Efficiency), P5 (Governance Self-Quality)
+
+Source: the cost-visibility design decision and the cost-transparency principle (pillar P7; see `agents/shared/principles.md`).
+
+Every orchestrator command (`commands/hatch3r-*.md` with `orchestrator: true`) and every meaningful skill run that mutates state MUST emit cost data — pre-execution estimate at plan time and post-execution actuals + delta at completion time. The delta lands in the iteration summary's Fan-out + Cost section per `rules/hatch3r-iteration-summary.md` §2.
+
+## Pre-Execution Estimate
+
+Emit at plan time, before fan-out begins:
+
+```yaml
+cost_estimate:
+  expected_sa_count: <int>
+  estimated_input_tokens_static_frame: <int>
+  estimated_web_research_queries: <int>
+  triage_tier: light | standard | deep
+  estimated_duration_min: <int>
+```
+
+Derived from:
+
+- Frontmatter `sub_agents_spawned` declaration when present (static intent declared by the artifact).
+- Triage-tier heuristics: Light = 1-3 SAs, Standard = 4-9 SAs, Deep = 10+ SAs.
+- Past-cycle telemetry baseline from `src/pipeline/observability.ts` — phase-level `inputTokens` + `outputTokens` averaged across recent runs of the same artifact ID.
+- Static-prompt frame character count divided by `CHARS_PER_TOKEN` (default 4) per `src/pipeline/observability.ts::estimateTokens`.
+
+Triage tier maps directly to `triage_tiers` frontmatter declared per Decision 17 (CONSTITUTION §6 Decision #20 in 2.0.0 mapping) — the runtime-selected tier is the one emitted in the estimate block.
+
+## Post-Execution Actuals
+
+Emit at completion time, after the last sub-agent returns:
+
+```yaml
+cost_actuals:
+  actual_sa_count: <int>
+  actual_input_tokens: <int>
+  actual_output_tokens: <int>
+  actual_web_research_queries: <int>
+  actual_duration_min: <float>
+delta:
+  sa_count_delta: <int>
+  input_tokens_delta_percent: <float>
+  duration_delta_percent: <float>
+```
+
+`sa_count_delta` is `actual_sa_count - expected_sa_count` (signed integer). `input_tokens_delta_percent` is `(actual - estimated) / estimated * 100` rounded to one decimal. `duration_delta_percent` follows the same formula on duration.
+
+## Surfacing in Iteration Summary
+
+Per `rules/hatch3r-iteration-summary.md` §2 Fan-out + Cost: both blocks appear in the iteration summary's Cost section. Deltas exceeding 25% (absolute value) flag for review — they signal under- or over-estimation patterns that the next cycle should investigate. The flag is informational, not a gate failure.
+
+A run with no Cost section in its iteration summary fails the iteration-summary validation gate (`.claude/rules/capability-lifecycle.md` Gate Checklist).
+
+### Worked Example
+
+A Tier 2 capability-add run that spawns 5 sub-agents (1 researcher + 4 implementers) emits at plan time:
+
+```yaml
+cost_estimate:
+  expected_sa_count: 5
+  estimated_input_tokens_static_frame: 18000
+  estimated_web_research_queries: 2
+  triage_tier: standard
+  estimated_duration_min: 12
+```
+
+At completion (one extra implementer spawned due to scope expansion discovered mid-run, two extra web queries):
+
+```yaml
+cost_actuals:
+  actual_sa_count: 6
+  actual_input_tokens: 22400
+  actual_output_tokens: 8900
+  actual_web_research_queries: 4
+  actual_duration_min: 15.3
+delta:
+  sa_count_delta: 1
+  input_tokens_delta_percent: 24.4
+  duration_delta_percent: 27.5
+```
+
+`duration_delta_percent` exceeds 25% — flagged informational for next-cycle EVOLVE review. `input_tokens_delta_percent` is 24.4% — under threshold, no flag.
+
+## Source of Telemetry
+
+`src/pipeline/observability.ts` records:
+
+- Input + output tokens per LLM call via `createPhaseTokenEstimate` → `PhaseTokenEstimate`.
+- Per-pipeline aggregation via `createTokenSummary` → `PipelineTokenSummary` (`totalInputTokens`, `totalOutputTokens`, `grandTotal`).
+- Cost estimation via `estimateCost` → `CostEstimate` with `DEFAULT_INPUT_COST_PER_1M = 3.0` USD and `DEFAULT_OUTPUT_COST_PER_1M = 15.0` USD as default rates.
+- Opt-in `EfficiencyEvent` JSONL telemetry via `recordEfficiencyEvent` (env-gated by `HATCH3R_EFFICIENCY_TELEMETRY=1`) — fields: `artifactId`, `phase`, `tokensIn`, `tokensOut`, `latencyMs`, `modelHint?`, `cacheHit?`.
+- Sub-agent spawn count per orchestrator phase (consumed by `rules/hatch3r-agent-orchestration.md` Per-Turn Pipeline-State Header).
+- Web research query count per cycle (incremented by adapter web-research integrations).
+- Duration per phase via phase timeout instrumentation (`src/pipeline/phaseTimeout.ts`).
+
+Implementation contract: `src/pipeline/costEstimator.ts` (to be authored under Bucket 2.3) consumes the baseline from past `EfficiencyEvent` records and emits `cost_estimate`; `src/pipeline/observability.ts` already provides the actuals primitives.
+
+## End-User Visibility
+
+Cost data appears in user-facing iteration summaries by default. Suppressing via the `--quiet` CLI flag still records telemetry to `.hatch3r/telemetry/<session-id>.json` for later review — the channel is preserved per the Silent Failure Contract (P5). Suppression at the user surface does not suppress at the persistence layer.
+
+Telemetry I/O failures route through `src/pipeline/failureLog.ts` per the Silent Failure Contract — never silently swallowed.
+
+## Acceptance Criteria
+
+A change to a `commands/hatch3r-*.md` orchestrator or to a meaningful state-mutating skill satisfies this rule when ALL hold:
+
+1. The artifact emits `cost_estimate` before the first sub-agent spawn.
+2. The artifact emits `cost_actuals` + `delta` before declaring iteration-summary status.
+3. The iteration summary's Fan-out + Cost section (per `rules/hatch3r-iteration-summary.md` §2) carries both blocks.
+4. Telemetry persists to `.hatch3r/telemetry/<session-id>.json` even under `--quiet`.
+5. Delta thresholds beyond 25% absolute value carry an explicit `flagged_for_review: true` annotation in the iteration summary.
+
+## Emission-Rate Telemetry (current status: per-run gate only; cross-run rate not yet wired)
+
+The acceptance criteria above are checked per run. They do NOT measure the cost-block emission rate across runs, and no automated cross-run measurement exists today.
+
+The SPACE-shaped activity/performance instrumentation (`src/pipeline/spaceTelemetry.ts`) provides the recording primitive `recordSpaceMetric`, the in-process aggregator `getSpaceSummary`, and the across-runs reader `loadSpaceMetricsFromDisk`, but they are not invoked on the cost-visibility path: orchestrator commands and skills are LLM-interpreted markdown with no binding to compiled `src/`, and no command, skill, hook, or `src/` code emits a `costVisibilityEmitted` metric. The cross-run emission-rate loop is therefore unwired — a future capability, not a live measurement (origin: D10-SA10.8-F-6; gap corrected D10-18). The module records on the `activity` and `performance` axes only; its `satisfaction` and `communication` axes are reserved with no feeder, so "SPACE" names the data shape, not full five-axis coverage (D10-40).
+
+To wire it, a host-runtime bridge (a Claude Code / Cursor / Copilot post-turn hook or an MCP shim) would need to call `recordSpaceMetric({ metricId: "costVisibilityEmitted", axis: "activity", value: <1 if both cost_estimate and cost_actuals were produced else 0> })` after each orchestrator/meaningful-skill turn, persisting one JSONL line per run to `.hatch3r/telemetry/space-<YYYY-MM-DD>.jsonl`; the audit cycle could then read the persisted JSONL across runs via `loadSpaceMetricsFromDisk` + `summarizeSpaceMetricRecords` (NOT `getSpaceSummary`, which sees only the current process's ring buffer) to check the 100% cost-visibility emission target against observed runs instead of only mandating it. `recordSpaceMetric` already routes I/O failures through `src/pipeline/failureLog.ts` and never throws (Silent Failure Contract), so building the bridge adds no failure surface. Until that bridge ships, cost-visibility compliance is enforced by the per-run acceptance criteria above plus audit-cycle spot checks, not by an aggregate metric.
+
+## Pillar Service
+
+- **P7** — surfaces token + duration measurements to the user; closes the loop on the P7 token-economy goal. Estimation accuracy improves cycle-over-cycle via the past-cycle telemetry baseline.
+- **P5** — every orchestrator measures itself; deltas become first-class governance signals consumed by the governance evolve-cycle.

package/dist/content/rules/hatch3r-cq-rule-frame.md

@@ -0,0 +1,54 @@
+---
+id: hatch3r-cq-rule-frame
+type: rule
+description: Shared output frame for the CQ measurement rules — the per-finding rigor-field schema and the Specialist-Status to canonical-severity map cited by hatch3r-{security,testability,scalability,maintainability,enhancability}
+scope: conditional
+globs: "src/**,**/__tests__/**,**/handlers/**,**/routes/**,**/services/**,**/api/**,**/migrations/**,**/openapi.yaml,**/openapi.json,**/*.proto,**/schema.graphql,**/asyncapi.yaml"
+tags: [review, floor:content-quality]
+precedence: high
+quality_charter: agents/shared/quality-charter.md
+cache_friendly: true
+---
+# CQ Rule Frame
+
+**Pillars:** P4 (Comprehensive Lean Coverage), P7 (Speed & Token Efficiency)
+
+## Scope
+
+This rule is the single source of two blocks that every CQ measurement rule emits: the per-finding rigor-field schema and the Specialist-Status to canonical-severity map. It is consumed by the CQ vector rules:
+
+- `rules/hatch3r-security.md` (CQ3)
+- `rules/hatch3r-testability.md` (CQ5)
+- `rules/hatch3r-scalability.md` (CQ6)
+- `rules/hatch3r-maintainability.md` (CQ8)
+- `rules/hatch3r-enhancability.md` (CQ9)
+
+Each consuming rule cites this file for both blocks and adds only its rule-specific Action list (the Status-to-Action consequences that differ per CQ vector). The upstream canonical vocabulary owner is `agents/shared/severity-mapping.md` — this file restates only the 3-row Specialist-Status subset that the CQ rules share, parameterized by CQ vector.
+
+## Per-Finding Output Format
+
+Every finding emitted under a CQ measurement rule MUST include the rigor-contract fields per `agents/shared/rigor-contract.md`. `<N>` is the consuming rule's CQ number (3, 5, 6, 8, or 9); the proof-trace artifact named in the first field is the consuming rule's measurement surface (file, test file, handler, or spec diff):
+
+- `proof_trace`: file:line citation + the consuming rule's measurement-output excerpt (command, runner, jscpd/oasdiff/buf-breaking, or spec-diff/grep).
+- `impact_horizon`: short | medium | long per CONSTITUTION Decision 17.
+- `progress_toward_pillar: content-quality.CQ<N>+<delta>`: numeric delta against the threshold (e.g. `+0.05` for a 5% step toward the consuming rule's target).
+- `confidence`: high | medium | low with explicit basis.
+- `causal_chain`: ≥3-step linkage from observation → root cause → impact.
+
+## Specialist-Status to Canonical-Severity Map
+
+Specialist status maps to canonical audit severity per `agents/shared/severity-mapping.md` (the canonical mapping owner). The 3-row subset the CQ rules share:
+
+| Specialist Status | Canonical Severity |
+|-------------------|--------------------|
+| `CRITICAL` | Critical |
+| `FINDINGS` | High + Medium |
+| `PASS` | Low + Info |
+
+The Action column is rule-specific and stays in each consuming rule's Severity Mapping section: the consuming rule lists, per Specialist Status row, the merge/release consequence for its CQ vector (block-release triggers, block-merge triggers, iteration-summary surfacing).
+
+## References
+
+- `agents/shared/severity-mapping.md` (canonical severity-vocabulary owner — 6-column map + Specialist Status column).
+- `agents/shared/rigor-contract.md` (the rigor-field definitions referenced by the output format).
+- `rules/hatch3r-security.md`, `rules/hatch3r-testability.md`, `rules/hatch3r-scalability.md`, `rules/hatch3r-maintainability.md`, `rules/hatch3r-enhancability.md` (the 5 consuming CQ rules).

package/dist/content/rules/hatch3r-cq-rule-frame.mdc

@@ -0,0 +1,49 @@
+---
+description: Shared output frame for the CQ measurement rules — the per-finding rigor-field schema and the Specialist-Status to canonical-severity map cited by hatch3r-{security,testability,scalability,maintainability,enhancability}
+globs: ["src/**", "**/__tests__/**", "**/handlers/**", "**/routes/**", "**/services/**", "**/api/**", "**/migrations/**", "**/openapi.yaml", "**/openapi.json", "**/*.proto", "**/schema.graphql", "**/asyncapi.yaml"]
+alwaysApply: false
+precedence: high
+---
+# CQ Rule Frame
+
+**Pillars:** P4 (Comprehensive Lean Coverage), P7 (Speed & Token Efficiency)
+
+## Scope
+
+This rule is the single source of two blocks that every CQ measurement rule emits: the per-finding rigor-field schema and the Specialist-Status to canonical-severity map. It is consumed by the CQ vector rules:
+
+- `rules/hatch3r-security.md` (CQ3)
+- `rules/hatch3r-testability.md` (CQ5)
+- `rules/hatch3r-scalability.md` (CQ6)
+- `rules/hatch3r-maintainability.md` (CQ8)
+- `rules/hatch3r-enhancability.md` (CQ9)
+
+Each consuming rule cites this file for both blocks and adds only its rule-specific Action list (the Status-to-Action consequences that differ per CQ vector). The upstream canonical vocabulary owner is `agents/shared/severity-mapping.md` — this file restates only the 3-row Specialist-Status subset that the CQ rules share, parameterized by CQ vector.
+
+## Per-Finding Output Format
+
+Every finding emitted under a CQ measurement rule MUST include the rigor-contract fields per `agents/shared/rigor-contract.md`. `<N>` is the consuming rule's CQ number (3, 5, 6, 8, or 9); the proof-trace artifact named in the first field is the consuming rule's measurement surface (file, test file, handler, or spec diff):
+
+- `proof_trace`: file:line citation + the consuming rule's measurement-output excerpt (command, runner, jscpd/oasdiff/buf-breaking, or spec-diff/grep).
+- `impact_horizon`: short | medium | long per CONSTITUTION Decision 17.
+- `progress_toward_pillar: content-quality.CQ<N>+<delta>`: numeric delta against the threshold (e.g. `+0.05` for a 5% step toward the consuming rule's target).
+- `confidence`: high | medium | low with explicit basis.
+- `causal_chain`: ≥3-step linkage from observation → root cause → impact.
+
+## Specialist-Status to Canonical-Severity Map
+
+Specialist status maps to canonical audit severity per `agents/shared/severity-mapping.md` (the canonical mapping owner). The 3-row subset the CQ rules share:
+
+| Specialist Status | Canonical Severity |
+|-------------------|--------------------|
+| `CRITICAL` | Critical |
+| `FINDINGS` | High + Medium |
+| `PASS` | Low + Info |
+
+The Action column is rule-specific and stays in each consuming rule's Severity Mapping section: the consuming rule lists, per Specialist Status row, the merge/release consequence for its CQ vector (block-release triggers, block-merge triggers, iteration-summary surfacing).
+
+## References
+
+- `agents/shared/severity-mapping.md` (canonical severity-vocabulary owner — 6-column map + Specialist Status column).
+- `agents/shared/rigor-contract.md` (the rigor-field definitions referenced by the output format).
+- `rules/hatch3r-security.md`, `rules/hatch3r-testability.md`, `rules/hatch3r-scalability.md`, `rules/hatch3r-maintainability.md`, `rules/hatch3r-enhancability.md` (the 5 consuming CQ rules).