hatch3r 1.9.0 → 2.0.0

package/dist/content/rules/hatch3r-edge-case-discipline.mdc

@@ -0,0 +1,65 @@
+---
+id: hatch3r-edge-case-discipline
+type: rule
+description: Build-time enumeration of domain/data-correctness edge cases (cardinality, null/empty/boundary, cross-entity consistency, illegal state transitions, concurrency, partial failure) plus language-agnostic error-handling discipline — fires at Plan, Implement, and Review
+tags: [implementation, reliability, testing, floor:content-quality]
+alwaysApply: true
+precedence: high
+quality_charter: agents/shared/quality-charter.md
+cache_friendly: true
+---
+# Edge-Case & Error-Handling Discipline
+
+**Pillars:** P2 (Scientific Quality)
+
+This rule fires whenever a feature wires together ≥2 domain entities, or whenever a function consumes external or user-supplied input. Edge-case enumeration becomes a named build-time step, not a runtime afterthought. `rules/hatch3r-resilience-patterns.md` keeps a correct system *available* under failure (breakers, retries, fallbacks); this rule keeps the system *correct* in the first place — the two complement each other and do not overlap.
+
+## When This Fires
+
+- **Plan:** before writing code, enumerate edge cases from the taxonomy below for every entity and every cross-entity relationship the feature touches. List them as explicit named cases (e.g. `case: two contacts collide on email + linked property`), never the placeholder "handle edge cases".
+- **Implement:** each enumerated case is handled in code OR explicitly recorded out-of-scope with a one-line reason. No silent omission — an unlisted case is a gap, an unhandled-but-listed case needs the recorded reason.
+- **Review:** reject the change if any taxonomy category was not enumerated for an entity-wiring feature, or an enumerated case has neither handling nor a recorded out-of-scope reason. Maps to a Medium-or-higher finding per `agents/shared/quality-charter.md` §14.
+
+## Domain Edge-Case Taxonomy
+
+Seven categories. For each: the question to ask, then a worked example in the real-estate domain (properties + contacts + reservations + deals).
+
+1. **Cardinality & duplicates** — for each relationship, what happens at zero, exactly-one, and N? Can two records collide on a natural key? Worked example: two contacts share the same email AND the same linked property but carry a different status — decide the dedup key and the tie-break rule (latest-updated wins, or merge) before writing the join, or the query returns a nondeterministic row.
+
+2. **Null / empty / zero / boundary** — apply boundary-value analysis (Min−1, Min, Max, Max+1) and equivalence partitioning to every numeric, string, and collection input. Worked example: a deal with `amount = 0`, a reservation with an empty date range (`start == end`), a property with zero linked contacts, a name string at the column-length limit and one byte over.
+
+3. **Cross-entity consistency & referential integrity** — if A references B, can B be missing, deleted, or in an invalid state when A is read? Worked example: a reservation pointing at an archived property; a deal whose contact was merged into another contact. Define cascade vs restrict vs orphan handling explicitly for each foreign reference; the default of an unhandled dangling reference is a 500 at read time.
+
+4. **Illegal state transitions** — model the entity lifecycle as an explicit state set, enumerate the legal transitions, and reject the rest at construction and at transition time. Worked example: a deal moving `closed → pending`; a reservation marked `confirmed` on a `withdrawn` listing. Apply make-illegal-states-unrepresentable / parse-don't-validate: validate once at the boundary, then the constructed type carries the proof so downstream code cannot re-encounter the illegal state.
+
+5. **Concurrency & ordering** — two writers modify the same record, or events arrive out of order. Worked example: two agents accept the same reservation slot at the same instant. Name the concurrency-control choice (optimistic version column, row lock, or idempotency key) at design time; "last write wins by accident" is not a choice. Cross-link `rules/hatch3r-scalability.md` and `rules/hatch3r-resilience-patterns.md`.
+
+6. **Partial failure across layers** — a single logical write spans cache + DB + queue + external API; what is the state when step 3 of 4 fails? Worked example: a deal is persisted to the DB, the cache is updated, the "deal-won" event is published, and the external CRM sync then times out. Define the consistency boundary (transaction, saga, or transactional outbox) and the compensating action. Cross-link `rules/hatch3r-resilience-patterns.md` failure classification.
+
+7. **Idempotency on replay / retry** — if the operation runs twice with the same input, is the second run a no-op? Required for any non-idempotent mutation reachable by a retry. Worked example: a retried "create reservation" call must not create two reservations for one slot. Cross-link `rules/hatch3r-resilience-patterns.md` → idempotency-key.
+
+The seven categories are a floor, not a ceiling: enumerate domain-specific invariants alongside them (e.g. "a property has at most one active deal", "a reservation date range never overlaps another confirmed reservation on the same property").
+
+## Error-Handling Discipline
+
+Language-agnostic principles; complements `rules/hatch3r-code-standards.md` and does not restate its TypeScript mechanics.
+
+- **Placement:** catch at architectural boundaries only (route handler, event handler, job processor, UI error boundary); let errors propagate within a module. Defer to `rules/hatch3r-code-standards.md` → Error Boundaries for the full pattern and the TS Result-type mechanics.
+- **Propagation with context:** every re-throw or wrap attaches the failing operation plus the relevant identifiers (entity id, correlation id — no PII, no secrets) and preserves the original cause chain. A wrap that drops the cause is a finding.
+- **Exhaustive matching:** every discriminated union, enum, and explicit state set is matched exhaustively with a compile-time-checked default, so adding a variant breaks the build rather than falling through silently. Cross-link `rules/hatch3r-code-standards.md` → exhaustive `switch` + `never`.
+- **Recovery vs fail-fast triage:** classify each failure as recoverable (fallback or degrade — cross-link `rules/hatch3r-resilience-patterns.md` → Graceful Degradation) or unrecoverable (fail fast with an actionable message — cross-link `agents/shared/quality-charter.md` §6). No catch block treats both alike.
+- **No silent catch (hard rule):** an empty catch, a catch that returns `null` or a default for every error, and swallow-and-continue are all prohibited. Defer to the `rules/hatch3r-code-standards.md` Error Handling Anti-Patterns table for the canonical prohibited list. This ties to `agents/shared/quality-charter.md` §6 (never fail silently) and §8 (a case that cannot be handled at build time is a clarification trigger, not a guess).
+
+## Cross-References
+
+- `rules/hatch3r-code-standards.md` — Result types, custom error classes, exhaustive `switch` + `never`, error anti-pattern table (the TS mechanics this rule references rather than restates).
+- `rules/hatch3r-resilience-patterns.md` — failure classification, idempotency-on-retry, graceful degradation (run-time resilience; this rule is build-time correctness).
+- `rules/hatch3r-testing.md` — every enumerated edge case maps to a required test class per the Per-Feature Mandate Map and Error Path Coverage.
+- `rules/hatch3r-scalability.md` — idempotency-key adoption on mutations.
+- `rules/hatch3r-migrations.md` — concurrent-modification and referential-integrity handling at the schema layer.
+- `agents/shared/quality-charter.md` — §6 (Fail Gracefully), §8 (Escalate Ambiguity Early), §13 (Adversarial Thinking).
+
+## References
+
+- ISTQB Certified Tester Foundation Level syllabus — Boundary Value Analysis + Equivalence Partitioning — `https://www.istqb.org/certifications/certified-tester-foundation-level` (accessed 2026-06-02, official-standards-body).
+- Alexis King, "Parse, Don't Validate" — `https://lexi-lambda.github.io/blog/2019/11/05/parse-don-t-validate/` (accessed 2026-06-02, named-author primary source).

