hatch3r 1.9.0 → 2.0.0

package/dist/content/skills/hatch3r-browser-verify/SKILL.md

@@ -0,0 +1,307 @@
+---
+id: hatch3r-browser-verify
+name: hatch3r-browser-verify
+type: skill
+description: Opt-in browser verification skill — Playwright-driven visual checks, axe-core a11y audits, screenshot regression diffs, and E2E test scaffolds. Default ON for UI-affecting agent invocations; disable globally via hatch3r config browser=off.
+tags: [browser, playwright, accessibility, visual-regression, floor:content-quality]
+pillars:
+  governance: [P2]
+  content-quality: [CQ1, CQ2, CQ7]
+quality_charter: agents/shared/quality-charter.md
+efficiency_patterns: agents/shared/efficiency-patterns.md
+efficiency_tier: standard
+cache_friendly: true
+parallel_tool_default: true
+opt_in: true
+default_on_for: [hatch3r-ui, hatch3r-ux]
+disable_via: hatch3r config browser=off
+---
+
+# Skill: hatch3r-browser-verify
+
+> Last updated: 2026-05-26
+
+## Quick Start
+
+Invoke this skill whenever a UI-affecting change reaches a verification gate — specifically when `agents/hatch3r-ui.md` or `agents/hatch3r-ux.md` runs against a built artifact. The skill is default ON for those two agents (frontmatter `browser_capability: opt-in`) and OFF elsewhere. Disable globally with `hatch3r config browser=off`; disable per-invocation with `--no-browser`.
+
+Four capabilities, run in order or independently:
+
+1. **Visual verification** — per-route screenshot capture against a built artifact.
+2. **Accessibility audit** — axe-core via `@axe-core/playwright` with 0 serious + 0 critical gate per `rules/hatch3r-accessibility-standards.md`.
+3. **Regression screenshot diffs** — `toHaveScreenshot()` with threshold + masks for dynamic content.
+4. **E2E test scaffolds** — generate a starter spec under `tests/e2e/<feature>.spec.ts`.
+
+```
+Task Progress:
+- [ ] Step 0: Detect ambiguity (P8 B1)
+- [ ] Step 1: Install Playwright + axe-core (if not present)
+- [ ] Step 2: Visual verification of UI changes
+- [ ] Step 3: Accessibility audit via axe-core + Playwright
+- [ ] Step 4: Regression screenshot diffs
+- [ ] Step 5: E2E test authoring scaffold
+```
+
+## Step 0 — Detect Ambiguity (P8 B1)
+
+Before any browser action, scan the invocation for unresolved questions per `agents/shared/user-question-protocol.md`. Triggers: which build artifact to verify against (dev server vs `npm run build` output vs deployed preview URL), which routes are in scope, headed vs headless, whether to install browser binaries when missing, and which baseline branch supplies the screenshot reference set. Ask one multiple-choice question per turn; declare the default-if-no-response.
+
+## 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`). Emit `sub_agents_spawned: { count, rationale }` in your output.
+
+## Invoked by
+
+This skill is the verification HARNESS for the browser sub-vector of CQ1 — it declares HOW Playwright-driven visual, a11y, regression, and E2E checks run against a built artifact. The DISPATCHER that decides WHEN to run it is the CQ specialist agent:
+
+- `agents/hatch3r-ui.md` — invokes this skill when a UI-affecting change reaches a verification gate (frontmatter `default_on_for: [hatch3r-ui, hatch3r-ux]`). The agent contributes the review trigger; this skill contributes the Playwright + axe-core procedure.
+
+Kept standalone (not merged into `hatch3r-ui-ux-verify`): Playwright is also a general `hatch3r-feature` workflow tool, not exclusively a CQ1 gate. No duplication: the agent decides WHEN, this skill defines HOW.
+
+## Step 1: Install Playwright (if not present)
+
+Detection first — skip install if `@playwright/test` is already in `devDependencies` of `package.json`:
+
+```
+jq -r '.devDependencies["@playwright/test"], .devDependencies["@axe-core/playwright"]' package.json
+```
+
+If either returns `null`, ask the user before installing (binaries are large; user machine state changes). On confirmation, pin to the tested-against versions (see Configuration "Tested-against versions" row) so verification outcomes and the bundled Chromium CVE surface stay reproducible across machines:
+
+```
+npm install -D @playwright/test@~1.60.0 @axe-core/playwright@~4.11.3
+npx playwright install chromium
+```
+
+The `~` pin floats patch releases within the tested minor line but blocks an uncontrolled minor bump that would swap the bundled Chromium build (and its CVE exposure) out from under the verification gate. Bump the pin deliberately when upstream Playwright ships a Chromium roll that closes a tracked advisory — see "Known Issues — Browser CVE Awareness".
+
+Use Chromium-only by default — adds ~280MB. Add `firefox` and `webkit` only when the project's browser-support matrix demands them. Record the installed Playwright version AND the bundled Chromium revision (`npx playwright --version` plus `cat node_modules/playwright-core/browsers.json | jq '.browsers[] | select(.name=="chromium")'`) in the verification output for traceability. See "Known Issues — Browser CVE Awareness" below before targeting untrusted or third-party content; the bundled Chromium is intentionally not a security boundary per upstream maintainer guidance.
+
+## Step 2: Visual verification of UI changes
+
+Run against the built artifact (not the dev server) so the verification matches the release surface. Production builds catch tree-shaking regressions, CSS purge mistakes, and asset-pipeline drift that dev servers hide.
+
+```
+npm run build
+npm run preview &     # or `npx serve dist` for static builds
+PREVIEW_PID=$!
+```
+
+Capture per-route screenshots into `.audit-workspace/visual/<timestamp>/`:
+
+```typescript
+// tests/visual/capture.spec.ts
+import { test, expect } from '@playwright/test';
+
+const routes = ['/', '/dashboard', '/settings', '/onboarding'];
+
+for (const route of routes) {
+  test(`capture ${route}`, async ({ page }) => {
+    await page.goto(`http://localhost:4173${route}`);
+    await page.waitForLoadState('networkidle');
+    await page.screenshot({
+      path: `.audit-workspace/visual/${Date.now()}/${route.replace(/\//g, '_') || 'root'}.png`,
+      fullPage: true,
+    });
+  });
+}
+```
+
+After capture: `kill $PREVIEW_PID`. Attach the screenshot directory path to the verification output so reviewers can open the images directly.
+
+## Step 3: Accessibility audit via axe-core + Playwright
+
+Gate: 0 serious + 0 critical violations per route per `rules/hatch3r-accessibility-standards.md`. Moderate violations are recorded but do not fail the gate — they feed the next CQ1 audit cycle.
+
+```typescript
+// tests/a11y/audit.spec.ts
+import { test, expect } from '@playwright/test';
+import AxeBuilder from '@axe-core/playwright';
+
+const routes = ['/', '/dashboard', '/settings', '/onboarding'];
+
+for (const route of routes) {
+  test(`a11y ${route}`, async ({ page }) => {
+    await page.goto(`http://localhost:4173${route}`);
+    await page.waitForLoadState('networkidle');
+
+    const results = await new AxeBuilder({ page })
+      .withTags(['wcag2a', 'wcag2aa', 'wcag21a', 'wcag21aa', 'wcag22aa'])
+      .analyze();
+
+    const blocking = results.violations.filter(
+      (v) => v.impact === 'serious' || v.impact === 'critical',
+    );
+    expect(blocking, JSON.stringify(blocking, null, 2)).toEqual([]);
+  });
+}
+```
+
+Run: `npx playwright test tests/a11y --reporter=json > .audit-workspace/a11y-results.json`.
+
+Per-cycle reminder: axe-core automated checks cover roughly 57% of WCAG issues by volume (Deque Systems). The remaining ~43% require a keyboard trace (`hatch3r-ui` Step) plus one human screen-reader pass per release per `agents/shared/quality-charter.md` §UI/UX quality verification gate.
+
+## Step 4: Regression screenshot diffs
+
+Use `toHaveScreenshot()` for pixel-diff comparison against a baseline. First run produces baselines under `tests/__screenshots__/`; subsequent runs compare.
+
+```typescript
+// tests/visual/regression.spec.ts
+import { test, expect } from '@playwright/test';
+
+test('dashboard regression', async ({ page }) => {
+  await page.goto('http://localhost:4173/dashboard');
+  await page.waitForLoadState('networkidle');
+
+  await expect(page).toHaveScreenshot('dashboard.png', {
+    fullPage: true,
+    maxDiffPixelRatio: 0.01,    // 1% pixel tolerance for sub-pixel font rendering
+    threshold: 0.2,             // YIQ color delta tolerance
+    mask: [
+      page.locator('[data-testid="timestamp"]'),
+      page.locator('[data-testid="user-avatar"]'),
+    ],                          // mask non-deterministic regions
+    animations: 'disabled',     // disable CSS animations during capture
+  });
+});
+```
+
+Update baselines deliberately after intentional UI changes:
+
+```
+npx playwright test tests/visual --update-snapshots
+git add tests/__screenshots__/
+```
+
+Commit the baseline diff in the same PR as the UI change so reviewers can verify the visual delta is intentional.
+
+## Step 5: E2E test authoring scaffold
+
+When a new feature ships, emit a starter spec at `tests/e2e/<feature>.spec.ts`. The scaffold covers happy path + one error path + one keyboard-only path — the minimum surface to gate the CQ2 error-recovery + first-run-success metrics.
+
+```typescript
+// tests/e2e/<feature>.spec.ts
+import { test, expect } from '@playwright/test';
+
+test.describe('<feature>', () => {
+  test('happy path produces expected outcome', async ({ page }) => {
+    await page.goto('/<feature-entry>');
+    // arrange: seed required state
+    // act: drive the user flow
+    // assert: outcome visible to user + URL or DOM state matches spec
+  });
+
+  test('error recovery shows actionable next step', async ({ page }) => {
+    await page.goto('/<feature-entry>');
+    // force the error path (network failure, validation rejection)
+    await expect(page.getByRole('alert')).toBeVisible();
+    await expect(page.getByRole('button', { name: /retry|try again/i })).toBeVisible();
+  });
+
+  test('keyboard-only completes the flow', async ({ page }) => {
+    await page.goto('/<feature-entry>');
+    await page.keyboard.press('Tab');           // first interactive element
+    // ...drive through Tab + Enter only; assert outcome
+  });
+});
+```
+
+Cross-reference the scaffold in the PR description and link it to the feature ticket so the maintainer can flesh it out before merge.
+
+## Configuration
+
+| Setting | Default | Override |
+|---------|---------|----------|
+| Browser verification globally | enabled | `hatch3r config browser=off` (writes `.hatch3r/hatch.json` schemaVersion 3; re-enable with `browser=on`) |
+| Default ON for agent | `hatch3r-ui`, `hatch3r-ux` (frontmatter `browser_capability: opt-in`) | per-invocation `--no-browser` |
+| Browser binary scope | Chromium only | `npx playwright install firefox webkit` |
+| Build artifact source | `npm run build` + `npm run preview` | `--target-url=<url>` for deployed preview |
+| Screenshot baseline | branch `main` | `--baseline=<ref>` |
+| Pixel-diff tolerance | `maxDiffPixelRatio: 0.01`, `threshold: 0.2` | per-test override in spec |
+| `minBrowserVersion` advisory | Chromium ≥145.0.7632.75 (CVE-2026-2441 fix floor; bundled with Playwright ≥1.59.0) | bump when upstream Chrome stable channel ships a new high-severity advisory; verify via `npx playwright --version` + `node_modules/playwright-core/browsers.json` |
+| Tested-against versions | `@playwright/test@~1.60.0` (bundled Chromium 148.0.7778.96) + `@axe-core/playwright@~4.11.3` — cycle 10, verified 2026-05-27 | re-pin on the next D21 cycle when upstream releases a Playwright minor that rolls Chromium past a tracked advisory |
+| Trust posture for `target_url` | first-party content only | use `channel: "chrome"` (or `channel: "chromium-tip-of-tree"`) when the verified UI loads third-party scripts/iframes — see "Known Issues — Browser CVE Awareness" |
+
+## Output contract
+
+Return structured result with proof_trace per state-dependent claim:
+
+```yaml
+skill: hatch3r-browser-verify
+run_id: <uuid>
+playwright_version: <semver>
+target_url: <http://localhost:4173 | deployed-preview-url>
+sub_agents_spawned:
+  count: <int>
+  rationale: <one-sentence justification>
+capabilities_executed: [visual, a11y, regression, e2e-scaffold]
+results:
+  visual:
+    routes_captured: <int>
+    output_dir: .audit-workspace/visual/<timestamp>/
+  a11y:
+    routes_audited: <int>
+    serious_critical_violations: <int>
+    proof_trace: .audit-workspace/a11y-results.json
+    gate_status: PASS | FAIL
+  regression:
+    snapshots_compared: <int>
+    diffs_above_threshold: <int>
+    diff_artifacts: tests/__screenshots__/**/diff.png
+  e2e_scaffold:
+    file_path: tests/e2e/<feature>.spec.ts
+    test_count: 3
+verification:
+  build_artifact_used: <bool>     # true = npm run build output; false = dev server
+  baseline_branch: <ref>
+  binaries_installed_this_run: <bool>
+```
+
+Every state-dependent claim (violation count, diff count, screenshot path) carries a `proof_trace` pointer to the artifact on disk so reviewers can re-open it.
+
+## Known Issues — Browser CVE Awareness
+
+The Chromium binary bundled with `npx playwright install chromium` rolls on Playwright's release cadence (roughly every 4–6 weeks), not Chrome's stable channel cadence (typically weekly for security patches). This means there is a window after each Chrome stable advisory during which `npx playwright install chromium` ships a Chromium build that lacks the latest fixes.
+
+Upstream maintainer position (microsoft/playwright issue #39574, closed 2026-04-03 by maintainer): "We assume that the browsers downloaded with Playwright are used for first-party content and are not serving a security boundary. Once you target untrusted content, you should secure your system with a VM, even if Chrome you are using does not suffer from any CVEs."
+
+What this means for verification runs:
+
+- **First-party content (your own built artifact, no third-party iframes/scripts):** bundled Chromium is the supported path; verify the installed version against the Chromium roll line in the Playwright release notes for your installed Playwright version.
+- **Third-party content (CMS embeds, analytics, marketing tags, deployed previews loading external assets):** switch to `channel: "chrome"` or `channel: "chromium-tip-of-tree"` in `playwright.config.ts`, OR run the verification under a VM/container with a hardened sandbox boundary. Bundled Chromium is explicitly NOT a security boundary for attacker-reachable surfaces.
+- **Active-exploit watch:** historical reference — CVE-2026-2441 (CSS use-after-free, Chrome Threat Analysis Group flagged active exploitation; CISA KEV added 2026-02-17, due date 2026-03-10) was patched in Chromium 145.0.7632.75 per https://nvd.nist.gov/vuln/detail/CVE-2026-2441 (accessed 2026-05-27) and reached Playwright users in 1.59.0 (Chromium 141.0.7390.37 → rolled forward; later 1.60.0 ships 148.0.7778.96). The Playwright-release-to-Chrome-stable gap is the recurring exposure pattern this section guards against, not a single CVE.
+- **Per-cycle hygiene:** before a release-gate verification run, check https://playwright.dev/docs/release-notes for the bundled Chromium revision in your installed Playwright version, then cross-reference https://chromereleases.googleblog.com/search/label/Stable%20updates for any post-bundle-cut advisories. If a Critical/High Chrome advisory landed after the Playwright bundle cut, either upgrade Playwright (when a roll is available) OR set `channel: "chrome"` for the run.
+
+## When to disable
+
+- **Headless CI environments without GPU** — fall back to axe-core CLI on serialized HTML (`@axe-core/cli`) when GPU-backed rendering is unavailable.
+- **Initial bootstrap before any UI exists** — `npx hatch3r init` on an empty repo has no surface to verify; skill stays dormant until first UI commit.
+- **Explicit user opt-out per CONSTITUTION §6 / VISION CLI scope** — `hatch3r config browser=off` respected unconditionally.
+- **`hatch3r-ui` or `hatch3r-ux` invoked on non-UI scope** — e.g., a commit touching only `src/api/`. The opt-in flag is honored only when the agent's actual scope includes UI files.
+
+## Boundaries
+
+- **Always** — run against the built artifact (`npm run build` output) for release-verification gates. Dev-server verification is acceptable for in-flight implementation feedback only.
+- **Ask first** — before installing browser binaries on the user's machine (~280MB for Chromium). One multiple-choice prompt per `agents/shared/user-question-protocol.md`.
+- **Never** — skip axe-core when UI verification is in scope. CQ1 gate requires 0 serious + 0 critical violations per route; skipping the audit is a self-declared gate failure.
+- **Never** — overwrite screenshot baselines without an explicit `--update-snapshots` run signed off by the maintainer. Drift in baselines silently passes regressions.
+
+## Cross-references
+
+- `rules/hatch3r-accessibility-standards.md` — WCAG 2.2 AA conformance gate (0 serious + 0 critical)
+- `agents/hatch3r-ui.md` — CQ1 specialist; this skill is its primary verification engine
+- `agents/hatch3r-ux.md` — CQ2 specialist; consumes the E2E scaffold + a11y audit
+- `agents/shared/quality-charter.md` §UI/UX quality — the verification gate definition this skill implements
+- `skills/hatch3r-ui-ux-verify` — sibling skill orchestrating the 9-gate release check; this skill provides gates 1, 3, 5
+
+## References
+
+- [Playwright Accessibility Testing](https://playwright.dev/docs/accessibility-testing) — official `@axe-core/playwright` integration guide. Accessed 2026-05-26. Trust tier: vendor-official.
+- [Playwright Visual Comparisons](https://playwright.dev/docs/test-snapshots) — `toHaveScreenshot()` API, masks, threshold, `--update-snapshots`. Accessed 2026-05-26. Trust tier: vendor-official.
+- [Playwright SnapshotAssertions API](https://playwright.dev/docs/api/class-snapshotassertions) — full option surface (`maxDiffPixels`, `maxDiffPixelRatio`, `threshold`, `animations`). Accessed 2026-05-26. Trust tier: vendor-official.
+- [@axe-core/playwright on npm](https://www.npmjs.com/package/axe-playwright) — package metadata, current version, weekly downloads. Accessed 2026-05-26. Trust tier: registry-official.
+- [Deque DevTools for Web — Playwright integration](https://docs.deque.com/devtools-for-web/4/en/node-pl-write-tests/) — `withTags`, WCAG 2.2 tag mapping, violation severity model. Accessed 2026-05-26. Trust tier: vendor-maintainer (Deque is axe-core author).
+- [microsoft/playwright issue #39574](https://github.com/microsoft/playwright/issues/39574) — upstream maintainer stance on bundled Chromium as non-security-boundary; recommends `channel: "chrome"` for untrusted-content verification. Closed 2026-04-03 (state COMPLETED). Accessed 2026-05-27. Trust tier: vendor-official.
+- [CVE-2026-2441 (NVD)](https://nvd.nist.gov/vuln/detail/CVE-2026-2441) — Chromium CSS use-after-free, Chromium fix in 145.0.7632.75; CISA KEV addition 2026-02-17. Accessed 2026-05-27. Trust tier: official-feed.
+- [Playwright `channel` option (BrowserType.launch)](https://playwright.dev/docs/api/class-browsertype#browser-type-launch-option-channel) — `chrome`, `chromium-tip-of-tree`, `msedge` channel switches for untrusted-content verification. Accessed 2026-05-27. Trust tier: vendor-official.
+- [Chrome Releases — Stable channel updates](https://chromereleases.googleblog.com/search/label/Stable%20updates) — Chrome stable channel advisory feed; cross-reference per-cycle against your installed Playwright's bundled Chromium revision. Accessed 2026-05-27. Trust tier: vendor-official.

package/dist/content/skills/hatch3r-bug-fix/SKILL.md

@@ -1,5 +1,7 @@
 ---
 id: hatch3r-bug-fix
+name: hatch3r-bug-fix
+type: skill
 description: Step-by-step bug fix workflow. Diagnose root cause, implement minimal fix, write regression test. Use when fixing bugs, working on bug report issues, or when the user mentions a bug.
 tags: [implementation, orchestration]
 quality_charter: agents/shared/quality-charter.md
@@ -93,9 +95,11 @@ Skip TDD and use the standard flow (Steps 3→4) when:
 ## Step 5: Verify
 
 ```bash
