hatch3r 1.9.0 → 2.0.0

package/dist/content/rules/hatch3r-data-classification.md

@@ -2,7 +2,8 @@
 id: hatch3r-data-classification
 type: rule
 description: Data classification standards covering PII handling, encryption, retention policies, and regulatory compliance
-scope: "**/models/**,**/schemas/**,**/schema*,**/database/**,**/db/**,**/*model*,**/*entity*,**/prisma/**,**/drizzle/**,**/*migration*"
+scope: conditional
+globs: "**/models/**,**/schemas/**,**/schema*,**/database/**,**/db/**,**/*model*,**/*entity*,**/prisma/**,**/drizzle/**,**/*migration*,**/log*,**/*logger*,**/analytics/**,**/*analytics*,**/events/**,**/*telemetry*,**/export*,**/*export*"
 tags: [floor:security]
 precedence: high
 quality_charter: agents/shared/quality-charter.md
@@ -27,6 +28,7 @@ cache_friendly: true
 - Never log PII. Use structured logging with PII fields explicitly excluded or masked.
 - Pseudonymize PII in analytics and reporting. Use irreversible hashing for identifiers.
 - Provide data export and deletion endpoints for data subject requests (GDPR Article 15/17, CCPA).
+- This rule's PII review applies wherever PII can leave the data model — not just schemas and migrations, but log statements, loggers, analytics/telemetry emitters, event payloads, and export paths. Before merging a change to any of these surfaces, confirm no Level 3+ field is logged, emitted, or exported unmasked.
 
 ## Encryption
 

package/dist/content/rules/hatch3r-data-classification.mdc

@@ -1,6 +1,6 @@
 ---
 description: Data classification standards covering PII handling, encryption, retention policies, and regulatory compliance
-globs: ["**/models/**", "**/schemas/**", "**/schema*", "**/database/**", "**/db/**", "**/*model*", "**/*entity*", "**/prisma/**", "**/drizzle/**", "**/*migration*"]
+globs: ["**/models/**", "**/schemas/**", "**/schema*", "**/database/**", "**/db/**", "**/*model*", "**/*entity*", "**/prisma/**", "**/drizzle/**", "**/*migration*", "**/log*", "**/*logger*", "**/analytics/**", "**/*analytics*", "**/events/**", "**/*telemetry*", "**/export*", "**/*export*"]
 alwaysApply: false
 precedence: high
 ---
@@ -23,6 +23,7 @@ precedence: high
 - Never log PII. Use structured logging with PII fields explicitly excluded or masked.
 - Pseudonymize PII in analytics and reporting. Use irreversible hashing for identifiers.
 - Provide data export and deletion endpoints for data subject requests (GDPR Article 15/17, CCPA).
+- This rule's PII review applies wherever PII can leave the data model — not just schemas and migrations, but log statements, loggers, analytics/telemetry emitters, event payloads, and export paths. Before merging a change to any of these surfaces, confirm no Level 3+ field is logged, emitted, or exported unmasked.
 
 ## Encryption
 

package/dist/content/rules/hatch3r-deep-context.md

@@ -4,11 +4,14 @@ type: rule
 description: Adaptive pre-implementation analysis — complexity scoring, requirements elicitation, similar implementation discovery, and transitive dependency tracing before coding
 scope: always
 tags: [orchestration, floor:protocol]
+precedence: high
 quality_charter: agents/shared/quality-charter.md
 cache_friendly: true
 ---
 # Deep Context Analysis
 
+**Pillars:** P2 (Scientific & Practical Quality), P7 (Speed & Token Efficiency)
+
 Before implementing any non-trivial task, assess its complexity and run proportional pre-implementation analysis. This rule ensures the agent asks the right questions, discovers existing patterns to follow, and maps the full blast radius before writing code.
 
 ## Complexity Scoring
@@ -28,11 +31,13 @@ Score every task against these signals before implementation. Each signal adds w
 
 ### Tier Assignment
 
-| Total Weight | Tier | Label |
-|-------------|------|-------|
-| 0–2 | 1 | Light |
-| 3–5 | 2 | Standard |
-| 6+ | 3 | Deep |
+| Total Weight | Tier | Label | Model Class (per-adapter) |
+|-------------|------|-------|---------------------------|
+| 0–2 | 1 | Light | economy |
+| 3–5 | 2 | Standard | default |
+| 6+ | 3 | Deep | strongest |
+
+The **Model Class** column is an abstract effort lever: tier scales the model class the same way it scales researcher depth (`quick`/`deep`) and Phase 4 specialist depth — `economy` for cheap mechanical changes, `default` for routine multi-file work, `strongest` for high-blast-radius reasoning. It is a hint resolved per-adapter against that adapter's model map (`src/models/resolve.ts::resolveAgentModel`, `models.default`), not a literal model id — adapters with no model-routing surface ignore it. Model class is a first-order effort lever alongside depth (`hatch3r-agent-orchestration` -> Tier-to-Phase-4 specialist depth mapping).
 
 ## Tier Actions
 
@@ -93,24 +98,19 @@ This rule augments — not replaces — the existing Universal Sub-Agent Pipelin
 
 ## Scoring Examples
 
-To reduce ambiguity in tier assignment, here are worked examples:
+Worked examples that reconcile signals to a tier (only firing signals listed):
 
 **Example 1: "Fix typo in error message" -- Tier 1 (score 0)**
 No signals triggered. Single file, no cross-module impact, no ambiguity.
 
 **Example 2: "Add email validation to signup form" -- Tier 2 (score 4)**
 - Multiple layers touched (API + UI): +3
-- Estimated 2-3 files: +0
-- Input validation is security-adjacent but not in a security-sensitive area: +0
-- Clear requirements ("validate email format"): +0
 - May trigger cross-cutting i18n for error messages: +1 (partial cross-cutting)
+- 2-3 files, clear requirements, input validation not in a security-sensitive area: +0 each
 
 **Example 3: "Migrate auth from session-based to JWT" -- Tier 3 (score 12)**
 - Multiple layers (auth middleware + API + UI + storage): +3
