hatch3r 1.8.0 → 2.0.0

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

@@ -1,7 +1,8 @@
 ---
 description: Security patterns including input validation, auth enforcement, and AI/agentic security for the project
-globs: ["**/auth/**", "**/security/**", "**/middleware/**", "**/*auth*", "**/*guard*", "**/*policy*", "**/*permission*", "**/*sanitiz*", "**/*validat*"]
+globs: ["**/security/**", "**/*guard*", "**/*policy*", "**/*permission*", "**/*sanitiz*", "**/*validat*"]
 alwaysApply: false
+precedence: critical
 ---
 # Security Patterns
 
@@ -24,12 +25,7 @@ alwaysApply: false
 
 ## Authentication Enforcement
 
-- Auth middleware on every route by default. Public routes require explicit opt-out with code review justification.
-- Token validation: pin allowed algorithms (reject `none`), enforce expiry (`exp`), verify audience (`aud`) and issuer (`iss`) claims. Reject tokens failing any check.
-- Session security: `HttpOnly`, `Secure`, `SameSite=Strict` (or `Lax` with justification) cookies. Rotate session ID on privilege change (login, role switch).
-- Multi-factor authentication for sensitive operations: admin actions, payment, account deletion, API key generation.
-- Rate-limit authentication endpoints (login, token refresh, password reset). Lock accounts or add progressive delays after repeated failures.
-- Invalidate all sessions on password change. Provide "sign out everywhere" capability.
+Authentication and authorization patterns (auth middleware, token validation, session security, MFA/AAL mapping, rate-limiting auth endpoints) are owned canonically by `rules/hatch3r-auth-patterns.md`. That rule activates on `**/auth/**`, `**/login/**`, `**/session/**`, `**/middleware/**`, and related globs; this rule no longer restates them, so the two no longer double-fire on the same files. For OWASP A07 in the web-app context see the §A07 section below.
 
 ## Fail-Closed Defaults
 
@@ -133,6 +129,8 @@ alwaysApply: false
 
 ## OWASP Top 10 2025 (Web Application Security)
 
