hatch3r 1.9.0 → 2.0.0

package/dist/content/rules/hatch3r-ai-ux-patterns.md

@@ -2,13 +2,17 @@
 id: hatch3r-ai-ux-patterns
 type: rule
 description: 2026 AI/agentic UX patterns for end-user projects shipping AI features — streaming, tool-call UI, human-approval gates, cancel/abort/undo, citations
-scope: "**/*.vue,**/*.jsx,**/*.tsx,**/*.svelte,**/ai/**,**/chat/**,**/assistant/**,**/agents/**,**/llm/**,**/copilot/**"
+scope: conditional
+globs: "**/*.vue,**/*.jsx,**/*.tsx,**/*.svelte,**/ai/**,**/chat/**,**/assistant/**,**/agents/**,**/llm/**,**/copilot/**"
 tags: [implementation, floor:ui-ux, ux, ai, frontend]
+precedence: high
 quality_charter: agents/shared/quality-charter.md
 cache_friendly: true
 ---
 # AI/Agentic UX Patterns (2026)
 
+**Pillars:** P2 (Scientific & Practical Quality), CQ2 (UX Quality)
+
 ## Scope
 
 This rule applies when the end-user project ships LLM-driven UI — chat, assistant, copilot, agent dashboards, generative UI surfaces. It does NOT govern the LLM backend itself (model selection, prompt engineering, retrieval pipeline). For non-AI UX rules (loading, empty, error, partial states; form patterns; microcopy), cross-reference `rules/hatch3r-ux-states-and-flows.md`. When both rules apply to the same surface, the non-AI rule sets the baseline and this rule layers AI-specific behavior on top.
@@ -110,7 +114,7 @@ Three distinct affordances — do not collapse them into a single control:
 
 ## Verification Gate
 
-Before declaring an AI surface "done":
+These 7 checks are operationalized as Gate 8 of `skills/hatch3r-ui-ux-verify` — the skill executes all 7, not just the streaming/tool-call subset. Before declaring an AI surface "done":
 
 - Streaming verified end-to-end: scripted Playwright test that asserts progressive token render (first token <1s after request, last token marked complete).
 - Tool-call card snapshot per state (`pending`, `in-progress`, `complete`, `failed`) — missing any state is a blocker.

package/dist/content/rules/hatch3r-ai-ux-patterns.mdc

@@ -2,9 +2,12 @@
 description: 2026 AI/agentic UX patterns for end-user projects shipping AI features — streaming, tool-call UI, human-approval gates, cancel/abort/undo, citations
 globs: ["**/*.vue", "**/*.jsx", "**/*.tsx", "**/*.svelte", "**/ai/**", "**/chat/**", "**/assistant/**", "**/agents/**", "**/llm/**", "**/copilot/**"]
 alwaysApply: false
+precedence: high
 ---
 # AI/Agentic UX Patterns (2026)
 
+**Pillars:** P2 (Scientific & Practical Quality), CQ2 (UX Quality)
+
 ## Scope
 
 This rule applies when the end-user project ships LLM-driven UI — chat, assistant, copilot, agent dashboards, generative UI surfaces. It does NOT govern the LLM backend itself (model selection, prompt engineering, retrieval pipeline). For non-AI UX rules (loading, empty, error, partial states; form patterns; microcopy), cross-reference `rules/hatch3r-ux-states-and-flows.md`. When both rules apply to the same surface, the non-AI rule sets the baseline and this rule layers AI-specific behavior on top.
@@ -106,7 +109,7 @@ Three distinct affordances — do not collapse them into a single control:
 
 ## Verification Gate
 
-Before declaring an AI surface "done":
+These 7 checks are operationalized as Gate 8 of `skills/hatch3r-ui-ux-verify` — the skill executes all 7, not just the streaming/tool-call subset. Before declaring an AI surface "done":
 
 - Streaming verified end-to-end: scripted Playwright test that asserts progressive token render (first token <1s after request, last token marked complete).
 - Tool-call card snapshot per state (`pending`, `in-progress`, `complete`, `failed`) — missing any state is a blocker.

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

