@vyuhlabs/dxkit 2.4.7 → 2.5.0

package/dist/cli.js

@@ -39,13 +39,16 @@ const vendored_advisor_1 = require("./analyzers/tools/vendored-advisor");
 const detect_1 = require("./detect");
 const generator_1 = require("./generator");
 const prompts_1 = require("./prompts");
-const project_yaml_1 = require("./project-yaml");
 const update_1 = require("./update");
 const doctor_1 = require("./doctor");
 const constants_1 = require("./constants");
 const logger = __importStar(require("./logger"));
 const scoring_1 = require("./scoring");
 const tools_unavailable_prose_1 = require("./analyzers/tools/tools-unavailable-prose");
+const report_date_1 = require("./analyzers/tools/report-date");
+const fail_on_1 = require("./fail-on");
+const report_schema_1 = require("./report-schema");
+const ship_installers_1 = require("./ship-installers");
 const fs = __importStar(require("fs"));
 const path = __importStar(require("path"));
 // process.stdout.write returns false when the OS pipe buffer is full
@@ -59,12 +62,51 @@ async function emitJson(payload) {
         await new Promise((resolve) => process.stdout.once('drain', resolve));
     }
 }
+/**
+ * Apply `--fail-on-score` to a higher-is-better score. Exits with
+ * code 1 + a logged reason when the gate fires. Skips when the user
+ * didn't pass the flag. Centralized so every analyzer that supports
+ * the flag fires consistent messages.
+ */
+function applyFailOnScore(raw, score, scoreLabel) {
+    if (raw === undefined)
+        return;
+    const threshold = (0, fail_on_1.parseScoreThreshold)(raw);
+    if (threshold === null) {
+        logger.fail(`--fail-on-score: invalid value "${raw}". Expected a number in [0, 100].`);
+        process.exit(1);
+    }
+    const verdict = (0, fail_on_1.checkFailOnScore)(score, threshold);
+    if (verdict.fails) {
+        logger.fail(`${scoreLabel} ${verdict.reason}`);
+        process.exit(1);
+    }
+}
+/**
+ * Apply `--fail-on-severity` to a per-severity count map. Exits
+ * with code 1 + a logged reason when the gate fires. Skips when
+ * the user didn't pass the flag.
+ */
+function applyFailOnSeverity(raw, counts, countsLabel) {
+    if (raw === undefined)
+        return;
+    const tier = (0, fail_on_1.parseSeverityTier)(raw);
+    if (tier === null) {
+        logger.fail(`--fail-on-severity: invalid tier "${raw}". Expected one of: critical, high, medium, low.`);
+        process.exit(1);
+    }
+    const verdict = (0, fail_on_1.checkFailOnSeverity)(counts, tier);
+    if (verdict.fails) {
+        logger.fail(`${countsLabel}: ${verdict.reason}`);
+        process.exit(1);
+    }
+}
 function printUsage() {
     console.log(`
-  ${logger.bold('vyuh-dxkit')} v${constants_1.VERSION} — AI-native developer experience toolkit
+  ${logger.bold('vyuh-dxkit')} v${constants_1.VERSION} — AI-native developer experience toolkit for any codebase
 
   ${logger.bold('Usage:')}
-    vyuh-dxkit init [options]    Initialize Claude Code DX in this repo
+    vyuh-dxkit init [options]    Install dxkit agent DX in this repo
     vyuh-dxkit update [options]  Re-generate (preserves evolved files)
     vyuh-dxkit doctor            Verify setup
     vyuh-dxkit health [path]     Run deterministic health analysis
@@ -80,23 +122,48 @@ function printUsage() {
     vyuh-dxkit to-xlsx <json>    Convert a dxkit JSON report to 15-col XLSX
     vyuh-dxkit tools [path]      Show required analysis tools status
     vyuh-dxkit tools install     Interactively install missing tools
+    vyuh-dxkit baseline create [path] [--name <name>] [--force]
+                                 Capture per-finding identities to .dxkit/baselines/<name>.json
+                                 (read later by guardrail check to gate new regressions)
+    vyuh-dxkit baseline show [path] [--name <n>] [--baseline <path>]
+                             [--kind <kind>] [--json]
+                                 Pretty-print the on-disk baseline. Default: summary +
+                                 per-kind counts. --kind drills into one kind. --json
+                                 emits a schema-banner-wrapped payload.
+    vyuh-dxkit guardrail check [path] [--name <n>] [--baseline <path>]
+                               [--changed-only] [--policy <path>]
+                               [--json | --markdown]
+                                 Diff current scan against the named baseline; block on net-new
+                                 regressions per brownfield policy. Exit code 1 when blocked.
 
   ${logger.bold('Init options:')}
-    --dx-only    Just .claude/ + CLAUDE.md (default)
-    --full       Everything: DX + quality + hooks + CI
-    --detect     Auto-detect stack, minimal prompts
-    --yes        Accept all defaults, no prompts
-    --force      Overwrite existing files (except evolved)
-    --stealth    Gitignore generated files (local-only, not committed)
-    --name <n>   Override project name
-    --no-scan    Skip codebase analysis
+    --dx-only                 Just .claude/ + CLAUDE.md (default)
+    --full                    Everything: DX + quality + hooks + devcontainer +
+                              CI guardrails + baseline-refresh workflow
+    --with-hooks              Install .githooks/pre-push guardrail hook (pre-commit opt-in)
+    --with-precommit-hook     Also install .githooks/pre-commit (slow on large repos)
+    --with-devcontainer       Install .devcontainer/ with pinned toolchains +
+                              dxkit + Claude Code & Codex CLIs
+    --with-ci                 Install .github/workflows/dxkit-guardrails.yml
+                              (PR-gate that posts a markdown summary comment)
+    --with-baseline-refresh   Install .github/workflows/dxkit-baseline-refresh.yml
+    --with-pr-review          Install .github/workflows/pr-review.yml (AI PR review; opt-in)
+                              (post-merge auto-regen of .dxkit/baselines/main.json)
+    --detect                  Auto-detect stack, minimal prompts
+    --yes                     Accept all defaults, no prompts
+    --force                   Overwrite existing files (incl. existing hooks/
+                              devcontainer instead of writing .dxkit sidecars)
+    --stealth                 Gitignore generated files (local-only, not committed)
+    --name <n>                Override project name
+    --no-scan                 Skip codebase analysis
 
   ${logger.bold('Update options:')}
     --force      Overwrite modified files (except evolved)
     --rescan     Re-run codebase analysis
 
   ${logger.bold('Analyzer options (health, vulnerabilities, test-gaps, quality, dev-report, licenses, bom):')}
-    --json            Print report as JSON to stdout
+    --json            Print report as JSON to stdout (top-level 'schema' field
+                      carries the dxkit.<kind>-report.v1 banner for version-gating)
     --verbose         Print per-tool timing to stderr
     --no-save         Skip writing the markdown report file
     --detailed        Also write <name>-detailed.md + .json with evidence + ranked actions
@@ -106,6 +173,12 @@ function printUsage() {
                       advisory rollup under byTopLevelDep still reflects transitives)
     --with-coverage   Health/test-gaps: materialize coverage artifacts via per-pack
                       runTests() before analysis (line-coverage truth vs filename match)
+    --fail-on-score <N>     Exit 1 when the analyzer's headline score drops below N.
+                            Applies to: health (overallScore), test-gaps (effectiveCoverage).
+    --fail-on-severity <tier>
+                      Exit 1 when any finding at <tier> or higher exists.
+                      tier ∈ critical|high|medium|low.
+                      Applies to: vulnerabilities, bom.
 
   ${logger.bold('Examples:')}
     npx vyuh-dxkit init                  # Interactive
@@ -146,6 +219,20 @@ async function run(argv) {
             timeout: { type: 'string' },
             'no-fail-fast': { type: 'boolean', default: false },
             'with-coverage': { type: 'boolean', default: false },
+            'changed-only': { type: 'boolean', default: false },
+            baseline: { type: 'string' },
+            policy: { type: 'string' },
+            markdown: { type: 'boolean', default: false },
+            'fail-on-score': { type: 'string' },
+            'fail-on-severity': { type: 'string' },
+            summary: { type: 'boolean', default: false },
+            kind: { type: 'string' },
+            'with-hooks': { type: 'boolean', default: false },
+            'with-precommit-hook': { type: 'boolean', default: false },
+            'with-devcontainer': { type: 'boolean', default: false },
+            'with-ci': { type: 'boolean', default: false },
+            'with-baseline-refresh': { type: 'boolean', default: false },
+            'with-pr-review': { type: 'boolean', default: false },
         },
         allowPositionals: true,
         strict: false,
@@ -173,66 +260,102 @@ async function run(argv) {
     switch (command) {
         case 'init': {
             logger.header('vyuh-dxkit init');
-            let config;
-            let finalMode = values.full ? 'full' : 'dx-only';
-            // If .project.yaml exists (written by create-devstack), try using it as config source
-            if ((0, project_yaml_1.hasProjectYaml)(cwd)) {
-                const yamlConfig = (0, project_yaml_1.readProjectYaml)(cwd);
-                if (yamlConfig) {
-                    logger.info('Found .project.yaml — using as config source.');
-                    config = yamlConfig;
-                    const langs = Object.entries(config.languages)
-                        .filter(([, v]) => v)
-                        .map(([k]) => k);
-                    const tools = Object.entries(config.tools)
-                        .filter(([, v]) => v)
-                        .map(([k]) => k);
-                    if (langs.length)
-                        logger.success(`Languages: ${langs.join(', ')}`);
-                    if (tools.length)
-                        logger.success(`Tools: ${tools.join(', ')}`);
-                    console.log('');
-                    // .project.yaml implies full mode (create-devstack handles the wizard)
-                    finalMode = values['dx-only'] ? 'dx-only' : 'full';
-                }
-                else {
-                    logger.warn('Found .project.yaml but it is malformed — falling back to detection.');
-                }
+            logger.info('Detecting stack...');
+            const detected = (0, detect_1.detect)(cwd);
+            const langs = Object.entries(detected.languages)
+                .filter(([, v]) => v)
+                .map(([k]) => k);
+            const tools = Object.entries(detected.tools)
+                .filter(([, v]) => v)
+                .map(([k]) => k);
+            if (langs.length === 0) {
+                logger.warn('No languages detected. Generating with minimal config.');
             }
-            if (!config) {
-                // No .project.yaml — detect stack and prompt as before
-                logger.info('Detecting stack...');
-                const detected = (0, detect_1.detect)(cwd);
-                const langs = Object.entries(detected.languages)
-                    .filter(([, v]) => v)
-                    .map(([k]) => k);
-                const tools = Object.entries(detected.tools)
-                    .filter(([, v]) => v)
-                    .map(([k]) => k);
-                if (langs.length === 0) {
-                    logger.warn('No languages detected. Generating with minimal config.');
-                }
-                else {
-                    logger.success(`Languages: ${langs.join(', ')}`);
-                }
-                if (tools.length)
-                    logger.success(`Tools: ${tools.join(', ')}`);
-                if (detected.framework)
-                    logger.success(`Framework: ${detected.framework}`);
-                if (detected.testRunner)
-                    logger.success(`Tests: ${detected.testRunner.framework} (${detected.testRunner.command})`);
-                console.log('');
-                // Resolve config via prompts
-                const promptOpts = {
-                    yes: !!(values.yes || values.detect),
-                    detect: !!values.detect,
-                    name: values.name,
-                };
-                const result = await (0, prompts_1.promptForConfig)(detected, promptOpts);
-                config = result.config;
-                finalMode = values.full ? 'full' : values['dx-only'] ? 'dx-only' : result.mode;
+            else {
+                logger.success(`Languages: ${langs.join(', ')}`);
             }
+            if (tools.length)
+                logger.success(`Tools: ${tools.join(', ')}`);
+            if (detected.framework)
+                logger.success(`Framework: ${detected.framework}`);
+            if (detected.testRunner)
+                logger.success(`Tests: ${detected.testRunner.framework} (${detected.testRunner.command})`);
+            console.log(''); // slop-ok
+            const promptOpts = {
+                yes: !!(values.yes || values.detect),
+                detect: !!values.detect,
+                name: values.name,
+            };
+            const promptResult = await (0, prompts_1.promptForConfig)(detected, promptOpts);
+            const config = promptResult.config;
+            const finalMode = values.full
+                ? 'full'
+                : values['dx-only']
+                    ? 'dx-only'
+                    : promptResult.mode;
             const result = await (0, generator_1.generate)(cwd, config, finalMode, !!values.force, !!values['no-scan']);
+            // Phase Ship installers (additive). `--full` implies every flag
+            // so a one-command setup gets the full 2.5.0 ship surface.
+            const isFull = !!values.full;
+            // pre-commit hook stays opt-in even under --full because it
+            // re-runs every analyzer on every commit (slow on large
+            // codebases until incremental scanning lands). Pre-push +
+            // CI catch the same regressions before code leaves the
+            // developer's machine.
+            const wantPrecommitHook = !!values['with-precommit-hook'];
+            // --with-precommit-hook implies --with-hooks (so the
+            // installer actually runs to install pre-commit alongside
+            // pre-push).
+            const wantHooks = isFull || !!values['with-hooks'] || wantPrecommitHook;
+            const wantDevcontainer = isFull || !!values['with-devcontainer'];
+            const wantCi = isFull || !!values['with-ci'];
+            const wantBaselineRefresh = isFull || !!values['with-baseline-refresh'];
+            // pr-review is opt-in even under --full because the workflow
+            // is inert without `ANTHROPIC_API_KEY` + `ENABLE_AI_REVIEW=true`
+            // configured separately. Shipping it by default just clutters
+            // the Actions tab on repos that don't intend to enable it.
+            const wantPrReview = !!values['with-pr-review'];
+            const shipResults = [];
+            if (wantHooks) {
+                shipResults.push({
+                    label: 'Git hooks',
+                    result: (0, ship_installers_1.installHooks)(cwd, {
+                        force: !!values.force,
+                        withPrecommit: wantPrecommitHook,
+                    }),
+                });
+            }
+            if (wantDevcontainer) {
+                shipResults.push({
+                    label: 'Devcontainer',
+                    result: (0, ship_installers_1.installDevcontainer)(cwd, { force: !!values.force }),
+                });
+            }
+            if (wantCi) {
+                shipResults.push({
+                    label: 'CI guardrails workflow',
+                    result: (0, ship_installers_1.installCiGuardrails)(cwd, { force: !!values.force }),
+                });
+            }
+            if (wantBaselineRefresh) {
+                shipResults.push({
+                    label: 'CI baseline-refresh workflow',
+                    result: (0, ship_installers_1.installCiBaselineRefresh)(cwd, { force: !!values.force }),
+                });
+            }
+            if (wantPrReview) {
+                shipResults.push({
+                    label: 'AI PR-review workflow',
+                    result: (0, ship_installers_1.installPrReview)(cwd, { force: !!values.force }),
+                });
+            }
+            // .gitignore + .dxkit-ignore seeding: default-on, no flag.
+            // Additive (existing entries preserved); safe for both fresh
+            // installs and re-runs.
+            shipResults.push({
+                label: 'Ignore files',
+                result: (0, ship_installers_1.installIgnoreFiles)(cwd, { force: !!values.force }),
+            });
             // Summary
             console.log('');
             logger.header('Summary');
@@ -242,6 +365,23 @@ async function run(argv) {
                 logger.warn(`Skipped: ${result.skipped.length} files (already exist)`);
             if (result.overwritten.length)
                 logger.info(`Overwritten: ${result.overwritten.length} files`);
+            for (const { label, result: r } of shipResults) {
+                if (r.installed.length) {
+                    logger.success(`${label}: installed ${r.installed.length} file(s)`);
+                    for (const f of r.installed)
+                        logger.dim(`    ${f}`);
+                }
+                if (r.sidecars.length) {
+                    logger.warn(`${label}: ${r.sidecars.length} sidecar(s) written (existing files preserved)`);
+                    for (const f of r.sidecars)
+                        logger.dim(`    ${f}`);
+                }
+                if (r.skipped.length) {
+                    logger.dim(`${label}: ${r.skipped.length} file(s) skipped (already present)`);
+                }
+                for (const note of r.notes)
+                    logger.info(note);
+            }
             console.log('');
             logger.info('Manifest written to .vyuh-dxkit.json');
             // Stealth mode: gitignore only files we just created
@@ -253,6 +393,9 @@ async function run(argv) {
             console.log('');
             logger.dim('  Run `vyuh-dxkit doctor` to verify setup');
             logger.dim('  Run `vyuh-dxkit update` to re-generate after changes');
+            if (shipResults.length > 0) {
+                logger.dim("  Run `vyuh-dxkit baseline create` to capture today's state");
+            }
             break;
         }
         case 'update': {
@@ -310,7 +453,7 @@ async function run(argv) {
             const healthMetrics = healthResult.metrics;
             const elapsed = ((Date.now() - startTime) / 1000).toFixed(1);
             if (values.json) {
-                await emitJson(report);
+                await emitJson((0, report_schema_1.stampSchema)(report, 'health'));
             }
             else {
                 // Console output
@@ -347,7 +490,7 @@ async function run(argv) {
             // call unconditionally.
             if (!values['no-save']) {
                 const reportDir = path.join(targetPath, '.dxkit', 'reports');
-                const date = new Date().toISOString().slice(0, 10);
+                const date = (0, report_date_1.getReportDate)();
                 const reportPath = path.join(reportDir, `health-audit-${date}.md`);
                 fs.mkdirSync(reportDir, { recursive: true });
                 fs.writeFileSync(reportPath, formatMarkdownReport(report, elapsed));
@@ -367,13 +510,17 @@ async function run(argv) {
                 const detailed = buildHealthDetailed(report, healthMetrics);
                 const detailedJsonPath = path.join(reportDir, `health-audit-${date}-detailed.json`);
                 const detailedMdPath = path.join(reportDir, `health-audit-${date}-detailed.md`);
-                fs.writeFileSync(detailedJsonPath, JSON.stringify(detailed, null, 2));
+                fs.writeFileSync(detailedJsonPath, JSON.stringify((0, report_schema_1.stampSchema)(detailed, 'health-detailed'), null, 2));
                 fs.writeFileSync(detailedMdPath, formatHealthDetailedMarkdown(detailed, elapsed));
                 if (values.detailed) {
                     logger.success(`Detailed report saved to ${path.relative(targetPath, detailedMdPath)}`);
                     logger.success(`Detailed JSON saved to ${path.relative(targetPath, detailedJsonPath)}`);
                 }
             }
+            // --fail-on-score: applies to the overall health score. Runs
+            // after disk writes so a failure still leaves a complete
+            // report behind for inspection.
+            applyFailOnScore(values['fail-on-score'], report.summary.overallScore, 'health overallScore');
             if (!values.json) {
                 // Hint about missing tools (exclude project-side config errors).
                 const PROJECT_ISSUES = ['config error', 'legacy .eslintrc', 'no eslint config'];
@@ -435,7 +582,7 @@ async function run(argv) {
             const report = await analyzeSecurity(targetPath, { verbose: !!values.verbose });
             const elapsed = ((Date.now() - startTime) / 1000).toFixed(1);
             if (values.json) {
-                await emitJson(report);
+                await emitJson((0, report_schema_1.stampSchema)(report, 'vulnerabilities'));
             }
             else {
                 const s = report.summary.findings;
@@ -457,7 +604,7 @@ async function run(argv) {
             // Disk side: orthogonal to --json (closes D018).
             if (!values['no-save']) {
                 const reportDir = path.join(targetPath, '.dxkit', 'reports');
-                const date = new Date().toISOString().slice(0, 10);
+                const date = (0, report_date_1.getReportDate)();
                 const reportPath = path.join(reportDir, `vulnerability-scan-${date}.md`);
                 fs.mkdirSync(reportDir, { recursive: true });
                 fs.writeFileSync(reportPath, formatSecurityReport(report, elapsed));
@@ -469,13 +616,20 @@ async function run(argv) {
                 const securityDetailed = buildSecurityDetailed(report);
                 const securityDetailedJsonPath = path.join(reportDir, `vulnerability-scan-${date}-detailed.json`);
                 const securityDetailedMdPath = path.join(reportDir, `vulnerability-scan-${date}-detailed.md`);
-                fs.writeFileSync(securityDetailedJsonPath, JSON.stringify(securityDetailed, null, 2));
+                fs.writeFileSync(securityDetailedJsonPath, JSON.stringify((0, report_schema_1.stampSchema)(securityDetailed, 'vulnerabilities-detailed'), null, 2));
                 fs.writeFileSync(securityDetailedMdPath, formatSecurityDetailedMarkdown(securityDetailed, elapsed));
                 if (values.detailed) {
                     logger.success(`Detailed report saved to ${path.relative(targetPath, securityDetailedMdPath)}`);
                     logger.success(`Detailed JSON saved to ${path.relative(targetPath, securityDetailedJsonPath)}`);
                 }
             }
+            // --fail-on-severity: applies to both code findings and
+            // dependency advisories. Code findings fire first because
+            // they're typically actionable (a SAST hit you wrote);
+            // dependency advisories second (transitive issue you may need
+            // to triage).
+            applyFailOnSeverity(values['fail-on-severity'], report.summary.findings, 'vulnerabilities (code)');
+            applyFailOnSeverity(values['fail-on-severity'], report.summary.dependencies, 'vulnerabilities (dependencies)');
             break;
         }
         case 'test-gaps': {
@@ -509,7 +663,7 @@ async function run(argv) {
             const report = await analyzeTestGaps(targetPath, { verbose: !!values.verbose });
             const elapsed = ((Date.now() - startTime) / 1000).toFixed(1);
             if (values.json) {
-                await emitJson(report);
+                await emitJson((0, report_schema_1.stampSchema)(report, 'test-gaps'));
             }
             else {
                 const s = report.summary;
@@ -527,7 +681,7 @@ async function run(argv) {
             // Disk side: orthogonal to --json (closes D018).
             if (!values['no-save']) {
                 const reportDir = path.join(targetPath, '.dxkit', 'reports');
-                const date = new Date().toISOString().slice(0, 10);
+                const date = (0, report_date_1.getReportDate)();
                 const reportPath = path.join(reportDir, `test-gaps-${date}.md`);
                 fs.mkdirSync(reportDir, { recursive: true });
                 fs.writeFileSync(reportPath, formatTestGapsReport(report, elapsed));
@@ -539,13 +693,18 @@ async function run(argv) {
                 const testGapsDetailed = buildTestGapsDetailed(report);
                 const testGapsDetailedJsonPath = path.join(reportDir, `test-gaps-${date}-detailed.json`);
                 const testGapsDetailedMdPath = path.join(reportDir, `test-gaps-${date}-detailed.md`);
-                fs.writeFileSync(testGapsDetailedJsonPath, JSON.stringify(testGapsDetailed, null, 2));
+                fs.writeFileSync(testGapsDetailedJsonPath, JSON.stringify((0, report_schema_1.stampSchema)(testGapsDetailed, 'test-gaps-detailed'), null, 2));
                 fs.writeFileSync(testGapsDetailedMdPath, formatTestGapsDetailedMarkdown(testGapsDetailed, elapsed));
                 if (values.detailed) {
                     logger.success(`Detailed report saved to ${path.relative(targetPath, testGapsDetailedMdPath)}`);
                     logger.success(`Detailed JSON saved to ${path.relative(targetPath, testGapsDetailedJsonPath)}`);
                 }
             }
+            // --fail-on-score: applies to the headline effectiveCoverage
+            // percentage. Tests-gap reports use a higher-is-better
+            // coverage scale, so the same threshold semantics work as
+            // for the health overall score.
+            applyFailOnScore(values['fail-on-score'], report.summary.effectiveCoverage, 'test-gaps effectiveCoverage');
             break;
         }
         case 'quality': {
@@ -560,7 +719,7 @@ async function run(argv) {
             });
             const elapsed = ((Date.now() - startTime) / 1000).toFixed(1);
             if (values.json) {
-                await emitJson(report);
+                await emitJson((0, report_schema_1.stampSchema)(report, 'quality'));
             }
             else {
                 const m = report.metrics;
@@ -599,7 +758,7 @@ async function run(argv) {
             // Disk side: orthogonal to --json (closes D018).
             if (!values['no-save']) {
                 const reportDir = path.join(targetPath, '.dxkit', 'reports');
-                const date = new Date().toISOString().slice(0, 10);
+                const date = (0, report_date_1.getReportDate)();
                 const reportPath = path.join(reportDir, `quality-review-${date}.md`);
                 fs.mkdirSync(reportDir, { recursive: true });
                 fs.writeFileSync(reportPath, formatQualityReport(report, elapsed));
@@ -632,7 +791,7 @@ async function run(argv) {
             });
             const elapsed = ((Date.now() - startTime) / 1000).toFixed(1);
             if (values.json) {
-                await emitJson(report);
+                await emitJson((0, report_schema_1.stampSchema)(report, 'dev-report'));
             }
             else {
                 const s = report.summary;
@@ -656,7 +815,7 @@ async function run(argv) {
             // Disk side: orthogonal to --json (closes D018).
             if (!values['no-save']) {
                 const reportDir = path.join(targetPath, '.dxkit', 'reports');
-                const date = new Date().toISOString().slice(0, 10);
+                const date = (0, report_date_1.getReportDate)();
                 const reportPath = path.join(reportDir, `developer-report-${date}.md`);
                 fs.mkdirSync(reportDir, { recursive: true });
                 fs.writeFileSync(reportPath, formatDevReport(report, elapsed));
@@ -689,7 +848,7 @@ async function run(argv) {
             const report = await analyzeLicenses(targetPath, { verbose: !!values.verbose });
             const elapsed = ((Date.now() - startTime) / 1000).toFixed(1);
             if (values.json) {
-                await emitJson(report); // slop-ok
+                await emitJson((0, report_schema_1.stampSchema)(report, 'licenses')); // slop-ok
             }
             else {
                 const s = report.summary;
@@ -717,7 +876,7 @@ async function run(argv) {
             // Disk side: orthogonal to --json (closes D018).
             if (!values['no-save']) {
                 const reportDir = path.join(targetPath, '.dxkit', 'reports');
-                const date = new Date().toISOString().slice(0, 10);
+                const date = (0, report_date_1.getReportDate)();
                 const reportPath = path.join(reportDir, `licenses-${date}.md`);
                 fs.mkdirSync(reportDir, { recursive: true });
                 fs.writeFileSync(reportPath, formatLicensesReport(report, elapsed));
@@ -765,7 +924,7 @@ async function run(argv) {
             });
             const elapsed = ((Date.now() - startTime) / 1000).toFixed(1);
             if (values.json) {
-                await emitJson(report); // slop-ok
+                await emitJson((0, report_schema_1.stampSchema)(report, 'bom')); // slop-ok
             }
             else {
                 const s = report.summary;
@@ -806,7 +965,7 @@ async function run(argv) {
             // Disk side: orthogonal to --json (closes D018).
             if (!values['no-save']) {
                 const reportDir = path.join(targetPath, '.dxkit', 'reports');
-                const date = new Date().toISOString().slice(0, 10);
+                const date = (0, report_date_1.getReportDate)();
                 const reportPath = path.join(reportDir, `bom-${date}.md`);
                 fs.mkdirSync(reportDir, { recursive: true });
                 fs.writeFileSync(reportPath, formatBomReport(report, elapsed));
@@ -834,6 +993,12 @@ async function run(argv) {
                     logger.success(`XLSX saved to ${path.relative(targetPath, xlsxPath)}`);
                 }
             }
+            // --fail-on-severity: BomReport.summary.bySeverity carries
+            // per-package max-severity counts. A package with multiple
+            // advisories is counted once at its highest severity, which
+            // is what a "block at this tier" gate wants — not double
+            // counting.
+            applyFailOnSeverity(values['fail-on-severity'], report.summary.bySeverity, 'bom severity');
             break;
         }
         case 'dashboard': {
@@ -1003,16 +1168,22 @@ async function run(argv) {
                 console.log(''); // slop-ok
             }
             const reportDir = path.join(targetPath, '.dxkit', 'reports');
-            const dateStr = new Date().toISOString().slice(0, 10);
+            // Snapshot the date once at orchestrator startup so every
+            // spawned subcommand writes filenames against the same date —
+            // long runs crossing UTC midnight otherwise produce a mix of
+            // pre- and post-midnight suffixes, and the post-step file-
+            // existence checks below miss the rolled-forward files.
+            const dateStr = (0, report_date_1.getReportDate)();
+            const childEnv = { ...process.env, DXKIT_REPORT_DATE: dateStr };
             for (const step of analyzerSteps) {
                 logger.info(`[${stepDurations.length + 1}/${analyzerSteps.length + 1}] ${step.label}...`);
                 const t0 = Date.now();
-                const rc = spawnSync(process.execPath, [process.argv[1], step.cmd, targetPath, ...passthroughFlags, ...(step.extraFlags ?? [])], { stdio: 'inherit' }).status;
+                const rc = spawnSync(process.execPath, [process.argv[1], step.cmd, targetPath, ...passthroughFlags, ...(step.extraFlags ?? [])], { stdio: 'inherit', env: childEnv }).status;
                 let effectiveRc = rc ?? -1;
                 // Post-step assertion: the child returned rc=0 BUT did the
                 // expected markdown actually land on disk? On heavy polyglot
-                // repos (web-client; 13K+ graphify nodes, jscpd timeout
-                // exhaustion) the health child was observed to silently exit
+                // repos (a JS-heavy customer frontend; 13K+ graphify nodes,
+                // jscpd timeout exhaustion) the health child was observed to silently exit
                 // 0 without writing its markdown — the dashboard then renders
                 // "no <X> data" and the customer never learns their report
                 // is missing. The orchestrator owns the "did the report
@@ -1027,12 +1198,29 @@ async function run(argv) {
                     }
                 }
                 stepDurations.push({ label: step.label, ms: Date.now() - t0, rc: effectiveRc });
+                // When the FIRST step (Health) fails, the AnalysisResult cache
+                // didn't get built — every downstream step then re-runs the
+                // full detect + Layer 0 + Layer 2 gather from scratch. On a
+                // heavy polyglot frontend this added ~86 s of redundant Layer
+                // 2 work to Step 2 (Vulnerabilities) alone, and ~10× that
+                // across the remaining 6 steps. Surface the cascade so the
+                // user understands why subsequent steps feel slower; the
+                // alternative path (build the cache directly from the failed
+                // gather) is a structural fix tracked for a later release.
+                if (step.cmd === 'health' && effectiveRc !== 0) {
+                    logger.warn('Health failed before the analysis cache could be built. ' +
+                        'The remaining steps will re-detect the stack and re-gather ' +
+                        'shared metrics from scratch (expect each to be measurably ' +
+                        'slower than usual). Their reports will still be written ' +
+                        'when they succeed individually.');
+                }
                 console.log(''); // slop-ok
             }
             logger.info(`[${stepDurations.length + 1}/${analyzerSteps.length + 1}] Dashboard...`);
             const dashT0 = Date.now();
             const dashRc = spawnSync(process.execPath, [process.argv[1], 'dashboard', targetPath], {
                 stdio: 'inherit',
+                env: childEnv,
             }).status;
             stepDurations.push({ label: 'Dashboard', ms: Date.now() - dashT0, rc: dashRc ?? -1 });
             // Final summary. Always emit it so the user sees the dashboard
@@ -1094,6 +1282,117 @@ async function run(argv) {
             logger.dim(`Converted in ${elapsed}s · report kind: ${kind}`);
             break;
         }
+        case 'baseline': {
+            const subCommand = positionals[1];
+            if (subCommand === 'create') {
+                const targetPath = resolveRepoPath(positionals[2]);
+                const { createBaseline } = await Promise.resolve().then(() => __importStar(require('./baseline/create')));
+                logger.header('vyuh-dxkit baseline create');
+                logger.info(`Capturing baseline for ${targetPath}...`);
+                const startTime = Date.now();
+                try {
+                    const result = await createBaseline({
+                        cwd: targetPath,
+                        name: values.name,
+                        force: !!values.force,
+                        verbose: !!values.verbose,
+                    });
+                    const elapsed = ((Date.now() - startTime) / 1000).toFixed(1);
+                    const rel = path.relative(targetPath, result.path);
+                    logger.success(`Wrote ${rel} — ${result.file.findings.length} findings, salt: ${result.file.saltMode} (${elapsed}s)`);
+                }
+                catch (err) {
+                    logger.fail(err.message);
+                    process.exit(1);
+                }
+                break;
+            }
+            if (subCommand === 'show') {
+                const targetPath = resolveRepoPath(positionals[2]);
+                const { DEFAULT_BASELINE_NAME, pathForBaseline, readBaselineFile } = await Promise.resolve().then(() => __importStar(require('./baseline/baseline-file')));
+                const { parseKindFilter, renderSummary, renderKind, renderJson, FILTER_KINDS } = await Promise.resolve().then(() => __importStar(require('./baseline/show')));
+                const name = values.name ?? DEFAULT_BASELINE_NAME;
+                const filePath = values.baseline ?? pathForBaseline(targetPath, name);
+                let file;
+                try {
+                    file = readBaselineFile(filePath);
+                }
+                catch (err) {
+                    logger.fail(err.message);
+                    process.exit(1);
+                }
+                // Optional kind filter. Validated up-front so a typo surfaces
+                // a clear error rather than a silently-empty result.
+                let kindFilter;
+                if (values.kind !== undefined) {
+                    const parsed = parseKindFilter(values.kind);
+                    if (parsed === null) {
+                        logger.fail(`--kind: unknown value "${values.kind}". Expected one of: ${FILTER_KINDS.join(', ')}.`);
+                        process.exit(1);
+                    }
+                    kindFilter = parsed;
+                }
+                if (values.json) {
+                    await emitJson(renderJson(file, kindFilter ? { kind: kindFilter } : {}));
+                }
+                else if (kindFilter) {
+                    process.stdout.write(renderKind(file, kindFilter) + '\n');
+                }
+                else {
+                    process.stdout.write(renderSummary(file) + '\n');
+                }
+                break;
+            }
+            logger.fail(`Unknown baseline subcommand: ${subCommand ?? '(missing)'}. ` +
+                `Available: vyuh-dxkit baseline create [path] [--name <name>] [--force] · ` +
+                `vyuh-dxkit baseline show [path] [--name <name>] [--baseline <path>] [--kind <kind>] [--json]`);
+            process.exit(1);
+            break;
+        }
+        case 'guardrail': {
+            const subCommand = positionals[1];
+            if (subCommand !== 'check') {
+                logger.fail(`Unknown guardrail subcommand: ${subCommand ?? '(missing)'}. ` +
+                    `Available: vyuh-dxkit guardrail check [path] [--name <n>] [--baseline <path>] ` +
+                    `[--changed-only] [--policy <path>] [--json | --markdown]`);
+                process.exit(1);
+            }
+            const targetPath = resolveRepoPath(positionals[2]);
+            const { runGuardrailCheck } = await Promise.resolve().then(() => __importStar(require('./baseline/check')));
+            const { renderConsole, renderJson, renderMarkdown } = await Promise.resolve().then(() => __importStar(require('./baseline/check-renderers')));
+            if (!values.json)
+                logger.header('vyuh-dxkit guardrail check');
+            if (!values.json)
+                logger.info(`Checking ${targetPath} against baseline...`);
+            const startTime = Date.now();
+            try {
+                const result = await runGuardrailCheck({
+                    cwd: targetPath,
+                    name: values.name,
+                    baselinePath: values.baseline,
+                    changedOnly: !!values['changed-only'],
+                    policyPath: values.policy,
+                    verbose: !!values.verbose,
+                });
+                const elapsed = ((Date.now() - startTime) / 1000).toFixed(1);
+                if (values.json) {
+                    await emitJson(renderJson(result));
+                }
+                else if (values.markdown) {
+                    process.stdout.write(renderMarkdown(result) + '\n');
+                }
+                else {
+                    process.stdout.write(renderConsole(result) + '\n');
+                    logger.dim(`Completed in ${elapsed}s`);
+                }
+                process.exit(result.blocks ? 1 : 0);
+            }
+            catch (err) {
+                logger.fail(err.message);
+                process.exit(1);
+            }
+            break;
+        }
         default:
             console.error(`Unknown command: ${command}`);
             printUsage();
@@ -1160,7 +1459,9 @@ function formatMarkdownReport(report, elapsed) {
         lines.push('');
         lines.push('| Rank | File | Lines |');
         lines.push('|-----:|------|------:|');
-        report.largestFiles.forEach((f, i) => {
+        // Top 10 is the render contract — the underlying metric carries
+        // every file over the threshold (consumed by the baseline producer).
+        report.largestFiles.slice(0, 10).forEach((f, i) => {
             lines.push(`| ${i + 1} | \`${f.path}\` | ${f.lines.toLocaleString()} |`);
         });
         lines.push('');
@@ -1172,7 +1473,9 @@ function formatMarkdownReport(report, elapsed) {
         // etc.; the remaining cases (most commonly `/libs/`) live in
         // customer-specific paths that can't be defaulted-away without
         // false-positives on first-party monorepo layouts.
-        const suspects = (0, vendored_advisor_1.suspectVendoredEntries)(report.largestFiles);
+        // Scope the vendored advisor to the rendered top 10 — the tip
+        // calls out files the user can see in the table above.
+        const suspects = (0, vendored_advisor_1.suspectVendoredEntries)(report.largestFiles.slice(0, 10));
         if (suspects.length > 0) {
             lines.push(`> **Tip — possibly vendored:** ${suspects
                 .map((s) => `\`${s.path}\``)