-- Vague term "migrate" (scope unclear): +2
-- Cross-cutting auth concern: +2
-- Security-sensitive area: +2
-- Behavioral contract change (session API to JWT API): +2
+- Vague term "migrate", cross-cutting auth, security-sensitive area, behavioral contract change (session API to JWT API): +2 each
 - Estimated >5 files: +1 (partial -- easily >5)
 
 When a signal partially applies (e.g., "maybe 5 files, maybe 4"), round down. Tier upgrades from adaptation (see `hatch3r-agent-orchestration-detail`) compensate for underestimates.

package/dist/content/rules/hatch3r-deep-context.mdc

@@ -1,9 +1,12 @@
 ---
 description: Adaptive pre-implementation analysis — complexity scoring, requirements elicitation, similar implementation discovery, and transitive dependency tracing before coding
 alwaysApply: true
+precedence: high
 ---
 # Deep Context Analysis
 
+**Pillars:** P2 (Scientific & Practical Quality), P7 (Speed & Token Efficiency)
+
 Before implementing any non-trivial task, assess its complexity and run proportional pre-implementation analysis. This rule ensures the agent asks the right questions, discovers existing patterns to follow, and maps the full blast radius before writing code.
 
 ## Complexity Scoring
@@ -23,11 +26,13 @@ Score every task against these signals before implementation. Each signal adds w
 
 ### Tier Assignment
 
-| Total Weight | Tier | Label |
-|-------------|------|-------|
-| 0–2 | 1 | Light |
-| 3–5 | 2 | Standard |
-| 6+ | 3 | Deep |
+| Total Weight | Tier | Label | Model Class (per-adapter) |
+|-------------|------|-------|---------------------------|
+| 0–2 | 1 | Light | economy |
+| 3–5 | 2 | Standard | default |
+| 6+ | 3 | Deep | strongest |
+
+The **Model Class** column is an abstract effort lever: tier scales the model class the same way it scales researcher depth (`quick`/`deep`) and Phase 4 specialist depth — `economy` for cheap mechanical changes, `default` for routine multi-file work, `strongest` for high-blast-radius reasoning. It is a hint resolved per-adapter against that adapter's model map (`src/models/resolve.ts::resolveAgentModel`, `models.default`), not a literal model id — adapters with no model-routing surface ignore it. Model class is a first-order effort lever alongside depth (`hatch3r-agent-orchestration` -> Tier-to-Phase-4 specialist depth mapping).
 
 ## Tier Actions
 
@@ -88,24 +93,19 @@ This rule augments — not replaces — the existing Universal Sub-Agent Pipelin
 
 ## Scoring Examples
 
-To reduce ambiguity in tier assignment, here are worked examples:
+Worked examples that reconcile signals to a tier (only firing signals listed):
 
 **Example 1: "Fix typo in error message" -- Tier 1 (score 0)**
 No signals triggered. Single file, no cross-module impact, no ambiguity.
 
 **Example 2: "Add email validation to signup form" -- Tier 2 (score 4)**
 - Multiple layers touched (API + UI): +3
-- Estimated 2-3 files: +0
-- Input validation is security-adjacent but not in a security-sensitive area: +0
-- Clear requirements ("validate email format"): +0
 - May trigger cross-cutting i18n for error messages: +1 (partial cross-cutting)
+- 2-3 files, clear requirements, input validation not in a security-sensitive area: +0 each
 
 **Example 3: "Migrate auth from session-based to JWT" -- Tier 3 (score 12)**
 - Multiple layers (auth middleware + API + UI + storage): +3
-- Vague term "migrate" (scope unclear): +2
-- Cross-cutting auth concern: +2
-- Security-sensitive area: +2
-- Behavioral contract change (session API to JWT API): +2
+- Vague term "migrate", cross-cutting auth, security-sensitive area, behavioral contract change (session API to JWT API): +2 each
 - Estimated >5 files: +1 (partial -- easily >5)
 
 When a signal partially applies (e.g., "maybe 5 files, maybe 4"), round down. Tier upgrades from adaptation (see `hatch3r-agent-orchestration-detail`) compensate for underestimates.

package/dist/content/rules/hatch3r-dependency-management.md

@@ -1,8 +1,9 @@
 ---
 id: hatch3r-dependency-management
 type: rule
-description: Lockfile discipline, CVE scanning, transitive dependency audits, major version upgrade protocol, and bundle-size impact gates for package manifests
-scope: "**/package.json,**/package-lock.json,**/yarn.lock,**/pnpm-lock.yaml,**/Cargo.toml,**/Cargo.lock,**/requirements*.txt,**/pyproject.toml,**/go.mod,**/go.sum,**/Gemfile*"
+description: Lockfile discipline, CVE scanning, transitive dependency audits, major version upgrade protocol, bundle-size impact gates, and SHA-pinned GitHub Action enforcement for package manifests and workflow files
+scope: conditional
+globs: "**/package.json,**/package-lock.json,**/yarn.lock,**/pnpm-lock.yaml,**/Cargo.toml,**/Cargo.lock,**/requirements*.txt,**/pyproject.toml,**/go.mod,**/go.sum,**/Gemfile*,**/.github/workflows/**,**/*.yml,**/*.yaml"
 tags: [maintenance, floor:security]
 precedence: high
 quality_charter: agents/shared/quality-charter.md
@@ -13,7 +14,7 @@ cache_friendly: true
 - Always commit the lockfile. Never install without saving.
 - Justify new dependencies in PR description: what it does, why needed, alternatives considered, bundle size impact.
 - Prefer well-maintained packages: recent commits, active issues, no known CVEs.
-- Pin exact versions for production deps. Use clean install (e.g., `npm ci`, `pip install -r`, `cargo build`) in CI.
+- Pin exact versions for production deps. Use clean install (e.g., `npm ci`, `pip install -r`, `cargo build`) in CI. **hatch3r dogfoods this:** the framework's own runtime dependencies in `package.json` -> `dependencies` are pinned to exact versions (no `^` or `~`), with dev-only deps free to float per ecosystem convention. See D15-M9 for the originating finding; `.github/workflows/ci.yml` step `npm ci` enforces lockfile-only installs.
 - Run a dependency security scanner (e.g., `npm audit`, `pip-audit`, `cargo audit`) before merging dependency changes. Fix high/critical before merge.
 - No duplicate packages serving the same purpose. Consolidate on one.
 - Remove unused dependencies on every cleanup pass.
