@vyuhlabs/dxkit 2.5.1 → 2.6.0

package/dist/upgrade.d.ts

@@ -0,0 +1,88 @@
+/**
+ * `vyuh-dxkit upgrade` — combined CLI for the dxkit upgrade flow.
+ *
+ * Two modes, one subcommand:
+ *
+ *   `--plan [--json]` — preview only. Emits UpgradePlan JSON
+ *   (consumed by dxkit-update skill) or text-prose summary. No
+ *   mutations. Used to inspect what an upgrade would do before
+ *   committing.
+ *
+ *   (no flag, or `--yes`) — execute. Runs the three-step upgrade:
+ *     1. `npm install @vyuhlabs/dxkit@<target>`     (binary)
+ *     2. `npx vyuh-dxkit update`                    (scaffold refresh)
+ *     3. `npx vyuh-dxkit doctor`                    (verify)
+ *   Then prints devcontainer-rebuild instructions if .devcontainer/
+ *   was refreshed.
+ *
+ * Architectural mirror of the doctor → dxkit-fix pattern: structured
+ * CLI output (--plan --json) for skill consumption, execution mode
+ * for direct human use. Same shape, different content.
+ */
+export type DeltaKind = 'none' | 'patch' | 'minor' | 'major' | 'downgrade';
+export interface UpgradeStep {
+    /** Shell command to run (verbatim — what gets executed). */
+    command: string;
+    /** One-line purpose shown in plan + before each execution. */
+    purpose: string;
+    /** Optional steps the customer can decline (e.g. devcontainer rebuild). */
+    optional?: boolean;
+}
+export interface UpgradePlan {
+    schema: 'upgrade-plan.v1';
+    generatedAt: string;
+    cwd: string;
+    current: {
+        /** Installed binary version (from `npx vyuh-dxkit --version`). */
+        binary: string | null;
+        /** Scaffold version recorded in manifest. */
+        scaffold: string | null;
+    };
+    /** Target version — `--target=X.Y.Z` or 'latest' from npm. */
+    target: string;
+    delta: DeltaKind;
+    /**
+     * Recommended execution sequence. Each step is independently
+     * idempotent — re-running is safe.
+     */
+    steps: UpgradeStep[];
+    /**
+     * Customer-facing warnings (peer-dep risks, breaking changes,
+     * "devcontainer will need rebuild after"). Empty when nothing
+     * actionable.
+     */
+    warnings: string[];
+    /**
+     * Brief note pointing the customer at the canonical changelog.
+     * Detailed per-version highlight parsing is a future enhancement —
+     * for now we keep this simple and link to the source of truth.
+     */
+    changelogNote: string;
+}
+export interface UpgradeOpts {
+    /** Pin to a specific version. Default: latest from npm. */
+    target?: string;
+    /** Skip interactive confirmations. */
+    yes?: boolean;
+    /** Print commands without executing. */
+    dryRun?: boolean;
+    /** Emit plan only; don't execute. */
+    planOnly?: boolean;
+    /** Emit plan as JSON instead of prose (only meaningful with planOnly). */
+    json?: boolean;
+    /**
+     * Injectable version reads. Useful for tests that need deterministic
+     * plans without subprocess fanout; production code leaves these
+     * undefined and the readers shell out as needed.
+     */
+    _readBinary?: (cwd: string) => string | null;
+    _readLatest?: () => string;
+}
+/**
+ * Classify the delta between two semver-shaped strings. Returns
+ * `'none'` if equal, `'downgrade'` if target < current.
+ */
+export declare function classifyDelta(current: string | null, target: string): DeltaKind;
+export declare function buildUpgradePlan(cwd: string, opts?: UpgradeOpts): UpgradePlan;
+export declare function runUpgrade(cwd: string, opts?: UpgradeOpts): Promise<void>;
+//# sourceMappingURL=upgrade.d.ts.map