-npm run lint && npm run typecheck && npm run test
+${HATCH3R:VERIFY_GATE_ALL}
 ```
 
+Resolved to the project's language-aware gate at sync time (fallback when detection is unknown: `npm run lint && npm run typecheck && npm run test`).
+
 ## Step 5b: Browser Verification (if UI Bug)
 
 Skip this step if the bug had no visual or interactive symptoms.
@@ -115,6 +119,15 @@ Use the project's PR template. Include:
 - Test evidence
 - Rollback plan (required for P0/P1)
 
+## 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 (trivial single-file fix): inline.
+- Tier 2 (multi-file or multi-concern fix): spawn parallel sub-agents per concern (researcher, implementer, reviewer, hatch3r-testability) via the Task tool.
+- Tier 3 (multi-module / high-risk fix): one fresh sub-agent per independent module or gate; orchestrator integrates only.
+
+Emit `sub_agents_spawned: { count, rationale }` in your output.
+
 ## Required Agent Delegation
 
 > **Note:** When this skill is invoked via the orchestration pipeline (board-pickup or workflow commands), skip this section — the orchestrator handles agent delegation in Phases 3 and 4.
@@ -122,7 +135,7 @@ Use the project's PR template. Include:
 You MUST spawn these agents via the Task tool (`subagent_type: "generalPurpose"`) at the appropriate points:
 
 - **`hatch3r-researcher`** — MUST spawn before implementation with modes `symptom-trace`, `root-cause`, `codebase-impact`. For Tier 2+ tasks (per `hatch3r-deep-context`), also include `requirements-elicitation` (bugs often have underspecified reproduction steps and ambiguous expected behavior). Skip only for trivially simple bugs (`risk:low` AND `priority:p3`).
-- **`hatch3r-test-writer`** — MUST spawn after fix implementation to write regression tests covering the fixed behavior and related edge cases.
+- **`hatch3r-testability`** (CQ5) — MUST spawn after fix implementation to author regression tests covering the fixed behavior and related edge cases and verify they meet the mandate map / coverage floor.
 - **`hatch3r-reviewer`** — MUST spawn after implementation for code review before PR creation.
 
 ## Related Skills

package/dist/content/skills/hatch3r-ci-pipeline/SKILL.md

@@ -1,7 +1,8 @@
 ---
 id: hatch3r-ci-pipeline
+name: hatch3r-ci-pipeline
 type: skill
-description: Design and optimize CI/CD pipelines. Covers stage design, test parallelization, artifact management, and pipeline performance.
+description: Designs and optimizes CI/CD pipelines. Covers stage design, test parallelization, artifact management, and pipeline performance.
 tags: [devops]
 quality_charter: agents/shared/quality-charter.md
 efficiency_patterns: agents/shared/efficiency-patterns.md
@@ -28,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: Audit Existing Pipeline
 
@@ -75,6 +71,15 @@ Never under-fan-out to save tokens. Token cost is dominated by quality and compl
 - Measure pipeline duration improvement against the baseline from Step 1.
 - Document the pipeline architecture for the team.
 
+## Supply-Chain Floor
+
+A CI/CD pipeline is the supply-chain attack surface — design the floor in, do not bolt it on. The glob-scoped floor rules attach when you edit a workflow or Dockerfile; this callout surfaces them at pipeline-design time so the controls are planned, not discovered. Apply both rules as authored — this section cross-references, it does not restate:
+
+- `rules/hatch3r-dependency-management.md` — SHA-pin every GitHub Action to a 40-char commit SHA (not a tag); `npm ci` / lockfile-only installs; CVE scan gate before merge; npm Trusted Publishing via GitHub OIDC with `--provenance` (no long-lived publish token), attestations signed by Sigstore.
+- `rules/hatch3r-container-hardening.md` — pin base images by `@sha256:` digest; generate an SBOM (CycloneDX or SPDX) in the build stage; cosign-sign images and verify by digest at deploy; distroless / Wolfi runtime, non-root user.
+
+Gate releases on these the same way Step 2 gates deploys on quality checks: a release stage that publishes without provenance + SBOM, or pulls an unpinned action / untagged base image, fails the gate.
+
 ## Pipeline Performance Targets
 
 | Metric | Target |
@@ -98,3 +103,8 @@ Never under-fan-out to save tokens. Token cost is dominated by quality and compl
 - [ ] Artifact management with retention policies
 - [ ] Pipeline duration meets performance targets
 - [ ] Documentation updated with pipeline architecture
+
+## References
+
+- [Caching dependencies to speed up workflows — GitHub Actions docs](https://docs.github.com/en/actions/using-workflows/caching-dependencies-to-speed-up-workflows) — accessed 2026-05-31, official-docs (GitHub). Source for the lockfile-hash cache-key strategy and cache-hit reporting behind the >80% cache-hit-ratio target.
+- [actionlint — GitHub Actions workflow linter](https://github.com/rhysd/actionlint) — accessed 2026-05-31, independent-analysis (rhysd). Source for the local workflow-YAML validation step in Error Handling.

package/dist/content/skills/hatch3r-cli-fd/SKILL.md

@@ -1,10 +1,17 @@
 ---
 id: hatch3r-cli-fd
+name: hatch3r-cli-fd
+type: skill
 description: "User-friendly find replacement, gitignore-aware. Use when locating filenames or directories by glob with parallel walking; invoke `fd`. Outputs newline-separated hit records; bound results with `-c` or `--max-count`."
 tags: ["cli-tools", "search", "orchestration"]
 quality_charter: agents/shared/quality-charter.md
 efficiency_patterns: agents/shared/efficiency-patterns.md
 cache_friendly: true
+# D9-H-6 (D9, P1): pre-approve the wrapped shell binary on the GitHub Copilot
+# Skills surface so the runtime skips per-invocation confirmation for `fd`.
+# Rendered as an `allowed-tools:` frontmatter line on `.github/skills/.../SKILL.md`
+# by the Copilot adapter; other adapters ignore the field.
+allowed_tools: ["fd"]
 cli_tool:
   id: fd
   bin: fd
@@ -17,6 +24,17 @@ cli_tool:
 
 User-friendly find replacement, gitignore-aware
 
+## §0 — Ambiguity & Safety Gate (P8 B1)
+
+Before invoking `fd`, resolve these via `agents/shared/user-question-protocol.md` (default behavior, not exception-driven):
+- **Scope:** when the search root or pattern matches more files than intended (a bare glob over the repo root, `-H` including dotfiles), confirm the target path before running.
+- **Irreversibility:** `fd` is read-only on its own, but `fd … -x` / `-X` runs an arbitrary command per match. `fd <pat> -x rm` or any mutating `--exec` is destructive and fan-out-wide — confirm the command and the match set before running, and prefer printing the list first.
+- **Ambiguity:** when the request maps to two or more matchers with materially different result sets (regex vs `-g` glob, `-e ext` vs path regex), ask which one.
+
+## Fan-out Discipline (P8 B2)
+
+Tier 1 reference card — no fan-out. This skill is a single-tool usage reference an agent consults inline; it spawns no sub-agents. Fan-out is owned by the calling workflow per its own Fan-out Discipline block. Source: `rules/hatch3r-fan-out-discipline.md` (P8 B2).
+
 ## When to Use
 
 Reach for `fd` when the task is in the **search** category and the agent would otherwise call an MCP tool or read large outputs into context.
@@ -75,11 +93,25 @@ Verify with:
 command -v fd
 ```
 