@@ -50,6 +51,8 @@ When trusted publishing is not yet enabled, publish with `npm publish --provenan
 
 ## SBOM Generation
 
+> Maturity tier: team+ — solo projects may defer. Per-release SBOM publishing earns its cost once consumers or compliance audits depend on it.
+
 Every release artifact ships a CycloneDX 1.6 or SPDX 3.0.1 SBOM, committed as a release asset and signed with the same Sigstore identity that signed the artifact. CycloneDX 1.6 is ECMA-424 ratified and broadly supported (Syft, Trivy, cdxgen, GitLab native). SPDX 3.0.1 is the BSI TR-03183-2 / EU CRA baseline.
 
 - Tooling baseline: `npm sbom --sbom-format=cyclonedx` (npm 10+), `cdxgen` (broad ecosystem coverage including Python, Java, Rust, Go), `syft` (containers + source repos).
@@ -64,6 +67,14 @@ Target SLSA Build L3 for production release artifacts: ephemeral hosted runner,
 - Deploy-time verification: `slsa-verifier` CLI confirms provenance, builder identity allow-list, and source-repo match before the artifact is consumed.
 - Pin the generator action to a 40-char commit SHA per the action-pinning policy below.
 
+### Defense-in-Depth Limit
+
+SLSA L3 attests build-pipeline integrity — which pipeline produced the artifact — not source integrity. A compromised build step inside a legitimate L3 pipeline produces a validly-attested malicious artifact. In the Mini Shai-Hulud incident (May 2026) the attacker injected a payload into release tarballs after `package.json` modification but before the signing step; the published packages carried valid Sigstore provenance via the workflow's `id-token: write` OIDC token, and downstream consumers that verified the L3 attestation trusted the artifact. Do not treat a passing `slsa-verifier` check as sufficient. Layer it with:
+
+- Pre-install behavioral scan of the resolved package (`socket.dev`, `osv-scanner`) — catches install-time payloads that provenance cannot.
+- `minimumReleaseAge: 72` and `ignore-scripts=true` per the malicious-package section below — closes the propagation window and blocks lifecycle-script execution.
+- Attestation identity verification, not just attestation presence: assert the signing identity (builder repo + workflow ref) matches the expected publisher, so a fork-built artifact fails even with valid provenance.
+
 ## Malicious-Package Detection Beyond `npm audit`
 
 `npm audit` only flags published CVEs. The 2025-2026 incident class — Shai-Hulud (Sep-Nov 2025), Axios 1.14.1 maintainer hijack (Mar 2026), Mini-Shai-Hulud (May 2026), DevTap typosquat (Apr-May 2026) — never reaches a CVE filing. Layer install-time behavioral detection on top of `npm audit`:
@@ -83,6 +94,8 @@ Target SLSA Build L3 for production release artifacts: ephemeral hosted runner,
 
 ## License Compliance
 
+> Maturity tier: team+ — solo projects may defer. A CI license gate matters once a team or downstream redistributes the artifact; a solo prototype with no redistribution can adopt it later.
+
 - Allow-list (default): MIT, Apache-2.0, ISC, BSD-2-Clause, BSD-3-Clause, MPL-2.0, CC0-1.0. Project policy may extend.
 - Deny-list (default): GPL-2.0, GPL-3.0, AGPL-3.0, AGPL-3.0-or-later, SSPL-1.0, Commons Clause. AGPL triggers copyleft on network use — it is the SaaS landmine.
 - Override requires documented business justification in the PR description plus security/legal sign-off.

package/dist/content/rules/hatch3r-dependency-management.mdc

@@ -1,6 +1,6 @@
 ---
-description: Lockfile discipline, CVE scanning, transitive dependency audits, major version upgrade protocol, and bundle-size impact gates for package manifests
-globs: ["**/package.json", "**/package-lock.json", "**/yarn.lock", "**/pnpm-lock.yaml", "**/Cargo.toml", "**/Cargo.lock", "**/requirements*.txt", "**/pyproject.toml", "**/go.mod", "**/go.sum", "**/Gemfile*"]
+description: Lockfile discipline, CVE scanning, transitive dependency audits, major version upgrade protocol, bundle-size impact gates, and SHA-pinned GitHub Action enforcement for package manifests and workflow files
+globs: ["**/package.json", "**/package-lock.json", "**/yarn.lock", "**/pnpm-lock.yaml", "**/Cargo.toml", "**/Cargo.lock", "**/requirements*.txt", "**/pyproject.toml", "**/go.mod", "**/go.sum", "**/Gemfile*", "**/.github/workflows/**", "**/*.yml", "**/*.yaml"]
 alwaysApply: false
 precedence: high
 ---
@@ -9,7 +9,7 @@ precedence: high
 - Always commit the lockfile. Never install without saving.
 - Justify new dependencies in PR description: what it does, why needed, alternatives considered, bundle size impact.
 - Prefer well-maintained packages: recent commits, active issues, no known CVEs.
-- Pin exact versions for production deps. Use clean install (e.g., `npm ci`, `pip install -r`, `cargo build`) in CI.
+- Pin exact versions for production deps. Use clean install (e.g., `npm ci`, `pip install -r`, `cargo build`) in CI. **hatch3r dogfoods this:** the framework's own runtime dependencies in `package.json` -> `dependencies` are pinned to exact versions (no `^` or `~`), with dev-only deps free to float per ecosystem convention. See D15-M9 for the originating finding; `.github/workflows/ci.yml` step `npm ci` enforces lockfile-only installs.
 - Run a dependency security scanner (e.g., `npm audit`, `pip-audit`, `cargo audit`) before merging dependency changes. Fix high/critical before merge.
 - No duplicate packages serving the same purpose. Consolidate on one.
 - Remove unused dependencies on every cleanup pass.
@@ -46,6 +46,8 @@ When trusted publishing is not yet enabled, publish with `npm publish --provenan
 
 ## SBOM Generation
 
