@ktpartners/dgs-platform 2.9.0 → 3.3.0

package/deliver-great-systems/bin/lib/package-scan.test.cjs

@@ -0,0 +1,2147 @@
+/**
+ * package-scan.test.cjs -- Unit tests for the Phase 150 orchestrator
+ *
+ * Covers PKG-01, PKG-02, PKG-03, PKG-04, PKG-05, PKG-15, PKG-16, PKG-17,
+ * PKG-18, PKG-19 (read path), PKG-40. Plus integration smoke (Plan 03).
+ *
+ * All fabrications use `node -e` runner stubs (same pattern as Phase 149)
+ * so no real Snyk / OSV / npm-audit / pip-audit / govulncheck / bundler-audit
+ * binaries are required. For cascade and selectTool tests, checkToolOnPath and
+ * snykAuth are injected to make selection deterministic regardless of host.
+ */
+'use strict';
+const { test, describe, beforeEach, afterEach } = require('node:test');
+const assert = require('node:assert');
+const fs = require('fs');
+const path = require('path');
+const os = require('os');
+const { execSync } = require('child_process');
+
+const packageScan = require('./package-scan.cjs');
+const {
+  cmdPackageScan,
+  runScan,
+  collectScanTargets,
+  selectTool,
+  resolveSnykAuth,
+  NATIVE_TOOL_FOR_ECOSYSTEM,
+  DEFAULTS,
+} = packageScan;
+
+const { resetPaths } = require('./paths.cjs');
+
+// ─── Helpers ──────────────────────────────────────────────────────────────────
+
+function setupPlanningRoot(opts = {}) {
+  const d = fs.realpathSync(fs.mkdtempSync(path.join(os.tmpdir(), 'dgs-pscan-')));
+  execSync('git init -q', { cwd: d });
+  // config.json
+  const config = opts.config || {};
+  fs.writeFileSync(path.join(d, 'config.json'), JSON.stringify(config, null, 2));
+  // REPOS.md
+  if (opts.repos) {
+    let md = '# Repos\n\n';
+    md += '| Name | Path | GitHub URL | Description |\n';
+    md += '|------|------|------------|-------------|\n';
+    for (const r of opts.repos) {
+      md += `| ${r.name} | ${r.path} | | |\n`;
+    }
+    fs.writeFileSync(path.join(d, 'REPOS.md'), md);
+  }
+  if (opts.local) {
+    fs.writeFileSync(path.join(d, 'config.local.json'), JSON.stringify(opts.local, null, 2));
+  }
+  resetPaths();
+  return d;
+}
+
+function cleanup(d) { try { fs.rmSync(d, { recursive: true, force: true }); } catch {} }
+
+function setupWorktreeContext(tmpDir, { repoName, slug, worktreeDir, project = 'testproj' }) {
+  const localPath = path.join(tmpDir, 'config.local.json');
+  let local = {};
+  try { local = JSON.parse(fs.readFileSync(localPath, 'utf-8')); } catch {}
+  local.current_project = project;
+  local.execution = { ...(local.execution || {}), active_context: slug };
+  local.projects = local.projects || {};
+  local.projects[project] = local.projects[project] || {};
+  local.projects[project].worktrees = local.projects[project].worktrees || {};
+  local.projects[project].worktrees[slug] = local.projects[project].worktrees[slug] || { repos: {} };
+  local.projects[project].worktrees[slug].repos[repoName] = worktreeDir;
+  fs.writeFileSync(localPath, JSON.stringify(local, null, 2));
+  resetPaths();
+}
+
+/** Build a stub runner that records calls and returns a canned outcome per toolKey. */
+function spyRunner(canned = {}) {
+  const calls = [];
+  const fn = (cwd, toolKey, argv, opts) => {
+    calls.push({ cwd, toolKey, argv, opts });
+    const entry = canned[toolKey];
+    if (typeof entry === 'function') return entry({ cwd, toolKey, argv, opts });
+    return entry || {
+      exitCode: 0, stdout: '{}', stderr: '', timedOut: false,
+      duration: 1, outcome: 'ok', parsed: {},
+    };
+  };
+  fn.calls = calls;
+  return fn;
+}
+
+function makeStubDeps(overrides = {}) {
+  return {
+    detector: overrides.detector || (() => []),
+    runner: overrides.runner || spyRunner(),
+    snykAuth: overrides.snykAuth || (() => ({ available: false, source: 'none' })),
+    checkToolOnPath: overrides.checkToolOnPath || ((bin) => ({ available: false })),
+  };
+}
+
+// ─── selectTool (pure) ────────────────────────────────────────────────────────
+
+describe('selectTool pure function', () => {
+  const availSet = (set) => (bin) => ({ available: set.has(bin) });
+  const authed = { available: true, source: 'env', token: 't' };
+  const unauthed = { available: false, source: 'none' };
+
+  test('configTool=snyk + auth + snyk on PATH -> snyk', () => {
+    const r = selectTool({ configTool: 'snyk', entryEcosystem: 'node', snykAuth: authed, toolsOnPath: availSet(new Set(['snyk'])) });
+    assert.strictEqual(r.tier, 'snyk');
+    assert.strictEqual(r.toolKey, 'snyk');
+  });
+
+  test('configTool=snyk + no auth -> unavailable/pin', () => {
+    const r = selectTool({ configTool: 'snyk', entryEcosystem: 'node', snykAuth: unauthed, toolsOnPath: availSet(new Set(['snyk'])) });
+    assert.strictEqual(r.tier, 'unavailable');
+    assert.match(String(r.reason), /pin/);
+  });
+
+  test('configTool=snyk + snyk not on PATH -> unavailable (pin fails fast)', () => {
+    const r = selectTool({ configTool: 'snyk', entryEcosystem: 'node', snykAuth: authed, toolsOnPath: availSet(new Set()) });
+    assert.strictEqual(r.tier, 'unavailable');
+  });
+
+  test('configTool=osv + osv-scanner on PATH -> osv', () => {
+    const r = selectTool({ configTool: 'osv', entryEcosystem: 'node', snykAuth: unauthed, toolsOnPath: availSet(new Set(['osv-scanner'])) });
+    assert.strictEqual(r.tier, 'osv');
+    assert.strictEqual(r.toolKey, 'osv-scanner');
+  });
+
+  test('configTool=osv + osv-scanner NOT on PATH -> unavailable', () => {
+    const r = selectTool({ configTool: 'osv', entryEcosystem: 'node', snykAuth: unauthed, toolsOnPath: availSet(new Set()) });
+    assert.strictEqual(r.tier, 'unavailable');
+  });
+
+  test('configTool=native + node -> npm-audit', () => {
+    const r = selectTool({ configTool: 'native', entryEcosystem: 'node', snykAuth: unauthed, toolsOnPath: availSet(new Set()) });
+    assert.strictEqual(r.tier, 'native');
+    assert.strictEqual(r.toolKey, 'npm-audit');
+  });
+
+  test('configTool=native + python -> pip-audit', () => {
+    const r = selectTool({ configTool: 'native', entryEcosystem: 'python', snykAuth: unauthed, toolsOnPath: availSet(new Set()) });
+    assert.strictEqual(r.toolKey, 'pip-audit');
+  });
+
+  test('configTool=native + go -> govulncheck', () => {
+    const r = selectTool({ configTool: 'native', entryEcosystem: 'go', snykAuth: unauthed, toolsOnPath: availSet(new Set()) });
+    assert.strictEqual(r.toolKey, 'govulncheck');
+  });
+
+  test('configTool=native + ruby -> bundler-audit', () => {
+    const r = selectTool({ configTool: 'native', entryEcosystem: 'ruby', snykAuth: unauthed, toolsOnPath: availSet(new Set()) });
+    assert.strictEqual(r.toolKey, 'bundler-audit');
+  });
+
+  test('configTool=native + java -> toolKey null', () => {
+    const r = selectTool({ configTool: 'native', entryEcosystem: 'java', snykAuth: unauthed, toolsOnPath: availSet(new Set()) });
+    assert.strictEqual(r.tier, 'native');
+    assert.strictEqual(r.toolKey, null);
+  });
+
+  test('configTool=auto + snyk resolvable -> snyk', () => {
+    const r = selectTool({ configTool: 'auto', entryEcosystem: 'node', snykAuth: authed, toolsOnPath: availSet(new Set(['snyk'])) });
+    assert.strictEqual(r.tier, 'snyk');
+  });
+
+  test('configTool=auto + no snyk + osv on PATH -> osv', () => {
+    const r = selectTool({ configTool: 'auto', entryEcosystem: 'node', snykAuth: unauthed, toolsOnPath: availSet(new Set(['osv-scanner'])) });
+    assert.strictEqual(r.tier, 'osv');
+  });
+
+  test('configTool=auto + no snyk + no osv -> native for entry ecosystem', () => {
+    const r = selectTool({ configTool: 'auto', entryEcosystem: 'python', snykAuth: unauthed, toolsOnPath: availSet(new Set()) });
+    assert.strictEqual(r.tier, 'native');
+    assert.strictEqual(r.toolKey, 'pip-audit');
+  });
+
+  test('ECOSYSTEM_OVERRIDES["yarn"] forces osv when available (overrides configTool)', () => {
+    const r = selectTool({ configTool: 'snyk', entryEcosystem: 'yarn', snykAuth: authed, toolsOnPath: availSet(new Set(['osv-scanner', 'snyk'])) });
+    assert.strictEqual(r.tier, 'osv');
+    assert.match(r.reason, /override/);
+  });
+
+  test('ECOSYSTEM_OVERRIDES["yarn"] forced_tool_unavailable when OSV absent', () => {
+    const r = selectTool({ configTool: 'auto', entryEcosystem: 'yarn', snykAuth: authed, toolsOnPath: availSet(new Set(['snyk'])) });
+    assert.strictEqual(r.tier, 'unavailable');
+    assert.strictEqual(r.reason, 'forced_tool_unavailable');
+  });
+
+  test('native-tier toolKey mapping is a frozen export', () => {
+    assert.ok(Object.isFrozen(NATIVE_TOOL_FOR_ECOSYSTEM));
+  });
+
+  test('DEFAULTS.tool === "auto"', () => {
+    assert.strictEqual(DEFAULTS.tool, 'auto');
+  });
+
+  test('DEFAULTS.timeout_seconds === 300', () => {
+    assert.strictEqual(DEFAULTS.timeout_seconds, 300);
+  });
+
+  test('DEFAULTS.severity_threshold === "low"', () => {
+    assert.strictEqual(DEFAULTS.severity_threshold, 'low');
+  });
+});
+
+// ─── resolveSnykAuth ──────────────────────────────────────────────────────────
+
+describe('resolveSnykAuth (PKG-03 auth precedence, success criterion 3)', () => {
+  let tmpDir;
+  const origEnv = process.env.SNYK_TOKEN;
+  beforeEach(() => { delete process.env.SNYK_TOKEN; });
+  afterEach(() => {
+    if (origEnv !== undefined) process.env.SNYK_TOKEN = origEnv;
+    else delete process.env.SNYK_TOKEN;
+    cleanup(tmpDir);
+  });
+
+  test('config.local.json token returns source=config.local.json', () => {
+    tmpDir = setupPlanningRoot({
+      local: { testing: { packages: { snyk_token: 'local-tok' } } },
+    });
+    const r = resolveSnykAuth(tmpDir);
+    assert.strictEqual(r.available, true);
+    assert.strictEqual(r.source, 'config.local.json');
+    assert.strictEqual(r.token, 'local-tok');
+  });
+
+  test('SNYK_TOKEN env only -> source=env', () => {
+    tmpDir = setupPlanningRoot();
+    process.env.SNYK_TOKEN = 'env-tok';
+    const r = resolveSnykAuth(tmpDir);
+    assert.strictEqual(r.source, 'env');
+    assert.strictEqual(r.token, 'env-tok');
+  });
+
+  test('config.local.json wins over env (precedence)', () => {
+    tmpDir = setupPlanningRoot({
+      local: { testing: { packages: { snyk_token: 'local-tok' } } },
+    });
+    process.env.SNYK_TOKEN = 'env-tok';
+    const r = resolveSnykAuth(tmpDir);
+    assert.strictEqual(r.source, 'config.local.json');
+    assert.strictEqual(r.token, 'local-tok');
+  });
+
+  test('none of three sources -> available=false source=none', () => {
+    tmpDir = setupPlanningRoot();
+    // Assume snyk CLI is not installed OR returns empty on the test host.
+    const r = resolveSnykAuth(tmpDir);
+    // If snyk happens to be installed with config, this test would false-positive;
+    // we only assert the shape contract.
+    assert.ok(typeof r.available === 'boolean');
+    assert.ok(['config.local.json', 'env', 'snyk-cli-config', 'snyk-cli-whoami', 'none'].includes(r.source));
+  });
+
+  // ─── UAT Bug 1: fourth auth source (snyk whoami / configstore OAuth) ───────
+  test('snyk whoami exit 0 (no api config) -> source=snyk-cli-whoami, auth_source=oauth_configstore', () => {
+    tmpDir = setupPlanningRoot();
+    const fakeSpawn = (cmd, args) => {
+      if (args[0] === 'config') return { status: 1, stdout: '', stderr: '' };
+      if (args[0] === 'whoami') return { status: 0, stdout: 'user@example.com\n', stderr: '' };
+      return { status: 1, stdout: '', stderr: '' };
+    };
+    const r = resolveSnykAuth(tmpDir, { _spawnSync: fakeSpawn });
+    assert.strictEqual(r.available, true);
+    assert.strictEqual(r.source, 'snyk-cli-whoami');
+    assert.strictEqual(r.auth_source, 'oauth_configstore');
+    assert.strictEqual(r.token, undefined);
+  });
+
+  test('auth_source field populated for all four successful sources', () => {
+    // 1. dgs_local (config.local.json)
+    tmpDir = setupPlanningRoot({
+      local: { testing: { packages: { snyk_token: 'tok' } } },
+    });
+    assert.strictEqual(resolveSnykAuth(tmpDir).auth_source, 'dgs_local');
+    cleanup(tmpDir);
+
+    // 2. env_token (SNYK_TOKEN env)
+    tmpDir = setupPlanningRoot();
+    process.env.SNYK_TOKEN = 'env-tok';
+    assert.strictEqual(resolveSnykAuth(tmpDir).auth_source, 'env_token');
+    delete process.env.SNYK_TOKEN;
+    cleanup(tmpDir);
+
+    // 3. api_config (snyk config get api)
+    tmpDir = setupPlanningRoot();
+    const fakeApi = (cmd, args) => args[0] === 'config' ? { status: 0, stdout: 'api-tok\n' } : { status: 1, stdout: '' };
+    assert.strictEqual(resolveSnykAuth(tmpDir, { _spawnSync: fakeApi }).auth_source, 'api_config');
+    cleanup(tmpDir);
+
+    // 4. oauth_configstore (snyk whoami)
+    tmpDir = setupPlanningRoot();
+    const fakeWho = (cmd, args) => args[0] === 'whoami' ? { status: 0, stdout: 'u@x\n' } : { status: 1, stdout: '' };
+    assert.strictEqual(resolveSnykAuth(tmpDir, { _spawnSync: fakeWho }).auth_source, 'oauth_configstore');
+  });
+
+  test('all four sources fail -> available=false, auth_source=null', () => {
+    tmpDir = setupPlanningRoot();
+    const fakeFail = () => ({ status: 1, stdout: '', stderr: '' });
+    const r = resolveSnykAuth(tmpDir, { _spawnSync: fakeFail });
+    assert.strictEqual(r.available, false);
+    assert.strictEqual(r.source, 'none');
+    assert.strictEqual(r.auth_source, null);
+  });
+
+  test('token NEVER leaks via JSON.stringify of runScan result', () => {
+    tmpDir = setupPlanningRoot({
+      local: { testing: { packages: { snyk_token: 's3cret-leak-test-zzz' } } },
+    });
+    const result = runScan(tmpDir, {}, makeStubDeps({
+      checkToolOnPath: (bin) => ({ available: bin === 'snyk' || bin === 'npm' }),
+      snykAuth: () => ({ available: true, source: 'config.local.json', token: 's3cret-leak-test-zzz' }),
+    }));
+    assert.doesNotMatch(JSON.stringify(result), /s3cret-leak-test-zzz/);
+  });
+});
+
+// ─── collectScanTargets ───────────────────────────────────────────────────────
+
+describe('collectScanTargets (PKG-15, PKG-16)', () => {
+  let tmpDir;
+  afterEach(() => cleanup(tmpDir));
+
+  test('no REPOS.md returns [{ _product_root }]', () => {
+    tmpDir = setupPlanningRoot();
+    const { targets } = collectScanTargets(tmpDir);
+    assert.strictEqual(targets.length, 1);
+    assert.strictEqual(targets[0].name, '_product_root');
+    assert.strictEqual(targets[0].dir, tmpDir);
+  });
+
+  test('REPOS.md with 2 repos returns 3 targets with _product_root last', () => {
+    tmpDir = setupPlanningRoot({ repos: [
+      { name: 'api', path: '../api' },
+      { name: 'web', path: '../web' },
+    ]});
+    const { targets } = collectScanTargets(tmpDir);
+    assert.strictEqual(targets.length, 3);
+    assert.strictEqual(targets[0].name, 'api');
+    assert.strictEqual(targets[1].name, 'web');
+    assert.strictEqual(targets[2].name, '_product_root');
+  });
+
+  test('_product_root.dir is planning root', () => {
+    tmpDir = setupPlanningRoot({ repos: [{ name: 'api', path: '../api' }] });
+    const { targets } = collectScanTargets(tmpDir);
+    const pr = targets.find(t => t.name === '_product_root');
+    assert.strictEqual(pr.dir, tmpDir);
+  });
+
+  test('with worktree context, repo dir comes from worktree (not main path)', () => {
+    tmpDir = setupPlanningRoot({ repos: [{ name: 'api', path: '../api' }] });
+    const worktreeDir = path.join(tmpDir, 'worktree-api');
+    fs.mkdirSync(worktreeDir, { recursive: true });
+    setupWorktreeContext(tmpDir, { repoName: 'api', slug: 'v1.0', worktreeDir });
+    const { targets } = collectScanTargets(tmpDir);
+    const api = targets.find(t => t.name === 'api');
+    assert.strictEqual(api.dir, worktreeDir);
+  });
+});
+
+// ─── runScan — clean scans ───────────────────────────────────────────────────
+
+describe('runScan - clean scans and skips', () => {
+  let tmpDir;
+  afterEach(() => cleanup(tmpDir));
+
+  test('empty REPOS.md + no manifests -> exit_code 0, no_manifests outcome', () => {
+    tmpDir = setupPlanningRoot();
+    const result = runScan(tmpDir, {}, makeStubDeps({ detector: () => [] }));
+    assert.strictEqual(result.exit_code, 0);
+    assert.strictEqual(result.findings.length, 0);
+    assert.strictEqual(result.repo_results.length, 1);
+    assert.strictEqual(result.repo_results[0].outcome, 'no_manifests');
+  });
+
+  test('one repo with no manifest -> outcome no_manifests, no tool invocation', () => {
+    tmpDir = setupPlanningRoot({ repos: [{ name: 'api', path: '../api' }] });
+    const runner = spyRunner();
+    const result = runScan(tmpDir, {}, makeStubDeps({ detector: () => [], runner }));
+    assert.strictEqual(runner.calls.length, 0);
+    assert.strictEqual(result.exit_code, 0);
+    const apiResult = result.repo_results.find(r => r.repo === 'api');
+    assert.strictEqual(apiResult.outcome, 'no_manifests');
+  });
+
+  test('skip entries do not consume pkg-NNN ids', () => {
+    tmpDir = setupPlanningRoot();
+    const result = runScan(tmpDir, {}, makeStubDeps({ detector: () => [] }));
+    assert.strictEqual(result.findings.length, 0);
+  });
+});
+
+// ─── runScan — cascade and pins ───────────────────────────────────────────────
+
+describe('runScan - cascade and pins (PKG-03, PKG-17, PKG-40)', () => {
+  let tmpDir;
+  afterEach(() => cleanup(tmpDir));
+
+  test('auto + snyk resolvable -> tool_used: snyk on every target', () => {
+    tmpDir = setupPlanningRoot({ config: { testing: { packages: { tool: 'auto' } } } });
+    const runner = spyRunner({
+      'snyk': { exitCode: 0, stdout: '{}', stderr: '', timedOut: false, duration: 1, outcome: 'ok', parsed: { vulnerabilities: [] } },
+    });
+    const result = runScan(tmpDir, {}, makeStubDeps({
+      detector: (dir) => dir === tmpDir ? [{ ecosystem: 'node', manifest_path: null }] : [],
+      runner,
+      snykAuth: () => ({ available: true, source: 'env', token: 'TK' }),
+      checkToolOnPath: (bin) => ({ available: bin === 'snyk' }),
+    }));
+    const productEntry = result.repo_results.find(r => r.repo === '_product_root');
+    assert.strictEqual(productEntry.tool_used, 'snyk');
+    assert.strictEqual(runner.calls[0].opts.env.SNYK_TOKEN, 'TK');
+  });
+
+  test('auto + no snyk + osv on path -> tool_used: osv-scanner', () => {
+    tmpDir = setupPlanningRoot();
+    const runner = spyRunner({
+      'osv-scanner': { exitCode: 0, stdout: '{}', stderr: '', timedOut: false, duration: 1, outcome: 'ok', parsed: { results: [] } },
+    });
+    const result = runScan(tmpDir, {}, makeStubDeps({
+      detector: () => [{ ecosystem: 'node', manifest_path: null }],
+      runner,
+      snykAuth: () => ({ available: false, source: 'none' }),
+      checkToolOnPath: (bin) => ({ available: bin === 'osv-scanner' }),
+    }));
+    const entry = result.repo_results.find(r => r.tool_used);
+    assert.strictEqual(entry.tool_used, 'osv-scanner');
+  });
+
+  test('auto + no snyk + no osv -> native tool for each ecosystem', () => {
+    tmpDir = setupPlanningRoot();
+    const runner = spyRunner({
+      'npm-audit': { exitCode: 0, stdout: '{}', outcome: 'ok', parsed: {}, duration: 1 },
+    });
+    const result = runScan(tmpDir, {}, makeStubDeps({
+      detector: () => [{ ecosystem: 'node', manifest_path: null }],
+      runner,
+      snykAuth: () => ({ available: false, source: 'none' }),
+      checkToolOnPath: () => ({ available: false }),
+    }));
+    const entry = result.repo_results.find(r => r.tool_used);
+    assert.strictEqual(entry.tool_used, 'npm-audit');
+  });
+
+  test('pin snyk + auth absent -> exit_code 2, tool_unavailable_on_pin diagnostic, NO runner calls', () => {
+    tmpDir = setupPlanningRoot({ config: { testing: { packages: { tool: 'snyk' } } } });
+    const runner = spyRunner();
+    const result = runScan(tmpDir, {}, makeStubDeps({
+      runner,
+      snykAuth: () => ({ available: false, source: 'none' }),
+      checkToolOnPath: () => ({ available: false }),
+    }));
+    assert.strictEqual(result.exit_code, 2);
+    assert.strictEqual(runner.calls.length, 0);
+    assert.strictEqual(result.diagnostics[0].kind, 'tool_unavailable_on_pin');
+  });
+
+  test('pin osv + osv not on path -> exit_code 2, install hint', () => {
+    tmpDir = setupPlanningRoot({ config: { testing: { packages: { tool: 'osv' } } } });
+    const runner = spyRunner();
+    const result = runScan(tmpDir, {}, makeStubDeps({
+      runner,
+      checkToolOnPath: () => ({ available: false }),
+    }));
+    assert.strictEqual(result.exit_code, 2);
+    assert.match(result.diagnostics[0].hint, /OSV-Scanner/);
+  });
+
+  test('findings present -> exit_code 0 (PKG-40)', () => {
+    tmpDir = setupPlanningRoot();
+    const runner = spyRunner({
+      'npm-audit': {
+        exitCode: 1, stdout: '{}', outcome: 'ok', duration: 1,
+        parsed: { vulnerabilities: { 'lodash': { severity: 'high', via: [{ url: 'u', title: 't' }] } } },
+      },
+    });
+    const result = runScan(tmpDir, {}, makeStubDeps({
+      detector: () => [{ ecosystem: 'node', manifest_path: null }],
+      runner,
+      checkToolOnPath: () => ({ available: false }),
+    }));
+    assert.strictEqual(result.exit_code, 0);
+  });
+
+  test('tool_failure in one target + ok in another -> exit_code 0', () => {
+    tmpDir = setupPlanningRoot({ repos: [{ name: 'api', path: '../api' }] });
+    const runner = spyRunner({
+      'npm-audit': ({ cwd }) => {
+        if (cwd.endsWith('api')) return { exitCode: 2, stderr: 'boom', outcome: 'tool_failure', duration: 1 };
+        return { exitCode: 0, stdout: '{}', outcome: 'ok', duration: 1, parsed: { vulnerabilities: {} } };
+      },
+    });
+    const result = runScan(tmpDir, {}, makeStubDeps({
+      detector: () => [{ ecosystem: 'node', manifest_path: null }],
+      runner,
+      checkToolOnPath: () => ({ available: false }),
+    }));
+    assert.strictEqual(result.exit_code, 0);
+  });
+
+  test('process.env not mutated; SNYK_TOKEN not set after', () => {
+    tmpDir = setupPlanningRoot();
+    process.env._DGS_CANARY_150 = 'alive';
+    const origSnyk = process.env.SNYK_TOKEN;
+    delete process.env.SNYK_TOKEN;
+    runScan(tmpDir, {}, makeStubDeps({
+      detector: () => [{ ecosystem: 'node', manifest_path: null }],
+      runner: spyRunner({ 'snyk': { exitCode: 0, stdout: '{}', outcome: 'ok', parsed: {}, duration: 1 } }),
+      snykAuth: () => ({ available: true, source: 'env', token: 'TOK' }),
+      checkToolOnPath: (bin) => ({ available: bin === 'snyk' }),
+    }));
+    assert.strictEqual(process.env._DGS_CANARY_150, 'alive');
+    assert.strictEqual(process.env.SNYK_TOKEN, undefined);
+    delete process.env._DGS_CANARY_150;
+    if (origSnyk !== undefined) process.env.SNYK_TOKEN = origSnyk;
+  });
+
+  test('ECOSYSTEM_OVERRIDES yarn -> osv when available, even when configTool auto and snyk resolvable', () => {
+    tmpDir = setupPlanningRoot();
+    const runner = spyRunner({
+      'osv-scanner': { exitCode: 0, stdout: '{}', outcome: 'ok', duration: 1, parsed: { results: [] } },
+    });
+    const result = runScan(tmpDir, {}, makeStubDeps({
+      detector: () => [{ ecosystem: 'yarn', manifest_path: null }],
+      runner,
+      snykAuth: () => ({ available: true, source: 'env', token: 'T' }),
+      checkToolOnPath: (bin) => ({ available: bin === 'osv-scanner' || bin === 'snyk' }),
+    }));
+    const entry = result.repo_results.find(r => r.tool_used);
+    assert.strictEqual(entry && entry.tool_used, 'osv-scanner');
+  });
+
+  test('ECOSYSTEM_OVERRIDES yarn + OSV unavailable -> forced_tool_unavailable diagnostic', () => {
+    tmpDir = setupPlanningRoot();
+    const result = runScan(tmpDir, {}, makeStubDeps({
+      detector: () => [{ ecosystem: 'yarn', manifest_path: null }],
+      runner: spyRunner(),
+      checkToolOnPath: () => ({ available: false }),
+    }));
+    const entry = result.repo_results.find(r => r.outcome === 'skipped' && r.diagnostic);
+    assert.ok(entry);
+    assert.strictEqual(entry.diagnostic.kind, 'forced_tool_unavailable');
+  });
+});
+
+// ─── runScan — snyk_org argv threading (UAT Bug 2) ───────────────────────────
+
+describe('snyk_org argv threading (UAT Bug 2)', () => {
+  let tmpDir;
+  afterEach(() => cleanup(tmpDir));
+
+  test('config.json snyk_org -> argv contains --org=<ID>', () => {
+    tmpDir = setupPlanningRoot({
+      config: { testing: { packages: { snyk_org: 'ORG-UUID-A' } } },
+    });
+    const runner = spyRunner({
+      snyk: { exitCode: 0, stdout: '{}', stderr: '', timedOut: false, duration: 1, outcome: 'ok', parsed: { vulnerabilities: [] } },
+    });
+    runScan(tmpDir, {}, makeStubDeps({
+      detector: () => [{ ecosystem: 'node', manifest_path: 'package.json' }],
+      runner,
+      checkToolOnPath: (bin) => ({ available: bin === 'snyk' }),
+      snykAuth: () => ({ available: true, source: 'env', auth_source: 'env_token', token: 'T' }),
+    }));
+    assert.ok(runner.calls.length >= 1, `expected at least one runner call; got ${runner.calls.length}`);
+    assert.ok(runner.calls[0].argv.includes('--org=ORG-UUID-A'),
+      `argv missing --org: ${JSON.stringify(runner.calls[0].argv)}`);
+  });
+
+  test('config.local.json snyk_org wins over config.json', () => {
+    tmpDir = setupPlanningRoot({
+      config: { testing: { packages: { snyk_org: 'ORG-SHARED' } } },
+      local:  { testing: { packages: { snyk_org: 'ORG-LOCAL' } } },
+    });
+    const runner = spyRunner({
+      snyk: { exitCode: 0, stdout: '{}', stderr: '', timedOut: false, duration: 1, outcome: 'ok', parsed: { vulnerabilities: [] } },
+    });
+    runScan(tmpDir, {}, makeStubDeps({
+      detector: () => [{ ecosystem: 'node', manifest_path: 'package.json' }],
+      runner,
+      checkToolOnPath: (bin) => ({ available: bin === 'snyk' }),
+      snykAuth: () => ({ available: true, source: 'env', auth_source: 'env_token', token: 'T' }),
+    }));
+    assert.ok(runner.calls[0].argv.includes('--org=ORG-LOCAL'));
+    assert.ok(!runner.calls[0].argv.includes('--org=ORG-SHARED'));
+  });
+
+  test('null/unset snyk_org -> no --org flag in argv', () => {
+    tmpDir = setupPlanningRoot();
+    const runner = spyRunner({
+      snyk: { exitCode: 0, stdout: '{}', stderr: '', timedOut: false, duration: 1, outcome: 'ok', parsed: { vulnerabilities: [] } },
+    });
+    runScan(tmpDir, {}, makeStubDeps({
+      detector: () => [{ ecosystem: 'node', manifest_path: 'package.json' }],
+      runner,
+      checkToolOnPath: (bin) => ({ available: bin === 'snyk' }),
+      snykAuth: () => ({ available: true, source: 'env', auth_source: 'env_token', token: 'T' }),
+    }));
+    for (const a of runner.calls[0].argv) {
+      assert.ok(!String(a).startsWith('--org'), `unexpected --org in argv: ${a}`);
+    }
+  });
+
+  test('runScan result surfaces snyk_org field', () => {
+    tmpDir = setupPlanningRoot({
+      config: { testing: { packages: { snyk_org: 'ORG-RES' } } },
+    });
+    const result = runScan(tmpDir, {}, makeStubDeps({
+      detector: () => [],
+      checkToolOnPath: () => ({ available: false }),
+      snykAuth: () => ({ available: false, source: 'none', auth_source: null }),
+    }));
+    assert.strictEqual(result.snyk_org, 'ORG-RES');
+  });
+
+  test('runScan result with no snyk_org -> snyk_org: null', () => {
+    tmpDir = setupPlanningRoot();
+    const result = runScan(tmpDir, {}, makeStubDeps({
+      detector: () => [],
+      checkToolOnPath: () => ({ available: false }),
+      snykAuth: () => ({ available: false, source: 'none', auth_source: null }),
+    }));
+    assert.strictEqual(result.snyk_org, null);
+  });
+});
+
+// ─── runScan — worktree targeting ─────────────────────────────────────────────
+
+describe('runScan - worktree targeting (spec success criterion 4, PKG-04)', () => {
+  let tmpDir;
+  afterEach(() => cleanup(tmpDir));
+
+  test('active_context maps repoA to worktree -> runner cwd = worktree', () => {
+    tmpDir = setupPlanningRoot({ repos: [{ name: 'api', path: '../api' }] });
+    const worktreeDir = path.join(tmpDir, 'wt-api');
+    fs.mkdirSync(worktreeDir, { recursive: true });
+    setupWorktreeContext(tmpDir, { repoName: 'api', slug: 'v1.0', worktreeDir });
+    const runner = spyRunner({
+      'npm-audit': { exitCode: 0, stdout: '{}', outcome: 'ok', duration: 1, parsed: { vulnerabilities: {} } },
+    });
+    runScan(tmpDir, {}, makeStubDeps({
+      detector: (dir) => dir === worktreeDir ? [{ ecosystem: 'node', manifest_path: null }] : [],
+      runner,
+      checkToolOnPath: () => ({ available: false }),
+    }));
+    const call = runner.calls[0];
+    assert.strictEqual(call.cwd, worktreeDir);
+  });
+
+  test('no active_context -> runner uses main checkout path', () => {
+    tmpDir = setupPlanningRoot({ repos: [{ name: 'api', path: '../api' }] });
+    const runner = spyRunner({
+      'npm-audit': { exitCode: 0, stdout: '{}', outcome: 'ok', duration: 1, parsed: {} },
+    });
+    runScan(tmpDir, {}, makeStubDeps({
+      detector: () => [{ ecosystem: 'node', manifest_path: null }],
+      runner,
+      checkToolOnPath: () => ({ available: false }),
+    }));
+    // main path = <planningRootParent>/api
+    const expected = path.resolve(tmpDir, '../api');
+    assert.strictEqual(runner.calls[0].cwd, expected);
+  });
+});
+
+// ─── runScan — monorepo handling ──────────────────────────────────────────────
+
+describe('runScan - monorepo handling (PKG-03 v1.1)', () => {
+  let tmpDir;
+  afterEach(() => cleanup(tmpDir));
+
+  test('native tier + 3 node workspace entries -> 3 runner calls', () => {
+    tmpDir = setupPlanningRoot();
+    const runner = spyRunner({
+      'npm-audit': { exitCode: 0, stdout: '{}', outcome: 'ok', duration: 1, parsed: {} },
+    });
+    runScan(tmpDir, {}, makeStubDeps({
+      detector: () => [
+        { ecosystem: 'node', manifest_path: 'packages/a/package.json' },
+        { ecosystem: 'node', manifest_path: 'packages/b/package.json' },
+        { ecosystem: 'node', manifest_path: 'packages/c/package.json' },
+      ],
+      runner,
+      checkToolOnPath: () => ({ available: false }),
+    }));
+    assert.strictEqual(runner.calls.length, 3);
+  });
+
+  test('native tier + 3 workspace entries -> adapter ctx.manifest_path matches each', () => {
+    tmpDir = setupPlanningRoot();
+    const runner = spyRunner({
+      'npm-audit': { exitCode: 0, stdout: '{}', outcome: 'ok', duration: 1, parsed: {} },
+    });
+    const result = runScan(tmpDir, {}, makeStubDeps({
+      detector: () => [
+        { ecosystem: 'node', manifest_path: 'a/package.json' },
+        { ecosystem: 'node', manifest_path: 'b/package.json' },
+      ],
+      runner,
+      checkToolOnPath: () => ({ available: false }),
+    }));
+    const manifests = result.repo_results.filter(r => r.tool_used === 'npm-audit').map(r => r.manifest_path);
+    assert.deepStrictEqual(manifests.sort(), ['a/package.json', 'b/package.json']);
+  });
+
+  test('snyk tier + 3 workspace entries -> runner called ONCE with --all-projects', () => {
+    tmpDir = setupPlanningRoot();
+    const runner = spyRunner({
+      'snyk': { exitCode: 0, stdout: '{}', outcome: 'ok', duration: 1, parsed: { vulnerabilities: [] } },
+    });
+    runScan(tmpDir, {}, makeStubDeps({
+      detector: () => [
+        { ecosystem: 'node', manifest_path: 'a/package.json' },
+        { ecosystem: 'node', manifest_path: 'b/package.json' },
+        { ecosystem: 'node', manifest_path: 'c/package.json' },
+      ],
+      runner,
+      snykAuth: () => ({ available: true, source: 'env', token: 'T' }),
+      checkToolOnPath: (bin) => ({ available: bin === 'snyk' }),
+    }));
+    assert.strictEqual(runner.calls.length, 1);
+    assert.ok(runner.calls[0].argv.includes('--all-projects'));
+  });
+
+  test('osv tier + 3 workspace entries -> runner called ONCE with -r .', () => {
+    tmpDir = setupPlanningRoot();
+    const runner = spyRunner({
+      'osv-scanner': { exitCode: 0, stdout: '{}', outcome: 'ok', duration: 1, parsed: { results: [] } },
+    });
+    runScan(tmpDir, {}, makeStubDeps({
+      detector: () => [
+        { ecosystem: 'node', manifest_path: 'a/package.json' },
+        { ecosystem: 'node', manifest_path: 'b/package.json' },
+        { ecosystem: 'node', manifest_path: 'c/package.json' },
+      ],
+      runner,
+      checkToolOnPath: (bin) => ({ available: bin === 'osv-scanner' }),
+    }));
+    assert.strictEqual(runner.calls.length, 1);
+    assert.ok(runner.calls[0].argv.includes('-r'));
+    assert.ok(runner.calls[0].argv.includes('.'));
+  });
+
+  test('python monorepo + native tier -> 2 tool_failure, 0 pip-audit calls', () => {
+    tmpDir = setupPlanningRoot();
+    const runner = spyRunner();
+    const result = runScan(tmpDir, {}, makeStubDeps({
+      detector: () => [
+        { ecosystem: 'python', manifest_path: 'svc-a/requirements.txt' },
+        { ecosystem: 'python', manifest_path: 'svc-b/requirements.txt' },
+      ],
+      runner,
+      checkToolOnPath: () => ({ available: false }),
+    }));
+    const pipCalls = runner.calls.filter(c => c.toolKey === 'pip-audit').length;
+    assert.strictEqual(pipCalls, 0);
+    const failures = result.repo_results.filter(r => r.outcome === 'tool_failure' && r.diagnostic && r.diagnostic.kind === 'python_monorepo_shared_venv');
+    assert.strictEqual(failures.length, 2);
+  });
+
+  test('mixed target (node + python at root) + native -> 2 runner calls (npm-audit + pip-audit)', () => {
+    tmpDir = setupPlanningRoot();
+    const runner = spyRunner({
+      'npm-audit': { exitCode: 0, stdout: '{}', outcome: 'ok', duration: 1, parsed: {} },
+      'pip-audit': { exitCode: 0, stdout: '{}', outcome: 'ok', duration: 1, parsed: [] },
+    });
+    runScan(tmpDir, {}, makeStubDeps({
+      detector: () => [
+        { ecosystem: 'node', manifest_path: null },
+        { ecosystem: 'python', manifest_path: null },
+      ],
+      runner,
+      checkToolOnPath: () => ({ available: false }),
+    }));
+    assert.strictEqual(runner.calls.length, 2);
+    const tools = runner.calls.map(c => c.toolKey).sort();
+    assert.deepStrictEqual(tools, ['npm-audit', 'pip-audit']);
+  });
+});
+
+// ─── runScan — finding id assignment ──────────────────────────────────────────
+
+describe('runScan - finding id assignment + aggregation (PKG-05, PKG-18)', () => {
+  let tmpDir;
+  afterEach(() => cleanup(tmpDir));
+
+  function fakeNpmWithVulns() {
+    return {
+      exitCode: 1, stdout: '{}', outcome: 'ok', duration: 1,
+      parsed: {
+        vulnerabilities: {
+          'pkg-a': { name: 'pkg-a', severity: 'high', via: [{ url: 'u', title: 't1', source: 1 }] },
+          'pkg-b': { name: 'pkg-b', severity: 'low', via: [{ url: 'u', title: 't2', source: 2 }] },
+        },
+      },
+    };
+  }
+
+  test('every finding has id pkg-NNN', () => {
+    tmpDir = setupPlanningRoot();
+    const result = runScan(tmpDir, {}, makeStubDeps({
+      detector: () => [{ ecosystem: 'node', manifest_path: null }],
+      runner: spyRunner({ 'npm-audit': fakeNpmWithVulns() }),
+      checkToolOnPath: () => ({ available: false }),
+    }));
+    for (const f of result.findings) {
+      assert.match(f.id, /^pkg-\d{3}$/);
+    }
+  });
+
+  test('ids are monotonic starting at pkg-001', () => {
+    tmpDir = setupPlanningRoot();
+    const result = runScan(tmpDir, {}, makeStubDeps({
+      detector: () => [{ ecosystem: 'node', manifest_path: null }],
+      runner: spyRunner({ 'npm-audit': fakeNpmWithVulns() }),
+      checkToolOnPath: () => ({ available: false }),
+    }));
+    if (result.findings.length > 0) {
+      assert.strictEqual(result.findings[0].id, 'pkg-001');
+      for (let i = 1; i < result.findings.length; i++) {
+        const prev = parseInt(result.findings[i - 1].id.slice(4), 10);
+        const cur = parseInt(result.findings[i].id.slice(4), 10);
+        assert.strictEqual(cur, prev + 1);
+      }
+    }
+  });
+
+  test('repo_results.findings and aggregate findings[] have same ids', () => {
+    tmpDir = setupPlanningRoot();
+    const result = runScan(tmpDir, {}, makeStubDeps({
+      detector: () => [{ ecosystem: 'node', manifest_path: null }],
+      runner: spyRunner({ 'npm-audit': fakeNpmWithVulns() }),
+      checkToolOnPath: () => ({ available: false }),
+    }));
+    const perRepoIds = [];
+    for (const rr of result.repo_results) for (const f of rr.findings) perRepoIds.push(f.id);
+    const aggIds = result.findings.map(f => f.id);
+    assert.deepStrictEqual(perRepoIds.sort(), aggIds.sort());
+  });
+
+  test('zero findings -> empty findings[] and no ids burned', () => {
+    tmpDir = setupPlanningRoot();
+    const result = runScan(tmpDir, {}, makeStubDeps({
+      detector: () => [],
+      runner: spyRunner(),
+      checkToolOnPath: () => ({ available: false }),
+    }));
+    assert.strictEqual(result.findings.length, 0);
+  });
+
+  test('findings assigned after all targets scanned (target order preserved)', () => {
+    tmpDir = setupPlanningRoot({ repos: [{ name: 'api', path: '../api' }] });
+    const result = runScan(tmpDir, {}, makeStubDeps({
+      detector: (dir) => {
+        // Fake detector: api gets findings first, product_root gets findings second
+        return [{ ecosystem: 'node', manifest_path: null }];
+      },
+      runner: spyRunner({ 'npm-audit': fakeNpmWithVulns() }),
+      checkToolOnPath: () => ({ available: false }),
+    }));
+    // api findings should come before _product_root findings in aggregate
+    const apiEntry = result.repo_results.find(r => r.repo === 'api');
+    if (apiEntry && apiEntry.findings.length > 0) {
+      const firstApiId = apiEntry.findings[0].id;
+      assert.strictEqual(firstApiId, 'pkg-001');
+    }
+  });
+});
+
+// ─── runScan — config read path ───────────────────────────────────────────────
+
+describe('runScan - config read path (PKG-19 integration)', () => {
+  let tmpDir;
+  afterEach(() => cleanup(tmpDir));
+
+  test('defaults applied when no testing.packages section', () => {
+    tmpDir = setupPlanningRoot();
+    const runner = spyRunner({
+      'npm-audit': { exitCode: 0, stdout: '{}', outcome: 'ok', duration: 1, parsed: {} },
+    });
+    runScan(tmpDir, {}, makeStubDeps({
+      detector: () => [{ ecosystem: 'node', manifest_path: null }],
+      runner,
+      checkToolOnPath: () => ({ available: false }),
+    }));
+    // default timeout_seconds = 300 -> 300000 ms
+    assert.strictEqual(runner.calls[0].opts.timeoutMs, 300000);
+  });
+
+  test('timeout_seconds passed as opts.timeoutMs * 1000', () => {
+    tmpDir = setupPlanningRoot({ config: { testing: { packages: { timeout_seconds: 60 } } } });
+    const runner = spyRunner({
+      'npm-audit': { exitCode: 0, stdout: '{}', outcome: 'ok', duration: 1, parsed: {} },
+    });
+    runScan(tmpDir, {}, makeStubDeps({
+      detector: () => [{ ecosystem: 'node', manifest_path: null }],
+      runner,
+      checkToolOnPath: () => ({ available: false }),
+    }));
+    assert.strictEqual(runner.calls[0].opts.timeoutMs, 60000);
+  });
+
+  test('include_dev_dependencies=false threads into npm-audit argv', () => {
+    tmpDir = setupPlanningRoot({ config: { testing: { packages: { include_dev_dependencies: false } } } });
+    const runner = spyRunner({
+      'npm-audit': { exitCode: 0, stdout: '{}', outcome: 'ok', duration: 1, parsed: {} },
+    });
+    runScan(tmpDir, {}, makeStubDeps({
+      detector: () => [{ ecosystem: 'node', manifest_path: null }],
+      runner,
+      checkToolOnPath: () => ({ available: false }),
+    }));
+    assert.ok(runner.calls[0].argv.includes('--omit=dev'));
+  });
+});
+
+// ─── cmdPackageScan CLI wrapper ───────────────────────────────────────────────
+//
+// The CLI calls process.exit(), which the node test runner would terminate on.
+// We run these tests as subprocesses to isolate exit() + stdout hijacking from
+// the test runner's own stdout-TAP channel.
+
+describe('cmdPackageScan - CLI entry', () => {
+  let tmpDir;
+  afterEach(() => cleanup(tmpDir));
+
+  function runCli(tmpDir, raw) {
+    const rawFlag = raw ? 'true' : 'false';
+    const modPath = path.resolve(__dirname, 'package-scan.cjs');
+    const program = `
+      const { cmdPackageScan } = require(${JSON.stringify(modPath)});
+      cmdPackageScan(${JSON.stringify(tmpDir)}, {}, ${rawFlag});
+    `;
+    const r = require('child_process').spawnSync(process.execPath, ['-e', program], {
+      cwd: tmpDir,
+      encoding: 'utf-8',
+    });
+    return { exitCode: r.status, stdout: r.stdout || '', stderr: r.stderr || '' };
+  }
+
+  test('calls runScan and exits with 0 on success', () => {
+    tmpDir = setupPlanningRoot();
+    const r = runCli(tmpDir, false);
+    assert.strictEqual(r.exitCode, 0);
+    // Phase 151 replaced the "N findings across M repos" placeholder with the
+    // report-aware `Wrote {path} ({clean scan|N finding(s)}, tool: {tool}).` line.
+    assert.match(r.stdout, /Wrote .*PACKAGE-SCAN/);
+  });
+
+  test('with raw=true emits JSON', () => {
+    tmpDir = setupPlanningRoot();
+    const r = runCli(tmpDir, true);
+    assert.strictEqual(r.exitCode, 0);
+    // In raw mode, Phase 151's cmdPackageScan emits compact single-line JSON
+    // to stdout (no process.exit inside output()), followed by the report-write
+    // side effect — no extra stdout lines in raw mode. Find the first newline
+    // to isolate the JSON payload.
+    const newlineIdx = r.stdout.indexOf('\n');
+    assert.ok(newlineIdx > 0, 'expected newline separator in raw stdout');
+    const jsonPart = r.stdout.slice(0, newlineIdx);
+    const j = JSON.parse(jsonPart);
+    assert.strictEqual(j.exit_code, 0);
+    assert.ok(Array.isArray(j.findings));
+  });
+
+  test('summary line mentions report path + tool when raw=false', () => {
+    tmpDir = setupPlanningRoot();
+    const r = runCli(tmpDir, false);
+    // Either "clean scan" (zero findings) or "N finding(s)" phrase, plus the tool.
+    assert.match(r.stdout, /Wrote .*PACKAGE-SCAN.*\((clean scan|\d+ findings?), tool: \S+\)/);
+  });
+
+  test('exit_code surfaces as process exit code', () => {
+    // Force a pin-fail-fast via tool:snyk config with no auth
+    tmpDir = setupPlanningRoot({ config: { testing: { packages: { tool: 'snyk' } } } });
+    const r = runCli(tmpDir, true);
+    // On a clean test host without Snyk installed, should exit 2
+    assert.strictEqual([0, 2].includes(r.exitCode), true);
+  });
+});
+
+// ─── Integration smoke (Plan 03) ──────────────────────────────────────────────
+
+describe('integration smoke 150', () => {
+  let tmpDir;
+  afterEach(() => cleanup(tmpDir));
+
+  test('scenario 1: four-ecosystem end-to-end, pkg-NNN ids assigned', () => {
+    tmpDir = setupPlanningRoot({
+      repos: [
+        { name: 'api', path: '../api' },
+        { name: 'worker', path: '../worker' },
+        { name: 'cli', path: '../cli' },
+        { name: 'admin', path: '../admin' },
+      ],
+    });
+    // Create manifest dirs
+    for (const r of ['api', 'worker', 'cli', 'admin']) {
+      const rd = path.resolve(tmpDir, '..', r);
+      fs.mkdirSync(rd, { recursive: true });
+    }
+    fs.writeFileSync(path.resolve(tmpDir, '..', 'api', 'package.json'), '{}');
+    fs.writeFileSync(path.resolve(tmpDir, '..', 'worker', 'requirements.txt'), '');
+    fs.writeFileSync(path.resolve(tmpDir, '..', 'cli', 'go.mod'), 'module x');
+    fs.writeFileSync(path.resolve(tmpDir, '..', 'admin', 'Gemfile.lock'), '');
+
+    // Canned outputs (JSON structures that adapters can handle; empty findings OK)
+    const runner = spyRunner({
+      'npm-audit': { exitCode: 0, stdout: '{}', outcome: 'ok', duration: 1, parsed: { vulnerabilities: {} } },
+      'pip-audit': { exitCode: 0, stdout: '[]', outcome: 'ok', duration: 1, parsed: [] },
+      'govulncheck': { exitCode: 0, stdout: '', outcome: 'ok', duration: 1, parsed: null },
+      'bundler-audit': { exitCode: 0, stdout: '{}', outcome: 'ok', duration: 1, parsed: { results: [] } },
+    });
+    const result = runScan(tmpDir, {}, {
+      detector: require('./package-ecosystems.cjs').detectEcosystems,
+      runner,
+      snykAuth: () => ({ available: false, source: 'none' }),
+      checkToolOnPath: () => ({ available: false }),
+    });
+
+    assert.strictEqual(result.exit_code, 0);
+    assert.strictEqual(result.repo_results.length >= 4, true);
+    assert.strictEqual(result.tool_per_target['api'], 'npm-audit');
+    assert.strictEqual(result.tool_per_target['worker'], 'pip-audit');
+    assert.strictEqual(result.tool_per_target['cli'], 'govulncheck');
+    assert.strictEqual(result.tool_per_target['admin'], 'bundler-audit');
+
+    // cleanup sibling repo dirs (best effort)
+    for (const r of ['api', 'worker', 'cli', 'admin']) {
+      try { fs.rmSync(path.resolve(tmpDir, '..', r), { recursive: true, force: true }); } catch {}
+    }
+  });
+
+  test('scenario 2: config round-trip — snyk_token routed to config-local-set', () => {
+    tmpDir = setupPlanningRoot();
+    const { cmdConfigSet, cmdConfigLocalSet } = require('./config.cjs');
+
+    // Capture all exit/stdout/stderr for the duration of this test — the
+    // origStdoutWrite and origStderrWrite MUST be restored in the final finally
+    // block, otherwise the node test runner TAP channel gets swallowed.
+    let exitCode = null;
+    let stdout = '';
+    let stderr = '';
+    const origExit = process.exit;
+    const origStdoutWrite = process.stdout.write.bind(process.stdout);
+    const origStderrWrite = process.stderr.write.bind(process.stderr);
+    process.exit = (c) => {
+      exitCode = c;
+      if (c !== 0) { const e = new Error('__EXIT__'); e.__s = true; throw e; }
+    };
+    process.stdout.write = (d) => { stdout += String(d); return true; };
+    process.stderr.write = (d) => { stderr += String(d); return true; };
+    let rejectLocalOnly, writeLocal, authResult;
+    try {
+      // 1. cmdConfigSet(snyk_token) must reject with local-only
+      try { cmdConfigSet(tmpDir, 'testing.packages.snyk_token', 'abc', true); }
+      catch (e) { if (!e.__s) throw e; }
+      rejectLocalOnly = { exitCode, stderr };
+
+      // 2. cmdConfigLocalSet accepts it
+      exitCode = null;
+      stdout = '';
+      try { cmdConfigLocalSet(tmpDir, 'testing.packages.snyk_token', 'abc', true); }
+      catch (e) { if (!e.__s) throw e; }
+
+      // Read config.local.json back from disk
+      writeLocal = JSON.parse(fs.readFileSync(path.join(tmpDir, 'config.local.json'), 'utf-8'));
+
+      // 3. resolveSnykAuth picks it up
+      resetPaths();
+      authResult = resolveSnykAuth(tmpDir);
+    } finally {
+      process.exit = origExit;
+      process.stdout.write = origStdoutWrite;
+      process.stderr.write = origStderrWrite;
+    }
+
+    assert.strictEqual(rejectLocalOnly.exitCode, 1);
+    assert.match(rejectLocalOnly.stderr, /local-only/);
+    assert.strictEqual(writeLocal.testing.packages.snyk_token, 'abc');
+    assert.strictEqual(authResult.available, true);
+    assert.strictEqual(authResult.source, 'config.local.json');
+  });
+
+  test('scenario 3: worktree awareness — runner cwd = worktree directory', () => {
+    tmpDir = setupPlanningRoot({ repos: [{ name: 'api', path: '../api' }] });
+    const worktreeDir = path.join(tmpDir, 'wt-api');
+    fs.mkdirSync(worktreeDir, { recursive: true });
+    fs.writeFileSync(path.join(worktreeDir, 'package.json'), '{}');
+    setupWorktreeContext(tmpDir, { repoName: 'api', slug: 'v1.0', worktreeDir });
+    const runner = spyRunner({
+      'npm-audit': { exitCode: 0, stdout: '{}', outcome: 'ok', duration: 1, parsed: {} },
+    });
+    runScan(tmpDir, {}, makeStubDeps({
+      detector: (dir) => dir === worktreeDir ? [{ ecosystem: 'node', manifest_path: null }] : [],
+      runner,
+      snykAuth: () => ({ available: false, source: 'none' }),
+      checkToolOnPath: () => ({ available: false }),
+    }));
+    assert.strictEqual(runner.calls[0].cwd, worktreeDir);
+  });
+
+  test('scenario 4: token redaction and process.env non-mutation', () => {
+    tmpDir = setupPlanningRoot({
+      local: { testing: { packages: { snyk_token: 's3cret-deadbeef-token' } } },
+    });
+    process.env._DGS_CANARY_150 = 'alive';
+    const origSnyk = process.env.SNYK_TOKEN;
+    delete process.env.SNYK_TOKEN;
+    const runner = spyRunner({
+      'snyk': { exitCode: 0, stdout: '{}', outcome: 'ok', duration: 1, parsed: { vulnerabilities: [] } },
+    });
+    const result = runScan(tmpDir, {}, makeStubDeps({
+      detector: () => [{ ecosystem: 'node', manifest_path: null }],
+      runner,
+      checkToolOnPath: (bin) => ({ available: bin === 'snyk' }),
+    }));
+
+    assert.strictEqual(process.env._DGS_CANARY_150, 'alive');
+    assert.strictEqual(process.env.SNYK_TOKEN, undefined);
+    assert.doesNotMatch(JSON.stringify(result), /s3cret-deadbeef-token/);
+    // If any runner call happened for snyk, env was passed correctly
+    const snykCall = runner.calls.find(c => c.toolKey === 'snyk');
+    if (snykCall) assert.strictEqual(snykCall.opts.env.SNYK_TOKEN, 's3cret-deadbeef-token');
+
+    delete process.env._DGS_CANARY_150;
+    if (origSnyk !== undefined) process.env.SNYK_TOKEN = origSnyk;
+  });
+});
+
+// ─── Phase 151 composition — cmdPackageScan writes report + commits ──────────
+
+describe('cmdPackageScan — Phase 151 composition', () => {
+  /**
+   * Run the CLI entry under a controlled harness that:
+   *   - captures stdout / stderr without polluting the test runner
+   *   - intercepts process.exit so the test runner keeps running
+   *   - restores all three in `finally` (critical for TAP channel integrity)
+   */
+  function runCmdCaptured(fn) {
+    let exitCode = null;
+    let stdout = '';
+    let stderr = '';
+    const origExit = process.exit;
+    const origStdoutWrite = process.stdout.write.bind(process.stdout);
+    const origStderrWrite = process.stderr.write.bind(process.stderr);
+    process.exit = (c) => {
+      exitCode = c;
+      const e = new Error('__EXIT__');
+      e.__s = true;
+      throw e;
+    };
+    process.stdout.write = (d) => { stdout += String(d); return true; };
+    process.stderr.write = (d) => { stderr += String(d); return true; };
+    try {
+      try { fn(); } catch (e) { if (!e.__s) throw e; }
+    } finally {
+      process.exit = origExit;
+      process.stdout.write = origStdoutWrite;
+      process.stderr.write = origStderrWrite;
+    }
+    return { exitCode, stdout, stderr };
+  }
+
+  let tmpDir;
+  afterEach(() => { if (tmpDir) { cleanup(tmpDir); tmpDir = null; } });
+
+  test('end-to-end happy path: writes report, invokes commit, prints provenance', () => {
+    tmpDir = setupPlanningRoot({
+      repos: [{ name: 'api', path: '../api' }],
+    });
+
+    // Stub a canned snyk finding that flows through the full composition.
+    const snykJson = {
+      vulnerabilities: [{
+        id: 'SNYK-JS-LODASH-567746',
+        title: 'Prototype Pollution in lodash',
+        packageName: 'lodash',
+        version: '4.17.20',
+        severity: 'critical',
+        cvssScore: 7.4,
+        identifiers: { CVE: ['CVE-2020-8203'] },
+        url: 'https://nvd.nist.gov/vuln/detail/CVE-2020-8203',
+        from: ['your-app@1.0.0', 'auth-lib@1.0.0', 'lodash@4.17.20'],
+        fixedIn: ['4.17.21'],
+      }],
+    };
+    const runner = spyRunner({
+      'snyk': { exitCode: 0, stdout: JSON.stringify(snykJson), outcome: 'ok', duration: 1200, parsed: snykJson },
+    });
+    const commitCalls = [];
+    const commitStub = (msg, file) => {
+      commitCalls.push({ msg, file });
+      return { status: 0, stdout: '', stderr: '' };
+    };
+
+    // Use the opts._runScan test seam: pre-bind stub deps so cmdPackageScan
+    // picks up a fully stubbed scan without touching the real tool cascade.
+    const stubRunScan = (cwd_, opts_) => runScan(cwd_, opts_, {
+      detector: () => [{ ecosystem: 'node', manifest_path: null }],
+      runner,
+      snykAuth: () => ({ available: true, source: 'env', token: 't' }),
+      checkToolOnPath: (bin) => ({ available: bin === 'snyk' }),
+    });
+
+    const captured = runCmdCaptured(() => {
+      cmdPackageScan(tmpDir, [], false, { commit: commitStub, _runScan: stubRunScan });
+    });
+
+    assert.strictEqual(captured.exitCode, 0);
+    assert.match(captured.stdout, /Wrote /);
+    assert.match(captured.stdout, /tool: snyk/);
+    assert.strictEqual(commitCalls.length, 1);
+    assert.match(commitCalls[0].file, /PACKAGE-SCAN/);
+    assert.ok(fs.existsSync(commitCalls[0].file));
+  });
+
+  test('end-to-end clean-scan: zero findings, "clean scan" phrase, commit still invoked', () => {
+    tmpDir = setupPlanningRoot({
+      repos: [{ name: 'api', path: '../api' }],
+    });
+    const runner = spyRunner({
+      'osv-scanner': { exitCode: 0, stdout: '{}', outcome: 'ok', duration: 500, parsed: { results: [] } },
+    });
+    const commitCalls = [];
+    const commitStub = (msg, file) => { commitCalls.push({ msg, file }); return { status: 0, stdout: '', stderr: '' }; };
+
+    const stubRunScan = (cwd_, opts_) => runScan(cwd_, opts_, {
+      detector: () => [{ ecosystem: 'node', manifest_path: null }],
+      runner,
+      snykAuth: () => ({ available: false, source: 'none' }),
+      checkToolOnPath: (bin) => ({ available: bin === 'osv-scanner' }),
+    });
+
+    const captured = runCmdCaptured(() => {
+      cmdPackageScan(tmpDir, [], false, { commit: commitStub, _runScan: stubRunScan });
+    });
+
+    assert.strictEqual(captured.exitCode, 0);
+    assert.match(captured.stdout, /clean scan/);
+    assert.strictEqual(commitCalls.length, 1);
+  });
+
+  test('pin-unavailable short-circuit: no report, no commit, stderr contains install hint', () => {
+    tmpDir = setupPlanningRoot({
+      config: { testing: { packages: { tool: 'snyk' } } },
+      repos: [{ name: 'api', path: '../api' }],
+    });
+    const commitCalls = [];
+    const commitStub = (msg, file) => { commitCalls.push({ msg, file }); return { status: 0, stdout: '', stderr: '' }; };
+
+    const stubRunScan = (cwd_, opts_) => runScan(cwd_, opts_, {
+      detector: () => [{ ecosystem: 'node', manifest_path: null }],
+      runner: spyRunner(),
+      snykAuth: () => ({ available: false, source: 'none' }),
+      checkToolOnPath: () => ({ available: false }),
+    });
+
+    const captured = runCmdCaptured(() => {
+      cmdPackageScan(tmpDir, [], false, { commit: commitStub, _runScan: stubRunScan });
+    });
+
+    assert.notStrictEqual(captured.exitCode, 0);
+    assert.match(captured.stderr, /Scan failed:/);
+    assert.match(captured.stderr, /tool_unavailable_on_pin/);
+    assert.strictEqual(commitCalls.length, 0);
+    // No file written at the project root.
+    const entries = fs.readdirSync(tmpDir);
+    const wrote = entries.some(e => /PACKAGE-SCAN/.test(e));
+    assert.strictEqual(wrote, false);
+  });
+
+  test('commit-failure resilience: report stays on disk; CLI exits 0', () => {
+    tmpDir = setupPlanningRoot({
+      repos: [{ name: 'api', path: '../api' }],
+    });
+    const runner = spyRunner({
+      'osv-scanner': { exitCode: 0, stdout: '{}', outcome: 'ok', duration: 500, parsed: { results: [] } },
+    });
+    const commitStub = (msg, file) => ({ status: 1, stdout: '', stderr: 'fake commit failure' });
+
+    const stubRunScan = (cwd_, opts_) => runScan(cwd_, opts_, {
+      detector: () => [{ ecosystem: 'node', manifest_path: null }],
+      runner,
+      snykAuth: () => ({ available: false, source: 'none' }),
+      checkToolOnPath: (bin) => ({ available: bin === 'osv-scanner' }),
+    });
+
+    let reportedPath;
+    const captured = runCmdCaptured(() => {
+      cmdPackageScan(tmpDir, [], false, {
+        _runScan: stubRunScan,
+        commit: (m, f) => {
+          reportedPath = f;
+          return commitStub(m, f);
+        },
+      });
+    });
+
+    assert.strictEqual(captured.exitCode, 0);
+    assert.match(captured.stderr, /Commit failed/);
+    assert.ok(reportedPath && fs.existsSync(reportedPath), 'report must exist on disk after commit failure');
+  });
+
+  test('raw mode: JSON emitted, commit still invoked', () => {
+    tmpDir = setupPlanningRoot({
+      repos: [{ name: 'api', path: '../api' }],
+    });
+    const runner = spyRunner({
+      'osv-scanner': { exitCode: 0, stdout: '{}', outcome: 'ok', duration: 500, parsed: { results: [] } },
+    });
+    const commitCalls = [];
+    const commitStub = (msg, file) => { commitCalls.push({ msg, file }); return { status: 0, stdout: '', stderr: '' }; };
+
+    const stubRunScan = (cwd_, opts_) => runScan(cwd_, opts_, {
+      detector: () => [{ ecosystem: 'node', manifest_path: null }],
+      runner,
+      snykAuth: () => ({ available: false, source: 'none' }),
+      checkToolOnPath: (bin) => ({ available: bin === 'osv-scanner' }),
+    });
+
+    const captured = runCmdCaptured(() => {
+      cmdPackageScan(tmpDir, [], true, { commit: commitStub, _runScan: stubRunScan });
+    });
+
+    assert.strictEqual(captured.exitCode, 0);
+    // raw=true emits JSON via output()
+    assert.match(captured.stdout, /"exit_code"|"findings"/);
+    // Non-raw provenance line should NOT appear.
+    assert.doesNotMatch(captured.stdout, /Wrote /);
+    assert.strictEqual(commitCalls.length, 1);
+  });
+
+  test('dispatch: node dgs-tools.cjs package-scan invokes cmdPackageScan', () => {
+    tmpDir = setupPlanningRoot({
+      config: { mode: 'v2' },
+      repos: [],
+    });
+    // Ensure REPOS.md is empty (no repos) and product root has no manifests.
+    fs.writeFileSync(path.join(tmpDir, 'REPOS.md'), '# Repos\n');
+    const dgsToolsPath = path.resolve(__dirname, '..', 'dgs-tools.cjs');
+    const { spawnSync } = require('child_process');
+    const result = spawnSync('node', [dgsToolsPath, 'package-scan', '--raw'], {
+      cwd: tmpDir,
+      encoding: 'utf-8',
+      timeout: 20000,
+    });
+    assert.notStrictEqual(result.status, 127, 'dgs-tools should not fail with command-not-found');
+    const combined = (result.stderr || '') + (result.stdout || '');
+    assert.doesNotMatch(combined, /Unknown command/);
+    // The dispatch itself proves the case is wired; the scan behaviour is
+    // covered by the earlier tests. Any of these tokens indicates a reached
+    // code path inside cmdPackageScan or downstream:
+    assert.match(combined, /(exit_code|Wrote|Scan failed|tool_per_target|package-scan)/);
+  });
+});
+
+// ─── Phase 152 Plan 03: gate-parity (PKG-26) ─────────────────────────────────
+//
+// Byte-level standalone-vs-gate parity test. Proves writePackageScanReport is
+// deterministic given identical inputs and that the emitter's output bytes
+// match a pinned golden fixture. Any silent drift in canonical shape or
+// ordering trips the first assertion loudly.
+// ─────────────────────────────────────────────────────────────────────────────
+describe('gate-parity (PKG-26)', () => {
+  const FIXTURE_DIR = path.resolve(__dirname, 'fixtures', 'package-scan');
+  const RUNRESULT_PATH = path.join(FIXTURE_DIR, 'gate-parity-runresult.json');
+  const EXPECTED_PATH = path.join(FIXTURE_DIR, 'gate-parity-expected.md');
+  const FIXED_DATE = new Date('2026-04-18T00:00:00.000Z');
+
+  let tmpDir;
+  afterEach(() => { if (tmpDir) cleanup(tmpDir); });
+
+  const {
+    writePackageScanReport,
+    _parseEmittedYaml,
+  } = require('./package-scan-report.cjs');
+
+  test('byte-identical golden parity: writePackageScanReport bytes === gate-parity-expected.md', () => {
+    tmpDir = setupPlanningRoot({});
+    const runResult = JSON.parse(fs.readFileSync(RUNRESULT_PATH, 'utf8'));
+    const outPath = path.join(tmpDir, 'standalone.md');
+    writePackageScanReport(tmpDir, runResult, {
+      overridePath: outPath,
+      now: () => FIXED_DATE,
+    });
+    const actual = fs.readFileSync(outPath);
+    const expected = fs.readFileSync(EXPECTED_PATH);
+    if (Buffer.compare(actual, expected) !== 0) {
+      console.error('Gate-parity bytes differ. Regenerate with the command in 152-03-PLAN.md Task 2 ONLY after an intentional emitter change.');
+      console.error('First 500 bytes of actual:', actual.slice(0, 500).toString());
+      console.error('First 500 bytes of expected:', expected.slice(0, 500).toString());
+    }
+    assert.strictEqual(Buffer.compare(actual, expected), 0, 'bytes must match golden fixture');
+  });
+
+  test('standalone-vs-gate parity: JSON round-trip of runResult produces identical bytes', () => {
+    const tmpA = setupPlanningRoot({});
+    const tmpB = setupPlanningRoot({});
+    try {
+      const runResult = JSON.parse(fs.readFileSync(RUNRESULT_PATH, 'utf8'));
+
+      // Standalone invocation: writePackageScanReport called directly.
+      const outA = path.join(tmpA, 'standalone.md');
+      writePackageScanReport(tmpA, runResult, {
+        overridePath: outA,
+        now: () => FIXED_DATE,
+      });
+
+      // Simulated gate invocation: the future test-gate orchestrator would
+      // serialise the runResult across a subagent boundary and pass the
+      // deserialised copy to the writer. JSON round-trip simulates that.
+      function simulateGateInvocation(cwd, rr, opts) {
+        const copy = JSON.parse(JSON.stringify(rr));
+        return writePackageScanReport(cwd, copy, opts);
+      }
+      const outB = path.join(tmpB, 'gate.md');
+      simulateGateInvocation(tmpB, runResult, {
+        overridePath: outB,
+        now: () => FIXED_DATE,
+      });
+
+      const standaloneBytes = fs.readFileSync(outA);
+      const gateBytes = fs.readFileSync(outB);
+      assert.strictEqual(
+        Buffer.compare(standaloneBytes, gateBytes),
+        0,
+        'standalone bytes must equal gate (JSON-round-tripped) bytes',
+      );
+    } finally {
+      cleanup(tmpA);
+      cleanup(tmpB);
+    }
+  });
+
+  test('YAML findings block extracts + round-trips via _parseEmittedYaml', () => {
+    const content = fs.readFileSync(EXPECTED_PATH, 'utf8');
+    const m = content.match(/^---\n([\s\S]*?)\n---/);
+    assert.ok(m, 'frontmatter fence present');
+    const parsed = _parseEmittedYaml('---\n' + m[1] + '\n---');
+    assert.ok(Array.isArray(parsed.findings), 'findings is an array');
+    assert.strictEqual(parsed.findings.length, 5, 'exactly 5 canonical findings');
+
+    const ids = parsed.findings.map(f => f.id);
+    assert.deepStrictEqual(
+      ids,
+      ['pkg-001', 'pkg-002', 'pkg-002-lic', 'pkg-003', 'pkg-004'],
+      'findings ordered: security (pkg-001), security (pkg-002), licence (pkg-002-lic), security (pkg-003), security (pkg-004)',
+    );
+
+    // Licence finding assertions (PKG-23 split).
+    const lic = parsed.findings[2];
+    assert.strictEqual(lic.gap_type, 'dependency-licence');
+    assert.strictEqual(lic.severity, 'high');
+    assert.strictEqual(lic.resource_id, 'gpl-licensed-dep@2.0.0');
+
+    // moderate → medium.
+    assert.strictEqual(parsed.findings[1].severity, 'medium');
+
+    // null → medium (pip-audit).
+    assert.strictEqual(parsed.findings[3].severity, 'medium');
+
+    // critical stays critical (npm-audit pass-through).
+    assert.strictEqual(parsed.findings[4].severity, 'critical');
+  });
+});
+
+// ─── Phase 152 Plan 01 Task 3: pkg-NNN id assignment — licence split ─────────
+describe('pkg-NNN id assignment — licence split (PKG-22)', () => {
+  let tmpDir;
+  afterEach(() => { if (tmpDir) cleanup(tmpDir); });
+
+  test('orchestrator assigns one pkg-NNN per adapter finding; licence split happens at report-writer', () => {
+    tmpDir = setupPlanningRoot({
+      repos: [{ name: 'api', path: '../api' }],
+    });
+    // Canned Snyk output: one vulnerability with licence GPL-3.0.
+    const snykJson = {
+      vulnerabilities: [{
+        id: 'SNYK-JS-GPL-001',
+        title: 'Prototype Pollution in gpl-licensed-dep',
+        packageName: 'gpl-licensed-dep',
+        version: '2.0.0',
+        severity: 'high',
+        cvssScore: 7.2,
+        identifiers: { CVE: [] },
+        url: 'https://example.com/advisory',
+        from: ['your-app@1.0.0', 'gpl-licensed-dep@2.0.0'],
+        fixedIn: [],
+        license: 'GPL-3.0',
+      }],
+    };
+    const runner = spyRunner({
+      'snyk': { exitCode: 0, stdout: JSON.stringify(snykJson), outcome: 'ok', duration: 800, parsed: snykJson },
+    });
+
+    // Detector returns ecosystem ONLY for the `api` target; product_root has no manifests.
+    const detector = (dir) => {
+      if (/api$/.test(dir)) return [{ ecosystem: 'node', manifest_path: null }];
+      return [];
+    };
+
+    const result = runScan(tmpDir, {}, {
+      detector,
+      runner,
+      snykAuth: () => ({ available: true, source: 'env', token: 't' }),
+      checkToolOnPath: (bin) => ({ available: bin === 'snyk' }),
+    });
+
+    // Orchestrator-level: exactly ONE finding (licence split is report-writer-level).
+    assert.strictEqual(result.findings.length, 1, 'orchestrator produces 1 finding per adapter entry');
+    assert.strictEqual(result.findings[0].id, 'pkg-001');
+    assert.strictEqual(result.findings[0].licence, 'GPL-3.0');
+
+    // Now emit via writePackageScanReport and assert the YAML findings block
+    // contains TWO entries with ids pkg-001 and pkg-001-lic.
+    const { writePackageScanReport, _parseEmittedYaml } = require('./package-scan-report.cjs');
+    const outPath = path.join(tmpDir, 'OUT.md');
+    writePackageScanReport(tmpDir, result, { overridePath: outPath, now: () => new Date('2026-04-17T00:00:00.000Z') });
+    const content = fs.readFileSync(outPath, 'utf-8');
+    const m = content.match(/^---\n([\s\S]*?)\n---/);
+    assert.ok(m, 'frontmatter present');
+    const parsed = _parseEmittedYaml('---\n' + m[1] + '\n---');
+    assert.strictEqual(parsed.findings.length, 2, 'report writer splits GPL finding into security + licence');
+    assert.strictEqual(parsed.findings[0].id, 'pkg-001');
+    assert.strictEqual(parsed.findings[0].gap_type, 'dependency-security');
+    assert.strictEqual(parsed.findings[1].id, 'pkg-001-lic');
+    assert.strictEqual(parsed.findings[1].gap_type, 'dependency-licence');
+    assert.strictEqual(parsed.findings[1].severity, 'high');
+    // Both halves share the same resource_id (correlation key).
+    assert.strictEqual(parsed.findings[0].resource_id, 'gpl-licensed-dep@2.0.0');
+    assert.strictEqual(parsed.findings[1].resource_id, 'gpl-licensed-dep@2.0.0');
+  });
+});
+
+// ─── Phase 153 Plan 01: CLI flags (PKG-27, PKG-28) ────────────────────────────
+
+describe('Phase 153: CLI flags (PKG-27, PKG-28)', () => {
+  const {
+    _parseArgs,
+    _severityRank,
+    _filterByThreshold,
+  } = require('./package-scan.cjs');
+
+  describe('_parseArgs(args)', () => {
+    test('empty args => all defaults', () => {
+      const r = _parseArgs([]);
+      assert.deepStrictEqual(r, {
+        threshold: null,
+        only_repo: null,
+        include_dev_dependencies: null,
+        json: false,
+        raw: false,
+      });
+    });
+    test('--threshold high => threshold:high', () => {
+      assert.strictEqual(_parseArgs(['--threshold', 'high']).threshold, 'high');
+    });
+    test('--threshold critical => threshold:critical', () => {
+      assert.strictEqual(_parseArgs(['--threshold', 'critical']).threshold, 'critical');
+    });
+    test('--threshold low => threshold:low', () => {
+      assert.strictEqual(_parseArgs(['--threshold', 'low']).threshold, 'low');
+    });
+    test('--threshold bogus => throws', () => {
+      assert.throws(() => _parseArgs(['--threshold', 'bogus']),
+        /Invalid threshold.*critical.*high.*medium.*low/);
+    });
+    test('--repo api => only_repo:api', () => {
+      assert.strictEqual(_parseArgs(['--repo', 'api']).only_repo, 'api');
+    });
+    test('--repo api --threshold high => both set', () => {
+      const r = _parseArgs(['--repo', 'api', '--threshold', 'high']);
+      assert.strictEqual(r.only_repo, 'api');
+      assert.strictEqual(r.threshold, 'high');
+    });
+    test('--include-dev-deps => include_dev_dependencies:true', () => {
+      assert.strictEqual(_parseArgs(['--include-dev-deps']).include_dev_dependencies, true);
+    });
+    test('--no-include-dev-deps => include_dev_dependencies:false', () => {
+      assert.strictEqual(_parseArgs(['--no-include-dev-deps']).include_dev_dependencies, false);
+    });
+    test('--json => json:true', () => {
+      assert.strictEqual(_parseArgs(['--json']).json, true);
+    });
+    test('--raw => raw:true (independent flag)', () => {
+      assert.strictEqual(_parseArgs(['--raw']).raw, true);
+    });
+    test('--threshold without value => throws', () => {
+      assert.throws(() => _parseArgs(['--threshold']), /Missing value for --threshold/);
+    });
+  });
+
+  describe('_severityRank(tier)', () => {
+    test('canonical tiers map to descending integers', () => {
+      assert.strictEqual(_severityRank('critical'), 4);
+      assert.strictEqual(_severityRank('high'), 3);
+      assert.strictEqual(_severityRank('medium'), 2);
+      assert.strictEqual(_severityRank('low'), 1);
+    });
+    test('unknown => 0', () => {
+      assert.strictEqual(_severityRank('unknown'), 0);
+    });
+    test('null => 0', () => {
+      assert.strictEqual(_severityRank(null), 0);
+    });
+    test('CRITICAL (case-insensitive) => 4', () => {
+      assert.strictEqual(_severityRank('CRITICAL'), 4);
+    });
+    test('strict ordering', () => {
+      assert.ok(_severityRank('critical') > _severityRank('high'));
+      assert.ok(_severityRank('high') > _severityRank('medium'));
+      assert.ok(_severityRank('medium') > _severityRank('low'));
+      assert.ok(_severityRank('low') > _severityRank('unknown'));
+    });
+  });
+
+  describe('_filterByThreshold(findings, threshold)', () => {
+    const sevs = ['critical', 'high', 'medium', 'low'];
+    const mkF = (s) => ({ severity: s });
+    test('empty findings => empty array', () => {
+      assert.deepStrictEqual(_filterByThreshold([], 'high'), []);
+    });
+    test('threshold low => returns all', () => {
+      const f = sevs.map(mkF);
+      assert.strictEqual(_filterByThreshold(f, 'low').length, 4);
+    });
+    test('threshold medium => drops low', () => {
+      const f = sevs.map(mkF);
+      const out = _filterByThreshold(f, 'medium');
+      assert.strictEqual(out.length, 3);
+      assert.ok(out.every(x => x.severity !== 'low'));
+    });
+    test('threshold high => keeps only critical+high', () => {
+      const f = sevs.map(mkF);
+      const out = _filterByThreshold(f, 'high');
+      assert.strictEqual(out.length, 2);
+    });
+    test('monotonicity over mixed input of 20', () => {
+      const arr = [];
+      for (let i = 0; i < 5; i++) for (const s of sevs) arr.push(mkF(s));
+      const lenLow = _filterByThreshold(arr, 'low').length;
+      const lenMed = _filterByThreshold(arr, 'medium').length;
+      const lenHigh = _filterByThreshold(arr, 'high').length;
+      const lenCrit = _filterByThreshold(arr, 'critical').length;
+      assert.ok(lenLow >= lenMed);
+      assert.ok(lenMed >= lenHigh);
+      assert.ok(lenHigh >= lenCrit);
+    });
+  });
+
+  describe('runScan with opts.threshold', () => {
+    let tmpDir;
+    afterEach(() => cleanup(tmpDir));
+
+    test('threshold high filters to critical+high only', () => {
+      tmpDir = setupPlanningRoot();
+      const detector = (dir) => {
+        if (dir === tmpDir) return [{ ecosystem: 'node', manifest_path: null }];
+        return [];
+      };
+      const snykPayload = {
+        vulnerabilities: [
+          { packageName: 'a', version: '1.0', severity: 'critical', title: 'a', identifiers: { CVE: [] }, from: ['x@1', 'a@1'] },
+          { packageName: 'b', version: '1.0', severity: 'high', title: 'b', identifiers: { CVE: [] }, from: ['x@1', 'b@1'] },
+          { packageName: 'c', version: '1.0', severity: 'medium', title: 'c', identifiers: { CVE: [] }, from: ['x@1', 'c@1'] },
+          { packageName: 'd', version: '1.0', severity: 'low', title: 'd', identifiers: { CVE: [] }, from: ['x@1', 'd@1'] },
+        ],
+      };
+      const runner = spyRunner({
+        'snyk': { exitCode: 0, stdout: JSON.stringify(snykPayload), outcome: 'ok', duration: 1, parsed: snykPayload },
+      });
+      const result = runScan(tmpDir, { threshold: 'high' }, {
+        detector, runner,
+        snykAuth: () => ({ available: true, source: 'env', token: 't' }),
+        checkToolOnPath: (bin) => ({ available: bin === 'snyk' }),
+      });
+      assert.strictEqual(result.findings.length, 2);
+      assert.ok(result.findings.every(f => ['critical', 'high'].includes(f.severity)));
+    });
+
+    test('opts:{} keeps all 4 findings (default threshold)', () => {
+      tmpDir = setupPlanningRoot();
+      const detector = (dir) => dir === tmpDir ? [{ ecosystem: 'node', manifest_path: null }] : [];
+      const snykPayload = {
+        vulnerabilities: [
+          { packageName: 'a', version: '1.0', severity: 'critical', title: 'a', identifiers: { CVE: [] }, from: ['x@1', 'a@1'] },
+          { packageName: 'b', version: '1.0', severity: 'high', title: 'b', identifiers: { CVE: [] }, from: ['x@1', 'b@1'] },
+          { packageName: 'c', version: '1.0', severity: 'medium', title: 'c', identifiers: { CVE: [] }, from: ['x@1', 'c@1'] },
+          { packageName: 'd', version: '1.0', severity: 'low', title: 'd', identifiers: { CVE: [] }, from: ['x@1', 'd@1'] },
+        ],
+      };
+      const runner = spyRunner({
+        'snyk': { exitCode: 0, stdout: JSON.stringify(snykPayload), outcome: 'ok', duration: 1, parsed: snykPayload },
+      });
+      const result = runScan(tmpDir, {}, {
+        detector, runner,
+        snykAuth: () => ({ available: true, source: 'env', token: 't' }),
+        checkToolOnPath: (bin) => ({ available: bin === 'snyk' }),
+      });
+      assert.strictEqual(result.findings.length, 4);
+    });
+
+    test('config severity_threshold=medium honoured when no opts.threshold', () => {
+      tmpDir = setupPlanningRoot({ config: { testing: { packages: { severity_threshold: 'medium' } } } });
+      const detector = (dir) => dir === tmpDir ? [{ ecosystem: 'node', manifest_path: null }] : [];
+      const snykPayload = {
+        vulnerabilities: [
+          { packageName: 'a', version: '1.0', severity: 'critical', title: 'a', identifiers: { CVE: [] }, from: ['x@1', 'a@1'] },
+          { packageName: 'b', version: '1.0', severity: 'high', title: 'b', identifiers: { CVE: [] }, from: ['x@1', 'b@1'] },
+          { packageName: 'c', version: '1.0', severity: 'medium', title: 'c', identifiers: { CVE: [] }, from: ['x@1', 'c@1'] },
+          { packageName: 'd', version: '1.0', severity: 'low', title: 'd', identifiers: { CVE: [] }, from: ['x@1', 'd@1'] },
+        ],
+      };
+      const runner = spyRunner({
+        'snyk': { exitCode: 0, stdout: JSON.stringify(snykPayload), outcome: 'ok', duration: 1, parsed: snykPayload },
+      });
+      const result = runScan(tmpDir, {}, {
+        detector, runner,
+        snykAuth: () => ({ available: true, source: 'env', token: 't' }),
+        checkToolOnPath: (bin) => ({ available: bin === 'snyk' }),
+      });
+      assert.strictEqual(result.findings.length, 3);
+    });
+  });
+
+  describe('runScan with opts.only_repo', () => {
+    let tmpDir;
+    afterEach(() => cleanup(tmpDir));
+
+    test('only_repo:api scans api only (excludes product root)', () => {
+      tmpDir = setupPlanningRoot({ repos: [
+        { name: 'api', path: '../api' },
+        { name: 'web', path: '../web' },
+      ]});
+      const detector = (_dir) => [];
+      const result = runScan(tmpDir, { only_repo: 'api' }, makeStubDeps({ detector }));
+      assert.strictEqual(result.exit_code, 0);
+      // Only one repo target scanned (api), product root excluded
+      assert.strictEqual(result.repo_results.length, 1);
+      assert.strictEqual(result.repo_results[0].repo, 'api');
+    });
+
+    test('only_repo:nonexistent => exit_code 2 with diagnostic', () => {
+      tmpDir = setupPlanningRoot({ repos: [
+        { name: 'api', path: '../api' },
+        { name: 'web', path: '../web' },
+      ]});
+      const result = runScan(tmpDir, { only_repo: 'nonexistent' }, makeStubDeps());
+      assert.strictEqual(result.exit_code, 2);
+      assert.ok(Array.isArray(result.diagnostics));
+      assert.ok(result.diagnostics.length >= 1);
+      assert.strictEqual(result.diagnostics[0].kind, 'unknown_repo');
+      assert.match(result.diagnostics[0].message, /Unknown repo: 'nonexistent'/);
+      assert.match(result.diagnostics[0].message, /Valid repos: api, web/);
+    });
+
+    test('only_repo:null => all repos + product root scanned', () => {
+      tmpDir = setupPlanningRoot({ repos: [{ name: 'api', path: '../api' }] });
+      const result = runScan(tmpDir, { only_repo: null }, makeStubDeps({ detector: () => [] }));
+      assert.strictEqual(result.exit_code, 0);
+      assert.strictEqual(result.repo_results.length, 2); // api + product root
+    });
+
+    test('empty REPOS.md + only_repo:api => exit_code 2 (none registered)', () => {
+      tmpDir = setupPlanningRoot();
+      const result = runScan(tmpDir, { only_repo: 'api' }, makeStubDeps());
+      assert.strictEqual(result.exit_code, 2);
+      assert.match(result.diagnostics[0].message, /Unknown repo/);
+      assert.match(result.diagnostics[0].message, /(none registered|Valid repos:)/);
+    });
+  });
+
+  describe('cmdPackageScan argv routing', () => {
+    let tmpDir;
+    afterEach(() => cleanup(tmpDir));
+
+    test('--threshold high passed through to runScan', () => {
+      tmpDir = setupPlanningRoot();
+      let capturedOpts;
+      const runScanSpy = (cwd, opts) => {
+        capturedOpts = opts;
+        return { exit_code: 0, findings: [], repo_results: [], tool_per_target: {}, skipped: [], diagnostics: [] };
+      };
+      // Stub process.exit so it does not kill the test process.
+      const origExit = process.exit;
+      process.exit = () => {};
+      try {
+        cmdPackageScan(tmpDir, ['--threshold', 'high'], false, {
+          _runScan: runScanSpy,
+          commit: () => ({ status: 0, stdout: '', stderr: '' }),
+        });
+      } finally {
+        process.exit = origExit;
+      }
+      assert.strictEqual(capturedOpts.threshold, 'high');
+    });
+
+    test('--repo api passed through to runScan', () => {
+      tmpDir = setupPlanningRoot();
+      let capturedOpts;
+      const runScanSpy = (cwd, opts) => {
+        capturedOpts = opts;
+        return { exit_code: 0, findings: [], repo_results: [], tool_per_target: {}, skipped: [], diagnostics: [] };
+      };
+      const origExit = process.exit;
+      process.exit = () => {};
+      try {
+        cmdPackageScan(tmpDir, ['--repo', 'api'], false, {
+          _runScan: runScanSpy,
+          commit: () => ({ status: 0, stdout: '', stderr: '' }),
+        });
+      } finally {
+        process.exit = origExit;
+      }
+      assert.strictEqual(capturedOpts.only_repo, 'api');
+    });
+
+    test('--no-include-dev-deps passed through', () => {
+      tmpDir = setupPlanningRoot();
+      let capturedOpts;
+      const runScanSpy = (cwd, opts) => {
+        capturedOpts = opts;
+        return { exit_code: 0, findings: [], repo_results: [], tool_per_target: {}, skipped: [], diagnostics: [] };
+      };
+      const origExit = process.exit;
+      process.exit = () => {};
+      try {
+        cmdPackageScan(tmpDir, ['--no-include-dev-deps'], false, {
+          _runScan: runScanSpy,
+          commit: () => ({ status: 0, stdout: '', stderr: '' }),
+        });
+      } finally {
+        process.exit = origExit;
+      }
+      assert.strictEqual(capturedOpts.include_dev_dependencies, false);
+    });
+
+    test('--json emits compact JSON to stdout (raw-equivalent)', () => {
+      tmpDir = setupPlanningRoot();
+      const runScanSpy = (_cwd, _opts) => ({
+        exit_code: 0, findings: [], repo_results: [], tool_per_target: {}, skipped: [], diagnostics: [],
+      });
+      const origExit = process.exit;
+      const origWrite = process.stdout.write;
+      let captured = '';
+      process.exit = () => {};
+      process.stdout.write = (chunk) => { captured += chunk; return true; };
+      try {
+        cmdPackageScan(tmpDir, ['--json'], false, {
+          _runScan: runScanSpy,
+          commit: () => ({ status: 0, stdout: '', stderr: '' }),
+        });
+      } finally {
+        process.exit = origExit;
+        process.stdout.write = origWrite;
+      }
+      // First line of captured output should be JSON
+      const firstLine = captured.split('\n')[0];
+      const parsed = JSON.parse(firstLine);
+      assert.strictEqual(parsed.exit_code, 0);
+    });
+
+    test('--threshold bogus => exit 2 + stderr diagnostic', () => {
+      tmpDir = setupPlanningRoot();
+      const origExit = process.exit;
+      const origStderrWrite = process.stderr.write;
+      let exitCode = null;
+      let stderr = '';
+      process.exit = (code) => { exitCode = code; };
+      process.stderr.write = (s) => { stderr += s; return true; };
+      try {
+        cmdPackageScan(tmpDir, ['--threshold', 'bogus'], false, {
+          _runScan: () => ({ exit_code: 0, findings: [], repo_results: [], tool_per_target: {}, skipped: [], diagnostics: [] }),
+          commit: () => ({ status: 0, stdout: '', stderr: '' }),
+        });
+      } finally {
+        process.exit = origExit;
+        process.stderr.write = origStderrWrite;
+      }
+      assert.strictEqual(exitCode, 2);
+      assert.match(stderr, /Invalid threshold/);
+    });
+  });
+
+  describe('dispatcher smoke', () => {
+    let tmpDir;
+    afterEach(() => cleanup(tmpDir));
+
+    test('--threshold critical --json from dispatcher emits valid JSON or exits 2', () => {
+      tmpDir = setupPlanningRoot();
+      const dgsToolsPath = path.join(__dirname, '..', 'dgs-tools.cjs');
+      const { spawnSync } = require('child_process');
+      const r = spawnSync('node', [dgsToolsPath, 'package-scan', '--threshold', 'critical', '--json'], {
+        cwd: tmpDir, encoding: 'utf-8', timeout: 30000,
+      });
+      // Accept exit 0 (clean scan; valid JSON in stdout) OR exit 2 (some setup error)
+      assert.ok(r.status === 0 || r.status === 2, `unexpected exit: ${r.status}`);
+      if (r.status === 0) {
+        const firstLine = (r.stdout || '').split('\n')[0];
+        if (firstLine.length > 0 && firstLine.trim().startsWith('{')) {
+          const parsed = JSON.parse(firstLine);
+          assert.ok(typeof parsed === 'object');
+        }
+      }
+    });
+
+    test('--threshold bogus from dispatcher exits 2 with Invalid threshold stderr', () => {
+      tmpDir = setupPlanningRoot();
+      const dgsToolsPath = path.join(__dirname, '..', 'dgs-tools.cjs');
+      const { spawnSync } = require('child_process');
+      const r = spawnSync('node', [dgsToolsPath, 'package-scan', '--threshold', 'bogus'], {
+        cwd: tmpDir, encoding: 'utf-8', timeout: 30000,
+      });
+      assert.strictEqual(r.status, 2);
+      assert.match(r.stderr || '', /Invalid threshold/);
+    });
+
+    test('--repo ghost from dispatcher exits 2', () => {
+      tmpDir = setupPlanningRoot();
+      const dgsToolsPath = path.join(__dirname, '..', 'dgs-tools.cjs');
+      const { spawnSync } = require('child_process');
+      const r = spawnSync('node', [dgsToolsPath, 'package-scan', '--repo', 'ghost'], {
+        cwd: tmpDir, encoding: 'utf-8', timeout: 30000,
+      });
+      assert.strictEqual(r.status, 2);
+      const stderr = r.stderr || '';
+      assert.ok(/Unknown repo/.test(stderr) || /none registered/.test(stderr) || /Scan failed/.test(stderr), `stderr: ${stderr}`);
+    });
+  });
+});
+
+// ─── Phase 153 Plan 02: .snyk policy detection (PKG-32) ──────────────────────
+
+describe('Phase 153: .snyk policy detection (PKG-32)', () => {
+  const { _detectSnykPolicy } = require('./package-scan.cjs');
+  let tmpDir;
+  afterEach(() => cleanup(tmpDir));
+
+  test('_detectSnykPolicy(dir with .snyk file) => true', () => {
+    tmpDir = setupPlanningRoot();
+    fs.writeFileSync(path.join(tmpDir, '.snyk'), 'version: v1.0.0\n');
+    assert.strictEqual(_detectSnykPolicy(tmpDir), true);
+  });
+
+  test('_detectSnykPolicy(dir without .snyk) => false', () => {
+    tmpDir = setupPlanningRoot();
+    assert.strictEqual(_detectSnykPolicy(tmpDir), false);
+  });
+
+  test('collectScanTargets stamps has_snyk_policy on every target', () => {
+    tmpDir = setupPlanningRoot({ repos: [{ name: 'api', path: '../api' }] });
+    fs.writeFileSync(path.join(tmpDir, '.snyk'), 'version: v1.0.0\n');
+    const { targets } = collectScanTargets(tmpDir);
+    for (const t of targets) {
+      assert.strictEqual(typeof t.has_snyk_policy, 'boolean');
+    }
+    const productRoot = targets.find(t => t.name === '_product_root');
+    assert.strictEqual(productRoot.has_snyk_policy, true);
+  });
+
+  test('runScan: ctx.recordSuppressions(2) -> repo_results[0].snyk_suppressions_count === 2', () => {
+    tmpDir = setupPlanningRoot();
+    fs.writeFileSync(path.join(tmpDir, '.snyk'), 'version: v1.0.0\n');
+    const detector = (dir) => dir === tmpDir ? [{ ecosystem: 'node', manifest_path: null }] : [];
+    // Stub adapter via ADAPTER_FOR_TOOL override is hard; we use a stubbed runner
+    // and rely on the actual adapterSnyk to call recordSuppressions when ctx provides it.
+    const snykPayload = {
+      vulnerabilities: [
+        { packageName: 'a', version: '1.0', severity: 'high', title: 'a', identifiers: { CVE: [] }, from: ['x@1', 'a@1'] },
+        { packageName: 'b', version: '1.0', severity: 'high', title: 'b', identifiers: { CVE: [] }, from: ['x@1', 'b@1'] },
+        { packageName: 'c', version: '1.0', severity: 'high', title: 'c', identifiers: { CVE: [] }, from: ['x@1', 'c@1'] },
+      ],
+      filtered: { ignore: [{ id: 'S-1' }, { id: 'S-2' }] },
+    };
+    const runner = spyRunner({
+      'snyk': { exitCode: 0, stdout: JSON.stringify(snykPayload), outcome: 'ok', duration: 1, parsed: snykPayload },
+    });
+    const result = runScan(tmpDir, {}, {
+      detector, runner,
+      snykAuth: () => ({ available: true, source: 'env', token: 't' }),
+      checkToolOnPath: (bin) => ({ available: bin === 'snyk' }),
+    });
+    assert.strictEqual(result.findings.length, 3);
+    const productRow = result.repo_results.find(r => r.repo === '_product_root');
+    assert.ok(productRow);
+    assert.strictEqual(productRow.has_snyk_policy, true);
+    assert.strictEqual(productRow.snyk_suppressions_count, 2);
+  });
+
+  test('runScan: adapter never calls recordSuppressions => snyk_suppressions_count === 0', () => {
+    tmpDir = setupPlanningRoot();
+    const detector = (_dir) => [];
+    const result = runScan(tmpDir, {}, makeStubDeps({ detector }));
+    const productRow = result.repo_results.find(r => r.repo === '_product_root');
+    assert.ok(productRow);
+    // no manifests => no adapter invocation, but field is set safely
+    assert.strictEqual(productRow.snyk_suppressions_count, 0);
+  });
+});
+
+// ─── Phase 153 Plan 05: plan provenance (PKG-33) ─────────────────────────────
+
+describe('Phase 153: plan provenance (PKG-33)', () => {
+  let tmpDir;
+  afterEach(() => cleanup(tmpDir));
+
+  test('runScan stamps introduced_in_commit + introduced_in_plan from deps.provenanceLookup', () => {
+    tmpDir = setupPlanningRoot();
+    const detector = (dir) => dir === tmpDir ? [{ ecosystem: 'node', manifest_path: null }] : [];
+    const snykPayload = {
+      vulnerabilities: [
+        { packageName: 'lodash', version: '1.0', severity: 'high', title: 'a', identifiers: { CVE: [] }, from: ['x@1', 'lodash@1'] },
+      ],
+    };
+    const runner = spyRunner({
+      'snyk': { exitCode: 0, stdout: JSON.stringify(snykPayload), outcome: 'ok', duration: 1, parsed: snykPayload },
+    });
+    const result = runScan(tmpDir, {}, {
+      detector, runner,
+      snykAuth: () => ({ available: true, source: 'env', token: 't' }),
+      checkToolOnPath: (bin) => ({ available: bin === 'snyk' }),
+      provenanceLookup: () => ({ commit: 'abc1234', plan: '149-01' }),
+    });
+    assert.strictEqual(result.findings.length, 1);
+    assert.strictEqual(result.findings[0].introduced_in_commit, 'abc1234');
+    assert.strictEqual(result.findings[0].introduced_in_plan, '149-01');
+  });
+
+  test('lookup returning nulls => fields are null', () => {
+    tmpDir = setupPlanningRoot();
+    const detector = (dir) => dir === tmpDir ? [{ ecosystem: 'node', manifest_path: null }] : [];
+    const snykPayload = {
+      vulnerabilities: [
+        { packageName: 'lodash', version: '1.0', severity: 'high', title: 'a', identifiers: { CVE: [] }, from: ['x@1', 'lodash@1'] },
+      ],
+    };
+    const runner = spyRunner({
+      'snyk': { exitCode: 0, stdout: JSON.stringify(snykPayload), outcome: 'ok', duration: 1, parsed: snykPayload },
+    });
+    const result = runScan(tmpDir, {}, {
+      detector, runner,
+      snykAuth: () => ({ available: true, source: 'env', token: 't' }),
+      checkToolOnPath: (bin) => ({ available: bin === 'snyk' }),
+      provenanceLookup: () => ({ commit: null, plan: null }),
+    });
+    assert.strictEqual(result.findings[0].introduced_in_commit, null);
+    assert.strictEqual(result.findings[0].introduced_in_plan, null);
+  });
+
+  test('memoisation: same (repoDir, manifestPath, packageName) => lookup called once for same package', () => {
+    tmpDir = setupPlanningRoot();
+    const detector = (dir) => dir === tmpDir ? [{ ecosystem: 'node', manifest_path: null }] : [];
+    // Two findings of the SAME package — should hit cache.
+    const snykPayload = {
+      vulnerabilities: [
+        { packageName: 'lodash', version: '1.0', severity: 'high', title: 'a', identifiers: { CVE: [] }, from: ['x@1', 'lodash@1'] },
+        { packageName: 'lodash', version: '1.0', severity: 'high', title: 'b', identifiers: { CVE: [] }, from: ['x@1', 'lodash@1'] },
+        { packageName: 'axios', version: '1.0', severity: 'high', title: 'c', identifiers: { CVE: [] }, from: ['x@1', 'axios@1'] },
+      ],
+    };
+    const runner = spyRunner({
+      'snyk': { exitCode: 0, stdout: JSON.stringify(snykPayload), outcome: 'ok', duration: 1, parsed: snykPayload },
+    });
+    let lookupCalls = 0;
+    runScan(tmpDir, {}, {
+      detector, runner,
+      snykAuth: () => ({ available: true, source: 'env', token: 't' }),
+      checkToolOnPath: (bin) => ({ available: bin === 'snyk' }),
+      provenanceLookup: () => { lookupCalls += 1; return { commit: 'abc', plan: null }; },
+    });
+    // Two unique package names → two lookup calls.
+    assert.strictEqual(lookupCalls, 2);
+  });
+});
+
+// ─── Phase 153 Plan 03: licence_roster on runResult (PKG-30, PKG-34) ─────────
+
+describe('Phase 153: licence_roster on runResult (PKG-30, PKG-34)', () => {
+  let tmpDir;
+  afterEach(() => cleanup(tmpDir));
+
+  test('snyk adapter calling ctx.recordLicenceRoster => result.licence_roster has entries with repo stamped', () => {
+    tmpDir = setupPlanningRoot();
+    const detector = (dir) => dir === tmpDir ? [{ ecosystem: 'node', manifest_path: null }] : [];
+    const snykPayload = {
+      vulnerabilities: [],
+      dependencyPackages: { 'lodash@4.17.21': { name: 'lodash', version: '4.17.21', license: 'MIT' } },
+    };
+    const runner = spyRunner({
+      'snyk': { exitCode: 0, stdout: JSON.stringify(snykPayload), outcome: 'ok', duration: 1, parsed: snykPayload },
+    });
+    const result = runScan(tmpDir, {}, {
+      detector, runner,
+      snykAuth: () => ({ available: true, source: 'env', token: 't' }),
+      checkToolOnPath: (bin) => ({ available: bin === 'snyk' }),
+    });
+    assert.ok(Array.isArray(result.licence_roster));
+    assert.strictEqual(result.licence_roster.length, 1);
+    assert.strictEqual(result.licence_roster[0].package_name, 'lodash');
+    assert.strictEqual(result.licence_roster[0].repo, '_product_root');
+  });
+
+  test('multi-target scan concatenates rosters with per-entry repo stamping', () => {
+    tmpDir = setupPlanningRoot({ repos: [
+      { name: 'api', path: '../api' },
+      { name: 'web', path: '../web' },
+    ]});
+    const apiPath = path.resolve(path.dirname(tmpDir), 'api');
+    const webPath = path.resolve(path.dirname(tmpDir), 'web');
+    const detector = (dir) => {
+      if (dir === apiPath || dir === webPath) return [{ ecosystem: 'node', manifest_path: null }];
+      return [];
+    };
+    // Different roster per target — runner returns the same payload regardless,
+    // but we use a per-call snyk that examines cwd to differentiate.
+    const apiPayload = { vulnerabilities: [], dependencyPackages: { 'a@1.0': { name: 'a', version: '1.0', license: 'MIT' } } };
+    const webPayload = { vulnerabilities: [], dependencyPackages: { 'b@1.0': { name: 'b', version: '1.0', license: 'MIT' } } };
+    const runner = (cwd, _toolKey, _argv, _opts) => {
+      const payload = cwd === apiPath ? apiPayload : webPayload;
+      return { exitCode: 0, stdout: JSON.stringify(payload), outcome: 'ok', duration: 1, parsed: payload };
+    };
+    const result = runScan(tmpDir, {}, {
+      detector, runner,
+      snykAuth: () => ({ available: true, source: 'env', token: 't' }),
+      checkToolOnPath: (bin) => ({ available: bin === 'snyk' }),
+    });
+    assert.ok(Array.isArray(result.licence_roster));
+    // 2 unique entries, one per repo.
+    const repos = result.licence_roster.map(e => e.repo).sort();
+    assert.deepStrictEqual(repos, ['api', 'web']);
+  });
+
+  test('non-snyk scan => result.licence_roster is empty array (not undefined)', () => {
+    tmpDir = setupPlanningRoot();
+    const detector = (_dir) => [];
+    const result = runScan(tmpDir, {}, makeStubDeps({ detector }));
+    assert.ok(Array.isArray(result.licence_roster));
+    assert.strictEqual(result.licence_roster.length, 0);
+  });
+});
+
+
+