hatch3r 1.8.0 → 2.0.0

package/dist/content/rules/hatch3r-proof-model.mdc

@@ -0,0 +1,131 @@
+---
+id: hatch3r-proof-model
+type: rule
+description: Mandatory citation per factual claim + pre-execution verification gates + proof_trace block schema. Hallucination prevention via verifiable proof, not citation alone.
+tags: [proof, verification, citation, floor:content-quality]
+precedence: high
+alwaysApply: true
+---
+# hatch3r Proof Model
+
+**Pillars:** P2 (Scientific Quality), P5 (Governance Self-Quality)
+
+This rule operationalises Decision #19 (CONSTITUTION §6): hallucination prevention via verifiable proof, not citation alone. It defines WHEN proof is required, WHAT schema each proof emits, and WHICH gates a hatch3r-driven agent must pass before issuing a factual assertion.
+
+## When Proof Trace Is Required
+
+Emit a `proof_trace:` block under any state-dependent claim:
+- File existence or absence
+- File content matching a pattern (specific bytes, frontmatter field, exported symbol)
+- grep match presence/count (zero matches is itself a state-dependent claim)
+- Type-check pass/fail (`npx tsc --noEmit` exit code)
+- Test exit code + output (`npm test` per-suite pass/fail counts)
+- Command exit code + output (any shell invocation whose result the agent is about to cite)
+- Web fetch success + content matching (URL resolves AND target string present)
+
+State-independent claims (definitional, axiomatic, design-rationale) do NOT require proof_trace — citing the file:line where the definition lives is sufficient.
+
+## Proof Trace Schema
+
+```yaml
+proof_trace:
+  claim: <one-sentence assertion>
+  command: <bash invocation OR Read tool call OR grep pattern>
+  expected: <pattern OR quoted output>
+  actual: <verbatim ≤200 chars from command output>
+  verdict: matched | mismatched
+  accessed: YYYY-MM-DD
+```
+
+Field rules:
+- `claim` — one sentence; what the proof verifies. Never a multi-clause assertion.
+- `command` — runnable verbatim by a reviewer. No paraphrase.
+- `expected` — either a regex/pattern OR the verbatim string the command should emit.
+- `actual` — verbatim slice of the command output, truncated to 200 characters with `…` suffix if longer.
+- `verdict` — `matched` when actual satisfies expected; `mismatched` otherwise. A `mismatched` verdict still belongs in the proof trace — it documents that verification was attempted.
+- `accessed` — ISO-8601 date when the command was run.
+
+## Pre-Execution Verification Gates
+
+Before issuing any agent-generated assertion that affects a downstream decision, the agent passes these gates in order:
+
+1. **State-dependent claim?** If yes, prepare a `proof_trace` block — do not emit the claim without it.
+2. **External dependency claim** (library version, API behavior, platform feature)? Verify against current documentation per `agents/shared/quality-charter.md` §15 Currency Verification (≤180 days). Cite URL + access date + trust tier per `agents/shared/rigor-contract.md` §Web Research Mandate.
+3. **Cross-file claim** (file X imports file Y, function A calls function B)? Run grep + cite file:line. Do not infer from filename or directory.
+4. **Behavioral claim** (function does X under condition Y)? Either point to a test that exercises Y → X, or write one before asserting.
+5. **Negative claim** (X does NOT exist, Y does NOT happen)? Run the search command and emit the zero-match output in `actual:`. Absence is harder to prove than presence — make the search command explicit.
+
+A claim that fails its gate is either dropped, or downgraded to confidence `low` per `agents/shared/quality-charter.md` §1 with the gap explicitly named.
+
+## Citation Alone Is Insufficient
+
+Per CONSTITUTION §6 Decision #19: "Citation alone insufficient — verification commands close the loop." Documents become stale; commands return current state. A citation without a verification command is a Medium-minimum finding under D24 self-audit.
+
+Concrete failure modes citation-alone leaves open:
+- File path moved or renamed since the cited revision
+- Section heading rewritten such that the citation refers to absent content
+- Behavior changed in a way the prose has not yet caught up to
+- Reviewer reading the citation does not have the cited file open
+
+A proof_trace defeats all four — the command runs against current state at review time.
+
+## Acceptable Failure Modes
+
+- **Verification impossible at write time** (e.g., production database state from local dev) — explicitly state the verification gap + lower confidence to medium per quality-charter §1.
+- **Verification cost prohibitive** (e.g., 30-minute integration suite for a docs typo) — log a `verification_skipped: <reason>` field; flag for downstream check. The skip must be documented, not silent.
+- **Source 404 / withdrawn** — re-research before relying; do not cite a dead URL per rigor-contract.md §Web Research Mandate. Re-running the fetch with a `accessed:` date earlier than the 404 does not rescue the citation.
+- **Verification command itself unreliable** (flaky test, intermittent network) — note the unreliability + run the command N≥3 times + cite the majority outcome.
+
+## Examples
+
+State-dependent claim WITH proof_trace:
+
+```yaml
+proof_trace:
+  claim: rigor-contract.md defines a Proof Trace Contract section
+  command: grep -n "Proof Trace Contract" agents/shared/rigor-contract.md
+  expected: line-numbered match referencing "Proof Trace Contract"
+  actual: "84:## Proof Trace Contract (Decision 9 — added 2026-05-26)"
+  verdict: matched
+  accessed: 2026-05-26
+```
+
+Negative claim WITH proof_trace:
+
+```yaml
+proof_trace:
+  claim: no occurrences of "TODO" remain in src/content/contentRoot.ts
+  command: grep -c "TODO" src/content/contentRoot.ts
+  expected: "0"
+  actual: "0"
+  verdict: matched
+  accessed: 2026-05-26
+```
+
+External dependency claim WITH proof_trace:
+
+```yaml
+proof_trace:
+  claim: Commander.js 12.x supports async action handlers
+  command: WebFetch https://github.com/tj/commander.js/blob/master/Readme.md#action-handler
+  expected: section "Action handler" describes async support
+  actual: "Action handler functions can also be async. Use parseAsync()…"
+  verdict: matched
+  accessed: 2026-05-26
+```
+
+## Enforcement
+
+The audit prompt's Behavioral Charter directive 20 (added 2.0.0) and `agents/shared/rigor-contract.md` §Proof Trace Contract (added 2026-05-26) operationalise this rule at audit time. Findings missing proof_trace on state-dependent claims are dropped at SA output time per the charter's directive 20 + rigor-contract §Schema Enforcement.
+
+Reviewer-class artifacts (`agents/hatch3r-reviewer.md`, future Reviewer Pass 1.5 per rigor-contract §Proof Trace Contract) read proof_trace blocks to verify implementation against documented runtime state. Implementer-class artifacts (`agents/hatch3r-implementer.md`) emit proof_trace blocks before declaring task completion.
+
+## Pillar Service
+- P2 — every factual claim becomes verifiable; placeholder findings are detectable and retryable.
+- P5 — governance system applies proof to itself; the rule that mandates proof is itself bound by proof at audit time.
+
+## Cross-References
+- Decision #19 — proof-trace + mandatory citation as 2.0.0 hallucination-prevention floor
+- `agents/shared/rigor-contract.md` §Proof Trace Contract — schema canonical location + Shallow Finding Detector linkage
+- The audit prompt's Behavioral Charter directive 20 — audit-time enforcement at SA output time
+- `agents/shared/quality-charter.md` §15 Currency Verification — external-dependency claim freshness window (≤180 days)

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