-Install (mac):
+Install (macOS — default for this machine):
 
 ```bash
 # brew
 brew install fd
 ```
 
+Install (Linux):
+
+```bash
+# apt
+sudo apt install fd-find
+```
+
+Install (Windows):
+
+```bash
+# scoop
+scoop install fd
+```
+
 Homepage: https://github.com/sharkdp/fd

package/dist/content/skills/hatch3r-cli-fzf/SKILL.md

@@ -1,10 +1,17 @@
 ---
 id: hatch3r-cli-fzf
+name: hatch3r-cli-fzf
+type: skill
 description: "Interactive fuzzy finder for TTY pickers. Use when ad-hoc interactive picker over piped stdin streams from another command; invoke `fzf`. Requires a TTY; degrade gracefully to non-interactive batch in CI."
 tags: ["cli-tools", "interactive", "maintenance"]
 quality_charter: agents/shared/quality-charter.md
 efficiency_patterns: agents/shared/efficiency-patterns.md
 cache_friendly: true
+# D9-H-6 (D9, P1): pre-approve the wrapped shell binary on the GitHub Copilot
+# Skills surface so the runtime skips per-invocation confirmation for `fzf`.
+# Rendered as an `allowed-tools:` frontmatter line on `.github/skills/.../SKILL.md`
+# by the Copilot adapter; other adapters ignore the field.
+allowed_tools: ["fzf"]
 cli_tool:
   id: fzf
   bin: fzf
