dw-kit 1.3.0 → 1.3.5

package/src/cli.mjs

@@ -101,6 +101,33 @@ export function run(argv) {
       await dashboardCommand(opts);
     });
 
+  program
+    .command('security-scan')
+    .description('Scan project lockfile against advisory snapshot (OSV.dev). Supply-chain guard (ADR-0005, opt-in).')
+    .option('--quick', 'Offline mode — use existing snapshot only (default behavior)')
+    .option('--update-db', 'Fetch fresh advisory snapshot from OSV.dev before scanning')
+    .option('--pre-install', 'Scan package.json without lockfile (OSV name-only + namespace fixture)')
+    .option('--offline', 'Skip network in --pre-install mode (fixture-only)')
+    .option('--json', 'Output machine-readable JSON')
+    .option('--install-hook', 'Wire supply-chain-scan.sh into .claude/settings.json PostToolUse (idempotent)')
+    .option('--uninstall-hook', 'Remove supply-chain-scan.sh entry from .claude/settings.json')
+    .action(async (opts) => {
+      if (opts.installHook || opts.uninstallHook) {
+        const { installHookInProject, uninstallHookFromProject } = await import('./lib/sc-install.mjs');
+        const r = opts.uninstallHook ? uninstallHookFromProject() : installHookInProject();
+        if (!r.ok) {
+          console.error(chalk.red(`✗ ${r.error}`));
+          process.exit(1);
+        }
+        if (r.action === 'added') console.log(chalk.green(`✓ Hook wired into ${r.path}`));
+        else if (r.action === 'removed') console.log(chalk.green(`✓ Removed ${r.count} entry from ${r.path}`));
+        else console.log(chalk.dim(`  (no-op: ${r.reason})`));
+        return;
+      }
+      const { securityScanCommand } = await import('./commands/security-scan.mjs');
+      await securityScanCommand(opts);
+    });
+
   program
     .command('claude-vn-fix')
     .description('Patch Claude CLI to fix Vietnamese IME (local, with backup/restore)')

package/src/commands/doctor.mjs

@@ -4,6 +4,7 @@ import { fileURLToPath } from 'node:url';
 import { header, ok, warn, err, info, log } from '../lib/ui.mjs';
 import { loadConfig, getToolkitVersions } from '../lib/config.mjs';
 import { detectPlatform, platformLabel } from '../lib/platform.mjs';
+import { snapshotInfo } from '../lib/sc-sync.mjs';
 
 const TOOLKIT_ROOT = resolve(fileURLToPath(import.meta.url), '..', '..', '..');
 
@@ -150,6 +151,26 @@ export async function doctorCommand() {
     }
   }
 
+  info('Supply-Chain Guard (ADR-0005, opt-in)');
+  const sc = snapshotInfo(projectDir);
+  if (!sc.exists) {
+    log('  Advisory snapshot — not yet created');
+    log('  Run `dw security-scan --update-db` to fetch from OSV.dev (opt-in feature)');
+  } else {
+    if (!sc.schema_compatible) {
+      err(`Advisory snapshot schema mismatch — expected 1.0, got ${sc.schema_version || 'unknown'}`);
+      log('  Run `dw security-scan --update-db` to refresh');
+      issues++;
+    } else if (sc.stale) {
+      warn(`Advisory snapshot stale: ${sc.age_days.toFixed(1)} days old (>7d threshold)`);
+      log(`  Source: ${sc.source} (${sc.ecosystem}), advisories=${sc.advisory_count}`);
+      log('  Run `dw security-scan --update-db` to refresh');
+      warnings++;
+    } else {
+      ok(`Advisory snapshot — ${sc.age_days.toFixed(1)}d old, ${sc.advisory_count} advisories (${sc.source})`);
+    }
+  }
+
   console.log();
   header('Diagnosis');
   if (issues === 0 && warnings === 0) {

package/src/commands/init.mjs

@@ -5,6 +5,7 @@ import { banner, ok, warn, info, log, ask, choose } from '../lib/ui.mjs';
 import { buildConfig, writeConfig } from '../lib/config.mjs';
 import { copyDir, copyFile, ensureDir } from '../lib/copy.mjs';
 import { detectPlatform, platformLabel } from '../lib/platform.mjs';
+import { ensureDwGitignore, ensureClaudeGitignore } from '../lib/gitignore.mjs';
 
 const TOOLKIT_ROOT = resolve(fileURLToPath(import.meta.url), '..', '..', '..');
 
@@ -82,7 +83,7 @@ export async function initCommand(opts) {
   ok(`Platform: ${platformLabel(adapter)}`);
 
   info('Setting up project...');
-  await setupProject(projectDir, { projectName, depth, roles, language, adapter });
+  await setupProject(projectDir, { projectName, depth, roles, language, adapter, presetKey: opts.preset });
 
   printSummary({ projectName, depth, roles, language, adapter });
 }
@@ -135,7 +136,7 @@ function normalizeRolesForDepth(parsedRoles, depth) {
   return merged;
 }
 
-async function setupProject(projectDir, { projectName, depth, roles, language, adapter }) {
+async function setupProject(projectDir, { projectName, depth, roles, language, adapter, presetKey }) {
   copyCoreDocs(projectDir);
   copyConfig(projectDir, { projectName, depth, roles, language });
   copyAdapterStructure(projectDir);
@@ -143,6 +144,7 @@ async function setupProject(projectDir, { projectName, depth, roles, language, a
   if (adapter === 'claude-cli') {
     copyClaudeFiles(projectDir);
     createMinimalCLAUDEmd(projectDir, projectName);
+    await maybeInstallSupplyChainHook(projectDir, presetKey);
   } else if (adapter === 'cursor') {
     copyCursorFiles(projectDir);
     copyGenericAdapter(projectDir);
@@ -152,6 +154,47 @@ async function setupProject(projectDir, { projectName, depth, roles, language, a
 
   createRuntimeDirs(projectDir);
   updateGitignore(projectDir);
+  writeScopedGitignores(projectDir, adapter);
+}
+
+function writeScopedGitignores(projectDir, adapter) {
+  try {
+    const dwR = ensureDwGitignore(projectDir);
+    if (dwR.action !== 'noop') ok(`.dw/.gitignore ${dwR.action}`);
+    if (adapter === 'claude-cli') {
+      const cR = ensureClaudeGitignore(projectDir);
+      if (cR.action !== 'noop') ok(`.claude/.gitignore ${cR.action}`);
+    }
+  } catch (e) {
+    warn(`Scoped gitignore: ${e.message}`);
+  }
+}
+
+async function maybeInstallSupplyChainHook(projectDir, presetKey) {
+  const preset = presetKey ? PRESETS[presetKey] : null;
+  const { installHookInProject, uninstallHookFromProject } = await import('../lib/sc-install.mjs');
+
+  if (preset && preset.hooksProfile === 'safety-only') {
+    // Solo preset — explicitly uninstall hook even if template provided it (TW5: opt-in OFF)
+    const result = uninstallHookFromProject(projectDir);
+    if (result.ok && result.action === 'removed') {
+      log('  Supply-chain guard: hook removed from settings (solo preset — opt-in OFF per ADR-0005 TW5)');
+    } else {
+      log('  Supply-chain guard: skipped (solo preset — opt-in OFF per ADR-0005 TW5)');
+    }
+    log('  Enable later: `dw security-scan --install-hook`');
+    return;
+  }
+
+  const result = installHookInProject(projectDir);
+  if (!result.ok) {
+    warn(`Supply-chain hook wiring skipped: ${result.error}`);
+    return;
+  }
+  if (result.action === 'added') {
+    ok('Supply-chain guard hook wired (ADR-0005 — opt-in flag enabled)');
+    log('  First scan: `dw security-scan --update-db`');
+  }
 }
 
 function copyCoreDocs(projectDir) {

package/src/commands/metrics.mjs

@@ -1,5 +1,5 @@
 import { readEvents, summarize } from '../lib/telemetry.mjs';
-import { analyze, THRESHOLDS } from '../lib/cut-analysis.mjs';
+import { analyze, analyzeTaskDocs, THRESHOLDS, TASK_DOC_THRESHOLDS } from '../lib/cut-analysis.mjs';
 import { banner, log, info, warn, ok, err } from '../lib/ui.mjs';
 import chalk from 'chalk';
 
@@ -162,4 +162,24 @@ function cutAnalysisReport(opts) {
   log(`  Hook:  avg_latency > ${THRESHOLDS.hook.maxAvgLatencyMs}ms OR fires/session > ${THRESHOLDS.hook.maxFiresPerSession}`);
   log('');
   info('Caveat: "devs" proxied by unique session hashes — undercounts real headcount.');
+
+  // Task doc health — invalidation trigger for 3→2 file consolidation (ADR-0001)
+  const td = analyzeTaskDocs(process.cwd());
+  if (td && td.totalTasks > 0) {
+    log('');
+    log(chalk.bold('Task Doc Health (ADR-0001 invalidation signal for 3→2 consolidation)'));
+    log(`  Tasks total: ${td.totalTasks}  (v2=${td.v2Count}, v1=${td.v1Count})`);
+    log(`  tracking.md lines: avg=${td.avgTrackingLines}  max=${td.maxTrackingLines}`);
+    log(`  Tasks with ≥3 md files: ${td.extraFilesCount} (${td.extraFilesPct}%)`);
+    if (td.triggers.length === 0) {
+      ok('No task-doc invalidation triggers fired — 3→2 consolidation holding.');
+    } else {
+      for (const t of td.triggers) {
+        err(t);
+      }
+    }
+    log('');
+    info('Task doc thresholds:');
+    log(`  avg_tracking_lines > ${TASK_DOC_THRESHOLDS.trackingLinesWarn}  OR  pct_tasks_with_3plus_files > ${TASK_DOC_THRESHOLDS.extraFilesPctWarn}%`);
+  }
 }

package/src/commands/security-scan.mjs

@@ -0,0 +1,427 @@
+import { existsSync, readFileSync } from 'node:fs';
+import { join, resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { banner, log, info, warn, ok, err } from '../lib/ui.mjs';
+import chalk from 'chalk';
+import {
+  loadSnapshot,
+  snapshotInfo,
+  syncSnapshotForProject,
+  isStale,
+  isSchemaCompatible,
+  fetchOsvByName,
+} from '../lib/sc-sync.mjs';
+import {
+  scanProject,
+  severityRank,
+  worstSeverity,
+  parsePackageJson,
+  findPackageJson,
+  matchPackageByName,
+  matchNamespaceFixture,
+} from '../lib/sc-scanner.mjs';
+import { logEvent } from '../lib/telemetry.mjs';
+
+const TOOLKIT_ROOT = resolve(fileURLToPath(import.meta.url), '..', '..', '..');
+const NAMESPACE_FIXTURE_REL = '.dw/security/ioc-namespaces.json';
+
+export async function securityScanCommand(opts) {
+  const rootDir = process.cwd();
+  const mode = pickMode(opts);
+
+  if (mode === 'pre-install') {
+    return runPreInstallMode(rootDir, opts);
+  }
+
+  if (opts.json) {
+    return runJsonMode(rootDir, mode, opts);
+  }
+
+  banner('dw-kit Supply-Chain Scan');
+
+  if (mode === 'update-db' || opts.updateDb) {
+    info('Fetching fresh advisory snapshot from OSV.dev...');
+    try {
+      const start = Date.now();
+      const res = await syncSnapshotForProject(rootDir);
+      const elapsed = Date.now() - start;
+      ok(`Snapshot updated — ${res.advisoryCount} advisories for ${res.packageCount} packages (${elapsed}ms)`);
+      logEvent({ event: 'sc_guard', action: 'sync', advisories: res.advisoryCount, packages: res.packageCount, latency_ms: elapsed }, rootDir);
+    } catch (e) {
+      err(`Sync failed: ${e.message}`);
+      if (e.code === 'NO_LOCKFILE') warn('Run `npm install` first to create package-lock.json.');
+      process.exit(2);
+    }
+    if (mode === 'update-db') {
+      log('');
+      info('Snapshot ready. Run `dw security-scan` to scan project.');
+      return;
+    }
+    log('');
+  }
+
+  const info_ = snapshotInfo(rootDir);
+  if (!info_.exists) {
+    warn('No advisory snapshot found.');
+    log('Run `dw security-scan --update-db` to fetch from OSV.dev.');
+    log('Quick mode requires an existing snapshot.');
+    process.exit(1);
+  }
+
+  const ageDays = info_.age_days;
+  const ageLabel = ageDays === Infinity ? 'unknown' : `${ageDays.toFixed(1)} days old`;
+  log(chalk.bold('Snapshot'));
+  log(`  Source     : ${info_.source} (${info_.ecosystem})`);
+  log(`  Fetched    : ${info_.fetched_at || '?'} (${ageLabel})`);
+  log(`  Advisories : ${info_.advisory_count}  Packages scanned previously: ${info_.package_count}`);
+  if (!info_.schema_compatible) {
+    err(`  Schema mismatch — expected 1.0, got ${info_.schema_version || 'unknown'}`);
+    log('  Run `dw security-scan --update-db` to refresh.');
+    process.exit(2);
+  }
+  if (info_.stale) {
+    warn(`  Snapshot is stale (>7 days). Run \`dw security-scan --update-db\` to refresh.`);
+  }
+
+  log('');
+  log(chalk.bold('Scanning project lockfile...'));
+  const snap = loadSnapshot(rootDir);
+  const start = Date.now();
+  const result = scanProject(rootDir, snap);
+  const elapsed = Date.now() - start;
+
+  if (result.error === 'no_lockfile') {
+    err('No lockfile found (expected package-lock.json).');
+    process.exit(1);
+  }
+  if (result.error === 'no_snapshot') {
+    err('Snapshot data unavailable.');
+    process.exit(1);
+  }
+
+  log(`  Lockfile          : ${result.lockfile}`);
+  log(`  Packages scanned  : ${result.packages_scanned}`);
+  log(`  Elapsed           : ${elapsed}ms`);
+  log('');
+
+  if (result.matches.length === 0) {
+    ok('No advisory matches — clean.');
+    logEvent({ event: 'sc_guard', action: 'scan_run', matches: 0, packages: result.packages_scanned, outcome: 'clean', latency_ms: elapsed }, rootDir);
+    log('');
+    advisoryFooter();
+    return;
+  }
+
+  log(chalk.bold(`Matches (${result.matches.length})`));
+  const sorted = result.matches.slice().sort((a, b) => severityRank(b.severity) - severityRank(a.severity));
+  for (const m of sorted) {
+    const tag = severityTag(m.severity);
+    log(`  ${tag} ${m.package}@${m.version}`);
+    if (m.summary) log(chalk.dim(`      ${m.summary}`));
+    log(chalk.dim(`      advisory: ${m.advisory_id}`));
+    if (m.fix_versions.length) log(chalk.dim(`      fix:      ${m.fix_versions.join(', ')}`));
+  }
+  log('');
+
+  const worst = worstSeverity(result.matches);
+  const blockCount = result.matches.filter((m) => severityRank(m.severity) >= severityRank('high')).length;
+  const exitCode = blockCount > 0 ? 2 : 1;
+
+  logEvent(
+    {
+      event: 'sc_guard',
+      action: blockCount > 0 ? 'block' : 'allow',
+      matches: result.matches.length,
+      block_count: blockCount,
+      worst_severity: worst,
+      packages: result.packages_scanned,
+      latency_ms: elapsed,
+      snapshot_age_days: ageDays,
+    },
+    rootDir,
+  );
+
+  if (blockCount > 0) {
+    err(`${blockCount} HIGH+ severity match(es) — review before merging lockfile changes.`);
+  } else {
+    warn(`${result.matches.length} low/medium match(es) — review recommended.`);
+  }
+  log('');
+  advisoryFooter();
+  process.exit(exitCode);
+}
+
+function pickMode(opts) {
+  if (opts.preInstall) return 'pre-install';
+  if (opts.updateDb) return 'update-db';
+  return 'scan';
+}
+
+function loadNamespaceFixture(rootDir) {
+  // Prefer project-local fixture, fall back to toolkit-bundled
+  const candidates = [
+    join(rootDir, NAMESPACE_FIXTURE_REL),
+    join(TOOLKIT_ROOT, NAMESPACE_FIXTURE_REL),
+  ];
+  for (const p of candidates) {
+    if (existsSync(p)) {
+      try {
+        return { fixture: JSON.parse(readFileSync(p, 'utf-8')), path: p };
+      } catch {
+        // skip malformed
+      }
+    }
+  }
+  return { fixture: null, path: null };
+}
+
+async function runPreInstallMode(rootDir, opts) {
+  const useJson = !!opts.json;
+  const out = { mode: 'pre-install', ok: true, network_ok: false, packages: 0, osv_hits: [], namespace_hits: [] };
+
+  const pkgPath = findPackageJson(rootDir);
+  if (!pkgPath) {
+    if (useJson) {
+      out.ok = false;
+      out.error = { code: 'NO_PACKAGE_JSON', message: 'No package.json in current directory' };
+      process.stdout.write(JSON.stringify(out) + '\n');
+      process.exit(1);
+    }
+    err('No package.json in current directory.');
+    process.exit(1);
+  }
+
+  let packages;
+  try {
+    packages = parsePackageJson(pkgPath);
+  } catch (e) {
+    if (useJson) {
+      out.ok = false;
+      out.error = { code: 'PARSE_FAILED', message: e.message };
+      process.stdout.write(JSON.stringify(out) + '\n');
+      process.exit(1);
+    }
+    err(`Failed to parse package.json: ${e.message}`);
+    process.exit(1);
+  }
+
+  out.packages = packages.size;
+
+  if (!useJson) {
+    banner('dw-kit Pre-Install Scan');
+    log(chalk.bold('package.json'));
+    log(`  Path     : ${pkgPath}`);
+    log(`  Declared : ${packages.size} packages (across deps/devDeps/peerDeps/optionalDeps)`);
+    log('');
+  }
+
+  // 1. Namespace fixture (offline, fast)
+  const fixtureBundle = loadNamespaceFixture(rootDir);
+  if (fixtureBundle.fixture) {
+    const hits = matchNamespaceFixture(packages, fixtureBundle.fixture);
+    out.namespace_hits = hits;
+    out.fixture_path = fixtureBundle.path;
+    if (!useJson) {
+      log(chalk.bold('Namespace IoC fixture'));
+      log(`  Source   : ${fixtureBundle.path}`);
+      log(`  Entries  : ${(fixtureBundle.fixture.namespaces || []).length} active namespace pattern(s)`);
+      if (hits.length === 0) {
+        ok('  No matches against active namespace patterns');
+      } else {
+        log('');
+        for (const h of hits) {
+          log(`  ${severityTag(h.severity)} ${h.package} matches pattern "${h.namespace_pattern}"`);
+          if (h.reason) log(chalk.dim(`      ${h.reason}`));
+          if (h.guidance) log(chalk.yellow(`      guidance: ${h.guidance}`));
+          if (h.advisory_url) log(chalk.dim(`      advisory: ${h.advisory_url}`));
+        }
+      }
+      log('');
+    }
+  }
+
+  // 2. OSV.dev name-only queries (network, optional)
+  if (!opts.offline) {
+    if (!useJson) log(chalk.bold('OSV.dev name-only query (per declared package)'));
+    const osvErrors = [];
+    let queried = 0;
+    for (const [name] of packages) {
+      try {
+        const result = await fetchOsvByName(name, 'npm', { timeoutMs: 5000 });
+        queried++;
+        const vulns = (result && result.vulns) || [];
+        if (vulns.length > 0) {
+          const hits = matchPackageByName(name, vulns);
+          for (const h of hits) {
+            out.osv_hits.push({ package: name, declared_range: packages.get(name), ...h });
+          }
+        }
+      } catch (e) {
+        osvErrors.push({ package: name, error: e.message });
+      }
+    }
+    out.network_ok = queried > 0;
+    out.osv_queried = queried;
+    out.osv_errors = osvErrors;
+
+    if (!useJson) {
+      log(`  Queried  : ${queried}/${packages.size} packages (${osvErrors.length} errors)`);
+      if (out.osv_hits.length === 0) {
+        ok('  No active advisories for declared packages');
+      } else {
+        const grouped = groupBy(out.osv_hits, 'package');
+        log('');
+        for (const [pkg, hits] of Object.entries(grouped)) {
+          const worst = hits.reduce(
+            (acc, h) => (severityRank(h.severity) > severityRank(acc) ? h.severity : acc),
+            'unknown',
+          );
+          log(`  ${severityTag(worst)} ${pkg}@${packages.get(pkg)} — ${hits.length} active advisory(s)`);
+          for (const h of hits.slice(0, 3)) {
+            log(chalk.dim(`      ${h.advisory_id}: ${h.summary || '(no summary)'}`));
+            if (h.fix_versions && h.fix_versions.length) {
+              log(chalk.dim(`        fix: ${h.fix_versions.slice(0, 3).join(', ')}`));
+            }
+          }
+          if (hits.length > 3) log(chalk.dim(`      ... and ${hits.length - 3} more`));
+        }
+      }
+      log('');
+    }
+  } else if (!useJson) {
+    log(chalk.dim('  OSV.dev query: skipped (--offline)'));
+    log('');
+  }
+
+  // Summarize
+  const namespaceCrit = out.namespace_hits.length;
+  const osvHigh = out.osv_hits.filter((h) => severityRank(h.severity) >= severityRank('high')).length;
+  const exitCode = namespaceCrit > 0 ? 2 : (osvHigh > 0 ? 2 : (out.osv_hits.length > 0 ? 1 : 0));
+
+  logEvent(
+    {
+      event: 'sc_guard',
+      action: exitCode >= 2 ? 'block' : (exitCode === 1 ? 'allow' : 'scan_run'),
+      sub_mode: 'pre-install',
+      packages: packages.size,
+      namespace_hits: namespaceCrit,
+      osv_hits: out.osv_hits.length,
+      osv_high: osvHigh,
+      network_ok: out.network_ok,
+    },
+    rootDir,
+  );
+
+  if (useJson) {
+    out.summary = { namespace_hits: namespaceCrit, osv_hits: out.osv_hits.length, osv_high: osvHigh, exit_code: exitCode };
+    process.stdout.write(JSON.stringify(out) + '\n');
+    process.exit(exitCode);
+  }
+
+  log(chalk.bold('Summary'));
+  if (exitCode === 0) {
+    ok(`Clean — ${packages.size} packages scanned, no matches`);
+  } else if (exitCode === 1) {
+    warn(`${out.osv_hits.length} low/medium advisor(y/ies) found — review recommended`);
+  } else {
+    err(`${namespaceCrit} namespace match(es) + ${osvHigh} HIGH+ advisory(s) — rotate credentials if already installed`);
+  }
+  log('');
+  advisoryFooter();
+  process.exit(exitCode);
+}
+
+function groupBy(arr, key) {
+  const out = {};
+  for (const item of arr) {
+    const k = item[key];
+    if (!out[k]) out[k] = [];
+    out[k].push(item);
+  }
+  return out;
+}
+
+function severityTag(label) {
+  switch (label) {
+    case 'critical':
+      return chalk.red.bold('[CRITICAL]'.padEnd(12));
+    case 'high':
+      return chalk.red('[HIGH]    '.padEnd(12));
+    case 'medium':
+      return chalk.yellow('[MEDIUM]  '.padEnd(12));
+    case 'low':
+      return chalk.blue('[LOW]     '.padEnd(12));
+    default:
+      return chalk.dim('[?]       '.padEnd(12));
+  }
+}
+
+function advisoryFooter() {
+  info('ADVISORY OUTPUT — NOT a decision rule.');
+  log('  Threshold matrix in v14-evaluation-protocol.md is authoritative.');
+  log('  Use this scan as evidence-supplement only.');
+  log('  Public sunset commitment: 2026-08-12 (see ADR-0005).');
+}
+
+async function runJsonMode(rootDir, mode, opts) {
+  let out = { mode, ok: true };
+
+  if (mode === 'update-db' || opts.updateDb) {
+    try {
+      const start = Date.now();
+      const res = await syncSnapshotForProject(rootDir);
+      out.sync = { advisory_count: res.advisoryCount, package_count: res.packageCount, latency_ms: Date.now() - start };
+      logEvent({ event: 'sc_guard', action: 'sync', advisories: res.advisoryCount, packages: res.packageCount }, rootDir);
+    } catch (e) {
+      out.ok = false;
+      out.error = { code: e.code || 'SYNC_FAILED', message: e.message };
+      process.stdout.write(JSON.stringify(out) + '\n');
+      process.exit(2);
+    }
+    if (mode === 'update-db') {
+      process.stdout.write(JSON.stringify(out) + '\n');
+      return;
+    }
+  }
+
+  const info_ = snapshotInfo(rootDir);
+  out.snapshot = info_;
+  if (!info_.exists) {
+    out.ok = false;
+    out.error = { code: 'NO_SNAPSHOT', message: 'Run `dw security-scan --update-db`' };
+    process.stdout.write(JSON.stringify(out) + '\n');
+    process.exit(1);
+  }
+
+  const snap = loadSnapshot(rootDir);
+  const start = Date.now();
+  const result = scanProject(rootDir, snap);
+  out.scan = { ...result, elapsed_ms: Date.now() - start };
+
+  if (result.error) {
+    out.ok = false;
+    out.error = { code: result.error.toUpperCase(), message: result.error };
+    process.stdout.write(JSON.stringify(out) + '\n');
+    process.exit(1);
+  }
+
+  const worst = worstSeverity(result.matches);
+  const blockCount = result.matches.filter((m) => severityRank(m.severity) >= severityRank('high')).length;
+  out.summary = { matches: result.matches.length, block_count: blockCount, worst_severity: worst };
+
+  logEvent(
+    {
+      event: 'sc_guard',
+      action: blockCount > 0 ? 'block' : (result.matches.length > 0 ? 'allow' : 'scan_run'),
+      matches: result.matches.length,
+      block_count: blockCount,
+      worst_severity: worst,
+      packages: result.packages_scanned,
+      snapshot_age_days: info_.age_days,
+    },
+    rootDir,
+  );
+
+  process.stdout.write(JSON.stringify(out) + '\n');
+  process.exit(blockCount > 0 ? 2 : result.matches.length > 0 ? 1 : 0);
+}

package/src/commands/upgrade.mjs

@@ -4,6 +4,7 @@ import { fileURLToPath } from 'node:url';
 import { header, ok, warn, err, info, log, dry } from '../lib/ui.mjs';
 import { loadConfig, writeConfig, getToolkitVersions } from '../lib/config.mjs';
 import { diffDirs, copyDir, copyFile } from '../lib/copy.mjs';
+import { ensureDwGitignore, ensureClaudeGitignore } from '../lib/gitignore.mjs';
 
 const TOOLKIT_ROOT = resolve(fileURLToPath(import.meta.url), '..', '..', '..');
 
@@ -57,6 +58,7 @@ export async function upgradeCommand(opts) {
 
   upgradeScripts(projectDir, opts);
   upgradeConfigSchema(projectDir, opts);
+  upgradeScopedGitignores(projectDir, opts);
 
   if (!opts.dryRun && totalChanges > 0) {
     updateVersionTracking(configPath, projectConfig, toolkitVersions);
@@ -169,6 +171,7 @@ function mergeSettingsJson(projectDir, opts) {
 
   if (opts.dryRun) {
     dry('merge .claude/settings.json');
+    dry('post-merge: wire supply-chain-scan.sh hook if missing (idempotent)');
     return;
   }
 
@@ -181,6 +184,57 @@ function mergeSettingsJson(projectDir, opts) {
   } catch (e) {
     warn(`settings.json merge failed: ${e.message}`);
   }
+
+  // Post-merge: explicitly install supply-chain-scan hook (ADR-0005, idempotent).
+  // deepMerge replaces arrays, so user's PostToolUse array may not contain the new
+  // hook entry. We must add it explicitly. Respects existing wiring.
+  installSupplyChainHookOnUpgrade(projectDir, opts);
+}
+
+function upgradeScopedGitignores(projectDir, opts) {
+  info('Scoped .gitignore (.dw/, .claude/)');
+  if (opts.dryRun) {
+    dry('refresh .dw/.gitignore + .claude/.gitignore managed blocks');
+    return;
+  }
+  try {
+    const dwR = ensureDwGitignore(projectDir);
+    if (dwR.action === 'noop') log('  .dw/.gitignore: up to date');
+    else ok(`.dw/.gitignore: ${dwR.action}`);
+
+    if (existsSync(join(projectDir, '.claude'))) {
+      const cR = ensureClaudeGitignore(projectDir);
+      if (cR.action === 'noop') log('  .claude/.gitignore: up to date');
+      else ok(`.claude/.gitignore: ${cR.action}`);
+    }
+  } catch (e) {
+    warn(`Scoped gitignore: ${e.message}`);
+  }
+}
+
+function installSupplyChainHookOnUpgrade(projectDir, opts) {
+  if (opts.dryRun) return;
+  try {
+    const configPath = join(projectDir, '.dw', 'config', 'dw.config.yml');
+    if (existsSync(configPath)) {
+      const cfg = readFileSync(configPath, 'utf-8');
+      if (/depth:\s*quick/i.test(cfg) && !/roles:\s*\[?\s*dev\s*,/i.test(cfg)) {
+        // Heuristic: solo preset → skip per ADR-0005 TW5
+        log('  Supply-chain hook: skipped (solo-style preset detected)');
+        log('  Enable later: `dw security-scan --install-hook`');
+        return;
+      }
+    }
+  } catch { /* fall through */ }
+
+  // Defer import (avoid loading at module top) for clean test isolation
+  import('../lib/sc-install.mjs').then((m) => {
+    const result = m.installHookInProject(projectDir);
+    if (result.ok && result.action === 'added') {
+      ok('Supply-chain guard hook wired (ADR-0005 — opt-in available since v1.3.5)');
+      log('  First scan: `dw security-scan --update-db`');
+    }
+  }).catch(() => { /* silent — installation is best-effort */ });
 }
 
 function deepMerge(base, override) {