package/dist/upgrade.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"upgrade.d.ts","sourceRoot":"","sources":["../src/upgrade.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;GAoBG;AAQH,MAAM,MAAM,SAAS,GAAG,MAAM,GAAG,OAAO,GAAG,OAAO,GAAG,OAAO,GAAG,WAAW,CAAC;AAE3E,MAAM,WAAW,WAAW;IAC1B,4DAA4D;IAC5D,OAAO,EAAE,MAAM,CAAC;IAChB,8DAA8D;IAC9D,OAAO,EAAE,MAAM,CAAC;IAChB,2EAA2E;IAC3E,QAAQ,CAAC,EAAE,OAAO,CAAC;CACpB;AAED,MAAM,WAAW,WAAW;IAC1B,MAAM,EAAE,iBAAiB,CAAC;IAC1B,WAAW,EAAE,MAAM,CAAC;IACpB,GAAG,EAAE,MAAM,CAAC;IACZ,OAAO,EAAE;QACP,kEAAkE;QAClE,MAAM,EAAE,MAAM,GAAG,IAAI,CAAC;QACtB,6CAA6C;QAC7C,QAAQ,EAAE,MAAM,GAAG,IAAI,CAAC;KACzB,CAAC;IACF,8DAA8D;IAC9D,MAAM,EAAE,MAAM,CAAC;IACf,KAAK,EAAE,SAAS,CAAC;IACjB;;;OAGG;IACH,KAAK,EAAE,WAAW,EAAE,CAAC;IACrB;;;;OAIG;IACH,QAAQ,EAAE,MAAM,EAAE,CAAC;IACnB;;;;OAIG;IACH,aAAa,EAAE,MAAM,CAAC;CACvB;AAED,MAAM,WAAW,WAAW;IAC1B,2DAA2D;IAC3D,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,sCAAsC;IACtC,GAAG,CAAC,EAAE,OAAO,CAAC;IACd,wCAAwC;IACxC,MAAM,CAAC,EAAE,OAAO,CAAC;IACjB,qCAAqC;IACrC,QAAQ,CAAC,EAAE,OAAO,CAAC;IACnB,0EAA0E;IAC1E,IAAI,CAAC,EAAE,OAAO,CAAC;IACf;;;;OAIG;IACH,WAAW,CAAC,EAAE,CAAC,GAAG,EAAE,MAAM,KAAK,MAAM,GAAG,IAAI,CAAC;IAC7C,WAAW,CAAC,EAAE,MAAM,MAAM,CAAC;CAC5B;AA4CD;;;GAGG;AACH,wBAAgB,aAAa,CAAC,OAAO,EAAE,MAAM,GAAG,IAAI,EAAE,MAAM,EAAE,MAAM,GAAG,SAAS,CAY/E;AAMD,wBAAgB,gBAAgB,CAAC,GAAG,EAAE,MAAM,EAAE,IAAI,GAAE,WAAgB,GAAG,WAAW,CA6FjF;AAyHD,wBAAsB,UAAU,CAAC,GAAG,EAAE,MAAM,EAAE,IAAI,GAAE,WAAgB,GAAG,OAAO,CAAC,IAAI,CAAC,CAcnF"}

package/dist/upgrade.js