+> Maturity tier: team+ — solo projects may defer. Per-release SBOM publishing earns its cost once consumers or compliance audits depend on it.
+
 Every release artifact ships a CycloneDX 1.6 or SPDX 3.0.1 SBOM, committed as a release asset and signed with the same Sigstore identity that signed the artifact. CycloneDX 1.6 is ECMA-424 ratified and broadly supported (Syft, Trivy, cdxgen, GitLab native). SPDX 3.0.1 is the BSI TR-03183-2 / EU CRA baseline.
 
 - Tooling baseline: `npm sbom --sbom-format=cyclonedx` (npm 10+), `cdxgen` (broad ecosystem coverage including Python, Java, Rust, Go), `syft` (containers + source repos).
@@ -60,6 +62,14 @@ Target SLSA Build L3 for production release artifacts: ephemeral hosted runner,
 - Deploy-time verification: `slsa-verifier` CLI confirms provenance, builder identity allow-list, and source-repo match before the artifact is consumed.
 - Pin the generator action to a 40-char commit SHA per the action-pinning policy below.
 
+### Defense-in-Depth Limit
+
+SLSA L3 attests build-pipeline integrity — which pipeline produced the artifact — not source integrity. A compromised build step inside a legitimate L3 pipeline produces a validly-attested malicious artifact. In the Mini Shai-Hulud incident (May 2026) the attacker injected a payload into release tarballs after `package.json` modification but before the signing step; the published packages carried valid Sigstore provenance via the workflow's `id-token: write` OIDC token, and downstream consumers that verified the L3 attestation trusted the artifact. Do not treat a passing `slsa-verifier` check as sufficient. Layer it with:
+
+- Pre-install behavioral scan of the resolved package (`socket.dev`, `osv-scanner`) — catches install-time payloads that provenance cannot.
+- `minimumReleaseAge: 72` and `ignore-scripts=true` per the malicious-package section below — closes the propagation window and blocks lifecycle-script execution.
+- Attestation identity verification, not just attestation presence: assert the signing identity (builder repo + workflow ref) matches the expected publisher, so a fork-built artifact fails even with valid provenance.
+
 ## Malicious-Package Detection Beyond `npm audit`
 
 `npm audit` only flags published CVEs. The 2025-2026 incident class — Shai-Hulud (Sep-Nov 2025), Axios 1.14.1 maintainer hijack (Mar 2026), Mini-Shai-Hulud (May 2026), DevTap typosquat (Apr-May 2026) — never reaches a CVE filing. Layer install-time behavioral detection on top of `npm audit`:
@@ -79,6 +89,8 @@ Target SLSA Build L3 for production release artifacts: ephemeral hosted runner,
 
 ## License Compliance
 
+> Maturity tier: team+ — solo projects may defer. A CI license gate matters once a team or downstream redistributes the artifact; a solo prototype with no redistribution can adopt it later.
+
 - Allow-list (default): MIT, Apache-2.0, ISC, BSD-2-Clause, BSD-3-Clause, MPL-2.0, CC0-1.0. Project policy may extend.
 - Deny-list (default): GPL-2.0, GPL-3.0, AGPL-3.0, AGPL-3.0-or-later, SSPL-1.0, Commons Clause. AGPL triggers copyleft on network use — it is the SaaS landmine.
 - Override requires documented business justification in the PR description plus security/legal sign-off.

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

@@ -2,7 +2,8 @@
 id: hatch3r-design-system-detection
 type: rule
 description: Mandatory detection of existing design tokens, theme primitives, and component library before AI agents author new UI components
-scope: "**/*.vue,**/*.jsx,**/*.tsx,**/*.svelte,**/*.css,**/*.scss,**/components/**,**/tokens*,**/theme*,**/design-system/**,**/tailwind*"
+scope: conditional
+globs: "**/*.vue,**/*.jsx,**/*.tsx,**/*.svelte,**/*.css,**/*.scss,**/components/**,**/tokens*,**/theme*,**/design-system/**,**/tailwind*"
 tags: [implementation, floor:ui-ux, ui, design-system, frontend]
 precedence: high
 quality_charter: agents/shared/quality-charter.md

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

