hatch3r 1.9.0 → 2.0.0

package/dist/content/rules/hatch3r-tooling-hierarchy.md

@@ -2,18 +2,19 @@
 id: hatch3r-tooling-hierarchy
 type: rule
 description: Platform MCP-first priority, documentation MCP for library APIs, web research for CVEs, and browser MCP for UI verification with fallback guidance
-scope: "**/.hatch3r/**,**/mcp/**,**/mcp.json,**/.cursor/**,**/.github/copilot*,**/hatch.json,**/.claude/**"
+scope: conditional
+globs: "**/.hatch3r/**,**/mcp/**,**/mcp.json,**/.cursor/**,**/.github/copilot*,**/hatch.json,**/.claude/**"
 tags: [orchestration]
 quality_charter: agents/shared/quality-charter.md
 cache_friendly: true
 ---
 # Tooling Hierarchy
 
-## A. Platform MCP-First (when available)
+**Pillars:** P3 (Adapter & External Tool Currency), P7 (Speed & Token Efficiency)
 
-**Prefer platform MCP tools over the platform CLI** when the MCP server provides typed tools with structured input/output. Use them as the primary interface for issue tracker and repository operations.
+## A. Platform MCP-First (when available)
 
-Read `platform` from `.hatch3r/hatch.json` to determine which platform tools to use.
+**Prefer platform MCP tools over the platform CLI** when the MCP server provides typed tools with structured input/output. Use them as the primary interface for issue tracker and repository operations. Read `platform` from `.hatch3r/hatch.json` to determine which platform tools to use.
 
 ### Prerequisites
 
@@ -25,11 +26,7 @@ Read `platform` from `.hatch3r/hatch.json` to determine which platform tools to
 
 ### Platform CLI Fallback Reference
 
-**Fallback to the platform CLI only when:**
-- The MCP tool catalog lacks the specific capability.
-- An MCP call fails repeatedly and the CLI provides a viable alternative.
-
-**Never** use the platform CLI for operations that have a direct MCP equivalent (issue CRUD, PR/MR CRUD, search, labels).
+**Fallback to the platform CLI only when** the MCP tool catalog lacks the capability, or an MCP call fails repeatedly and the CLI provides a viable alternative. **Never** use the CLI for operations that have a direct MCP equivalent (issue CRUD, PR/MR CRUD, search, labels).
 
 | Action | GitHub | Azure DevOps | GitLab |
 |--------|--------|--------------|--------|
@@ -54,17 +51,21 @@ Read `platform` from `.hatch3r/hatch.json` to determine which platform tools to
 Use documentation MCP (e.g., Context7) to retrieve up-to-date, version-specific documentation for external libraries and frameworks. This prevents hallucinated APIs and outdated patterns.
 
 **When to use:**
-- Working with any external dependency.
+- Working with any external dependency, or reviewing code that uses third-party libraries.
 - Verifying API signatures, configuration options, or migration paths.
-- Reviewing code that uses third-party libraries.
-- Writing tests with external test frameworks.
-- Debugging errors from external libraries.
+- Writing tests with external test frameworks, or debugging errors from external libraries.
 
 **When NOT to use:**
 - Internal project specs — use project docs.
 - Internal codebase patterns — use Grep, SemanticSearch, or exploration tools.
 - General programming concepts not tied to a specific library.
 
+**Fallback when documentation MCP is unavailable:**
+If no documentation MCP server (e.g., Context7) is in `mcp.servers` in `.hatch3r/hatch.json`:
+- Fall back to web research (§C) for the library's official docs, then read the installed version's type definitions in `node_modules` (or the language equivalent).
+- Note in your output when a version-specific lookup would have been valuable (e.g., "Context7 lookup recommended for the express@5 migration but not available").
+- Do NOT assert API signatures from memory — flag any unverified third-party API as needing confirmation.
+
 ## C. Web Research for External Context
 
 Use web search to retrieve current, real-world information not available in project docs or library documentation.
@@ -72,20 +73,17 @@ Use web search to retrieve current, real-world information not available in proj
 **When to use:**
 - Latest security advisories, CVEs, or vulnerability disclosures for dependencies.
 - Breaking changes or deprecations in upcoming dependency versions.
-- Current best practices for architecture patterns, deployment strategies, or tooling.
+- Current best practices for architecture, deployment, or tooling, including comparing alternatives against current community consensus.
 - Novel problems with no match in docs (e.g., obscure error messages, platform-specific quirks).
-- Comparing alternative approaches or tools with current community consensus.
 
 **When NOT to use:**
 - Questions answerable from project specs or codebase exploration.
-- Standard library API questions (use documentation MCP instead).
-- Internal project decisions (use project ADRs).
+- Standard library API questions (use documentation MCP instead), or internal project decisions (use project ADRs).
 
 **Fallback when web search is unavailable:**
-If no web search MCP server is configured (e.g., `brave-search` is not in `mcp.servers` in `.hatch3r/hatch.json`), web research cannot be performed. In this case:
-- Note in your output when web research would have been valuable (e.g., "Web research recommended for CVE verification but not available").
+If no web search MCP server (e.g., `brave-search`) is in `mcp.servers` in `.hatch3r/hatch.json`:
+- Note in your output when web research would have been valuable (e.g., "Web research recommended for CVE verification but not available"), and flag security-sensitive decisions that would benefit from current advisory data.
 - Rely more heavily on Context7 documentation MCP and codebase exploration.