@@ -0,0 +1,70 @@
+---
+id: hatch3r-python-patterns
+type: rule
+description: Python 3.12+ conventions covering uv project management, Ruff lint+format, mypy strict typing, pytest parametrize, and the FastAPI/Django request-path + ORM N+1 floor
+scope: conditional
+globs: "**/*.py,**/pyproject.toml,**/requirements.txt,**/manage.py,**/setup.cfg,**/tox.ini,**/Pipfile,**/conftest.py"
+tags: [implementation, lang:python]
+quality_charter: agents/shared/quality-charter.md
+cache_friendly: true
+---
+# Python Patterns
+
+**Pillars:** P2 (Scientific & Practical Quality), CQ8 (Maintainability Quality)
+
+> Applies when the project ships Python. Detection signals: `pyproject.toml`, `setup.py`, `requirements.txt`, `Pipfile`, `setup.cfg`, or `tox.ini` at repo root, or `manage.py` for Django.
+
+## Python Language Floor
+
+- Target Python 3.12+. Declare `requires-python = ">=3.12"` in `pyproject.toml`. Drop Python 2 idioms (`from __future__`, `six`, `u""` prefixes) entirely.
+- Centralize all tool config in `pyproject.toml` — single source of truth for build, Ruff, mypy, and pytest. Do not split config across `setup.cfg` + `.flake8` + `.isort.cfg`.
+- Use `uv` for dependency + environment management. Commit `uv.lock`. Run every tool through `uv run <tool>` so the resolved environment is deterministic across machines; never activate a virtualenv manually in CI.
+- Treat lint, format-check, type, and test as four separate gates: `uv run ruff check`, `uv run ruff format --check`, `uv run mypy src/`, `uv run pytest`. Any non-zero exit blocks merge.
+
+## Linting & Formatting (Ruff)
+
+- Use Ruff for both linting and formatting — it replaces flake8 + isort + black + pyupgrade in one tool with drop-in Black formatting parity.
+- Enable at minimum these rule families in `[tool.ruff.lint]` `select`: `E`/`F` (pyflakes + pycodestyle), `I` (import sort), `B` (bugbear), `UP` (pyupgrade), `SIM` (flake8-simplify), `RUF` (Ruff-native). Add `ASYNC` for async codebases.
+- Run `ruff format` (not standalone black). Set `line-length = 100` (or the team standard) once in `[tool.ruff]` so the linter and formatter agree.
+- Wire `astral-sh/ruff-pre-commit` so lint + format run before every commit; CI re-runs the same checks as the authoritative gate.
+
+## Typing (mypy)
+
+- Enable `strict = true` in `[tool.mypy]` from day one — adding strict typing to a typed-from-the-start codebase is cheaper than retrofitting it later.
+- Type every public function signature: parameters and return. Prefer `X | None` over `Optional[X]` (3.10+ union syntax). Use `collections.abc` protocols (`Sequence`, `Mapping`, `Iterable`) for parameters, concrete types for returns.
+- Exclude the test directory from strict mode only when test fixtures fight the type checker — keep `src/` strict. Never blanket-suppress with `# type: ignore` without a specific error code (`# type: ignore[arg-type]`).
+- For data shapes, prefer `@dataclass(slots=True)` or Pydantic v2 `BaseModel` over untyped dicts. Pydantic v2 validates at the boundary; dataclasses are zero-overhead internal records.
+
+## Testing (pytest)
+
+- pytest is the floor — do not use `unittest.TestCase` for new suites. Test files `test_*.py`, functions `test_*`.
+- Use `@pytest.mark.parametrize` for input-table tests instead of loops — each case reports independently, mirroring Go table-driven subtests.
+- Fixtures over `setUp`/`tearDown`: scope fixtures (`function`/`module`/`session`) deliberately. Put shared fixtures in `conftest.py`.
+- Coverage floor: `pytest --cov=src --cov-fail-under=80`. Critical paths (auth, billing, migrations) at 90%. Use `pytest-randomly` to surface inter-test state leakage.
+- Mark slow/integration tests (`@pytest.mark.slow`) and gate them behind `-m "not slow"` in the fast pre-commit loop; run the full set in CI.
+
+## Async & Web (FastAPI / Django)
+
+- In an async request path use async all the way down: `httpx` over `requests`, `asyncio.sleep` over `time.sleep`, an async ORM/driver (`asyncpg`, SQLAlchemy `AsyncSession`, or SQLModel) over a blocking one. A single blocking call stalls the event loop for every concurrent request.
+- FastAPI runs plain `def` handlers in a threadpool automatically — only mark a handler `async def` when it actually awaits async I/O. Do not put blocking DB calls inside an `async def` without an async driver.
+- Prevent N+1 queries: Django `select_related()` (FK / one-to-one) and `prefetch_related()` (reverse FK / M2M); SQLAlchemy `selectinload()` / `joinedload()`. Accessing a related attribute inside a loop over N rows silently issues N+1 queries.
+- Validate every request body and response with Pydantic v2 models (FastAPI) or DRF serializers (Django) — never trust raw request dicts. Keep request/response schemas distinct from ORM models.
+- Django: run `manage.py check --deploy` in CI; never ship with `DEBUG = True`; load secrets from the environment, not `settings.py`.
+
+## Dependency Hygiene
+
+- Pin direct dependencies in `pyproject.toml` and lock the full graph in `uv.lock`. Reproducible installs (`uv sync --frozen`) in CI.
+- Vulnerability scanning: `pip-audit` (or `uv`'s audit) in CI against the locked graph. Block merge on known CVE matches.
+- Keep runtime and dev dependencies separate (`[project.dependencies]` vs `[dependency-groups]` / `[project.optional-dependencies]`). Production images install runtime-only.
+
+## References
+
+- Ruff documentation: https://docs.astral.sh/ruff/ (accessed 2026-06-05, official-docs)
+- Modern Python tooling (uv + Ruff + mypy), 2026: https://softaims.com/blog/modern-python-tooling-uv-ruff-mypy-2026 (accessed 2026-06-05, established-practitioner)
+- FastAPI async patterns + ORM N+1, 2025: https://shiladityamajumder.medium.com/async-apis-with-fastapi-patterns-pitfalls-best-practices-2d72b2b66f25 (accessed 2026-06-05, established-practitioner)
+
+## Cross-References
+
+- `rules/hatch3r-api-design.md` — REST/GraphQL/gRPC contract floors apply to FastAPI / Django services.
+- `rules/hatch3r-testing.md` — coverage thresholds carry over to `pytest --cov`.
+- `rules/hatch3r-observability-logging.md` — structured-logging contract applies to Python `logging` / `structlog`.

package/dist/content/rules/hatch3r-python-patterns.mdc

@@ -0,0 +1,65 @@
+---
+description: Python 3.12+ conventions covering uv project management, Ruff lint+format, mypy strict typing, pytest parametrize, and the FastAPI/Django request-path + ORM N+1 floor
+globs: ["**/*.py", "**/pyproject.toml", "**/requirements.txt", "**/manage.py", "**/setup.cfg", "**/tox.ini", "**/Pipfile", "**/conftest.py"]
+alwaysApply: false
+---
+# Python Patterns
+
+**Pillars:** P2 (Scientific & Practical Quality), CQ8 (Maintainability Quality)
+
+> Applies when the project ships Python. Detection signals: `pyproject.toml`, `setup.py`, `requirements.txt`, `Pipfile`, `setup.cfg`, or `tox.ini` at repo root, or `manage.py` for Django.
+
+## Python Language Floor
+
+- Target Python 3.12+. Declare `requires-python = ">=3.12"` in `pyproject.toml`. Drop Python 2 idioms (`from __future__`, `six`, `u""` prefixes) entirely.
+- Centralize all tool config in `pyproject.toml` — single source of truth for build, Ruff, mypy, and pytest. Do not split config across `setup.cfg` + `.flake8` + `.isort.cfg`.
+- Use `uv` for dependency + environment management. Commit `uv.lock`. Run every tool through `uv run <tool>` so the resolved environment is deterministic across machines; never activate a virtualenv manually in CI.
+- Treat lint, format-check, type, and test as four separate gates: `uv run ruff check`, `uv run ruff format --check`, `uv run mypy src/`, `uv run pytest`. Any non-zero exit blocks merge.
+
+## Linting & Formatting (Ruff)
+
+- Use Ruff for both linting and formatting — it replaces flake8 + isort + black + pyupgrade in one tool with drop-in Black formatting parity.
+- Enable at minimum these rule families in `[tool.ruff.lint]` `select`: `E`/`F` (pyflakes + pycodestyle), `I` (import sort), `B` (bugbear), `UP` (pyupgrade), `SIM` (flake8-simplify), `RUF` (Ruff-native). Add `ASYNC` for async codebases.
+- Run `ruff format` (not standalone black). Set `line-length = 100` (or the team standard) once in `[tool.ruff]` so the linter and formatter agree.
+- Wire `astral-sh/ruff-pre-commit` so lint + format run before every commit; CI re-runs the same checks as the authoritative gate.
+
+## Typing (mypy)
+
+- Enable `strict = true` in `[tool.mypy]` from day one — adding strict typing to a typed-from-the-start codebase is cheaper than retrofitting it later.
+- Type every public function signature: parameters and return. Prefer `X | None` over `Optional[X]` (3.10+ union syntax). Use `collections.abc` protocols (`Sequence`, `Mapping`, `Iterable`) for parameters, concrete types for returns.
+- Exclude the test directory from strict mode only when test fixtures fight the type checker — keep `src/` strict. Never blanket-suppress with `# type: ignore` without a specific error code (`# type: ignore[arg-type]`).
+- For data shapes, prefer `@dataclass(slots=True)` or Pydantic v2 `BaseModel` over untyped dicts. Pydantic v2 validates at the boundary; dataclasses are zero-overhead internal records.
+
+## Testing (pytest)
+
+- pytest is the floor — do not use `unittest.TestCase` for new suites. Test files `test_*.py`, functions `test_*`.
+- Use `@pytest.mark.parametrize` for input-table tests instead of loops — each case reports independently, mirroring Go table-driven subtests.
+- Fixtures over `setUp`/`tearDown`: scope fixtures (`function`/`module`/`session`) deliberately. Put shared fixtures in `conftest.py`.
+- Coverage floor: `pytest --cov=src --cov-fail-under=80`. Critical paths (auth, billing, migrations) at 90%. Use `pytest-randomly` to surface inter-test state leakage.
+- Mark slow/integration tests (`@pytest.mark.slow`) and gate them behind `-m "not slow"` in the fast pre-commit loop; run the full set in CI.
+
+## Async & Web (FastAPI / Django)
+
+- In an async request path use async all the way down: `httpx` over `requests`, `asyncio.sleep` over `time.sleep`, an async ORM/driver (`asyncpg`, SQLAlchemy `AsyncSession`, or SQLModel) over a blocking one. A single blocking call stalls the event loop for every concurrent request.
+- FastAPI runs plain `def` handlers in a threadpool automatically — only mark a handler `async def` when it actually awaits async I/O. Do not put blocking DB calls inside an `async def` without an async driver.
+- Prevent N+1 queries: Django `select_related()` (FK / one-to-one) and `prefetch_related()` (reverse FK / M2M); SQLAlchemy `selectinload()` / `joinedload()`. Accessing a related attribute inside a loop over N rows silently issues N+1 queries.
+- Validate every request body and response with Pydantic v2 models (FastAPI) or DRF serializers (Django) — never trust raw request dicts. Keep request/response schemas distinct from ORM models.
+- Django: run `manage.py check --deploy` in CI; never ship with `DEBUG = True`; load secrets from the environment, not `settings.py`.
+
+## Dependency Hygiene
+
+- Pin direct dependencies in `pyproject.toml` and lock the full graph in `uv.lock`. Reproducible installs (`uv sync --frozen`) in CI.
+- Vulnerability scanning: `pip-audit` (or `uv`'s audit) in CI against the locked graph. Block merge on known CVE matches.
+- Keep runtime and dev dependencies separate (`[project.dependencies]` vs `[dependency-groups]` / `[project.optional-dependencies]`). Production images install runtime-only.
+
+## References
+
+- Ruff documentation: https://docs.astral.sh/ruff/ (accessed 2026-06-05, official-docs)
+- Modern Python tooling (uv + Ruff + mypy), 2026: https://softaims.com/blog/modern-python-tooling-uv-ruff-mypy-2026 (accessed 2026-06-05, established-practitioner)
+- FastAPI async patterns + ORM N+1, 2025: https://shiladityamajumder.medium.com/async-apis-with-fastapi-patterns-pitfalls-best-practices-2d72b2b66f25 (accessed 2026-06-05, established-practitioner)
+
+## Cross-References
+
+- `rules/hatch3r-api-design.md` — REST/GraphQL/gRPC contract floors apply to FastAPI / Django services.
+- `rules/hatch3r-testing.md` — coverage thresholds carry over to `pytest --cov`.
+- `rules/hatch3r-observability-logging.md` — structured-logging contract applies to Python `logging` / `structlog`.

package/dist/content/rules/hatch3r-react-native-patterns.md

@@ -0,0 +1,83 @@
+---
+id: hatch3r-react-native-patterns
+type: rule
+description: React Native conventions covering New Architecture (Fabric + TurboModules), Hermes, Expo Router/SDK, native module bridging, performance, and platform-specific UI
+scope: conditional
+globs: "**/App.tsx,**/App.jsx,**/index.js,**/metro.config.js,**/metro.config.ts,**/babel.config.js,**/app.json,**/app.config.ts,**/app.config.js,**/ios/**,**/android/**,**/expo-env.d.ts,**/.expo/**,**/*.native.tsx,**/*.native.jsx,**/*.native.ts"
+tags: [implementation, lang:typescript]
+quality_charter: agents/shared/quality-charter.md
+cache_friendly: true
+---
+# React Native Patterns
+
+**Pillars:** P2 (Scientific & Practical Quality), CQ8 (Maintainability Quality)
+
+> Applies when the project ships a React Native or Expo app. Detection signals: `react-native` in `package.json` dependencies, `app.json` / `app.config.{ts,js}`, `metro.config.js`, `ios/` + `android/` workspace folders, or `.expo/` directory.
+
+## New Architecture (Fabric + TurboModules)
+
+- Target React Native 0.76+ with the New Architecture enabled (`newArchEnabled: true` in `app.json` for Expo, or `RCT_NEW_ARCH_ENABLED=1` for bare workflow). The New Architecture is on by default in 0.76 and is the only supported path for Expo SDK 52+.
+- Use Fabric renderer (synchronous, type-safe) for new native components. Legacy Paper renderer is for backward compatibility only — do not write new components against it.
+- Author native modules as TurboModules via `codegen` schemas. Stop adding `RCTBridgeModule`-style legacy modules — they bypass type-safety and force a full bridge serialization.
+- Run `react-native codegen` in CI to regenerate JSI specs from the schema files. Spec drift between TS and native side is a merge blocker.
+- Hermes is the default JS engine — keep it on. Avoid JSC unless a specific dependency requires it; document the reason in `README.md`.
+
+## Expo (Managed + Bare Workflow)
+
+- Prefer the Expo Managed workflow for new apps under SDK 52+. Expo Router 4 (file-system routing in `app/`) is the routing default; do not introduce React Navigation directly when Expo Router already covers the route surface.
+- Use EAS Build for production binaries (Apple App Store, Google Play). Local `expo run:ios` / `expo run:android` is for development only.
+- Pin the Expo SDK in `app.json` (`expo.sdkVersion`) and lock the matching `expo` package version. SDK upgrades go through `npx expo install --fix` — never edit `package.json` versions manually for Expo packages.
+- For OTA updates, use EAS Update (CodePush is sunset for RN). Channel and runtime version policy: pin `runtimeVersion` per binary release; never push a runtime-incompatible JS bundle.
+
+## Bridging & Native Modules
+
+- New native modules: author TurboModule specs in TypeScript first (`*.spec.ts`), run codegen, then implement Swift/Kotlin handlers. Spec-first prevents type drift.
+- Fabric native components: declare the spec via `codegenNativeComponent<Props>('ComponentName')`; never call the legacy `requireNativeComponent` for new code.
+- Use the `react-native-nitro-modules` or `expo-modules-core` API when authoring shared native code — both target the New Architecture and avoid the legacy bridge.
+- Cross-platform native APIs: prefer existing Expo modules (`expo-camera`, `expo-file-system`, `expo-secure-store`) over hand-rolled bridges. Do not duplicate community-maintained bindings.
+
+## Navigation
+
+- File-system routing via Expo Router 4 (`app/_layout.tsx`, `app/(tabs)/index.tsx`, `app/[id].tsx`). Use typed routes (`expo-router/typed-routes`) for compile-time link safety.
+- Deep links: define the URL scheme in `app.json` (`scheme`) and register the universal/app-link domain pair for both platforms. Test universal links on a real device — simulators do not honor associated-domains entitlements reliably.
+- For non-Expo apps, use React Navigation 7 with `@react-navigation/native-stack` (native UIKit/Fragment stack). JS-based stack (`@react-navigation/stack`) is for prototypes only.
+
+## Performance
+
+- Replace `FlatList` / `SectionList` with `@shopify/flash-list` for lists over 50 rows. FlashList recycles cells natively and outperforms FlatList by 5-10x on mid-range Android.
+- Memoize render functions in lists: every `renderItem` is wrapped in `React.memo` with stable equality. Inline arrow functions in `renderItem` re-render the whole list.
+- Use `InteractionManager.runAfterInteractions` to defer non-critical work until animations and gestures complete; never schedule heavy work on the JS thread during a transition.
+- Image loading: use `expo-image` (managed) or `react-native-fast-image` (bare). The default `<Image>` lacks caching and progressive decode.
+- Lazy-load screens with `React.lazy` + `Suspense` inside Expo Router layouts. Code-split heavy native screens behind navigation events.
+
+## Platform-Specific UI
+
+- Branch on `Platform.OS === 'ios' | 'android' | 'web'` only when the platform mandates a different UX (haptic patterns, header back gesture, status bar contrast). Avoid platform branching for layout — use flex + responsive units.
+- iOS: use `react-native-screens` with `enableScreens()` so the navigator renders native `UIViewController` stacks. Without this, all screens are JS Views.
+- Android: target SDK 35 (Android 15) per Google Play 2025 requirement. Configure edge-to-edge content (`android:windowOptOutEdgeToEdgeEnforcement="false"`) and respect insets via `react-native-safe-area-context`.
+- Accessibility: every touchable surface has `accessibilityRole`, `accessibilityLabel`, and `accessibilityHint`. Test with VoiceOver (iOS) and TalkBack (Android) before merge — simulator a11y is not equivalent.
+
+## State & Data
+
+- Use TanStack Query (`@tanstack/react-query`) for server state. Avoid Redux unless the app has cross-screen optimistic UI requirements not served by Query mutations.
+- Local persistent state: `@react-native-async-storage/async-storage` for non-secret values, `expo-secure-store` for tokens. Never store auth tokens in AsyncStorage on iOS (Keychain via SecureStore is the floor).
+- Background sync: use Expo's `expo-task-manager` + `expo-background-fetch` (managed) or `react-native-background-fetch` (bare). Document the platform-specific minimum interval (iOS ~15 min minimum, Android ~15 min minimum on Doze).
+
+## Testing
+
+- Unit + component tests with `jest-expo` (Expo) or `@testing-library/react-native` (bare). Run on the host Node runtime — no simulator boot for unit tests.
+- Integration tests with Detox (gray-box) or Maestro (black-box). Detox is preferred for apps with native modules; Maestro for pure-JS flows.
+- Snapshot tests for every screen at multiple viewport sizes (iPhone SE, iPhone 16 Pro Max, Pixel 8a) — guard against layout regressions on small devices.
+- E2E on EAS: configure `eas-cli` matrix builds against real devices via BrowserStack App Live or Sauce Labs Real Device Cloud.
+
+## References
+
+- React Native New Architecture overview: https://reactnative.dev/docs/the-new-architecture/landing-page (accessed 2026-05-27, official-docs)
+- Expo SDK 52 release notes: https://expo.dev/changelog/2024-11-12-sdk-52 (accessed 2026-05-27, official-docs)
+- Expo Router 4: https://docs.expo.dev/router/introduction/ (accessed 2026-05-27, official-docs)
+
+## Cross-References
+
+- `rules/hatch3r-component-conventions.md` — shared four-state surface contract applies to RN screens.
+- `rules/hatch3r-accessibility-standards.md` — WCAG mapping carries to React Native via `accessibilityRole` props.
+- `rules/hatch3r-testing.md` — coverage thresholds and determinism rules apply to RN tests.

package/dist/content/rules/hatch3r-react-native-patterns.mdc

@@ -0,0 +1,78 @@
+---
+description: React Native conventions covering New Architecture (Fabric + TurboModules), Hermes, Expo Router/SDK, native module bridging, performance, and platform-specific UI
+globs: ["**/App.tsx", "**/App.jsx", "**/index.js", "**/metro.config.js", "**/metro.config.ts", "**/babel.config.js", "**/app.json", "**/app.config.ts", "**/app.config.js", "**/ios/**", "**/android/**", "**/expo-env.d.ts", "**/.expo/**", "**/*.native.tsx", "**/*.native.jsx", "**/*.native.ts"]
+alwaysApply: false
+---
+# React Native Patterns
+
+**Pillars:** P2 (Scientific & Practical Quality), CQ8 (Maintainability Quality)
+
+> Applies when the project ships a React Native or Expo app. Detection signals: `react-native` in `package.json` dependencies, `app.json` / `app.config.{ts,js}`, `metro.config.js`, `ios/` + `android/` workspace folders, or `.expo/` directory.
+
+## New Architecture (Fabric + TurboModules)
+
+- Target React Native 0.76+ with the New Architecture enabled (`newArchEnabled: true` in `app.json` for Expo, or `RCT_NEW_ARCH_ENABLED=1` for bare workflow). The New Architecture is on by default in 0.76 and is the only supported path for Expo SDK 52+.
+- Use Fabric renderer (synchronous, type-safe) for new native components. Legacy Paper renderer is for backward compatibility only — do not write new components against it.
+- Author native modules as TurboModules via `codegen` schemas. Stop adding `RCTBridgeModule`-style legacy modules — they bypass type-safety and force a full bridge serialization.
+- Run `react-native codegen` in CI to regenerate JSI specs from the schema files. Spec drift between TS and native side is a merge blocker.
+- Hermes is the default JS engine — keep it on. Avoid JSC unless a specific dependency requires it; document the reason in `README.md`.
+
+## Expo (Managed + Bare Workflow)
+
+- Prefer the Expo Managed workflow for new apps under SDK 52+. Expo Router 4 (file-system routing in `app/`) is the routing default; do not introduce React Navigation directly when Expo Router already covers the route surface.
+- Use EAS Build for production binaries (Apple App Store, Google Play). Local `expo run:ios` / `expo run:android` is for development only.
+- Pin the Expo SDK in `app.json` (`expo.sdkVersion`) and lock the matching `expo` package version. SDK upgrades go through `npx expo install --fix` — never edit `package.json` versions manually for Expo packages.
+- For OTA updates, use EAS Update (CodePush is sunset for RN). Channel and runtime version policy: pin `runtimeVersion` per binary release; never push a runtime-incompatible JS bundle.
+
+## Bridging & Native Modules
+
+- New native modules: author TurboModule specs in TypeScript first (`*.spec.ts`), run codegen, then implement Swift/Kotlin handlers. Spec-first prevents type drift.
+- Fabric native components: declare the spec via `codegenNativeComponent<Props>('ComponentName')`; never call the legacy `requireNativeComponent` for new code.
+- Use the `react-native-nitro-modules` or `expo-modules-core` API when authoring shared native code — both target the New Architecture and avoid the legacy bridge.
+- Cross-platform native APIs: prefer existing Expo modules (`expo-camera`, `expo-file-system`, `expo-secure-store`) over hand-rolled bridges. Do not duplicate community-maintained bindings.
+
+## Navigation
+
+- File-system routing via Expo Router 4 (`app/_layout.tsx`, `app/(tabs)/index.tsx`, `app/[id].tsx`). Use typed routes (`expo-router/typed-routes`) for compile-time link safety.
+- Deep links: define the URL scheme in `app.json` (`scheme`) and register the universal/app-link domain pair for both platforms. Test universal links on a real device — simulators do not honor associated-domains entitlements reliably.
+- For non-Expo apps, use React Navigation 7 with `@react-navigation/native-stack` (native UIKit/Fragment stack). JS-based stack (`@react-navigation/stack`) is for prototypes only.
+
+## Performance
+
+- Replace `FlatList` / `SectionList` with `@shopify/flash-list` for lists over 50 rows. FlashList recycles cells natively and outperforms FlatList by 5-10x on mid-range Android.
+- Memoize render functions in lists: every `renderItem` is wrapped in `React.memo` with stable equality. Inline arrow functions in `renderItem` re-render the whole list.
+- Use `InteractionManager.runAfterInteractions` to defer non-critical work until animations and gestures complete; never schedule heavy work on the JS thread during a transition.
+- Image loading: use `expo-image` (managed) or `react-native-fast-image` (bare). The default `<Image>` lacks caching and progressive decode.
+- Lazy-load screens with `React.lazy` + `Suspense` inside Expo Router layouts. Code-split heavy native screens behind navigation events.
+
+## Platform-Specific UI
+
+- Branch on `Platform.OS === 'ios' | 'android' | 'web'` only when the platform mandates a different UX (haptic patterns, header back gesture, status bar contrast). Avoid platform branching for layout — use flex + responsive units.
+- iOS: use `react-native-screens` with `enableScreens()` so the navigator renders native `UIViewController` stacks. Without this, all screens are JS Views.
+- Android: target SDK 35 (Android 15) per Google Play 2025 requirement. Configure edge-to-edge content (`android:windowOptOutEdgeToEdgeEnforcement="false"`) and respect insets via `react-native-safe-area-context`.
+- Accessibility: every touchable surface has `accessibilityRole`, `accessibilityLabel`, and `accessibilityHint`. Test with VoiceOver (iOS) and TalkBack (Android) before merge — simulator a11y is not equivalent.
+
+## State & Data
+
+- Use TanStack Query (`@tanstack/react-query`) for server state. Avoid Redux unless the app has cross-screen optimistic UI requirements not served by Query mutations.
+- Local persistent state: `@react-native-async-storage/async-storage` for non-secret values, `expo-secure-store` for tokens. Never store auth tokens in AsyncStorage on iOS (Keychain via SecureStore is the floor).
+- Background sync: use Expo's `expo-task-manager` + `expo-background-fetch` (managed) or `react-native-background-fetch` (bare). Document the platform-specific minimum interval (iOS ~15 min minimum, Android ~15 min minimum on Doze).
+
+## Testing
+
+- Unit + component tests with `jest-expo` (Expo) or `@testing-library/react-native` (bare). Run on the host Node runtime — no simulator boot for unit tests.
+- Integration tests with Detox (gray-box) or Maestro (black-box). Detox is preferred for apps with native modules; Maestro for pure-JS flows.
+- Snapshot tests for every screen at multiple viewport sizes (iPhone SE, iPhone 16 Pro Max, Pixel 8a) — guard against layout regressions on small devices.
+- E2E on EAS: configure `eas-cli` matrix builds against real devices via BrowserStack App Live or Sauce Labs Real Device Cloud.
+
+## References
+
+- React Native New Architecture overview: https://reactnative.dev/docs/the-new-architecture/landing-page (accessed 2026-05-27, official-docs)
+- Expo SDK 52 release notes: https://expo.dev/changelog/2024-11-12-sdk-52 (accessed 2026-05-27, official-docs)
+- Expo Router 4: https://docs.expo.dev/router/introduction/ (accessed 2026-05-27, official-docs)
+
+## Cross-References
+
+- `rules/hatch3r-component-conventions.md` — shared four-state surface contract applies to RN screens.
+- `rules/hatch3r-accessibility-standards.md` — WCAG mapping carries to React Native via `accessibilityRole` props.
+- `rules/hatch3r-testing.md` — coverage thresholds and determinism rules apply to RN tests.

package/{rules → dist/content/rules}/hatch3r-resilience-patterns.md

@@ -2,8 +2,10 @@
 id: hatch3r-resilience-patterns
 type: rule
 description: Resilience patterns in user code — circuit breakers, retry with decorrelated jitter, timeouts with deadline propagation, idempotency keys, bulkheads, hedged requests
-scope: "**/services/**,**/handlers/**,**/clients/**,**/integrations/**,**/api/**,**/middleware/**,**/circuit*,**/retry*,**/resilience*"
+scope: conditional
+globs: "**/services/**,**/handlers/**,**/clients/**,**/integrations/**,**/api/**,**/middleware/**,**/circuit*,**/retry*,**/resilience*"
 tags: [implementation, devops]
+precedence: high
 quality_charter: agents/shared/quality-charter.md
 cache_friendly: true
 ---

package/{rules → dist/content/rules}/hatch3r-resilience-patterns.mdc

@@ -2,6 +2,7 @@
 description: Resilience patterns in user code — circuit breakers, retry with decorrelated jitter, timeouts with deadline propagation, idempotency keys, bulkheads, hedged requests
 globs: ["**/services/**", "**/handlers/**", "**/clients/**", "**/integrations/**", "**/api/**", "**/middleware/**", "**/circuit*", "**/retry*", "**/resilience*"]
 alwaysApply: false
+precedence: high
 ---
 # Resilience Patterns
 

package/dist/content/rules/hatch3r-reviewer-calibration.md

@@ -0,0 +1,84 @@
+---
+id: hatch3r-reviewer-calibration
+type: rule
+description: "Reviewer runtime confidence-calibration contract: every Nth (default N=5) consecutive clean PASS triggers an out-of-band second-pass review before loop exit; divergence reverts to REQUEST CHANGES; each second pass logs to .hatch3r/calibration-log.jsonl. Canonical source of the N-default and the directive that agents/hatch3r-reviewer.md and calibration-protocol.md reference."
+tags: [review, orchestration, floor:protocol]
+scope: always
+precedence: high
+quality_charter: agents/shared/quality-charter.md
+cache_friendly: true
+---
+# hatch3r Reviewer Confidence Calibration
+
+**Pillars:** P2 (Scientific & Practical Quality), P5 (Governance Self-Quality)
+
+A reviewer's `confidence` rating is self-assigned by the same model that produced the verdict. Without an out-of-band check it is structurally over-trusted: LLM judges systematically overstate confidence — predicted confidence significantly exceeds realized correctness (Tian et al. 2025, arxiv:2508.06225) — so a self-reported clean PASS carries a non-zero, unmeasured miscalibration probability at runtime. This rule is the canonical, always-on source for the **runtime** (within-loop) bound that closes that gap before the review loop exits on a clean PASS. It owns the N-default and the directive that `agents/hatch3r-reviewer.md` §Runtime Confidence Calibration and the across-cycle calibration protocol cite.
+
+Scope split (do not duplicate across the two artifacts):
+
+- **Runtime, within-loop (this rule + `agents/hatch3r-reviewer.md`):** bounds an unbounded run of self-trusted clean verdicts inside one review-loop session. Fires before loop exit.
+- **Across-cycle measurement (the across-cycle calibration protocol):** samples N=20 prior-cycle PASS findings at cycle close and scores realized over-claim rate. Fires at cycle archive time.
+
+The two are complements, not substitutes — neither replaces the other.
+
+## Directive (verbatim)
+
+> Every Nth consecutive clean PASS verdict on a review-loop exit triggers one out-of-band second-pass review of the same diff. If the second pass surfaces any Critical or Warning the first pass did not, the loop does NOT exit clean — it reverts to REQUEST CHANGES. Each second pass appends one record to `.hatch3r/calibration-log.jsonl`.
+
+## N-default (authoritative)
+
+`N = 5` consecutive clean PASS verdicts for general diffs; `N = 1` for safety-class diffs (auth / security / migration — see the high-risk fast path in Trigger). These are the single source of truth for the defaults; `agents/hatch3r-reviewer.md` and the across-cycle calibration protocol cite these values rather than redeclaring them. The lowered safety-class default fires the second pass on the first clean PASS so an auth, security, or migration change never merges on a single self-trusted verdict (D23-2).
+
+- **Counter owner — the orchestrator, NOT the reviewer.** The reviewer sub-agent is spawned stateless per iteration and the review loop exits on the first clean verdict, so a reviewer-owned counter can never exceed 1 and the second pass would never fire. The orchestrator owns `consecutive_clean_pass_count` and reads/writes it; the reviewer only reports its per-verdict outcome.
+- **Counter scope — across top-level runs, persisted.** Count consecutive clean PASS verdicts across top-level pipeline runs, not within one loop and not per-iteration (the loop exits on the first clean verdict, so within a single loop the count advances by at most 1). The orchestrator persists the running count to project-local `.hatch3r/calibration-state.json` (`{ "consecutive_clean_pass_count": <int>, "updated_at": "<ISO-8601>" }`), written atomically via `src/merge/safeWrite.ts`. On each top-level run the orchestrator reads the prior count, increments on a would-be-clean exit, and resets to 0 on any REQUEST CHANGES or DESIGN_OBJECTION verdict. A missing/unparseable file is treated as count 0.
+- **Project override:** a project may set a different cadence via its own config; the override widens or narrows the cadence but never disables the second pass while a second pass remains available (see Unavailability below).
+
+## Trigger
+
+The orchestrator evaluates the trigger at the would-be-clean loop exit (the point where the loop would return a clean PASS — 0 Critical + 0 Warning — to Phase 4), using the cross-run counter it persisted per N-default above. Either branch fires the second pass:
+
+- **Cadence branch (default):** the post-increment `consecutive_clean_pass_count` (prior persisted count + 1 for this run) is a multiple of `N`.
+- **High-risk fast path (safety-class, N=1):** the reviewed diff touches any safety-class surface — a file tagged `floor:security`, auth/authn code (the `hatch3r-security` (CQ3) dispatch set in `agents/hatch3r-reviewer.md`: `src/auth/**`, OAuth/OIDC config, WebAuthn/passkey server, release-pipeline files, dependency manifest/lockfile), any change that triggers the CQ3 security specialist, OR a schema/event-schema migration (the `migration.review` surface — schema DDL, backfills, event-schema changes). For a safety-class diff, fire the second pass on the **first** clean PASS, independent of the cadence counter (do not wait for the Nth). The fast-path branch still increments and persists the cross-run counter; it only lowers the firing threshold to `N=1` for that run.
+
+## Action
+
+Run one second-pass review of the same diff with an independent judge:
+
+1. **Documented setup recommendation — a different model class.** A same-model-family critique shares the generator's blind spot, so a same-family second pass cannot detect the error classes the family is systematically biased to produce (Huang et al., ICLR 2024, "Large Language Models Cannot Self-Correct Reasoning Yet"). Route the second pass to a different model class wherever the deployment can — this is the recommended project setup, not best-effort. The second pass renders its own independent verdict + confidence.
+2. **Fallback — same model class re-rolled at higher temperature,** used ONLY when no second model class is routable. Because this fallback does not break the shared-blind-spot, it is a weaker check: emit `calibration: degraded (same-family re-roll)` in the verdict for that run so the weakened independence is visible and never asserted as a clean cross-family check. Record the model class used in the log (`second_pass_model_class: re-roll`).
+
+The second pass applies the same Review Checklist as the first (`agents/hatch3r-reviewer.md` → Review Checklist); it is a full re-review, not a spot check.
+
+## Divergence handling
+
+- **Divergent** — the second pass surfaces any Critical or Warning the first pass did not: do NOT exit clean. Revert the loop verdict to REQUEST CHANGES, record both verdicts, and feed the divergence to the next fixer iteration.
+- **Aligned** — both passes agree (both clean): exit clean and record alignment.
+
+A divergent second pass is the failure mode of interest — it is the runtime signal that the first pass was over-confident.
+
+## Logging
+
+Append exactly one record per second pass to `.hatch3r/calibration-log.jsonl` (project-local, JSON Lines) via the atomic append path in `src/merge/safeWrite.ts`. One JSON object per line:
+
+```json
+{"timestamp":"<ISO-8601>","first_pass_verdict":"PASS","second_pass_verdict":"PASS|REQUEST CHANGES","divergent":false,"second_pass_model_class":"different|re-roll","consecutive_clean_count":5,"trigger":"cadence|high-risk"}
+```
+
+`consecutive_clean_count` is the post-increment cross-run count at firing time; `trigger` records which Trigger branch fired (`high-risk` when the diff touched a safety-class surface and the second pass fired on the first clean PASS under the `N=1` fast path). `second_pass_model_class` is `different` for a cross-family second pass or `re-roll` for the same-family fallback; a `re-roll` record corresponds to a `calibration: degraded (same-family re-roll)` verdict annotation per Action. The project-local over-claim rate derived from this log feeds the iteration-summary `Confidence` field per `rules/hatch3r-iteration-summary.md`.
+
+## Unavailability (visible skip, never silent)
+
+Skip the second pass ONLY when no second model class is available AND the orchestrator has disabled same-model re-roll. In that case emit `calibration: skipped (no second pass available)` in the verdict so the gap is visible rather than silent — a silent skip is a Silent-Failure-Contract violation. A skip does NOT reset the consecutive-clean-PASS counter; the next eligible exit re-attempts the second pass.
+
+## Pillar Service
+
+- **P2 Scientific & Practical Quality (primary).** Adds an adversarial out-of-band check to a self-assigned confidence value; over-claimed clean verdicts become detectable at runtime, not just at cycle close.
+- **P5 Governance Self-Quality (supporting).** Removes the "reviewer as sole judge of its own confidence" structural over-trust pattern from the within-loop path, mirroring the across-cycle loop that `calibration-protocol.md` adds at cycle scope.
+
+## References
+
+- `agents/hatch3r-reviewer.md` §Runtime Confidence Calibration — the consuming agent body that invokes this contract (accessed 2026-05-28, trust tier: canonical).
+- The across-cycle calibration protocol §Runtime complement (F13.2-F1) — the across-cycle measurement loop this runtime bound complements (accessed 2026-05-28, trust tier: canonical).
+- `rules/hatch3r-iteration-summary.md` — consumes the project-local over-claim rate for the `Confidence` field (accessed 2026-05-28, trust tier: canonical).
+- Tian, Z. et al. "Overconfidence in LLM-as-a-Judge: Diagnosis and Confidence-Driven Solution" (arxiv:2508.06225). `https://arxiv.org/abs/2508.06225` (accessed 2026-06-09, peer-reviewed-methodology). Evidence that an LLM judge's predicted confidence significantly overstates realized correctness (the Overconfidence Phenomenon), so a self-reported clean PASS is structurally over-trusted — motivating the out-of-band second pass.
+- Huang, J. et al. "Large Language Models Cannot Self-Correct Reasoning Yet." ICLR 2024 (arxiv:2310.01798). `https://arxiv.org/abs/2310.01798` (accessed 2026-06-06, peer-reviewed-methodology). Evidence that same-model self-critique shares the generator's blind spot, motivating the different-model-class setup recommendation in Action and the lowered safety-class `N=1` second-pass cadence (D23-2).