hatch3r 1.7.0 → 1.7.5

package/rules/hatch3r-dependency-management.mdc

@@ -26,3 +26,75 @@ alwaysApply: false
 - Review changelogs and migration guides before upgrading major versions. Never blindly bump major versions and assume backward compatibility.
 - Run the full test suite after any dependency upgrade, including integration tests. A passing unit test suite does not guarantee compatibility with upgraded peer dependencies.
 - When upgrading a shared dependency used across multiple modules, upgrade all consumers in the same PR to avoid version skew within the monorepo or project.
+
+## npm Trusted Publishing (OIDC)
+
+For libraries published to npm, configure an npm Trusted Publisher with GitHub OIDC. The publishing workflow exchanges a per-run JWT for short-lived publish credentials — no long-lived `NPM_TOKEN` in secrets. Provenance attestations are auto-generated and signed by Sigstore Fulcio with the inclusion record in Rekor.
+
+- Requirements: npm CLI >=11.5.1, Node >=22.14.0, `repository` field set in `package.json` (provenance validation fails without it).
+- Workflow grants `id-token: write` permission at the job level.
+- Remove `NPM_TOKEN` from repository and organization secrets after migrating to trusted publishing.
+- PyPI, crates.io, and RubyGems offer equivalent OIDC trusted publishing — migrate at least one ecosystem per release pipeline.
+
+## Provenance Flag for Non-Trusted Publishing
+
+When trusted publishing is not yet enabled, publish with `npm publish --provenance`. The flag activates Sigstore-signed provenance even with token auth.
+
+- Verify provenance: `npm view <pkg> --json | jq .dist.attestations` returns Sigstore attestation URLs; the npm package page renders a Provenance section.
+- Consumers verify on install: `npm audit signatures` walks the attestation chain and confirms Rekor inclusion.
+
+## SBOM Generation
+
+Every release artifact ships a CycloneDX 1.6 or SPDX 3.0.1 SBOM, committed as a release asset and signed with the same Sigstore identity that signed the artifact. CycloneDX 1.6 is ECMA-424 ratified and broadly supported (Syft, Trivy, cdxgen, GitLab native). SPDX 3.0.1 is the BSI TR-03183-2 / EU CRA baseline.
+
+- Tooling baseline: `npm sbom --sbom-format=cyclonedx` (npm 10+), `cdxgen` (broad ecosystem coverage including Python, Java, Rust, Go), `syft` (containers + source repos).
+- CI step generates SBOM on every release tag and uploads as a release asset.
+- PR-time SBOM diff (`cyclonedx-cli diff` or `syft diff`) blocks PRs that introduce unexpected new transitive dependencies; reviewer approves the diff alongside the source diff.
+
+## SLSA v1.0 / v1.1 Build Provenance
+
+Target SLSA Build L3 for production release artifacts: ephemeral hosted runner, isolated builder identity, signed in-toto provenance, transparency log inclusion. SLSA v1.1 (April 2025) is incremental on the Build track — v1.0 L3 artifacts also meet v1.1 L3.
+
+- GitHub Actions implementation: `slsa-framework/slsa-github-generator` (language-agnostic generators for npm, container, generic artifact).
+- Deploy-time verification: `slsa-verifier` CLI confirms provenance, builder identity allow-list, and source-repo match before the artifact is consumed.
+- Pin the generator action to a 40-char commit SHA per the action-pinning policy below.
+
+## Malicious-Package Detection Beyond `npm audit`
+
+`npm audit` only flags published CVEs. The 2025-2026 incident class — Shai-Hulud (Sep-Nov 2025), Axios 1.14.1 maintainer hijack (Mar 2026), Mini-Shai-Hulud (May 2026), DevTap typosquat (Apr-May 2026) — never reaches a CVE filing. Layer install-time behavioral detection on top of `npm audit`:
+
+- Pre-install behavioral scan: `socket.dev`, `snyk`, or `osv-scanner` against the lockfile in CI. `npq` adds a pre-install gate at the developer workstation.
+- pnpm `minimumReleaseAge: 72` (3 days, raise to 7 for high-trust projects) blocks consumption of brand-new versions until the typosquat / maintainer-hijack window closes.
+- Disable lifecycle scripts in CI: `.npmrc` sets `ignore-scripts=true`; pnpm uses `strictDepBuilds: true` plus `allowBuilds: [explicit-list]`.
+- GitHub `dependency-review-action` on every PR blocks new dependencies with known advisories or disallowed licenses.
+
+## Lockfile Policy
+
+- Lockfile committed to the repository: `package-lock.json`, `yarn.lock`, or `pnpm-lock.yaml`. Multi-language repos commit the per-ecosystem lockfile (`Cargo.lock`, `poetry.lock`, `go.sum`, `Gemfile.lock`).
+- CI installs from the lockfile only: `npm ci`, `yarn install --frozen-lockfile`, `pnpm install --frozen-lockfile`, `cargo build --locked`. Drift fails the build.
+- `lockfile-lint` enforces registry allow-list and integrity-hash presence on every entry. Run in CI alongside install.
+- Lockfile diffs receive the same review scrutiny as source diffs — reviewers inspect new transitive entries and version jumps.
+- Renovate or Dependabot configured with grouped weekly updates: one PR per ecosystem per week for non-security updates; security updates open immediately.
+
+## License Compliance
+
+- Allow-list (default): MIT, Apache-2.0, ISC, BSD-2-Clause, BSD-3-Clause, MPL-2.0, CC0-1.0. Project policy may extend.
+- Deny-list (default): GPL-2.0, GPL-3.0, AGPL-3.0, AGPL-3.0-or-later, SSPL-1.0, Commons Clause. AGPL triggers copyleft on network use — it is the SaaS landmine.
+- Override requires documented business justification in the PR description plus security/legal sign-off.
+- CI gate per ecosystem: `license-checker --onlyAllow "MIT;Apache-2.0;ISC;BSD-2-Clause;BSD-3-Clause;MPL-2.0;CC0-1.0"` (Node), `pip-licenses --allow-only` (Python), `cargo-license` (Rust). CI fails on detection of a denied license in direct or transitive deps.
+
+## Pinned GitHub Action SHAs
+
+Every action `uses:` line references a 40-character commit SHA, never a tag (`@v3`, `@main`, `@v44.5.1`). Tags are mutable; SHAs are not.
+
+- CVE-2025-30066 (tj-actions/changed-files, March 2025) compromised 23,000+ repositories — the attacker mutated existing version tags to point to a malicious commit that dumped secrets to workflow logs. Root cause: compromised PAT on `reviewdog/action-setup` (CVE-2025-30154). Tag pinning would not have prevented this; SHA pinning would have.
+- Annotate the SHA with the version: `uses: actions/checkout@<40-char-sha> # v4.2.2`.
+- Dependabot configured with `package-ecosystem: github-actions` updates SHAs while preserving the version comment. Renovate equivalent: `pinDigests: true`.
+- CI rejects PRs that introduce tag references via a linter step (e.g., `pinact` or a custom regex check).
+
+## OSV.dev and GHSA Feeds
+
+- `osv-scanner` runs on every PR and nightly against the lockfile. OSV.dev (Google) is the polyglot 2026 aggregator: npm, PyPI, crates.io, Maven, Go modules, RubyGems, Packagist, NuGet — single schema across all.
+- GitHub Security Advisories (GHSA) remain the npm-ecosystem authoritative feed; `npm audit` and OSV both consume GHSA.
+- NVD provides CPE-keyed CVE records for OS and language-stdlib vulnerabilities.
+- Renovate `vulnerabilityAlerts: { enabled: true }` plus `osvVulnerabilityAlerts: true` produce auto-PRs that force-update to fixed versions and bypass the normal cooldown for security fixes. Pair with auto-merge for patch-level fixes when tests pass.