@@ -0,0 +1,104 @@
+---
+id: hatch3r-dotnet-patterns
+type: rule
+description: .NET 9 + C# 13 conventions covering minimal APIs, nullable reference types, async/await, Entity Framework Core, dependency injection, structured logging, and xUnit testing
+scope: conditional
+globs: "**/*.cs,**/*.csproj,**/*.sln,**/*.fsproj,**/*.vbproj,**/Directory.Build.props,**/Directory.Build.targets,**/global.json,**/nuget.config,**/appsettings.json,**/appsettings.*.json,**/Program.cs,**/Startup.cs"
+tags: [implementation]
+quality_charter: agents/shared/quality-charter.md
+cache_friendly: true
+---
+# .NET Patterns
+
+**Pillars:** P2 (Scientific & Practical Quality), CQ8 (Maintainability Quality)
+
+> Applies when the project ships a .NET / C# solution. Detection signals: `*.csproj` / `*.sln` files, `global.json`, or any `*.cs` source at repo root. Includes ASP.NET Core, console apps, libraries, and Blazor projects.
+
+## .NET / C# Language Floor
+
+- Target .NET 9.0 (LTS-supporting upgrade path) or the current LTS (.NET 8). Pin via `global.json` (`sdk.version`) and `*.csproj` `<TargetFramework>net9.0</TargetFramework>`.
+- Use C# 13+ features: collection expressions (`[1, 2, 3]`), primary constructors on non-record classes, `params Span<T>`. Avoid mixing older syntax with new — pick the modern form across the codebase.
+- Enable nullable reference types (`<Nullable>enable</Nullable>` in `*.csproj`). Treat warnings as errors: `<TreatWarningsAsErrors>true</TreatWarningsAsErrors>`.
+- Use `Directory.Build.props` to centralize SDK version, lang version, code-analysis rules, and shared package versions across all projects.
+
+## Project Layout
+
+- Solution structure:
+  - `src/<ProjectName>/<ProjectName>.csproj` — main library / app projects.
+  - `src/<ProjectName>.Api/` — ASP.NET Core API projects.
+  - `tests/<ProjectName>.Tests/` — unit tests per project.
+  - `tests/<ProjectName>.IntegrationTests/` — integration tests with `WebApplicationFactory`.
+- Use `Microsoft.NET.Sdk` (or `Microsoft.NET.Sdk.Web` for ASP.NET) — do not use the legacy `csproj` format. Configure central package management via `Directory.Packages.props` to lock NuGet versions across the solution.
+- Public API exposed via top-level types; internal helpers marked `internal`. Use `InternalsVisibleTo` for test projects only.
+
+## ASP.NET Core (Minimal APIs)
+
+- Prefer Minimal APIs in `Program.cs` for new services — they reduce boilerplate and integrate with Native AOT.
+- Use route groups (`app.MapGroup("/api/v1")`) with `RequireAuthorization()`, `AddEndpointFilter`, and `WithOpenApi()` modifiers. Versioning via route prefix or `Asp.Versioning.Http` package.
+- Endpoint handlers receive parameters via attributes: `[FromBody]`, `[FromQuery]`, `[FromRoute]`, `[FromServices]`. Async handlers return `Results.Ok(...)`, `Results.Problem(...)`, `Results.ValidationProblem(...)` — never raw exceptions for expected error paths.
+- For controllers: use `[ApiController]` with `[Route("api/[controller]")]`. Model binding + validation is automatic; opt out of `[ApiController]`-implied filters only when you need different conventions and document the rationale.
+
+## Dependency Injection
+
+- Built-in `IServiceCollection` is the floor. Register via lifetime-explicit methods: `AddSingleton`, `AddScoped`, `AddTransient`. Document the lifetime choice in a comment when non-obvious.
+- Constructor injection only. Property injection via the framework is a smell — refactor to constructor injection or accept the value through a method parameter.
+- Configuration via the `Options` pattern: `services.Configure<MyOptions>(config.GetSection("My"))`. Inject `IOptions<MyOptions>` (or `IOptionsMonitor<T>` for change-tolerant readers). Do not inject `IConfiguration` directly.
+- Disposable singletons: the container disposes them on app shutdown. Never call `Dispose()` manually on a resolved singleton.
+
+## Async / Await
+
+- Use `async Task<T>` / `async ValueTask<T>` end-to-end. Never `.Result` / `.Wait()` — they deadlock under ASP.NET Core's synchronization context.
+- Pass `CancellationToken` as a parameter; propagate through every layer. Endpoint handlers automatically receive `HttpContext.RequestAborted`.
+- `ConfigureAwait(false)` on library code; `ConfigureAwait(true)` (default) in UI / ASP.NET handlers. The `Microsoft.VisualStudio.Threading.Analyzers` package catches missing `ConfigureAwait` in libraries.
+- For parallel async work: `Task.WhenAll` (all must succeed) or `Parallel.ForEachAsync` (Bounded parallelism). Avoid `Task.Run` in ASP.NET — it consumes a thread-pool slot for no benefit.
+
+## Entity Framework Core
+
+- EF Core 9.x is the floor. Use `AddDbContextPool<>` for ASP.NET — context pooling reduces allocation overhead.
+- Migrations: `dotnet ef migrations add <Name>` per schema change; check generated files into VCS. Never edit migration `Designer.cs` by hand.
+- Query discipline: prefer projected `Select(x => new Dto { ... })` over fetching entities. Use `AsNoTracking()` for read-only queries — the change tracker is unnecessary overhead.
+- Avoid `.Include().Include()` chains beyond one level — denormalize the query into a projection.
+- Set timeouts: `dbContext.Database.SetCommandTimeout(TimeSpan.FromSeconds(30))`. Default is unbounded.
+- Use raw SQL (`FromSqlInterpolated`) for queries EF can't express. Never string-concatenate user input into SQL; `FromSqlInterpolated` parameterizes correctly.
+
+## Structured Logging
+
+- Use `Microsoft.Extensions.Logging` with structured-message templates: `logger.LogInformation("User {UserId} created order {OrderId}", userId, orderId)`. Never use interpolated strings (`$"..."`) — they lose the structure.
+- Pin a logging provider in production: Serilog (`Serilog.AspNetCore`) for the richest sink ecosystem, or OpenTelemetry exporter for vendor-neutral pipelines.
+- Configure log levels per category in `appsettings.json`. `Microsoft.AspNetCore` → `Warning` in production to mute request-pipeline noise.
+- Correlation IDs: enable `ActivityIdFormat = ActivityIdFormat.W3C` for W3C Trace Context. Every log entry includes the active trace ID automatically via `TraceContext` enrichment.
+
+## Testing
+
+- Unit tests with xUnit (`Microsoft.NET.Test.Sdk` + `xunit` + `xunit.runner.visualstudio`). Naming convention: `Method_State_ExpectedBehavior`.
+- Use `FluentAssertions` for readable assertions — `result.Should().BeOfType<Ok<User>>()`.
+- Mocking: NSubstitute (recommended) or Moq. Hand-rolled fakes for interfaces with ≤3 methods.
+- Integration tests: `WebApplicationFactory<TEntryPoint>` from `Microsoft.AspNetCore.Mvc.Testing`. Replace external dependencies (database, cache) via `IServiceCollection` overrides in `ConfigureWebHost`. Use Testcontainers (`Testcontainers.PostgreSql`, `Testcontainers.Redis`) for real-database integration tests.
+- Coverage: `dotnet test --collect:"XPlat Code Coverage"` with Coverlet. Floor: 80% line coverage in `src/`, 90% in critical modules (auth, billing, persistence).
+
+## Native AOT & Performance
+
+- Native AOT support (`PublishAot=true`) for cold-start-sensitive workloads (CLI tools, serverless). Audit dependencies — reflection-heavy packages (e.g., older Newtonsoft.Json paths) break AOT.
+- Trimming (`PublishTrimmed=true`) for self-contained deploys to reduce binary size. Mark trim-unsafe APIs with `[RequiresUnreferencedCode]`.
+- Use `Span<T>` / `Memory<T>` for hot-path buffer manipulation. `ArrayPool<T>.Shared` for transient large buffers to reduce GC pressure.
+- Profile with `dotnet-trace` and `dotnet-counters` before optimizing.
+
+## NuGet Hygiene
+
+- Central package management: define versions once in `Directory.Packages.props` (`<PackageVersion Include="Foo" Version="1.2.3" />`). Per-project references then drop the `Version` attribute.
+- Vulnerability scanning: `dotnet list package --vulnerable --include-transitive` in CI. Block merge on listed advisories.
+- License compliance: `dotnet-project-licenses` tool with an allowlist. Block GPL contamination via the allowlist.
+- Pin to released versions only — never `*` or floating prerelease versions.
+
+## References
+
+- .NET 9 release notes: https://learn.microsoft.com/en-us/dotnet/core/whats-new/dotnet-9 (accessed 2026-05-27, official-docs)
+- ASP.NET Core Minimal APIs: https://learn.microsoft.com/en-us/aspnet/core/fundamentals/minimal-apis/ (accessed 2026-05-27, official-docs)
+- EF Core 9.x: https://learn.microsoft.com/en-us/ef/core/what-is-new/ (accessed 2026-05-27, official-docs)
+- C# 13 features: https://learn.microsoft.com/en-us/dotnet/csharp/whats-new/csharp-13 (accessed 2026-05-27, official-docs)
+
+## Cross-References
+
+- `rules/hatch3r-api-design.md` — REST/GraphQL/gRPC contract floors apply to ASP.NET Core services.
+- `rules/hatch3r-testing.md` — coverage thresholds carry over to `dotnet test` + Coverlet.
+- `rules/hatch3r-observability-logging.md` — `Microsoft.Extensions.Logging` integration with the canonical logging contract.

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