package/dist/content/rules/hatch3r-enhancability.md

@@ -0,0 +1,147 @@
+---
+id: hatch3r-enhancability-rule
+type: rule
+description: CQ9 Enhancability Quality measurement rule — feature-flag adoption on user-visible behavior, config externalization, API versioning + deprecation policy, forward-compat patterns, extension-point definition
+scope: conditional
+globs: "src/**,**/config/**,**/openapi.yaml,**/openapi.json,**/*.proto,**/schema.graphql,**/asyncapi.yaml,**/flags*,**/plugins/**,**/extensions/**"
+tags: [review, enhancability, code-standards, floor:content-quality]
+precedence: high
+quality_charter: agents/shared/quality-charter.md
+cache_friendly: true
+---
+# Enhancability Quality (CQ9)
+
+**Pillars:** P4 (Comprehensive Lean Coverage), CQ9 (Enhancability Quality)
+
+## Scope
+
+This rule binds the CQ9 measurement set across end-user code that hatch3r-generated agents produce. It owns:
+
+- The feature-flag adoption floor on user-visible behavior changes.
+- The configuration-externalization floor on environment-dependent values.
+- The API versioning + deprecation policy on stable endpoints.
+- The forward-compatibility pattern gate (additive schema, Deprecation + Sunset headers, contract tests).
+- The extension-point definition gate for cross-cutting concerns.
+- Specialist routing to `agents/hatch3r-enhancability.md`.
+
+This complements (does not duplicate) `rules/hatch3r-feature-flags.md` (flag-system implementation pattern), `rules/hatch3r-api-versioning.md` (semver + deprecation timeline), and `rules/hatch3r-progressive-delivery.md` (rollout strategy).
+
+## CQ9 Threshold Set
+
+Source: pillar CQ9 (see `agents/shared/principles.md`). Every threshold below is measurable per audit cycle.
+
+| Threshold | Target | Measurement source |
+|-----------|--------|--------------------|
+| Feature-flag adoption | 100% on user-visible behavior changes | Diff scan vs flag-key inventory (`flags.yaml` or in-code registry) |
+| Configuration externalization | 100% on environment-dependent values | Grep diff for hardcoded URLs, timeouts, retry counts, batch sizes, toggles, credentials |
+| API versioning compliance | Semver 2.0.0 per release | MAJOR/MINOR/PATCH bump matches diff classification |
+| Forward-compat patterns | 100% on stable endpoints | Additive schema; Deprecation (RFC 9745) + Sunset (RFC 8594) headers; consumer-driven contract tests |
+| Extension-point definition | Per cross-cutting concern | Named interface; plugin registry; documented lifecycle hooks (onInit, onShutdown, onConfigChange); `## Stability` block |
+| Spec-diff CI gate | Exit-zero per release | `oasdiff`, `buf breaking`, `graphql-inspector diff` CI step active |
+
+## Feature-Flag Adoption
+
+Every user-visible behavior change MUST ship behind an OpenFeature (or vendor-equivalent) flag. The rule:
+
+1. **Provider registration** — application code wires a flag provider via `OpenFeature.setProvider()` (vendor SDK: LaunchDarkly, flagd, Unleash, Flagsmith, Split). Provider config lives in env-overridable settings.
+2. **Flag-key inventory** — every flag key is registered in `flags.yaml` (or equivalent) with metadata: owner, description, default-value, kill-switch flag.
+3. **Evaluation context** — flag evaluations carry a documented attribute schema (user-id, account-id, org-id, environment, locale, beta-cohort).
+4. **Kill-switch** — every behavior-changing flag has a documented kill-switch path: setting the flag to OFF reverts to the previous behavior without code rollback.
+5. **Cleanup window** — flags retired ≤90 days after 100% rollout per `rules/hatch3r-feature-flags.md`.
+
+Behavior changes shipped without a flag are CRITICAL findings.
+
+## Configuration Externalization
+
+Every environment-dependent value MUST be externalized — hardcoded values in `src/` paths are FINDINGS minimum. Externalize via:
+
+- **Schema-validated env** — Zod (`z.object({...}).parse(process.env)`), Joi (`Joi.object({...}).validate()`), Pydantic (`class Settings(BaseSettings)`), envalid (`cleanEnv()`).
+- **Dotenv-flow** — `.env.development`, `.env.production`; secrets via secret-manager not file.
+- **Startup-time validation** — config schema parsed once at boot; mis-config fails fast with named missing field.
+
+Forbidden in `src/` paths:
+
+- Hardcoded URLs to external services.
+- Hardcoded timeouts, retry counts, batch sizes.
+- Hardcoded feature toggles (`if (true)` ahead of a feature).
+- Hardcoded credentials, API keys, tokens (see also `rules/hatch3r-secrets-management.md`).
+- Silent fallback on config-validation error (catch + log + continue) — fail fast or document the explicit recovery path.
+
+## API Versioning + Deprecation
+
+Source: semver 2.0.0 (semver.org) + `rules/hatch3r-api-versioning.md`. The diff classification determines the version bump:
+
+| Diff classification | Required bump |
+|---------------------|---------------|
+| Breaking change (removed field, changed type, renamed endpoint, semantics change) | MAJOR |
+| Additive (new field, new endpoint, new method, new enum value) | MINOR |
+| Fix (clarification, doc-only, bug-fix matching documented behavior) | PATCH |
+
+The OpenAPI / AsyncAPI / GraphQL SDL `info.version` MUST be aligned to the release tag. Skipping a MAJOR bump on a breaking change is CRITICAL.
+
+## Forward-Compatibility Patterns
+
+On stable endpoints:
+
+- **Additive schema** — new fields are optional; default values are documented; consumers ignore unknown fields. Removing a field is breaking; renaming is breaking.
+- **Deprecation header (RFC 9745)** — emit `Deprecation: @1735689600` (Unix-time) or `Deprecation: Tue, 20 May 2025 00:00:00 GMT` (IMF-fixdate) on retiring endpoints.
+- **Sunset header (RFC 8594)** — emit `Sunset: Tue, 31 Dec 2025 23:59:59 GMT` (IMF-fixdate only) on retiring endpoints. Sunset date MUST be later than Deprecation date.
+- **Migration link** — emit `Link: <https://api.example.com/docs/migration>; rel="deprecation"` + `Link: <…>; rel="sunset"`.
+- **Consumer-driven contract tests** — every public surface has a Pact (or equivalent) contract test from the consumer side; provider verification CI step exits-zero.
+- **Spec-diff CI gate** — `oasdiff breaking --fail-on-diff` (REST), `buf breaking --against` (protobuf), `graphql-inspector diff` (GraphQL); the gate exits non-zero on breaks.
+
+## Extension-Point Definition
+
+Cross-cutting concerns (logging, auth, persistence, telemetry, error handling) get a named extension point:
+
+- **Plugin interface** — exported TypeScript interface (`export interface AuthPlugin { ... }`) or Python protocol (`class AuthPlugin(Protocol)`).
+- **Plugin registry** — central registration via `Plugin.register('auth', new MyAuthPlugin())` or dependency-injection container.
+- **Lifecycle hooks** — `onInit(config)`, `onShutdown()`, `onConfigChange(newConfig)`.
+- **Stability block** — `## Stability: stable | experimental | deprecated` block in the plugin's documentation.
+- **Version-stable contract** — once a plugin interface is `stable`, the contract is bound to the deprecation policy and semver rules.
+
+## Specialist Agent Routing
+
+| Trigger | Route to |
+|---------|----------|
+| User-visible behavior modified | `agents/hatch3r-enhancability.md` (flag adoption gate) |
+| Public API surface modified (OpenAPI / GraphQL SDL / AsyncAPI / protobuf) | `agents/hatch3r-enhancability.md` (versioning + forward-compat gate) |
+| Config schema or feature-flag definition modified | `agents/hatch3r-enhancability.md` (externalization gate) |
+| Extension-point interface modified | `agents/hatch3r-enhancability.md` (plugin contract gate) |
+| Release-prep audit | `agents/hatch3r-enhancability.md` |
+
+## Per-Finding Output Format
+
+Every finding emitted under this rule uses the CQ per-finding rigor-field schema per `rules/hatch3r-cq-rule-frame.md` → Per-Finding Output Format (rigor-contract fields per `agents/shared/rigor-contract.md`), with `<N>` = CQ9. The `proof_trace` excerpt is the file:line citation + spec-diff/grep output for the threshold that produced the finding.
+
+## Severity Mapping
+
+The Specialist-Status to canonical-severity map (`CRITICAL` → Critical, `FINDINGS` → High + Medium, `PASS` → Low + Info) is the shared CQ frame per `rules/hatch3r-cq-rule-frame.md` → Specialist-Status to Canonical-Severity Map, sourced from `agents/shared/severity-mapping.md`. CQ9 Action per status:
+
+- `CRITICAL`: Behavior change shipped without a flag; breaking change on stable endpoint without major-version bump; hardcoded credential or secret; silent fallback on config-validation error; missing CI spec-diff gate.
+- `FINDINGS`: Externalization gap (hardcoded URL/timeout/batch-size); missing Deprecation/Sunset header; semver-policy gap; under-documented extension point.
+- `PASS`: All thresholds met; surface in iteration summary.
+
+## Irreversibility Trigger
+
+Retiring a feature flag, dropping an API endpoint, or hardcoding a previously-externalized value is irreversible at production traffic. Each MUST go through `agents/shared/user-question-protocol.md` per `rules/hatch3r-clarification-default.md` B1 before action, with its own ask cycle.
+
+## When to Invoke
+
+- Every PR that modifies user-visible behavior, public API surfaces, config schema, or extension-point interfaces.
+- Implementer pre-write check when authoring a new user-visible behavior — confirms the flag-gating + config-externalization plan before code is written.
+- Verifier pre-merge gate on protected branches that touch the public API or behavior-toggle surface.
+- API change audit during a D14 or forthcoming D22 cycle, or whenever the maturity tier escalates.
+- Plugin / extension-point surface review before declaring an interface stable.
+
+## References
+
+- Pillar CQ9 (measurement set + specialist owner; see `agents/shared/principles.md`).
+- The extensibility audit domain (enhancability domain).
+- `agents/hatch3r-enhancability.md` (CQ9 reviewer / gate).
+- `rules/hatch3r-feature-flags.md` (flag-system implementation pattern).
+- `rules/hatch3r-api-versioning.md` (semver + deprecation timeline).
+- `rules/hatch3r-progressive-delivery.md` (rollout strategy).
+- `rules/hatch3r-secrets-management.md` (secret hygiene — paired with externalization).
+- RFC 9745 (Deprecation header), RFC 8594 (Sunset header), semver 2.0.0 (semver.org).
+- OpenFeature spec (https://openfeature.dev/specification/) — vendor-neutral flag SDK pattern.

package/dist/content/rules/hatch3r-enhancability.mdc

@@ -0,0 +1,142 @@
+---
+description: CQ9 Enhancability Quality measurement rule — feature-flag adoption on user-visible behavior, config externalization, API versioning + deprecation policy, forward-compat patterns, extension-point definition
+globs: ["src/**", "**/config/**", "**/openapi.yaml", "**/openapi.json", "**/*.proto", "**/schema.graphql", "**/asyncapi.yaml", "**/flags*", "**/plugins/**", "**/extensions/**"]
+alwaysApply: false
+precedence: high
+---
+# Enhancability Quality (CQ9)
+
+**Pillars:** P4 (Comprehensive Lean Coverage), CQ9 (Enhancability Quality)
+
+## Scope
+
+This rule binds the CQ9 measurement set across end-user code that hatch3r-generated agents produce. It owns:
+
+- The feature-flag adoption floor on user-visible behavior changes.
+- The configuration-externalization floor on environment-dependent values.
+- The API versioning + deprecation policy on stable endpoints.
+- The forward-compatibility pattern gate (additive schema, Deprecation + Sunset headers, contract tests).
+- The extension-point definition gate for cross-cutting concerns.
+- Specialist routing to `agents/hatch3r-enhancability.md`.
+
+This complements (does not duplicate) `rules/hatch3r-feature-flags.md` (flag-system implementation pattern), `rules/hatch3r-api-versioning.md` (semver + deprecation timeline), and `rules/hatch3r-progressive-delivery.md` (rollout strategy).
+
+## CQ9 Threshold Set
+
+Source: pillar CQ9 (see `agents/shared/principles.md`). Every threshold below is measurable per audit cycle.
+
+| Threshold | Target | Measurement source |
+|-----------|--------|--------------------|
+| Feature-flag adoption | 100% on user-visible behavior changes | Diff scan vs flag-key inventory (`flags.yaml` or in-code registry) |
+| Configuration externalization | 100% on environment-dependent values | Grep diff for hardcoded URLs, timeouts, retry counts, batch sizes, toggles, credentials |
+| API versioning compliance | Semver 2.0.0 per release | MAJOR/MINOR/PATCH bump matches diff classification |
+| Forward-compat patterns | 100% on stable endpoints | Additive schema; Deprecation (RFC 9745) + Sunset (RFC 8594) headers; consumer-driven contract tests |
+| Extension-point definition | Per cross-cutting concern | Named interface; plugin registry; documented lifecycle hooks (onInit, onShutdown, onConfigChange); `## Stability` block |
+| Spec-diff CI gate | Exit-zero per release | `oasdiff`, `buf breaking`, `graphql-inspector diff` CI step active |
+
+## Feature-Flag Adoption
+
+Every user-visible behavior change MUST ship behind an OpenFeature (or vendor-equivalent) flag. The rule:
+
+1. **Provider registration** — application code wires a flag provider via `OpenFeature.setProvider()` (vendor SDK: LaunchDarkly, flagd, Unleash, Flagsmith, Split). Provider config lives in env-overridable settings.
+2. **Flag-key inventory** — every flag key is registered in `flags.yaml` (or equivalent) with metadata: owner, description, default-value, kill-switch flag.
+3. **Evaluation context** — flag evaluations carry a documented attribute schema (user-id, account-id, org-id, environment, locale, beta-cohort).
+4. **Kill-switch** — every behavior-changing flag has a documented kill-switch path: setting the flag to OFF reverts to the previous behavior without code rollback.
+5. **Cleanup window** — flags retired ≤90 days after 100% rollout per `rules/hatch3r-feature-flags.md`.
+
+Behavior changes shipped without a flag are CRITICAL findings.
+
+## Configuration Externalization
+
+Every environment-dependent value MUST be externalized — hardcoded values in `src/` paths are FINDINGS minimum. Externalize via:
+
+- **Schema-validated env** — Zod (`z.object({...}).parse(process.env)`), Joi (`Joi.object({...}).validate()`), Pydantic (`class Settings(BaseSettings)`), envalid (`cleanEnv()`).
+- **Dotenv-flow** — `.env.development`, `.env.production`; secrets via secret-manager not file.
+- **Startup-time validation** — config schema parsed once at boot; mis-config fails fast with named missing field.
+
+Forbidden in `src/` paths:
+
+- Hardcoded URLs to external services.
+- Hardcoded timeouts, retry counts, batch sizes.
+- Hardcoded feature toggles (`if (true)` ahead of a feature).
+- Hardcoded credentials, API keys, tokens (see also `rules/hatch3r-secrets-management.md`).
+- Silent fallback on config-validation error (catch + log + continue) — fail fast or document the explicit recovery path.
+
+## API Versioning + Deprecation
+
+Source: semver 2.0.0 (semver.org) + `rules/hatch3r-api-versioning.md`. The diff classification determines the version bump:
+
+| Diff classification | Required bump |
+|---------------------|---------------|
+| Breaking change (removed field, changed type, renamed endpoint, semantics change) | MAJOR |
+| Additive (new field, new endpoint, new method, new enum value) | MINOR |
+| Fix (clarification, doc-only, bug-fix matching documented behavior) | PATCH |
+
+The OpenAPI / AsyncAPI / GraphQL SDL `info.version` MUST be aligned to the release tag. Skipping a MAJOR bump on a breaking change is CRITICAL.
+
+## Forward-Compatibility Patterns
+
+On stable endpoints:
+
+- **Additive schema** — new fields are optional; default values are documented; consumers ignore unknown fields. Removing a field is breaking; renaming is breaking.
+- **Deprecation header (RFC 9745)** — emit `Deprecation: @1735689600` (Unix-time) or `Deprecation: Tue, 20 May 2025 00:00:00 GMT` (IMF-fixdate) on retiring endpoints.
+- **Sunset header (RFC 8594)** — emit `Sunset: Tue, 31 Dec 2025 23:59:59 GMT` (IMF-fixdate only) on retiring endpoints. Sunset date MUST be later than Deprecation date.
+- **Migration link** — emit `Link: <https://api.example.com/docs/migration>; rel="deprecation"` + `Link: <…>; rel="sunset"`.
+- **Consumer-driven contract tests** — every public surface has a Pact (or equivalent) contract test from the consumer side; provider verification CI step exits-zero.
+- **Spec-diff CI gate** — `oasdiff breaking --fail-on-diff` (REST), `buf breaking --against` (protobuf), `graphql-inspector diff` (GraphQL); the gate exits non-zero on breaks.
+
+## Extension-Point Definition
+
+Cross-cutting concerns (logging, auth, persistence, telemetry, error handling) get a named extension point:
+
+- **Plugin interface** — exported TypeScript interface (`export interface AuthPlugin { ... }`) or Python protocol (`class AuthPlugin(Protocol)`).
+- **Plugin registry** — central registration via `Plugin.register('auth', new MyAuthPlugin())` or dependency-injection container.
+- **Lifecycle hooks** — `onInit(config)`, `onShutdown()`, `onConfigChange(newConfig)`.
+- **Stability block** — `## Stability: stable | experimental | deprecated` block in the plugin's documentation.
+- **Version-stable contract** — once a plugin interface is `stable`, the contract is bound to the deprecation policy and semver rules.
+
+## Specialist Agent Routing
+
+| Trigger | Route to |
+|---------|----------|
+| User-visible behavior modified | `agents/hatch3r-enhancability.md` (flag adoption gate) |
+| Public API surface modified (OpenAPI / GraphQL SDL / AsyncAPI / protobuf) | `agents/hatch3r-enhancability.md` (versioning + forward-compat gate) |
+| Config schema or feature-flag definition modified | `agents/hatch3r-enhancability.md` (externalization gate) |
+| Extension-point interface modified | `agents/hatch3r-enhancability.md` (plugin contract gate) |
+| Release-prep audit | `agents/hatch3r-enhancability.md` |
+
+## Per-Finding Output Format
+
+Every finding emitted under this rule uses the CQ per-finding rigor-field schema per `rules/hatch3r-cq-rule-frame.md` → Per-Finding Output Format (rigor-contract fields per `agents/shared/rigor-contract.md`), with `<N>` = CQ9. The `proof_trace` excerpt is the file:line citation + spec-diff/grep output for the threshold that produced the finding.
+
+## Severity Mapping
+
+The Specialist-Status to canonical-severity map (`CRITICAL` → Critical, `FINDINGS` → High + Medium, `PASS` → Low + Info) is the shared CQ frame per `rules/hatch3r-cq-rule-frame.md` → Specialist-Status to Canonical-Severity Map, sourced from `agents/shared/severity-mapping.md`. CQ9 Action per status:
+
+- `CRITICAL`: Behavior change shipped without a flag; breaking change on stable endpoint without major-version bump; hardcoded credential or secret; silent fallback on config-validation error; missing CI spec-diff gate.
+- `FINDINGS`: Externalization gap (hardcoded URL/timeout/batch-size); missing Deprecation/Sunset header; semver-policy gap; under-documented extension point.
+- `PASS`: All thresholds met; surface in iteration summary.
+
+## Irreversibility Trigger
+
+Retiring a feature flag, dropping an API endpoint, or hardcoding a previously-externalized value is irreversible at production traffic. Each MUST go through `agents/shared/user-question-protocol.md` per `rules/hatch3r-clarification-default.md` B1 before action, with its own ask cycle.
+
+## When to Invoke
+
+- Every PR that modifies user-visible behavior, public API surfaces, config schema, or extension-point interfaces.
+- Implementer pre-write check when authoring a new user-visible behavior — confirms the flag-gating + config-externalization plan before code is written.
+- Verifier pre-merge gate on protected branches that touch the public API or behavior-toggle surface.
+- API change audit during a D14 or forthcoming D22 cycle, or whenever the maturity tier escalates.
+- Plugin / extension-point surface review before declaring an interface stable.
+
+## References
+
+- Pillar CQ9 (measurement set + specialist owner; see `agents/shared/principles.md`).
+- The extensibility audit domain (enhancability domain).
+- `agents/hatch3r-enhancability.md` (CQ9 reviewer / gate).
+- `rules/hatch3r-feature-flags.md` (flag-system implementation pattern).
+- `rules/hatch3r-api-versioning.md` (semver + deprecation timeline).
+- `rules/hatch3r-progressive-delivery.md` (rollout strategy).
+- `rules/hatch3r-secrets-management.md` (secret hygiene — paired with externalization).
+- RFC 9745 (Deprecation header), RFC 8594 (Sunset header), semver 2.0.0 (semver.org).
+- OpenFeature spec (https://openfeature.dev/specification/) — vendor-neutral flag SDK pattern.

package/dist/content/rules/hatch3r-event-schema-evolution.md

@@ -2,7 +2,8 @@
 id: hatch3r-event-schema-evolution
 type: rule
 description: Event and message schema evolution patterns for Kafka / Kinesis / Pub-Sub / event store — backward + forward + full compatibility modes, schema registry, consumer-side defaults
-scope: "**/events/**,**/schemas/**,**/*.avsc,**/*.proto,**/messaging/**,**/kafka/**,**/pubsub/**"
+scope: conditional
+globs: "**/events/**,**/schemas/**,**/*.avsc,**/*.proto,**/messaging/**,**/kafka/**,**/pubsub/**"
 tags: [implementation, devops]
 precedence: high
 quality_charter: agents/shared/quality-charter.md

package/dist/content/rules/hatch3r-fan-out-discipline.md

@@ -0,0 +1,91 @@
+---
+id: hatch3r-fan-out-discipline
+type: rule
+description: "P8 B2 floor: sub-agent fan-out scales with task size; serialization is valid only on dependency edges; token cost never justifies under-fan-out. Delegating artifacts emit sub-agent count + rationale as a first-class output field."
+tags: [orchestration, floor:protocol]
+scope: always
+precedence: high
+quality_charter: agents/shared/quality-charter.md
+cache_friendly: true
+---
+# hatch3r Fan-out Discipline
+
+**Pillars:** P8 (Clarification & Fan-out Discipline)
+
+Canonical reference for the *mechanics* of parallel dispatch: `rules/hatch3r-agent-orchestration.md` → Parallel Safety. This rule is the corpus-wide, always-on floor that every adapter ships to the end-user repo, so the B2 directive binds runtime agents directly and not only by inheritance through the orchestration rule.
+
+## B2 directive (verbatim)
+
+> Sub-agent fan-out scales with task size; serialization is only valid on dependency edges. Token cost is never a valid reason to serialize independent work. Delegating artifacts emit sub-agent count + rationale as a first-class output field.
+
+## Scaling heuristic
+
+Sub-agent count tracks task decomposition, not a fixed cap:
+
+- N independent modules → N parallel Phase-2 implementers.
+- M specialist gates → M parallel Phase-4 specialists.
+- K independent research questions → K parallel researcher modes.
+
+When work is independent under the three parallel-safety conditions below, fan out. Only a true dependency edge — where stage B consumes stage A's output — justifies serialization.
+
+The count derived above sets WHETHER to spawn each sub-agent. Past roughly 8 concurrent sub-agents, the count also sets the SHAPE: a single orchestrator that integrates 11–15 concurrent results in one context becomes the reviewability bottleneck. At that width, keep the full task-derived count but split it across a two-level tree (see Hierarchical delegation) rather than collapsing it to a narrower flat fan-out — collapsing the count to ease integration is the P8 violation the cost-dominance clause already forbids.
+
+## Hierarchical delegation
+
+The flat model — one orchestrator fans out to N workers and integrates all N results itself — is the default and is correct up to roughly 8 concurrent sub-agents (the empirical lead-agent ceiling cited in References, and the `max_phase4_parallel` default in `rules/hatch3r-agent-orchestration.md`). Beyond that width, prefer a two-level tree over a flat 11–15-wide fan-out:
+
+- The root orchestrator decomposes the task into ≤8 disjoint groups and spawns one sub-orchestrator per group.
+- Each sub-orchestrator fans out to its group's workers, integrates that group's results, and returns a single group-level summary.
+- The root integrates ≤8 group summaries — not 11–15 raw worker results — so per-context integration load stays inside the reviewability ceiling at every level.
+
+This preserves the task-derived total fan-out (no work is serialized): the same N workers still run concurrently, redistributed across sub-orchestrators. The grouping boundary MUST honor the three parallel-safety conditions both within a group and across groups, so a two-level tree carries no extra merge risk over the equivalent flat fan-out. High-fan-out commands are the trigger case — `commands/hatch3r-workflow.md` (`count: 15`) and the batch-mode `commands/hatch3r-board-fill.md` / `commands/hatch3r-board-pickup.md` (`count: 11` × issue count) otherwise concentrate every result on one orchestrator context.
+
+Cost-dominance and reviewability govern different axes and never trade against each other: cost-dominance governs WHETHER to spawn a sub-agent (always spawn when work is independent; token cost never serializes it), reviewability governs the SHAPE of the resulting tree (flat ≤8, two-level beyond). Neither axis ever justifies dropping the task-derived count.
+
+## Three parallel-safety conditions
+
+Fan out only when ALL three hold (per `rules/hatch3r-agent-orchestration.md` → Three Conditions to Parallelize):
+
+1. **Read-only or disjoint writes** — no two sub-agents write the same file or region.
+2. **Deterministic aggregation** — outputs merge without orchestrator intervention (tests pass-if-all-pass; findings union).
+3. **No shared mutable state** — agents that mutate shared state serialize; parallel agents only READ.
+
+A fan-out that fails any condition is serialized or gated by a merge-conflict check — that is the only valid reason to drop below the task-derived count.
+
+## Cost-dominance clause
+
+Token cost of sub-agent invocation never justifies under-fan-out. Cost governs HOW MUCH context each sub-agent receives (the P7 static-first prompt frame); it does not govern WHETHER to spawn the sub-agent at all. P8 dominates P7: when an edit would compress fan-out to save tokens, reject it. When in doubt, fan out. Reviewability is a separate, non-cost axis: it governs the SHAPE of the fan-out tree (flat vs two-level per Hierarchical delegation), never WHETHER to spawn — so reviewability never serializes independent work either.
+
+## Required output field
+
+Delegating artifacts (orchestrator commands, fan-out skills, delegating agents) emit a first-class output field:
+
+```
+sub_agents_spawned:
+  count: <integer>
+  rationale: <one-sentence task-decomposition justification>
+```
+
+Omitting the field on a delegating artifact is a P8 B2 violation (D07 fan-out-discipline audit). The `rationale` states the decomposition basis (module count, specialist-gate count, research-question count) so a reviewer can check the count against the task without re-deriving it.
+
+## Static intent vs runtime attestation
+
+The `sub_agents_spawned` frontmatter field declares fan-out intent at config time; it does not prove the orchestrator delegated at run time. The pair is closed by the End-of-Turn Delegation Attestation (`rules/hatch3r-agent-orchestration.md` → End-of-Turn Delegation Attestation): the per-file `delegation_proof_id` returned by the implementer or fixer sub-agent is forgery-resistant, because an orchestrator that skipped delegation has no token to quote. Static frontmatter declares; the runtime block verifies.
+
+## Scope
+
+Binds every hatch3r-invoked workflow that delegates via the Task tool in the end-user repo — every `commands/hatch3r-*.md` with `orchestrator: true`, every delegating `agents/hatch3r-*.md`, and every fan-out `skills/hatch3r-*/SKILL.md`. Tier 1 reference-card skills that neither spawn sub-agents nor mutate files carry no fan-out obligation; they state `Tier 1 reference card — no fan-out` instead.
+
+How each class emits the field differs because the count is known at a different time:
+
+- **Commands** declare it as a static frontmatter key — a command's fan-out is fixed by its `agentPipeline`, so `sub_agents_spawned: {count, rationale}` is a config-time value. `scripts/validate-fanout-emission.ts` enforces the key on every `orchestrator: true` command (CI gate `npm run validate:efficiency`).
+- **Skills** carry the runtime-emission directive in the body — a skill's count is task-derived (Tier 1 inline / Tier 2 per-concern / Tier 3 per-module), so a static integer would misstate it. A skill whose body holds a Tier-2/3 Task-tool delegation contract MUST state `` Emit `sub_agents_spawned: { count, rationale }` in your output. ``; the same validator flags `P8-FANOUT-SKILL-MISS` on a delegating, non-exempt skill that omits it.
+- **Agents** are prose-bound: their delegation is inherited from `rules/hatch3r-agent-orchestration.md` and they carry no `orchestrator` frontmatter marker, so no separate validator trigger applies; the worker agents that mention the Task tool delegate on behalf of a parent orchestrator, not as a fan-out root.
+
+## References
+
+- Pillar P8 B2 (source directive; see `agents/shared/principles.md`).
+- `rules/hatch3r-agent-orchestration.md` → Parallel Safety, Scaling Heuristic, Cost-Dominance Principle, End-of-Turn Delegation Attestation (mechanics this rule references).
+- The orchestration audit domain audits the B2 contract per cycle.
+- Anthropic, "Multi-agent orchestration" (Managed Agents) — `https://platform.claude.com/docs/en/managed-agents/multi-agent` (accessed 2026-05-26, official-docs): a lead agent decomposes a job and delegates pieces to specialist sub-agents working in parallel over a shared file system, up to ~10 simultaneous — the lead-agent ceiling that anchors the ~8 flat-vs-hierarchical threshold above; beyond it a lead agent itself acts as a sub-orchestrator over its own workers.
+- Augment Code, "Multi-Agent Orchestration Architecture Guide" — `https://www.augmentcode.com/guides/multi-agent-orchestration-architecture-guide` (accessed 2026-05-26, independent-analysis): structured context objects pass only relevant fields per worker; graph-based message passing structures communication along declared dependency edges.

package/dist/content/rules/hatch3r-fan-out-discipline.mdc

@@ -0,0 +1,91 @@
+---
+id: hatch3r-fan-out-discipline
+type: rule
+description: "P8 B2 floor: sub-agent fan-out scales with task size; serialization is valid only on dependency edges; token cost never justifies under-fan-out. Delegating artifacts emit sub-agent count + rationale as a first-class output field."
+tags: [orchestration, floor:protocol]
+alwaysApply: true
+precedence: high
+quality_charter: agents/shared/quality-charter.md
+cache_friendly: true
+---
+# hatch3r Fan-out Discipline
+
+**Pillars:** P8 (Clarification & Fan-out Discipline)
+
+Canonical reference for the *mechanics* of parallel dispatch: `rules/hatch3r-agent-orchestration.md` → Parallel Safety. This rule is the corpus-wide, always-on floor that every adapter ships to the end-user repo, so the B2 directive binds runtime agents directly and not only by inheritance through the orchestration rule.
+
+## B2 directive (verbatim)
+
+> Sub-agent fan-out scales with task size; serialization is only valid on dependency edges. Token cost is never a valid reason to serialize independent work. Delegating artifacts emit sub-agent count + rationale as a first-class output field.
+
+## Scaling heuristic
+
+Sub-agent count tracks task decomposition, not a fixed cap:
+
+- N independent modules → N parallel Phase-2 implementers.
+- M specialist gates → M parallel Phase-4 specialists.
+- K independent research questions → K parallel researcher modes.
+
+When work is independent under the three parallel-safety conditions below, fan out. Only a true dependency edge — where stage B consumes stage A's output — justifies serialization.
+
+The count derived above sets WHETHER to spawn each sub-agent. Past roughly 8 concurrent sub-agents, the count also sets the SHAPE: a single orchestrator that integrates 11–15 concurrent results in one context becomes the reviewability bottleneck. At that width, keep the full task-derived count but split it across a two-level tree (see Hierarchical delegation) rather than collapsing it to a narrower flat fan-out — collapsing the count to ease integration is the P8 violation the cost-dominance clause already forbids.
+
+## Hierarchical delegation
+
+The flat model — one orchestrator fans out to N workers and integrates all N results itself — is the default and is correct up to roughly 8 concurrent sub-agents (the empirical lead-agent ceiling cited in References, and the `max_phase4_parallel` default in `rules/hatch3r-agent-orchestration.md`). Beyond that width, prefer a two-level tree over a flat 11–15-wide fan-out:
+
+- The root orchestrator decomposes the task into ≤8 disjoint groups and spawns one sub-orchestrator per group.
+- Each sub-orchestrator fans out to its group's workers, integrates that group's results, and returns a single group-level summary.
+- The root integrates ≤8 group summaries — not 11–15 raw worker results — so per-context integration load stays inside the reviewability ceiling at every level.
+
+This preserves the task-derived total fan-out (no work is serialized): the same N workers still run concurrently, redistributed across sub-orchestrators. The grouping boundary MUST honor the three parallel-safety conditions both within a group and across groups, so a two-level tree carries no extra merge risk over the equivalent flat fan-out. High-fan-out commands are the trigger case — `commands/hatch3r-workflow.md` (`count: 15`) and the batch-mode `commands/hatch3r-board-fill.md` / `commands/hatch3r-board-pickup.md` (`count: 11` × issue count) otherwise concentrate every result on one orchestrator context.
+
+Cost-dominance and reviewability govern different axes and never trade against each other: cost-dominance governs WHETHER to spawn a sub-agent (always spawn when work is independent; token cost never serializes it), reviewability governs the SHAPE of the resulting tree (flat ≤8, two-level beyond). Neither axis ever justifies dropping the task-derived count.
+
+## Three parallel-safety conditions
+
+Fan out only when ALL three hold (per `rules/hatch3r-agent-orchestration.md` → Three Conditions to Parallelize):
+
+1. **Read-only or disjoint writes** — no two sub-agents write the same file or region.
+2. **Deterministic aggregation** — outputs merge without orchestrator intervention (tests pass-if-all-pass; findings union).
+3. **No shared mutable state** — agents that mutate shared state serialize; parallel agents only READ.
+
+A fan-out that fails any condition is serialized or gated by a merge-conflict check — that is the only valid reason to drop below the task-derived count.
+
+## Cost-dominance clause
+
+Token cost of sub-agent invocation never justifies under-fan-out. Cost governs HOW MUCH context each sub-agent receives (the P7 static-first prompt frame); it does not govern WHETHER to spawn the sub-agent at all. P8 dominates P7: when an edit would compress fan-out to save tokens, reject it. When in doubt, fan out. Reviewability is a separate, non-cost axis: it governs the SHAPE of the fan-out tree (flat vs two-level per Hierarchical delegation), never WHETHER to spawn — so reviewability never serializes independent work either.
+
+## Required output field
+
+Delegating artifacts (orchestrator commands, fan-out skills, delegating agents) emit a first-class output field:
+
+```
+sub_agents_spawned:
+  count: <integer>
+  rationale: <one-sentence task-decomposition justification>
+```
+
+Omitting the field on a delegating artifact is a P8 B2 violation (D07 fan-out-discipline audit). The `rationale` states the decomposition basis (module count, specialist-gate count, research-question count) so a reviewer can check the count against the task without re-deriving it.
+
+## Static intent vs runtime attestation
+
+The `sub_agents_spawned` frontmatter field declares fan-out intent at config time; it does not prove the orchestrator delegated at run time. The pair is closed by the End-of-Turn Delegation Attestation (`rules/hatch3r-agent-orchestration.md` → End-of-Turn Delegation Attestation): the per-file `delegation_proof_id` returned by the implementer or fixer sub-agent is forgery-resistant, because an orchestrator that skipped delegation has no token to quote. Static frontmatter declares; the runtime block verifies.
+
+## Scope
+
+Binds every hatch3r-invoked workflow that delegates via the Task tool in the end-user repo — every `commands/hatch3r-*.md` with `orchestrator: true`, every delegating `agents/hatch3r-*.md`, and every fan-out `skills/hatch3r-*/SKILL.md`. Tier 1 reference-card skills that neither spawn sub-agents nor mutate files carry no fan-out obligation; they state `Tier 1 reference card — no fan-out` instead.
+
+How each class emits the field differs because the count is known at a different time:
+
+- **Commands** declare it as a static frontmatter key — a command's fan-out is fixed by its `agentPipeline`, so `sub_agents_spawned: {count, rationale}` is a config-time value. `scripts/validate-fanout-emission.ts` enforces the key on every `orchestrator: true` command (CI gate `npm run validate:efficiency`).
+- **Skills** carry the runtime-emission directive in the body — a skill's count is task-derived (Tier 1 inline / Tier 2 per-concern / Tier 3 per-module), so a static integer would misstate it. A skill whose body holds a Tier-2/3 Task-tool delegation contract MUST state `` Emit `sub_agents_spawned: { count, rationale }` in your output. ``; the same validator flags `P8-FANOUT-SKILL-MISS` on a delegating, non-exempt skill that omits it.
+- **Agents** are prose-bound: their delegation is inherited from `rules/hatch3r-agent-orchestration.md` and they carry no `orchestrator` frontmatter marker, so no separate validator trigger applies; the worker agents that mention the Task tool delegate on behalf of a parent orchestrator, not as a fan-out root.
+
+## References
+
+- Pillar P8 B2 (source directive; see `agents/shared/principles.md`).
+- `rules/hatch3r-agent-orchestration.md` → Parallel Safety, Scaling Heuristic, Cost-Dominance Principle, End-of-Turn Delegation Attestation (mechanics this rule references).
+- The orchestration audit domain audits the B2 contract per cycle.
+- Anthropic, "Multi-agent orchestration" (Managed Agents) — `https://platform.claude.com/docs/en/managed-agents/multi-agent` (accessed 2026-05-26, official-docs): a lead agent decomposes a job and delegates pieces to specialist sub-agents working in parallel over a shared file system, up to ~10 simultaneous — the lead-agent ceiling that anchors the ~8 flat-vs-hierarchical threshold above; beyond it a lead agent itself acts as a sub-orchestrator over its own workers.
+- Augment Code, "Multi-Agent Orchestration Architecture Guide" — `https://www.augmentcode.com/guides/multi-agent-orchestration-architecture-guide` (accessed 2026-05-26, independent-analysis): structured context objects pass only relevant fields per worker; graph-based message passing structures communication along declared dependency edges.

package/dist/content/rules/hatch3r-feature-flags.md

@@ -10,6 +10,8 @@ cache_friendly: true
 ---
 # Feature Flags
 
+**Pillars:** P2 (Scientific & Practical Quality), CQ9 (Enhancability Quality)
+
 - Use flags for gradual rollout of user-facing changes. Not for A/B experiments without tracking.
 - Naming: `FF_{AREA}_{FEATURE}` (e.g., `FF_PET_NEW_CELEBRATION`).
 - Store flags in remote config or user document in your backend.

package/dist/content/rules/hatch3r-feature-flags.mdc

@@ -5,6 +5,8 @@ alwaysApply: false
 ---
 # Feature Flags
 
+**Pillars:** P2 (Scientific & Practical Quality), CQ9 (Enhancability Quality)
+
 - Use flags for gradual rollout of user-facing changes. Not for A/B experiments without tracking.
 - Naming: `FF_{AREA}_{FEATURE}` (e.g., `FF_PET_NEW_CELEBRATION`).
 - Store flags in remote config or user document in your backend.