@@ -0,0 +1,107 @@
+---
+id: hatch3r-android-patterns
+type: rule
+description: Android Kotlin conventions covering Jetpack Compose, coroutines + Flow, Hilt DI, Room, modular Gradle, AGP 8.x, target SDK 35, and Compose testing
+scope: conditional
+globs: "**/*.kt,**/*.kts,**/build.gradle,**/build.gradle.kts,**/settings.gradle,**/settings.gradle.kts,**/gradle.properties,**/AndroidManifest.xml,**/proguard-rules.pro,**/app/src/**,**/android/app/**,**/libs.versions.toml"
+tags: [implementation, lang:java]
+quality_charter: agents/shared/quality-charter.md
+cache_friendly: true
+---
+# Android Patterns
+
+**Pillars:** P2 (Scientific & Practical Quality), CQ8 (Maintainability Quality)
+
+> Applies when the project ships an Android app or Kotlin library. Detection signals: `build.gradle` / `build.gradle.kts`, `AndroidManifest.xml`, `app/` module, or any `*.kt` file paired with Gradle wrapper. Native Android takes precedence over Flutter/React-Native cross-platform shells.
+
+## Kotlin Language Floor
+
+- Target Kotlin 2.0+ with K2 compiler (`kotlin.experimental.tryK2=true`). Treat warnings as errors in CI.
+- Use `data class` for value-equality types, `sealed class` / `sealed interface` for closed-set hierarchies (UI state, events, errors). Exhaust `when` over sealed types — the compiler enforces it.
+- Coroutines + Flow for concurrency. Never use `Thread` directly. Wrap legacy callback APIs with `suspendCancellableCoroutine` at the boundary.
+- Nullability: explicit `?` for nullable types; avoid `!!` (force-unwrap) outside test fixtures. Platform types from Java interop annotated with `@Nullable` / `@NonNull` where possible.
+
+## Build Tooling
+
+- Android Gradle Plugin (AGP) 8.7+ with Gradle 8.10+. Use the version catalog (`gradle/libs.versions.toml`) for every dependency — no hard-coded versions in `build.gradle.kts`.
+- Kotlin DSL (`build.gradle.kts`) for new modules. Migrate Groovy scripts during regular refactors; do not mix dialects in a single module's chain.
+- Target SDK 35 (Android 15) — Google Play requires `targetSdk = 35` for new apps and updates in 2025. Set `compileSdk = 35` alongside.
+- Min SDK: 24 (Android 7.0) covers >97% of active devices per Android Distribution Dashboard. Going below 24 means losing modern Kotlin stdlib calls that require API 24.
+
+## Architecture
+
+- Pick ONE app-architecture pattern per app and document it in `docs/architecture.md`:
+  - **MVI / Unidirectional Data Flow with Compose + ViewModel + StateFlow** — recommended default.
+  - **MVVM with LiveData** — only for legacy apps that haven't migrated to Compose.
+- Modular Gradle structure: `app/` (entry point), `feature:<name>/` (feature modules), `core:<network|database|design-system>/` (shared modules). Cross-feature imports go through `core:` interfaces.
+- Composition root in `app/` wires Hilt graphs. Feature modules expose `@Module @InstallIn(SingletonComponent::class)` providers; they never instantiate dependencies directly.
+
+## Dependency Injection
+
+- Use Hilt for runtime DI (annotation-processor based, sits on top of Dagger). Configure `@HiltAndroidApp` on the `Application` class and `@AndroidEntryPoint` on Activities, Fragments, Services.
+- Constructor injection for ViewModels via `@HiltViewModel` + `@Inject constructor`. Do not use `ViewModelProvider.Factory` manually unless integrating with a non-Hilt host.
+- Scoped bindings: `@SingletonComponent` for app-wide singletons, `@ViewModelScoped` for per-ViewModel instances. Never share `@SingletonComponent` state with UI lifecycle.
+
+## Jetpack Compose
+
+- Compose is the UI floor for new screens. Migrate XML views during regular refactors; do not mix `ConstraintLayout` XML with Compose for a single screen.
+- State hoisting: `@Composable` functions are stateless by default. Hoist `MutableState` to the ViewModel; pass values + lambdas down.
+- Use `collectAsStateWithLifecycle()` on Flow → State conversions inside composables. Plain `collectAsState()` ignores lifecycle and leaks during backgrounded screens.
+- Recompose discipline: stable types only as composable parameters. Use `@Stable` / `@Immutable` annotations or `kotlinx-collections-immutable` for lists. `MutableList<T>` parameters force every consumer to recompose on any mutation.
+- Material 3 (`androidx.compose.material3`) is the design system floor for Compose. Material 2 is legacy.
+
+## Coroutines & Flow
+
+- Structured concurrency: every coroutine launched in a `CoroutineScope` tied to a lifecycle. Use `viewModelScope` (auto-cancels on `onCleared()`), `lifecycleScope` (auto-cancels on lifecycle destroy), and `WorkManager` for background tasks.
+- Never launch from `GlobalScope`. Never call `runBlocking` on the main thread.
+- Cold flows (`flow { }`, `flowOf`) for one-shot streams; hot flows (`MutableStateFlow`, `MutableSharedFlow`) for UI state and event buses. `LiveData` is legacy — use `StateFlow` for new code.
+- Use `Dispatchers.IO` for blocking I/O, `Dispatchers.Default` for CPU-bound work. The main dispatcher is for UI updates only; no blocking work there.
+
+## Persistence
+
+- Room is the SQL persistence floor. Define `@Entity`, `@Dao`, and a `@Database` class with a versioned schema. Migration paths via `Migration` objects committed to VCS.
+- DataStore (Preferences or Proto) for key-value and structured preferences. SharedPreferences is legacy — do not adopt for new code.
+- For network sync: WorkManager with `Constraints` (network, charging, battery) + exponential backoff. Never use `JobScheduler` directly — WorkManager wraps it and handles edge cases.
+- Bind Room DAOs and DataStore to coroutines / Flow — suspend functions for one-shot queries, `Flow<T>` for observed reads.
+
+## Networking
+
+- Use Retrofit 2.11+ with kotlinx-serialization-converter or Moshi (Gson is in maintenance — prefer one of the modern serializers). Configure OkHttp logging interceptor only in debug builds.
+- Ktor Client is the alternative when the app shares a multi-platform stack with Kotlin Multiplatform.
+- Configure timeouts on every OkHttp client: connect (10s), read (30s), write (15s). Default timeouts are unbounded — production apps must override.
+- Certificate pinning (`CertificatePinner`) for high-security endpoints. Always include a backup pin and a rotation schedule.
+
+## Testing
+
+- Unit tests with JUnit 5 (`org.junit.jupiter:junit-jupiter`) + MockK for mocking. JUnit 4 + Mockito is legacy — do not add for new modules.
+- Coroutine tests with `kotlinx-coroutines-test` (`runTest`, `TestDispatcher`). Never use `Thread.sleep` to wait for async work.
+- Compose UI tests with `androidx.compose.ui:ui-test-junit4`. Use semantics-based matchers (`hasContentDescription`, `hasTestTag`) — avoid text matchers for resilience.
+- Instrumented tests via `androidTest/` source set on emulators or Firebase Test Lab matrices. Configure `testCoverage` in the AGP block; floor 80% line coverage in `feature:` modules.
+- Screenshot tests via Paparazzi (host-side, no emulator needed) or Roborazzi. Update goldens through PR review.
+
+## Accessibility
+
+- Every interactive composable has `Modifier.semantics { contentDescription = "..." }` or uses Material 3 widgets that provide semantics by default.
+- TalkBack tested on every PR touching UI. The TalkBack-on screenshot test in Paparazzi catches regressions automatically.
+- Dynamic font scaling: respect `MaterialTheme.typography` and avoid hard-coded `.sp` values in layouts. Test with the largest accessibility font size in the system settings.
+- Touch targets: minimum 48dp × 48dp per Material 3 guidelines. `Modifier.minimumInteractiveComponentSize()` enforces this when composables are below 48dp.
+
+## Distribution
+
+- Sign release builds with Play App Signing — Google holds the upload key, you hold the signing key in escrow. Configure via Play Console.
+- App Bundle (`*.aab`) for Play Store, APK only for sideload / direct distribution. Enable `bundle { language { enableSplit = true } }`.
+- ProGuard / R8 on release builds (`isMinifyEnabled = true`, `isShrinkResources = true`). Maintain `proguard-rules.pro` per module; verify post-shrink builds in CI before publishing.
+- Use Crashlytics or Sentry for crash reporting. Symbolicate native crashes via NDK symbol upload in CI.
+
+## References
+
+- AGP 8.x release notes: https://developer.android.com/build/releases/gradle-plugin (accessed 2026-05-27, official-docs)
+- Jetpack Compose: https://developer.android.com/jetpack/compose (accessed 2026-05-27, official-docs)
+- Coroutines + Flow: https://kotlinlang.org/docs/coroutines-overview.html (accessed 2026-05-27, official-docs)
+- Google Play target SDK 35 requirement: https://developer.android.com/google/play/requirements/target-sdk (accessed 2026-05-27, official-docs)
+
+## Cross-References
+
+- `rules/hatch3r-component-conventions.md` — four-state surface contract maps to Compose `StateFlow<UiState>` patterns.
+- `rules/hatch3r-testing.md` — coverage thresholds and determinism rules apply to JUnit / Compose tests.
+- `rules/hatch3r-accessibility-standards.md` — WCAG mapping for Compose `semantics { ... }` modifiers.

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