-- Flag security-sensitive decisions that would benefit from current advisory data.
 - Do NOT silently skip web research — surface the limitation so the user can decide whether to enable it.
 
 ## D. Browser Verification for UI Changes
@@ -96,26 +94,26 @@ Use browser automation MCP tools to visually verify UI changes after automated t
 - Verifying UI component changes render as specified in the design or acceptance criteria.
 - Reproducing and confirming fixes for visually observable bugs.
 - Accessibility auditing (keyboard nav, contrast, focus indicators).
-- Frontend performance profiling (CPU, frame rate, memory).
-- Capturing screenshot evidence for PRs.
+- Frontend performance profiling (CPU, frame rate, memory), and capturing screenshot evidence for PRs.
 
 **When NOT to use:**
 - Pure backend or API changes with no visual impact.
 - Configuration or infrastructure changes.
 - Code refactors that do not alter rendered output.
 
-**Available tools:**
-- IDE-native browser MCP (e.g., `cursor-ide-browser` in Cursor).
-- Playwright MCP (`@anthropic/mcp-playwright`) for cross-editor browser automation.
+**Fallback when browser MCP is unavailable:**
+If no browser automation MCP server is configured, defer interactive verification:
+- For accessibility, run an in-process axe-core check (`@axe-core/playwright`, `jest-axe`, or `axe-core` in a jsdom test) in the test suite to catch violations without a live browser.
+- Note in your output that visual/UI confirmation was skipped and recommend manual review before merge — do NOT silently skip it.
+
+**Available tools:** IDE-native browser MCP (e.g., `cursor-ide-browser` in Cursor); Playwright MCP (`@anthropic/mcp-playwright`) for cross-editor browser automation.
 
 ## E. Knowledge Augmentation Priority
 
-When seeking information, follow this priority order:
+When seeking information, follow this priority order, combining sources when valuable (e.g., read the spec, then verify external API usage with docs MCP, then check for recent advisories via web research):
 
 1. **Project specs and ADRs** — authoritative for project-specific behavior, constraints, and decisions.
-2. **Codebase exploration** (code search tools, semantic code search) — ground truth for current implementation.
-3. **Documentation MCP** — authoritative for external library/framework APIs and patterns.
+2. **Codebase exploration** (code search, semantic code search) — ground truth for current implementation.
+3. **Documentation MCP** — authoritative for external library/framework APIs and patterns. Falls back to web research + installed type definitions when unavailable (§B).
 4. **Web research** — current events, best practices, security advisories, novel problems.
-5. **Browser verification** — visual confirmation of UI changes after automated tests pass.
-
-Combine sources when valuable: read the spec first, then verify external API usage with docs MCP, then check for recent advisories via web research.
+5. **Browser verification** — visual confirmation of UI changes after automated tests pass; falls back to in-process axe-core for a11y when unavailable (§D).

package/dist/content/rules/hatch3r-tooling-hierarchy.mdc

@@ -5,11 +5,11 @@ alwaysApply: false
 ---
 # Tooling Hierarchy
 
-## A. Platform MCP-First (when available)
+**Pillars:** P3 (Adapter & External Tool Currency), P7 (Speed & Token Efficiency)
 
-**Prefer platform MCP tools over the platform CLI** when the MCP server provides typed tools with structured input/output. Use them as the primary interface for issue tracker and repository operations.
+## A. Platform MCP-First (when available)
 
-Read `platform` from `.hatch3r/hatch.json` to determine which platform tools to use.
+**Prefer platform MCP tools over the platform CLI** when the MCP server provides typed tools with structured input/output. Use them as the primary interface for issue tracker and repository operations. Read `platform` from `.hatch3r/hatch.json` to determine which platform tools to use.
 
 ### Prerequisites
 
@@ -21,11 +21,7 @@ Read `platform` from `.hatch3r/hatch.json` to determine which platform tools to
 
 ### Platform CLI Fallback Reference
 
-**Fallback to the platform CLI only when:**
-- The MCP tool catalog lacks the specific capability.
-- An MCP call fails repeatedly and the CLI provides a viable alternative.
-
-**Never** use the platform CLI for operations that have a direct MCP equivalent (issue CRUD, PR/MR CRUD, search, labels).
+**Fallback to the platform CLI only when** the MCP tool catalog lacks the capability, or an MCP call fails repeatedly and the CLI provides a viable alternative. **Never** use the CLI for operations that have a direct MCP equivalent (issue CRUD, PR/MR CRUD, search, labels).
 
 | Action | GitHub | Azure DevOps | GitLab |
 |--------|--------|--------------|--------|
@@ -50,17 +46,21 @@ Read `platform` from `.hatch3r/hatch.json` to determine which platform tools to
 Use documentation MCP (e.g., Context7) to retrieve up-to-date, version-specific documentation for external libraries and frameworks. This prevents hallucinated APIs and outdated patterns.
 
 **When to use:**
-- Working with any external dependency.
+- Working with any external dependency, or reviewing code that uses third-party libraries.
 - Verifying API signatures, configuration options, or migration paths.
-- Reviewing code that uses third-party libraries.
-- Writing tests with external test frameworks.
-- Debugging errors from external libraries.
+- Writing tests with external test frameworks, or debugging errors from external libraries.
 
 **When NOT to use:**
 - Internal project specs — use project docs.
 - Internal codebase patterns — use Grep, SemanticSearch, or exploration tools.
 - General programming concepts not tied to a specific library.
 