@@ -0,0 +1,99 @@
+---
+description: .NET 9 + C# 13 conventions covering minimal APIs, nullable reference types, async/await, Entity Framework Core, dependency injection, structured logging, and xUnit testing
+globs: ["**/*.cs", "**/*.csproj", "**/*.sln", "**/*.fsproj", "**/*.vbproj", "**/Directory.Build.props", "**/Directory.Build.targets", "**/global.json", "**/nuget.config", "**/appsettings.json", "**/appsettings.*.json", "**/Program.cs", "**/Startup.cs"]
+alwaysApply: false
+---
+# .NET Patterns
+
+**Pillars:** P2 (Scientific & Practical Quality), CQ8 (Maintainability Quality)
+
+> Applies when the project ships a .NET / C# solution. Detection signals: `*.csproj` / `*.sln` files, `global.json`, or any `*.cs` source at repo root. Includes ASP.NET Core, console apps, libraries, and Blazor projects.
+
+## .NET / C# Language Floor
+
+- Target .NET 9.0 (LTS-supporting upgrade path) or the current LTS (.NET 8). Pin via `global.json` (`sdk.version`) and `*.csproj` `<TargetFramework>net9.0</TargetFramework>`.
+- Use C# 13+ features: collection expressions (`[1, 2, 3]`), primary constructors on non-record classes, `params Span<T>`. Avoid mixing older syntax with new — pick the modern form across the codebase.
+- Enable nullable reference types (`<Nullable>enable</Nullable>` in `*.csproj`). Treat warnings as errors: `<TreatWarningsAsErrors>true</TreatWarningsAsErrors>`.
+- Use `Directory.Build.props` to centralize SDK version, lang version, code-analysis rules, and shared package versions across all projects.
+
+## Project Layout
+
+- Solution structure:
+  - `src/<ProjectName>/<ProjectName>.csproj` — main library / app projects.
+  - `src/<ProjectName>.Api/` — ASP.NET Core API projects.
+  - `tests/<ProjectName>.Tests/` — unit tests per project.
+  - `tests/<ProjectName>.IntegrationTests/` — integration tests with `WebApplicationFactory`.
+- Use `Microsoft.NET.Sdk` (or `Microsoft.NET.Sdk.Web` for ASP.NET) — do not use the legacy `csproj` format. Configure central package management via `Directory.Packages.props` to lock NuGet versions across the solution.
+- Public API exposed via top-level types; internal helpers marked `internal`. Use `InternalsVisibleTo` for test projects only.
+
+## ASP.NET Core (Minimal APIs)
+
+- Prefer Minimal APIs in `Program.cs` for new services — they reduce boilerplate and integrate with Native AOT.
+- Use route groups (`app.MapGroup("/api/v1")`) with `RequireAuthorization()`, `AddEndpointFilter`, and `WithOpenApi()` modifiers. Versioning via route prefix or `Asp.Versioning.Http` package.
+- Endpoint handlers receive parameters via attributes: `[FromBody]`, `[FromQuery]`, `[FromRoute]`, `[FromServices]`. Async handlers return `Results.Ok(...)`, `Results.Problem(...)`, `Results.ValidationProblem(...)` — never raw exceptions for expected error paths.
+- For controllers: use `[ApiController]` with `[Route("api/[controller]")]`. Model binding + validation is automatic; opt out of `[ApiController]`-implied filters only when you need different conventions and document the rationale.
+
+## Dependency Injection
+
+- Built-in `IServiceCollection` is the floor. Register via lifetime-explicit methods: `AddSingleton`, `AddScoped`, `AddTransient`. Document the lifetime choice in a comment when non-obvious.
+- Constructor injection only. Property injection via the framework is a smell — refactor to constructor injection or accept the value through a method parameter.
+- Configuration via the `Options` pattern: `services.Configure<MyOptions>(config.GetSection("My"))`. Inject `IOptions<MyOptions>` (or `IOptionsMonitor<T>` for change-tolerant readers). Do not inject `IConfiguration` directly.
+- Disposable singletons: the container disposes them on app shutdown. Never call `Dispose()` manually on a resolved singleton.
+
+## Async / Await
+
+- Use `async Task<T>` / `async ValueTask<T>` end-to-end. Never `.Result` / `.Wait()` — they deadlock under ASP.NET Core's synchronization context.
+- Pass `CancellationToken` as a parameter; propagate through every layer. Endpoint handlers automatically receive `HttpContext.RequestAborted`.
+- `ConfigureAwait(false)` on library code; `ConfigureAwait(true)` (default) in UI / ASP.NET handlers. The `Microsoft.VisualStudio.Threading.Analyzers` package catches missing `ConfigureAwait` in libraries.
+- For parallel async work: `Task.WhenAll` (all must succeed) or `Parallel.ForEachAsync` (Bounded parallelism). Avoid `Task.Run` in ASP.NET — it consumes a thread-pool slot for no benefit.
+
+## Entity Framework Core
+
+- EF Core 9.x is the floor. Use `AddDbContextPool<>` for ASP.NET — context pooling reduces allocation overhead.
+- Migrations: `dotnet ef migrations add <Name>` per schema change; check generated files into VCS. Never edit migration `Designer.cs` by hand.
+- Query discipline: prefer projected `Select(x => new Dto { ... })` over fetching entities. Use `AsNoTracking()` for read-only queries — the change tracker is unnecessary overhead.
+- Avoid `.Include().Include()` chains beyond one level — denormalize the query into a projection.
+- Set timeouts: `dbContext.Database.SetCommandTimeout(TimeSpan.FromSeconds(30))`. Default is unbounded.
+- Use raw SQL (`FromSqlInterpolated`) for queries EF can't express. Never string-concatenate user input into SQL; `FromSqlInterpolated` parameterizes correctly.
+
+## Structured Logging
+
+- Use `Microsoft.Extensions.Logging` with structured-message templates: `logger.LogInformation("User {UserId} created order {OrderId}", userId, orderId)`. Never use interpolated strings (`$"..."`) — they lose the structure.
+- Pin a logging provider in production: Serilog (`Serilog.AspNetCore`) for the richest sink ecosystem, or OpenTelemetry exporter for vendor-neutral pipelines.
+- Configure log levels per category in `appsettings.json`. `Microsoft.AspNetCore` → `Warning` in production to mute request-pipeline noise.
+- Correlation IDs: enable `ActivityIdFormat = ActivityIdFormat.W3C` for W3C Trace Context. Every log entry includes the active trace ID automatically via `TraceContext` enrichment.
+
+## Testing
+
+- Unit tests with xUnit (`Microsoft.NET.Test.Sdk` + `xunit` + `xunit.runner.visualstudio`). Naming convention: `Method_State_ExpectedBehavior`.
+- Use `FluentAssertions` for readable assertions — `result.Should().BeOfType<Ok<User>>()`.
+- Mocking: NSubstitute (recommended) or Moq. Hand-rolled fakes for interfaces with ≤3 methods.
+- Integration tests: `WebApplicationFactory<TEntryPoint>` from `Microsoft.AspNetCore.Mvc.Testing`. Replace external dependencies (database, cache) via `IServiceCollection` overrides in `ConfigureWebHost`. Use Testcontainers (`Testcontainers.PostgreSql`, `Testcontainers.Redis`) for real-database integration tests.
+- Coverage: `dotnet test --collect:"XPlat Code Coverage"` with Coverlet. Floor: 80% line coverage in `src/`, 90% in critical modules (auth, billing, persistence).
+
+## Native AOT & Performance
+
+- Native AOT support (`PublishAot=true`) for cold-start-sensitive workloads (CLI tools, serverless). Audit dependencies — reflection-heavy packages (e.g., older Newtonsoft.Json paths) break AOT.
+- Trimming (`PublishTrimmed=true`) for self-contained deploys to reduce binary size. Mark trim-unsafe APIs with `[RequiresUnreferencedCode]`.
+- Use `Span<T>` / `Memory<T>` for hot-path buffer manipulation. `ArrayPool<T>.Shared` for transient large buffers to reduce GC pressure.
+- Profile with `dotnet-trace` and `dotnet-counters` before optimizing.
+
+## NuGet Hygiene
+
+- Central package management: define versions once in `Directory.Packages.props` (`<PackageVersion Include="Foo" Version="1.2.3" />`). Per-project references then drop the `Version` attribute.
+- Vulnerability scanning: `dotnet list package --vulnerable --include-transitive` in CI. Block merge on listed advisories.
+- License compliance: `dotnet-project-licenses` tool with an allowlist. Block GPL contamination via the allowlist.
+- Pin to released versions only — never `*` or floating prerelease versions.
+
+## References
+
+- .NET 9 release notes: https://learn.microsoft.com/en-us/dotnet/core/whats-new/dotnet-9 (accessed 2026-05-27, official-docs)
+- ASP.NET Core Minimal APIs: https://learn.microsoft.com/en-us/aspnet/core/fundamentals/minimal-apis/ (accessed 2026-05-27, official-docs)
+- EF Core 9.x: https://learn.microsoft.com/en-us/ef/core/what-is-new/ (accessed 2026-05-27, official-docs)
+- C# 13 features: https://learn.microsoft.com/en-us/dotnet/csharp/whats-new/csharp-13 (accessed 2026-05-27, official-docs)
+
+## Cross-References
+
+- `rules/hatch3r-api-design.md` — REST/GraphQL/gRPC contract floors apply to ASP.NET Core services.
+- `rules/hatch3r-testing.md` — coverage thresholds carry over to `dotnet test` + Coverlet.
+- `rules/hatch3r-observability-logging.md` — `Microsoft.Extensions.Logging` integration with the canonical logging contract.