@@ -0,0 +1,324 @@
+"use strict";
+/**
+ * `vyuh-dxkit upgrade` — combined CLI for the dxkit upgrade flow.
+ *
+ * Two modes, one subcommand:
+ *
+ *   `--plan [--json]` — preview only. Emits UpgradePlan JSON
+ *   (consumed by dxkit-update skill) or text-prose summary. No
+ *   mutations. Used to inspect what an upgrade would do before
+ *   committing.
+ *
+ *   (no flag, or `--yes`) — execute. Runs the three-step upgrade:
+ *     1. `npm install @vyuhlabs/dxkit@<target>`     (binary)
+ *     2. `npx vyuh-dxkit update`                    (scaffold refresh)
+ *     3. `npx vyuh-dxkit doctor`                    (verify)
+ *   Then prints devcontainer-rebuild instructions if .devcontainer/
+ *   was refreshed.
+ *
+ * Architectural mirror of the doctor → dxkit-fix pattern: structured
+ * CLI output (--plan --json) for skill consumption, execution mode
+ * for direct human use. Same shape, different content.
+ */
+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.classifyDelta = classifyDelta;
+exports.buildUpgradePlan = buildUpgradePlan;
+exports.runUpgrade = runUpgrade;
+const fs = __importStar(require("fs"));
+const path = __importStar(require("path"));
+const child_process_1 = require("child_process");
+const logger = __importStar(require("./logger"));
+// ────────────────────────────────────────────────────────────────────
+// Version helpers
+// ────────────────────────────────────────────────────────────────────
+function readScaffoldVersion(cwd) {
+    const manifestPath = path.join(cwd, '.vyuh-dxkit.json');
+    if (!fs.existsSync(manifestPath))
+        return null;
+    try {
+        const manifest = JSON.parse(fs.readFileSync(manifestPath, 'utf-8'));
+        return manifest.version ?? null;
+    }
+    catch {
+        return null;
+    }
+}
+function readBinaryVersion(cwd) {
+    try {
+        const out = (0, child_process_1.execSync)('npx --no-install vyuh-dxkit --version 2>/dev/null', {
+            cwd,
+            stdio: ['ignore', 'pipe', 'ignore'],
+            encoding: 'utf-8',
+        });
+        return out.trim() || null;
+    }
+    catch {
+        return null;
+    }
+}
+function readLatestPublished() {
+    try {
+        const out = (0, child_process_1.execSync)('npm view @vyuhlabs/dxkit version 2>/dev/null', {
+            stdio: ['ignore', 'pipe', 'ignore'],
+            encoding: 'utf-8',
+            timeout: 15000,
+        });
+        return out.trim();
+    }
+    catch {
+        // npm registry unreachable — return empty so caller can decide
+        return '';
+    }
+}
+/**
+ * Classify the delta between two semver-shaped strings. Returns
+ * `'none'` if equal, `'downgrade'` if target < current.
+ */
+function classifyDelta(current, target) {
+    if (!current || !target)
+        return 'none';
+    const [c1, c2, c3] = current.split('.').map((n) => parseInt(n, 10));
+    const [t1, t2, t3] = target.split('.').map((n) => parseInt(n, 10));
+    if (Number.isNaN(c1) || Number.isNaN(t1))
+        return 'none';
+    if (t1 > c1)
+        return 'major';
+    if (t1 < c1)
+        return 'downgrade';
+    if (t2 > c2)
+        return 'minor';
+    if (t2 < c2)
+        return 'downgrade';
+    if (t3 > c3)
+        return 'patch';
+    if (t3 < c3)
+        return 'downgrade';
+    return 'none';
+}
+// ────────────────────────────────────────────────────────────────────
+// Plan construction
+// ────────────────────────────────────────────────────────────────────
+function buildUpgradePlan(cwd, opts = {}) {
+    const scaffold = readScaffoldVersion(cwd);
+    const binary = (opts._readBinary ?? readBinaryVersion)(cwd);
+    const latest = opts.target ?? (opts._readLatest ?? readLatestPublished)();
+    // Use binary version as the "current" anchor for delta classification —
+    // it's what npm install will replace. Scaffold version informs whether
+    // vyuh-dxkit update is needed even when binary is already up to date.
+    const delta = classifyDelta(binary, latest);
+    const steps = [];
+    const warnings = [];
+    if (!latest) {
+        warnings.push('Could not query npm for the latest version (registry unreachable or rate-limited). ' +
+            'Pass --target=X.Y.Z to upgrade to a specific version.');
+    }
+    // Step 1: binary upgrade. Always included unless delta is none AND
+    // scaffold already matches.
+    if (delta !== 'none' || (scaffold && binary && scaffold !== binary)) {
+        if (latest) {
+            steps.push({
+                command: `npm install @vyuhlabs/dxkit@${latest}`,
+                purpose: `Install dxkit binary ${binary ?? '(missing)'} → ${latest}`,
+            });
+        }
+    }
+    // Step 2: scaffold refresh. Always run when scaffold ≠ binary OR after
+    // a binary upgrade (scaffold may need updating to match the new binary).
+    if (latest) {
+        steps.push({
+            command: 'npx vyuh-dxkit update',
+            purpose: 'Refresh scaffold (.devcontainer, .githooks, .claude/skills, CI workflows)',
+        });
+    }
+    // Step 3: verify with doctor.
+    if (latest) {
+        steps.push({
+            command: 'npx vyuh-dxkit doctor',
+            purpose: 'Verify operational health post-upgrade',
+        });
+    }
+    // Optional: devcontainer rebuild reminder. We mark this optional so
+    // dxkit-update can surface it as a "you also need to do this manually"
+    // step rather than something the CLI can execute.
+    const hasDevcontainer = fs.existsSync(path.join(cwd, '.devcontainer', 'devcontainer.json'));
+    if (hasDevcontainer && delta !== 'none') {
+        steps.push({
+            command: '# Rebuild devcontainer: VSCode Command Palette → "Dev Containers: Rebuild Container"',
+            purpose: 'Pick up devcontainer.json changes (if any) — manual step',
+            optional: true,
+        });
+    }
+    // Warnings.
+    if (delta === 'major') {
+        warnings.push(`Major version jump (${binary} → ${latest}). Read CHANGELOG.md for breaking changes ` +
+            'before running the upgrade.');
+    }
+    if (delta === 'downgrade') {
+        warnings.push(`Target version ${latest} is OLDER than installed ${binary}. ` +
+            'Downgrades are not officially supported; baseline + manifest schemas may differ.');
+    }
+    if (scaffold && binary && scaffold !== binary) {
+        warnings.push(`Scaffold version (${scaffold}) doesn't match binary (${binary}). ` +
+            'Step 2 (vyuh-dxkit update) will reconcile.');
+    }
+    return {
+        schema: 'upgrade-plan.v1',
+        generatedAt: new Date().toISOString(),
+        cwd,
+        current: { binary, scaffold },
+        target: latest,
+        delta,
+        steps,
+        warnings,
+        changelogNote: latest
+            ? `For per-version details: https://github.com/vyuh-labs/dxkit/blob/main/CHANGELOG.md`
+            : '',
+    };
+}
+// ────────────────────────────────────────────────────────────────────
+// Renderers
+// ────────────────────────────────────────────────────────────────────
+function renderPlanProse(plan) {
+    logger.header('vyuh-dxkit upgrade --plan');
+    logger.info(`Current: scaffold ${plan.current.scaffold ?? '(none)'} + binary ${plan.current.binary ?? '(none)'}`);
+    logger.info(`Target:  ${plan.target || '(latest unavailable)'}`);
+    logger.info(`Delta:   ${plan.delta}`);
+    if (plan.warnings.length) {
+        console.log(''); // slop-ok
+        for (const w of plan.warnings)
+            logger.warn(w);
+    }
+    if (plan.steps.length) {
+        console.log(''); // slop-ok
+        logger.info('Plan:');
+        plan.steps.forEach((s, i) => {
+            const marker = s.optional ? '○' : '●';
+            logger.dim(`  ${marker} [${i + 1}/${plan.steps.length}] ${s.purpose}`);
+            logger.dim(`     ${s.command}`);
+        });
+    }
+    if (plan.changelogNote) {
+        console.log(''); // slop-ok
+        logger.dim(plan.changelogNote);
+    }
+}
+// ────────────────────────────────────────────────────────────────────
+// Execution
+// ────────────────────────────────────────────────────────────────────
+function runStep(step, cwd, dryRun) {
+    if (step.optional) {
+        // Optional steps are never auto-executed — surfaced for the
+        // customer to do manually.
+        return true;
+    }
+    logger.info(`→ ${step.purpose}`);
+    logger.dim(`  ${step.command}`);
+    if (dryRun) {
+        logger.dim('  (dry-run; skipping)');
+        return true;
+    }
+    // Shell out to a real shell so npx/npm work the same way as the
+    // customer's terminal would. We DON'T use spawnSync's shell:true
+    // bash escaping concerns because the commands here are all dxkit-
+    // controlled — no customer input flows into them.
+    const result = (0, child_process_1.spawnSync)('bash', ['-c', step.command], {
+        cwd,
+        stdio: 'inherit',
+    });
+    return result.status === 0;
+}
+async function runUpgradeExecution(cwd, plan, opts) {
+    // Print the plan so the customer sees what's about to happen.
+    renderPlanProse(plan);
+    if (plan.steps.length === 0) {
+        console.log(''); // slop-ok
+        logger.success('Already up to date — nothing to do.');
+        return;
+    }
+    if (!opts.yes && !opts.dryRun) {
+        // We don't bundle a real prompt library here — the upgrade is
+        // intended either non-interactive (--yes) or driven by the
+        // dxkit-update skill (which handles confirmation). Surface the
+        // hint so a direct human invocation knows to add --yes.
+        console.log(''); // slop-ok
+        logger.warn('Interactive confirmation is not implemented for this command. ' +
+            'Re-run with --yes to execute, --dry-run to print without executing, ' +
+            'or use the dxkit-update skill for a guided upgrade.');
+        return;
+    }
+    console.log(''); // slop-ok
+    logger.header('Executing upgrade');
+    const optionalAfter = [];
+    for (const step of plan.steps) {
+        if (step.optional) {
+            optionalAfter.push(step);
+            continue;
+        }
+        const ok = runStep(step, cwd, !!opts.dryRun);
+        if (!ok) {
+            logger.fail(`Step failed: ${step.purpose}`);
+            logger.dim('  Upgrade aborted. Re-run `vyuh-dxkit doctor` to see current state.');
+            process.exitCode = 1;
+            return;
+        }
+    }
+    console.log(''); // slop-ok
+    logger.success(`Upgraded to ${plan.target}.`);
+    if (optionalAfter.length) {
+        console.log(''); // slop-ok
+        logger.info('Manual steps still required:');
+        for (const s of optionalAfter)
+            logger.dim(`  • ${s.purpose}\n    ${s.command}`);
+    }
+}
+// ────────────────────────────────────────────────────────────────────
+// Entry point
+// ────────────────────────────────────────────────────────────────────
+async function runUpgrade(cwd, opts = {}) {
+    const plan = buildUpgradePlan(cwd, opts);
+    if (opts.planOnly) {
+        if (opts.json) {
+            // Logger already routes to stderr in --json mode (cli.ts sets it).
+            console.log(JSON.stringify(plan, null, 2)); // slop-ok
+        }
+        else {
+            renderPlanProse(plan);
+        }
+        return;
+    }
+    await runUpgradeExecution(cwd, plan, opts);
+}
+//# sourceMappingURL=upgrade.js.map

package/dist/upgrade.js.map

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

package/package.json

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

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

@@ -42,20 +42,22 @@ Skip items where reachability is "no" (graphify can't find a call path) UNLESS t
 # 2. Remove the secret from the file
 # 3. If the secret was committed: `git filter-repo` or BFG to scrub history
 # 4. Re-scan to confirm gitleaks no longer reports it
-vyuh-dxkit vulnerabilities --json | jq '.summary.findings'
+npx vyuh-dxkit vulnerabilities --json | jq '.summary.findings'
 ```
 
 Don't try to redact the secret in place — the git history still has it. Rotation is the only true fix.
 
+If the "secret" is actually a placeholder in test code (e.g., `"sk_test_xxxxxxxxxxxx"` with no real credential value), confirm with the developer and allowlist via `dxkit-allow:test-fixture` — see "Allowlisting (when fix is not viable)" below.
+
 ### SAST finding (semgrep)
 
 ```bash
 # 1. Read the finding's rule + line range from the report
 # 2. Open the file, understand why semgrep flagged it
-# 3. Either FIX (preferred) or SUPPRESS (carefully)
+# 3. Either FIX (preferred) or ALLOWLIST (carefully — see below)
 ```
 
-Suppression is `// nosemgrep: <rule-id>` on the offending line. Use sparingly — every suppression is a future maintenance burden. Better: fix the underlying issue.
+If the finding is a true false positive or intentional pattern (test fixture, mitigated externally), suppress via dxkit's allowlist — NOT via semgrep's `// nosemgrep:`. The dxkit allowlist is the canonical surface (single source of truth across every scanner), carries a typed category + reason, and is audit-trackable through `vyuh-dxkit allowlist audit`. See "Allowlisting (when fix is not viable)" below.
 
 ### Dependency vulnerability
 
@@ -63,13 +65,15 @@ Suppression is `// nosemgrep: <rule-id>` on the offending line. Use sparingly
 # Find the patched version (osv-scanner / npm-audit / etc. report it)
 npm install <pkg>@<patched-version>
 # Re-run the scan
-vyuh-dxkit vulnerabilities
+npx vyuh-dxkit vulnerabilities
 ```
 
 For peer-dep conflicts: `npm install <pkg>@<patched-version> --legacy-peer-deps` (matches the post-create.sh fallback chain).
 
 For Python: `pip install --upgrade <pkg>=<patched>` then re-pip-freeze. For Go: `go get <pkg>@<patched>` then `go mod tidy`. For Ruby: edit Gemfile, `bundle update <pkg>`. For Rust: `cargo update -p <pkg> --precise <patched>`.
 
+If no patched version exists OR the upgrade breaks other constraints AND the risk is mitigated externally (network policy, WAF, runtime guard), allowlist with `category=mitigated-externally` and a reason describing the mitigation. If the team is accepting the risk while waiting on a fix, `category=accepted-risk` + an expiry tied to the fix deadline.
+
 ### Test gap
 
 ```bash
@@ -78,7 +82,7 @@ For Python: `pip install --upgrade <pkg>=<patched>` then re-pip-freeze. For Go:
 # 3. Run the test runner to confirm it passes
 npm test  # or pytest, go test, cargo test, etc.
 # 4. Re-run test-gaps to confirm the file dropped off the list
-vyuh-dxkit test-gaps
+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.
@@ -93,13 +97,95 @@ Don't write tests that just import the module — write tests that exercise beha
 
 If the finding is a false positive, add `// slop-ok: <reason>` on the offending line (or `# slop-ok` for non-JS).
 
+## Allowlisting (when fix is not viable)
+
+**Fix first.** The allowlist is the SECOND option, not the first. When you reach for it, choose deliberately — every allowlist entry is a future maintenance burden the customer's team will revisit.
+
+Five typed categories signal WHY the suppression is in place:
+
+| Category | Meaning | Where it lives |
+|---|---|---|
+| `false-positive` | Scanner is wrong about this code | Inline annotation OR file-level |
+| `test-fixture` | Intentional pattern in a fixture / test file | Inline annotation OR file-level |
+| `mitigated-externally` | Real risk but neutralized at runtime (WAF, env, etc.) | Inline annotation OR file-level |
+| `accepted-risk` | Real risk, accepted by the team, signed off | File-level only (needs expiry + acknowledged severity) |
+| `deferred` | Real, will fix later, tracked work | File-level only (needs expiry) |
+
+`accepted-risk` and `deferred` require an `expiresAt` date because they describe assertions that should age out — by default the CLI sets 90 days. `false-positive`, `test-fixture`, and `mitigated-externally` describe assertions that don't naturally stale; they may omit expiry.
+
+### The two surfaces
+
+**Inline annotation** is the natural fit for source-anchored findings (secrets, code, config, dep-vuln, hygiene) with an inline-compatible category. The annotation lives next to the line it suppresses:
+
+```python
+api_key = "sk_test_xxxx"  # dxkit-allow:test-fixture reason="placeholder in unit test"
+```
+
+Or, for long source lines, above:
+
+```typescript
+// dxkit-allow:false-positive reason="regex matches intentional placeholder"
+const apiKey = "sk_test_xxxx";
+```
+
+The grammar is uniform across every language; only the comment marker varies (`#` for python/ruby, `//` for typescript/go/rust/csharp/kotlin/java). Don't type it by hand — let dxkit insert it for you (see CLI below).
+
+**File-level allowlist** lives at `.dxkit/allowlist.json` and is the surface for:
+
+- Cross-file or whole-file findings (duplication, coverage-gap, test-gap, god-file, large-file, stale-file)
+- Findings with no stable single-line attachment (dep-vuln, secret-hmac)
+- Any `accepted-risk` or `deferred` suppression regardless of kind
+
+### Add an allowlist entry (canonical path)
+
+Don't hand-edit the annotation comment or the JSON file — let the CLI insert it correctly:
+
+```bash
+# Inline annotation at file:line — for source-anchored findings
+# with an inline-compatible category
+npx vyuh-dxkit allowlist add src/auth/oauth.ts:42 \
+    --category=test-fixture --reason="placeholder in unit test"
+
+# File-level entry — for everything else (kind + fingerprint required;
+# both come straight from the guardrail check's output)
+npx vyuh-dxkit allowlist add --fingerprint=a3f9c0e8b7d2e1f4 \
+    --kind=dep-vuln --category=accepted-risk \
+    --reason="WAF rule X mitigates this CVE" --expires=2026-08-22
+```
+
+The guardrail's block message gives you the exact command to paste for every blocked finding — file path + line for inline-compatible kinds, fingerprint + kind for everything else. Just copy-paste.
+
+### When the finding only carries an id (sanitized / ref-based baseline)
+
+If you're seeing a blocked finding labelled `<sanitized>` (in `baseline show` output) OR with no `file`/`line` columns in the PR-comment table, the repo's baseline mode is `committed-sanitized` or `ref-based` and the human-readable locator was stripped at write time. Two options:
+
+- **Inspect the finding in the current scan.** The fingerprint pairs against the live scan's output, which is rich (always). Re-run the matching analyzer (`vyuh-dxkit vulnerabilities`, `vyuh-dxkit health`, etc.) and grep the JSON output for the fingerprint — that finding has full file:line context.
+- **Allowlist by fingerprint anyway.** File-level allowlist entries only need fingerprint + kind, both of which the guardrail message still provides. The category + reason apply regardless of whether the locator is visible at baseline time.
+
+The fingerprint contract is preserved across all three modes — `committed-full`, `committed-sanitized`, `ref-based` all produce the same identity bytes for the same finding. Sanitization only strips the human-readable rendering; it doesn't change which findings pair across runs.
+
+### Review what's allowlisted
+
+```bash
+npx vyuh-dxkit allowlist list             # all entries (text)
+npx vyuh-dxkit allowlist show <fingerprint>  # one entry's full detail
+npx vyuh-dxkit allowlist audit            # expired / soon-to-expire / missing-rationale
+npx vyuh-dxkit allowlist prune            # remove expired entries
+```
+
+Run `audit` periodically — `accepted-risk` and `deferred` entries that pass their expiry should either be re-justified (renew expiry) or pruned (remove the entry; the underlying finding will re-flag on the next scan).
+
+### Stale annotations
+
+If the underlying finding is fixed but the inline annotation lingers, the next scan emits a `stale-allow` finding pointing at the orphaned comment. The remediation is always to remove the annotation — dxkit refuses to allowlist a stale-allow finding (allowlisting the warning that an annotation is stale would defeat the entire model).
+
 ## Verification — never skip
 
 After each fix:
 
 ```bash
 # Re-run the SPECIFIC analyzer that flagged the finding
-vyuh-dxkit vulnerabilities  # or quality / test-gaps / health
+npx vyuh-dxkit vulnerabilities  # or quality / test-gaps / health
 ```
 
 The fix is verified when:
@@ -111,14 +197,19 @@ If the finding's still there: the fix didn't work, try again.
 
 ## Baseline decisions
 
-Once a finding is fixed AND verified gone, the workflow depends on what changed:
+Once a finding is processed (fixed, allowlisted, or accepted), the workflow depends on which path you took:
 
 | Scenario | Action |
 |---|---|
-| Fix landed via a code change | Commit the code. Baseline is unchanged. Future scans confirm the fix held. |
-| Fix landed via a config change (e.g., new entry in `.dxkit-ignore`) | Re-baseline: `vyuh-dxkit baseline create --force`. Commit both `.dxkit-ignore` and the new baseline. |
-| Finding accepted as known + not blocking | Re-baseline with explicit reason in the commit message. Future scans treat it as pre-existing, not net-new. |
-| Finding is genuinely a false positive | First try suppression on the offending line. If you can't suppress, re-baseline. |
+| Fix landed via a code change | Commit the code. Baseline + allowlist are unchanged. Future scans confirm the fix held. |
+| Genuine false positive OR intentional pattern | `vyuh-dxkit allowlist add` with `category=false-positive` or `test-fixture`. Commit the annotation / allowlist file. Baseline is unchanged. |
+| Real risk neutralized externally (WAF, runtime guard) | `vyuh-dxkit allowlist add` with `category=mitigated-externally` + a reason describing the mitigation. Baseline unchanged. |
+| Real risk, accepted by team, won't fix | `vyuh-dxkit allowlist add` with `category=accepted-risk` + `--expires=YYYY-MM-DD` (defaults 90 days). Acknowledged-severity required for high/critical. |
+| Real risk, will fix later (tracked work) | `vyuh-dxkit allowlist add` with `category=deferred` + `--expires=YYYY-MM-DD`. The expiry forces re-review when the deadline passes. |
+| Fix landed via a config change (e.g., new entry in `.dxkit-ignore`) | Re-baseline: `npx vyuh-dxkit baseline create --force`. Commit both `.dxkit-ignore` and the new baseline. |
+| Brownfield acceptance (the whole CURRENT state is known mess; future regressions must be net-new) | Re-baseline with an explicit reason in the commit message. Reserve this for the deliberate "draw a line here" moment, not per-finding suppression. |
+
+**Prefer the allowlist over re-baselining for per-finding decisions.** The allowlist carries a typed category + reason + (when relevant) expiry; the baseline carries only "this finding was here." Future maintainers reading `vyuh-dxkit allowlist show <fingerprint>` see WHY the suppression is in place; reading the baseline file shows only that the finding existed at capture time. Per-finding decisions belong in the allowlist; codebase-wide brownfield acceptance belongs in the baseline.
 
 **Never** re-baseline a finding silently — the commit message should explain why the regression is accepted. Future maintainers reading `git log .dxkit/baselines/` should see the rationale.
 
@@ -127,24 +218,27 @@ Once a finding is fixed AND verified gone, the workflow depends on what changed:
 After fixing N findings, run the guardrail check before pushing:
 
 ```bash
-vyuh-dxkit guardrail check
+npx vyuh-dxkit guardrail check
 ```
 
 Exit 0 = your fixes didn't introduce any net-new regressions (you only removed/fixed things). Exit 1 = something new appeared; address that before pushing.
 
 ## When fixes get expensive
 
-Sometimes the right call is: don't fix, accept as baseline.
+Sometimes the right call is: don't fix, allowlist (or re-baseline if it's brownfield-wide).
 
 Examples:
-- Legacy code on a deprecation path (sunset > fix)
-- A SAST finding in vendored code you don't maintain
-- A test gap on a one-off script that doesn't merit tests
+- Legacy code on a deprecation path (sunset > fix) → `accepted-risk` with expiry matching the sunset date
+- A SAST finding in vendored code you don't maintain → `mitigated-externally` if the vendor patches separately, else `accepted-risk`
+- A test gap on a one-off script that doesn't merit tests → `accepted-risk`
+- An import line flagged by a scanner that you've reviewed and confirmed safe → `false-positive` inline annotation at the import
 
-In those cases: accept-as-baseline with a commit message explaining the call. dxkit's baseline IS designed to support this — the brownfield contract is "today's mess is acknowledged; tomorrow's must be a real improvement." Use it.
+In those cases: `vyuh-dxkit allowlist add` is the right tool for per-finding decisions (typed reason + expiry where relevant). Reserve "accept as baseline" for the deliberate one-shot brownfield moment ("this entire current state is known mess; today's findings are the new baseline"). The two surfaces complement each other — allowlist for individual judgment calls, baseline for the codebase-wide line in the sand.
 
 ## Hand-offs
 
 - For ignore-file edits as part of a fix → `dxkit-config` skill
 - 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 allowlist management beyond the per-finding `add` path (auditing existing entries, pruning expired ones, reviewing the team's overall suppression posture) → run `npx vyuh-dxkit allowlist audit` / `list` / `prune` directly; no separate skill yet