@@ -0,0 +1,102 @@
+---
+description: Android Kotlin conventions covering Jetpack Compose, coroutines + Flow, Hilt DI, Room, modular Gradle, AGP 8.x, target SDK 35, and Compose testing
+globs: ["**/*.kt", "**/*.kts", "**/build.gradle", "**/build.gradle.kts", "**/settings.gradle", "**/settings.gradle.kts", "**/gradle.properties", "**/AndroidManifest.xml", "**/proguard-rules.pro", "**/app/src/**", "**/android/app/**", "**/libs.versions.toml"]
+alwaysApply: false
+---
+# Android Patterns
+
+**Pillars:** P2 (Scientific & Practical Quality), CQ8 (Maintainability Quality)
+
+> Applies when the project ships an Android app or Kotlin library. Detection signals: `build.gradle` / `build.gradle.kts`, `AndroidManifest.xml`, `app/` module, or any `*.kt` file paired with Gradle wrapper. Native Android takes precedence over Flutter/React-Native cross-platform shells.
+
+## Kotlin Language Floor
+
+- Target Kotlin 2.0+ with K2 compiler (`kotlin.experimental.tryK2=true`). Treat warnings as errors in CI.
+- Use `data class` for value-equality types, `sealed class` / `sealed interface` for closed-set hierarchies (UI state, events, errors). Exhaust `when` over sealed types — the compiler enforces it.
+- Coroutines + Flow for concurrency. Never use `Thread` directly. Wrap legacy callback APIs with `suspendCancellableCoroutine` at the boundary.
+- Nullability: explicit `?` for nullable types; avoid `!!` (force-unwrap) outside test fixtures. Platform types from Java interop annotated with `@Nullable` / `@NonNull` where possible.
+
+## Build Tooling
+
+- Android Gradle Plugin (AGP) 8.7+ with Gradle 8.10+. Use the version catalog (`gradle/libs.versions.toml`) for every dependency — no hard-coded versions in `build.gradle.kts`.
+- Kotlin DSL (`build.gradle.kts`) for new modules. Migrate Groovy scripts during regular refactors; do not mix dialects in a single module's chain.
+- Target SDK 35 (Android 15) — Google Play requires `targetSdk = 35` for new apps and updates in 2025. Set `compileSdk = 35` alongside.
+- Min SDK: 24 (Android 7.0) covers >97% of active devices per Android Distribution Dashboard. Going below 24 means losing modern Kotlin stdlib calls that require API 24.
+
+## Architecture
+
+- Pick ONE app-architecture pattern per app and document it in `docs/architecture.md`:
+  - **MVI / Unidirectional Data Flow with Compose + ViewModel + StateFlow** — recommended default.
+  - **MVVM with LiveData** — only for legacy apps that haven't migrated to Compose.
+- Modular Gradle structure: `app/` (entry point), `feature:<name>/` (feature modules), `core:<network|database|design-system>/` (shared modules). Cross-feature imports go through `core:` interfaces.
+- Composition root in `app/` wires Hilt graphs. Feature modules expose `@Module @InstallIn(SingletonComponent::class)` providers; they never instantiate dependencies directly.
+
+## Dependency Injection
+
+- Use Hilt for runtime DI (annotation-processor based, sits on top of Dagger). Configure `@HiltAndroidApp` on the `Application` class and `@AndroidEntryPoint` on Activities, Fragments, Services.
+- Constructor injection for ViewModels via `@HiltViewModel` + `@Inject constructor`. Do not use `ViewModelProvider.Factory` manually unless integrating with a non-Hilt host.
+- Scoped bindings: `@SingletonComponent` for app-wide singletons, `@ViewModelScoped` for per-ViewModel instances. Never share `@SingletonComponent` state with UI lifecycle.
+
+## Jetpack Compose
+
+- Compose is the UI floor for new screens. Migrate XML views during regular refactors; do not mix `ConstraintLayout` XML with Compose for a single screen.
+- State hoisting: `@Composable` functions are stateless by default. Hoist `MutableState` to the ViewModel; pass values + lambdas down.
+- Use `collectAsStateWithLifecycle()` on Flow → State conversions inside composables. Plain `collectAsState()` ignores lifecycle and leaks during backgrounded screens.
+- Recompose discipline: stable types only as composable parameters. Use `@Stable` / `@Immutable` annotations or `kotlinx-collections-immutable` for lists. `MutableList<T>` parameters force every consumer to recompose on any mutation.
+- Material 3 (`androidx.compose.material3`) is the design system floor for Compose. Material 2 is legacy.
+
+## Coroutines & Flow
+
+- Structured concurrency: every coroutine launched in a `CoroutineScope` tied to a lifecycle. Use `viewModelScope` (auto-cancels on `onCleared()`), `lifecycleScope` (auto-cancels on lifecycle destroy), and `WorkManager` for background tasks.
+- Never launch from `GlobalScope`. Never call `runBlocking` on the main thread.
+- Cold flows (`flow { }`, `flowOf`) for one-shot streams; hot flows (`MutableStateFlow`, `MutableSharedFlow`) for UI state and event buses. `LiveData` is legacy — use `StateFlow` for new code.
+- Use `Dispatchers.IO` for blocking I/O, `Dispatchers.Default` for CPU-bound work. The main dispatcher is for UI updates only; no blocking work there.
+
+## Persistence
+
+- Room is the SQL persistence floor. Define `@Entity`, `@Dao`, and a `@Database` class with a versioned schema. Migration paths via `Migration` objects committed to VCS.
+- DataStore (Preferences or Proto) for key-value and structured preferences. SharedPreferences is legacy — do not adopt for new code.
+- For network sync: WorkManager with `Constraints` (network, charging, battery) + exponential backoff. Never use `JobScheduler` directly — WorkManager wraps it and handles edge cases.
+- Bind Room DAOs and DataStore to coroutines / Flow — suspend functions for one-shot queries, `Flow<T>` for observed reads.
+
+## Networking
+
+- Use Retrofit 2.11+ with kotlinx-serialization-converter or Moshi (Gson is in maintenance — prefer one of the modern serializers). Configure OkHttp logging interceptor only in debug builds.
+- Ktor Client is the alternative when the app shares a multi-platform stack with Kotlin Multiplatform.
+- Configure timeouts on every OkHttp client: connect (10s), read (30s), write (15s). Default timeouts are unbounded — production apps must override.
+- Certificate pinning (`CertificatePinner`) for high-security endpoints. Always include a backup pin and a rotation schedule.
+
+## Testing
+
+- Unit tests with JUnit 5 (`org.junit.jupiter:junit-jupiter`) + MockK for mocking. JUnit 4 + Mockito is legacy — do not add for new modules.
+- Coroutine tests with `kotlinx-coroutines-test` (`runTest`, `TestDispatcher`). Never use `Thread.sleep` to wait for async work.
+- Compose UI tests with `androidx.compose.ui:ui-test-junit4`. Use semantics-based matchers (`hasContentDescription`, `hasTestTag`) — avoid text matchers for resilience.
+- Instrumented tests via `androidTest/` source set on emulators or Firebase Test Lab matrices. Configure `testCoverage` in the AGP block; floor 80% line coverage in `feature:` modules.
+- Screenshot tests via Paparazzi (host-side, no emulator needed) or Roborazzi. Update goldens through PR review.
+
+## Accessibility
+
+- Every interactive composable has `Modifier.semantics { contentDescription = "..." }` or uses Material 3 widgets that provide semantics by default.
+- TalkBack tested on every PR touching UI. The TalkBack-on screenshot test in Paparazzi catches regressions automatically.
+- Dynamic font scaling: respect `MaterialTheme.typography` and avoid hard-coded `.sp` values in layouts. Test with the largest accessibility font size in the system settings.
+- Touch targets: minimum 48dp × 48dp per Material 3 guidelines. `Modifier.minimumInteractiveComponentSize()` enforces this when composables are below 48dp.
+
+## Distribution
+
+- Sign release builds with Play App Signing — Google holds the upload key, you hold the signing key in escrow. Configure via Play Console.
+- App Bundle (`*.aab`) for Play Store, APK only for sideload / direct distribution. Enable `bundle { language { enableSplit = true } }`.
+- ProGuard / R8 on release builds (`isMinifyEnabled = true`, `isShrinkResources = true`). Maintain `proguard-rules.pro` per module; verify post-shrink builds in CI before publishing.
+- Use Crashlytics or Sentry for crash reporting. Symbolicate native crashes via NDK symbol upload in CI.
+
+## References
+
+- AGP 8.x release notes: https://developer.android.com/build/releases/gradle-plugin (accessed 2026-05-27, official-docs)
+- Jetpack Compose: https://developer.android.com/jetpack/compose (accessed 2026-05-27, official-docs)
+- Coroutines + Flow: https://kotlinlang.org/docs/coroutines-overview.html (accessed 2026-05-27, official-docs)
+- Google Play target SDK 35 requirement: https://developer.android.com/google/play/requirements/target-sdk (accessed 2026-05-27, official-docs)
+
+## Cross-References
+
+- `rules/hatch3r-component-conventions.md` — four-state surface contract maps to Compose `StateFlow<UiState>` patterns.
+- `rules/hatch3r-testing.md` — coverage thresholds and determinism rules apply to JUnit / Compose tests.
+- `rules/hatch3r-accessibility-standards.md` — WCAG mapping for Compose `semantics { ... }` modifiers.

