@vyuhlabs/dxkit 1.5.1 → 1.6.0

package/dist/tools-cli.js

@@ -0,0 +1,231 @@
+"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.runToolsCommand = runToolsCommand;
+/**
+ * CLI handler for `vyuh-dxkit tools` subcommand.
+ *
+ * Modes:
+ * - `vyuh-dxkit tools`             → list status for required tools
+ * - `vyuh-dxkit tools install`     → interactive install of missing tools
+ * - `vyuh-dxkit tools install --yes` → install all missing, no prompts
+ */
+const readline = __importStar(require("readline/promises"));
+const process_1 = require("process");
+const child_process_1 = require("child_process");
+const detect_1 = require("./detect");
+const logger = __importStar(require("./logger"));
+const tool_registry_1 = require("./analyzers/tools/tool-registry");
+const LAYER_ORDER = {
+    universal: 1,
+    language: 2,
+    optional: 3,
+};
+const LAYER_LABEL = {
+    universal: 'universal',
+    language: 'language ',
+    optional: 'optional ',
+};
+function sortByLayer(statuses) {
+    return [...statuses].sort((a, b) => {
+        const la = LAYER_ORDER[a.requirement.layer] || 99;
+        const lb = LAYER_ORDER[b.requirement.layer] || 99;
+        if (la !== lb)
+            return la - lb;
+        return a.name.localeCompare(b.name);
+    });
+}
+function formatStatusLine(s) {
+    const icon = s.available ? '\x1b[32m✓\x1b[0m' : '\x1b[31m✗\x1b[0m';
+    const name = s.name.padEnd(16);
+    const layer = LAYER_LABEL[s.requirement.layer] || s.requirement.layer;
+    const forStack = s.requirement.for.padEnd(7);
+    if (s.available) {
+        const src = s.source === 'path' ? '' : ` (${s.source})`;
+        return `  ${icon} ${name}  ${layer}  ${forStack}  ${logger.bold('found')}${src}`;
+    }
+    return `  ${icon} ${name}  ${layer}  ${forStack}  \x1b[2mmissing\x1b[0m`;
+}
+/** Show tool status for the repo's detected stack. */
+function showStatus(targetPath) {
+    const stack = (0, detect_1.detect)(targetPath);
+    const langs = Object.entries(stack.languages)
+        .filter(([, v]) => v)
+        .map(([k]) => k);
+    logger.header('vyuh-dxkit tools');
+    logger.info(`Stack: ${langs.join(', ') || 'unknown'}`);
+    console.log('');
+    const statuses = sortByLayer((0, tool_registry_1.checkAllTools)(stack.languages, targetPath));
+    console.log(`  ${logger.bold('Tool'.padEnd(16))}  ${logger.bold('layer'.padEnd(10))}  ${logger.bold('for'.padEnd(7))}  ${logger.bold('status')}`);
+    console.log(`  ${'─'.repeat(16)}  ${'─'.repeat(10)}  ${'─'.repeat(7)}  ${'─'.repeat(20)}`);
+    for (const s of statuses) {
+        console.log(formatStatusLine(s));
+        if (s.available && s.version) {
+            logger.dim(`    version: ${s.version}`);
+        }
+        if (s.available && s.path && s.source !== 'path') {
+            logger.dim(`    path: ${s.path}`);
+        }
+    }
+    const missing = statuses.filter((s) => !s.available);
+    const total = statuses.length;
+    console.log('');
+    if (missing.length === 0) {
+        logger.success(`All ${total} required tools available.`);
+    }
+    else {
+        logger.warn(`${missing.length}/${total} tools missing.`);
+        console.log('');
+        logger.dim(`Run \`vyuh-dxkit tools install\` to install missing tools interactively.`);
+    }
+    return statuses;
+}
+async function confirm(rl, question) {
+    const answer = await rl.question(`  ${question} [Y/n]: `);
+    if (!answer.trim())
+        return true;
+    return answer.trim().toLowerCase().startsWith('y');
+}
+function runInstallCmd(cmd) {
+    try {
+        // Use bash -c so multi-command scripts (with &&, ||, ;) work
+        (0, child_process_1.execSync)(cmd, {
+            shell: '/bin/bash',
+            stdio: ['inherit', 'inherit', 'inherit'],
+            timeout: 600000, // 10 min for downloads
+        });
+        return { success: true, message: 'installed' };
+    }
+    catch (err) {
+        const e = err;
+        return { success: false, message: e.message || 'unknown error' };
+    }
+}
+/** Interactive install of missing tools. */
+async function runInstall(targetPath, autoYes) {
+    const statuses = showStatus(targetPath);
+    const missing = statuses.filter((s) => !s.available);
+    if (missing.length === 0) {
+        return;
+    }
+    console.log('');
+    logger.header('Install missing tools');
+    const rl = autoYes ? null : readline.createInterface({ input: process_1.stdin, output: process_1.stdout });
+    const results = [];
+    try {
+        for (const s of missing) {
+            const def = tool_registry_1.TOOL_DEFS[s.name];
+            if (!def) {
+                results.push({ name: s.name, status: 'skipped', msg: 'no install command' });
+                continue;
+            }
+            const cmd = (0, tool_registry_1.getInstallCommand)(def);
+            if (cmd === 'builtin' || cmd === 'builtin (npm)' || cmd === 'builtin (dotnet SDK)') {
+                results.push({ name: s.name, status: 'skipped', msg: 'builtin' });
+                continue;
+            }
+            console.log('');
+            console.log(`  ${logger.bold(s.name)} — ${def.description}`);
+            logger.dim(`    ${cmd}`);
+            let shouldInstall = autoYes;
+            if (!autoYes && rl) {
+                shouldInstall = await confirm(rl, `  Install ${s.name}?`);
+            }
+            if (!shouldInstall) {
+                results.push({ name: s.name, status: 'skipped', msg: 'user declined' });
+                logger.dim('  Skipped.');
+                continue;
+            }
+            console.log('');
+            logger.info(`Running: ${cmd}`);
+            const result = runInstallCmd(cmd);
+            if (result.success) {
+                // Verify install worked
+                const recheck = (0, tool_registry_1.findTool)(def, targetPath);
+                if (recheck.available) {
+                    results.push({ name: s.name, status: 'installed' });
+                    logger.success(`${s.name} installed (${recheck.source})`);
+                }
+                else {
+                    results.push({
+                        name: s.name,
+                        status: 'failed',
+                        msg: 'install command succeeded but tool not found',
+                    });
+                    logger.fail(`${s.name} install command ran but tool not found in PATH`);
+                }
+            }
+            else {
+                results.push({ name: s.name, status: 'failed', msg: result.message });
+                logger.fail(`${s.name}: ${result.message}`);
+            }
+        }
+    }
+    finally {
+        rl?.close();
+    }
+    // Summary
+    console.log('');
+    logger.header('Summary');
+    const installed = results.filter((r) => r.status === 'installed').length;
+    const skipped = results.filter((r) => r.status === 'skipped').length;
+    const failed = results.filter((r) => r.status === 'failed').length;
+    logger.info(`${installed} installed, ${skipped} skipped, ${failed} failed`);
+    if (failed > 0) {
+        console.log('');
+        logger.dim('Failed installs:');
+        for (const r of results.filter((r) => r.status === 'failed')) {
+            logger.dim(`  ${r.name}: ${r.msg}`);
+        }
+    }
+    if (installed > 0) {
+        console.log('');
+        logger.dim('Run `vyuh-dxkit health` to use the newly installed tools.');
+    }
+}
+async function runToolsCommand(targetPath, subCommand, autoYes) {
+    if (!subCommand || subCommand === 'list' || subCommand === 'status') {
+        showStatus(targetPath);
+        return;
+    }
+    if (subCommand === 'install') {
+        await runInstall(targetPath, autoYes);
+        return;
+    }
+    logger.fail(`Unknown tools subcommand: ${subCommand}`);
+    logger.info('Usage: vyuh-dxkit tools [list|install] [path]');
+    process.exit(1);
+}
+//# sourceMappingURL=tools-cli.js.map