+**Fallback when documentation MCP is unavailable:**
+If no documentation MCP server (e.g., Context7) is in `mcp.servers` in `.hatch3r/hatch.json`:
+- Fall back to web research (§C) for the library's official docs, then read the installed version's type definitions in `node_modules` (or the language equivalent).
+- Note in your output when a version-specific lookup would have been valuable (e.g., "Context7 lookup recommended for the express@5 migration but not available").
+- Do NOT assert API signatures from memory — flag any unverified third-party API as needing confirmation.
+
 ## C. Web Research for External Context
 
 Use web search to retrieve current, real-world information not available in project docs or library documentation.
@@ -68,20 +68,17 @@ Use web search to retrieve current, real-world information not available in proj
 **When to use:**
 - Latest security advisories, CVEs, or vulnerability disclosures for dependencies.
 - Breaking changes or deprecations in upcoming dependency versions.
-- Current best practices for architecture patterns, deployment strategies, or tooling.
+- Current best practices for architecture, deployment, or tooling, including comparing alternatives against current community consensus.
 - Novel problems with no match in docs (e.g., obscure error messages, platform-specific quirks).
-- Comparing alternative approaches or tools with current community consensus.
 
 **When NOT to use:**
 - Questions answerable from project specs or codebase exploration.
-- Standard library API questions (use documentation MCP instead).
-- Internal project decisions (use project ADRs).
+- Standard library API questions (use documentation MCP instead), or internal project decisions (use project ADRs).
 
 **Fallback when web search is unavailable:**
-If no web search MCP server is configured (e.g., `brave-search` is not in `mcp.servers` in `.hatch3r/hatch.json`), web research cannot be performed. In this case:
-- Note in your output when web research would have been valuable (e.g., "Web research recommended for CVE verification but not available").
+If no web search MCP server (e.g., `brave-search`) is in `mcp.servers` in `.hatch3r/hatch.json`:
+- Note in your output when web research would have been valuable (e.g., "Web research recommended for CVE verification but not available"), and flag security-sensitive decisions that would benefit from current advisory data.
 - Rely more heavily on Context7 documentation MCP and codebase exploration.
-- Flag security-sensitive decisions that would benefit from current advisory data.
 - Do NOT silently skip web research — surface the limitation so the user can decide whether to enable it.
 
 ## D. Browser Verification for UI Changes
@@ -92,26 +89,26 @@ Use browser automation MCP tools to visually verify UI changes after automated t
 - Verifying UI component changes render as specified in the design or acceptance criteria.
 - Reproducing and confirming fixes for visually observable bugs.
 - Accessibility auditing (keyboard nav, contrast, focus indicators).
-- Frontend performance profiling (CPU, frame rate, memory).
-- Capturing screenshot evidence for PRs.
+- Frontend performance profiling (CPU, frame rate, memory), and capturing screenshot evidence for PRs.
 
 **When NOT to use:**
 - Pure backend or API changes with no visual impact.
 - Configuration or infrastructure changes.
 - Code refactors that do not alter rendered output.
 
-**Available tools:**
-- IDE-native browser MCP (e.g., `cursor-ide-browser` in Cursor).
-- Playwright MCP (`@anthropic/mcp-playwright`) for cross-editor browser automation.
+**Fallback when browser MCP is unavailable:**
+If no browser automation MCP server is configured, defer interactive verification:
+- For accessibility, run an in-process axe-core check (`@axe-core/playwright`, `jest-axe`, or `axe-core` in a jsdom test) in the test suite to catch violations without a live browser.
+- Note in your output that visual/UI confirmation was skipped and recommend manual review before merge — do NOT silently skip it.
+
+**Available tools:** IDE-native browser MCP (e.g., `cursor-ide-browser` in Cursor); Playwright MCP (`@anthropic/mcp-playwright`) for cross-editor browser automation.
 
 ## E. Knowledge Augmentation Priority
 
-When seeking information, follow this priority order:
+When seeking information, follow this priority order, combining sources when valuable (e.g., read the spec, then verify external API usage with docs MCP, then check for recent advisories via web research):
 
 1. **Project specs and ADRs** — authoritative for project-specific behavior, constraints, and decisions.
-2. **Codebase exploration** (code search tools, semantic code search) — ground truth for current implementation.
-3. **Documentation MCP** — authoritative for external library/framework APIs and patterns.
+2. **Codebase exploration** (code search, semantic code search) — ground truth for current implementation.
+3. **Documentation MCP** — authoritative for external library/framework APIs and patterns. Falls back to web research + installed type definitions when unavailable (§B).
 4. **Web research** — current events, best practices, security advisories, novel problems.
-5. **Browser verification** — visual confirmation of UI changes after automated tests pass.
-
-Combine sources when valuable: read the spec first, then verify external API usage with docs MCP, then check for recent advisories via web research.
+5. **Browser verification** — visual confirmation of UI changes after automated tests pass; falls back to in-process axe-core for a11y when unavailable (§D).

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