package/dist/content/rules/hatch3r-anti-duplication.md

@@ -0,0 +1,115 @@
+---
+id: hatch3r-anti-duplication
+type: rule
+description: Pre-implementation discovery gate (codebase pattern search) + post-write duplication scan (jscpd threshold per maturity tier). Silent duplication is a P4 violation.
+tags: [anti-duplication, code-quality, floor:content-quality]
+precedence: high
+scope: always
+---
+# hatch3r Anti-Duplication
+
+**Pillars:** P4 (Comprehensive Lean Coverage), CQ8 (Maintainability Quality)
+
+## Pre-Implementation Discovery Gate
+
+Before writing any new function, type, or pattern:
+
+1. **Grep existing surface** for similar function names: `grep -rn "function.*<similar-name>" src/`
+2. **Grep existing surface** for similar type shapes: `grep -rn "type.*<similar-shape>" src/`
+3. **Grep existing surface** for similar comment headers: `grep -rn "// <similar-purpose>" src/`
+4. **Read closest existing match** end-to-end to confirm it does NOT cover the new requirement.
+
+If a similar artifact exists with ≥80% scope overlap, do one of:
+
+- Extend the existing artifact with the additional case.
+- Refactor into a shared abstraction consumed by both.
+- Document the distinct scope as an ADR before authoring the new artifact.
+
+Report findings of the discovery scan in the iteration summary §Files Mutated section.
+
+## Post-Write Duplication Scan
+
+After every implementation:
+
+1. Run `npx jscpd <changed-dirs>` (or equivalent: PMD CPD, simian, sonar-scanner).
+2. Flag any block matching ≥30 lines OR ≥80% similarity with existing code.
+3. Refactor or justify before merge.
+
+Tools accepted as equivalent: `jscpd` (Node), `PMD CPD` (Java/multi-lang), `simian` (multi-lang), `sonar-scanner` duplication module. Pick by toolchain; the threshold below is tool-agnostic.
+
+## Tunable Thresholds Per Maturity Tier
+
+Per `hatch3r config maturity=<tier>`:
+
+- **solo** — jscpd threshold ≤10% (relaxed for early-stage exploration)
+- **team** — jscpd threshold ≤7%
+- **scaleup** — jscpd threshold ≤5%
+- **enterprise** — jscpd threshold ≤3%
+
+Tier set via `hatch3r config maturity=<tier>` per CONSTITUTION §6 Decision #16 (Decision 4 in fresh-session-prompt mapping). Threshold breach blocks merge until the offending block is refactored or justified with an inline ADR comment.
+
+## Silent Duplication Violation
+
+Per CONSTITUTION §2 P4: Single Source of Truth. Silent duplication (no ADR, no refactor) is a P4 violation surfaced by D16 Compound System audit + D22 Content Architecture audit (after authoring).
+
+Per CONSTITUTION §2 P5 Silent Failure Contract: a duplication scan that finds matches but emits no warning to the caller is itself a contract violation — the scan must surface findings via the iteration summary or a CI gate.
+
+## Discovery Gate Output Schema
+
+Report from the pre-implementation grep step lands in the iteration summary as:
+
+```
+discovery_scan:
+  greps_run: <integer>
+  candidate_matches: <integer>
+  closest_match_path: <relative-path>
+  overlap_assessment: none | partial | high (≥80%)
+  decision: new-artifact | extend-existing | refactor-shared | adr-distinct
+```
+
+`overlap_assessment: high` without `decision: extend-existing | refactor-shared | adr-distinct` is a P4 violation — author is creating a duplicate.
+
+## Worked Example
+
+Task: add a function that formats an ISO-8601 timestamp for a CLI log line.
+
+1. Discovery grep: `grep -rn "function format.*Date\|function format.*Time\|function format.*Timestamp" src/`.
+2. Closest match found: `src/cli/util/format.ts::formatLocalTime(date: Date): string` — 11 lines, formats `HH:mm:ss` only.
+3. Overlap assessment: `partial` — same domain (date formatting) but distinct output shape (timestamp vs time-of-day).
+4. Decision: `extend-existing` — add a `format: "iso" | "local"` parameter to `formatLocalTime`, rename to `formatTime`, update 3 callers.
+5. Post-write scan: `npx jscpd src/cli/util/` reports 0% duplication on the change. Merge.
+
+The discovery step took ~30 seconds; it prevented a parallel `formatIsoTimestamp` function and a forked test file.
+
+## Skip Conditions
+
+The discovery + scan procedure binds every code-writing turn EXCEPT:
+
+- Single-line edits to existing functions (bug fix, typo, error-message wording).
+- Frontmatter-only edits to canonical content artifacts.
+- Test-file edits that mirror an existing source-file change (the test mirrors a function the discovery step already ran on).
+- Cosmetic edits (whitespace, comment wording, import sorting).
+
+When skipped, declare `discovery_scan: skipped (reason: <reason>)` in the iteration summary. Skipping without declaration is itself a P5 silent-failure violation per CONSTITUTION §2 P5 Silent Failure Contract.
+
+## Enforcement
+
+- `agents/shared/quality-charter.md` §12 binds every agent to this procedure.
+- `agents/hatch3r-implementer.md` runs the discovery gate before writing.
+- `agents/hatch3r-reviewer.md` runs the duplication scan in review.
+- The compound-system and content-architecture audit domains audit duplication at cycle time.
+
+## Pillar Service
+
+- P4 — every artifact earns its existence; no redundant code or content.
+- CQ8 — generated code carries the same anti-duplication discipline (jscpd ≤5% per CONSTITUTION §2 CQ8 Measurement).
+
+## References
+
+- CONSTITUTION §6 Decision #21 (pre-implementation discovery + post-write duplication scan).
+- CONSTITUTION §6 Decision #16 (maturity tier `solo|team|scaleup|enterprise`).
+- CONSTITUTION §2 P4 (Single Source of Truth).
+- CONSTITUTION §2 CQ8 (Maintainability Measurement — jscpd ≤5% per cycle).
+- `agents/shared/quality-charter.md` §12 (Anti-Duplication Procedure).
+- The compound-system audit domain (duplication candidate threshold SA 16.3).
+- The content-architecture audit domain (content-corpus duplication audit; authored in subsequent cycle).