@@ -17,6 +24,17 @@ cli_tool:
 
 Interactive fuzzy finder for TTY pickers
 
+## §0 — Ambiguity & Safety Gate (P8 B1)
+
+Before invoking `fzf`, resolve these via `agents/shared/user-question-protocol.md` (default behavior, not exception-driven):
+- **Scope:** confirm the input stream piped into `fzf` is the intended candidate set; a wrong upstream command silently changes what gets ranked.
+- **Irreversibility:** `fzf` only selects — it never mutates files. The real hazard is invoking interactive `fzf` (no `--filter`) in a non-TTY context (CI, agent loop): it blocks on stdin forever. Always use `--filter` headless mode from an autonomous agent; treat any downstream action on the selection (the command you pipe the pick into) under its own irreversibility check.
+- **Ambiguity:** when more than one match scores closely and the workflow needs a single deterministic pick, pin it with `--filter … | head -1` rather than relying on interactive choice.
+
+## Fan-out Discipline (P8 B2)
+
+Tier 1 reference card — no fan-out. This skill is a single-tool usage reference an agent consults inline; it spawns no sub-agents. Fan-out is owned by the calling workflow per its own Fan-out Discipline block. Source: `rules/hatch3r-fan-out-discipline.md` (P8 B2).
+
 ## When to Use
 
 Reach for `fzf` when the task is in the **interactive** category and the agent would otherwise call an MCP tool or read large outputs into context.