package/dist/content/rules/hatch3r-edge-case-discipline.md

@@ -0,0 +1,65 @@
+---
+id: hatch3r-edge-case-discipline
+type: rule
+description: Build-time enumeration of domain/data-correctness edge cases (cardinality, null/empty/boundary, cross-entity consistency, illegal state transitions, concurrency, partial failure) plus language-agnostic error-handling discipline — fires at Plan, Implement, and Review
+tags: [implementation, reliability, testing, floor:content-quality]
+scope: always
+precedence: high
+quality_charter: agents/shared/quality-charter.md
+cache_friendly: true
+---
+# Edge-Case & Error-Handling Discipline
+
+**Pillars:** P2 (Scientific Quality)
+
+This rule fires whenever a feature wires together ≥2 domain entities, or whenever a function consumes external or user-supplied input. Edge-case enumeration becomes a named build-time step, not a runtime afterthought. `rules/hatch3r-resilience-patterns.md` keeps a correct system *available* under failure (breakers, retries, fallbacks); this rule keeps the system *correct* in the first place — the two complement each other and do not overlap.
+
+## When This Fires
+
+- **Plan:** before writing code, enumerate edge cases from the taxonomy below for every entity and every cross-entity relationship the feature touches. List them as explicit named cases (e.g. `case: two contacts collide on email + linked property`), never the placeholder "handle edge cases".
+- **Implement:** each enumerated case is handled in code OR explicitly recorded out-of-scope with a one-line reason. No silent omission — an unlisted case is a gap, an unhandled-but-listed case needs the recorded reason.
+- **Review:** reject the change if any taxonomy category was not enumerated for an entity-wiring feature, or an enumerated case has neither handling nor a recorded out-of-scope reason. Maps to a Medium-or-higher finding per `agents/shared/quality-charter.md` §14.
+
+## Domain Edge-Case Taxonomy
+
+Seven categories. For each: the question to ask, then a worked example in the real-estate domain (properties + contacts + reservations + deals).
+
+1. **Cardinality & duplicates** — for each relationship, what happens at zero, exactly-one, and N? Can two records collide on a natural key? Worked example: two contacts share the same email AND the same linked property but carry a different status — decide the dedup key and the tie-break rule (latest-updated wins, or merge) before writing the join, or the query returns a nondeterministic row.
+
+2. **Null / empty / zero / boundary** — apply boundary-value analysis (Min−1, Min, Max, Max+1) and equivalence partitioning to every numeric, string, and collection input. Worked example: a deal with `amount = 0`, a reservation with an empty date range (`start == end`), a property with zero linked contacts, a name string at the column-length limit and one byte over.
+
+3. **Cross-entity consistency & referential integrity** — if A references B, can B be missing, deleted, or in an invalid state when A is read? Worked example: a reservation pointing at an archived property; a deal whose contact was merged into another contact. Define cascade vs restrict vs orphan handling explicitly for each foreign reference; the default of an unhandled dangling reference is a 500 at read time.
+
+4. **Illegal state transitions** — model the entity lifecycle as an explicit state set, enumerate the legal transitions, and reject the rest at construction and at transition time. Worked example: a deal moving `closed → pending`; a reservation marked `confirmed` on a `withdrawn` listing. Apply make-illegal-states-unrepresentable / parse-don't-validate: validate once at the boundary, then the constructed type carries the proof so downstream code cannot re-encounter the illegal state.
+
+5. **Concurrency & ordering** — two writers modify the same record, or events arrive out of order. Worked example: two agents accept the same reservation slot at the same instant. Name the concurrency-control choice (optimistic version column, row lock, or idempotency key) at design time; "last write wins by accident" is not a choice. Cross-link `rules/hatch3r-scalability.md` and `rules/hatch3r-resilience-patterns.md`.
+
+6. **Partial failure across layers** — a single logical write spans cache + DB + queue + external API; what is the state when step 3 of 4 fails? Worked example: a deal is persisted to the DB, the cache is updated, the "deal-won" event is published, and the external CRM sync then times out. Define the consistency boundary (transaction, saga, or transactional outbox) and the compensating action. Cross-link `rules/hatch3r-resilience-patterns.md` failure classification.
+
+7. **Idempotency on replay / retry** — if the operation runs twice with the same input, is the second run a no-op? Required for any non-idempotent mutation reachable by a retry. Worked example: a retried "create reservation" call must not create two reservations for one slot. Cross-link `rules/hatch3r-resilience-patterns.md` → idempotency-key.
+
+The seven categories are a floor, not a ceiling: enumerate domain-specific invariants alongside them (e.g. "a property has at most one active deal", "a reservation date range never overlaps another confirmed reservation on the same property").
+
+## Error-Handling Discipline
+
+Language-agnostic principles; complements `rules/hatch3r-code-standards.md` and does not restate its TypeScript mechanics.
+
+- **Placement:** catch at architectural boundaries only (route handler, event handler, job processor, UI error boundary); let errors propagate within a module. Defer to `rules/hatch3r-code-standards.md` → Error Boundaries for the full pattern and the TS Result-type mechanics.
+- **Propagation with context:** every re-throw or wrap attaches the failing operation plus the relevant identifiers (entity id, correlation id — no PII, no secrets) and preserves the original cause chain. A wrap that drops the cause is a finding.
+- **Exhaustive matching:** every discriminated union, enum, and explicit state set is matched exhaustively with a compile-time-checked default, so adding a variant breaks the build rather than falling through silently. Cross-link `rules/hatch3r-code-standards.md` → exhaustive `switch` + `never`.
+- **Recovery vs fail-fast triage:** classify each failure as recoverable (fallback or degrade — cross-link `rules/hatch3r-resilience-patterns.md` → Graceful Degradation) or unrecoverable (fail fast with an actionable message — cross-link `agents/shared/quality-charter.md` §6). No catch block treats both alike.
+- **No silent catch (hard rule):** an empty catch, a catch that returns `null` or a default for every error, and swallow-and-continue are all prohibited. Defer to the `rules/hatch3r-code-standards.md` Error Handling Anti-Patterns table for the canonical prohibited list. This ties to `agents/shared/quality-charter.md` §6 (never fail silently) and §8 (a case that cannot be handled at build time is a clarification trigger, not a guess).
+
+## Cross-References
+
+- `rules/hatch3r-code-standards.md` — Result types, custom error classes, exhaustive `switch` + `never`, error anti-pattern table (the TS mechanics this rule references rather than restates).
+- `rules/hatch3r-resilience-patterns.md` — failure classification, idempotency-on-retry, graceful degradation (run-time resilience; this rule is build-time correctness).
+- `rules/hatch3r-testing.md` — every enumerated edge case maps to a required test class per the Per-Feature Mandate Map and Error Path Coverage.
+- `rules/hatch3r-scalability.md` — idempotency-key adoption on mutations.
+- `rules/hatch3r-migrations.md` — concurrent-modification and referential-integrity handling at the schema layer.
+- `agents/shared/quality-charter.md` — §6 (Fail Gracefully), §8 (Escalate Ambiguity Early), §13 (Adversarial Thinking).
+
+## References
+
+- ISTQB Certified Tester Foundation Level syllabus — Boundary Value Analysis + Equivalence Partitioning — `https://www.istqb.org/certifications/certified-tester-foundation-level` (accessed 2026-06-02, official-standards-body).
+- Alexis King, "Parse, Don't Validate" — `https://lexi-lambda.github.io/blog/2019/11/05/parse-don-t-validate/` (accessed 2026-06-02, named-author primary source).