package/dist/content/rules/hatch3r-anti-duplication.mdc

@@ -0,0 +1,115 @@
+---
+id: hatch3r-anti-duplication
+type: rule
+description: Pre-implementation discovery gate (codebase pattern search) + post-write duplication scan (jscpd threshold per maturity tier). Silent duplication is a P4 violation.
+tags: [anti-duplication, code-quality, floor:content-quality]
+precedence: high
+alwaysApply: true
+---
+# hatch3r Anti-Duplication
+
+**Pillars:** P4 (Comprehensive Lean Coverage), CQ8 (Maintainability Quality)
+
+## Pre-Implementation Discovery Gate
+
+Before writing any new function, type, or pattern:
+
+1. **Grep existing surface** for similar function names: `grep -rn "function.*<similar-name>" src/`
+2. **Grep existing surface** for similar type shapes: `grep -rn "type.*<similar-shape>" src/`
+3. **Grep existing surface** for similar comment headers: `grep -rn "// <similar-purpose>" src/`
+4. **Read closest existing match** end-to-end to confirm it does NOT cover the new requirement.
+
+If a similar artifact exists with ≥80% scope overlap, do one of:
+
+- Extend the existing artifact with the additional case.
+- Refactor into a shared abstraction consumed by both.
+- Document the distinct scope as an ADR before authoring the new artifact.
+
+Report findings of the discovery scan in the iteration summary §Files Mutated section.
+
+## Post-Write Duplication Scan
+
+After every implementation:
+
+1. Run `npx jscpd <changed-dirs>` (or equivalent: PMD CPD, simian, sonar-scanner).
+2. Flag any block matching ≥30 lines OR ≥80% similarity with existing code.
+3. Refactor or justify before merge.
+
+Tools accepted as equivalent: `jscpd` (Node), `PMD CPD` (Java/multi-lang), `simian` (multi-lang), `sonar-scanner` duplication module. Pick by toolchain; the threshold below is tool-agnostic.
+
+## Tunable Thresholds Per Maturity Tier
+
+Per `hatch3r config maturity=<tier>`:
+
+- **solo** — jscpd threshold ≤10% (relaxed for early-stage exploration)
+- **team** — jscpd threshold ≤7%
+- **scaleup** — jscpd threshold ≤5%
+- **enterprise** — jscpd threshold ≤3%
+
+Tier set via `hatch3r config maturity=<tier>` per CONSTITUTION §6 Decision #16 (Decision 4 in fresh-session-prompt mapping). Threshold breach blocks merge until the offending block is refactored or justified with an inline ADR comment.
+
+## Silent Duplication Violation
+
+Per CONSTITUTION §2 P4: Single Source of Truth. Silent duplication (no ADR, no refactor) is a P4 violation surfaced by D16 Compound System audit + D22 Content Architecture audit (after authoring).
+
+Per CONSTITUTION §2 P5 Silent Failure Contract: a duplication scan that finds matches but emits no warning to the caller is itself a contract violation — the scan must surface findings via the iteration summary or a CI gate.
+
+## Discovery Gate Output Schema
+
+Report from the pre-implementation grep step lands in the iteration summary as:
+
+```
+discovery_scan:
+  greps_run: <integer>
+  candidate_matches: <integer>
+  closest_match_path: <relative-path>
+  overlap_assessment: none | partial | high (≥80%)
+  decision: new-artifact | extend-existing | refactor-shared | adr-distinct
+```
+
+`overlap_assessment: high` without `decision: extend-existing | refactor-shared | adr-distinct` is a P4 violation — author is creating a duplicate.
+
+## Worked Example
+
+Task: add a function that formats an ISO-8601 timestamp for a CLI log line.
+
+1. Discovery grep: `grep -rn "function format.*Date\|function format.*Time\|function format.*Timestamp" src/`.
+2. Closest match found: `src/cli/util/format.ts::formatLocalTime(date: Date): string` — 11 lines, formats `HH:mm:ss` only.
+3. Overlap assessment: `partial` — same domain (date formatting) but distinct output shape (timestamp vs time-of-day).
+4. Decision: `extend-existing` — add a `format: "iso" | "local"` parameter to `formatLocalTime`, rename to `formatTime`, update 3 callers.
+5. Post-write scan: `npx jscpd src/cli/util/` reports 0% duplication on the change. Merge.
+
+The discovery step took ~30 seconds; it prevented a parallel `formatIsoTimestamp` function and a forked test file.
+
+## Skip Conditions
+
+The discovery + scan procedure binds every code-writing turn EXCEPT:
+
+- Single-line edits to existing functions (bug fix, typo, error-message wording).
+- Frontmatter-only edits to canonical content artifacts.
+- Test-file edits that mirror an existing source-file change (the test mirrors a function the discovery step already ran on).
+- Cosmetic edits (whitespace, comment wording, import sorting).
+
+When skipped, declare `discovery_scan: skipped (reason: <reason>)` in the iteration summary. Skipping without declaration is itself a P5 silent-failure violation per CONSTITUTION §2 P5 Silent Failure Contract.
+
+## Enforcement
+
+- `agents/shared/quality-charter.md` §12 binds every agent to this procedure.
+- `agents/hatch3r-implementer.md` runs the discovery gate before writing.
+- `agents/hatch3r-reviewer.md` runs the duplication scan in review.
+- The compound-system and content-architecture audit domains audit duplication at cycle time.
+
+## Pillar Service
+
+- P4 — every artifact earns its existence; no redundant code or content.
+- CQ8 — generated code carries the same anti-duplication discipline (jscpd ≤5% per CONSTITUTION §2 CQ8 Measurement).
+
+## References
+
+- CONSTITUTION §6 Decision #21 (pre-implementation discovery + post-write duplication scan).
+- CONSTITUTION §6 Decision #16 (maturity tier `solo|team|scaleup|enterprise`).
+- CONSTITUTION §2 P4 (Single Source of Truth).
+- CONSTITUTION §2 CQ8 (Maintainability Measurement — jscpd ≤5% per cycle).
+- `agents/shared/quality-charter.md` §12 (Anti-Duplication Procedure).
+- The compound-system audit domain (duplication candidate threshold SA 16.3).
+- The content-architecture audit domain (content-corpus duplication audit; authored in subsequent cycle).