@@ -74,11 +92,25 @@ Verify with:
 command -v fzf
 ```
 
-Install (mac):
+Install (macOS — default for this machine):
 
 ```bash
 # brew
 brew install fzf
 ```
 
+Install (Linux):
+
+```bash
+# apt
+sudo apt install fzf
+```
+
+Install (Windows):
+
+```bash
+# scoop
+scoop install fzf
+```
+
 Homepage: https://github.com/junegunn/fzf

package/dist/content/skills/hatch3r-cli-gh/SKILL.md

@@ -1,10 +1,17 @@
 ---
 id: hatch3r-cli-gh
+name: hatch3r-cli-gh
+type: skill
 description: "GitHub CLI — repos, issues, PRs, releases, gists. Use when drafting GitHub pull requests, issues, releases, gists, or workflow dispatches; invoke `gh`. Authenticates via the platform's native token mechanism (OAuth / PAT)."
 tags: ["cli-tools", "forge", "orchestration"]
 quality_charter: agents/shared/quality-charter.md
 efficiency_patterns: agents/shared/efficiency-patterns.md
 cache_friendly: true
+# D9-H-6 (D9, P1): pre-approve the wrapped shell binary on the GitHub Copilot
+# Skills surface so the runtime skips per-invocation confirmation for `gh`.
+# Rendered as an `allowed-tools:` frontmatter line on `.github/skills/.../SKILL.md`
+# by the Copilot adapter; other adapters ignore the field.
+allowed_tools: ["gh"]
 cli_tool:
   id: gh
   bin: gh
@@ -17,6 +24,17 @@ cli_tool:
 
 GitHub CLI — repos, issues, PRs, releases, gists
 
+## §0 — Ambiguity & Safety Gate (P8 B1)
+
+Before invoking `gh`, resolve these via `agents/shared/user-question-protocol.md` (default behavior, not exception-driven):
+- **Scope:** when the target repo/PR/issue number is not explicit (e.g. "close the PR" with several open), confirm which one before acting — never guess the number.
+- **Irreversibility:** `gh pr close`, `gh pr merge`, `gh release create`, `gh issue close`, `gh repo delete`, and `gh api -X DELETE/POST/PATCH` mutate remote state. Confirm intent before running any of these; they are not safe to assume.
+- **Ambiguity:** when the request maps to two or more flag combinations with materially different blast radius (e.g. `--squash` vs `--rebase` on `gh pr merge`), ask which one.
+
+## Fan-out Discipline (P8 B2)
+
+Tier 1 reference card — no fan-out. This skill is a single-tool usage reference an agent consults inline; it spawns no sub-agents. Fan-out is owned by the calling workflow per its own Fan-out Discipline block. Source: `rules/hatch3r-fan-out-discipline.md` (P8 B2).
+
 ## When to Use
 
 Reach for `gh` when the task is in the **forge** category and the agent would otherwise call an MCP tool or read large outputs into context.
@@ -80,11 +98,42 @@ Verify with:
 command -v gh
 ```
 
