@vyuhlabs/dxkit 2.9.1 → 2.9.3

package/templates/.claude/skills/dxkit-allowlist/SKILL.md

@@ -0,0 +1,107 @@
+---
+name: dxkit-allowlist
+description: Manage the dxkit allowlist over its whole lifecycle — list, inspect, audit (including orphaned entries after a re-baseline), remove stale entries, prune expired ones, and export Snyk-originated suppressions to a .snyk policy. Use when the user says "review our allowlist", "what suppressions do we have", "this allowlist entry is stale", "remove this fingerprint", "the allowlist drifted after re-baselining", "audit our accepted-risk entries", or "push our Snyk ignores back to Snyk". For the fix-vs-suppress DECISION and adding a new entry, defer to dxkit-action.
+---
+
+# dxkit-allowlist
+
+The allowlist is dxkit's per-finding suppression surface: a reviewed finding that the team has categorized (`false-positive`, `test-fixture`, `mitigated-externally`, `accepted-risk`, `deferred`) with a reason, so the guardrail lets it pass on future runs. It's the single source of truth across every scanner — native semgrep/gitleaks and ingested Snyk Code / CodeQL findings alike, all keyed on one fingerprint.
+
+This skill manages the allowlist's **lifecycle**: reviewing what's there, keeping it honest, and propagating decisions outward. For the upstream question — *should this be fixed instead of suppressed, and how do I add an entry* — that decision and the `add` path live in **dxkit-action**. Fix first; suppress second.
+
+## The lifecycle at a glance
+
+```
+add ──▶ list / show ──▶ audit ──▶ { renew | remove | prune } ──▶ export --snyk
+(dxkit-action)  inspect    keep honest   clean up                 propagate to Snyk
+```
+
+## Review what's suppressed
+
+```bash
+npx vyuh-dxkit allowlist list                # every entry (text); --json for structured
+npx vyuh-dxkit allowlist show <fingerprint>  # one entry's full detail
+```
+
+Reading is always safe — no mutation. Use these to brief the team on the overall suppression posture before a release or audit.
+
+## Audit — keep the allowlist honest
+
+```bash
+npx vyuh-dxkit allowlist audit                      # expired / soon-to-expire / missing-rationale
+npx vyuh-dxkit allowlist audit --soon-days=30       # widen the soon-to-expire window
+npx vyuh-dxkit allowlist audit --against-baseline   # ALSO flag orphaned entries
+```
+
+`audit` partitions entries into actionable buckets:
+
+- **expired** — past their `expiresAt`. The suppression no longer applies; the finding will re-flag on the next scan. Prune or renew.
+- **soon-to-expire** — within the window (default 14 days). `accepted-risk` / `deferred` entries approaching expiry should be re-justified or removed.
+- **missing-rationale** — no reason on the entry (only happens in sanitized mode when the gitignored reasons sidecar is absent).
+- **orphaned** — *only with `--against-baseline`*. The entry's fingerprint matches no finding in the committed baseline.
+
+### Orphaned entries — flag, never bulk-remove
+
+`--against-baseline` reads the committed baseline and reports entries whose fingerprint isn't present in the current finding set (it counts both each finding's own fingerprint and any cross-tool fingerprints absorbed into it, so an entry keyed on a collapsed contributor is *not* falsely flagged).
+
+**An orphan is not automatically stale.** Two things produce orphans:
+
+1. **The finding is genuinely gone** (fixed, file deleted) → the entry is dead weight; remove it.
+2. **Re-baselining churned the fingerprint** — semgrep is nondeterministic run-to-run, and cross-tool dedup can shift which tool's fingerprint represents a merged finding. The suppressed finding may still exist intermittently. Removing the entry would let it block a future PR.
+
+So treat the orphaned bucket as a **review queue**: confirm each finding is truly gone (re-run the analyzer and check the fingerprint is absent), *then* remove. Never script a bulk-remove of the orphaned set.
+
+## Remove a single entry
+
+```bash
+npx vyuh-dxkit allowlist remove <fingerprint>
+```
+
+Deletes one file-level entry. Use this for a confirmed-orphaned entry, or any stale-but-unexpired entry (which `prune` won't touch — `prune` removes only *expired* entries). No more hand-editing `.dxkit/allowlist.json`.
+
+## Prune expired entries
+
+```bash
+npx vyuh-dxkit allowlist prune --dry-run   # preview what would go
+npx vyuh-dxkit allowlist prune             # remove all expired entries
+```
+
+`prune` is the bulk counterpart to `remove`, scoped to expired entries only (those are unambiguously inactive). Run it periodically; renew anything still relevant before pruning.
+
+## The re-baseline → re-point flow (self-serve)
+
+After a baseline refresh, some fingerprints churn and a few valid suppressions orphan. The self-serve recovery:
+
+```bash
+npx vyuh-dxkit allowlist audit --against-baseline   # 1. discover orphans
+# 2. for each orphan: re-run the analyzer, confirm the finding is truly gone
+npx vyuh-dxkit vulnerabilities                      #    (grep output for the fingerprint)
+npx vyuh-dxkit allowlist remove <fingerprint>       # 3a. gone → remove
+npx vyuh-dxkit allowlist add --fingerprint=<new> …  # 3b. churned → re-point to the new fp (see dxkit-action)
+```
+
+> **Refresh the baseline in CI, not on your laptop.** A local `baseline create --force` bakes your machine's scanner versions into the committed baseline, which produces spurious tooling-drift warnings and phantom "resolved" findings on the next PR — and *causes* exactly this fingerprint churn. Use the bundled `dxkit-baseline-refresh` workflow (workflow_dispatch) so the canonical baseline is captured with CI's scanner versions. See **dxkit-ingest** for the refresh-job pattern.
+
+## Export to Snyk — propagate suppressions outward
+
+```bash
+npx vyuh-dxkit allowlist export --snyk            # writes ./.snyk
+npx vyuh-dxkit allowlist export --snyk --out=path/to/.snyk
+```
+
+When the team allowlists a **Snyk-originated** finding (one ingested via `dxkit-ingest`, `tool: snyk-code`), the decision lives only in dxkit by default — Snyk's own gate (`snyk code test`, the Snyk UI) still reports it as open. `export --snyk` closes that loop: it writes a `.snyk` policy ignoring every Snyk Code finding that maps to an *active* allowlist entry, keyed on the Snyk rule id + path, carrying the entry's reason + expiry. Expired entries are skipped; native semgrep/gitleaks findings don't export (no Snyk equivalent).
+
+This is the outbound mirror of the inbound sync dxkit already does (it honors Snyk's SARIF `result.suppressions` at ingest). The two are round-trip stable — an exported ignore re-read from Snyk's SARIF is suppressed, not double-counted.
+
+**Prerequisite:** Snyk Code (SAST) honors `.snyk` ignores only when the org has Snyk's "consistent ignores" feature enabled; SCA/dependency ignores are standard. Commit the `.snyk` so it applies in CI. It's opt-in — if dxkit is the only gate, you don't need it.
+
+## Stale inline annotations
+
+Inline `dxkit-allow:` annotations are a different surface (source-anchored, managed by `dxkit-action`'s `add` path). If the underlying finding is fixed but the annotation lingers, the next scan emits a `stale-allow` finding pointing at the orphaned comment. The fix is always to delete the comment — dxkit refuses to allowlist a stale-allow.
+
+## Hand-offs
+
+- For the **fix-vs-suppress decision** and **adding** a new entry (inline or file-level, the typed-category table, the canonical `add` path) → **dxkit-action**.
+- For **ingesting** Snyk/CodeQL findings in the first place, and the **CI baseline/deep-SAST refresh** jobs → **dxkit-ingest**.
+- For **ignore-file** (`.dxkit-ignore`) edits and policy tuning → **dxkit-config**.
+- For a **broken install** (guardrail not firing, command not found) → **dxkit-fix**.

package/templates/.claude/skills/dxkit-config/SKILL.md

@@ -155,7 +155,7 @@ A `npx vyuh-dxkit doctor` or `tools list` showing tools as missing **when they a
 1. Create / edit `.dxkit/tools.json` and add that directory to `probePaths`.
 2. Re-run `npx vyuh-dxkit tools list` — the tool should now show as available.
 3. If the user wants dxkit to *install* tools into a specific dir, set `installDir`, then `npx vyuh-dxkit tools install`.
-4. Regenerate the baseline so it reflects the now-available scanners: `npx vyuh-dxkit baseline create --force`.
+4. Regenerate the baseline so it reflects the now-available scanners — through the `dxkit-baseline-refresh` CI workflow, not a local `baseline create --force` (see "What NOT to do" for why).
 
 ## Workflow
 
@@ -163,11 +163,11 @@ When the user asks for a config change:
 
 1. Identify which file owns the concern (path exclusion → `.dxkit-ignore`; severity routing → `.dxkit/policy.json`; detection override → `.npx vyuh-dxkit.json`).
 2. Open the file, propose the edit, confirm.
-3. After writing, run `npx vyuh-dxkit baseline create --force` if exclusions changed (so the baseline doesn't carry stale findings from the now-excluded paths).
-4. Commit both: the config file + the regenerated baseline.
+3. If exclusions changed, refresh the baseline so it doesn't carry stale findings from the now-excluded paths — via the `dxkit-baseline-refresh` CI workflow, not a local `baseline create --force` (see "What NOT to do").
+4. Commit the config file; let CI refresh + commit the baseline.
 
 ## What NOT to do
 
 - Don't edit `.dxkit/cache/` or `.dxkit/reports/` — they're regenerated on every run (gitignored).
-- Don't manually mutate `.dxkit/baselines/main.json` — use `baseline create --force` to regenerate.
+- Don't manually mutate `.dxkit/baselines/main.json` — regenerate it. And regenerate it in CI (the `dxkit-baseline-refresh` workflow), NOT with a local `baseline create --force`: a local refresh bakes your machine's scanner versions into the committed baseline, so the next PR's guardrail emits spurious `TOOLING-DRIFT` warnings and phantom "resolved" findings when CI's versions differ. A local `--force` is fine only for the first capture or a throwaway experiment.
 - Don't add `.dxkit/` to `.dxkit-ignore` — dxkit itself doesn't scan its own outputs.

package/templates/.claude/skills/dxkit-docs/SKILL.md

@@ -146,3 +146,5 @@ npx vyuh-dxkit guardrail check
   should leave the new surface documented).
 - Slop findings outside docs (AI-generated code prose, CHANGELOG slop) →
   `dxkit-action`'s slop recipe.
+- Closing test gaps / raising the Tests score (the sibling generator skill) →
+  `dxkit-test`.

package/templates/.claude/skills/dxkit-feature/SKILL.md

@@ -154,8 +154,7 @@ Exit 0 = the feature added no net-new regressions. Exit 1 = something new
 appeared — **a finding you introduced.** Address it before pushing:
 
 - A real finding in your new code → fix it now (hand off to `dxkit-action`
-  for the fix recipes — secret rotation, dep upgrade, writing the missing
-  test, etc.).
+  for the fix recipes — secret rotation, dep upgrade, SAST, etc.).
 - A genuine false positive / intentional pattern → allowlist with a typed
   category + reason (see `dxkit-action`'s allowlisting section). Fix first;
   allowlist second.
@@ -163,6 +162,15 @@ appeared — **a finding you introduced.** Address it before pushing:
 The feature isn't done when it works — it's done when it works **and** the
 guardrail is green.
 
+### Offer to test the new surface
+
+A new feature is the most common source of a fresh test gap. When step [5]'s
+`test-gaps` shows the code you just added is untested — especially if it has
+callers (a non-trivial blast radius) — **offer to write tests for it, and on
+the user's confirmation hand off to `dxkit-test`** to write them grounded in
+the behavior you just built. Keep it an offer: don't auto-generate tests the
+user didn't ask for, but don't let a new untested surface ship silently either.
+
 ## [6] Baseline decision
 
 | Scenario | Action |
@@ -180,7 +188,10 @@ own feature introduced.
 ## Hand-offs
 
 - A finding the guardrail blocked needs fixing → `dxkit-action` (the fix-loop
-  recipes for secrets, dep-vulns, SAST, test gaps).
+  recipes for secrets, dep-vulns, SAST).
+- Writing tests for the new (or any untested) surface → `dxkit-test`.
+- Raising the PR once the feature is built + green → `dxkit-pr` (title + body
+  from the diff, dxkit signals, reviewer checklist).
 - Re-running reports between iterations → `dxkit-reports`.
 - Ignore-file / config edits as part of the feature → `dxkit-config`.
 - Hook problems on the verify push → `dxkit-hooks`.

package/templates/.claude/skills/dxkit-fix/SKILL.md

@@ -91,7 +91,7 @@ If doctor flags a tool (git, dotnet, node, npm, a scanner) as missing but the cu
 2. Add that directory to `.dxkit/tools.json` `probePaths` (hand off to **dxkit-config**, which documents the file).
 3. Re-run `npx vyuh-dxkit doctor` to confirm it now resolves.
 
-This matters: an undetected scanner means `baseline create` silently captured ZERO findings for that tool's category — re-baseline (`baseline create --force`) once detection is fixed.
+This matters: an undetected scanner means `baseline create` silently captured ZERO findings for that tool's category — refresh the baseline once detection is fixed. Do that through the `dxkit-baseline-refresh` CI workflow, not a local `baseline create --force`: a local refresh records your machine's scanner versions in the committed baseline, so the next PR's guardrail emits spurious `TOOLING-DRIFT` warnings and phantom "resolved" findings when CI's versions differ.
 
 ## Capturing the FIRST baseline — be deliberate
 

package/templates/.claude/skills/dxkit-ingest/SKILL.md

@@ -88,6 +88,8 @@ Compiled languages (Java, C#, Kotlin, Go) need a working build for CodeQL extrac
 
 Ingested findings flow through the same aggregate as native findings, so they appear in the vulnerability report (with the engine as the `tool`), get a stable fingerprint, dedupe against any overlapping semgrep finding, and — with `--graph-context` — carry the enclosing symbol + blast radius the agent needs to fix safely. That graph enrichment is the part the source engine's own autofix doesn't have.
 
+> **Step [4] belongs in CI, not on your laptop.** Adding ingested findings changes the finding set, so the baseline must be refreshed to pick them up. Do that through the bundled `dxkit-baseline-refresh` workflow (workflow_dispatch / post-merge), NOT a local `baseline create --force`. A local refresh bakes your machine's scanner versions into the committed baseline; when they differ from CI's, the next PR gets spurious `TOOLING-DRIFT` warnings and phantom "resolved" findings. Refresh the snapshot AND the baseline from CI so both are captured with CI's tool versions.
+
 ## Keeping it fresh (CI)
 
 Add a scheduled refresh (mirrors `dxkit-baseline-refresh`): a CI job with the `SNYK_TOKEN` secret runs `ingest --from-snyk` and commits the updated snapshot. The bundled `--with-deep-sast-refresh` workflow (`workflow_dispatch`) does exactly this; its `method` input picks `api` (Enterprise, quota-free) or `cli` (free/team, one test per run). The ingested findings are a point-in-time snapshot of the engine's last scan — re-ingest after the engine re-scans.

package/templates/.claude/skills/dxkit-init/SKILL.md

@@ -21,7 +21,7 @@ Ask the user what they want, then pick the right invocation:
 
 | Flag | What it ships | Default under `--full`? |
 |---|---|---|
-| `--with-dxkit-agents` | The 6 dxkit-* skills + AGENTS.md + CLAUDE.md shim | Yes |
+| `--with-dxkit-agents` | The dxkit-* skills + AGENTS.md + CLAUDE.md shim | Yes |
 | `--with-hooks` | `.githooks/pre-push` + postinstall activation wire-up | Yes |
 | `--with-precommit-hook` | Adds `.githooks/pre-commit` (slow on large repos) | No (still opt-in) |
 | `--with-devcontainer` | `.devcontainer/devcontainer.json` (per-stack features) + post-create.sh | Yes |

package/templates/.claude/skills/dxkit-onboard/SKILL.md

@@ -82,7 +82,7 @@ Before running, ASK:
 
 Optional flags worth surfacing if the customer pushes back on "full":
 
-- `--with-dxkit-agents` — just the 8 dxkit-* skills (no hooks, no CI)
+- `--with-dxkit-agents` — just the dxkit-* skills (no hooks, no CI)
 - `--with-hooks --with-dxkit-agents` — skills + pre-push hook
 - `--with-precommit-hook` — also pre-commit (slow on large repos)
 
@@ -262,7 +262,7 @@ When in doubt, dxkit-onboard handles the full first-install journey and delegate
 ```
 ✓ Fresh dxkit install complete:
    • Binary: 2.5.X installed globally + project-local
-   • Scaffold: 8 dxkit-* skills, AGENTS.md, CLAUDE.md, devcontainer, hooks, CI workflows
+   • Scaffold: dxkit-* skills, AGENTS.md, CLAUDE.md, devcontainer, hooks, CI workflows
    • Doctor: 14/14 (Reports + Agent DX + Operational health)
    • Baseline: N findings locked in (or "skipped — you're triaging first")
    • Pre-commit: yes/no (your choice)

package/templates/.claude/skills/dxkit-pr/SKILL.md

@@ -0,0 +1,142 @@
+---
+name: dxkit-pr
+description: Open a pull request with a title + body grounded in the branch's real commits and diff — what changed, features implemented, findings fixed — plus a reviewer checklist and the dxkit guardrail/allowlist/score signals a reviewer needs. Use when the user says "raise a PR", "open a pull request", "create the PR", "write the PR description", or after dxkit-feature / dxkit-action finishes a change and it's ready to push for review.
+---
+
+# dxkit-pr
+
+This skill turns a finished branch into a **reviewable** pull request: a title
+and body grounded in what actually changed (not a generic template), and a
+checklist that guides the reviewer through what to verify. It's the natural
+close of `dxkit-feature` (built something) and `dxkit-action` (fixed findings) —
+both hand off here when the work is ready for review.
+
+A good PR description is written from the diff, not from memory. This skill
+reads the branch, summarizes it honestly, and attaches the dxkit signals
+(guardrail verdict, allowlist activity, score movement) a reviewer would
+otherwise have to reconstruct by hand.
+
+## The PR loop
+
+```
+[1] Survey      → branch vs base: commits, diff stat, files touched
+[2] Classify    → features / fixes / refactors / docs / findings closed
+[3] Signals     → guardrail verdict + allowlist activity + score deltas
+[4] Draft       → title + body grounded in [1]–[3] + a reviewer checklist
+[5] Confirm     → show the user the draft; open with `gh pr create` on yes
+```
+
+Don't skip [5]. A PR is outward-facing — show the draft and get a yes before
+opening it.
+
+## [1] Survey — read the branch, don't guess
+
+```bash
+git fetch origin
+BASE=origin/main                      # or the repo's default branch
+git log --oneline $BASE..HEAD         # every commit on this branch
+git diff --stat $BASE...HEAD          # files + churn
+git diff $BASE...HEAD                 # the actual change, when you need detail
+```
+
+Read the commit messages first — on a well-kept branch they already narrate the
+work. Use the diff to verify and fill gaps, not to re-derive everything.
+
+## [2] Classify — group the change for a reviewer
+
+Sort the commits/diff into the buckets a reviewer cares about:
+
+- **Features** — new capability, with the entry point / surface it adds.
+- **Fixes** — bugs or findings closed (name the finding if it came from a dxkit
+  report: rule, file, severity).
+- **Refactors** — behavior-preserving structure changes (flag these — they're
+  where "looks big, reads safe" lives).
+- **Docs / tests / chore** — supporting changes.
+
+Lead the body with the *why* (the problem) and the *what* (the approach), then
+the bucketed change list. Keep it proportional — a one-commit fix gets a short
+body; a multi-commit feature gets sections.
+
+## [3] Signals — attach what dxkit knows
+
+Run the guardrail so the PR states its own verdict, and surface any suppression
+activity a reviewer must sign off on:
+
+```bash
+npx vyuh-dxkit guardrail check                       # PASS/FAIL the PR will get in CI
+npx vyuh-dxkit allowlist audit                        # any new/expiring suppressions?
+npx vyuh-dxkit health --detailed | head -40           # score movement, if relevant
+```
+
+Put in the body:
+
+- **Guardrail verdict** — PASS, or FAIL with the net-new findings named (a
+  reviewer should know before CI tells them).
+- **Allowlist activity** — any suppression added on this branch, with its
+  category + reason + expiry, called out for explicit review (suppressions are
+  the highest-trust thing a reviewer approves).
+- **Score deltas** — only when the change targeted a dimension (e.g. "Tests
+  62 → 71 after closing the auth gaps"). Don't pad with unchanged scores.
+
+## [4] Draft — title, body, reviewer checklist
+
+**Title** — imperative, scoped, specific. `feat(auth): add refresh-token
+rotation`, not `Updates`. Match the repo's existing PR/commit convention
+(check `git log` on the base branch).
+
+**Body** — structure:
+
+```markdown
+## What & why
+<the problem this solves, in 1–3 sentences>
+
+## Changes
+- **Feature:** …
+- **Fix:** … (closes <finding/issue>)
+- **Refactor:** … (behavior-preserving)
+
+## dxkit signals
+- Guardrail: ✅ PASS  (or ❌ + the net-new findings)
+- Allowlist: <new suppressions + reason + expiry, or "no changes">
+- Scores: <dimension deltas, if the change targeted one>
+
+## Reviewer checklist
+- [ ] Change matches the description; scope isn't broader than stated
+- [ ] <feature>: behavior verified (how to exercise it)
+- [ ] Refactors are behavior-preserving (no silent semantic change)
+- [ ] New/changed code is tested; test gaps addressed or noted
+- [ ] Any allowlist suppression is justified (category + reason + expiry)
+- [ ] No secrets/keys/tokens in the diff
+- [ ] Docs updated if behavior or interfaces changed
+```
+
+Tailor the checklist to the *actual* change — drop rows that don't apply, add
+specific ones (a migration step, a config flag to set, a caller to re-test from
+the blast radius). A generic checklist is noise; a targeted one guides the review.
+
+## [5] Confirm + open
+
+Show the user the full draft (title + body) and confirm. On yes:
+
+```bash
+git push -u origin HEAD                # if not already pushed
+gh pr create --base main --title "<title>" --body "<body>"
+```
+
+If `gh` isn't authenticated, print the title + body for the user to paste, and
+point them at `gh auth login`. Never open a PR the user hasn't seen.
+
+## Scope — what NOT to do
+
+- Don't invent changes the diff doesn't show, or claim a finding is fixed
+  without having verified it (re-run the analyzer first — see `dxkit-action`).
+- Don't open the PR before the guardrail is green, unless the user explicitly
+  wants a draft PR for early review — and then mark it draft and say so in the body.
+- Don't restate every commit verbatim — synthesize. The commit log is one click
+  away; the body's job is the narrative + the review guidance.
+
+## Hand-offs
+
+- A guardrail FAIL blocking the PR → `dxkit-action` to fix the net-new findings first.
+- Writing the feature being PR'd → `dxkit-feature`; closing test gaps it opened → `dxkit-test`.
+- Branch-protection / required-check setup so the PR is actually gated → `dxkit-hooks` / repo settings.

package/templates/.claude/skills/dxkit-reports/SKILL.md

@@ -103,7 +103,7 @@ Surface those three when summarizing a dep-vuln finding. The detailed JSON has t
 
 ## When the user wants to ACT on findings
 
-Hand off to the `dxkit-action` skill — that's the workflow for prioritizing + fixing + re-baselining. This skill stops at "here's what's wrong."
+Hand off to the `dxkit-action` skill — that's the workflow for prioritizing + fixing + re-baselining. This skill stops at "here's what's wrong." For a dimension-focused push, hand to the specialist generator skills instead: **dxkit-test** to close test-gaps / raise the Tests score, **dxkit-docs** to write missing documentation.
 
 ## Troubleshooting
 

package/templates/.claude/skills/dxkit-test/SKILL.md

@@ -0,0 +1,130 @@
+---
+name: dxkit-test
+description: Write the tests a repo is missing — read the test-gaps report (blast-radius-weighted), orient on what the untested code actually does via the graph, then write real tests that close the highest-risk gaps and move the Tests score without coverage theater. Use when the user says "write tests", "add tests for this module", "improve the test coverage / Tests score", "close the test gaps", "cover the untested files", or after a health report flags Testing.
+---
+
+# dxkit-test
+
+This skill closes the gap `dxkit-action` doesn't: it **writes** the missing
+tests rather than fixing flagged findings. It is the testing mirror of
+`dxkit-docs` — same shape, different dimension. It's built around one hard
+constraint: a test that doesn't actually exercise behavior (an empty `expect(true)`,
+a snapshot of nothing, a call with no assertion) raises the coverage number
+while proving nothing. The whole point of this skill is tests that are
+**grounded in real behavior** and **catch real regressions** — not coverage
+theater.
+
+## The testing loop
+
+```
+[1] Read the gap   → test-gaps: the blast-radius-weighted untested worklist
+[2] Orient         → graph: what the file does, who depends on it, what to assert
+[3] Generate       → write real tests in the repo's framework + patterns
+[4] Verify         → run the suite + coverage; Tests up, nothing red
+[5] Guardrail      → guardrail check before pushing
+```
+
+Don't skip [2] or [4]. [2] is what makes the tests meaningful; [4] is what
+proves they pass and the coverage actually moved.
+
+## [1] Read the gap — what's actually untested, worst-first
+
+Run the test-gaps report with graph context so the worklist is ranked by
+**blast radius** (how many files depend on each untested file), not just size:
+
+```bash
+npx vyuh-dxkit test-gaps --detailed --graph-context
+npx vyuh-dxkit test-gaps --detailed --graph-context --json | jq '.actions, .gaps[0:10]'
+```
+
+The report partitions untested files into CRITICAL / HIGH / MEDIUM / LOW risk
+tiers, and **within each tier the most-depended-on files surface first** (the
+`Graph context` column shows `role · N caller files`). Work top-down: a
+30-caller untested file is a bigger liability than a 500-line leaf nothing
+calls. The `actions` array names the top-K per tier with projected
+score uplift — that's your queue.
+
+A `blast radius n/a` cell means graphify couldn't resolve that language's call
+graph (C# is the known case) — treat it as *unknown*, not "no callers," and
+fall back to the file's role + size to judge its risk.
+
+## [2] Orient — understand the behavior before you assert on it
+
+A test is only as good as your understanding of what the code should do.
+Before writing, learn the real shape from the graph (cheap, structural):
+
+```bash
+npx vyuh-dxkit context src/payments/refund.ts        # the file's symbols, callers, callees
+npx vyuh-dxkit explore file src/payments/refund.ts   # its structural neighborhood
+```
+
+Use it to decide three things:
+
+- **What the public contract is** — the exported symbols are what callers rely
+  on; test those, not private helpers.
+- **What the callers expect** — the caller files (blast radius) tell you the
+  real usage shapes to cover, including the edge cases they pass.
+- **What's risky** — error paths, branching, boundary conditions. Then **read
+  the actual code** — the graph points you at it; it doesn't replace reading
+  it.
+
+## [3] Generate — real tests, the repo's way
+
+- **Match the existing framework + conventions.** Detect what the repo already
+  uses (vitest/jest, pytest, go test, JUnit, RSpec, …) from the existing test
+  files and `test-gaps` output — never introduce a new test framework. Copy the
+  nearest existing test's structure, naming, fixtures, and assertion style so
+  the new tests read like the repo's.
+- **Assert behavior, not existence.** Each test must exercise a real path and
+  assert a real outcome — return values, side effects, error handling,
+  boundaries. A test that calls a function and asserts nothing is slop.
+- **Cover the contract + the edges.** Happy path, the error/edge cases the
+  callers actually hit, and at least one boundary. Prioritize branches over
+  lines.
+- **Don't fake it.** No mocking the unit under test into a tautology; no
+  asserting on a stub you wrote. Mock external boundaries (network, clock,
+  fs) the way the repo already does.
+
+## [4] Verify — Tests up, suite green, no coverage theater
+
+```bash
+# Run the repo's real test command (from package.json / Makefile / etc.)
+<the repo's test command>            # e.g. npm test, pytest, go test ./...
+
+# Re-materialize coverage + the gap report
+npx vyuh-dxkit coverage              # runs the suite to produce real line coverage
+npx vyuh-dxkit test-gaps --detailed  # the targeted gap should be gone / downgraded
+```
+
+The work is done when:
+
+- The new tests **pass** (a failing or skipped test is not coverage).
+- The targeted file is no longer in the gap worklist (or dropped a risk tier).
+- `effectiveCoverage` rose from a real signal — prefer line-coverage truth
+  (`coverage`) over the filename-match heuristic; a name-matched 5-line test on
+  a 200-line file is exactly the theater this skill exists to avoid.
+
+## [5] Guardrail — before pushing
+
+```bash
+npx vyuh-dxkit guardrail check
+```
+
+Exit 0 = your new tests didn't introduce a net-new regression (e.g. a flaky
+test, a slop finding in test prose). Address anything it flags before pushing.
+
+## Scope — what NOT to test
+
+- Don't test auto-generated, vendored, or trivial pass-through code just to
+  move the number — credit comes from covering the files that carry risk.
+- Don't write tests you can't make pass; a `.skip` is a gap, not a closure.
+- Don't assert on implementation details that will break on every refactor —
+  test the contract, not the internals.
+
+## Hand-offs
+
+- Running / interpreting the health or test-gaps report → `dxkit-reports`.
+- A test gap surfaced as one finding inside a broader fix pass → `dxkit-action`.
+- Testing a feature you're building → `dxkit-feature` (it offers to hand the
+  new surface here once the feature lands).
+- Documentation gaps (the sibling generator skill) → `dxkit-docs`.

package/templates/.claude/skills/dxkit-update/SKILL.md

@@ -135,6 +135,10 @@ Iterate optional steps in the plan:
 | "Doctor says X is broken" | `dxkit-fix` |
 | "I want to run a report" | `dxkit-reports` |
 | "Fix these findings" | `dxkit-action` |
+| "Write the missing tests" | `dxkit-test` |
+| "Write the missing docs" | `dxkit-docs` |
+| "Manage / audit the allowlist" | `dxkit-allowlist` |
+| "Raise the PR" | `dxkit-pr` |
 | "Configure dxkit" | `dxkit-config` |
 | "Set up hooks" | `dxkit-hooks` |
 | "Explain dxkit" | `dxkit-learn` |

package/templates/AGENTS.md.template

@@ -12,14 +12,20 @@ For agent-specific config, see the editor-specific files alongside this one —
 
 This repo is managed by [`@vyuhlabs/dxkit`](https://github.com/vyuh-labs/dxkit). dxkit measures code health across 6 dimensions, captures a per-finding baseline, and gates PRs on net-new regressions.
 
-Six skills are installed under `.claude/skills/` (Claude Code auto-discovers via skill frontmatter):
+The `dxkit-*` skills are installed under `.claude/skills/` (Claude Code auto-discovers via skill frontmatter):
 
 - **dxkit-learn** — explains dxkit concepts (baselines, dimensions, scanners)
-- **dxkit-init** — interactive setup walkthrough
+- **dxkit-onboard** — fresh-install walkthrough; **dxkit-init** — interactive setup
 - **dxkit-config** — edit `.dxkit-ignore`, `.vyuh-dxkit.json`, policy
 - **dxkit-hooks** — install / troubleshoot git hooks
 - **dxkit-reports** — run analyzers, explain output, dashboard
-- **dxkit-action** — prioritize + fix + verify + re-baseline
+- **dxkit-action** — prioritize + fix + verify + re-baseline (scoped to one category if asked)
+- **dxkit-test** — write the missing tests to close gaps; **dxkit-docs** — write the missing docs
+- **dxkit-feature** — graph-guided net-new development
+- **dxkit-ingest** — bring external SAST (Snyk Code / CodeQL / SARIF) into dxkit
+- **dxkit-allowlist** — manage the suppression lifecycle (audit / remove / prune / export to Snyk)
+- **dxkit-pr** — open a PR with a diff-grounded body + reviewer checklist
+- **dxkit-update** — upgrade an existing install; **dxkit-fix** — repair a broken one
 
 Reach for the relevant skill when working in this repo. They wrap the `vyuh-dxkit` CLI with workflow guidance.
 

package/templates/CLAUDE.md.template

@@ -6,14 +6,20 @@ Whenever Claude Code starts a session in this repo, it reads BOTH files: this on
 
 ## dxkit skills
 
-Six dxkit-specific skills are installed under `.claude/skills/`. Claude Code auto-discovers them via their frontmatter `description` fields:
+The `dxkit-*` skills are installed under `.claude/skills/`. Claude Code auto-discovers them via their frontmatter `description` fields:
 
 - `dxkit-learn` — explain what dxkit does, what scores mean, what scanners run
-- `dxkit-init` — walk through `vyuh-dxkit init` flag choices
+- `dxkit-onboard` / `dxkit-init` — fresh-install walkthrough / `init` flag choices
 - `dxkit-config` — edit `.dxkit-ignore` / `.vyuh-dxkit.json` / policy
 - `dxkit-hooks` — install / troubleshoot git hooks
 - `dxkit-reports` — run analyzers + read output
-- `dxkit-action` — prioritize + fix + verify + re-baseline
+- `dxkit-action` — prioritize + fix + verify + re-baseline (scoped to one category if asked)
+- `dxkit-test` / `dxkit-docs` — write the missing tests / docs to move a dimension
+- `dxkit-feature` — graph-guided net-new development
+- `dxkit-ingest` — bring external SAST (Snyk Code / CodeQL / SARIF) into dxkit
+- `dxkit-allowlist` — manage the suppression lifecycle (audit / remove / prune / export)
+- `dxkit-pr` — open a PR with a diff-grounded body + reviewer checklist
+- `dxkit-update` / `dxkit-fix` — upgrade / repair an install
 
 When the user asks about dxkit concepts or wants to run an analyzer, reach for the matching skill before improvising.