package/dist/content/rules/hatch3r-api-design.md

@@ -2,13 +2,17 @@
 id: hatch3r-api-design
 type: rule
 description: REST, GraphQL, and gRPC contract patterns covering versioning, auth, CORS, pagination, webhooks, rate limiting, and security headers
-scope: "**/api/**,**/routes/**,**/controllers/**,**/endpoints/**,**/*route*,**/*controller*,**/*endpoint*,**/*handler*,**/graphql/**,**/trpc/**"
+scope: conditional
+globs: "**/api/**,**/routes/**,**/controllers/**,**/endpoints/**,**/*route*,**/*controller*,**/*endpoint*,**/*handler*,**/graphql/**,**/trpc/**"
 tags: [planning]
+precedence: high
 quality_charter: agents/shared/quality-charter.md
 cache_friendly: true
 ---
 # API Design
 
+**Pillars:** P2 (Scientific & Practical Quality), CQ9 (Enhancability Quality)
+
 - Use consistent request/response schemas. Document in spec files.
 - All endpoints versioned (URL prefix or header). Backward-compatible changes only.
 - Additive changes only: add fields, never rename or remove without migration.

package/dist/content/rules/hatch3r-api-design.mdc

@@ -2,9 +2,12 @@
 description: REST, GraphQL, and gRPC contract patterns covering versioning, auth, CORS, pagination, webhooks, rate limiting, and security headers
 globs: ["**/api/**", "**/routes/**", "**/controllers/**", "**/endpoints/**", "**/*route*", "**/*controller*", "**/*endpoint*", "**/*handler*", "**/graphql/**", "**/trpc/**"]
 alwaysApply: false