@@ -0,0 +1,58 @@
+---
+id: hatch3r-typescript-patterns
+type: rule
+description: TypeScript and JavaScript typing mechanics — satisfies over as, discriminated unions, branded types, strict utility types, barrel exports, and import ordering
+scope: conditional
+globs: "**/*.ts,**/*.tsx,**/*.mts,**/*.cts,**/*.js,**/*.jsx,**/*.mjs,**/*.cjs,**/tsconfig*.json,**/.eslintrc*,**/eslint.config.*"
+tags: [implementation, lang:typescript]
+quality_charter: agents/shared/quality-charter.md
+cache_friendly: true
+---
+# TypeScript Patterns
+
+**Pillars:** P2 (Scientific & Practical Quality), CQ8 (Maintainability Quality)
+
+> Applies when the project ships TypeScript or JavaScript. Detection signals: `tsconfig.json` at repo root, `*.ts`/`*.tsx` source files, or an ESLint config. This rule carries the TypeScript/JavaScript-specific typing, barrel, and import mechanics that were split out of `rules/hatch3r-code-standards.md` (the language-agnostic code floor) under D14-14 / SA14.1-F3, so these idioms bind only on TS/JS repos and not as a floor on Go, Rust, Python, Ruby, or Java repos where they are nonsensical.
+
+## TypeScript-Specific Patterns
+
+### `satisfies` Over `as`
+
+- Use `satisfies` to validate a value conforms to a type while preserving its narrower inferred type. Prefer `satisfies Config` over `as Config` because `as` silences type errors and loses narrowing.
+- Use `as const` for literal types in configuration objects, action types, and discriminant values. Combine with `satisfies` when both literal inference and shape validation are needed: `const config = { ... } as const satisfies Config`.
+
+### Discriminated Unions
+
+- Model domain variants with discriminated unions over polymorphic classes or `type` string checks. Every variant must share a common literal discriminant field (e.g., `kind`, `type`, `status`).
+- Use a `switch` that handles every variant, with a `never` default case so the compiler errors when a new variant is added but not handled.
+
+### Branded Types
+
+- Use branded types for domain identifiers that must not be accidentally interchanged (e.g., `UserId`, `OrderId`, `Currency`). Implement via intersection with a unique symbol: `type UserId = string & { readonly __brand: unique symbol }`.
+- Provide factory functions (`createUserId(raw: string): UserId`) that validate the input before branding. Never brand raw values without validation.
+
+### Strict Utility Types
+
+- Prefer `Readonly<T>` for function parameters and return types that should not be mutated by the caller.
+- Use `Record<string, never>` instead of `{}` to represent an empty object type. `{}` matches any non-nullish value.
+- Avoid `Omit` with string literals that do not exist on the source type — use `satisfies` or a helper type that enforces key existence.
+
+## Barrel Exports
+
+- Use barrel files (`index.ts`) at module boundaries to define the public API of a module. Re-export only the types and functions intended for external consumption.
+- Never import from a module's internal files directly — import from the barrel. Enforce with ESLint `no-restricted-imports` or equivalent.
+- Keep barrel files thin — only re-exports, no logic. A barrel with logic is a code smell.
+
+## Import Ordering
+
+Enforce consistent import ordering via linter rules (e.g., `eslint-plugin-import`). The canonical order:
+
+1. **Built-in modules** — `node:fs`, `node:path`, etc.
+2. **External packages** — `zod`, `express`, etc.
+3. **Internal aliases** — `@/utils`, `@/types`, etc.
+4. **Relative imports** — `./sibling`, `../parent`, etc.
+5. **Type-only imports** — `import type { ... }` (grouped separately where the linter supports it)
+
+Separate each group with a blank line. Sort alphabetically within each group.
+
+Reference: `rules/hatch3r-code-standards.md` (language-agnostic code floor — naming, size caps, Result-type error handling, module boundaries, dead-code, untrusted-content hygiene), `rules/hatch3r-edge-case-discipline.md` (every-variant-matching and silent-catch rules that build on the discriminated-union mechanics above).

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

@@ -0,0 +1,53 @@
+---
+description: TypeScript and JavaScript typing mechanics — satisfies over as, discriminated unions, branded types, strict utility types, barrel exports, and import ordering
+globs: ["**/*.ts", "**/*.tsx", "**/*.mts", "**/*.cts", "**/*.js", "**/*.jsx", "**/*.mjs", "**/*.cjs", "**/tsconfig*.json", "**/.eslintrc*", "**/eslint.config.*"]
+alwaysApply: false
+---
+# TypeScript Patterns
+
+**Pillars:** P2 (Scientific & Practical Quality), CQ8 (Maintainability Quality)
+
+> Applies when the project ships TypeScript or JavaScript. Detection signals: `tsconfig.json` at repo root, `*.ts`/`*.tsx` source files, or an ESLint config. This rule carries the TypeScript/JavaScript-specific typing, barrel, and import mechanics that were split out of `rules/hatch3r-code-standards.md` (the language-agnostic code floor) under D14-14 / SA14.1-F3, so these idioms bind only on TS/JS repos and not as a floor on Go, Rust, Python, Ruby, or Java repos where they are nonsensical.
+
+## TypeScript-Specific Patterns
+
+### `satisfies` Over `as`
+
+- Use `satisfies` to validate a value conforms to a type while preserving its narrower inferred type. Prefer `satisfies Config` over `as Config` because `as` silences type errors and loses narrowing.
+- Use `as const` for literal types in configuration objects, action types, and discriminant values. Combine with `satisfies` when both literal inference and shape validation are needed: `const config = { ... } as const satisfies Config`.
+
+### Discriminated Unions
+
+- Model domain variants with discriminated unions over polymorphic classes or `type` string checks. Every variant must share a common literal discriminant field (e.g., `kind`, `type`, `status`).
+- Use a `switch` that handles every variant, with a `never` default case so the compiler errors when a new variant is added but not handled.
+
+### Branded Types
+
+- Use branded types for domain identifiers that must not be accidentally interchanged (e.g., `UserId`, `OrderId`, `Currency`). Implement via intersection with a unique symbol: `type UserId = string & { readonly __brand: unique symbol }`.
+- Provide factory functions (`createUserId(raw: string): UserId`) that validate the input before branding. Never brand raw values without validation.
+
+### Strict Utility Types
+
+- Prefer `Readonly<T>` for function parameters and return types that should not be mutated by the caller.
+- Use `Record<string, never>` instead of `{}` to represent an empty object type. `{}` matches any non-nullish value.
+- Avoid `Omit` with string literals that do not exist on the source type — use `satisfies` or a helper type that enforces key existence.
+
+## Barrel Exports
+
+- Use barrel files (`index.ts`) at module boundaries to define the public API of a module. Re-export only the types and functions intended for external consumption.
+- Never import from a module's internal files directly — import from the barrel. Enforce with ESLint `no-restricted-imports` or equivalent.
+- Keep barrel files thin — only re-exports, no logic. A barrel with logic is a code smell.
+
+## Import Ordering
+
+Enforce consistent import ordering via linter rules (e.g., `eslint-plugin-import`). The canonical order:
+
+1. **Built-in modules** — `node:fs`, `node:path`, etc.
+2. **External packages** — `zod`, `express`, etc.
+3. **Internal aliases** — `@/utils`, `@/types`, etc.
+4. **Relative imports** — `./sibling`, `../parent`, etc.
+5. **Type-only imports** — `import type { ... }` (grouped separately where the linter supports it)
+
+Separate each group with a blank line. Sort alphabetically within each group.
+
+Reference: `rules/hatch3r-code-standards.md` (language-agnostic code floor — naming, size caps, Result-type error handling, module boundaries, dead-code, untrusted-content hygiene), `rules/hatch3r-edge-case-discipline.md` (every-variant-matching and silent-catch rules that build on the discriminated-union mechanics above).