package/rules/hatch3r-design-system-detection.md

@@ -0,0 +1,142 @@
+---
+id: hatch3r-design-system-detection
+type: rule
+description: Mandatory detection of existing design tokens, theme primitives, and component library before AI agents author new UI components
+scope: "**/*.vue,**/*.jsx,**/*.tsx,**/*.svelte,**/*.css,**/*.scss,**/components/**,**/tokens*,**/theme*,**/design-system/**,**/tailwind*"
+tags: [ui, design-system, frontend]
+quality_charter: agents/shared/quality-charter.md
+cache_friendly: true
+---
+# Design System Detection
+
+## Reuse-Before-Author Principle
+
+Existing tokens beat extended tokens beat new tokens. Before authoring any UI primitive, an agent must detect whether tokens, themes, or component libraries already exist in the project and reuse them. Skipping detection is a regression: it produces duplicate primitives, drift in semantic naming, and visual inconsistency with shipped UI.
+
+## Detection Routine (5 Steps, Ordered)
+
+Run these five steps in order before authoring any UI artifact. Record each finding in the implementation plan or PR description.
+
+### Step 1 — Scan `package.json` for design-system signals
+
+Grep dependencies and `devDependencies` for: `@radix-ui/*`, `@shadcn/ui` references in `components.json`, `tailwindcss` (record the major version), `@chakra-ui/*`, `@mui/*` (Material), `bootstrap`, `headlessui`, `@ariakit/*`, `@reach/*`. Each signal pins the headless or styled library the project already commits to.
+
+```
+jq '.dependencies + .devDependencies | keys[]' package.json | grep -E '(radix|shadcn|tailwind|chakra|mui|bootstrap|headlessui|ariakit|reach)'
+```
+
+### Step 2 — Locate the token source
+
+Search in this exact order — the first hit wins:
+
+1. `tokens.json` at repo root or under `design-system/` — DTCG 2025.10 format
+2. `src/styles/tokens.css` or `app/styles/tokens.css` — CSS custom properties
+3. Tailwind v4 `@theme` block inside `app.css`, `globals.css`, or `src/styles/main.css`
+4. `tailwind.config.{js,ts,mjs}` `theme.extend` — Tailwind v3 fallback
+5. `figma.tokens.json` — Tokens Studio export, transformed downstream
+
+```
+fd -e json -e css 'tokens|theme' . && rg '^\s*@theme\b' --type css
+```
+
+### Step 3 — Map the component library
+
+Look for these markers, in order:
+
+- `components.json` — shadcn CLI registry config; records the components directory and registry URLs
+- `src/components/ui/*` — shadcn convention
+- `src/components/primitives/*` — generic primitives directory
+- `app/components/*` — Nuxt/Vue convention
+- `packages/ui/src/*` — monorepo shared package
+
+Record the directory, the import pattern (`@/components/ui/button` etc.), and whether components wrap a headless library or hand-roll DOM.
+
+### Step 4 — Identify the color space
+
+Inspect token values:
+
+- OKLCH (`oklch(0.7 0.15 250)`) — preferred 2026 default for shadcn v4 and Tailwind v4
+- Display-P3 (`color(display-p3 1 0.5 0)`) — wide-gamut explicit
+- sRGB hex (`#3b82f6`) — legacy; flag for migration when adding tokens
+
+Document the convention. New tokens must match the existing color space — mixed-space palettes produce inconsistent blending in `color-mix()`.
+
+### Step 5 — Record findings
+
+Add a short section to the implementation plan or PR description listing: token source path, component library directory, headless library (Radix/Ariakit/Headless UI/none), color space, breakpoint strategy (container queries via `@container` or media queries via `@media`).
+
+## DTCG Token Format (2025.10)
+
+When emitting or proposing new tokens, conform to the W3C Design Tokens Community Group format. Required fields per token: `$value`, `$type` (one of `color`, `dimension`, `fontFamily`, `fontWeight`, `duration`, `cubicBezier`, `number`). Optional: `$description`. Alias another token via `{group.token}` reference syntax. Transform pipelines: Style Dictionary 4.x or Tokens Studio. Source: `design-tokens.github.io/community-group`.
+
+```json
+{
+  "color": {
+    "primary": { "$value": "oklch(0.7 0.15 250)", "$type": "color" },
+    "brand":   { "$value": "{color.primary}",     "$type": "color" }
+  }
+}
+```
+
+## shadcn Baseline (2026)
+
+When scaffolding React UI in a project without a component library:
+
+- `npx shadcn@latest init` — initialize `components.json`, base tokens, and `cn()` util
+- `npx shadcn@latest add <component> --dry-run` — inspect the diff before writing
+- Pull from namespaced registries (`@my-org/...`) for org-specific components
+- Never fork primitives into local copies; extend via composition
+
+## Tailwind v4 CSS-First
+
+For new projects targeting Tailwind v4: configure entirely via the `@theme` block in CSS. Do not generate `tailwind.config.js` — that is the v3 model. v4 defaults to OKLCH color space; use `color-mix(in oklch, ...)` for tints, shades, and surface elevations.
+
+```css
+@import "tailwindcss";
+@theme {
+  --color-primary: oklch(0.7 0.15 250);
+  --color-primary-hover: color-mix(in oklch, var(--color-primary) 90%, black);
+}
+```
+
+## Radix Primitives + WAI-ARIA APG
+
+Never hand-roll focus traps, ARIA roles, roving tabindex, or keyboard navigation for: menu, dialog, popover, tabs, select, combobox, listbox, dropdown, tooltip, accordion. Compose Radix Primitives, Ariakit, or React Aria, and verify behavior against the WAI-ARIA Authoring Practices Guide (`w3.org/WAI/ARIA/apg/`). Hand-rolled implementations of these patterns are rejected.
+
+## Modern CSS Over JS (Interop 2026 Baseline)
+
+Prefer the native CSS or HTML feature over a JS equivalent whenever the Interop 2026 baseline includes it:
+
+- `:has()` selector — replaces JS-based parent-state classes
+- Container queries (`@container`) — replaces `@media` for component-scoped breakpoints
+- View Transitions API — replaces Framer Motion route transitions
+- Native `<dialog>` + Popover API (`popover` attribute) — replaces Headless UI modals for non-trapping cases
+- CSS anchor positioning — replaces Floating UI for menus and tooltips
+- Cascade layers (`@layer`) — replaces specificity hacks
+- `color-mix()` — replaces JS color manipulation libs
+
+## Reuse > Extend > Create — Decision Tree
+
+| Situation | Action |
+|---|---|
+| Token exists with matching semantic name | Use directly |
+| Token exists with adjacent semantic | Alias new semantic to existing primitive |
+| No token, primitive exists in scale | Add semantic alias pointing at the existing primitive |
+| No primitive at all | Add primitive plus semantic alias; justify the new primitive in the PR |
+
+## Verification Before "Done"
+
+- Design-token adoption >= 95% in generated code — no hard-coded hex, rgb, or pixel values for colors and spacing
+- `npx shadcn@latest add <component> --diff` shows no unintentional local drift from the registry
+- Components imported from the primitives library; not duplicated inline
+- Color values in OKLCH where the existing token source uses OKLCH
+- New tokens conform to DTCG `$value`/`$type` shape and pass the project's Style Dictionary build
+
+## References
+
+- W3C Design Tokens Community Group spec: `design-tokens.github.io/community-group` (2025.10 working draft)
+- shadcn docs: `ui.shadcn.com`
+- Tailwind v4 docs: `tailwindcss.com/docs` (CSS-first `@theme` chapter)
+- Radix Primitives: `radix-ui.com/primitives`
+- WAI-ARIA Authoring Practices Guide: `w3.org/WAI/ARIA/apg/`
+- Interop 2026 dashboard: `wpt.fyi/interop-2026`