+precedence: high
 ---
 # API Design
 
+**Pillars:** P2 (Scientific & Practical Quality), CQ9 (Enhancability Quality)
+
 - Use consistent request/response schemas. Document in spec files.
 - All endpoints versioned (URL prefix or header). Backward-compatible changes only.
 - Additive changes only: add fields, never rename or remove without migration.

package/dist/content/rules/hatch3r-api-versioning.md

@@ -2,7 +2,8 @@
 id: hatch3r-api-versioning
 type: rule
 description: API versioning, deprecation lifecycle, and idempotency — RFC 9457 errors, RFC 9745 Deprecation header, RFC 8594 Sunset, OAuth 2.1, Idempotency-Key, semver vs CalVer for APIs
-scope: "**/api/**,**/openapi*,**/asyncapi*,**/*.proto,**/routes/**,**/handlers/**,**/controllers/**"
+scope: conditional
+globs: "**/api/**,**/openapi*,**/asyncapi*,**/*.proto,**/routes/**,**/handlers/**,**/controllers/**"
 tags: [implementation, devops]
 precedence: high
 quality_charter: agents/shared/quality-charter.md

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

@@ -2,7 +2,8 @@
 id: hatch3r-auth-patterns
 type: rule
 description: Authentication and authorization patterns for end-user apps — OAuth 2.1, OIDC, DPoP, JWT rotation, cookie security, RBAC vs ABAC vs ReBAC rubric
