hatch3r 1.7.1 → 1.8.0

package/skills/hatch3r-pr-creation/SKILL.md

@@ -16,12 +16,26 @@ cache_friendly: true
 
 ```
 Task Progress:
+- [ ] Step 0: Detect ambiguity (P8 B1)
 - [ ] Step 1: Verify branch naming
 - [ ] Step 2: Self-review against checklist
 - [ ] Step 3: Fill PR/MR template
 - [ ] Step 4: Create the PR/MR
 ```
 
+## Step 0 — Detect Ambiguity (P8 B1)
+
+Before any work, scan the invocation for unresolved questions in scope, intent, acceptance criteria, target environment, 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: target base branch (`board.defaultBranch` vs feature branch), draft vs ready-for-review, reviewers explicitly named, rollout plan (feature flag vs direct), and whether the diff includes irreversible operations (force-push, data migration).
+
+## 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.
+
 ## Step 1: Branch Naming
 
 Branches must follow `{type}/{short-description}`:

package/skills/hatch3r-qa-validation/SKILL.md

@@ -12,6 +12,7 @@ cache_friendly: true
 
 ```
 Task Progress:
+- [ ] Step 0: Detect ambiguity (P8 B1)
 - [ ] Step 1: Read the issue and relevant specs
 - [ ] Step 2: Produce a validation plan
 - [ ] Step 3: Execute all test cases
@@ -19,6 +20,19 @@ Task Progress:
 - [ ] Step 5: File follow-up issues
 ```
 
+## Step 0 — Detect Ambiguity (P8 B1)
+
+Before any work, scan the invocation for unresolved questions in scope, intent, acceptance criteria, target environment, 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. This upgrades validation from exception-driven to default-driven. Triggers for THIS skill: validation scope (single feature vs release), target environment (staging vs prod), pass/fail thresholds, flaky-test policy (retry vs quarantine), and ship/hold authority (auto-block vs surface for review).
+
+## 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.
+
 ## Step 1: Read Inputs
 
 - Parse the issue body: validation scope, test matrix, environments, preconditions, pass/fail criteria, evidence requirements.
@@ -61,6 +75,10 @@ For non-UI test cases (API, data integrity, background jobs), use appropriate no
 
 Do NOT fix bugs during validation. Document and file issues.
 
+### 3c. UI/UX Verification Gate
+
+For any feature that ships UI, the UI/UX verification gate is **`hatch3r-ui-ux-verify`** (`skills/hatch3r-ui-ux-verify/SKILL.md`). All 9 gates in that skill must pass before declaring the feature done. QA validation alone (browser tests, screenshot evidence) does not constitute UI/UX done. Run `hatch3r-ui-ux-verify` before this report's SHIP recommendation and include its verdict in the report.
+
 ## Step 4: Validation Report
 
 Produce a structured report with:

package/skills/hatch3r-recipe/SKILL.md

@@ -12,6 +12,7 @@ cache_friendly: true
 
 ```
 Task Progress:
+- [ ] Step 0: Detect ambiguity (P8 B1)
 - [ ] Step 1: Identify the workflow to capture as a recipe
 - [ ] Step 2: Design the step sequence and dependency graph
 - [ ] Step 3: Write the recipe YAML
@@ -19,6 +20,19 @@ Task Progress:
 - [ ] Step 5: Validate with a real execution
 ```
 
+## Step 0 — Detect Ambiguity (P8 B1)
+
+Before any work, scan the invocation for unresolved questions in scope, intent, acceptance criteria, target environment, 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: recipe scope (single project vs shared), required variables and defaults, checkpoint policy (pause vs flow), error handling (resume vs restart), and target file location (`.hatch3r/recipes/` project vs global).
+
+## 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.
+
 ## Step 1: Identify Workflow
 
 Determine the repeatable workflow pattern:

package/skills/hatch3r-refactor/SKILL.md

@@ -14,6 +14,7 @@ cache_friendly: true
 
 ```
 Task Progress:
+- [ ] Step 0: Detect ambiguity (P8 B1)
 - [ ] Step 1: Read the issue, specs, and existing tests
 - [ ] Step 2: Produce a refactor plan
 - [ ] Step 3: Implement with behavioral preservation
@@ -21,6 +22,19 @@ Task Progress:
 - [ ] Step 5: Open PR
 ```
 
+## Step 0 — Detect Ambiguity (P8 B1)
+
+Before any work, scan the invocation for unresolved questions in scope, intent, acceptance criteria, target environment, 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: refactor scope (one module vs cross-cutting), behavioral invariants to preserve, public API surface (preserved vs changed), test rewrite policy (preserve vs replace), and acceptable performance delta.
+
+## 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.
+
 ## Step 1: Read Inputs
 
 - Parse the issue body: motivation, proposed change, affected files, safety plan, risk analysis, acceptance criteria.

package/skills/hatch3r-release/SKILL.md

@@ -14,6 +14,7 @@ cache_friendly: true
 
 ```
 Task Progress:
+- [ ] Step 0: Detect ambiguity (P8 B1)
 - [ ] Step 1: Determine version bump (major/minor/patch) based on changes
 - [ ] Step 2: Generate changelog from merged PRs and commit history
 - [ ] Step 3: Update version in package.json and any other version references
@@ -23,6 +24,19 @@ Task Progress:
 - [ ] Step 7: Monitor post-deploy for errors/regressions
 ```
 
+## Step 0 — Detect Ambiguity (P8 B1)
+
+Before any work, scan the invocation for unresolved questions in scope, intent, acceptance criteria, target environment, 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: bump level (major vs minor vs patch), deploy authority (cut-only vs deploy-and-monitor), staging gate (required vs skipped), rollback policy (auto vs manual), and irreversible tag/publish operations (npm publish, GitHub release).
+
+## 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.
+
 ## Step 1: Determine Version Bump
 
 - Review changes since last release: merged PRs/MRs, commit history.

package/skills/hatch3r-reliability-verify/SKILL.md

@@ -0,0 +1,146 @@
+---
+id: hatch3r-reliability-verify
+type: skill
+description: Reliability verification gate before declaring an agent-produced service done — SLO defined, kill switch, timeouts, retries, probes, runbook, staged rollout
+tags: [review, devops]
+quality_charter: agents/shared/quality-charter.md
+efficiency_patterns: agents/shared/efficiency-patterns.md
+cache_friendly: true
+---
+# Reliability Verification Gate
+
+## Quick Start
+
+This skill defines what "done" means for any feature shipping a service to production. Run before declaring a feature complete. The 9 gates below are machine-checkable on the manifest, the source, and the alert configuration. Skipping any gate = the feature is not done. Functional tests passing alone do not satisfy this bar — a service that lacks an SLO, a kill switch, or a runbook will fail in production before its first alert reaches the on-call.
+
+Inputs the skill expects:
+
+- A service repository with `src/` and `k8s/` (or equivalent manifest path).
+- A `docs/runbooks/` directory.
+- Either a `slo/` directory or inline SLO definitions in the alert manifest (Prometheus rules, Datadog monitors, OpenSLO YAML).
+
+Outputs the skill produces: a 9-line verdict block written to the PR conversation, plus a JSON artifact at `.audit-workspace/reliability-verify-<sha>.json` for downstream consumption by `hatch3r-release` (or any downstream release-prep skill).
+
+## Step 0 — Detect Ambiguity (P8 B1)
+
+Before any work, scan the invocation for unresolved questions in scope, intent, acceptance criteria, target environment, 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: service scope, SLO target values and window, rollout strategy (canary stages, hold durations), kill-switch authority and provider, and blast-radius rollback drill cadence.
+
+## 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.
+
+## Gate 1: SLO defined
+
+- The service has at least one Service Level Objective with target percentile, evaluation window, and a wired burn-rate alert.
+- Format: `availability >= 99.9% over rolling 28d` or `p95 latency <= 300ms over rolling 28d`.
+- Burn-rate alert pattern: multi-window multi-burn-rate (Google SRE) — fast burn (14.4x over 5m AND 6x over 1h) pages immediately; slow burn (3x over 6h AND 1x over 3d) opens a ticket.
+- Output: SLO manifest path committed to the repo (e.g. `slo/<service>.yaml` or a Sloth / OpenSLO file).
+- Check: grep for `slo:` or `objectives:` in the service manifest; reject if absent.
+- Cross-reference: `rules/hatch3r-observability-metrics.md`.
+
+## Gate 2: Kill switch present
+
+- Every risky feature is gated by an OpenFeature Ops flag with a documented flip procedure.
+- The flag name appears in `docs/runbooks/<service>.md` next to the alert that would trigger its use.
+- Default-on with OFF override; provider connectivity loss does not silently disable the kill switch.
+- Check: open the runbook, locate the flag name, confirm a flip-procedure step exists with the exact CLI or UI action.
+- Cross-reference: `rules/hatch3r-operability.md` §Feature Flags.
+
+## Gate 3: Timeouts on every outbound call
+
+- Every DB, cache, queue, external HTTP, and external RPC call has an explicit timeout.
+- Deadline propagation verified: parent timeout reaches child via `context.WithDeadline` (Go), chained `AbortSignal` (Web/Node), `Deadline` metadata (gRPC), or `TimeLimiter` (JVM).
+- Default budgets: service-call 5s, DB 2s, cache 200ms, health-probe 1s.
+- Check: grep the codebase for outbound-call sites and confirm each has a timeout argument or wrapper.
+- Cross-reference: `rules/hatch3r-resilience-patterns.md` §Timeouts.
+
+## Gate 4: Retries with decorrelated jitter
+
+- Outbound calls wrap in a retry library — `opossum` (Node), `resilience4j` (JVM), `Polly` (.NET), `gobreaker` + `cenkalti/backoff` (Go), or `pybreaker` + `tenacity` (Python).
+- Retry algorithm is decorrelated jitter: `sleep = min(cap, random_between(base, prev_sleep * 3))` with base 100ms, cap 30s, max 3 retries.
+- `Idempotency-Key` header present on retried non-idempotent operations (POST, PATCH).
+- Retry budget enforced: retry traffic capped at 10% of base traffic.
+- Cross-reference: `rules/hatch3r-resilience-patterns.md` §Retry.
+
+## Gate 5: Probes wired
+
+- Kubernetes manifest defines `livenessProbe`, `readinessProbe`, and (for slow-starting services) `startupProbe`.
+- Liveness is shallow (no downstream check); readiness is deep (downstream pings).
+- Distinct endpoints — `/health/live`, `/health/ready`, `/health/startup` — not a single shared `/health`.
+- Probe timeouts under 1s for live, under 2s for ready; periods 10s / 5s / 5s.
+- Check: parse the k8s manifest YAML and verify `livenessProbe.httpGet.path != readinessProbe.httpGet.path` (shared endpoints fail this gate).
+- Cross-reference: `rules/hatch3r-operability.md` §Probes.
+
+## Gate 6: Graceful shutdown
+
+- SIGTERM handler closes the listener, marks `/health/ready` to 503, then drains in-flight requests.
+- `preStop` hook delays 1–3s before SIGTERM to handle the endpoint-propagation race.
+- `terminationGracePeriodSeconds >= 45`.
+- Queue consumers commit offsets before disconnect.
+- Cross-reference: `rules/hatch3r-operability.md` §Graceful Shutdown.
+
+## Gate 7: Runbook URL on every alert
+
+- Every Prometheus / Datadog / Grafana alert has a `runbook_url` annotation linking to `docs/runbooks/<alert-name>.md`.
+- Runbook contains the 5 required sections: Symptoms, Triage, Mitigation, Root cause, Follow-ups.
+- CI check on the alert manifest fails any alert without `runbook_url` or with a 404 link.
+- Cross-reference: `rules/hatch3r-operability.md` §Runbook URL.
+
+## Gate 8: Staged rollout configured
+
+- Deployment uses Argo Rollouts, Flagger, or an equivalent controller with canary or blue-green configured.
+- Stage cadence: 1% → 10% → 50% → 100% with minimum holds 30 min / 1 h / 2 h.
+- Auto-rollback wired to the service SLO burn-rate alert (fast-burn triggers immediate rollback).
+- Canary analysis gates error-rate ratio, p95/p99 latency, and business KPIs against a live baseline.
+- Check: locate the `Rollout` or `Canary` resource in the deploy directory; reject if missing or if `steps:` skips the 1% stage.
+- Cross-reference: `rules/hatch3r-progressive-delivery.md`.
+
+## Gate 9: Blast-radius documented
+
+- PR description includes the blast-radius block: services affected, regions, traffic %, rollback time target (<5 min), exact rollback command.
+- Rollback command verified by quarterly drill — drill date recorded in the runbook.
+- Database migrations follow expand-contract; no destructive migration ships in the same deploy as the consuming code.
+- Check: parse the PR body for the `## Blast radius` section; reject if absent or if any required field is empty.
+- Cross-reference: `rules/hatch3r-progressive-delivery.md` §Blast-Radius Reasoning.
+
+## Verdict
+
+All 9 gates pass = the service is "done" enough to ship to production. Anything less = not done; the missing gates are findings against this skill.
+
+The orchestrator running this skill emits a single-line verdict per gate (`GATE_N: PASS|FAIL <evidence-path>`) and aggregates them. One FAIL on a required gate blocks the merge regardless of functional-test status.
+
+Evidence path format: `path/to/file.yaml:LN` or `commit-sha`. The verdict is auditable — a downstream review or release-gate skill can replay the same checks against the same evidence paths and reproduce the verdict bit-for-bit.
+
+Gates run independently — a FAIL on Gate 3 does not short-circuit the remaining gates; the run produces the full 9-line verdict so the developer fixes everything in one pass rather than serializing on rerun cycles.
+
+## When this skill runs
+
+- After `hatch3r-implementer` finishes service code and before `hatch3r-qa-validation` runs.
+- On every PR that touches `src/services/`, `src/handlers/`, `src/clients/`, `k8s/`, `manifests/`, or the alert / SLO configuration.
+- Gate 9 (drill verification) requires manual confirmation from the on-call rota at release-cut time, not per PR.
+- New-service bootstrap: run the full 9 gates before the first production deploy; failing any one is a blocker, not a follow-up.
+
+## Cross-References
+
+- `rules/hatch3r-resilience-patterns.md` — circuit breakers, retries with decorrelated jitter, idempotency keys.
+- `rules/hatch3r-operability.md` — probes, graceful shutdown, kill switches, runbooks.
+- `rules/hatch3r-progressive-delivery.md` — canary, blue-green, auto-rollback on SLO burn.
+- `rules/hatch3r-observability-metrics.md` — SLOs, RED metrics, burn-rate alerts.
+
+## References
+
+- Google SRE workbook — `sre.google/workbook`
+- Kubernetes probes — `kubernetes.io/docs/tasks/configure-pod-container/configure-liveness-readiness-startup-probes`
+- Argo Rollouts — `argoproj.github.io/argo-rollouts`
+- Flagger — `flagger.app`
+- OpenFeature — `openfeature.dev`
+- opossum (Node) — `github.com/nodeshift/opossum`
+- resilience4j (JVM) — `resilience4j.readme.io`
+- Polly (.NET) — `pollydocs.org`
+- Sloth (Prometheus SLO generator) — `sloth.dev`
+- OpenSLO specification — `openslo.com`

package/skills/hatch3r-rule-customize/SKILL.md

@@ -5,9 +5,19 @@ tags: [customize]
 quality_charter: agents/shared/quality-charter.md
 efficiency_patterns: agents/shared/efficiency-patterns.md
 cache_friendly: true
+redirect_to: hatch3r-customize
 ---
 # Rule Customization
 
 > **This skill has been consolidated.** Use the `hatch3r-customize` skill with `type: rule`.
 
 For rule-specific reference (scope overrides, YAML schema), see the `hatch3r-rule-customize` command.
+
+## Rejected Merge Alternative (D16.3 add-vs-remove bias)
+
+Per `governance/audit/domains/D16-compound-system.md` SA 16.3, the default recommendation on functional overlap is MERGE rather than removal. Full deletion of this redirect file was rejected for two reasons:
+
+1. **Preserves UX entry points.** Users typed `/h4tcher-rule-customize` or referenced the id `hatch3r-rule-customize` (per `rules/hatch3r-browser-verification.md:57` and sibling cross-references) before consolidation. Deleting the id breaks those entry points without a redirect target.
+2. **Signals umbrella canonicality.** The `redirect_to: hatch3r-customize` frontmatter field marks `hatch3r-customize` as the single source of truth — tooling, audit scans, and adapters can resolve any redirect to the canonical without re-reading body prose.
+
+The 13-LOC redirect cost is paid once per type; the umbrella body lives in `skills/hatch3r-customize/SKILL.md`.

package/skills/hatch3r-skill-customize/SKILL.md

@@ -5,9 +5,19 @@ tags: [customize]
 quality_charter: agents/shared/quality-charter.md
 efficiency_patterns: agents/shared/efficiency-patterns.md
 cache_friendly: true
+redirect_to: hatch3r-customize
 ---
 # Skill Customization
 
 > **This skill has been consolidated.** Use the `hatch3r-customize` skill with `type: skill`.
 
 For skill-specific reference (YAML schema, examples), see the `hatch3r-skill-customize` command.
+
+## Rejected Merge Alternative (D16.3 add-vs-remove bias)
+
+Per `governance/audit/domains/D16-compound-system.md` SA 16.3, the default recommendation on functional overlap is MERGE rather than removal. Full deletion of this redirect file was rejected for two reasons:
+
+1. **Preserves UX entry points.** Users typed `/h4tcher-skill-customize` or referenced the id `hatch3r-skill-customize` (per `rules/hatch3r-browser-verification.md:58` and sibling cross-references) before consolidation. Deleting the id breaks those entry points without a redirect target.
+2. **Signals umbrella canonicality.** The `redirect_to: hatch3r-customize` frontmatter field marks `hatch3r-customize` as the single source of truth — tooling, audit scans, and adapters can resolve any redirect to the canonical without re-reading body prose.
+
+The 13-LOC redirect cost is paid once per type; the umbrella body lives in `skills/hatch3r-customize/SKILL.md`.

package/skills/hatch3r-ui-ux-verify/SKILL.md

@@ -0,0 +1,138 @@
+---
+id: hatch3r-ui-ux-verify
+type: skill
+description: UI/UX verification gate before declaring a feature done — axe-core, scripted keyboard trace, accessibility-tree snapshot, four-state coverage, visual-regression baseline, one human screen-reader pass per release
+tags: [ui, ux, a11y]
+quality_charter: agents/shared/quality-charter.md
+efficiency_patterns: agents/shared/efficiency-patterns.md
+cache_friendly: true
+---
+# UI/UX Verification Gate
+
+## Quick Start
+
+This skill defines what "done" means for any feature shipping UI. Run before declaring a feature complete. The 9 gates below mix automated checks (machine-checkable on every PR) with one manual gate (one human screen-reader pass per release). Skipping any gate = the feature is not done. Browser tests and screenshots from `hatch3r-qa-validation` alone do not satisfy this bar.
+
+## Step 0 — Detect Ambiguity (P8 B1)
+
+Before any work, scan the invocation for unresolved questions in scope, intent, acceptance criteria, target environment, 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: routes in scope (single vs all interactive), WCAG target (2.1 AA vs 2.2 AA), visual-regression baseline policy (regenerate vs keep), AI-UX gate applicability, and whether Gate 9 (manual SR pass) is required this run.
+
+## 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.
+
+## Gate 1: Automated a11y scan (axe-core via Playwright)
+
+- Command: `npx playwright test --grep @a11y` with `@axe-core/playwright` integration on every interactive route.
+- Pass criteria: 0 serious / 0 critical violations.
+- WCAG 2.2 AA target with explicit checks for the new success criteria:
+  - **SC 2.5.8 Target Size:** assert minimum 24x24 CSS px on every focusable element.
+  - **SC 2.4.11 Focus Not Obscured:** assert the focus ring is fully visible — not hidden behind sticky headers, banners, or chatbots.
+  - **SC 2.5.7 Dragging Movements:** assert a non-drag alternative exists for any drag operation.
+- Output: a11y report committed to PR. Merge gate: 0 violations.
+- Setup: `import AxeBuilder from '@axe-core/playwright'`; call `new AxeBuilder({ page }).analyze()` inside each route test and assert `results.violations.length === 0` after filtering for `impact in ['serious', 'critical']`.
+
+## Gate 2: Scripted keyboard trace
+
+- Playwright script Tabs / Shift+Tabs / Enter / Space / Escape / Arrows through every interactive element on every route.
+- Per-element assertions:
+  - Focus is visible (computed outline width > 0 or detectable focus ring).
+  - Focused element is within the viewport (scroll into view if not).
+  - No keyboard trap — Tab on the last element exits to the next region.
+- Pass criteria: 100% interactive elements reached + 0 traps + 0 focus-visibility failures.
+- Implementation: enumerate focusable elements via `page.locator('a, button, input, select, textarea, [tabindex]:not([tabindex="-1"])')`; iterate Tab presses up to `count + 5` and record the activeElement chain. Diff against the enumeration; any unreached element fails the gate.
+
+## Gate 3: Accessibility-tree snapshot
+
+- Playwright captures the accessibility tree on each route via `page.accessibility.snapshot()`.
+- Per-route assertions:
+  - Exactly one `<h1>`.
+  - Landmark coverage: `banner`, `main`, `nav`, `contentinfo` present.
+  - Every form input has an accessible name.
+  - Every image has an `alt` attribute or `role="presentation"`.
+- Snapshots committed to the repo. Diff on every PR surfaces visual a11y regression.
+
+## Gate 4: Four-state coverage check
+
+- For every async surface, assert snapshots exist for all four states:
+  - **loading** (skeleton)
+  - **empty** (with CTA)
+  - **error** (cause + retry)
+  - **partial** (banner + degraded data)
+- Missing snapshot = blocker.
+- Convention: `src/__tests__/states/<feature>.<state>.spec.ts`.
+- Discovery: a pre-test script greps for async data hooks (`useQuery`, `useSWR`, `fetch`, `axios`) and emits the list of features that must have all four state files. Missing files fail the gate before any test runs.
+
+## Gate 5: Visual regression baseline
+
+- `playwright.toHaveScreenshot()` for component-library projects; Chromatic or Percy for Storybook-heavy projects.
+- Baselines committed to git or stored in the registry. Never auto-regenerated in CI on the same commit that introduces a visual change.
+- Pass criteria: 0 unintentional drift. Intentional drift requires a reviewer to update the baseline.
+- Pixel threshold: `maxDiffPixels: 0` for layout-critical screens (header, nav, primary CTA); `maxDiffPixelRatio: 0.001` for content-heavy screens. Tighter thresholds catch silent regressions; looser thresholds tolerate font-rendering noise on content text.
+
+## Gate 6: Microcopy lint
+
+- Forbid filler tokens in user-facing strings: "oops", "whoops", "something went wrong", "uh oh".
+- Require a corrective verb on error strings — scan the messages files for error messages, fail when no imperative verb appears.
+- Require the `autocomplete` attribute on every input matching `email`, `password`, `name`, or `address`. axe-core covers part of this; add a custom rule for the rest.
+
+## Gate 7: Core Web Vitals (2026 thresholds)
+
+- Lighthouse CI or the `web-vitals` library in a synthetic environment.
+- p75 thresholds, measured on mobile with slow-4G + 4x CPU throttle:
+  - **LCP** <= 2.5s
+  - **INP** <= 200ms
+  - **CLS** <= 0.1
+- Failure on any metric = merge blocker.
+- Field data follow-up: when production has RUM (Real User Monitoring) wired via `web-vitals` posting to an analytics endpoint, compare p75 field values to synthetic budgets weekly. A 25% gap between synthetic and field is a finding — re-tune the synthetic environment.
+
+## Gate 8: AI-UX checks (when applicable)
+
+Applies only when the feature ships LLM-driven UI:
+
+- Streaming hooks in use — grep for `useChat`, `useCompletion`, `streamUI`, or the framework equivalent.
+- Tool-call cards visible by default — assert at least one rendered card per tool invocation in fixtures.
+- Human-approval gates present for side-effectful tools — assert an approval card before `write`, `send`, or `post` tool calls.
+- Cancel/abort controls present and wired to an `AbortController`.
+
+Cross-reference: `rules/hatch3r-ai-ux-patterns.md` (Slice 5).
+
+## Gate 9: Manual screen-reader pass (per release, not per PR)
+
+- One human pass with VoiceOver (macOS or iOS) or NVDA (Windows) per release on the key user flow.
+- Document the trace in the release notes: route walked, issues found, fixes applied.
+- This gate cannot be skipped or automated away.
+- Trace template: open route, enable screen reader, navigate by heading / by landmark / by form control. Record three things — what was announced, what was missing, what was wrong. Fix or file before release.
+
+## Verdict
+
+All 9 gates pass = the feature is "done". Anything less = not done.
+
+The orchestrator running this skill emits a single-line verdict per gate (`GATE_N: PASS|FAIL <evidence-path>`) and aggregates them. One FAIL on a required gate blocks the merge regardless of QA validation status.
+
+## When this skill runs
+
+- After `hatch3r-implementer` finishes feature code and before `hatch3r-qa-validation` runs.
+- On every PR that touches `src/components/`, `src/pages/`, `src/routes/`, or any file matched by the design-system glob.
+- Gate 9 (manual screen-reader pass) skipped on PR runs and required at release-cut time only.
+
+## Cross-References
+
+- `rules/hatch3r-accessibility-standards.md`
+- `rules/hatch3r-ux-states-and-flows.md`
+- `rules/hatch3r-ai-ux-patterns.md`
+- `rules/hatch3r-design-system-detection.md`
+- `rules/hatch3r-performance-budgets.md`
+
+## References
+
+- Playwright accessibility testing — `playwright.dev/docs/accessibility-testing`
+- Deque axe-core — `github.com/dequelabs/axe-core`
+- Google Core Web Vitals 2026 thresholds — `web.dev/articles/vitals`
+- Vercel AI SDK UI documentation — `sdk.vercel.ai/docs/ai-sdk-ui`
+- WCAG 2.2 — `www.w3.org/TR/WCAG22/`

package/skills/hatch3r-visual-refactor/SKILL.md

@@ -14,6 +14,7 @@ cache_friendly: true
 
 ```
 Task Progress:
+- [ ] Step 0: Detect ambiguity (P8 B1)
 - [ ] Step 1: Read the issue, mockups, and design system
 - [ ] Step 2: Produce a visual change plan
 - [ ] Step 3: Implement matching the mockup
@@ -21,11 +22,24 @@ Task Progress:
 - [ ] Step 5: Open PR with before/after screenshots
 ```
 
+## Step 0 — Detect Ambiguity (P8 B1)
+
+Before any work, scan the invocation for unresolved questions in scope, intent, acceptance criteria, target environment, 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: mockup source (provided vs derived from design system), reuse vs extend vs create verdict from `hatch3r-design-system-detect`, responsive breakpoint set, animation budget, and snapshot-regeneration authority.
+
+## 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.
+
 ## Step 1: Read Inputs
 
 - Parse the issue body: proposed changes, before/after mockups, affected surfaces, accessibility checklist, responsiveness requirements.
 - Read project quality documentation (accessibility, animation budgets).
-- Review the existing design system tokens and component hierarchy.
+- Invoke `hatch3r-design-system-detect` to produce the Design System Inventory (`skills/hatch3r-design-system-detect/SKILL.md`). Use the inventory to choose between reuse / extend / create paths. Skipping detection is a regression — visual refactors that invent new tokens or duplicate primitives are rejected at review.
 - For external library docs and current best practices, follow the project's tooling hierarchy.
 
 ## Step 2: Visual Change Plan