package/dist/content/rules/hatch3r-ux-states-and-flows.md

@@ -2,7 +2,8 @@
 id: hatch3r-ux-states-and-flows
 type: rule
 description: Four-state surface contract (loading/empty/error/partial), user-flow decomposition before implementation, and microcopy + tone discipline for end-user UIs
-scope: "**/*.vue,**/*.jsx,**/*.tsx,**/*.svelte,**/components/**,**/*.html,**/messages/**,**/locales/**,**/copy/**"
+scope: conditional
+globs: "**/*.vue,**/*.jsx,**/*.tsx,**/*.svelte,**/components/**,**/*.html,**/messages/**,**/locales/**,**/copy/**"
 tags: [implementation, floor:ui-ux, ux, ui, frontend]
 precedence: high
 quality_charter: agents/shared/quality-charter.md
@@ -24,7 +25,7 @@ Flow decomposition is also the contract between the feature designer and the rev
 
 ## Four-State Surface Contract
 
-Every async view renders all four states. Missing any state on an async view is a blocker — NN/g 2025 measured 92% of AI-generated dashboards omit empty state and 78% omit error state, so this is the regression bar to beat.
+Every async view renders all four states. Missing any state on an async view is a blocker: the empty, error, and partial states are each a distinct cause-and-recovery path, and dropping one strands the user with no diagnosis or next action when that path fires (an empty result reads as a broken load, a failed request reads as a hang, a partial result silently hides the failed subset). The blocker is justified by recovery-path completeness, not by an omission-frequency statistic. NN/g empty-state and error-message guidance ([empty states](https://www.nngroup.com/articles/empty-state-interface-design/), [error messages](https://www.nngroup.com/articles/error-message-guidelines/), both accessed 2026-06-05, NN/g, official-docs) anchors the per-state rendering rules below.
 
 | State | Trigger | Rendering rules |
 |-------|---------|-----------------|
@@ -37,6 +38,10 @@ State machines drive these transitions — model the view as `idle | loading | s
 
 Transitions between states have their own rules. Loading -> success swaps the skeleton for content without layout shift (the skeleton was already the final dimensions). Loading -> error replaces the skeleton with the error surface and announces it via `role="alert"`. Loading -> empty replaces the skeleton with the sub-typed empty surface (cold / filter / permission). Success -> partial overlays the banner without re-rendering the succeeded subset. Every transition has a measurable duration and an announcement strategy — never silent.
 
+### Partial-state fixture recipe
+
+Loading, empty, and error each fixture from one mocked response (delay it, return `[]`, return a 5xx). Partial is the hard case the snapshot blocker most often strands on: it requires two concurrent requests resolving to opposite outcomes in a single render. Build it one of two ways. (1) **MSW per-endpoint**: register two handlers in the same worker — `http.get('/api/widgets', () => HttpResponse.json(widgets))` and `http.get('/api/sidebar', () => HttpResponse.json(null, { status: 500 }))` — so the view mounts its 200 subset and its 500 subset together and the partial banner renders against real degraded data. (2) **`Promise.allSettled` with a forced rejection**: have the fixture's data layer resolve the succeeded fetch and reject the failed one (`Promise.allSettled([ok(widgets), Promise.reject(new Error('sidebar 500'))])`), then assert the component reads `status === 'rejected'` on the failed entry and renders the banner + retry for that subset only. Either path produces the snapshot Gate 4 (`skills/hatch3r-ui-ux-verify/SKILL.md` -> Gate 4) requires; do not stub the partial state by hand-editing the success snapshot, which never exercises the failed-subset render path.
+
 ## First-Run vs Filter vs Network — Content Structure
 
 | State type | Heading level | Visual cue | CTA | Example |
@@ -109,7 +114,7 @@ Anchored to GOV.UK Design System (error pattern, plain English) and IBM Carbon (
 ## Mobile and Touch
 
 - Touch target minimum: 44pt on iOS HIG, 48dp on Material 3. The platform minimum supersedes WCAG SC 2.5.8 (24x24 CSS px) on touch surfaces — use the stricter bound.
-- Spacing between adjacent interactive elements: >=8px to avoid mis-taps. Measure on the rendered DOM, not on the design comp — padding and margins count toward hit area only when they belong to the same interactive element.
+- Spacing between adjacent interactive elements: >=8px to avoid mis-taps. Measure on the rendered DOM (web) or the rendered native view tree (RN/Flutter/SwiftUI/Compose), not on the design comp — padding and margins count toward hit area only when they belong to the same interactive element.
 - Avoid tap-to-reveal (hover-only tooltip) on touch surfaces. Use permanent labels or long-press with a visible affordance. Hover-only tooltips fail WCAG SC 1.4.13 Content on Hover or Focus on touch.
 - Apply `env(safe-area-inset-*)` on full-bleed surfaces so primary CTAs do not sit under the iOS home indicator, notch, or Android gesture nav. Native equivalents: `safeAreaInsets` on iOS, `WindowInsets` on Android.
 - Dynamic Type on iOS (`UIFont.preferredFont(forTextStyle:)` or SwiftUI `Font.body`) and rem-based font scaling on Android/web. Never use hard-coded `px` for text — fails text-resize verification at 200% zoom (WCAG SC 1.4.4) and 400% reflow (SC 1.4.10).
@@ -117,6 +122,7 @@ Anchored to GOV.UK Design System (error pattern, plain English) and IBM Carbon (
 - Pointer-event vs touch-event: prefer pointer events (`pointerdown`, `pointermove`, `pointerup`) so the same handler covers mouse, touch, pen. Synthesize click events on tap with a 300ms tolerance only on legacy mobile browsers — modern engines emit click immediately.
 - Pinch-zoom: never disable user zoom on the viewport meta tag. WCAG SC 1.4.4 fails on disabled zoom. Use `maximum-scale=5` to allow up to 5x zoom while suppressing zoom-on-focus jitter.
 - Orientation lock: respect WCAG SC 1.3.4 — content adapts to portrait and landscape unless an essential exception applies (e.g., piano keyboard, blueprint editor). Document the exception in the spec.
+- Native verification: the touch obligations above hold for React Native, Flutter, SwiftUI/UIKit, and Android Compose/View targets, which have no DOM for axe-core to scan. Verify them with the framework-native a11y check (`eslint-plugin-react-native-a11y`; Flutter `meets_guideline` matchers; Espresso `AccessibilityChecks`; XCUITest `performAccessibilityAudit()`) per `rules/hatch3r-accessibility-standards.md` -> Mobile-native verification path; a native obligation with no such check is `BLOCKED_MISSING_TOOL`, not satisfied.
 
 ## Heuristic Verification Gate
 
@@ -134,7 +140,8 @@ Run every check below before declaring a feature done. A "done" claim without th
 ## References
 
 - WCAG 2.2 AA — new success criteria SC 2.5.8 (Target Size), SC 2.4.11 (Focus Not Obscured), SC 2.5.7 (Dragging Movements), SC 1.4.13 (Content on Hover or Focus)
-- NN/g state-omission research 2025 — empty-state and error-state omission rates in AI-generated UIs (92% empty omitted, 78% error omitted)
+- Nielsen Norman Group, "Designing Empty States in Complex Applications: 3 Guidelines" — https://www.nngroup.com/articles/empty-state-interface-design/ (accessed 2026-06-05, NN/g, official-docs)
+- Nielsen Norman Group, "Error-Message Guidelines" — https://www.nngroup.com/articles/error-message-guidelines/ (accessed 2026-06-05, NN/g, official-docs)
 - GOV.UK Design System — error message and error summary components, plain English readability guidance
 - IBM Carbon Design System — voice and tone content guidelines, error message patterns
 - Baymard Institute — inline form validation research and disabled-submit findings (top-10 form-abandonment driver)

package/dist/content/rules/hatch3r-ux-states-and-flows.mdc

@@ -20,7 +20,7 @@ Flow decomposition is also the contract between the feature designer and the rev
 
 ## Four-State Surface Contract
 
-Every async view renders all four states. Missing any state on an async view is a blocker — NN/g 2025 measured 92% of AI-generated dashboards omit empty state and 78% omit error state, so this is the regression bar to beat.
+Every async view renders all four states. Missing any state on an async view is a blocker: the empty, error, and partial states are each a distinct cause-and-recovery path, and dropping one strands the user with no diagnosis or next action when that path fires (an empty result reads as a broken load, a failed request reads as a hang, a partial result silently hides the failed subset). The blocker is justified by recovery-path completeness, not by an omission-frequency statistic. NN/g empty-state and error-message guidance ([empty states](https://www.nngroup.com/articles/empty-state-interface-design/), [error messages](https://www.nngroup.com/articles/error-message-guidelines/), both accessed 2026-06-05, NN/g, official-docs) anchors the per-state rendering rules below.
 
 | State | Trigger | Rendering rules |
 |-------|---------|-----------------|
@@ -33,6 +33,10 @@ State machines drive these transitions — model the view as `idle | loading | s
 
 Transitions between states have their own rules. Loading -> success swaps the skeleton for content without layout shift (the skeleton was already the final dimensions). Loading -> error replaces the skeleton with the error surface and announces it via `role="alert"`. Loading -> empty replaces the skeleton with the sub-typed empty surface (cold / filter / permission). Success -> partial overlays the banner without re-rendering the succeeded subset. Every transition has a measurable duration and an announcement strategy — never silent.
 
+### Partial-state fixture recipe
+
+Loading, empty, and error each fixture from one mocked response (delay it, return `[]`, return a 5xx). Partial is the hard case the snapshot blocker most often strands on: it requires two concurrent requests resolving to opposite outcomes in a single render. Build it one of two ways. (1) **MSW per-endpoint**: register two handlers in the same worker — `http.get('/api/widgets', () => HttpResponse.json(widgets))` and `http.get('/api/sidebar', () => HttpResponse.json(null, { status: 500 }))` — so the view mounts its 200 subset and its 500 subset together and the partial banner renders against real degraded data. (2) **`Promise.allSettled` with a forced rejection**: have the fixture's data layer resolve the succeeded fetch and reject the failed one (`Promise.allSettled([ok(widgets), Promise.reject(new Error('sidebar 500'))])`), then assert the component reads `status === 'rejected'` on the failed entry and renders the banner + retry for that subset only. Either path produces the snapshot Gate 4 (`skills/hatch3r-ui-ux-verify/SKILL.md` -> Gate 4) requires; do not stub the partial state by hand-editing the success snapshot, which never exercises the failed-subset render path.
+
 ## First-Run vs Filter vs Network — Content Structure
 
 | State type | Heading level | Visual cue | CTA | Example |
@@ -105,7 +109,7 @@ Anchored to GOV.UK Design System (error pattern, plain English) and IBM Carbon (
 ## Mobile and Touch
 
 - Touch target minimum: 44pt on iOS HIG, 48dp on Material 3. The platform minimum supersedes WCAG SC 2.5.8 (24x24 CSS px) on touch surfaces — use the stricter bound.
-- Spacing between adjacent interactive elements: >=8px to avoid mis-taps. Measure on the rendered DOM, not on the design comp — padding and margins count toward hit area only when they belong to the same interactive element.
+- Spacing between adjacent interactive elements: >=8px to avoid mis-taps. Measure on the rendered DOM (web) or the rendered native view tree (RN/Flutter/SwiftUI/Compose), not on the design comp — padding and margins count toward hit area only when they belong to the same interactive element.
 - Avoid tap-to-reveal (hover-only tooltip) on touch surfaces. Use permanent labels or long-press with a visible affordance. Hover-only tooltips fail WCAG SC 1.4.13 Content on Hover or Focus on touch.
 - Apply `env(safe-area-inset-*)` on full-bleed surfaces so primary CTAs do not sit under the iOS home indicator, notch, or Android gesture nav. Native equivalents: `safeAreaInsets` on iOS, `WindowInsets` on Android.
 - Dynamic Type on iOS (`UIFont.preferredFont(forTextStyle:)` or SwiftUI `Font.body`) and rem-based font scaling on Android/web. Never use hard-coded `px` for text — fails text-resize verification at 200% zoom (WCAG SC 1.4.4) and 400% reflow (SC 1.4.10).
@@ -113,6 +117,7 @@ Anchored to GOV.UK Design System (error pattern, plain English) and IBM Carbon (
 - Pointer-event vs touch-event: prefer pointer events (`pointerdown`, `pointermove`, `pointerup`) so the same handler covers mouse, touch, pen. Synthesize click events on tap with a 300ms tolerance only on legacy mobile browsers — modern engines emit click immediately.
 - Pinch-zoom: never disable user zoom on the viewport meta tag. WCAG SC 1.4.4 fails on disabled zoom. Use `maximum-scale=5` to allow up to 5x zoom while suppressing zoom-on-focus jitter.
 - Orientation lock: respect WCAG SC 1.3.4 — content adapts to portrait and landscape unless an essential exception applies (e.g., piano keyboard, blueprint editor). Document the exception in the spec.
+- Native verification: the touch obligations above hold for React Native, Flutter, SwiftUI/UIKit, and Android Compose/View targets, which have no DOM for axe-core to scan. Verify them with the framework-native a11y check (`eslint-plugin-react-native-a11y`; Flutter `meets_guideline` matchers; Espresso `AccessibilityChecks`; XCUITest `performAccessibilityAudit()`) per `rules/hatch3r-accessibility-standards.md` -> Mobile-native verification path; a native obligation with no such check is `BLOCKED_MISSING_TOOL`, not satisfied.
 
 ## Heuristic Verification Gate
 
@@ -130,7 +135,8 @@ Run every check below before declaring a feature done. A "done" claim without th
 ## References
 
 - WCAG 2.2 AA — new success criteria SC 2.5.8 (Target Size), SC 2.4.11 (Focus Not Obscured), SC 2.5.7 (Dragging Movements), SC 1.4.13 (Content on Hover or Focus)
-- NN/g state-omission research 2025 — empty-state and error-state omission rates in AI-generated UIs (92% empty omitted, 78% error omitted)
+- Nielsen Norman Group, "Designing Empty States in Complex Applications: 3 Guidelines" — https://www.nngroup.com/articles/empty-state-interface-design/ (accessed 2026-06-05, NN/g, official-docs)
+- Nielsen Norman Group, "Error-Message Guidelines" — https://www.nngroup.com/articles/error-message-guidelines/ (accessed 2026-06-05, NN/g, official-docs)
 - GOV.UK Design System — error message and error summary components, plain English readability guidance
 - IBM Carbon Design System — voice and tone content guidelines, error message patterns
 - Baymard Institute — inline form validation research and disabled-submit findings (top-10 form-abandonment driver)

package/dist/content/skills/hatch3r-a11y-audit/SKILL.md

@@ -1,6 +1,8 @@
 ---
 id: hatch3r-a11y-audit
-description: Run a WCAG AA accessibility audit with findings and fixes across 7 scan categories (keyboard, contrast, ARIA, reduced motion, screen reader, high contrast, automated axe). Use when auditing accessibility or verifying WCAG compliance.
+name: hatch3r-a11y-audit
+type: skill
+description: Runs a WCAG AA accessibility audit with findings and fixes across 7 scan categories (keyboard, contrast, ARIA, reduced motion, screen reader, high contrast, automated axe). Use when auditing accessibility or verifying WCAG compliance.
 tags: [review, floor:ui-ux, a11y]
 quality_charter: agents/shared/quality-charter.md
 efficiency_patterns: agents/shared/efficiency-patterns.md
@@ -27,12 +29,7 @@ Before any work, scan the invocation for unresolved questions in scope, intent,
 
 ## Fan-out Discipline (P8 B2)
 
-This skill delegates per task size:
-- Tier 1 (trivial single-file): inline execution acceptable.
-- Tier 2 (multi-file or multi-concern): spawn parallel sub-agents per concern via the Task tool.
-- Tier 3 (multi-module / high-risk): one fresh sub-agent per independent module or gate; orchestrator integrates only.
-
-Never under-fan-out to save tokens. Token cost is dominated by quality and completeness gains. Emit `sub_agents_spawned: { count, rationale }` in your output.
+Fan-out scales with task size; token cost never justifies serializing independent work (`rules/hatch3r-fan-out-discipline.md` P8 B2; `agents/shared/efficiency-patterns.md`). Emit `sub_agents_spawned: { count, rationale }` in your output.
 
 ## Progressive Disclosure
 
@@ -97,7 +94,7 @@ Use the severity rubric in `references/manual-audit-checklist.md` to assign seve
 
 You MUST spawn these agents via the Task tool (`subagent_type: "generalPurpose"`) at the appropriate points:
 
-- **`hatch3r-a11y-auditor`** — MUST spawn to perform the full WCAG AA compliance audit autonomously. Provide the list of surfaces/components to audit and the current violation list.
+- **`hatch3r-ui`** (CQ1) — MUST spawn to perform the full WCAG AA compliance audit autonomously (axe-core + design-token + four-state + deep ARIA / reduced-motion). Provide the list of surfaces/components to audit and the current violation list.
 
 ## Related Rules
 
@@ -119,3 +116,8 @@ You MUST spawn these agents via the Task tool (`subagent_type: "generalPurpose"`
 - [ ] ARIA live regions for dynamic content
 - [ ] Automated scan clean for critical/major
 - [ ] Manual verification completed
+
+## References
+
+- [WCAG 2.2 — W3C Recommendation](https://www.w3.org/TR/WCAG22/) — accessed 2026-05-31, official-docs (W3C). Source for the success criteria (1.1.1, 1.4.3, 2.1.1, 4.1.2) and the 4.5:1 AA text-contrast ratio cited above.
+- [axe-core rules and WCAG mapping](https://github.com/dequelabs/axe-core/blob/develop/doc/rule-descriptions.md) — accessed 2026-05-31, independent-analysis (Deque Systems). Source for the automated-scan rule IDs and impact levels mapped to WCAG criteria in Step 2.

package/dist/content/skills/hatch3r-a11y-audit/references/manual-audit-checklist.md

@@ -49,10 +49,12 @@ Loaded on demand during Step 3 of the accessibility audit workflow when a detail
 
 ## Severity Cataloging
 
-| Severity | Definition                              | Examples                                                      |
-| -------- | --------------------------------------- | ------------------------------------------------------------- |
-| Critical | Blocks core functionality, fails WCAG A | Missing form labels, no keyboard access to primary actions    |
-| Major    | Significant barrier, fails WCAG AA      | Contrast < 4.5:1, missing focus indicators, no reduced motion |
-| Minor    | Improves experience, best practice      | Redundant labels, suboptimal heading order                    |
+WCAG conformance levels map to the canonical audit severity 5-tier via `agents/shared/severity-mapping.md` — `Critical → Critical`, `Major → Medium` (escalate to High when blocking a critical user journey per the table's A11y-Auditor row), `Minor → Low`. Findings reported to consumers (`hatch3r-fixer`, audit registry) MUST use the canonical 5-tier or carry the mapping reference; this file documents the local WCAG vocabulary alongside the canonical pointer.
+
+| Severity (local WCAG) | Canonical map         | Definition                              | Examples                                                      |
+| --------------------- | --------------------- | --------------------------------------- | ------------------------------------------------------------- |
+| Critical              | Critical              | Blocks core functionality, fails WCAG A | Missing form labels, no keyboard access to primary actions    |
+| Major                 | Medium (High if blocking critical journey) | Significant barrier, fails WCAG AA      | Contrast < 4.5:1, missing focus indicators, no reduced motion |
+| Minor                 | Low                   | Improves experience, best practice      | Redundant labels, suboptimal heading order                    |
 
 Produce a findings table: ID, severity, WCAG criterion, description, location, fix suggestion. Prioritize critical first, then major. Minor can be batched.