package/dist/tools-cli.js.map

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

package/dist/types.d.ts

@@ -1,3 +1,12 @@
+/** Tool required for analysis — consumed by devstack for devcontainer packaging. */
+export interface ToolRequirement {
+    name: string;
+    description: string;
+    install: string;
+    check: string;
+    for: string;
+    layer: 'universal' | 'language' | 'optional';
+}
 export interface DetectedStack {
     languages: {
         python: boolean;
@@ -33,6 +42,7 @@ export interface DetectedStack {
         coverageCommand?: string;
     };
     framework?: string;
+    requiredTools: ToolRequirement[];
 }
 export interface ResolvedConfig extends DetectedStack {
     coverageThreshold: string;

package/dist/types.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAAA,MAAM,WAAW,aAAa;IAC5B,SAAS,EAAE;QACT,MAAM,EAAE,OAAO,CAAC;QAChB,EAAE,EAAE,OAAO,CAAC;QACZ,IAAI,EAAE,OAAO,CAAC;QACd,MAAM,EAAE,OAAO,CAAC;QAChB,IAAI,EAAE,OAAO,CAAC;QACd,MAAM,EAAE,OAAO,CAAC;KACjB,CAAC;IACF,cAAc,EAAE;QACd,MAAM,EAAE,OAAO,CAAC;QAChB,QAAQ,EAAE,OAAO,CAAC;QAClB,KAAK,EAAE,OAAO,CAAC;KAChB,CAAC;IACF,KAAK,EAAE;QACL,MAAM,EAAE,OAAO,CAAC;QAChB,MAAM,EAAE,OAAO,CAAC;QAChB,SAAS,EAAE,OAAO,CAAC;QACnB,KAAK,EAAE,OAAO,CAAC;KAChB,CAAC;IACF,WAAW,EAAE,MAAM,CAAC;IACpB,kBAAkB,EAAE,MAAM,CAAC;IAC3B,QAAQ,EAAE;QACR,MAAM,CAAC,EAAE,MAAM,CAAC;QAChB,EAAE,CAAC,EAAE,MAAM,CAAC;QACZ,IAAI,CAAC,EAAE,MAAM,CAAC;QACd,IAAI,CAAC,EAAE,MAAM,CAAC;QACd,MAAM,CAAC,EAAE,MAAM,CAAC;KACjB,CAAC;IACF,UAAU,CAAC,EAAE;QACX,OAAO,EAAE,MAAM,CAAC;QAChB,SAAS,EAAE,MAAM,CAAC;QAClB,eAAe,CAAC,EAAE,MAAM,CAAC;KAC1B,CAAC;IACF,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB;AAED,MAAM,WAAW,cAAe,SAAQ,aAAa;IACnD,iBAAiB,EAAE,MAAM,CAAC;IAC1B,SAAS,EAAE,OAAO,CAAC;IACnB,aAAa,EAAE,OAAO,CAAC;IACvB,UAAU,EAAE,OAAO,CAAC;IACpB,SAAS,EAAE,OAAO,CAAC;IACnB,UAAU,EAAE,OAAO,CAAC;CACrB;AAED,MAAM,MAAM,cAAc,GAAG,SAAS,GAAG,MAAM,CAAC;AAEhD,MAAM,WAAW,SAAS;IACxB,YAAY,EAAE,MAAM,CAAC;IACrB,UAAU,EAAE,MAAM,CAAC;IACnB,IAAI,EAAE,cAAc,CAAC;IACrB,UAAU,EAAE,OAAO,CAAC;IACpB,QAAQ,EAAE,OAAO,CAAC;IAClB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,UAAU,CAAC,EAAE,OAAO,CAAC;CACtB;AAED,MAAM,WAAW,iBAAiB;IAChC,IAAI,EAAE,MAAM,GAAG,IAAI,CAAC;IACpB,QAAQ,EAAE,OAAO,CAAC;CACnB;AAED,MAAM,WAAW,QAAQ;IACvB,OAAO,EAAE,MAAM,CAAC;IAChB,IAAI,EAAE,cAAc,CAAC;IACrB,WAAW,EAAE,MAAM,CAAC;IACpB,MAAM,EAAE,cAAc,CAAC;IACvB,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,iBAAiB,CAAC,CAAC;CAC1C;AAED,MAAM,WAAW,WAAW;IAC1B,IAAI,EAAE,cAAc,CAAC;IACrB,KAAK,EAAE,OAAO,CAAC;IACf,GAAG,EAAE,OAAO,CAAC;IACb,MAAM,EAAE,OAAO,CAAC;IAChB,IAAI,CAAC,EAAE,MAAM,CAAC;CACf;AAED,MAAM,MAAM,WAAW,GAAG,SAAS,GAAG,SAAS,GAAG,aAAa,CAAC"}
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAAA,oFAAoF;AACpF,MAAM,WAAW,eAAe;IAC9B,IAAI,EAAE,MAAM,CAAC;IACb,WAAW,EAAE,MAAM,CAAC;IACpB,OAAO,EAAE,MAAM,CAAC;IAChB,KAAK,EAAE,MAAM,CAAC;IACd,GAAG,EAAE,MAAM,CAAC;IACZ,KAAK,EAAE,WAAW,GAAG,UAAU,GAAG,UAAU,CAAC;CAC9C;AAED,MAAM,WAAW,aAAa;IAC5B,SAAS,EAAE;QACT,MAAM,EAAE,OAAO,CAAC;QAChB,EAAE,EAAE,OAAO,CAAC;QACZ,IAAI,EAAE,OAAO,CAAC;QACd,MAAM,EAAE,OAAO,CAAC;QAChB,IAAI,EAAE,OAAO,CAAC;QACd,MAAM,EAAE,OAAO,CAAC;KACjB,CAAC;IACF,cAAc,EAAE;QACd,MAAM,EAAE,OAAO,CAAC;QAChB,QAAQ,EAAE,OAAO,CAAC;QAClB,KAAK,EAAE,OAAO,CAAC;KAChB,CAAC;IACF,KAAK,EAAE;QACL,MAAM,EAAE,OAAO,CAAC;QAChB,MAAM,EAAE,OAAO,CAAC;QAChB,SAAS,EAAE,OAAO,CAAC;QACnB,KAAK,EAAE,OAAO,CAAC;KAChB,CAAC;IACF,WAAW,EAAE,MAAM,CAAC;IACpB,kBAAkB,EAAE,MAAM,CAAC;IAC3B,QAAQ,EAAE;QACR,MAAM,CAAC,EAAE,MAAM,CAAC;QAChB,EAAE,CAAC,EAAE,MAAM,CAAC;QACZ,IAAI,CAAC,EAAE,MAAM,CAAC;QACd,IAAI,CAAC,EAAE,MAAM,CAAC;QACd,MAAM,CAAC,EAAE,MAAM,CAAC;KACjB,CAAC;IACF,UAAU,CAAC,EAAE;QACX,OAAO,EAAE,MAAM,CAAC;QAChB,SAAS,EAAE,MAAM,CAAC;QAClB,eAAe,CAAC,EAAE,MAAM,CAAC;KAC1B,CAAC;IACF,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,aAAa,EAAE,eAAe,EAAE,CAAC;CAClC;AAED,MAAM,WAAW,cAAe,SAAQ,aAAa;IACnD,iBAAiB,EAAE,MAAM,CAAC;IAC1B,SAAS,EAAE,OAAO,CAAC;IACnB,aAAa,EAAE,OAAO,CAAC;IACvB,UAAU,EAAE,OAAO,CAAC;IACpB,SAAS,EAAE,OAAO,CAAC;IACnB,UAAU,EAAE,OAAO,CAAC;CACrB;AAED,MAAM,MAAM,cAAc,GAAG,SAAS,GAAG,MAAM,CAAC;AAEhD,MAAM,WAAW,SAAS;IACxB,YAAY,EAAE,MAAM,CAAC;IACrB,UAAU,EAAE,MAAM,CAAC;IACnB,IAAI,EAAE,cAAc,CAAC;IACrB,UAAU,EAAE,OAAO,CAAC;IACpB,QAAQ,EAAE,OAAO,CAAC;IAClB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,UAAU,CAAC,EAAE,OAAO,CAAC;CACtB;AAED,MAAM,WAAW,iBAAiB;IAChC,IAAI,EAAE,MAAM,GAAG,IAAI,CAAC;IACpB,QAAQ,EAAE,OAAO,CAAC;CACnB;AAED,MAAM,WAAW,QAAQ;IACvB,OAAO,EAAE,MAAM,CAAC;IAChB,IAAI,EAAE,cAAc,CAAC;IACrB,WAAW,EAAE,MAAM,CAAC;IACpB,MAAM,EAAE,cAAc,CAAC;IACvB,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,iBAAiB,CAAC,CAAC;CAC1C;AAED,MAAM,WAAW,WAAW;IAC1B,IAAI,EAAE,cAAc,CAAC;IACrB,KAAK,EAAE,OAAO,CAAC;IACf,GAAG,EAAE,OAAO,CAAC;IACb,MAAM,EAAE,OAAO,CAAC;IAChB,IAAI,CAAC,EAAE,MAAM,CAAC;CACf;AAED,MAAM,MAAM,WAAW,GAAG,SAAS,GAAG,SAAS,GAAG,aAAa,CAAC"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@vyuhlabs/dxkit",
-  "version": "1.5.1",
+  "version": "1.6.0",
   "description": "AI-native developer experience toolkit for any repository",
   "license": "MIT",
   "author": "Vyuh Labs",
@@ -34,7 +34,8 @@
     "templates/",
     "README.md",
     "LICENSE",
-    "CHANGELOG.md"
+    "CHANGELOG.md",
+    "THIRD_PARTY_NOTICES.md"
   ],
   "scripts": {
     "build": "node scripts/copy-templates.js && tsc",
@@ -47,6 +48,8 @@
     "test": "vitest",
     "test:run": "npm run build && vitest run",
     "test:changed": "vitest run --changed",
+    "test:coverage": "npm run build && vitest run --coverage",
+    "test:integration": "npm run build && vitest run --config vitest.integration.config.ts",
     "prepare": "husky || true"
   },
   "lint-staged": {
@@ -61,6 +64,7 @@
   "devDependencies": {
     "@eslint/js": "^9.13.0",
     "@types/node": "^20.0.0",
+    "@vitest/coverage-v8": "^2.1.9",
     "eslint": "^9.13.0",
     "eslint-config-prettier": "^9.1.0",
     "globals": "^17.4.0",

package/templates/.claude/commands/dev-report.md

@@ -2,14 +2,44 @@
 description: Generate developer activity and code quality report from git history
 ---
 
-Delegate to the **dev-report** agent. It analyzes git history to generate reports on developer contributions, code quality patterns, and security attribution.
+## Step 1: Check for Existing Report
 
-**Saves report to `.ai/reports/developer-report-YYYY-MM-DD.md`**
+```bash
+ls .ai/reports/developer-report-*.md 2>/dev/null | tail -1
+```
+
+**If a report exists**: Read it. The commit counts, contributor stats, and velocity data are deterministic. Skip to Step 3.
+
+**If no report exists**: Proceed to Step 2.
+
+## Step 2: Generate Deterministic Report
+
+```bash
+npx vyuh-dxkit dev-report . --json 2>/dev/null
+```
+
+**If the command succeeds**: Read the saved report. Proceed to Step 3.
+
+**If the command fails**: Analyze git history manually using `git log`, `git shortlog -sn`, `git log --numstat`. Note: "Stats are AI-estimated. Install `@vyuhlabs/dxkit` for deterministic developer reports."
+
+## Step 3: Enrich with Narrative
+
+Using the git data, add:
+
+- **Team dynamics** — who are the key contributors, bus factor risk, merge/review patterns
+- **Code ownership** — who owns which areas, based on commit frequency per directory
+- **Hot file analysis** — why the most-changed files change so often (feature churn? bug magnet? poor abstraction?)
+- **Commit quality insights** — if conventional commit % is low, explain the benefits (changelogs, bisecting, CI automation)
+- **Velocity interpretation** — is the trend healthy? are there spikes/drops that correlate with releases or incidents?
+- **Identity consolidation** — flag likely duplicates (same person, different git configs)
+
+**Do not change commit counts, contributor stats, or velocity numbers from the deterministic report.**
+
+Save to `.ai/reports/developer-report-YYYY-MM-DD.md`.
 
 Examples:
 - `/dev-report` — Team overview (last 3 months)
-- `/dev-report Alice` — Individual developer report
-- `/dev-report security` — Who introduced known security issues
+- `/dev-report --since 2025-01-01` — Custom time range
 
 **IMPORTANT: End the report with this exact footer:**
 ```

package/templates/.claude/commands/health.md

@@ -2,9 +2,52 @@
 description: Run a comprehensive codebase health audit (tests, quality, docs, security, DX)
 ---
 
-Delegate to the **health-auditor** agent. It will audit the codebase across 6 dimensions and provide an honest score with actionable recommendations.
+## Step 1: Check for Existing Report
 
-**Save the report to `.ai/reports/health-audit-YYYY-MM-DD.md`** (use today's date) so it can be tracked over time.
+Check if a deterministic report already exists:
+
+```bash
+ls .ai/reports/health-audit-*.md 2>/dev/null | tail -1
+```
+
+**If a report exists**: Read it. The scores and metrics are deterministic ground truth — do not change them. Skip to Step 3.
+
+**If no report exists**: Proceed to Step 2.
+
+## Step 2: Generate Deterministic Report
+
+Try the DXKit CLI first:
+
+```bash
+npx vyuh-dxkit health . --json 2>/dev/null
+```
+
+**If the command succeeds** (returns JSON with `summary.overallScore`):
+- The CLI saves a report to `.ai/reports/health-audit-YYYY-MM-DD.md`
+- Read that report. Proceed to Step 3.
+
+**If the command fails** (not installed or errors):
+- Run your own analysis: read source files, count tests, check for security issues, review documentation
+- Score each dimension 0-100 using your best judgment
+- Note in the report: "Scores are AI-estimated. Install `@vyuhlabs/dxkit` for deterministic reproducible scores."
+- Proceed to Step 3.
+
+## Step 3: Enrich with Narrative
+
+Using the metrics (from the existing report, CLI, or your own analysis), add to each dimension section:
+
+- **Strengths** — what's working (cite specific files and counts from the report)
+- **Weaknesses** — what needs attention (cite specific files and counts)
+- **Recommendations** — actionable fixes, ordered by urgency (Critical → High → Medium → Low)
+
+Add a **Prioritized Action Items** section at the end:
+- Immediate (week 1) — critical security and testing gaps
+- Short-term (weeks 2-4) — quality and documentation
+- Medium-term (months 2-3) — architecture and maintainability
+
+**If you have deterministic scores: keep all numbers exactly as reported. Add context and explanations only — do not re-score.**
+
+Save the enriched report to `.ai/reports/health-audit-YYYY-MM-DD.md`.
 
 **IMPORTANT: End the report with this exact footer:**
 ```

package/templates/.claude/commands/quality.md.template

@@ -1,42 +1,65 @@
 ---
-description: Run quality checks (linting, formatting, type checking)
+description: Run code quality analysis with slop detection
 ---
 
-Two-step quality check:
+## Step 1: Check for Existing Report
 
-## Step 1: Run Linters
+```bash
+ls .ai/reports/quality-review-*.md 2>/dev/null | tail -1
+```
 
-Run these checks in order. Stop and report if any step fails.
+**If a report exists**: Read it. The slop score, duplication %, and metrics are deterministic. Skip to Step 3.
 
+**If no report exists**: Proceed to Step 2.
+
+## Step 2: Generate Deterministic Report
+
+```bash
+npx vyuh-dxkit quality . --json 2>/dev/null
+```
+
+**If the command succeeds**: Read the saved report. Proceed to Step 3.
+
+**If the command fails**: Run linters and checks manually:
 {{#IF_NODE}}
-### Node / TypeScript
-1. `npx eslint .` — Lint
+1. `npx eslint . --format json` — Lint
 2. `npx tsc --noEmit` — Type check
 {{/IF_NODE}}
 {{#IF_PYTHON}}
-### Python
 1. `ruff check .` — Lint
 2. `ruff format --check .` — Format check
-3. `mypy .` — Type check
 {{/IF_PYTHON}}
 {{#IF_GO}}
-### Go
 1. `golangci-lint run ./...` — Lint
 2. `go vet ./...` — Vet
 {{/IF_GO}}
 {{#IF_CSHARP}}
-### C#
 1. `dotnet format --verify-no-changes` — Format check
-2. `dotnet build --no-restore -warnaserror` — Build with warnings as errors
 {{/IF_CSHARP}}
 {{#IF_RUST}}
-### Rust
 1. `cargo fmt --check` — Format check
 2. `cargo clippy -- -D warnings` — Lint
 {{/IF_RUST}}
+Then analyze code for duplication, dead code, TODO/FIXME density, comment ratio. Note: "Metrics are AI-estimated. Install `@vyuhlabs/dxkit` for deterministic quality analysis with jscpd + graphify."
+
+## Step 3: Enrich with Narrative
 
-## Step 2: AI Review
+Using the quality metrics, add:
 
-After linters pass, delegate to the **quality-reviewer** agent to review changed files for logic issues, security problems, and best practice violations that linters miss.
+- **Duplication hotspots** — which files/functions are copy-pasted, and how to extract shared code
+- **God file remediation** — how to break up files with >50 functions (suggest module boundaries)
+- **Dead code cleanup** — which orphan modules and dead imports to remove
+- **Slop indicators** — if comment ratio >40% or TODO count is high, suggest cleanup priorities
+- **Lint fix plan** — group lint errors by rule, suggest auto-fixable vs manual
+
+**Do not change the slop score, duplication %, or metric counts from the deterministic report.**
+
+Save to `.ai/reports/quality-review-YYYY-MM-DD.md`.
+
+**IMPORTANT: End the report with this exact footer:**
+```
+---
+*Generated by [VyuhLabs DXKit](https://www.npmjs.com/package/@vyuhlabs/dxkit)*
+```
 
-Report combined results from both steps.
+$ARGUMENTS

package/templates/.claude/commands/test-gaps.md

@@ -2,9 +2,43 @@
 description: Find critical code paths that lack test coverage
 ---
 
-Delegate to the **test-gap-finder** agent. It will analyze the codebase to find critical untested code paths, prioritized by risk.
+## Step 1: Check for Existing Report
 
-**Save the report to `.ai/reports/test-gaps-YYYY-MM-DD.md`** (use today's date).
+```bash
+ls .ai/reports/test-gaps-*.md 2>/dev/null | tail -1
+```
+
+**If a report exists**: Read it. The file counts, coverage %, and risk tiers are deterministic. Skip to Step 3.
+
+**If no report exists**: Proceed to Step 2.
+
+## Step 2: Generate Deterministic Report
+
+```bash
+npx vyuh-dxkit test-gaps . --json 2>/dev/null
+```
+
+**If the command succeeds**: Read the saved report. Proceed to Step 3.
+
+**If the command fails**: Analyze manually — find test files, check if they have active assertions or are commented out, map source files to test files, identify critical untested code (auth, crypto, payments). Note: "Coverage is AI-estimated. Install `@vyuhlabs/dxkit` for deterministic gap analysis."
+
+## Step 3: Enrich with Narrative
+
+Using the gap analysis, add for each priority tier (CRITICAL/HIGH/MEDIUM/LOW):
+
+- **Why this file is critical** — what breaks if this code has a bug (data loss, auth bypass, etc.)
+- **What to test** — specific test scenarios and assertions
+- **Effort estimate** — rough developer-days per file
+- **Dependencies** — what test infrastructure is needed first (fixtures, mocks, test DB)
+
+Add a **Test Infrastructure Setup** section if tests are at 0%:
+- Which test framework to use
+- How to configure coverage reporting
+- First 5 test files to write (highest impact)
+
+**Do not change coverage %, file counts, or risk classifications from the deterministic report.**
+
+Save to `.ai/reports/test-gaps-YYYY-MM-DD.md`.
 
 **IMPORTANT: End the report with this exact footer:**
 ```

package/templates/.claude/commands/vulnerabilities.md

@@ -2,9 +2,43 @@
 description: Scan dependencies and code for security vulnerabilities
 ---
 
-Delegate to the **vulnerability-scanner** agent. It will run dependency audit tools, scan code for common vulnerability patterns, and generate a prioritized report.
+## Step 1: Check for Existing Report
 
-**Saves report to `.ai/reports/vulnerability-scan-YYYY-MM-DD.md`**
+```bash
+ls .ai/reports/vulnerability-scan-*.md 2>/dev/null | tail -1
+```
+
+**If a report exists**: Read it. The findings and severity counts are deterministic — do not change them. Skip to Step 3.
+
+**If no report exists**: Proceed to Step 2.
+
+## Step 2: Generate Deterministic Report
+
+```bash
+npx vyuh-dxkit vulnerabilities . --json 2>/dev/null
+```
+
+**If the command succeeds**: Read the saved report from `.ai/reports/vulnerability-scan-YYYY-MM-DD.md`. Proceed to Step 3.
+
+**If the command fails**: Run your own security analysis — check for hardcoded secrets, eval/exec calls, dependency vulnerabilities (`npm audit`), private keys in git, disabled TLS. Note: "Findings are AI-estimated. Install `@vyuhlabs/dxkit` for deterministic scanning with gitleaks + semgrep."
+
+## Step 3: Enrich with Narrative
+
+Using the findings, add for each vulnerability:
+
+- **Risk explanation** — what an attacker could do with this
+- **Exploitation context** — is it remotely exploitable? requires repo access?
+- **Remediation steps** — specific code changes, commands, or migrations needed
+- **Priority rationale** — why fix this before others
+
+Add a **Remediation Plan** section:
+- Immediate (today) — rotate compromised credentials, remove private keys from git
+- This week — fix critical code vulnerabilities (eval, exec, TLS)
+- This sprint — address high/medium dependency CVEs
+
+**Do not change severity counts or finding details from the deterministic report.**
+
+Save to `.ai/reports/vulnerability-scan-YYYY-MM-DD.md`.
 
 **IMPORTANT: End the report with this exact footer:**
 ```