hatch3r 1.8.0 → 2.0.0

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/{rules → dist/content/rules}/hatch3r-ux-states-and-flows.md

@@ -2,8 +2,10 @@
 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/**"
-tags: [ux, ui, frontend]
+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
 cache_friendly: true
 ---
@@ -23,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 |
 |-------|---------|-----------------|
@@ -36,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 |
@@ -108,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).
@@ -116,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
 
@@ -133,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/{rules → dist/content/rules}/hatch3r-ux-states-and-flows.mdc

@@ -2,6 +2,7 @@
 description: Four-state surface contract (loading/empty/error/partial), user-flow decomposition before implementation, and microcopy + tone discipline for end-user UIs
 globs: ["**/*.vue", "**/*.jsx", "**/*.tsx", "**/*.svelte", "**/components/**", "**/*.html", "**/messages/**", "**/locales/**", "**/copy/**"]
 alwaysApply: false
+precedence: high
 ---
 # UX States and Flows
 
@@ -19,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 |
 |-------|---------|-----------------|
@@ -32,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 |
@@ -104,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).
@@ -112,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
 
@@ -129,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/{skills → dist/content/skills}/hatch3r-a11y-audit/SKILL.md

@@ -1,7 +1,9 @@
 ---
 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.
-tags: [review, a11y]
+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
 cache_friendly: true
@@ -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/{skills → 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.

package/dist/content/skills/hatch3r-adhoc-orchestrate/SKILL.md

@@ -0,0 +1,131 @@
+---
+id: hatch3r-adhoc-orchestrate
+name: hatch3r-adhoc-orchestrate
+type: skill
+description: Scaffolds the ad-hoc Tier >= 2 orchestration protocol -- Per-Turn Pipeline-State Header, implementer delegation plan, End-of-Turn Delegation Attestation. Use for a maintainer multi-phase task with no registered command to avoid bypass mode.
+tags: [orchestration]
+quality_charter: agents/shared/quality-charter.md
+efficiency_patterns: agents/shared/efficiency-patterns.md
+cache_friendly: true
+parallel_tool_default: true
+sub_agents_spawned:
+  count: 0
+  rationale: This is a scaffolding skill — it emits the orchestration-protocol blocks for the maintainer's own multi-phase task; the maintainer's task then spawns its own implementer/fixer sub-agents per the plan this skill produces. The skill itself delegates nothing.
+---
+
+# Ad-Hoc Orchestration Scaffold
+
+## Quick Start
+
+```
+Task Progress:
+- [ ] Step 0: Detect ambiguity (P8 B1)
+- [ ] Step 1: Score the task tier (Tier >= 2 gate)
+- [ ] Step 2: Emit the Per-Turn Pipeline-State Header
+- [ ] Step 3: Build the delegation plan (no inline implementation)
+- [ ] Step 4: Emit the End-of-Turn Delegation Attestation template
+- [ ] Step 5: Verify the bypass-protection checklist
+```
+
+A multi-phase task driven by hand — research + implement + review, no registered `/h4tcher-*` command — is still bound by the **Orchestrator Self-Discipline (Bypass Protection)** contract in `CLAUDE.md` and `rules/hatch3r-agent-orchestration.md`. The CHANGELOG #73 failure mode is exactly this: running research and review sub-agents while inlining the implementation, escaping the protocol because no command was invoked. This skill is the turnkey scaffold that closes that loophole — it does not perform the work; it emits the three required protocol blocks so the maintainer's ad-hoc flow stays attributable.
+
+Use this skill at the start of any maintainer-side multi-phase task at Tier >= 2 that is NOT already running under a registered command (which carries these blocks itself). When the work matches a registered intent, prefer the command: `/h4tcher-capability-add`, `/h4tcher-capability-refactor`, `/h4tcher-capability-remove` for lifecycle work; `commands/hatch3r-*.md` for end-user content workflows.
+
+## Step 0 — Detect Ambiguity (P8 B1)
+
+Before any work, scan the invocation for unresolved questions in scope, intent, acceptance criteria, target files, or irreversibility. If any are found, ask the user via the platform-native question tool per `agents/shared/user-question-protocol.md`. Do not proceed under silent assumption. Default path, not an exception. Triggers for THIS skill: the task tier is genuinely uncertain (Tier 1 vs Tier 2 changes whether the protocol even applies), the set of files to mutate is unbounded, or a registered command already covers the intent (route there instead of scaffolding).
+
+## Step 1: Score the Task Tier (Tier >= 2 Gate)
+
+The protocol binds at Tier 2 and Tier 3 only. Score the task per the `hatch3r-deep-context` rule (deep-context score >= 3 → Tier >= 2):
+
+- **Tier 1** — trivial single-file edit, no cross-module reasoning. The header and attestation are NOT required; a single targeted edit is acceptable. State "Tier 1 — protocol not required" and exit the scaffold.
+- **Tier 2** — multi-file or behavior-changing task with bounded scope. Full protocol applies.
+- **Tier 3** — multi-module / high-risk task. Full protocol applies; fan out one sub-agent per independent module per `rules/hatch3r-fan-out-discipline.md` (P8 B2).
+
+Record the score and the one-line rationale. The tier is the load-bearing input to every block below.
+
+## Step 2: Emit the Per-Turn Pipeline-State Header
+
+At the START of every assistant turn that touches the task, emit the single-line header per `rules/hatch3r-agent-orchestration.md` -> Per-Turn Pipeline-State Header:
+
+```
+[hatch3r-pipeline: phase {1|2|3|4} | last: {agent} → {SUCCESS|PARTIAL|FAILED|BLOCKED|n/a} | next: {agent or "user-confirmation" or "complete"}]
+```
+
+Example first turn: `[hatch3r-pipeline: phase 1 | last: n/a | next: hatch3r-researcher]`
+
+Phase mapping for an ad-hoc task (mirror the four-phase pipeline):
+
+| Phase | Meaning | Driving agent |
+|-------|---------|---------------|
+| 1 | Research / context gathering | `hatch3r-researcher` |
+| 2 | Implementation | `hatch3r-implementer` |
+| 3 | Review loop | `hatch3r-reviewer` ↔ `hatch3r-fixer` |
+| 4 | Final quality + summary | parallel specialists, then iteration summary |
+
+A missing header on a Tier >= 2 turn is a self-detectable drift signal — halt and re-ground rather than continuing blind.
+
+## Step 3: Build the Delegation Plan (No Inline Implementation)
+
+The hard constraint: the orchestrator turn MUST NOT call any code-writing tool (`Edit`, `Write`, `MultiEdit`) directly. Code mutation flows ONLY through the Task tool spawning `hatch3r-implementer` (Phase 2) or `hatch3r-fixer` (Phase 3) per `rules/hatch3r-agent-orchestration.md` -> Mandatory Delegation Directive (No Inline Implementation). There is no Tier-1 carve-out here — Tier 1 exits at Step 1.
+
+Produce a delegation plan before touching any file:
+
+```
+Delegation Plan:
+  Phase 1 — research:   hatch3r-researcher, modes: {…}, depth: {quick|standard|deep}
+  Phase 2 — implement:  hatch3r-implementer × {N}  ({1 per independent module}; correlation_id: {uuid})
+  Phase 3 — review:     hatch3r-reviewer ↔ hatch3r-fixer (max 4 iterations)
+  Phase 4 — quality:    {applicable specialists per the Phase 4 Specialist Trigger Table}
+  sub_agents_spawned:   { count: {N}, rationale: {one-sentence task-decomposition justification} }
+```
+
+Fan-out scales with task decomposition, not token budget (P8 B2 dominates P7): N independent modules → N parallel Phase-2 implementers; serialize only on true dependency edges (shared files, ordered handoffs). Every delegation prompt carries the confidence expression requirement and the `correlation_id` per the orchestration rule.
+
+## Step 4: Emit the End-of-Turn Delegation Attestation Template
+
+Every turn that mutated files at Tier >= 2 emits the attestation block immediately BEFORE the Iteration Summary (beside it, not inside it — the iteration-summary contract stays verbatim), per `rules/hatch3r-agent-orchestration.md` -> End-of-Turn Delegation Attestation:
+
+```
+[hatch3r-delegation-attestation]
+files_mutated_this_turn:
+  - <relative path>: via <hatch3r-implementer | hatch3r-fixer> (proof: <delegation_proof_id>)
+mutating_subagent_invocations: <integer>
+inline_edits_by_orchestrator: none
+```
+
+Why it is forgery-resistant: the per-file `delegation_proof_id` is returned by `hatch3r-implementer` / `hatch3r-fixer` in their structured results (`agents/hatch3r-implementer.md` -> Return Structured Result; `agents/hatch3r-fixer.md` -> Return Structured Result). Quote it verbatim. A turn that skipped delegation has no `delegation_proof_id` to quote — its row is unattributable, which is a self-declared P8 B2 violation: halt and queue re-delegation next turn. `inline_edits_by_orchestrator: none` is the only accepted value in an ad-hoc flow (the `hatch3r-quick-change` Tier-1 carve-out does not apply outside that command).
+
+## Step 5: Bypass-Protection Checklist
+
+Before declaring the turn complete, verify every item — a failed item is the CHANGELOG #73 bypass mode:
+
+- [ ] Task tier scored; protocol applied iff Tier >= 2 (Step 1).
+- [ ] Per-Turn Pipeline-State Header emitted at the start of every task-touching turn (Step 2).
+- [ ] Zero inline `Edit` / `Write` / `MultiEdit` from the orchestrator turn; every code mutation went through `hatch3r-implementer` or `hatch3r-fixer` (Step 3).
+- [ ] End-of-Turn Delegation Attestation emitted before the Iteration Summary, every mutated file attributed to a sub-agent with its `delegation_proof_id` quoted verbatim (Step 4).
+- [ ] `sub_agents_spawned: { count, rationale }` emitted as a first-class field per `rules/hatch3r-fan-out-discipline.md`.
+- [ ] Iteration Summary follows per `rules/hatch3r-iteration-summary.md`.
+
+## Error Handling
+
+- **Unattributable mutation row:** a file was mutated but no `delegation_proof_id` exists for it → the orchestrator inlined the edit. This is a P8 B2 violation. Halt the turn, queue re-delegation of that file through `hatch3r-implementer`/`hatch3r-fixer` next turn, and note the bypass in the attestation block.
+- **Tier misclassification surfaces mid-task:** a Tier-1-scored task that grows to touch multiple modules → re-score to Tier >= 2 immediately, begin emitting the header and attestation from the current turn, and re-delegate any already-inlined edits.
+- **Registered command exists for the intent:** if mid-scaffold you recognize the task matches a registered `/h4tcher-*` command or `commands/hatch3r-*.md`, stop scaffolding and route to that command — it carries these blocks natively and avoids hand-maintained drift.
+
+## Definition of Done
+
+- [ ] Tier scored; protocol applied at Tier >= 2 or skipped at Tier 1.
+- [ ] Header emitted on every task-touching turn.
+- [ ] No inline orchestrator edits; all mutations attributed to a delegated sub-agent.
+- [ ] Attestation block emitted before the Iteration Summary with verbatim `delegation_proof_id`s.
+- [ ] `sub_agents_spawned` count + rationale present.
+
+## References
+
+- `CLAUDE.md` -> "Orchestrator Self-Discipline (Bypass Protection)" — the three-requirement contract this skill scaffolds; accessed 2026-05-31; trust tier: official-docs (in-repo canonical).
+- `rules/hatch3r-agent-orchestration.md` -> Per-Turn Pipeline-State Header, End-of-Turn Delegation Attestation, Mandatory Delegation Directive (No Inline Implementation) — block formats and rules reproduced here; accessed 2026-05-31; trust tier: official-docs (in-repo canonical).
+- `rules/hatch3r-fan-out-discipline.md` — P8 B2 fan-out scaling, `sub_agents_spawned` first-class field, attestation forgery-resistance rationale; accessed 2026-05-31; trust tier: official-docs (in-repo canonical).
+- `skills/hatch3r-incident-response/SKILL.md` — canonical skill structure (Quick Start + Step pattern + Fan-out Discipline section) modeled here; accessed 2026-05-31; trust tier: official-docs (in-repo canonical).
+- hatch3r governance self-audit analysis — source rationale for the missing ad-hoc Tier >= 2 orchestrator scaffold; accessed 2026-05-31; trust tier: official-docs (in-repo canonical).

package/{skills → dist/content/skills}/hatch3r-ai-feature/SKILL.md

@@ -1,5 +1,6 @@
 ---
 id: hatch3r-ai-feature
+name: hatch3r-ai-feature
 type: skill
 description: Eval-driven development workflow for shipping AI features — write eval before prompt, measure, iterate, ship with caching + cost telemetry + model fallback + hallucination SLI
 tags: [implementation, ai]
@@ -11,6 +12,8 @@ cache_friendly: true
 
 ## Quick Start
 
+**Applies when:** the project ships an LLM/AI feature. On a project with no AI feature, skip — do not scaffold AI machinery pre-emptively (per `rules/hatch3r-right-sizing.md`).
+
 Run this skill before shipping any LLM-driven feature. It defines the canonical eval-driven loop (write eval, write prompt, measure, iterate) and the production-readiness gates. Skipping any of the 9 steps = the feature is not done.
 
 This skill is the implementation counterpart to `rules/hatch3r-ai-evals.md` (backend governance) and `rules/hatch3r-ai-ux-patterns.md` (UI governance). The rules define the bar; this skill defines the route to clearing the bar.
@@ -21,12 +24,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.
 
 ## Step 1: Define the task and success criteria
 

package/{skills → dist/content/skills}/hatch3r-api-spec/SKILL.md

@@ -1,7 +1,8 @@
 ---
 id: hatch3r-api-spec
+name: hatch3r-api-spec
 type: skill
-description: Generate and validate OpenAPI specifications from codebase. Covers endpoint design, schema validation, and documentation generation.
+description: Generates and validates OpenAPI specifications from codebase. Covers endpoint design, schema validation, and documentation generation.
 tags: [planning]
 quality_charter: agents/shared/quality-charter.md
 efficiency_patterns: agents/shared/efficiency-patterns.md
@@ -10,6 +11,16 @@ cache_friendly: true
 
 # API Specification Workflow
 
+## Relationship to `commands/hatch3r-api-spec.md` (Decision 13 handoff)
+
+This skill shares the `id: hatch3r-api-spec` with the orchestrator command `commands/hatch3r-api-spec.md`. The two are NOT duplicates — they split the OpenAPI workflow by execution model per CONSTITUTION §6 Decision 13:
+
+- **`commands/hatch3r-api-spec.md` (orchestrator entry):** the canonical multi-agent pipeline — researcher scans routes, docs-writer assembles the spec, reviewer validates (`agentPipeline: [hatch3r-researcher, hatch3r-docs-writer, hatch3r-reviewer]`). Use the command when the workflow warrants sub-agent fan-out (Tier 2/3 framework detection, drift detection, breaking-change review).
+- **This skill (inline procedure):** the single-pass reference body the command's docs-writer and reviewer stages follow when assembling and validating the spec. Use the skill directly for Tier 1 single-endpoint spec edits where no fan-out is needed, OR as the step-by-step procedure cited inside the command's Step 5 (OpenAPI Assembly) and Step 6 (Validation).
+- **Unique to this skill:** Step 6 (`oasdiff` breaking-change CI gate wiring) is the inline-procedure detail the command references rather than restates.
+
+The merge-candidate review (F16.3-H3) flagged the shared id; this handoff documentation is the explicit workflow-split declaration that disambiguates the pair. A future collapse into a single command appendix requires coordinated edits to the command body, the bundled content inventory (skills count), and the Decision-13 anti-duplicate-id gate in `src/cli/commands/validate.ts`.
+
 ## Quick Start
 
 ```
@@ -69,7 +80,7 @@ Before any work, scan the invocation for unresolved questions in scope, intent,
 
 ## Step 6: Wire `oasdiff` Breaking-Change CI Gate
 
-Breaking changes on stable endpoints must trip CI before merge. This step enforces the CONSTITUTION §2 P5 lean-thresholds row "API breaking-change events on stable endpoints = 0 per release" (governance/CONSTITUTION.md:80, verified by `oasdiff / buf breaking / graphql-inspector CI gate`).
+Breaking changes on stable endpoints must trip CI before merge. This step enforces the canonical lean-threshold floor "API breaking-change events on stable endpoints = 0 per release" (see `agents/shared/principles.md`, verified by `oasdiff / buf breaking / graphql-inspector CI gate`).
 
 ### 6.1 Install `oasdiff`
 
@@ -133,6 +144,15 @@ When a breaking change is deliberate (versioned endpoint cut, deprecated field r
 
 The gate stays green only because the change is recorded — not because the breaking signal was silenced.
 
+## Fan-out Discipline (P8 B2)
+
+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`). Tier boundaries for THIS skill:
+- Tier 1 (single service / one spec file): inline.
+- Tier 2 (multiple services or spec + client-codegen + CI-gate concerns): spawn parallel sub-agents per concern via the Task tool.
+- Tier 3 (cross-service contract suite): one fresh sub-agent per service spec; orchestrator integrates only.
+
+Emit `sub_agents_spawned: { count, rationale }` in your output.
+
 ## Error Handling
 
 - **Route definitions use dynamic or meta-programmed patterns**: If endpoints are generated at runtime or via decorators that resist static analysis, document the gap and manually enumerate the missing endpoints.
@@ -147,3 +167,8 @@ The gate stays green only because the change is recorded — not because the bre
 - [ ] Example requests/responses included
 - [ ] No breaking changes to existing API consumers
 - [ ] `oasdiff breaking` CI gate is wired and fails on any `ERR`-level breaking change on stable endpoints (CONSTITUTION §2 P5: 0 per release)
+
+## References
+
+- [OpenAPI Specification 3.1.0](https://spec.openapis.org/oas/v3.1.0) — accessed 2026-05-31, official-docs (OpenAPI Initiative). Source for the 3.1 `info`/`components/schemas`/`$ref`/`security` structures and the JSON-Schema-aligned validation keywords used in Steps 2–3.
+- [oasdiff breaking-change detection](https://github.com/Tufin/oasdiff) — accessed 2026-05-31, independent-analysis (Tufin). Source for the `oasdiff breaking --fail-on ERR` CI-gate behavior, `--format githubactions` annotations, and ignore-rules file in Step 6.

package/{skills → dist/content/skills}/hatch3r-architecture-review/SKILL.md

@@ -1,6 +1,8 @@
 ---
 id: hatch3r-architecture-review
-description: Evaluate architectural decisions and produce ADRs following the project template. Use when making architectural decisions, evaluating trade-offs, or creating ADRs.
+name: hatch3r-architecture-review
+type: skill
+description: Evaluates architectural decisions and produce ADRs following the project template. Use when making architectural decisions, evaluating trade-offs, or creating ADRs.
 tags: [review]
 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.
 
 ## Step 1: Read Existing ADRs and Template
 
@@ -72,7 +69,7 @@ Reference:
 ## Step 4: External Research
 
 - For external library docs and current best practices, follow the project's tooling hierarchy.
-- **Issue/PR search** (check `platform` in `.agents/hatch.json`): Search for related issues, prior discussions, or similar decisions in the repo:
+- **Issue/PR search** (check `platform` in `.hatch3r/hatch.json`): Search for related issues, prior discussions, or similar decisions in the repo:
   - **GitHub:** Use **GitHub MCP** or `gh issue list --search "..."` / `gh pr list --search "..."`
   - **Azure DevOps:** `az boards query --wiql "SELECT [System.Id] FROM WorkItems WHERE [System.Title] CONTAINS '...'"` or `az repos pr list`
   - **GitLab:** `glab issue list --search "..."` / `glab mr list --search "..."`