-scope: "**/auth/**,**/login/**,**/session/**,**/oauth/**,**/oidc/**,**/jwt/**,**/permissions/**,**/policies/**,**/middleware/**"
+scope: conditional
+globs: "**/auth/**,**/login/**,**/session/**,**/oauth/**,**/oidc/**,**/jwt/**,**/permissions/**,**/policies/**,**/middleware/**"
 tags: [implementation, floor:security]
 precedence: high
 quality_charter: agents/shared/quality-charter.md
@@ -151,6 +152,7 @@ Required event set: login success, login failure, MFA challenge issued, MFA veri
 
 ## Cross-References
 
+- `rules/hatch3r-security-patterns.md` — general application security (input validation, output encoding, OWASP/ASI). Auth middleware, token validation, session security, and MFA/AAL mapping live here, not there; security-patterns delegates them to this rule to avoid double-firing on `**/auth/**` + `**/middleware/**`.
 - `rules/hatch3r-passkey-server.md` — server-side WebAuthn ceremony (paired companion).
 - `rules/hatch3r-ux-states-and-flows.md` — frontend identifier-first login + Conditional UI.
 - `rules/hatch3r-ai-ux-patterns.md` — frontend WebAuthn UX patterns.

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

@@ -147,6 +147,7 @@ Required event set: login success, login failure, MFA challenge issued, MFA veri
 
 ## Cross-References
 
+- `rules/hatch3r-security-patterns.md` — general application security (input validation, output encoding, OWASP/ASI). Auth middleware, token validation, session security, and MFA/AAL mapping live here, not there; security-patterns delegates them to this rule to avoid double-firing on `**/auth/**` + `**/middleware/**`.
 - `rules/hatch3r-passkey-server.md` — server-side WebAuthn ceremony (paired companion).
 - `rules/hatch3r-ux-states-and-flows.md` — frontend identifier-first login + Conditional UI.
 - `rules/hatch3r-ai-ux-patterns.md` — frontend WebAuthn UX patterns.

package/dist/content/rules/hatch3r-browser-verification.md

@@ -10,6 +10,8 @@ cache_friendly: true
 ---
 # Browser Verification
 
+**Pillars:** P2 (Scientific & Practical Quality), CQ1 (UI Quality)
+
 ## When Required
 
 Browser verification is required when changes touch user-facing surfaces:

package/dist/content/rules/hatch3r-browser-verification.mdc

@@ -5,6 +5,8 @@ alwaysApply: false
 ---
 # Browser Verification
 
+**Pillars:** P2 (Scientific & Practical Quality), CQ1 (UI Quality)
+
 ## When Required
 
 Browser verification is required when changes touch user-facing surfaces: