hatch3r 1.7.0 → 1.7.5

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

@@ -0,0 +1,133 @@
+---
+id: hatch3r-observability-verify
+type: skill
+description: Verification gate before declaring an agent-produced service done — OTel span coverage on request path, structured-log + trace-id correlation, SLO definition, error-tracking integration, GenAI semconv on AI features
+tags: [review, performance, devops]
+quality_charter: agents/shared/quality-charter.md
+---
+# Observability Verification Gate
+
+## Quick Start
+
+This skill defines what "done" means for any feature shipping a service. Run before declaring a feature complete. The 9 gates below mix automated checks (machine-checkable on every PR) with one release-cadence gate (SLO + burn-rate alert review per release). Skipping any gate = the feature is not done. Reviewer approval and passing unit tests 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: service scope (which routes), trace vendor (OTel collector vs vendor SDK), sample rates (head vs tail), SLO target values, and Gate 7 applicability (LLM-in-path vs pure service).
+
+## 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: OTel span on request path
+
+- Every HTTP server entry point, every RPC handler, and every queue consumer emits a root span. Every outbound DB / cache / queue / external HTTP call is wrapped in a child span.
+- Discovery: enumerate route declarations via `grep -E 'app\.(get|post|put|patch|delete)|router\.|@Get|@Post|fastify\.route' src/` and outbound calls via `grep -E 'fetch\(|axios|prisma|redis|pg\.query'`. Each match must have a tracer call on the same path: `grep -E 'tracer|startSpan|@WithSpan'` against the file.
+- Auto-instrumentation packages (`@opentelemetry/auto-instrumentations-node`, `opentelemetry-instrumentation` Python) satisfy the spec when loaded before app imports — verify via process arg `--require @opentelemetry/auto-instrumentations-node/register` or equivalent loader.
+- Pass criteria: >=1 root span per route + >=1 child span per outbound call. 0 routes without instrumentation. Coverage threshold: >=95% of declared routes emit at least one root span under fixture traffic.
+- HTTP semconv attributes on every server span: `http.request.method`, `http.route`, `http.response.status_code`, `url.scheme`. DB spans carry `db.system` + `db.operation.name`. Span status `ERROR` set on every 5xx + every caught exception. Sources: `rules/hatch3r-observability-tracing.md`, OpenTelemetry semconv v1.29.
+
+## Gate 2: Structured logs with trace_id injection
+
+- Every log line emitted from request scope is JSON (pino / winston / zap / loguru / `slog`). No `console.log` for application logs in production code paths.
+- Every request-scoped logger carries `trace_id` and `span_id` from the active OTel context. Verify via Playwright or vitest fixture that emits a request and asserts both fields appear on the captured log line.
+- Hook the logger to the active span: `@opentelemetry/instrumentation-pino` for Node, `LoggingInstrumentor` for Python — auto-injects trace_id + span_id. Manual injection acceptable when auto-instrumentation is unavailable for the logger.
+- W3C Trace Context (`traceparent` + `tracestate` headers) propagated on every outbound HTTP call. Test: send a request, inspect the outbound call recorded by `nock` / `msw` / a recording proxy, assert the header is present and parses as a valid traceparent string `00-{32hex}-{16hex}-{2hex}`.
+- Pass criteria: 0 unstructured app-log statements + 100% of request-scoped log lines carry `trace_id` + traceparent propagated on every outbound call. Sources: `rules/hatch3r-observability-logging.md`, W3C Trace Context Level 1 (W3C Recommendation 2020-02).
+
+## Gate 3: Severity and message standards
+
+- OTel `SeverityNumber` mapping documented in the logger initialization. Replace ad-hoc level strings with the OTel-aligned set: `TRACE / DEBUG / INFO / WARN / ERROR / FATAL` mapped to SeverityNumber 1 / 5 / 9 / 13 / 17 / 21.
+- Log messages follow the verb-first structure: action + object + outcome. Example: `"created order" {order_id, amount}`. Never embed dynamic values into the message string — pass them as fields.
+- PII / secret redaction enabled via a centralized redactor — pino redact paths, winston format redactor, or a structured-log middleware. Audit: grep for password / authorization / token / email fields in log payloads; 0 unredacted hits.
+- Required envelope fields on every log entry: `service.name`, `service.version`, `deployment.environment`, `trace_id`, `span_id`, `severity_number`, `timestamp` (RFC 3339 with millisecond precision).
+- No `console.log` for app logs. Enforced via eslint rule `no-console` with `error` severity in production code paths; test code is exempt via override. Sources: `rules/hatch3r-observability-logging.md`, OpenTelemetry Logs Data Model.
+
+## Gate 4: RED + USE metrics
+
+- Services emit RED metrics: a Rate counter, an Error counter, and a Duration histogram, each labeled `route`, `method`, `status`. Histogram buckets follow the rule default `[5, 10, 25, 50, 100, 250, 500, 1000, 2500, 5000, 10000]` ms.
+- Resources emit USE metrics: Utilization gauge, Saturation gauge, Errors counter on the resource pool — DB connection pool, worker pool, queue depth, file descriptor count, in-memory cache fill ratio.
+- Naming follows `{service}.{domain}.{metric}_{unit}` in snake_case. Counter names end in `_total`; histogram names end in the unit (`_ms`, `_bytes`).
+- Cardinality budget per metric documented in a comment next to the instrument declaration. Cap label cardinality at the value defined in `rules/hatch3r-observability-metrics.md` (<100 unique values per label). Never use raw `user_id` or unbucketed `path` as a label.
+- Exemplars attached to histogram observations when running with OTel Collector — link the metric data point to the corresponding trace_id for click-through from Grafana to the trace view.
+- Pass criteria: RED triplet present per route + USE triplet present per pooled resource + cardinality cap declared + exemplars wired. Sources: Brendan Gregg USE method, Tom Wilkie RED method, `rules/hatch3r-observability-metrics.md`.
+
+## Gate 5: SLO defined
+
+- Service declares at least one SLO covering availability, latency p95 or p99, and correctness where applicable. SLO target + measurement window + error-budget formula committed in `slo.yaml` or `service.yaml` at the service root.
+- SLI definition uses the user-facing event ratio: `good_events / valid_events`. Source the numerator and denominator from the same signal (load-balancer logs OR application metrics, never mixed).
+- Burn-rate alerts follow the Google SRE workbook multi-window multi-burn-rate (MWMBR) pattern: fast-burn alert at 2% budget consumed in 1 hour AND slow-burn at 5% consumed in 6 hours. Both windows must confirm before paging. Window pair selected per the workbook table to keep detection time < 1 hour for full-budget-exhaustion incidents.
+- Error budget tracked on a rolling 30-day window. Burn-rate threshold = (budget_consumed_ratio / window_fraction).
+- Pass criteria: SLO target documented + burn-rate alert config committed + runbook link present + error-budget tracker dashboard exists. Sources: Google SRE Workbook ch. 5 (Alerting on SLOs), `rules/hatch3r-observability-metrics.md`.
+
+## Gate 6: Error tracker integration
+
+- Sentry / Honeycomb / Datadog / Bugsnag SDK initialized at process entry before any application code runs. Release version + commit SHA tagged via `release: process.env.GIT_SHA` or equivalent.
+- Source maps uploaded in the build pipeline — verify via a grep of the deploy workflow for `sentry-cli sourcemaps upload` or vendor equivalent. Source-map upload step runs on tag-push and on every production deploy.
+- Breadcrumbs configured: capture the last 50 user actions, network requests, and log entries leading to an error. Console-message breadcrumbs disabled in production to avoid leaking debug data.
+- PII scrubbing enabled — `beforeSend` hook strips email, IP, password, authorization tokens from event payloads. Test via a fixture event with PII and assert the captured payload is clean.
+- Sample rates: 100% for errors, 10% for transactions in production. Adjust per cost envelope; record the override in the SDK init comment.
+- Pass criteria: SDK init present + release tag set + source-map upload in CI + PII scrubber wired + breadcrumb config explicit. Sources: `rules/hatch3r-observability-logging.md`, Sentry release tracking guide.
+
+## Gate 7: AI / LLM observability (when applicable)
+
+Applies only when the feature calls an LLM or runs an agent:
+
+- GenAI semconv span on every LLM call carrying `gen_ai.system`, `gen_ai.request.model`, `gen_ai.usage.input_tokens`, `gen_ai.usage.output_tokens`, `gen_ai.response.finish_reasons`. Cache-hit flag emitted as a span attribute when the provider returns one.
+- Tools invoked by the agent emit `tool.{name}.execute` spans per `rules/hatch3r-observability-tracing-detail.md`. Each tool span carries `tool.name`, `tool.input_hash`, `tool.output_status`, `tool.duration_ms`.
+- Cost telemetry per request: a metric counter `gen_ai.tokens_total{direction, model, agent_name}` and a histogram `gen_ai.request_duration_ms`.
+- GenAI spans sampled at 50-100% in production — higher than general spans because volume is low and per-call cost is high.
+
+Cross-reference: `rules/hatch3r-ai-evals.md` (Slice 5), OpenLLMetry semantic conventions.
+
+## Gate 8: Sampling and cost control
+
+- Head sampling configured in the SDK and tail sampling configured at the OpenTelemetry Collector. Default: `ParentBased(TraceIdRatioBased(0.1))` head sample + tail-sampling policy keeping 100% of error traces and 100% of traces with latency > p95.
+- Spans-per-second budget documented per service alongside expected QPS. Budget formula: `target_sps = qps * head_sample * (1 + retry_factor)`. Re-check on every deploy.
+- Log sampling for high-volume routes — health checks and static asset routes drop to 1% sample rate via a per-route override at the logger or middleware.
+- Cardinality drop rules at the Collector or vendor — drop attributes that exceed the cardinality budget rather than failing ingestion. Example: drop `user_id` from spans before export when count > 10k unique values per 5-minute window.
+- Cost-budget alert wired on monthly telemetry spend with a 80% threshold warning and 100% threshold page.
+- Pass criteria: head + tail sampling declared + per-route log sample rule + cardinality drop policy + cost-budget alert. Sources: OpenTelemetry sampling docs, `rules/hatch3r-observability-tracing.md`.
+
+## Gate 9: Alerts-as-code with runbook URL
+
+- Every Prometheus / Datadog / Grafana alert defined in Terraform or YAML committed to the repo. No alerts created via vendor console.
+- Every alert rule carries a `runbook_url` annotation linking to a runbook in `docs/runbooks/` or equivalent. Runbook contains: symptoms, likely causes, diagnostic steps, remediation actions, owner team, escalation policy.
+- Severity tier set on every alert per the project policy: P1 page on-call within 15 min; P2 page within 1 hour; P3 Slack channel; P4 ticket only. Alerts without a severity tag fail the gate.
+- CI check parses alert files and fails when `runbook_url` is missing or the target runbook file does not exist. Provide a `validate-alerts` script under `scripts/` or rely on `promtool check rules` for Prometheus.
+- Pass criteria: 100% alerts in code + 100% alerts with runbook annotation + 100% alerts with severity tier + target runbook file exists. Sources: Grafana alerting-as-code docs, Datadog Terraform provider, `rules/hatch3r-observability-metrics.md`.
+
+## 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 reviewer approval status.
+
+## When this skill runs
+
+- After `hatch3r-implementer` finishes service code and before `hatch3r-qa-validation` runs.
+- On every PR that touches `src/routes/`, `src/handlers/`, `src/services/`, `src/api/`, `src/middleware/`, `src/controllers/`, `src/lib/`, or any file matching the four observability rule globs.
+- Gate 5 (SLO + burn-rate alert review) executes at release-cut time per release; PR-level execution checks only that the SLO file exists and is non-empty.
+
+## Cross-References
+
+- `rules/hatch3r-observability.md`
+- `rules/hatch3r-observability-logging.md`
+- `rules/hatch3r-observability-metrics.md`
+- `rules/hatch3r-observability-tracing.md`
+- `rules/hatch3r-observability-tracing-detail.md`
+
+## References
+
+- OpenTelemetry Semantic Conventions v1.29 — `opentelemetry.io/docs/specs/semconv/`
+- OpenTelemetry GenAI Semantic Conventions — `opentelemetry.io/docs/specs/semconv/gen-ai/`
+- W3C Trace Context Level 1 — `www.w3.org/TR/trace-context/`
+- Google SRE Workbook ch. 5 (SLO + multi-burn-rate alerts) — `sre.google/workbook/alerting-on-slos/`
+- Grafana SLO and alerts-as-code — `grafana.com/docs/grafana/latest/alerting/`
+- Sentry release tracking and source maps — `docs.sentry.io/product/releases/`
+- OpenLLMetry GenAI conventions — `github.com/traceloop/openllmetry`

package/skills/hatch3r-perf-audit/SKILL.md

@@ -14,6 +14,7 @@ cache_friendly: true
 
 ```
 Task Progress:
+- [ ] Step 0: Detect ambiguity (P8 B1)
 - [ ] Step 1: Read performance budgets from rules and specs
 - [ ] Step 2: Profile — bundle size, runtime, memory
 - [ ] Step 3: Identify violations — which budgets exceeded, which hot paths slow
@@ -22,6 +23,19 @@ Task Progress:
 - [ ] Step 6: Verify all budgets met, no 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: target surface (frontend bundle vs backend cold start vs DB query), budget threshold values, profiling environment (local vs CI vs production), regression policy (revert vs ship-and-monitor), and whether optimization is allowed to introduce new deps.
+
+## 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 Performance Budgets
 
 Load the project's performance budgets from project rules and quality documentation:

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,144 @@
+---
+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
+---
+# 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-ui-ux-verify/SKILL.md

@@ -0,0 +1,136 @@
+---
+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
+---
+# 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