hatch3r 1.8.0 → 2.0.0

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/{rules → 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/{rules → 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/{rules → dist/content/rules}/hatch3r-api-versioning.md

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

package/{rules → dist/content/rules}/hatch3r-api-versioning.mdc

@@ -2,6 +2,7 @@
 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
 globs: ["**/api/**", "**/openapi*", "**/asyncapi*", "**/*.proto", "**/routes/**", "**/handlers/**", "**/controllers/**"]
 alwaysApply: false
+precedence: high
 ---
 # API Versioning, Deprecation & Idempotency
 

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

@@ -2,8 +2,10 @@
 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/**"
-tags: [security, implementation]
+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
 cache_friendly: true
 ---
@@ -150,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/{rules → dist/content/rules}/hatch3r-auth-patterns.mdc

@@ -2,6 +2,7 @@
 description: Authentication and authorization patterns for end-user apps — OAuth 2.1, OIDC, DPoP, JWT rotation, cookie security, RBAC vs ABAC vs ReBAC rubric
 globs: ["**/auth/**", "**/login/**", "**/session/**", "**/oauth/**", "**/oidc/**", "**/jwt/**", "**/permissions/**", "**/policies/**", "**/middleware/**"]
 alwaysApply: false
+precedence: high
 ---
 # Authentication & Authorization Patterns
 
@@ -146,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/{rules → 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:
@@ -48,16 +50,12 @@ Browser verification is opt-in per command session. The orchestrator follows a s
 | Supports Browser Verification | Does NOT Support |
 | ------------------------------ | ---------------- |
 | `hatch3r-workflow` | `hatch3r-board-fill` |
-| `hatch3r-board-pickup` | `hatch3r-board-groom` |
-| `hatch3r-quick-change` | `hatch3r-board-refresh` |
-| `hatch3r-revision` | `hatch3r-roadmap` |
-| `hatch3r-debug` | `hatch3r-release` |
-| | `hatch3r-refactor-plan` |
-| | `hatch3r-security-audit` |
-| | `hatch3r-rule-customize` |
-| | `hatch3r-skill-customize` |
-
-Commands in the "Does NOT Support" column are documentation-only, planning-only, or non-implementation commands. They MUST NOT prompt for browser verification.
+| `hatch3r-board-pickup` | `hatch3r-roadmap` |
+| `hatch3r-quick-change` | `hatch3r-refactor-plan` |
+| `hatch3r-revision` | `hatch3r-security-audit` |
+| `hatch3r-debug` | |
+
+Commands in the "Does NOT Support" column are documentation-only, planning-only, or non-implementation commands. They MUST NOT prompt for browser verification. Skills (including `hatch3r-board-groom`, `hatch3r-board-refresh`, `hatch3r-release`) are invoked outside the orchestrator command lifecycle and therefore do not prompt for browser verification.
 
 ---
 

package/{rules → 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:
@@ -43,16 +45,12 @@ Browser verification is opt-in per command session. The orchestrator follows a s
 | Supports Browser Verification | Does NOT Support |
 | ------------------------------ | ---------------- |
 | `hatch3r-workflow` | `hatch3r-board-fill` |
-| `hatch3r-board-pickup` | `hatch3r-board-groom` |
-| `hatch3r-quick-change` | `hatch3r-board-refresh` |
-| `hatch3r-revision` | `hatch3r-roadmap` |
-| `hatch3r-debug` | `hatch3r-release` |
-| | `hatch3r-refactor-plan` |
-| | `hatch3r-security-audit` |
-| | `hatch3r-rule-customize` |
-| | `hatch3r-skill-customize` |
-
-Commands in the "Does NOT Support" column are documentation-only, planning-only, or non-implementation commands. They MUST NOT prompt for browser verification.
+| `hatch3r-board-pickup` | `hatch3r-roadmap` |
+| `hatch3r-quick-change` | `hatch3r-refactor-plan` |
+| `hatch3r-revision` | `hatch3r-security-audit` |
+| `hatch3r-debug` | |
+
+Commands in the "Does NOT Support" column are documentation-only, planning-only, or non-implementation commands. They MUST NOT prompt for browser verification. Skills (including `hatch3r-board-groom`, `hatch3r-board-refresh`, `hatch3r-release`) are invoked outside the orchestrator command lifecycle and therefore do not prompt for browser verification.
 
 ---
 

package/dist/content/rules/hatch3r-capability-matrix.md

@@ -0,0 +1,108 @@
+---
+id: hatch3r-capability-matrix
+type: rule
+description: Per-cycle adapter capability matrix audit — twin metric currency + utilization. Surfaces unutilized platform-native features per adapter each cycle.
+tags: [adapters, currency, capability, floor:content-quality]
+precedence: high
+scope: conditional
+globs: "src/adapters/**,docs/adapter-capability-matrix.md"
+---
+# hatch3r Capability Matrix
+
+**Pillars:** P3 (Adapter & External Tool Currency), CQ9 (Enhancability Quality)
+
+## Twin Metric Model
+
+Per cycle, every adapter (`src/adapters/{claude,cursor,copilot}.ts`) is measured on two metrics:
+
+1. **Currency** — platform documentation date vs audit date delta (target ≤90 days)
+2. **Capability utilization** — (covered platform features / total platform features) per adapter
+
+Both metrics surface to D09 audit findings. Currency stale >90 days = Medium; capability utilization regression cycle-over-cycle = Medium.
+
+## Capability Discovery Procedure
+
+For each adapter, per cycle:
+
+1. **Web-research** the platform's current documentation
+2. **Enumerate native capabilities** in a normalised list: hooks, slash commands, MCP support, agent definitions, settings schema, rule format, prompt format, etc.
+3. **Map current adapter utilization** per capability:
+   - **utilized** — adapter emits / consumes this capability
+   - **partially-utilized** — adapter emits a subset; gap documented
+   - **unutilized** — capability exists, adapter does not use it
+4. **Cross-reference** `docs/adapter-capability-matrix.md` static reference doc
+5. **Surface unutilized capabilities** as audit findings (Info or Medium per value)
+
+## Output Schema
+
+```yaml
+adapter: claude | cursor | copilot
+cycle: <N>
+date: YYYY-MM-DD
+currency:
+  source_doc_date: YYYY-MM-DD
+  audit_date: YYYY-MM-DD
+  delta_days: <int>
+  source_url: https://...
+capabilities:
+  - name: <feature name>
+    status: utilized | partially-utilized | unutilized
+    coverage: <0.0-1.0 ratio if partially-utilized>
+    finding_id: <if surfaced>
+utilization_ratio: <int>/<int>  # covered / total
+```
+
+## Capability Categories (Per Adapter)
+
+Each adapter's native capability surface enumerates across these categories — D09 SA-{Cursor, Claude, Copilot} maps each category per cycle:
+
+| Category | Claude Code | Cursor | GitHub Copilot |
+|----------|-------------|--------|----------------|
+| Hooks / events | `.claude/settings.json` hooks (Pre/PostToolUse, SessionStart, etc.) | `.cursor/hooks/` | `.github/workflows/` agentic triggers |
+| Slash commands | `.claude/commands/*.md` | `.cursor/commands/*.md` | `.github/prompts/*.md` |
+| Agent definitions | `.claude/agents/*.md` | `.cursor/agents/*.md` | `.github/agents/*.md` |
+| Rule format | `.claude/rules/*.md` | `.cursor/rules/*.mdc` | `.github/instructions/*.md` |
+| MCP support | `.mcp.json` | `.cursor/mcp.json` | (limited / via VS Code settings) |
+| Tool allowlist | per-agent `tools:` frontmatter | per-agent `tools:` | per-instruction file scope |
+| Settings schema | `.claude/settings.json` | `.cursor/settings.json` | `.github/copilot-instructions.md` |
+
+Each capability resolves to one of: utilized, partially-utilized, unutilized. Per-adapter SA cites the platform's official documentation URL + access date when classifying.
+
+## Adapter-Capability-Matrix Static Reference
+
+`docs/adapter-capability-matrix.md` is a maintained per-adapter feature table. The audit verifies the live matrix against the static doc and flags drift in either direction.
+
+## Drift Detection
+
+Per-cycle delta computation:
+
+1. Load prior cycle's matrix from the audit execution-insights store (key `d9_adapter_capability_matrix.{adapter}`) — this key is populated by the platform-adapters domain SA 9.4 synthesis agent at the end of each cycle that audits this matrix. On the first cycle that runs this procedure the key is absent: skip steps 2-3 (no prior baseline) and record the current matrix as the baseline for next cycle.
+2. Compute `utilization_ratio` delta cycle-over-cycle
+3. Regression (current < prior) = Medium finding with root-cause analysis required
+4. Currency `delta_days > 90` = Medium finding per P3
+5. Currency `delta_days > 180` = High finding (compounded staleness)
+
+## CL-2 Routing for Unutilized Capabilities
+
+D09 SA 9.4 (Capability Matrix Verification, SEQUENTIAL) aggregates unutilized capabilities across the 3 adapters and surfaces the top 3-5 highest-value gaps as CL-2 candidates for next-cycle adapter enhancement. Value scoring criteria:
+
+- **High value:** capability unlocks a content type already in canonical corpus (e.g., MCP transport that lets canonical MCP rules emit natively)
+- **Medium value:** capability improves end-user runtime efficiency (P7) or trust (P6) on emitted output
+- **Low value:** capability has unclear end-user benefit; document and re-evaluate next cycle
+
+## Cross-Reference
+
+- The platform-adapters audit domain — its per-adapter SA-{Cursor, Claude, Copilot} per cycle runs this procedure
+- The CLI-tool-currency audit domain — sibling cycle for CLI tool currency
+- `.claude/rules/adapter-development.md` — adapter authoring conventions
+
+## Pillar Service
+- P3 — currency + utilization measured every cycle, no implicit drift
+- CQ9 — every platform feature is a potential enhancement surface; this audit surfaces them
+
+## References
+
+- Anthropic, *Claude Code: hooks, agents, settings* — https://docs.claude.com/en/docs/claude-code/ (accessed 2026-05-26, trust tier: official-docs)
+- Cursor, *Cursor docs: rules, agents, MCP* — https://cursor.com/docs (accessed 2026-05-26, trust tier: official-docs)
+- GitHub, *Copilot custom instructions and prompts* — https://docs.github.com/en/copilot/customizing-copilot (accessed 2026-05-26, trust tier: official-docs)
+