package/rules/hatch3r-design-system-detection.mdc

@@ -0,0 +1,138 @@
+---
+description: Mandatory detection of existing design tokens, theme primitives, and component library before AI agents author new UI components
+globs: ["**/*.vue", "**/*.jsx", "**/*.tsx", "**/*.svelte", "**/*.css", "**/*.scss", "**/components/**", "**/tokens*", "**/theme*", "**/design-system/**", "**/tailwind*"]
+alwaysApply: false
+---
+# Design System Detection
+
+## Reuse-Before-Author Principle
+
+Existing tokens beat extended tokens beat new tokens. Before authoring any UI primitive, an agent must detect whether tokens, themes, or component libraries already exist in the project and reuse them. Skipping detection is a regression: it produces duplicate primitives, drift in semantic naming, and visual inconsistency with shipped UI.
+
+## Detection Routine (5 Steps, Ordered)
+
+Run these five steps in order before authoring any UI artifact. Record each finding in the implementation plan or PR description.
+
+### Step 1 — Scan `package.json` for design-system signals
+
+Grep dependencies and `devDependencies` for: `@radix-ui/*`, `@shadcn/ui` references in `components.json`, `tailwindcss` (record the major version), `@chakra-ui/*`, `@mui/*` (Material), `bootstrap`, `headlessui`, `@ariakit/*`, `@reach/*`. Each signal pins the headless or styled library the project already commits to.
+
+```
+jq '.dependencies + .devDependencies | keys[]' package.json | grep -E '(radix|shadcn|tailwind|chakra|mui|bootstrap|headlessui|ariakit|reach)'
+```
+
+### Step 2 — Locate the token source
+
+Search in this exact order — the first hit wins:
+
+1. `tokens.json` at repo root or under `design-system/` — DTCG 2025.10 format
+2. `src/styles/tokens.css` or `app/styles/tokens.css` — CSS custom properties
+3. Tailwind v4 `@theme` block inside `app.css`, `globals.css`, or `src/styles/main.css`
+4. `tailwind.config.{js,ts,mjs}` `theme.extend` — Tailwind v3 fallback
+5. `figma.tokens.json` — Tokens Studio export, transformed downstream
+
+```
+fd -e json -e css 'tokens|theme' . && rg '^\s*@theme\b' --type css
+```
+
+### Step 3 — Map the component library
+
+Look for these markers, in order:
+
+- `components.json` — shadcn CLI registry config; records the components directory and registry URLs
+- `src/components/ui/*` — shadcn convention
+- `src/components/primitives/*` — generic primitives directory
+- `app/components/*` — Nuxt/Vue convention
+- `packages/ui/src/*` — monorepo shared package
+
+Record the directory, the import pattern (`@/components/ui/button` etc.), and whether components wrap a headless library or hand-roll DOM.
+
+### Step 4 — Identify the color space
+
+Inspect token values:
+
+- OKLCH (`oklch(0.7 0.15 250)`) — preferred 2026 default for shadcn v4 and Tailwind v4
+- Display-P3 (`color(display-p3 1 0.5 0)`) — wide-gamut explicit
+- sRGB hex (`#3b82f6`) — legacy; flag for migration when adding tokens
+
+Document the convention. New tokens must match the existing color space — mixed-space palettes produce inconsistent blending in `color-mix()`.
+
+### Step 5 — Record findings
+
+Add a short section to the implementation plan or PR description listing: token source path, component library directory, headless library (Radix/Ariakit/Headless UI/none), color space, breakpoint strategy (container queries via `@container` or media queries via `@media`).
+
+## DTCG Token Format (2025.10)
+
+When emitting or proposing new tokens, conform to the W3C Design Tokens Community Group format. Required fields per token: `$value`, `$type` (one of `color`, `dimension`, `fontFamily`, `fontWeight`, `duration`, `cubicBezier`, `number`). Optional: `$description`. Alias another token via `{group.token}` reference syntax. Transform pipelines: Style Dictionary 4.x or Tokens Studio. Source: `design-tokens.github.io/community-group`.
+
+```json
+{
+  "color": {
+    "primary": { "$value": "oklch(0.7 0.15 250)", "$type": "color" },
+    "brand":   { "$value": "{color.primary}",     "$type": "color" }
+  }
+}
+```
+
+## shadcn Baseline (2026)
+
+When scaffolding React UI in a project without a component library:
+
+- `npx shadcn@latest init` — initialize `components.json`, base tokens, and `cn()` util
+- `npx shadcn@latest add <component> --dry-run` — inspect the diff before writing
+- Pull from namespaced registries (`@my-org/...`) for org-specific components
+- Never fork primitives into local copies; extend via composition
+
+## Tailwind v4 CSS-First
+
+For new projects targeting Tailwind v4: configure entirely via the `@theme` block in CSS. Do not generate `tailwind.config.js` — that is the v3 model. v4 defaults to OKLCH color space; use `color-mix(in oklch, ...)` for tints, shades, and surface elevations.
+
+```css
+@import "tailwindcss";
+@theme {
+  --color-primary: oklch(0.7 0.15 250);
+  --color-primary-hover: color-mix(in oklch, var(--color-primary) 90%, black);
+}
+```
+
+## Radix Primitives + WAI-ARIA APG
+
+Never hand-roll focus traps, ARIA roles, roving tabindex, or keyboard navigation for: menu, dialog, popover, tabs, select, combobox, listbox, dropdown, tooltip, accordion. Compose Radix Primitives, Ariakit, or React Aria, and verify behavior against the WAI-ARIA Authoring Practices Guide (`w3.org/WAI/ARIA/apg/`). Hand-rolled implementations of these patterns are rejected.
+
+## Modern CSS Over JS (Interop 2026 Baseline)
+
+Prefer the native CSS or HTML feature over a JS equivalent whenever the Interop 2026 baseline includes it:
+
+- `:has()` selector — replaces JS-based parent-state classes
+- Container queries (`@container`) — replaces `@media` for component-scoped breakpoints
+- View Transitions API — replaces Framer Motion route transitions
+- Native `<dialog>` + Popover API (`popover` attribute) — replaces Headless UI modals for non-trapping cases
+- CSS anchor positioning — replaces Floating UI for menus and tooltips
+- Cascade layers (`@layer`) — replaces specificity hacks
+- `color-mix()` — replaces JS color manipulation libs
+
+## Reuse > Extend > Create — Decision Tree
+
+| Situation | Action |
+|---|---|
+| Token exists with matching semantic name | Use directly |
+| Token exists with adjacent semantic | Alias new semantic to existing primitive |
+| No token, primitive exists in scale | Add semantic alias pointing at the existing primitive |
+| No primitive at all | Add primitive plus semantic alias; justify the new primitive in the PR |
+
+## Verification Before "Done"
+
+- Design-token adoption >= 95% in generated code — no hard-coded hex, rgb, or pixel values for colors and spacing
+- `npx shadcn@latest add <component> --diff` shows no unintentional local drift from the registry
+- Components imported from the primitives library; not duplicated inline
+- Color values in OKLCH where the existing token source uses OKLCH
+- New tokens conform to DTCG `$value`/`$type` shape and pass the project's Style Dictionary build
+
+## References
+
+- W3C Design Tokens Community Group spec: `design-tokens.github.io/community-group` (2025.10 working draft)
+- shadcn docs: `ui.shadcn.com`
+- Tailwind v4 docs: `tailwindcss.com/docs` (CSS-first `@theme` chapter)
+- Radix Primitives: `radix-ui.com/primitives`
+- WAI-ARIA Authoring Practices Guide: `w3.org/WAI/ARIA/apg/`
+- Interop 2026 dashboard: `wpt.fyi/interop-2026`

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

@@ -0,0 +1,90 @@
+---
+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/**"
+tags: [implementation, devops]
+quality_charter: agents/shared/quality-charter.md
+cache_friendly: true
+---
+# Event Schema Evolution
+
+Schemas for events, messages, and stream records evolve independently of producer and consumer deploy order. Every change must declare an explicit compatibility mode and pass a registry compatibility check before merge.
+
+## Compatibility Modes
+
+A registry compatibility mode constrains the diff between adjacent schema versions. Pick the mode that matches the deploy-order guarantee available in the target system.
+
+- **`BACKWARD`** — a consumer using the new schema reads data written with the old schema. Allowed diffs: delete a field, add a field that has a default value. Deploy consumers first. Default for evolving consumer code.
+- **`FORWARD`** — a consumer using the old schema reads data written with the new schema. Allowed diffs: add a field, delete a field that had a default value. Deploy producers first. Default for evolving producer code.
+- **`FULL`** — both directions. Required when producer and consumer deploy order cannot be controlled (e.g., split across teams or platforms).
+- **`*_TRANSITIVE`** variants (BACKWARD_TRANSITIVE, FORWARD_TRANSITIVE, FULL_TRANSITIVE) — the constraint holds against every prior schema version, not just the immediately preceding one. Required when consumers may replay from offset zero or read a historical archive.
+- **`NONE`** — disables compatibility checking; breaking changes accepted. Permitted only on a dedicated `*-v2` subject during a planned migration window with a dated deprecation plan in the migration ticket.
+
+Default recommendation when in doubt: `BACKWARD_TRANSITIVE` — consumers can deploy first and replay from offset zero.
+
+## Schema Registry Mandate
+
+- Every event topic / stream / subscription has a registered schema in Confluent Schema Registry, Apicurio Registry, AWS Glue Schema Registry, or Karapace. No in-tree schema-only repos without a registry binding.
+- Subject naming strategy is declared per topic: `TopicNameStrategy` (one schema per topic — default), `RecordNameStrategy` (one schema per record type across topics), or `TopicRecordNameStrategy` (multiple record types per topic). Mixing strategies inside the same topic is forbidden.
+- Compatibility mode is set per subject in the registry and asserted in CI. Changing the mode requires a registry-admin role and a logged justification.
+- Schemas are versioned by the registry; the producer pins the schema ID it serialized with, and the consumer fetches by ID — never by name + "latest".
+
+## Avro Evolution Rules
+
+- Adding a field requires a `default` value to remain backward-compatible — a consumer using the new schema reads old data by substituting the default for the absent field.
+- Removing a field requires the field to have had a `default` value to remain forward-compatible — an old consumer reads new data and the missing field falls back to its declared default.
+- Use a union with `null` (e.g., `["null", "string"]` with `default: null`) to express an optional field. Place `null` first in the union so the default is unambiguously the null branch.
+- Never rename a field — add a new field and register an `aliases: ["old_name"]` entry on the new field so old data deserializes against the new schema.
+- Never change a field's type. To replace a type, add a new field of the new type, dual-write during the migration window, and remove the old field only after consumer migration completes.
+
+## Protobuf Evolution Rules
+
+- Use `proto3` for new schemas. Field numbers are immutable identifiers — never reuse a tag number, never renumber, never reorder by tag.
+- When removing a field, add a `reserved` clause for both the tag number and the field name so future authors cannot resurrect the removed field with a different type and produce silent data corruption.
+- Field type widening is constrained: int32 / uint32 / int64 / uint64 / bool are mutually wire-compatible; sint32 ↔ sint64 are compatible; fixed32 ↔ sfixed32 are compatible; `string` ↔ `bytes` are compatible when bytes are valid UTF-8. Other type changes are breaking.
+- Use `optional` (proto3 since 3.15) for clear presence semantics on scalar fields. Without `optional`, unset and default-valued fields are indistinguishable on the wire.
+- Never remove an enum value — mark it `[deprecated = true]` and leave it in place. Removing an enum value breaks consumers that have it pinned.
+- New message types are not forward-compatible — old producers/consumers do not know about them. Prefer `BACKWARD_TRANSITIVE` for protobuf subjects.
+
+## JSON Schema Evolution
+
+- Default policy: additive only. New optional properties may be added; required properties may not be added to an existing record type.
+- `additionalProperties: false` blocks forward compatibility (a consumer using the old strict schema rejects new fields). Choose explicitly: set `false` only when the consumer must reject unknown fields for security reasons; set `true` (or omit) to allow forward-compatible evolution.
+- Version the schema identifier with semver (e.g., `$id: "https://example.com/schemas/event/v1.3.0.json"`). Patch and minor bumps must be additive; major bumps signal an incompatible change and require a new subject.
+- For shared envelope shapes (e.g., CloudEvents), pin the envelope spec version and version only the `data` payload schema.
+
+## Consumer-Side Defaults and Tolerance
+
+- Every optional field deserializes to an explicit default value in consumer code (zero-value, `None`, empty string, empty list — declared, not implicit).
+- Consumers never panic, crash, or fail-stop on a missing field. Missing → default. Unknown field → log at `info`, increment `event.schema.unknown_field` counter, continue processing.
+- Emit `event.schema.version` and `event.subject` as attributes on every consumer-side trace span and metric label, so observability dashboards surface version distribution and detect stuck consumers on the old schema.
+- Consumers validate against the schema fetched by ID at deserialization time; never validate against a hard-coded in-process schema literal.
+
+## Dual-Publish During Migration
+
+- When the shape change exceeds what the registry compatibility mode permits, dual-publish: write the same logical event in both old and new shapes — either to two topics (`orders.v1`, `orders.v2`) or to one topic with a union schema discriminated by a `schema_version` field.
+- Keep dual-publish active until every consumer has been confirmed migrated to the new shape (poll consumer-group offsets against both topics; alert on lag on the new shape; alert on consumption from the old shape from any non-allowlisted consumer group).
+- Deprecate the old shape only after the consumer-migration confirmation report is logged in the migration ticket. Default deprecation window: 1 full release cycle plus 1 on-call rotation past zero consumption.
+
+## Outbox and Idempotency
+
+- Every event carries a unique `event_id`. Prefer UUIDv7 over UUIDv4 — UUIDv7 is time-sortable, which simplifies dedup and ordering checks.
+- Consumers deduplicate by `event_id` over a sliding window sized to the maximum reprocessing horizon (typically 24–72 hours).
+- Producers that write to a transactional database publish events via the transactional outbox pattern: append the event row to an `outbox` table in the same DB transaction as the business write; a separate relay process drains the outbox to the broker with at-least-once semantics. This avoids the dual-write inconsistency between DB and broker.
+- Every consumer is idempotent at the business-logic layer — receiving the same `event_id` twice produces the same end-state.
+
+## Verification
+
+- CI runs a registry compatibility check on every PR that touches a schema file: `confluent-schema-registry-maven-plugin` test-compatibility goal, the REST `/compatibility/subjects/<subject>/versions/latest` endpoint, or `buf breaking` for protobuf. PR fails on incompatible diff.
+- `buf breaking --against '.git#branch=main'` runs on every protobuf change to detect tag-reuse, type-narrowing, and enum-value removal.
+- Generated client code from schemas is regenerated and committed in the same PR as the schema change; CI fails on drift between schema and generated code.
+- A schema-evolution test fixture replays a representative set of historical messages against the new schema and asserts deserialization success.
+
+## References
+
+- Confluent Schema Registry — Schema Evolution and Compatibility: https://docs.confluent.io/platform/current/schema-registry/fundamentals/schema-evolution.html
+- Apache Avro Specification — Schema Resolution: https://avro.apache.org/docs/current/specification/#schema-resolution
+- Protocol Buffers Language Guide (proto3) — Updating a Message Type: https://protobuf.dev/programming-guides/proto3/#updating
+- `buf breaking` — protobuf breaking-change detector: https://buf.build/docs/breaking/overview
+- CloudEvents specification: https://github.com/cloudevents/spec

package/rules/hatch3r-event-schema-evolution.mdc

@@ -0,0 +1,86 @@
+---
+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
+---
+# Event Schema Evolution
+
+Schemas for events, messages, and stream records evolve independently of producer and consumer deploy order. Every change must declare an explicit compatibility mode and pass a registry compatibility check before merge.
+
+## Compatibility Modes
+
+A registry compatibility mode constrains the diff between adjacent schema versions. Pick the mode that matches the deploy-order guarantee available in the target system.
+
+- **`BACKWARD`** — a consumer using the new schema reads data written with the old schema. Allowed diffs: delete a field, add a field that has a default value. Deploy consumers first. Default for evolving consumer code.
+- **`FORWARD`** — a consumer using the old schema reads data written with the new schema. Allowed diffs: add a field, delete a field that had a default value. Deploy producers first. Default for evolving producer code.
+- **`FULL`** — both directions. Required when producer and consumer deploy order cannot be controlled (e.g., split across teams or platforms).
+- **`*_TRANSITIVE`** variants (BACKWARD_TRANSITIVE, FORWARD_TRANSITIVE, FULL_TRANSITIVE) — the constraint holds against every prior schema version, not just the immediately preceding one. Required when consumers may replay from offset zero or read a historical archive.
+- **`NONE`** — disables compatibility checking; breaking changes accepted. Permitted only on a dedicated `*-v2` subject during a planned migration window with a dated deprecation plan in the migration ticket.
+
+Default recommendation when in doubt: `BACKWARD_TRANSITIVE` — consumers can deploy first and replay from offset zero.
+
+## Schema Registry Mandate
+
+- Every event topic / stream / subscription has a registered schema in Confluent Schema Registry, Apicurio Registry, AWS Glue Schema Registry, or Karapace. No in-tree schema-only repos without a registry binding.
+- Subject naming strategy is declared per topic: `TopicNameStrategy` (one schema per topic — default), `RecordNameStrategy` (one schema per record type across topics), or `TopicRecordNameStrategy` (multiple record types per topic). Mixing strategies inside the same topic is forbidden.
+- Compatibility mode is set per subject in the registry and asserted in CI. Changing the mode requires a registry-admin role and a logged justification.
+- Schemas are versioned by the registry; the producer pins the schema ID it serialized with, and the consumer fetches by ID — never by name + "latest".
+
+## Avro Evolution Rules
+
+- Adding a field requires a `default` value to remain backward-compatible — a consumer using the new schema reads old data by substituting the default for the absent field.
+- Removing a field requires the field to have had a `default` value to remain forward-compatible — an old consumer reads new data and the missing field falls back to its declared default.
+- Use a union with `null` (e.g., `["null", "string"]` with `default: null`) to express an optional field. Place `null` first in the union so the default is unambiguously the null branch.
+- Never rename a field — add a new field and register an `aliases: ["old_name"]` entry on the new field so old data deserializes against the new schema.
+- Never change a field's type. To replace a type, add a new field of the new type, dual-write during the migration window, and remove the old field only after consumer migration completes.
+
+## Protobuf Evolution Rules
+
+- Use `proto3` for new schemas. Field numbers are immutable identifiers — never reuse a tag number, never renumber, never reorder by tag.
+- When removing a field, add a `reserved` clause for both the tag number and the field name so future authors cannot resurrect the removed field with a different type and produce silent data corruption.
+- Field type widening is constrained: int32 / uint32 / int64 / uint64 / bool are mutually wire-compatible; sint32 ↔ sint64 are compatible; fixed32 ↔ sfixed32 are compatible; `string` ↔ `bytes` are compatible when bytes are valid UTF-8. Other type changes are breaking.
+- Use `optional` (proto3 since 3.15) for clear presence semantics on scalar fields. Without `optional`, unset and default-valued fields are indistinguishable on the wire.
+- Never remove an enum value — mark it `[deprecated = true]` and leave it in place. Removing an enum value breaks consumers that have it pinned.
+- New message types are not forward-compatible — old producers/consumers do not know about them. Prefer `BACKWARD_TRANSITIVE` for protobuf subjects.
+
+## JSON Schema Evolution
+
+- Default policy: additive only. New optional properties may be added; required properties may not be added to an existing record type.
+- `additionalProperties: false` blocks forward compatibility (a consumer using the old strict schema rejects new fields). Choose explicitly: set `false` only when the consumer must reject unknown fields for security reasons; set `true` (or omit) to allow forward-compatible evolution.
+- Version the schema identifier with semver (e.g., `$id: "https://example.com/schemas/event/v1.3.0.json"`). Patch and minor bumps must be additive; major bumps signal an incompatible change and require a new subject.
+- For shared envelope shapes (e.g., CloudEvents), pin the envelope spec version and version only the `data` payload schema.
+
+## Consumer-Side Defaults and Tolerance
+
+- Every optional field deserializes to an explicit default value in consumer code (zero-value, `None`, empty string, empty list — declared, not implicit).
+- Consumers never panic, crash, or fail-stop on a missing field. Missing → default. Unknown field → log at `info`, increment `event.schema.unknown_field` counter, continue processing.
+- Emit `event.schema.version` and `event.subject` as attributes on every consumer-side trace span and metric label, so observability dashboards surface version distribution and detect stuck consumers on the old schema.
+- Consumers validate against the schema fetched by ID at deserialization time; never validate against a hard-coded in-process schema literal.
+
+## Dual-Publish During Migration
+
+- When the shape change exceeds what the registry compatibility mode permits, dual-publish: write the same logical event in both old and new shapes — either to two topics (`orders.v1`, `orders.v2`) or to one topic with a union schema discriminated by a `schema_version` field.
+- Keep dual-publish active until every consumer has been confirmed migrated to the new shape (poll consumer-group offsets against both topics; alert on lag on the new shape; alert on consumption from the old shape from any non-allowlisted consumer group).
+- Deprecate the old shape only after the consumer-migration confirmation report is logged in the migration ticket. Default deprecation window: 1 full release cycle plus 1 on-call rotation past zero consumption.
+
+## Outbox and Idempotency
+
+- Every event carries a unique `event_id`. Prefer UUIDv7 over UUIDv4 — UUIDv7 is time-sortable, which simplifies dedup and ordering checks.
+- Consumers deduplicate by `event_id` over a sliding window sized to the maximum reprocessing horizon (typically 24–72 hours).
+- Producers that write to a transactional database publish events via the transactional outbox pattern: append the event row to an `outbox` table in the same DB transaction as the business write; a separate relay process drains the outbox to the broker with at-least-once semantics. This avoids the dual-write inconsistency between DB and broker.
+- Every consumer is idempotent at the business-logic layer — receiving the same `event_id` twice produces the same end-state.
+
+## Verification
+
+- CI runs a registry compatibility check on every PR that touches a schema file: `confluent-schema-registry-maven-plugin` test-compatibility goal, the REST `/compatibility/subjects/<subject>/versions/latest` endpoint, or `buf breaking` for protobuf. PR fails on incompatible diff.
+- `buf breaking --against '.git#branch=main'` runs on every protobuf change to detect tag-reuse, type-narrowing, and enum-value removal.
+- Generated client code from schemas is regenerated and committed in the same PR as the schema change; CI fails on drift between schema and generated code.
+- A schema-evolution test fixture replays a representative set of historical messages against the new schema and asserts deserialization success.
+
+## References
+
+- Confluent Schema Registry — Schema Evolution and Compatibility: https://docs.confluent.io/platform/current/schema-registry/fundamentals/schema-evolution.html
+- Apache Avro Specification — Schema Resolution: https://avro.apache.org/docs/current/specification/#schema-resolution
+- Protocol Buffers Language Guide (proto3) — Updating a Message Type: https://protobuf.dev/programming-guides/proto3/#updating
+- `buf breaking` — protobuf breaking-change detector: https://buf.build/docs/breaking/overview
+- CloudEvents specification: https://github.com/cloudevents/spec

package/rules/hatch3r-handoff-readiness.md

@@ -0,0 +1,45 @@
+---
+id: hatch3r-handoff-readiness
+type: rule
+description: Handoff readiness checklist — pre-write validation before persisting a canonical handoff document.
+scope: conditional
+globs: .agents/handoffs/active/**/*.md
+precedence: high
+tags: [core, maintenance]
+quality_charter: agents/shared/quality-charter.md
+cache_friendly: true
+---
+# Handoff Readiness Checklist
+
+Before writing a handoff to `.agents/handoffs/active/`, verify each criterion. Refuse the write if any **Required** criterion fails; warn on **Recommended** failures.
+
+## Required (fail = refuse write)
+
+| # | Criterion | Rationale |
+|---|-----------|-----------|
+| 1 | Body ≤ 51,200 bytes (50 KB) | Token bloat — full transcripts and unbounded sessions degrade resume reliability |
+| 2 | Body contains no full message transcript | Token bloat — structured fields only |
+| 3 | All 8 required sections present (Problem, Decisions, Work Done, Work Remaining, Blockers, Next Steps, Build & Test Status, File Manifest) | Resume needs structured state |
+| 4 | git_ref matches current HEAD (branch@sha7) | Staleness signal integrity |
+| 5 | Frontmatter validates against schema | Loader interop |
+| 6 | Injection-pattern scan clean (P-LEARN-01..05) | ASI06 memory poisoning prevention |
+| 7 | Integrity hash computed (sha256:<hex>) | Tamper detection |
+
+## Recommended (fail = warn)
+
+| # | Criterion | Rationale |
+|---|-----------|-----------|
+| 8 | `summary` populated, ≤ 200 chars | Loader briefing budget |
+| 9 | `target_agent` is explicit (not `any`) | Avoids handoff loops (industry anti-pattern) |
+| 10 | `Build & Test Status` table populated with at least one row | Resume reliability — knowing whether tests passed at handoff time |
+
+## Enforcement
+
+The `hatch3r-handoff-preparer` agent applies this checklist before invoking `writeHandoff` in `src/content/handoffs/index.ts`. The `validateHandoffContent` function in `src/content/handoffs/validation.ts` runs criteria 1-7 as `errors[]` and 8-10 as `warnings[]`.
+
+## Cross-references
+
+- Body sections schema: `.agents/handoffs/README.md`
+- Iteration Summary contract (populates Work Done / Work Remaining / Blockers): `rules/hatch3r-iteration-summary.md`
+- Injection-pattern catalog: `agents/shared/injection-patterns.md` Section B
+- Quality charter (confidence levels): `agents/shared/quality-charter.md`

package/rules/hatch3r-handoff-readiness.mdc

@@ -0,0 +1,40 @@
+---
+description: Handoff readiness checklist — pre-write validation before persisting a canonical handoff document.
+globs: [".agents/handoffs/active/**/*.md"]
+alwaysApply: false
+precedence: high
+---
+# Handoff Readiness Checklist
+
+Before writing a handoff to `.agents/handoffs/active/`, verify each criterion. Refuse the write if any **Required** criterion fails; warn on **Recommended** failures.
+
+## Required (fail = refuse write)
+
+| # | Criterion | Rationale |
+|---|-----------|-----------|
+| 1 | Body ≤ 51,200 bytes (50 KB) | Token bloat — full transcripts and unbounded sessions degrade resume reliability |
+| 2 | Body contains no full message transcript | Token bloat — structured fields only |
+| 3 | All 8 required sections present (Problem, Decisions, Work Done, Work Remaining, Blockers, Next Steps, Build & Test Status, File Manifest) | Resume needs structured state |
+| 4 | git_ref matches current HEAD (branch@sha7) | Staleness signal integrity |
+| 5 | Frontmatter validates against schema | Loader interop |
+| 6 | Injection-pattern scan clean (P-LEARN-01..05) | ASI06 memory poisoning prevention |
+| 7 | Integrity hash computed (sha256:<hex>) | Tamper detection |
+
+## Recommended (fail = warn)
+
+| # | Criterion | Rationale |
+|---|-----------|-----------|
+| 8 | `summary` populated, ≤ 200 chars | Loader briefing budget |
+| 9 | `target_agent` is explicit (not `any`) | Avoids handoff loops (industry anti-pattern) |
+| 10 | `Build & Test Status` table populated with at least one row | Resume reliability — knowing whether tests passed at handoff time |
+
+## Enforcement
+
+The `hatch3r-handoff-preparer` agent applies this checklist before invoking `writeHandoff` in `src/content/handoffs/index.ts`. The `validateHandoffContent` function in `src/content/handoffs/validation.ts` runs criteria 1-7 as `errors[]` and 8-10 as `warnings[]`.
+
+## Cross-references
+
+- Body sections schema: `.agents/handoffs/README.md`
+- Iteration Summary contract (populates Work Done / Work Remaining / Blockers): `rules/hatch3r-iteration-summary.md`
+- Injection-pattern catalog: `agents/shared/injection-patterns.md` Section B
+- Quality charter (confidence levels): `agents/shared/quality-charter.md`