-Install (mac):
+Install (macOS — default for this machine):
 
 ```bash
 # brew
 brew install gh
 ```
 
+Install (Linux):
+
+```bash
+# apt
+sudo apt install gh
+```
+
+Install (Windows):
+
+```bash
+# winget
+winget install GitHub.cli
+```
+
 Homepage: https://cli.github.com/
+
+## Security
+
+Minimum recommended version: `>=2.93.0`. Builds below this floor carry known unpatched advisories — upgrade before relying on the tool.
+
+GHSA-8xvp-7hj6-mcj9 (CVE-2026-48501, High): gh CLI 2.92.0 and earlier attach the Authorization header to TUF repository-mirror requests issued by `gh attestation`, `gh release verify`, and `gh release verify-asset` — sending the github.com token (or `GH_ENTERPRISE_TOKEN` / `GITHUB_ENTERPRISE_TOKEN`) to hosts that are not GitHub API endpoints (`tuf-repo.github.com`, `tuf-repo-cdn.sigstore.dev`, and an Azure blob host). Any token previously used with those commands should be treated as exposed and rotated. Fixed in 2.93.0 — upgrade before running attestation or release-verify flows.
+
+GHSA-crc3-h8v6-qh57 (CVE-2026-45803, Low): `gh run view --log` and `gh run view --log-failed` stream GitHub Actions workflow log lines to stdout or the pager without sanitizing terminal control sequences, so a malicious workflow can embed escape sequences that execute when a maintainer views the log (altered window titles, manipulated output, command execution in emulators such as `screen`). This is an escape-sequence-injection issue, not a token leak. Fixed in 2.92.0 — upgrade before viewing logs from untrusted workflows.
+
+GHSA-55v3-xh23-96gh (token-leak note, `cli/go-gh` library): inside a codespace, `auth.TokenForHost` could source `GITHUB_TOKEN` for a non-`github.com`/`ghe.com` host, sending the token to an unintended host. Fixed in go-gh 2.11.1, vendored into gh ≥ 2.42.0; the `>=2.93.0` floor already clears it. Relevant when running gh against untrusted GitHub Enterprise hosts from a codespace.
+
+## References
+
+- GHSA-8xvp-7hj6-mcj9 / CVE-2026-48501 — https://github.com/cli/cli/security/advisories/GHSA-8xvp-7hj6-mcj9 (accessed 2026-06-06; tier: vendor advisory — GitHub CLI maintainers)
+- GHSA-crc3-h8v6-qh57 / CVE-2026-45803 — https://github.com/cli/cli/security/advisories/GHSA-crc3-h8v6-qh57 (accessed 2026-06-05; tier: vendor advisory — GitHub CLI maintainers)
+- GHSA-55v3-xh23-96gh — https://github.com/cli/go-gh/security/advisories/GHSA-55v3-xh23-96gh (accessed 2026-06-05; tier: vendor advisory — GitHub CLI maintainers)
+- GitHub Advisory Database (queried via `gh api /repos/cli/cli/security-advisories`, accessed 2026-06-05; tier: official advisory feed)