hatch3r 1.8.0 → 2.0.0

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/{rules → dist/content/rules}/hatch3r-event-schema-evolution.md

@@ -2,8 +2,10 @@
 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
 cache_friendly: true
 ---

package/{rules → dist/content/rules}/hatch3r-event-schema-evolution.mdc

@@ -2,6 +2,7 @@
 description: Event and message schema evolution patterns for Kafka / Kinesis / Pub-Sub / event store — backward + forward + full compatibility modes, schema registry, consumer-side defaults
 globs: ["**/events/**", "**/schemas/**", "**/*.avsc", "**/*.proto", "**/messaging/**", "**/kafka/**", "**/pubsub/**"]
 alwaysApply: false
+precedence: high
 ---
 # Event Schema Evolution
 

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/{rules → 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/{rules → 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.

package/dist/content/rules/hatch3r-flutter-patterns.md

@@ -0,0 +1,88 @@
+---
+id: hatch3r-flutter-patterns
+type: rule
+description: Flutter and Dart conventions covering null safety, state management (Riverpod/Bloc), Material 3, FFI, performance, platform channels, and integration testing
+scope: conditional
+globs: "**/*.dart,**/pubspec.yaml,**/pubspec.lock,**/analysis_options.yaml,**/build.yaml,**/lib/**,**/test/**,**/integration_test/**,**/ios/Runner/**,**/android/app/**,**/windows/runner/**,**/macos/Runner/**,**/linux/**,**/web/index.html"
+tags: [implementation]
+quality_charter: agents/shared/quality-charter.md
+cache_friendly: true
+---
+# Flutter Patterns
+
+**Pillars:** P2 (Scientific & Practical Quality), CQ8 (Maintainability Quality)
+
+> Applies when the project ships a Flutter app or Dart package. Detection signals: `pubspec.yaml` with `flutter:` block, `lib/main.dart` entrypoint, or `pubspec.yaml` at repo root.
+
+## Dart Language Floor
+
+- Use Dart 3.5+ with sound null safety. Every nullable field is explicit (`String?`), every late variable initialized before access. No `!` (bang operator) outside of test fixtures or proven-non-null hot paths.
+- Records and patterns: prefer records (`(int, String)`) and pattern matching (`switch (value) { ... }`) over tuple classes and visitor patterns for simple variant returns.
+- Sealed classes for closed-set hierarchies (state, events, errors): `sealed class AuthState { ... }` + `final class Authenticated extends AuthState { ... }` so the analyzer enforces exhaustive switches.
+- Enable strict analyzer mode in `analysis_options.yaml` with `flutter_lints` plus `very_good_analysis`. Treat warnings as errors in CI.
+
+## Project Structure
+
+- Feature-first layout under `lib/`: `lib/features/<feature>/{data,domain,presentation}/` with a `lib/core/` for shared utilities. Avoid `lib/widgets/` / `lib/screens/` flat layouts beyond toy apps.
+- Single entrypoint per flavor: `lib/main_dev.dart`, `lib/main_staging.dart`, `lib/main_prod.dart`. Each delegates to a shared `lib/bootstrap.dart` after environment binding.
+- Public APIs documented with `///` doc comments. `dartdoc` runs in CI for the `lib/` public surface — undocumented public APIs are a warning.
+
+## State Management
+
+- Pick ONE state-management approach per app and document it in `docs/architecture.md`:
+  - **Riverpod 2.x** (`flutter_riverpod` + `riverpod_generator`) — recommended default. Code-gen typed providers via `@riverpod` annotations.
+  - **Bloc** (`flutter_bloc`) — when the team prefers event-sourcing semantics.
+  - **InheritedNotifier / ChangeNotifier** — only for trivial widget-local state. Provider package is in maintenance — do not adopt for new code.
+- Riverpod: prefer `@riverpod`-generated providers over manual `Provider`/`StateProvider`. Async providers return `AsyncValue<T>` — surface `loading` / `error` / `data` states in the UI.
+- Bloc: separate events (input) from states (output). Avoid `setState` inside `BlocBuilder` — all mutation flows via `add(event)` to the bloc.
+- Never call `notifyListeners()` inside `build()`. Never read providers in a constructor.
+
+## UI & Material 3
+
+- Material 3 (Material You) is the default for Android-leaning apps: `ThemeData(useMaterial3: true)`. Configure `colorSchemeSeed` rather than ad-hoc primary/accent colors so dynamic color works.
+- For iOS-leaning apps, use Cupertino widgets directly or `flutter_platform_widgets` for hybrid surfaces. Do not use `Material` on a `CupertinoPageScaffold`.
+- Responsive layout: use `LayoutBuilder`, `MediaQuery.sizeOf(context)`, and `Flexible`/`Expanded` for breakpoints. Avoid hard-coded pixel widths.
+- Accessibility: every interactive widget has a `Semantics(label: ...)` wrapper or uses a built-in widget that emits semantics. Test with TalkBack (Android) and VoiceOver (iOS); the `flutter_test` semantics tester catches static violations.
+
+## Performance
+
+- Avoid expensive work in `build()`. Lift `MaterialPageRoute` factories, regex literals, and constant widgets to `const` constructors so Flutter can skip the rebuild.
+- Use `const` constructors aggressively — `const SizedBox(height: 8)` is allocation-free and a major frame-budget win.
+- For long scrollable lists, use `ListView.builder` with `itemExtent` set when row height is uniform. `ListView()` (default) builds every child up-front.
+- Image loading: `cached_network_image` or `flutter_image_compress` for network images. The default `Image.network` does not persist a disk cache.
+- Profile with DevTools: target 60fps on mid-range Android (Pixel 4a class). Frame times above 16ms are regressions; profile the Timeline view for jank.
+
+## Platform Channels & FFI
+
+- Native interop: prefer `dart:ffi` for synchronous C/C++ bindings (≥10x faster than channels). Use platform channels only when the API is event-driven or requires UI-thread context.
+- `package:ffigen` generates Dart bindings from C headers — never hand-roll `Pointer<Native...>` signatures.
+- Pigeon (`package:pigeon`) generates type-safe platform-channel code from a Dart interface declaration. Stop writing raw `MethodChannel` calls — Pigeon-generated code prevents schema drift.
+
+## Testing
+
+- Three test layers in `test/` (unit + widget) and `integration_test/` (full app on real device or emulator):
+  - Unit tests: pure Dart logic, no Flutter binding. Run with `flutter test`.
+  - Widget tests: pumped `WidgetTester` flows with mocked dependencies. Use `find.byKey` over `find.text` for resilience to copy changes.
+  - Integration tests: `integration_test/` with `IntegrationTestWidgetsFlutterBinding`. Run on devices via `flutter drive` and on CI matrices.
+- Coverage: `flutter test --coverage` + `lcov` reports. Floor: 80% line coverage in `lib/features/**`; critical features (auth, payments) 90%.
+- Golden tests for visual regressions: `goldenFileComparator` with the `alchemist` package for multi-platform/multi-device goldens. Update goldens via PR review, never blanket-update.
+- Mock HTTP: `package:http_mock_adapter` for Dio, `nock` for `package:http`. Never hit real network in tests.
+
+## Builds & Distribution
+
+- Flavors via `--flavor` flag + matching Android/iOS configs (`android/app/build.gradle` flavors, `ios/Runner/Configurations`). Bake the API base URL per flavor.
+- App size: enable `--obfuscate --split-debug-info=<path>` for release builds. Track size regressions via `flutter build apk --analyze-size` in CI.
+- Use Codemagic, Bitrise, or Fastlane for store deploys. Sign Android with Play App Signing; iOS via App Store Connect API keys (avoid Apple ID password auth — deprecated).
+
+## References
+
+- Dart 3 release notes: https://dart.dev/guides/whats-new (accessed 2026-05-27, official-docs)
+- Flutter Material 3: https://docs.flutter.dev/ui/design/material (accessed 2026-05-27, official-docs)
+- Riverpod 2.x: https://riverpod.dev/docs/introduction/getting_started (accessed 2026-05-27, official-docs)
+- Pigeon: https://pub.dev/packages/pigeon (accessed 2026-05-27, official-docs)
+
+## Cross-References
+
+- `rules/hatch3r-component-conventions.md` — four-state surface contract maps to Flutter `AsyncValue` patterns.
+- `rules/hatch3r-testing.md` — coverage thresholds and determinism rules apply to Dart tests.
+- `rules/hatch3r-accessibility-standards.md` — WCAG mapping for `Semantics` widget usage.