+Subsection order and titles follow the official OWASP Top 10:2025 release (https://owasp.org/Top10/2025/, accessed 2026-06-05). The 2025 list reorders the 2021 set: Security Misconfiguration rises to A02, A03 becomes Software Supply Chain Failures (an expansion of 2021's Vulnerable and Outdated Components), and Injection moves to A05.
+
 ### A01 — Broken Access Control
 
 - Enforce access control server-side. Client-side checks are UX, not security.
@@ -142,7 +140,32 @@ alwaysApply: false
 - Rate-limit API access to minimize automated IDOR scanning and credential stuffing.
 - Log access control failures and alert on repeated violations from the same identity.
 
-### A02 — Cryptographic Failures
+### A02 — Security Misconfiguration
+
+- Harden all environments: remove default accounts, disable unused features/ports/services, remove sample applications.
+- Use identical security configuration across development, staging, and production. Differences in security settings between environments mask vulnerabilities.
+- Automate configuration verification: infrastructure-as-code with security baselines, configuration scanning in CI.
+- Send security headers on every response (HSTS, CSP, X-Content-Type-Options, X-Frame-Options). Centralize in middleware.
+- Review cloud permissions quarterly. Remove unused IAM roles, security groups, and service accounts.
+- Disable detailed error messages in production. Use generic error responses with correlation IDs for debugging.
+
+### A03 — Software Supply Chain Failures
+
+Expands 2021's Vulnerable and Outdated Components to cover the full dependency, build, and distribution chain — third-party code, build tools, CI/CD systems, and package registries.
+
+- Maintain a software bill of materials (SBOM) for all direct and transitive dependencies.
+- Run `npm audit` (or equivalent) in CI on every build. Block merges with critical or high vulnerabilities.
+- Subscribe to security advisories for all critical dependencies using the platform's built-in tools or third-party equivalents:
+  - **GitHub:** Dependabot alerts and security advisories
+  - **Azure DevOps:** Microsoft Defender for DevOps or WhiteSource/Mend integration
+  - **GitLab:** GitLab Dependency Scanning CI template, or Snyk integration
+- Remove unused dependencies. Unused code with known vulnerabilities is still a risk.
+- Pin dependency versions in lockfiles. Review lockfile changes in PRs with the same scrutiny as code changes.
+- Verify package provenance: prefer signed packages, scoped registries, and `npm ci` over `npm install`. Reject `npx -y` on untrusted names (typosquatting / dependency confusion).
+- Harden the build pipeline itself: pin CI actions by commit SHA, restrict who can modify pipeline config, and treat build secrets as production credentials.
+- Establish SLAs for vulnerability remediation: critical within 24 hours, high within 1 week, moderate within 1 sprint.
+
+### A04 — Cryptographic Failures
 
 - Classify data by sensitivity (PII, financial, health, credentials). Apply encryption requirements per classification.
 - Encrypt data in transit (TLS 1.2+ mandatory, prefer 1.3) and at rest (AES-256 or equivalent).
@@ -151,7 +174,7 @@ alwaysApply: false
 - Generate cryptographic keys with secure random sources (`crypto.randomBytes`, not `Math.random`). Never hard-code keys or IVs.
 - Disable caching for responses containing sensitive data (`Cache-Control: no-store`).
 
-### A03 — Injection
+### A05 — Injection
 
 - Use parameterized queries or prepared statements for all database operations. Zero tolerance for string concatenation with user input in queries.
 - Apply context-aware output encoding: HTML entities, URL encoding, JavaScript escaping, CSS escaping, LDAP escaping — matched to the output context.
@@ -159,7 +182,7 @@ alwaysApply: false
 - Use `LIMIT` and pagination in queries to prevent mass data disclosure via injection.
 - For OS command execution: avoid entirely if possible. If necessary, use parameterized APIs (not shell interpolation) with strict input validation.
 
-### A04 — Insecure Design
+### A06 — Insecure Design
 
 - Use threat modeling during design phase (STRIDE, attack trees, or equivalent). Identify trust boundaries and abuse cases before writing code.
 - Establish and enforce secure design patterns: separation of concerns, defense in depth, least privilege, fail-closed.
@@ -167,28 +190,7 @@ alwaysApply: false
 - Design rate limiting, resource quotas, and cost controls into the architecture — not as afterthoughts.
 - Establish secure development lifecycle (SDL) practices: security requirements, design review, code review, testing.
 
-### A05 — Security Misconfiguration
-
-- Harden all environments: remove default accounts, disable unused features/ports/services, remove sample applications.
-- Use identical security configuration across development, staging, and production. Differences in security settings between environments mask vulnerabilities.
-- Automate configuration verification: infrastructure-as-code with security baselines, configuration scanning in CI.
-- Send security headers on every response (HSTS, CSP, X-Content-Type-Options, X-Frame-Options). Centralize in middleware.
-- Review cloud permissions quarterly. Remove unused IAM roles, security groups, and service accounts.
-- Disable detailed error messages in production. Use generic error responses with correlation IDs for debugging.
-
-### A06 — Vulnerable and Outdated Components
-
-- Maintain a software bill of materials (SBOM) for all direct and transitive dependencies.
-- Run `npm audit` (or equivalent) in CI on every build. Block merges with critical or high vulnerabilities.
-- Subscribe to security advisories for all critical dependencies using the platform's built-in tools or third-party equivalents:
-  - **GitHub:** Dependabot alerts and security advisories
-  - **Azure DevOps:** Microsoft Defender for DevOps or WhiteSource/Mend integration
-  - **GitLab:** GitLab Dependency Scanning CI template, or Snyk integration
-- Remove unused dependencies. Unused code with known vulnerabilities is still a risk.
-- Pin dependency versions in lockfiles. Review lockfile changes in PRs with the same scrutiny as code changes.
-- Establish SLAs for vulnerability remediation: critical within 24 hours, high within 1 week, moderate within 1 sprint.
-
-### A07 — Identification and Authentication Failures
+### A07 — Authentication Failures
 
 - Implement multi-factor authentication for privileged accounts and sensitive operations.
 - Enforce password complexity requirements: minimum 8 characters, check against breached password databases (Have I Been Pwned API).
@@ -197,7 +199,7 @@ alwaysApply: false
 - Never expose session IDs in URLs. Use secure, HttpOnly, SameSite cookies.
 - Implement account lockout with notification after repeated failed attempts.
 
-### A08 — Software and Data Integrity Failures
+### A08 — Software or Data Integrity Failures
 
 - Verify integrity of all software updates, dependencies, and CI/CD pipeline artifacts using digital signatures or checksums.
 - Use lockfiles and verify their integrity. `npm ci` (not `npm install`) in CI for deterministic builds that fail on lockfile drift.
@@ -209,7 +211,7 @@ alwaysApply: false
   - **Azure DevOps:** Pin pipeline tasks by exact version (e.g., `task@2`)
   - **GitLab CI:** Pin included templates by SHA or tag reference
 
-### A09 — Security Logging and Monitoring Failures
+### A09 — Security Logging and Alerting Failures
 
 - Log all authentication events (success, failure, lockout), access control failures, input validation failures, and security-relevant business events.
 - Use structured logging with correlation IDs. Include: timestamp, severity, event type, user identity (if available), source IP, resource accessed, outcome.

package/dist/content/rules/hatch3r-security.md

@@ -0,0 +1,97 @@
+---
+id: hatch3r-security-rule
+type: rule
+description: CQ3 Security Quality measurement rule — supply-chain integrity, auth depth, secret hygiene, OWASP ASI controls; specialist routing to hatch3r-security
+scope: conditional
+globs: "src/**,**/auth/**,**/.github/workflows/**,**/Dockerfile*,**/package.json,**/package-lock.json,**/pnpm-lock.yaml,**/yarn.lock"
+tags: [floor:security, floor:content-quality, security]
+precedence: high
+quality_charter: agents/shared/quality-charter.md
+cache_friendly: true
+---
+# Security Quality (CQ3)
+
+**Pillars:** P6 (Security & Trust), CQ3 (Security Quality)
+
+## Scope
+
+This rule binds the CQ3 measurement set across end-user code that hatch3r generates AND the framework's own source tree. It complements (does not duplicate) two adjacent rules:
+
+- `rules/hatch3r-security-patterns.md` (critical precedence) — input-validation + auth-enforcement patterns at the code level.
+- `rules/hatch3r-secrets-management.md` (critical precedence) — secret detection, env-var hygiene, lockfile policy.
+
+This rule owns the CQ3 threshold set, the specialist agent routing, and the per-finding escalation pathway.
+
+## CQ3 Threshold Set
+
+Source: pillar CQ3 (see `agents/shared/principles.md`). Every threshold below is measurable per audit cycle; missing measurement is a Medium finding minimum.
+
+| Threshold | Target | Measurement source |
+|-----------|--------|--------------------|
+| npm provenance | 100% on release artifacts | `npm publish --provenance`; verify via `npm view {pkg} --json | jq .provenance` |
+| SBOM (CycloneDX 1.6 or SPDX 3.0.1) | Attached to every release | CI artifact; `syft` or `cyclonedx-npm` output |
+| SHA-pinned GitHub Actions | 100% — 40-char commit SHA | `.github/workflows/*.yml` grep for `uses: .*@[a-f0-9]{40}` |
+| Cosign-signed containers | 100% on published images | `cosign verify --certificate-identity-regexp` against issuer + Rekor entry |
+| OAuth 2.1 conformance | 100% on auth-bearing services | PKCE on public + confidential clients; refresh-token rotation with reuse detection; implicit + ROPC absent |
+| OIDC ID-token validation | 100% — `iss`, `aud`, `azp`, `exp`, `nonce`, JWKS signature | Code audit per `rules/hatch3r-auth-patterns.md` |
+| DPoP sender-constraint (RFC 9449) | 100% on browser tokens | `htm`, `htu`, `iat`, `jti` validation; key-thumbprint binding |
+| WebAuthn server ceremony | 100% on passwordless flows | Challenge TTL + single-use; RP-ID hash; signature; counter strictly greater; opaque `user.id` |
+| Hardcoded secrets count | 0 per cycle | `gitleaks detect --redact`, `trufflehog filesystem`, `detect-secrets scan` |
+| OWASP ASI01-10 coverage | 100% on agent-produced code | Per-control verification against the current agentic-security domain checklist |
+| CVE advisory acknowledgement | ≤90-day staleness | `npm audit --audit-level=high`; `osv-scanner -r .`; GHSA inspection |
+
+## Specialist Agent Routing
+
+The CQ3 envelope is owned by a single specialist. Route every trigger below to it:
+
+| Trigger | Route to |
+|---------|----------|
+| Auth-flow PR (sign-in, refresh, step-up, logout, token introspection, M2M) | `agents/hatch3r-security.md` (CQ3 specialist) |
+| Release-touching PR (workflow YAML, Dockerfile, package manifest, container manifest, SBOM tooling) | `agents/hatch3r-security.md` (CQ3 specialist) |
+| Project-specific deep audit (database rules, cloud functions, data flows, OWASP Top 10) | `agents/hatch3r-security.md` (CQ3 specialist — deep-audit mode) |
+| CVE response — advisory ≤90 days old matches `package.json` lockfile or SHA-pinned action | `agents/hatch3r-security.md` (CQ3 specialist) + framework-owner escalation per CONSTITUTION §2 P6 |
+| Container hardening (rootless, distroless, non-root UID, capabilities dropped) | `rules/hatch3r-container-hardening.md` (rule) + `agents/hatch3r-security.md` (review) |
+
+The CQ3 specialist gates the floor, emits `progress_toward_pillar: content-quality.CQ3+<delta>` per finding, AND performs deep project-specific audits when invoked in deep-audit mode. One agent, one routing surface.
+
+## Severity Mapping
+
+The Specialist-Status to canonical-severity map (`CRITICAL` → Critical, `FINDINGS` → High + Medium, `PASS` → Low + Info) is the shared CQ frame per `rules/hatch3r-cq-rule-frame.md` → Specialist-Status to Canonical-Severity Map, sourced from `agents/shared/severity-mapping.md`. CQ3 Action per status:
+
+- `CRITICAL`: Block release; framework-owner escalation; ≤7d resolution per CONSTITUTION §2 P6.
+- `FINDINGS`: Block merge on `floor:security` paths; ≤14d resolution for High.
+- `PASS`: Surface in iteration summary; no merge block.
+
+## Per-Finding Output Format
+
+Every finding emitted under this rule uses the CQ per-finding rigor-field schema per `rules/hatch3r-cq-rule-frame.md` → Per-Finding Output Format (rigor-contract fields per `agents/shared/rigor-contract.md`), with `<N>` = CQ3. The `proof_trace` excerpt is the command-output for the measurement that produced the finding (e.g. `npm audit`, `gitleaks`, SHA-pin grep).
+
+## Per-Tier Floor Admission
+
+Decision 4 (CONSTITUTION §6) admits CQ3 floor items per maturity tier:
+
+| Tier | Floor admission |
+|------|-----------------|
+| solo | npm audit clean; no hardcoded secrets; PKCE on OAuth public clients |
+| team | + SBOM attached to release; SHA-pinned actions on release workflow |
+| scaleup | + DPoP on browser tokens; refresh-token rotation; OIDC strict validation |
+| enterprise | + WebAuthn server ceremony; cosign on containers; OWASP ASI01-10 100%; CVE acknowledgement ≤7d for Critical |
+
+Tier escalation tightens the floor; previous baselines do not survive a tier bump without re-measurement.
+
+## When to Invoke
+
+- Every PR touching `src/auth/*`, JWT verification, cookie wiring, OAuth client config, WebAuthn ceremony, or `.github/workflows/*.yml`.
+- Every release-prep gate before publishing — SBOM, provenance, SHA-pin, cosign on all release artifacts.
+- Every dependency update PR — `npm audit`, `osv-scanner`, GHSA inspection; populate `securityNote` per `rules/hatch3r-tool-currency.md` if a CLI tool is affected.
+- Quarterly OWASP ASI revision review — the ASI revision number changes; rerun the 100% coverage gate against the current revision.
+
+## References
+
+- Pillar CQ3 (measurement set + specialist owner; see `agents/shared/principles.md`).
+- The agentic-security audit domain (OWASP ASI controls + supply-chain audit checklists).
+- `agents/hatch3r-security.md` (CQ3 specialist agent — auth + supply-chain + ASI scope).
+- `agents/hatch3r-security.md` (CQ3 specialist — deep-audit mode for project-specific audits).
+- `rules/hatch3r-security-patterns.md` (input-validation + auth enforcement at code level).
+- `rules/hatch3r-secrets-management.md` (secret detection + env-var hygiene + lockfile policy).
+- `rules/hatch3r-container-hardening.md` (rootless / distroless / non-root UID / capability discipline).

package/dist/content/rules/hatch3r-security.mdc

@@ -0,0 +1,92 @@
+---
+description: CQ3 Security Quality measurement rule — supply-chain integrity, auth depth, secret hygiene, OWASP ASI controls; specialist routing to hatch3r-security
+globs: ["src/**", "**/auth/**", "**/.github/workflows/**", "**/Dockerfile*", "**/package.json", "**/package-lock.json", "**/pnpm-lock.yaml", "**/yarn.lock"]
+alwaysApply: false
+precedence: high
+---
+# Security Quality (CQ3)
+
+**Pillars:** P6 (Security & Trust), CQ3 (Security Quality)
+
+## Scope
+
+This rule binds the CQ3 measurement set across end-user code that hatch3r generates AND the framework's own source tree. It complements (does not duplicate) two adjacent rules:
+
+- `rules/hatch3r-security-patterns.md` (critical precedence) — input-validation + auth-enforcement patterns at the code level.
+- `rules/hatch3r-secrets-management.md` (critical precedence) — secret detection, env-var hygiene, lockfile policy.
+
+This rule owns the CQ3 threshold set, the specialist agent routing, and the per-finding escalation pathway.
+
+## CQ3 Threshold Set
+
+Source: pillar CQ3 (see `agents/shared/principles.md`). Every threshold below is measurable per audit cycle; missing measurement is a Medium finding minimum.
+
+| Threshold | Target | Measurement source |
+|-----------|--------|--------------------|
+| npm provenance | 100% on release artifacts | `npm publish --provenance`; verify via `npm view {pkg} --json | jq .provenance` |
+| SBOM (CycloneDX 1.6 or SPDX 3.0.1) | Attached to every release | CI artifact; `syft` or `cyclonedx-npm` output |
+| SHA-pinned GitHub Actions | 100% — 40-char commit SHA | `.github/workflows/*.yml` grep for `uses: .*@[a-f0-9]{40}` |
+| Cosign-signed containers | 100% on published images | `cosign verify --certificate-identity-regexp` against issuer + Rekor entry |
+| OAuth 2.1 conformance | 100% on auth-bearing services | PKCE on public + confidential clients; refresh-token rotation with reuse detection; implicit + ROPC absent |
+| OIDC ID-token validation | 100% — `iss`, `aud`, `azp`, `exp`, `nonce`, JWKS signature | Code audit per `rules/hatch3r-auth-patterns.md` |
+| DPoP sender-constraint (RFC 9449) | 100% on browser tokens | `htm`, `htu`, `iat`, `jti` validation; key-thumbprint binding |
+| WebAuthn server ceremony | 100% on passwordless flows | Challenge TTL + single-use; RP-ID hash; signature; counter strictly greater; opaque `user.id` |
+| Hardcoded secrets count | 0 per cycle | `gitleaks detect --redact`, `trufflehog filesystem`, `detect-secrets scan` |
+| OWASP ASI01-10 coverage | 100% on agent-produced code | Per-control verification against the current agentic-security domain checklist |
+| CVE advisory acknowledgement | ≤90-day staleness | `npm audit --audit-level=high`; `osv-scanner -r .`; GHSA inspection |
+
+## Specialist Agent Routing
+
+The CQ3 envelope is owned by a single specialist. Route every trigger below to it:
+
+| Trigger | Route to |
+|---------|----------|
+| Auth-flow PR (sign-in, refresh, step-up, logout, token introspection, M2M) | `agents/hatch3r-security.md` (CQ3 specialist) |
+| Release-touching PR (workflow YAML, Dockerfile, package manifest, container manifest, SBOM tooling) | `agents/hatch3r-security.md` (CQ3 specialist) |
+| Project-specific deep audit (database rules, cloud functions, data flows, OWASP Top 10) | `agents/hatch3r-security.md` (CQ3 specialist — deep-audit mode) |
+| CVE response — advisory ≤90 days old matches `package.json` lockfile or SHA-pinned action | `agents/hatch3r-security.md` (CQ3 specialist) + framework-owner escalation per CONSTITUTION §2 P6 |
+| Container hardening (rootless, distroless, non-root UID, capabilities dropped) | `rules/hatch3r-container-hardening.md` (rule) + `agents/hatch3r-security.md` (review) |
+
+The CQ3 specialist gates the floor, emits `progress_toward_pillar: content-quality.CQ3+<delta>` per finding, AND performs deep project-specific audits when invoked in deep-audit mode. One agent, one routing surface.
+
+## Severity Mapping
+
+The Specialist-Status to canonical-severity map (`CRITICAL` → Critical, `FINDINGS` → High + Medium, `PASS` → Low + Info) is the shared CQ frame per `rules/hatch3r-cq-rule-frame.md` → Specialist-Status to Canonical-Severity Map, sourced from `agents/shared/severity-mapping.md`. CQ3 Action per status:
+
+- `CRITICAL`: Block release; framework-owner escalation; ≤7d resolution per CONSTITUTION §2 P6.
+- `FINDINGS`: Block merge on `floor:security` paths; ≤14d resolution for High.
+- `PASS`: Surface in iteration summary; no merge block.
+
+## Per-Finding Output Format
+
+Every finding emitted under this rule uses the CQ per-finding rigor-field schema per `rules/hatch3r-cq-rule-frame.md` → Per-Finding Output Format (rigor-contract fields per `agents/shared/rigor-contract.md`), with `<N>` = CQ3. The `proof_trace` excerpt is the command-output for the measurement that produced the finding (e.g. `npm audit`, `gitleaks`, SHA-pin grep).
+
+## Per-Tier Floor Admission
+
+Decision 4 (CONSTITUTION §6) admits CQ3 floor items per maturity tier:
+
+| Tier | Floor admission |
+|------|-----------------|
+| solo | npm audit clean; no hardcoded secrets; PKCE on OAuth public clients |
+| team | + SBOM attached to release; SHA-pinned actions on release workflow |
+| scaleup | + DPoP on browser tokens; refresh-token rotation; OIDC strict validation |
+| enterprise | + WebAuthn server ceremony; cosign on containers; OWASP ASI01-10 100%; CVE acknowledgement ≤7d for Critical |
+
+Tier escalation tightens the floor; previous baselines do not survive a tier bump without re-measurement.
+
+## When to Invoke
+
+- Every PR touching `src/auth/*`, JWT verification, cookie wiring, OAuth client config, WebAuthn ceremony, or `.github/workflows/*.yml`.
+- Every release-prep gate before publishing — SBOM, provenance, SHA-pin, cosign on all release artifacts.
+- Every dependency update PR — `npm audit`, `osv-scanner`, GHSA inspection; populate `securityNote` per `rules/hatch3r-tool-currency.md` if a CLI tool is affected.
+- Quarterly OWASP ASI revision review — the ASI revision number changes; rerun the 100% coverage gate against the current revision.
+
+## References
+
+- Pillar CQ3 (measurement set + specialist owner; see `agents/shared/principles.md`).
+- The agentic-security audit domain (OWASP ASI controls + supply-chain audit checklists).
+- `agents/hatch3r-security.md` (CQ3 specialist agent — auth + supply-chain + ASI scope).
+- `agents/hatch3r-security.md` (CQ3 specialist — deep-audit mode for project-specific audits).
+- `rules/hatch3r-security-patterns.md` (input-validation + auth enforcement at code level).
+- `rules/hatch3r-secrets-management.md` (secret detection + env-var hygiene + lockfile policy).
+- `rules/hatch3r-container-hardening.md` (rootless / distroless / non-root UID / capability discipline).

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

@@ -0,0 +1,98 @@
+---
+id: hatch3r-swiftui-patterns
+type: rule
+description: SwiftUI and Swift conventions covering Swift 6 concurrency, @Observable + @Bindable, navigation stacks, Swift Package Manager, modular architecture, and XCTest
+scope: conditional
+globs: "**/*.swift,**/*.swiftinterface,**/Package.swift,**/Package.resolved,**/*.xcodeproj/**,**/*.xcworkspace/**,**/Info.plist,**/*.entitlements,**/Tuist/**,**/Project.swift,**/Workspace.swift,**/ios/**,**/macos/**,**/visionOS/**,**/watchOS/**,**/tvOS/**"
+tags: [implementation]
+quality_charter: agents/shared/quality-charter.md
+cache_friendly: true
+---
+# SwiftUI Patterns
+
+**Pillars:** P2 (Scientific & Practical Quality), CQ8 (Maintainability Quality)
+
+> Applies when the project ships a SwiftUI/UIKit app or Swift package. Detection signals: `Package.swift`, `*.xcodeproj`, `*.xcworkspace`, or `*.swift` files at repo root.
+
+## Swift Language Floor
+
+- Target Swift 6.0+ with strict concurrency checking enabled (`SWIFT_STRICT_CONCURRENCY=complete`). Data-race-safety is the default; opt-out (`@unchecked Sendable`) requires a code comment justifying thread-safety reasoning.
+- Adopt `async/await` throughout. Wrap legacy completion-handler APIs with `withCheckedThrowingContinuation` at the boundary; do not propagate completion-handler signatures into new code.
+- Use `Sendable` conformance for types crossing actor boundaries. `actor` for shared mutable state; `MainActor`-isolated types for UI state.
+- Strict typing: no `Any` outside of bridging code. Prefer `some Protocol` (opaque return types) over existential `any Protocol` when the concrete type is known at compile time.
+
+## SwiftUI App Architecture
+
+- Use `@Observable` macro (Swift 5.9+) for view-model state classes; `@Bindable` for two-way binding in views. `ObservableObject` + `@Published` is legacy — migrate during regular refactors.
+- Pick ONE app-state pattern per app and document it in `docs/architecture.md`:
+  - **MV (Model–View) with `@Observable`** — recommended default. View-models are simple `@Observable` classes; views observe by reference.
+  - **TCA (The Composable Architecture)** — when the team wants unidirectional data flow with reducers + effects.
+  - **MVVM with Combine** — when the team already has heavy Combine investment. Avoid in greenfield code.
+- View body is a pure function of state. Never perform side effects in `body`; use `.task { ... }` or `.onChange(of:) { ... }` modifiers.
+- Compose small `View` types — a view exceeding 200 lines is a refactor signal. Extract subviews and use `@ViewBuilder` for conditional content.
+
+## Navigation
+
+- Use `NavigationStack` (iOS 16+) with path-driven navigation: bind a `[Destination]` path to the stack and push routes by appending to the array. `NavigationView` is deprecated — migrate.
+- Type the navigation destination via `navigationDestination(for:)` modifiers. Avoid `NavigationLink(destination:)` for stack-pushed views — it bypasses path binding.
+- Deep links: parse incoming URLs in the `.onOpenURL { ... }` modifier on the root view and update the navigation path. Test universal links on a real device — simulators do not honor associated-domains entitlements reliably.
+- Sheets and popovers via `.sheet(item:)` with an `Identifiable` payload — never pass a `Bool` and a separate state variable.
+
+## Concurrency
+
+- Long-running work: `Task { ... }` for fire-and-forget, `await Task { ... }.value` for cancelable async work. Always check `Task.isCancelled` inside loops.
+- Detached tasks (`Task.detached`) only when you need to escape MainActor isolation; document why in a comment. They inherit no priority or actor isolation.
+- `TaskGroup` for parallel fan-out: prefer `withThrowingTaskGroup` for error propagation. Limit concurrency explicitly (`group.addTask` with a semaphore) when the workload could overload the network or disk.
+- Use AsyncStream / AsyncSequence for event streams. Wrap delegate-based APIs (CLLocationManager, etc.) with `AsyncStream.makeStream(of:)` rather than maintaining ad-hoc callback caches.
+
+## Modular Architecture
+
+- Swift Package Manager (SPM) is the dependency floor. Vendor packages via local Swift packages, not CocoaPods or Carthage (both in maintenance for new projects).
+- Project structure (Tuist or hand-rolled):
+  - `App/` — main app target (UI + composition root only).
+  - `Features/<Feature>/` — feature modules, each its own SwiftPM target.
+  - `Core/` — shared utilities, networking, persistence.
+- Each feature module exports a public API via `public` types; everything else is `internal`. Cross-feature imports go through `Core/` interfaces.
+- Tuist (`Project.swift`, `Workspace.swift`) for multi-target projects above 5 modules. Hand-managed `.xcodeproj` files are merge-conflict prone — Tuist regenerates them deterministically.
+
+## Performance
+
+- Profile with Instruments (Time Profiler, Allocations, SwiftUI). Target 60fps on the oldest supported device class.
+- Avoid heavy work in `View.body`. Cache derived values with `@State` initialized via `init` or compute once in `.task { ... }`.
+- Lists: `List` with stable `Identifiable` IDs and `id: \.id` explicit key paths. Use `LazyVStack` inside `ScrollView` for non-Sectioned lists.
+- Images: `AsyncImage` for network images, `Image(systemName:)` for SF Symbols. For high-frequency reload, use `nuke` or `Kingfisher` with disk cache configured.
+- View identity: stable IDs prevent SwiftUI from re-creating views on every state change. `ForEach(items, id: \.id)` — never use `ForEach(items.indices)` for mutable arrays.
+
+## Accessibility
+
+- Every interactive view has an `.accessibilityLabel(_:)`, `.accessibilityHint(_:)`, and an appropriate `.accessibilityIdentifier(_:)` for UI tests.
+- Group decorative views with `.accessibilityElement(children: .ignore)` so VoiceOver does not stop on every visual element.
+- Dynamic Type: prefer `.font(.body)` and the semantic font modifiers over fixed-point sizes. Test with the largest accessibility size (`accessibility5`).
+- Reduced Motion: gate animations on `@Environment(\.accessibilityReduceMotion)` — disable parallax, springy bounces, and decorative transitions when set.
+
+## Testing
+
+- Unit tests with XCTest (`*Tests/`). Use `swift-testing` (Swift 6) for new test suites when you need parameterized tests, traits, or parallel execution semantics.
+- UI tests with XCUITest under `*UITests/`. Use accessibility identifiers for query stability — never use text labels for selectors.
+- Snapshot tests via `swift-snapshot-testing` (pointfreeco) for SwiftUI view regressions. Configure per-device snapshots in CI.
+- Mock HTTP with `URLProtocol` subclass or `swift-openapi-generator` mock transport. Never hit real network in unit tests.
+
+## Builds & Distribution
+
+- Sign with App Store Connect API keys, not Apple ID password. Configure via `xcrun altool --apiKey` or fastlane `app_store_connect_api_key`.
+- Bitcode is removed (Xcode 14+) — do not enable. dSYM archive every release for crash symbolication; upload to Crashlytics / Sentry / TestFlight automatically in CI.
+- App size: enable `SWIFT_OPTIMIZATION_LEVEL=-O` for release builds. Track size via `xcodebuild -resultBundlePath` JSON output in CI.
+- TestFlight for beta distribution. Use external groups for QA, internal groups for engineering — never share builds via plain `.ipa` files.
+
+## References
+
+- Swift 6 concurrency: https://www.swift.org/migration/documentation/migrationguide/ (accessed 2026-05-27, official-docs)
+- SwiftUI `@Observable`: https://developer.apple.com/documentation/observation (accessed 2026-05-27, official-docs)
+- NavigationStack: https://developer.apple.com/documentation/swiftui/navigationstack (accessed 2026-05-27, official-docs)
+- swift-testing: https://developer.apple.com/xcode/swift-testing/ (accessed 2026-05-27, official-docs)
+
+## Cross-References
+
+- `rules/hatch3r-component-conventions.md` — four-state surface contract maps to SwiftUI `phase`-based async views.
+- `rules/hatch3r-testing.md` — coverage thresholds and determinism rules apply to XCTest / swift-testing.
+- `rules/hatch3r-accessibility-standards.md` — WCAG mapping for SwiftUI `accessibility*` modifiers.

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

@@ -0,0 +1,93 @@
+---
+description: SwiftUI and Swift conventions covering Swift 6 concurrency, @Observable + @Bindable, navigation stacks, Swift Package Manager, modular architecture, and XCTest
+globs: ["**/*.swift", "**/*.swiftinterface", "**/Package.swift", "**/Package.resolved", "**/*.xcodeproj/**", "**/*.xcworkspace/**", "**/Info.plist", "**/*.entitlements", "**/Tuist/**", "**/Project.swift", "**/Workspace.swift", "**/ios/**", "**/macos/**", "**/visionOS/**", "**/watchOS/**", "**/tvOS/**"]
+alwaysApply: false
+---
+# SwiftUI Patterns
+
+**Pillars:** P2 (Scientific & Practical Quality), CQ8 (Maintainability Quality)
+
+> Applies when the project ships a SwiftUI/UIKit app or Swift package. Detection signals: `Package.swift`, `*.xcodeproj`, `*.xcworkspace`, or `*.swift` files at repo root.
+
+## Swift Language Floor
+
+- Target Swift 6.0+ with strict concurrency checking enabled (`SWIFT_STRICT_CONCURRENCY=complete`). Data-race-safety is the default; opt-out (`@unchecked Sendable`) requires a code comment justifying thread-safety reasoning.
+- Adopt `async/await` throughout. Wrap legacy completion-handler APIs with `withCheckedThrowingContinuation` at the boundary; do not propagate completion-handler signatures into new code.
+- Use `Sendable` conformance for types crossing actor boundaries. `actor` for shared mutable state; `MainActor`-isolated types for UI state.
+- Strict typing: no `Any` outside of bridging code. Prefer `some Protocol` (opaque return types) over existential `any Protocol` when the concrete type is known at compile time.
+
+## SwiftUI App Architecture
+
+- Use `@Observable` macro (Swift 5.9+) for view-model state classes; `@Bindable` for two-way binding in views. `ObservableObject` + `@Published` is legacy — migrate during regular refactors.
+- Pick ONE app-state pattern per app and document it in `docs/architecture.md`:
+  - **MV (Model–View) with `@Observable`** — recommended default. View-models are simple `@Observable` classes; views observe by reference.
+  - **TCA (The Composable Architecture)** — when the team wants unidirectional data flow with reducers + effects.
+  - **MVVM with Combine** — when the team already has heavy Combine investment. Avoid in greenfield code.
+- View body is a pure function of state. Never perform side effects in `body`; use `.task { ... }` or `.onChange(of:) { ... }` modifiers.
+- Compose small `View` types — a view exceeding 200 lines is a refactor signal. Extract subviews and use `@ViewBuilder` for conditional content.
+
+## Navigation
+
+- Use `NavigationStack` (iOS 16+) with path-driven navigation: bind a `[Destination]` path to the stack and push routes by appending to the array. `NavigationView` is deprecated — migrate.
+- Type the navigation destination via `navigationDestination(for:)` modifiers. Avoid `NavigationLink(destination:)` for stack-pushed views — it bypasses path binding.
+- Deep links: parse incoming URLs in the `.onOpenURL { ... }` modifier on the root view and update the navigation path. Test universal links on a real device — simulators do not honor associated-domains entitlements reliably.
+- Sheets and popovers via `.sheet(item:)` with an `Identifiable` payload — never pass a `Bool` and a separate state variable.
+
+## Concurrency
+
+- Long-running work: `Task { ... }` for fire-and-forget, `await Task { ... }.value` for cancelable async work. Always check `Task.isCancelled` inside loops.
+- Detached tasks (`Task.detached`) only when you need to escape MainActor isolation; document why in a comment. They inherit no priority or actor isolation.
+- `TaskGroup` for parallel fan-out: prefer `withThrowingTaskGroup` for error propagation. Limit concurrency explicitly (`group.addTask` with a semaphore) when the workload could overload the network or disk.
+- Use AsyncStream / AsyncSequence for event streams. Wrap delegate-based APIs (CLLocationManager, etc.) with `AsyncStream.makeStream(of:)` rather than maintaining ad-hoc callback caches.
+
+## Modular Architecture
+
+- Swift Package Manager (SPM) is the dependency floor. Vendor packages via local Swift packages, not CocoaPods or Carthage (both in maintenance for new projects).
+- Project structure (Tuist or hand-rolled):
+  - `App/` — main app target (UI + composition root only).
+  - `Features/<Feature>/` — feature modules, each its own SwiftPM target.
+  - `Core/` — shared utilities, networking, persistence.
+- Each feature module exports a public API via `public` types; everything else is `internal`. Cross-feature imports go through `Core/` interfaces.
+- Tuist (`Project.swift`, `Workspace.swift`) for multi-target projects above 5 modules. Hand-managed `.xcodeproj` files are merge-conflict prone — Tuist regenerates them deterministically.
+
+## Performance
+
+- Profile with Instruments (Time Profiler, Allocations, SwiftUI). Target 60fps on the oldest supported device class.
+- Avoid heavy work in `View.body`. Cache derived values with `@State` initialized via `init` or compute once in `.task { ... }`.
+- Lists: `List` with stable `Identifiable` IDs and `id: \.id` explicit key paths. Use `LazyVStack` inside `ScrollView` for non-Sectioned lists.
+- Images: `AsyncImage` for network images, `Image(systemName:)` for SF Symbols. For high-frequency reload, use `nuke` or `Kingfisher` with disk cache configured.
+- View identity: stable IDs prevent SwiftUI from re-creating views on every state change. `ForEach(items, id: \.id)` — never use `ForEach(items.indices)` for mutable arrays.
+
+## Accessibility
+
+- Every interactive view has an `.accessibilityLabel(_:)`, `.accessibilityHint(_:)`, and an appropriate `.accessibilityIdentifier(_:)` for UI tests.
+- Group decorative views with `.accessibilityElement(children: .ignore)` so VoiceOver does not stop on every visual element.
+- Dynamic Type: prefer `.font(.body)` and the semantic font modifiers over fixed-point sizes. Test with the largest accessibility size (`accessibility5`).
+- Reduced Motion: gate animations on `@Environment(\.accessibilityReduceMotion)` — disable parallax, springy bounces, and decorative transitions when set.
+
+## Testing
+
+- Unit tests with XCTest (`*Tests/`). Use `swift-testing` (Swift 6) for new test suites when you need parameterized tests, traits, or parallel execution semantics.
+- UI tests with XCUITest under `*UITests/`. Use accessibility identifiers for query stability — never use text labels for selectors.
+- Snapshot tests via `swift-snapshot-testing` (pointfreeco) for SwiftUI view regressions. Configure per-device snapshots in CI.
+- Mock HTTP with `URLProtocol` subclass or `swift-openapi-generator` mock transport. Never hit real network in unit tests.
+
+## Builds & Distribution
+
+- Sign with App Store Connect API keys, not Apple ID password. Configure via `xcrun altool --apiKey` or fastlane `app_store_connect_api_key`.
+- Bitcode is removed (Xcode 14+) — do not enable. dSYM archive every release for crash symbolication; upload to Crashlytics / Sentry / TestFlight automatically in CI.
+- App size: enable `SWIFT_OPTIMIZATION_LEVEL=-O` for release builds. Track size via `xcodebuild -resultBundlePath` JSON output in CI.
+- TestFlight for beta distribution. Use external groups for QA, internal groups for engineering — never share builds via plain `.ipa` files.
+
+## References
+
+- Swift 6 concurrency: https://www.swift.org/migration/documentation/migrationguide/ (accessed 2026-05-27, official-docs)
+- SwiftUI `@Observable`: https://developer.apple.com/documentation/observation (accessed 2026-05-27, official-docs)
+- NavigationStack: https://developer.apple.com/documentation/swiftui/navigationstack (accessed 2026-05-27, official-docs)
+- swift-testing: https://developer.apple.com/xcode/swift-testing/ (accessed 2026-05-27, official-docs)
+
+## Cross-References
+
+- `rules/hatch3r-component-conventions.md` — four-state surface contract maps to SwiftUI `phase`-based async views.
+- `rules/hatch3r-testing.md` — coverage thresholds and determinism rules apply to XCTest / swift-testing.
+- `rules/hatch3r-accessibility-standards.md` — WCAG mapping for SwiftUI `accessibility*` modifiers.

package/dist/content/rules/hatch3r-testability.md

@@ -0,0 +1,115 @@
+---
+id: hatch3r-testability-rule
+type: rule
+description: CQ5 Testability Quality measurement rule — per-feature test-class mandate map, real-deal ratio floor, AI eval coverage, mutation kill rate, specialist routing to hatch3r-testability
+scope: conditional
+globs: "src/**,**/__tests__/**,**/tests/**,**/test/**,**/*.test.*,**/*.spec.*,**/vitest.config.*,**/jest.config.*,**/cypress.config.*"
+tags: [review, testing, floor:content-quality]
+precedence: high
+quality_charter: agents/shared/quality-charter.md
+cache_friendly: true
+---
+# Testability Quality (CQ5)
+
+**Pillars:** P2 (Scientific & Practical Quality), CQ5 (Testability Quality)
+
+## Scope
+
+This rule binds the CQ5 measurement set across end-user code that hatch3r generates AND the framework's own test tree. It complements (does not duplicate) `rules/hatch3r-testing.md` (broad coverage + determinism + flaky-test policy). This rule owns:
+
+- The per-feature test-class mandate map.
+- The real-deal-first ratio floor.
+- The AI feature eval coverage gate.
+- The mutation-kill-rate gate on critical paths.
+- Specialist routing to `agents/hatch3r-testability.md` (CQ5 reviewer / gate + test authoring).
+
+## Per-Feature Test-Class Mandate Map
+
+Source: pillar CQ5 (see `agents/shared/principles.md`) + `rules/hatch3r-testing.md` mandate table. Every changed feature is classified, and the mandated test class MUST be present. Missing the mandated class is a CRITICAL finding from the specialist.
+
+| Feature class | Mandated test class | Tooling per ecosystem |
+|---------------|---------------------|-----------------------|
+| Parser (input deserialization, file format, protocol) | Fuzz | jazzer.js (JS), libfuzzer (Rust), atheris (Python), Jazzer (JVM) |
+| Payment (settlement, refund, ledger) | Mutation | Stryker (JS/TS), Pitest (JVM), mutmut (Python), mutpy (Python) |
+| RPC boundary (gRPC, GraphQL, REST consumer/provider) | Contract | Pact (cross-language), Schemathesis (OpenAPI), buf curl (protobuf) |
+| State machine (workflow, transition graph) | Property | fast-check (JS/TS), Hypothesis (Python), ScalaCheck (JVM) |
+| UI (component, page render) | Visual regression | Playwright with toHaveScreenshot, Percy, Chromatic, Loki |
+| AI feature (prompt-driven, model-driven) | Golden + adversarial + regression eval | Inspect AI, promptfoo, Anthropic Workbench evals, Braintrust |
+
+## Real-Deal-First Ratio
+
+The floor: ≥80% of integration tests use real services (test database, in-process emulator, sandboxed external API) rather than mocks. Mocks are admitted only with a `// MOCK: <reason>` comment naming a specific reason from this allowlist:
+
+- `// MOCK: External service has no sandbox (vendor confirmed)`
+- `// MOCK: Network unreachable in CI (offline build)`
+- `// MOCK: Time-source isolation (controlled clock)`
+- `// MOCK: Side-effect quarantine (irreversible operation)`
+- `// MOCK: Performance budget (test pack must run <5min)`
+
+Reasons outside the allowlist fail the audit-checklist item 2. Framework-level mock helpers (`vi.mock`, `jest.mock`, `unittest.mock.patch`, `mockito.when`) are detected by import-statement grep against the per-language pattern map.
+
+## AI Feature Eval Coverage
+
+Every AI feature surface (prompt-driven, model-driven, agent-driven) MUST carry three eval sets per `rules/hatch3r-ai-evals.md`, at 100% coverage:
+
+- **Golden set** — known-good inputs with expected outputs; regression marker on every model/prompt change.
+- **Adversarial set** — prompt injections, boundary inputs, malformed payloads; verifies refusal + safe-failure behavior.
+- **Regression set** — historical bug reproductions; ensures fixed bugs stay fixed.
+
+CI wires the evals on prompt/model changes; the CI gate exits non-zero on regression. Hallucination is tracked as an SLI per Anthropic engineering guidance (cited under References on the source rule).
+
+## Mutation Kill Rate
+
+On critical paths (payment, auth, anything labelled `critical` per maturity tier), the mutation kill-rate floor is read from repo config (not from this rule's defaults). Default per-tier floors per CONSTITUTION §6 Decision 4:
+
+| Tier | Mutation kill-rate floor on critical paths |
+|------|--------------------------------------------|
+| solo | Not required |
+| team | ≥60% |
+| scaleup | ≥75% |
+| enterprise | ≥85% |
+
+Tier escalation raises the floor; the previous baseline does not survive without re-measurement. Out-of-cycle floor changes require a documented baseline reset to keep wave-to-wave comparison valid.
+
+## Specialist Agent Routing
+
+| Trigger | Route to |
+|---------|----------|
+| Test code added, modified, or removed | `agents/hatch3r-testability.md` (CQ5 reviewer / gate) |
+| New feature in a mandate-map class needs test authoring | `agents/hatch3r-testability.md` (author + gate) |
+| Coverage threshold or test-runner config modified | `agents/hatch3r-testability.md` |
+| AI feature surface added or model/prompt change | `agents/hatch3r-testability.md` + `rules/hatch3r-ai-evals.md` |
+| Mutation kill-rate floor change proposed | `agents/hatch3r-testability.md` with baseline-reset documentation |
+
+The CQ5 specialist authors mandated tests, reviews coverage, and gates releases; `agents/hatch3r-testability.md` writes tests AND measures mandate compliance, blocking releases that miss the floor.
+
+## Per-Finding Output Format
+
+Every finding emitted under this rule uses the CQ per-finding rigor-field schema per `rules/hatch3r-cq-rule-frame.md` → Per-Finding Output Format (rigor-contract fields per `agents/shared/rigor-contract.md`), with `<N>` = CQ5. The `proof_trace` excerpt is the test-file:line citation + runner-output for the measurement that produced the finding.
+
+## Severity Mapping
+
+The Specialist-Status to canonical-severity map (`CRITICAL` → Critical, `FINDINGS` → High + Medium, `PASS` → Low + Info) is the shared CQ frame per `rules/hatch3r-cq-rule-frame.md` → Specialist-Status to Canonical-Severity Map, sourced from `agents/shared/severity-mapping.md`. CQ5 Action per status:
+
+- `CRITICAL`: Block release on mandate-map miss OR AI-eval-coverage <100%.
+- `FINDINGS`: Block merge on real-deal-ratio drop, coverage threshold miss, mutation kill-rate floor breach, or unowned flaky test.
+- `PASS`: Surface in iteration summary.
+
+## When to Invoke
+
+- Every PR that modifies test code, removes tests, or introduces a feature in a mandate-map class.
+- Every Implementer pre-write check — confirms the mandated test class before writing so `agents/hatch3r-testability.md` produces the right shape on first pass.
+- Every Verifier pre-merge gate immediately before `gh pr merge` on protected branches; status must be PASS to allow merge on auth/payment paths.
+- D03 or D22 audit cycles, and any maturity-tier escalation per `hatch3r config maturity`.
+- AI feature release gate before a prompt/model bump ships to production traffic.
+- Quarterly audit on real-deal ratio drift — even with no PRs to test code, mock accretion over time silently degrades the ratio against the 80% floor.
+
+## References
+
+- Pillar CQ5 (measurement set + specialist owner; see `agents/shared/principles.md`).
+- The test-coverage-quality audit domain (testability domain).
+- `agents/hatch3r-testability.md` (CQ5 reviewer / gate).
+- `agents/hatch3r-testability.md` (CQ5 test-authoring + gate agent — single owner).
+- `rules/hatch3r-testing.md` (broad coverage + determinism + flaky policy).
+- `rules/hatch3r-ai-evals.md` (golden + adversarial + regression eval requirements).
+- `rules/hatch3r-contract-testing.md` (Pact + Schemathesis pattern).