@vyuhlabs/dxkit 2.9.2 → 2.9.4

package/dist/reviewers-cli.js

@@ -0,0 +1,263 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.parseCodeowners = parseCodeowners;
+exports.matchCodeowners = matchCodeowners;
+exports.buildSuggestions = buildSuggestions;
+exports.runReviewers = runReviewers;
+/**
+ * `vyuh-dxkit reviewers` — suggest reviewers for a change, grounded on the
+ * active-owner model (dev-report git history) rather than naive last-touch
+ * blame, blended with CODEOWNERS.
+ *
+ * The differentiation over a platform's built-in suggested-reviewers: the
+ * candidates are activity-weighted (recent, sustained work ranks highest),
+ * scoped to who is still active (a departed owner is never silently
+ * suggested), bot-free, exclude the change's own author, and carry a
+ * bus-factor signal. CODEOWNERS, when present, is authoritative and merged
+ * in. Output renders names + GitHub @handles — never raw emails.
+ *
+ * Pure helpers (`parseCodeowners`, `matchCodeowners`, `buildSuggestions`)
+ * are unit-tested without git; `runReviewers` is the IO entry point.
+ */
+const fs = __importStar(require("fs"));
+const path = __importStar(require("path"));
+const child_process_1 = require("child_process");
+const logger = __importStar(require("./logger"));
+const ownership_1 = require("./analyzers/developer/ownership");
+const gather_1 = require("./analyzers/developer/gather");
+/**
+ * Parse a CODEOWNERS file. Each non-comment line is `<pattern> <owner>...`.
+ * Returns rules in file order; CODEOWNERS semantics are "last matching rule
+ * wins," so callers iterate in reverse.
+ */
+function parseCodeowners(content) {
+    const rules = [];
+    for (const raw of content.split(/\r?\n/)) {
+        const line = raw.replace(/#.*$/, '').trim();
+        if (!line)
+            continue;
+        const parts = line.split(/\s+/);
+        const pattern = parts[0];
+        const owners = parts.slice(1).filter(Boolean);
+        if (pattern && owners.length > 0)
+            rules.push({ pattern, owners });
+    }
+    return rules;
+}
+/** Translate a CODEOWNERS pattern to a RegExp (subset: `*`, `**`, leading
+ *  `/`, trailing `/`). Good enough for the common cases; unmatched exotic
+ *  globs simply don't match (conservative — never over-claims ownership). */
+function patternToRegExp(pattern) {
+    let p = pattern;
+    const anchored = p.startsWith('/');
+    if (anchored)
+        p = p.slice(1);
+    const dirOnly = p.endsWith('/');
+    if (dirOnly)
+        p = p.slice(0, -1);
+    // Tokenize so `**` -> `.*` and `*` -> `[^/]*` without a fragile placeholder;
+    // every other regex-special char is escaped.
+    let body = '';
+    for (let i = 0; i < p.length; i++) {
+        const c = p[i];
+        if (c === '*') {
+            if (p[i + 1] === '*') {
+                body += '.*';
+                i++;
+            }
+            else {
+                body += '[^/]*';
+            }
+        }
+        else if (/[.+^${}()|[\]\\?]/.test(c)) {
+            body += '\\' + c;
+        }
+        else {
+            body += c;
+        }
+    }
+    const full = dirOnly ? `${body}/.*` : `${body}(?:/.*)?`;
+    return new RegExp(anchored ? `^${full}$` : `(?:^|/)${full}$`);
+}
+/** Owners for one file: the LAST matching CODEOWNERS rule wins. Empty when
+ *  no rule matches. */
+function matchCodeowners(rules, file) {
+    for (let i = rules.length - 1; i >= 0; i--) {
+        if (patternToRegExp(rules[i].pattern).test(file))
+            return [...rules[i].owners];
+    }
+    return [];
+}
+/**
+ * Compose the active-owner ranking with CODEOWNERS into a ranked reviewer
+ * list. Pure. CODEOWNERS owners are authoritative (always included, flagged);
+ * active git owners follow, ranked by score; inactive owners are dropped from
+ * the suggestion list (they're surfaced only via the `note` fallback).
+ */
+function buildSuggestions(ownership, opts = {}) {
+    const limit = opts.limit ?? 3;
+    const codeowners = dedupe(opts.codeowners ?? []);
+    const out = [];
+    const seen = new Set();
+    // 1. CODEOWNERS first — authoritative.
+    for (const token of codeowners) {
+        const handle = token.startsWith('@') ? token.slice(1) : undefined;
+        const key = token.toLowerCase();
+        if (seen.has(key))
+            continue;
+        seen.add(key);
+        out.push({
+            name: token,
+            ...(handle ? { handle } : {}),
+            active: true, // CODEOWNERS is a maintained, current declaration
+            isCodeowner: true,
+            reason: 'listed in CODEOWNERS for the touched paths',
+            score: Number.POSITIVE_INFINITY,
+        });
+    }
+    // 2. Active git owners, ranked.
+    const activeOwners = ownership.ranked.filter((o) => o.active);
+    for (const o of activeOwners) {
+        const handle = o.githubHandle;
+        const key = (handle ? `@${handle}` : o.name).toLowerCase();
+        if (seen.has(key))
+            continue;
+        seen.add(key);
+        out.push({
+            name: o.name,
+            ...(handle ? { handle } : {}),
+            active: true,
+            isCodeowner: false,
+            reason: `${o.commits} recent commit${o.commits === 1 ? '' : 's'} to the touched files (last ${o.lastTouched})`,
+            score: o.score,
+        });
+    }
+    const reviewers = out.slice(0, limit);
+    let note;
+    if (activeOwners.length === 0 && codeowners.length === 0) {
+        note =
+            ownership.ranked.length > 0
+                ? 'Every contributor who has touched these files is inactive — no current owner to suggest. Route by current team ownership.'
+                : 'No git history or CODEOWNERS for the touched files — no reviewer signal.';
+    }
+    else if (activeOwners.length === 0) {
+        note = 'Original authors are inactive — suggesting by CODEOWNERS only.';
+    }
+    return {
+        touchedFiles: [],
+        reviewers,
+        busFactor: ownership.busFactor,
+        ...(note ? { note } : {}),
+    };
+}
+function dedupe(xs) {
+    const seen = new Set();
+    const out = [];
+    for (const x of xs) {
+        const k = x.toLowerCase();
+        if (!seen.has(k)) {
+            seen.add(k);
+            out.push(x);
+        }
+    }
+    return out;
+}
+function gitOut(cmd, cwd) {
+    try {
+        return (0, child_process_1.execSync)(cmd, { cwd, encoding: 'utf8', stdio: ['ignore', 'pipe', 'ignore'] }).trim();
+    }
+    catch {
+        return '';
+    }
+}
+function touchedFiles(cwd, opts) {
+    if (opts.staged) {
+        return gitOut('git diff --cached --name-only', cwd).split('\n').filter(Boolean);
+    }
+    const base = opts.base || gitOut('git rev-parse --abbrev-ref origin/HEAD', cwd) || 'origin/main';
+    const out = gitOut(`git diff --name-only ${base}...HEAD`, cwd);
+    return out.split('\n').filter(Boolean);
+}
+function readCodeowners(cwd) {
+    for (const rel of ['.github/CODEOWNERS', 'CODEOWNERS', 'docs/CODEOWNERS']) {
+        const p = path.join(cwd, rel);
+        if (fs.existsSync(p))
+            return parseCodeowners(fs.readFileSync(p, 'utf8'));
+    }
+    return [];
+}
+function runReviewers(cwd, opts) {
+    const files = touchedFiles(cwd, opts);
+    if (files.length === 0) {
+        logger.info('No changed files detected (pass --base <ref> or --staged). Nothing to suggest.');
+        return;
+    }
+    // Exclude the change author from suggestions (never review your own PR).
+    const authorEmail = gitOut('git config --get user.email', cwd);
+    const excludeEmails = authorEmail ? new Set([(0, gather_1.normalizeEmail)(authorEmail)]) : undefined;
+    const ownership = (0, ownership_1.ownersFor)(cwd, files, { ...(excludeEmails ? { excludeEmails } : {}) });
+    // CODEOWNERS owners for the touched files (deduped across files).
+    const rules = readCodeowners(cwd);
+    const coOwners = [];
+    for (const f of files)
+        coOwners.push(...matchCodeowners(rules, f));
+    const result = {
+        ...buildSuggestions(ownership, {
+            ...(opts.limit !== undefined ? { limit: opts.limit } : {}),
+            codeowners: coOwners,
+        }),
+        touchedFiles: files,
+    };
+    if (opts.json) {
+        process.stdout.write(JSON.stringify(result, null, 2) + '\n');
+        return;
+    }
+    logger.info(`Suggested reviewers for ${files.length} changed file${files.length === 1 ? '' : 's'}:`);
+    if (result.reviewers.length === 0) {
+        logger.info('  (none)');
+    }
+    for (const r of result.reviewers) {
+        const who = r.handle ? `@${r.handle}` : r.name;
+        const tag = r.isCodeowner ? ' [CODEOWNERS]' : '';
+        logger.info(`  ${who}${tag} — ${r.reason}`);
+    }
+    if (result.busFactor === 1) {
+        logger.warn('  Bus factor 1: a single active owner covers these files — consider spreading knowledge.');
+    }
+    if (result.note)
+        logger.dim(`  ${result.note}`);
+}
+//# sourceMappingURL=reviewers-cli.js.map

package/dist/reviewers-cli.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"reviewers-cli.js","sourceRoot":"","sources":["../src/reviewers-cli.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@vyuhlabs/dxkit",
-  "version": "2.9.2",
+  "version": "2.9.4",
   "description": "AI-native developer experience toolkit for any codebase",
   "license": "MIT",
   "author": "Vyuh Labs",

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

@@ -1,6 +1,6 @@
 ---
 name: dxkit-action
-description: Read a dxkit report and execute fixes — prioritize findings by severity, plan the fix sequence, run the fix, verify the score moved, re-baseline if appropriate. Use when the user says "fix these findings", "act on the health report", "close out these vulnerabilities", or after dxkit-reports has surfaced something concrete.
+description: Read a dxkit report and execute fixes — prioritize findings by severity, plan the fix sequence, run the fix, verify the score moved, re-baseline if appropriate. Supports a SCOPED pass to burn down one category at a time (dependency/BOM vulnerabilities, security, code quality, tests, docs). Use when the user says "fix these findings", "act on the health report", "close out these vulnerabilities", "just fix the dependency vulns", "only the security findings", or after dxkit-reports has surfaced something concrete.
 ---
 
 # dxkit-action
@@ -28,6 +28,40 @@ npx vyuh-dxkit vulnerabilities --detailed --graph-context   # or test-gaps / qua
 
 `--graph-context` adds a "Graph context" column (the module a finding lives in + its blast radius — how many files call into it) so you can plan the fix without separately discovering structure. It's a structural HINT, not ground truth — read "Graph context" below for how to use it safely.
 
+Add **`--attribute`** when you need to know *who to ask* about a pre-existing finding — it adds a "Who to ask" column from `git blame` routed through the active-owner model, so an inactive author is forwarded to the file's current owner (names + @handles, never emails). It's opt-in and **historical only**: a net-new finding the guardrail just blocked was introduced by your own change, so "who to ask" there is simply the PR author — no blame needed. Honor the honesty caveat (blame is last-touch, not necessarily who introduced it).
+
+## Scoped fix — fix one category at a time
+
+Often the user doesn't want "fix everything" — they want to burn down **one
+category**: "just the dependency vulns", "only the security findings", "the
+code-quality stuff." Honor that. A scoped pass keeps the change reviewable and
+lets the team sequence the work.
+
+When the user names a scope (or you propose one), run the report that already
+partitions that dimension and work **only** that worklist — prioritization
+(severity → reachability → blast radius) still applies, but within the scope:
+
+| Scope the user asks for | Run | Findings in scope | Notes / hand-off |
+|---|---|---|---|
+| "dependency / BOM vulnerabilities" | `npx vyuh-dxkit bom` (or `vulnerabilities --detailed`) | `dep-vuln` | upgrade-first; see "Dependency vulnerability" below |
+| "security" | `npx vyuh-dxkit vulnerabilities --detailed --graph-context` | code-SAST, secrets, dep-vuln | reachable findings first (the report orders them); secrets always top |
+| "code quality" | `npx vyuh-dxkit quality --detailed --graph-context` | duplication, slop, lint, complexity | see "Slop / code-pattern finding" below |
+| "tests" / "coverage" | `npx vyuh-dxkit test-gaps --detailed --graph-context` | test-gap | hand off to **dxkit-test** for a real test-writing push |
+| "documentation" | `npx vyuh-dxkit health --detailed` (Documentation) | doc-gap | hand off to **dxkit-docs** |
+
+Rules for a scoped pass:
+
+- **Stay in the lane.** If the user said "just deps," don't also start fixing
+  SAST findings you notice — surface them ("I also see 3 HIGH SAST findings;
+  want a separate pass?") but don't expand scope unasked.
+- **Tests / docs scopes are hand-offs, not inline work.** Closing test gaps or
+  writing docs is a dedicated loop — route to `dxkit-test` / `dxkit-docs`
+  rather than half-doing it here.
+- **Verify within the scope.** Step [5] re-runs the scope's own report; the
+  scoped dimension should move and nothing else should regress (guardrail).
+
+Without a named scope, work the full **Priority order** below.
+
 ## Priority order
 
 Walk findings in this order (highest to lowest):
@@ -105,6 +139,8 @@ If no patched version exists OR the upgrade breaks other constraints AND the ris
 
 ### Test gap
 
+For one test gap inside a broader fix pass, close it inline:
+
 ```bash
 # 1. Read the source file the test-gap analyzer flagged
 # 2. Write a test that exercises the file's primary contract
@@ -116,6 +152,8 @@ npx vyuh-dxkit test-gaps
 
 Don't write tests that just import the module — write tests that exercise behavior. Useless tests inflate the count but don't move the dimension.
 
+For a dedicated push to close many gaps / raise the Tests score — reading the blast-radius-weighted worklist, orienting via the graph, writing meaningful tests in the repo's framework — hand off to the **dxkit-test** skill (the testing mirror of dxkit-docs).
+
 ### Slop / code-pattern finding
 
 ```bash
@@ -272,4 +310,7 @@ In those cases: `vyuh-dxkit allowlist add` is the right tool for per-finding dec
 - For hook-related issues during a fix push → `dxkit-hooks` skill
 - For re-running reports between fixes → `dxkit-reports` skill
 - For broken dxkit install (hooks not firing, vyuh-dxkit not on PATH) → `dxkit-fix` skill
+- For a dedicated test-writing push (close many gaps / raise the Tests score) → `dxkit-test` skill
+- For generating missing documentation → `dxkit-docs` skill
+- For raising the PR once fixes are done + guardrail-green → `dxkit-pr` skill (PR body from the diff + the guardrail/allowlist signals + a reviewer checklist)
 - For allowlist management beyond the per-finding `add` path — auditing existing entries (including orphans after a re-baseline), removing stale fingerprints, pruning expired ones, exporting to a `.snyk`, or reviewing the team's overall suppression posture → **dxkit-allowlist** skill

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-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,163 @@
+---
+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.
+
+### Suggested reviewers
+
+```bash
+npx vyuh-dxkit reviewers --base <base-branch> --json
+```
+
+This ranks reviewers by the **active-owner model** — recency-weighted git
+history on the touched files, with bots and departed contributors filtered, the
+PR author excluded, blended with `CODEOWNERS`. Better signal than the platform's
+naive last-touch suggestion. Surface the top few in the body with the *why*
+("@alice — owns 3/4 touched files, active"), and you can pass them to
+`gh pr create --reviewer`. Honor the output's caveats: if it returns a
+`busFactor: 1`, note the single-point-of-failure; if it returns a `note`
+(original authors inactive / no signal), say so rather than inventing a
+reviewer. Renders `@handle`s, never emails.
+
+## [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>
+
+## Suggested reviewers
+- @alice — owns 3/4 touched files, active · @bob — CODEOWNERS
+  (or the `note` when there's no active-owner signal)
+
+## 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>" \
+    --reviewer <handle1>,<handle2>     # the active owners from `reviewers`, if any
+```
+
+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