mandrel 2.40.0 → 2.42.0

package/.agents/skills/core/gates-and-baselines/SKILL.md

@@ -2,9 +2,10 @@
 name: gates-and-baselines
 description:
   Governs quality gates and the unified-baseline snapshots. Use when authoring
-  a baseline refresh commit (CRAP, maintainability, dead-exports, lighthouse),
-  when setting up or modifying CI quality gates, or when introducing a new gate
-  that asserts on pre-existing state without turning the integration branch red.
+  a baseline refresh commit (coverage, CRAP, maintainability, duplication,
+  dead-exports), when setting up or modifying CI quality gates, or when
+  introducing a new gate that asserts on pre-existing state without turning the
+  base branch red.
 allowed_tools:
   - Read
   - Write
@@ -15,141 +16,13 @@ allowed_tools:
 
 ## Policy Capsule
 
-- **No gate may be skipped.** Failing lint means fix lint, not disable the rule; a failing test means fix the code, not `.skip` or delete the test. Gates are ordered shift-left so cheap checks fail first, and CI failure output is fed back verbatim with the directive to reproduce and fix locally before re-pushing.
+- **No gate may be skipped.** Failing lint means fix lint; a failing test means fix the code, not `.skip` or delete the test. Feed CI failure output back verbatim and reproduce locally before re-pushing.
 - **Introducing a gate that asserts on pre-existing state** (doc-drift, lint-vocabulary, dependency-cycle, missing-coverage) MUST land green at merge: either advisory-first (report-only until the backlog is burned down) or with the populated baseline committed in the same change that turns the gate on. Never wire a gate into `requiredChecks` that lands red on latent findings nobody authored.
 - **Refresh a baseline only when the change is deliberate** — a rename/move, an operator-approved complexity bump, a signed-off perf delta, an intentional API-surface change. Never refresh to paper over an unintentional regression; fix the regression instead.
-- **Pick the refresh that matches why you are refreshing** — the two are different scopes, and the wrong one silently no-ops. `npm run <kind>:update` is **diff-scoped**: it re-scores only files changed in `origin/main..HEAD` and preserves every other row verbatim. That is what you want after changing code. `npm run <kind>:reanchor` is the same script with `--full-scope`: it re-scores every file in every target dir. That is what you want when the baseline is **stale** — a scorer-version bump, a coverage-shape change, accumulated drift — because a diff-scoped run would leave the stale rows exactly as they were and the staleness finding would re-fire. Kinds with both scopes: `coverage`, `crap`, `maintainability`, `duplication`. Dead-exports has a producer but no scope axis — knip scores the whole graph, so `npm run dead-exports:update` (both passes, via `.agents/scripts/update-dead-exports-baseline.js`) is the only sanctioned way to write `baselines/dead-exports.json` / `baselines/dead-exports-production.json`; never hand-edit those files. Lighthouse still has no producer — edit `baselines/lighthouse.json` directly. Run any of them on the **Story branch**, not on `main`.
+- **Pick the refresh that matches why you are refreshing** — the wrong scope silently no-ops. `npm run <kind>:update` is **diff-scoped**: it re-scores only files changed in `origin/main..HEAD` and preserves every other row verbatim; that is what you want after changing code. `npm run <kind>:reanchor` is the same script with `--full-scope` and re-scores every file in every target dir; that is what you want when the baseline is **stale** (a scorer-version bump, a coverage-shape change, accumulated drift), because a diff-scoped run would leave the stale rows exactly as they were.
+- Kinds carrying both scopes: `coverage`, `crap`, `maintainability`, `duplication`. Dead-exports has no scope axis — knip scores the whole graph, so `npm run dead-exports:update` (both passes) is the only sanctioned way to write `baselines/dead-exports.json` / `baselines/dead-exports-production.json`; never hand-edit them. Run any refresh on the **Story branch**, never on `main`.
 - Verify the refresh diff is scoped to the relevant `baselines/<kind>.json` (plus cosmetic `package-lock.json` churn only). If unrelated files appear, STOP — the refresh is contaminated. Stage baseline files **explicitly** (`git add baselines/<kind>.json`); never `git add -A` in a refresh commit.
-- Commit-subject contract: a **Conventional-Commits** subject `chore(baselines): refresh <kind> snapshot for <reason>` — never an ad-hoc leading token like `baseline-refresh:` (commitlint and the planner validator reject it). The body is **mandatory** and non-empty: what changed, why the new floor is correct, and the Story that triggered it.
-- Add the machine-readable trailer `baseline-refresh: true` (git-trailer `Key: value` style) and `Story: #<storyId>` to the body whenever observability classification matters. Never pass `--no-verify`; the `commit-msg` hook (commitlint) MUST run and pass.
+- Commit-subject contract: the **Conventional-Commits** subject `chore(baselines): refresh <kind> snapshot for <reason>` — never an ad-hoc leading token like `baseline-refresh:` (commitlint and the planner validator reject it). The body is **mandatory** and non-empty: what changed, why the new floor is correct, and the Story that triggered it.
+- Add the machine-readable trailer `baseline-refresh: true` (git-trailer `Key: value` style) and `Story: #<storyId>` to that body. Never pass `--no-verify`; the `commit-msg` hook (commitlint) MUST run and pass.
 - After the refresh lands, re-run `node .agents/scripts/check-baselines.js` to confirm the gate passes against the new snapshot; if it still fails, a sibling kind drifted — refresh that kind too.
-- Keep credentials in GitHub Secrets (or platform equivalent) even for CI-only test databases; treat the security audit (`npm audit` or equivalent) as gating for critical/high vulnerabilities reachable in production code.
-
-## The Quality Gate Pipeline
-
-Automate quality gates so no change reaches production without passing tests,
-lint, type checking, and build. **Shift left** — a bug caught in linting costs
-minutes; the same bug caught in production costs hours — and prefer many small,
-frequent releases over big-bang merges (a deploy of 3 changes is debuggable, one
-of 30 is not).
-
-```text
-lint → typecheck → unit tests → build → integration → E2E (optional)
-     → security audit → bundle-size
-```
-
-**No gate can be skipped.** If lint fails, fix lint. If a test fails, fix the
-code. When CI fails, feed the specific error back into the agent loop with the
-directive to verify locally before re-pushing.
-
-### Introducing a gate on pre-existing state
-
-A new gate that asserts on latent state (doc-drift, lint-vocabulary,
-dependency-cycle, missing-test-coverage) lands red because of findings nobody
-authored, and every downstream PR is blocked until someone hotfixes the
-integration branch. Before wiring such a gate into `requiredChecks`, land it in
-a shape that is green at merge — **advisory-first** (report-only until the
-backlog is burned down) or by **committing the populated baseline in the same
-change** that turns the gate on.
-
-## Baseline Refresh
-
-The close-validation chain enforces unified baseline snapshots
-(`baselines/crap.json`, `baselines/maintainability.json`,
-`baselines/dead-exports.json`, `baselines/lighthouse.json`). A refresh is **not**
-a regression entry — it tells the ratchet that the new baseline key is
-intentional, so the gate compares future runs against the refreshed snapshot
-rather than the prior one.
-
-**When to refresh:** a file rename/move detached an MI/CRAP key; a method rename
-inside a file produced a phantom new + phantom deleted key (escomplex keys CRAP
-rows on `<file>::<methodName>`); an operator-approved complexity bump or perf
-delta needs to be enshrined as the new floor; a dead-export gate flagged a
-signed-off API-surface change. If the underlying change is an **unintentional**
-regression, do not refresh — remediate first.
-
-### Commit-subject contract (authoritative)
-
-```text
-chore(baselines): refresh <kind> snapshot for <reason>
-
-<non-empty body explaining the refresh — what changed, why the new
-baseline is the correct floor, and any operator sign-off reference>
-
-baseline-refresh: true
-Story: #<storyId>
-```
-
-The `commit-msg` hook (`commitlint`) rejects any subject whose leading token is
-not one of `feat|fix|chore|refactor|perf|docs|style|test|build|ci|revert`, and
-`--no-verify` is forbidden by
-[`.agents/rules/git-conventions.md`](../../../rules/git-conventions.md), so the
-subject MUST conform. `release-please` consumes the subject on `main`;
-`chore(baselines):` keeps the refresh out of the user-facing changelog (correct —
-it is internal hygiene) while staying machine-parseable. The
-`baseline-refresh: true` **body trailer** is the canonical machine-readable
-marker — subject-level leading tokens are not, and must not be, used for this
-purpose. (Its only reader, `baseline-refresh-rate.js`, went with the
-execution-analysis surface in Story #4545; the trailer convention stands on its
-own as the parseable marker for any future reader.)
-
-### Procedure
-
-| Kind            | After a code change (diff-scoped)  | Stale baseline (full re-anchor)      |
-| --------------- | ---------------------------------- | ------------------------------------ |
-| CRAP            | `npm run crap:update`              | `npm run crap:reanchor`              |
-| Maintainability | `npm run maintainability:update`   | `npm run maintainability:reanchor`   |
-| Coverage        | `npm run coverage:update`          | `npm run coverage:reanchor`          |
-| Duplication     | `npm run duplication:update`       | `npm run duplication:reanchor`       |
-| Dead-exports    | `npm run dead-exports:update` (regenerates both passes; never hand-edit the JSON) | same — no scope flag applies |
-| Lighthouse      | edit `baselines/lighthouse.json`   | same — no scope flag applies         |
-
-1. **Run the matching command for your reason** — left column after a code
-   change, right column for a stale baseline — on the Story branch (HEAD must
-   already be the Story branch, not `main`).
-2. **Verify the diff is scoped** to the relevant `baselines/<kind>.json` (and
-   possibly cosmetic `package-lock.json` churn). Unrelated files → STOP, the
-   refresh is contaminated. Judge contamination by **which files** changed, not
-   how many rows moved inside the baseline: a `:reanchor` legitimately rewrites
-   most of its own file, so say in the commit body that the breadth is a
-   re-anchor and not a mass regression.
-3. **Author the commit.** Stage the baseline file(s) explicitly, then commit with
-   the Conventional-Commits subject + body trailer above:
-
-   ```bash
-   git add baselines/<kind>.json
-   git commit -m "$(cat <<'EOF'
-   chore(baselines): refresh <kind> snapshot for <reason>
-
-   <body: what changed, why the new floor is correct, linking the Story.>
-
-   baseline-refresh: true
-   Story: #<storyId>
-   EOF
-   )"
-   ```
-
-   Do NOT pass `--no-verify`.
-4. **Re-run the gate** — `node .agents/scripts/check-baselines.js`. If it still
-   fails, a sibling kind drifted; repeat from step 1 for that kind.
-
-## Red Flags
-
-- CI failures ignored or silenced; tests disabled in CI to make the pipeline pass.
-- A new required gate merged red on pre-existing findings, blocking every
-  downstream PR.
-- A legacy ad-hoc leading token (`baseline-refresh:`) as the commit subject type.
-- An empty-body refresh — unreviewable, hides the operator decision.
-- A refresh commit whose diff touches unrelated files (contaminated refresh).
-- Refreshing to paper over an unintentional regression.
-- Secrets stored in code or CI config instead of a secrets manager.
-
-## Verification
-
-- [ ] Every quality gate is present (lint, types, tests, build, audit) and
-      failures block merge (branch protection configured).
-- [ ] Any newly introduced gate is green at merge (advisory-first or
-      baseline-in-same-change).
-- [ ] A baseline refresh uses the Conventional-Commits subject + non-empty body
-      + `baseline-refresh: true` trailer, staged explicitly, no `--no-verify`.
-- [ ] `check-baselines.js` passes against the refreshed snapshot.
+- Open a [`reference.md`](reference.md) section only when the task engages it: the baseline roster, the per-kind refresh table, and the step-by-step procedure live there.

package/.agents/skills/core/gates-and-baselines/reference.md

@@ -0,0 +1,103 @@
+# Gates and Baselines — Reference (on-demand)
+
+**Read this when** a refresh is actually in front of you and the Policy Capsule
+in [`SKILL.md`](SKILL.md) does not settle it. The capsule is the contract; this
+file is the roster, the per-kind command table, and the procedure.
+
+## The baseline roster
+
+`baselines/` holds one snapshot per gate kind. What is present here is what
+`check-baselines.js` and its siblings enforce:
+
+| Baseline | Enforced by |
+| --- | --- |
+| `coverage.json` | `npm run coverage:check` |
+| `crap.json` | `npm run crap:check` |
+| `maintainability.json` | `npm run maintainability:check` |
+| `duplication.json` | `npm run duplication:check` |
+| `dead-exports.json`, `dead-exports-production.json` | `check-dead-exports.js` |
+| `arch-cycles.json` | `npm run check:arch` |
+| `cyclomatic.json` | `npm run check:cyclomatic` |
+| `context-budget.json` | `npm run check:context-budget` |
+| `workflow-citations.json` | `npm run check:workflow-citations` |
+| `agents-loc.csv` | `npm run baseline:agents-loc` |
+
+A refresh is **not** a regression entry — it tells the ratchet that the new
+baseline key is intentional, so the gate compares future runs against the
+refreshed snapshot rather than the prior one.
+
+**When to refresh:** a file rename/move detached an MI/CRAP key; a method
+rename inside a file produced a phantom new + phantom deleted key (escomplex
+keys CRAP rows on `<file>::<methodName>`); an operator-approved complexity bump
+or perf delta needs to be enshrined as the new floor; a dead-export gate
+flagged a signed-off API-surface change. If the underlying change is an
+**unintentional** regression, do not refresh — remediate first.
+
+## Per-kind refresh commands
+
+| Kind            | After a code change (diff-scoped)  | Stale baseline (full re-anchor)      |
+| --------------- | ---------------------------------- | ------------------------------------ |
+| CRAP            | `npm run crap:update`              | `npm run crap:reanchor`              |
+| Maintainability | `npm run maintainability:update`   | `npm run maintainability:reanchor`   |
+| Coverage        | `npm run coverage:update`          | `npm run coverage:reanchor`          |
+| Duplication     | `npm run duplication:update`       | `npm run duplication:reanchor`       |
+| Dead-exports    | `npm run dead-exports:update` (regenerates both passes; never hand-edit the JSON) | same — no scope flag applies |
+| Cyclomatic      | `npm run cyclomatic:update`        | same — no scope flag applies         |
+| Context budget  | `node .agents/scripts/check-context-budget.js --update` | same — no scope flag applies |
+
+## Procedure
+
+1. **Run the matching command for your reason** — left column after a code
+   change, right column for a stale baseline — on the Story branch (HEAD must
+   already be the Story branch, not `main`).
+2. **Verify the diff is scoped** to the relevant `baselines/<kind>.json` (and
+   possibly cosmetic `package-lock.json` churn). Unrelated files → STOP, the
+   refresh is contaminated. Judge contamination by **which files** changed, not
+   how many rows moved inside the baseline: a `:reanchor` legitimately rewrites
+   most of its own file, so say in the commit body that the breadth is a
+   re-anchor and not a mass regression.
+3. **Author the commit.** Stage the baseline file(s) explicitly, then commit
+   with the Conventional-Commits subject the capsule pins, plus the body and
+   trailers:
+
+   ```bash
+   git add baselines/<kind>.json
+   git commit -m "$(cat <<'EOF'
+   <the refresh subject the Policy Capsule pins>
+
+   <body: what changed, why the new floor is correct, linking the Story.>
+
+   baseline-refresh: true
+   Story: #<storyId>
+   EOF
+   )"
+   ```
+
+   Do NOT pass `--no-verify`.
+4. **Re-run the gate** — `node .agents/scripts/check-baselines.js`. If it still
+   fails, a sibling kind drifted; repeat from step 1 for that kind.
+
+The `baseline-refresh: true` body trailer — not a subject-level token — is the
+canonical machine-readable marker for a refresh commit; the decision and its
+history are recorded in
+[`docs/decisions.md` ADR 20260906-5160b](../../../../docs/decisions.md).
+
+## Red Flags
+
+- CI failures ignored or silenced; tests disabled in CI to make the pipeline
+  pass.
+- A new required gate merged red on pre-existing findings, blocking every
+  downstream PR.
+- A legacy ad-hoc leading token (`baseline-refresh:`) as the commit subject
+  type.
+- An empty-body refresh — unreviewable, hides the operator decision.
+- A refresh commit whose diff touches unrelated files (contaminated refresh).
+- Refreshing to paper over an unintentional regression.
+
+## Verification
+
+- [ ] Any newly introduced gate is green at merge (advisory-first or
+      baseline-in-same-change).
+- [ ] A baseline refresh uses the pinned subject + non-empty body +
+      `baseline-refresh: true` trailer, staged explicitly, no `--no-verify`.
+- [ ] `check-baselines.js` passes against the refreshed snapshot.

package/.agents/skills/core/idea-refinement/SKILL.md

@@ -34,15 +34,6 @@ separate Epic Clarity Gate path in v2 — N=1 Story authoring with a folded
 You are an ideation partner. Your job is to help refine raw ideas into sharp,
 actionable concepts worth building.
 
-### Philosophy
-
-- Simplicity is the ultimate sophistication. Push toward the simplest version
-  that still solves the real problem.
-- Start with the user experience, work backwards to technology.
-- Say no to 1,000 things. Focus beats breadth.
-- Challenge every assumption. "How it's usually done" is not a reason.
-- Show people the future — don't just give them better horses.
-
 ### Process
 
 When the user invokes this skill with an idea (`$ARGUMENTS`), guide them through
@@ -93,9 +84,8 @@ before anything lands in the Phase 3 one-pager.
    vitamin), feasibility branches (cost, hardest part, build vs. buy,
    sequencing), differentiation branches (why switch), and hidden assumptions
    (what you're betting is true, what could kill this, what you're ignoring and
-   why that's okay for now). Read `refinement-criteria.md` in this skill
-   directory for the full evaluation rubric. If the list is empty after
-   enumeration, take the off-ramp.
+   why that's okay for now). If the list is empty after enumeration, take the
+   off-ramp.
 
 3. **Interrogate sequentially.** For each branch, in priority order
    (highest-leverage / most blocking first):
@@ -177,9 +167,3 @@ saying no to good ideas. Make the trade-offs explicit.
 
 Ask the user if they'd like to save this to `docs/ideas/[idea-name].md` (or a
 location of their choosing). Only save if they confirm.
-
-### Tone
-
-Direct, thoughtful, slightly provocative. You're a sharp thinking partner, not a
-facilitator reading from a script. Channel the energy of "that's interesting,
-but what if…" — always pushing one step further without being exhausting.

package/.agents/skills/core/security-and-hardening/SKILL.md

@@ -4,8 +4,8 @@ description:
   Hardens code against vulnerabilities. Use when handling user input,
   authentication, data storage, or external integrations. The non-negotiable
   security MUSTs live in `.agents/rules/security-baseline.md`; this skill shows
-  how to apply them with process guidance, an audit-triage tree, and a review
-  checklist.
+  how to apply them, with the project's surfacing and validation-response
+  process.
 ---
 
 # Security and Hardening
@@ -35,5 +35,3 @@ task engages it.
 
 - [Security Surfacing, Not Runtime Pause](reference.md#security-surfacing-not-runtime-pause)
 - [Validation-Error Responses](reference.md#validation-error-responses)
-- [Triaging npm audit Results](reference.md#triaging-npm-audit-results)
-- [Security Review Checklist](reference.md#security-review-checklist)

package/.agents/skills/core/security-and-hardening/reference.md

@@ -45,73 +45,3 @@ and [§ Response Envelope](../../../rules/api-conventions.md#response-envelope).
 Do not hand-roll a divergent status (e.g. 422) or envelope shape in
 security-relevant handlers — cite the rule and reuse its shape, keeping the
 security skill and the api skill in agreement.
-
-## Triaging npm audit Results
-
-The MUST is in [security-baseline § Dependency Hygiene](../../../rules/security-baseline.md#dependency-hygiene).
-This decision tree shows how to prioritize:
-
-```text
-npm audit reports a vulnerability
-├── Severity: critical or high
-│   ├── Is the vulnerable code reachable in your app?
-│   │   ├── YES --> Fix immediately (update, patch, or replace the dependency)
-│   │   └── NO (dev-only dep, unused code path) --> Fix soon, but not a blocker
-│   └── Is a fix available?
-│       ├── YES --> Update to the patched version
-│       └── NO --> Check for workarounds, consider replacing the dependency, or add to allowlist with a review date
-├── Severity: moderate
-│   ├── Reachable in production? --> Fix in the next release cycle
-│   └── Dev-only? --> Fix when convenient, track in backlog
-└── Severity: low
-    └── Track and fix during regular dependency updates
-```
-
-**Key questions:**
-
-- Is the vulnerable function actually called in your code path?
-- Is the dependency a runtime dependency or dev-only?
-- Is the vulnerability exploitable given your deployment context (e.g., a
-  server-side vulnerability in a client-only app)?
-
-When you defer a fix, document the reason and set a review date.
-
-## Security Review Checklist
-
-Use this when reviewing your own change before requesting human review. Each
-item maps to a section in
-[`security-baseline.md`](../../../rules/security-baseline.md).
-
-```markdown
-### Authentication
-
-- [ ] Passwords hashed with bcrypt/scrypt/argon2 (salt rounds ≥ 12)
-- [ ] Session tokens are httpOnly, secure, sameSite
-- [ ] Login has rate limiting
-- [ ] Password reset tokens expire
-
-### Authorization
-
-- [ ] Every endpoint checks user permissions
-- [ ] Users can only access their own resources
-- [ ] Admin actions require admin role verification
-
-### Input
-
-- [ ] All user input validated at the boundary
-- [ ] SQL queries are parameterized
-- [ ] HTML output is encoded/escaped
-
-### Data
-
-- [ ] No secrets in code or version control
-- [ ] Sensitive fields excluded from API responses
-- [ ] PII encrypted at rest (if applicable)
-
-### Infrastructure
-
-- [ ] Security headers configured (CSP, HSTS, etc.)
-- [ ] CORS restricted to known origins
-- [ ] Dependencies audited for vulnerabilities
-- [ ] Error messages don't expose internals
-```

package/.agents/skills/skills.index.json

@@ -1,24 +1,14 @@
 {
-  "generatedAt": "2026-08-06T10:26:18.702Z",
+  "generatedAt": "2026-09-06T12:59:23.069Z",
   "generator": "generate-skills-index.js@1",
   "skills": [
-    {
-      "name": "api-and-interface-design",
-      "tier": "core",
-      "category": "core",
-      "path": ".agents/skills/core/api-and-interface-design/SKILL.md",
-      "description": "Designs stable, well-documented APIs and module interfaces. Use when creating REST/GraphQL endpoints, defining contracts between modules, or changing public interfaces. The wire-format SSOT — response envelope, HTTP status codes, validation taxonomy, payload naming — lives in `.agents/rules/api-conventions.md`; this skill shows authors how to apply it.",
-      "policyCapsuleBullets": 9,
-      "allowedTools": null,
-      "vendor": null
-    },
     {
       "name": "browser-testing-with-devtools",
       "tier": "core",
       "category": "core",
       "path": ".agents/skills/core/browser-testing-with-devtools/SKILL.md",
       "description": "Tests in real browsers. Use when building or debugging anything that runs in a browser. Use when you need to inspect the DOM, capture console errors, analyze network requests, profile performance, or verify visual output with real runtime data via Chrome DevTools MCP.",
-      "policyCapsuleBullets": 9,
+      "policyCapsuleBullets": 8,
       "allowedTools": null,
       "vendor": null
     },
@@ -28,17 +18,7 @@
       "category": "core",
       "path": ".agents/skills/core/code-review-and-quality/SKILL.md",
       "description": "Conducts multi-axis code review and runs the disciplined post-green refactor pass. Use before merging any change, when reviewing code written by yourself, another agent, or a human, or when the opt-in `delivery.refactorStage` checkpoint asks for a behaviour-preserving CRAP/duplication pass after the suite is green.",
-      "policyCapsuleBullets": 12,
-      "allowedTools": null,
-      "vendor": null
-    },
-    {
-      "name": "debugging-and-error-recovery",
-      "tier": "core",
-      "category": "core",
-      "path": ".agents/skills/core/debugging-and-error-recovery/SKILL.md",
-      "description": "Guides systematic root-cause debugging. Use when tests fail, builds break, behavior doesn't match expectations, or you encounter any unexpected error. Use when you need a systematic approach to finding and fixing the root cause rather than guessing.",
-      "policyCapsuleBullets": 9,
+      "policyCapsuleBullets": 7,
       "allowedTools": null,
       "vendor": null
     },
@@ -48,7 +28,7 @@
       "category": "core",
       "path": ".agents/skills/core/documentation-and-adrs/SKILL.md",
       "description": "Records decisions and documentation. Use when making architectural decisions, changing public APIs, shipping features, or when you need to record context that future engineers and agents will need to understand the codebase.",
-      "policyCapsuleBullets": 9,
+      "policyCapsuleBullets": 6,
       "allowedTools": null,
       "vendor": null
     },
@@ -57,21 +37,11 @@
       "tier": "core",
       "category": "core",
       "path": ".agents/skills/core/gates-and-baselines/SKILL.md",
-      "description": "Governs quality gates and the unified-baseline snapshots. Use when authoring a baseline refresh commit (CRAP, maintainability, dead-exports, lighthouse), when setting up or modifying CI quality gates, or when introducing a new gate that asserts on pre-existing state without turning the integration branch red.",
-      "policyCapsuleBullets": 9,
+      "description": "Governs quality gates and the unified-baseline snapshots. Use when authoring a baseline refresh commit (coverage, CRAP, maintainability, duplication, dead-exports), when setting up or modifying CI quality gates, or when introducing a new gate that asserts on pre-existing state without turning the base branch red.",
+      "policyCapsuleBullets": 10,
       "allowedTools": ["Read", "Write", "Bash"],
       "vendor": null
     },
-    {
-      "name": "git-workflow-and-versioning",
-      "tier": "core",
-      "category": "core",
-      "path": ".agents/skills/core/git-workflow-and-versioning/SKILL.md",
-      "description": "Structures git workflow practices. Use when making any code change. Use when committing, branching, resolving conflicts, or when you need to organize work across multiple parallel streams.",
-      "policyCapsuleBullets": 6,
-      "allowedTools": null,
-      "vendor": null
-    },
     {
       "name": "idea-refinement",
       "tier": "core",
@@ -82,16 +52,6 @@
       "allowedTools": null,
       "vendor": null
     },
-    {
-      "name": "qa-coverage-mapping",
-      "tier": "core",
-      "category": "core",
-      "path": ".agents/skills/core/qa-coverage-mapping/SKILL.md",
-      "description": "Map a quality finding to a per-tier coverage verdict (unit / contract / acceptance) aligned to `.agents/rules/testing-standards.md`. Use when a finding points at a symbol or surface and you need to know which test tiers already cover it and which are missing, so remediation lands the right tier. Delegates the verdict to the deterministic `lib/qa/coverage-verdict.js#coverageVerdict` helper.",
-      "policyCapsuleBullets": 7,
-      "allowedTools": ["Read", "Bash"],
-      "vendor": null
-    },
     {
       "name": "scope-triage",
       "tier": "core",
@@ -107,7 +67,7 @@
       "tier": "core",
       "category": "core",
       "path": ".agents/skills/core/security-and-hardening/SKILL.md",
-      "description": "Hardens code against vulnerabilities. Use when handling user input, authentication, data storage, or external integrations. The non-negotiable security MUSTs live in `.agents/rules/security-baseline.md`; this skill shows how to apply them with process guidance, an audit-triage tree, and a review checklist.",
+      "description": "Hardens code against vulnerabilities. Use when handling user input, authentication, data storage, or external integrations. The non-negotiable security MUSTs live in `.agents/rules/security-baseline.md`; this skill shows how to apply them, with the project's surfacing and validation-response process.",
       "policyCapsuleBullets": 6,
       "allowedTools": null,
       "vendor": null
@@ -128,7 +88,7 @@
       "category": "qa",
       "path": ".agents/skills/stack/qa/playwright-bdd/SKILL.md",
       "description": "Wires Gherkin `.feature` files to Playwright via the `playwright-bdd` library. Use when running BDD scenarios on a Playwright runtime — pairs with the `gherkin-authoring` skill (scenario prose) and the `playwright` skill (browser conventions). Drives execution by tag expression with trace-first debugging and Playwright-native sharding.",
-      "policyCapsuleBullets": 8,
+      "policyCapsuleBullets": 9,
       "allowedTools": null,
       "vendor": "playwright"
     },
@@ -142,35 +102,15 @@
       "allowedTools": null,
       "vendor": "playwright"
     },
-    {
-      "name": "qa-explore-driving",
-      "tier": "stack",
-      "category": "qa",
-      "path": ".agents/skills/stack/qa/qa-explore-driving/SKILL.md",
-      "description": "Conventions for agent-driven exploratory QA driving — how the agent itself drives a surface during `/qa-explore` (agent-led), as opposed to the human-led `/qa-assist`. Use when the agent explores a running app via the browser MCP (navigation-first, the default) — including authenticated deployed surfaces reached through the resolved environment's sign-in seam — or walks a static surface (the documented interim where no seam resolves), under a strictly read-only capture invariant. The exploration procedure lives in `.agents/workflows/qa-explore.md`; this skill is the driving-conventions reference it leans on.",
-      "policyCapsuleBullets": 9,
-      "allowedTools": null,
-      "vendor": null
-    },
     {
       "name": "qa-harness",
       "tier": "stack",
       "category": "qa",
       "path": ".agents/skills/stack/qa/qa-harness/SKILL.md",
-      "description": "Conventions for the agent-driven QA harness that drives Gherkin scenarios through a real browser. Use when executing `/qa-run` or instrumenting a live surface — covers navigation-first execution, per-surface console and network capture, design-token visual checks, and the framework-generic heuristic cards for turning signal into findings. The harness procedure lives in `.agents/workflows/qa-run.md`; this skill is the conventions reference it leans on.",
-      "policyCapsuleBullets": 7,
+      "description": "Conventions for agent-driven QA driving — the one driving-conventions reference behind both `/qa-run` (the known-scenario sweep through a real browser) and `/qa-explore` (agent-led exploratory driving). Use when instrumenting a live surface — covers navigation-first execution, per-surface console and network capture, design-token visual checks, the `F#` finding shape, per-environment resolution, and static driving as the documented interim. The run procedures live in `.agents/workflows/qa-run.md` and `.agents/workflows/qa-explore.md`; this skill is the conventions reference they lean on.",
+      "policyCapsuleBullets": 11,
       "allowedTools": null,
       "vendor": null
-    },
-    {
-      "name": "vitest",
-      "tier": "stack",
-      "category": "qa",
-      "path": ".agents/skills/stack/qa/vitest/SKILL.md",
-      "description": "Writes fast, isolated unit and integration tests with Vitest. Use when each test must run on file-save without shared state — `vi.mock()` for external deps, `vi.spyOn()` for call monitoring, AAA structure, and edge-case coverage for null/undefined/boundary inputs.",
-      "policyCapsuleBullets": 8,
-      "allowedTools": null,
-      "vendor": "vitest"
     }
   ]
 }

package/.agents/skills/stack/qa/gherkin-authoring/SKILL.md

@@ -17,7 +17,7 @@ description:
 - Never assert on HTTP status codes, SQL state, DOM selectors, URLs, or JSON payloads inside `.feature` prose — push those to contract tests.
 - Tag every Scenario or Outline with exactly one canonical `@domain-*` tag and the appropriate risk/platform tags from the gherkin-standards taxonomy.
 - Use `Background` only when every scenario in the file genuinely shares the precondition with no per-scenario variation.
-- Reuse existing step definitions: grep the steps tree for the verb stem before authoring a new step.
+- Complete the step-reuse sequence in [`gherkin-standards.md` § Step Reuse](../../../../rules/gherkin-standards.md#step-reuse--grep-before-you-write) before authoring any scenario text; that rule is the only home for it.
 - Author one scenario per PRD acceptance criterion; for bounded matrices, use a Scenario Outline with ≤12 Examples rows.
 - Use third-person present-tense, role-qualified actors (`the billing-admin`), never first person.
 
@@ -29,16 +29,10 @@ the rule for the **what**.
 
 ## Long-form reference — read on demand
 
-The worked authoring material — canonical Given/When/Then phrasing, the
-one-AC-to-one-scenario translation walkthrough, Background-vs-Given and
-Outline-vs-multi-scenario decisions, the step-definition library layout and
-reuse/deprecation workflow, and the pre-PR authoring checklist — lives in the
-on-demand sibling [`reference.md`](reference.md). Open a section only when the
-task engages it.
+The step-definition library layout and the pre-PR authoring checklist live in
+the on-demand sibling [`reference.md`](reference.md). Open a section only when
+the task engages it.
 
-- [Canonical Given / When / Then Phrasing](reference.md#canonical-given--when--then-phrasing)
-- [Translating PRD Acceptance Criteria to Scenarios](reference.md#translating-prd-acceptance-criteria-to-scenarios)
-- [Background vs. Given, Outline vs. Multi-Scenario](reference.md#background-vs-given-outline-vs-multi-scenario)
 - [Step-Definition Library Structure](reference.md#step-definition-library-structure)
 - [Authoring Checklist](reference.md#authoring-checklist)