@ktpartners/dgs-platform 3.0.4 → 3.3.0

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

@@ -0,0 +1,1963 @@
+/**
+ * package-scan-report.test.cjs -- Unit tests for the Phase 151 report writer
+ *
+ * Covers PKG-06, PKG-07, PKG-20, PKG-21.
+ *
+ * The module under test -- package-scan-report.cjs -- emits YAML frontmatter
+ * (with round-trip validation), renders a markdown body, resolves the report
+ * placement path via a three-tier cascade (active phase -> active milestone ->
+ * project root), and composes the three in `writePackageScanReport`.
+ */
+'use strict';
+const { test, describe } = require('node:test');
+const assert = require('node:assert/strict');
+const fs = require('fs');
+const path = require('path');
+const os = require('os');
+const { execSync } = require('child_process');
+
+// The module under test. Task 1 scaffolds this as a failing require (module
+// does not yet exist); Task 2 lands the implementation and these tests pass.
+const {
+  writePackageScanReport,
+  _emitYamlFrontmatter,
+  _renderBody,
+  _resolveReportPath,
+  _parseEmittedYaml,
+} = require('./package-scan-report.cjs');
+
+const { resetPaths } = require('./paths.cjs');
+
+// ─── Helpers ──────────────────────────────────────────────────────────────────
+
+function setupPlanningRoot({ config, local, repos } = {}) {
+  const tmpDir = fs.realpathSync(fs.mkdtempSync(path.join(os.tmpdir(), 'pkgscan-report-')));
+  execSync('git init -q', { cwd: tmpDir });
+  fs.writeFileSync(path.join(tmpDir, 'config.json'), JSON.stringify(config || { mode: 'v2' }, null, 2));
+  if (local) fs.writeFileSync(path.join(tmpDir, 'config.local.json'), JSON.stringify(local, null, 2));
+  if (repos) fs.writeFileSync(path.join(tmpDir, 'REPOS.md'), repos);
+  resetPaths();
+  return tmpDir;
+}
+
+function cleanup(d) { try { fs.rmSync(d, { recursive: true, force: true }); } catch {} }
+
+function makeRunResult({ findings = [], repo_results = [], diagnostics = [], tool_per_target = {} } = {}) {
+  return {
+    exit_code: 0,
+    tool_per_target,
+    repo_results,
+    findings,
+    skipped: [],
+    diagnostics,
+  };
+}
+
+function makeFinding(overrides = {}) {
+  return {
+    id: overrides.id || 'pkg-001',
+    tool: overrides.tool || 'snyk',
+    ecosystem: overrides.ecosystem || 'node',
+    repo: overrides.repo || 'api',
+    manifest_path: overrides.manifest_path === undefined ? null : overrides.manifest_path,
+    package_name: overrides.package_name || 'lodash',
+    installed_version: overrides.installed_version || '4.17.20',
+    vulnerability: overrides.vulnerability || {
+      cve: 'CVE-2020-8203',
+      title: 'Prototype Pollution in lodash',
+      description: null,
+      reference_url: 'https://nvd.nist.gov/vuln/detail/CVE-2020-8203',
+    },
+    severity: overrides.severity === undefined ? 'critical' : overrides.severity,
+    cvss_score: overrides.cvss_score === undefined ? 7.4 : overrides.cvss_score,
+    cvss_vector: overrides.cvss_vector || null,
+    direct_or_transitive: overrides.direct_or_transitive || 'transitive',
+    dependency_chain: overrides.dependency_chain === undefined ? ['your-app', 'auth-lib', 'lodash'] : overrides.dependency_chain,
+    chain_available: overrides.chain_available === undefined ? true : overrides.chain_available,
+    fix_version: overrides.fix_version || '4.17.21',
+    remediation: overrides.remediation || 'npm install lodash@^4.17.21 --save',
+    licence: overrides.licence || null,
+  };
+}
+
+function makeFrontmatterPayload(overrides = {}) {
+  return Object.assign({
+    type: 'package-scan',
+    date: '2026-04-17',
+    tool: 'snyk',
+    repos_scanned: 1,
+    critical: 1,
+    high: 0,
+    medium: 0,
+    low: 0,
+    duration: 3,
+    findings: [
+      {
+        id: 'pkg-001',
+        test_source: 'package-scan',
+        gap_type: 'dependency-security',
+        severity: 'critical',
+        resource_id: 'lodash@4.17.20',
+        repo: 'api',
+        manifest_path: null,
+        title: 'Prototype Pollution in lodash',
+        description: null,
+        remediation: 'npm install lodash@^4.17.21 --save',
+        reference: 'https://nvd.nist.gov/vuln/detail/CVE-2020-8203',
+        cve: 'CVE-2020-8203',
+        cvss: 7.4,
+        dependency_chain: ['your-app', 'auth-lib', 'lodash'],
+        chain_available: true,
+        direct_or_transitive: 'transitive',
+        tool: 'snyk',
+      },
+    ],
+  }, overrides);
+}
+
+// ─── _emitYamlFrontmatter — happy path ────────────────────────────────────────
+
+describe('_emitYamlFrontmatter — happy path', () => {
+  test('emits `type: package-scan` as the first field', () => {
+    const emitted = _emitYamlFrontmatter(makeFrontmatterPayload());
+    assert.ok(emitted.startsWith('---\n'));
+    const afterFence = emitted.slice(4);
+    assert.ok(afterFence.startsWith('type: "package-scan"'));
+  });
+
+  test('emits all top-level fields in fixed order', () => {
+    const emitted = _emitYamlFrontmatter(makeFrontmatterPayload());
+    const expectedOrder = ['type', 'date', 'tool', 'repos_scanned', 'critical', 'high', 'medium', 'low', 'duration', 'findings'];
+    let lastIdx = -1;
+    for (const key of expectedOrder) {
+      const idx = emitted.indexOf('\n' + key + ':');
+      assert.ok(idx > lastIdx, `${key} must appear after previous fields (got idx ${idx}, lastIdx ${lastIdx})`);
+      lastIdx = idx;
+    }
+  });
+
+  test('emits `findings: []` when findings array is empty', () => {
+    const emitted = _emitYamlFrontmatter(makeFrontmatterPayload({ findings: [] }));
+    assert.match(emitted, /findings: \[\]/);
+  });
+});
+
+// ─── _emitYamlFrontmatter — adversarial corpus ────────────────────────────────
+
+describe('_emitYamlFrontmatter — adversarial corpus', () => {
+  const cases = [
+    {
+      name: 'title with colon',
+      mutate: (f) => { f.vulnerability = { ...f.vulnerability, title: 'Prototype Pollution: [CVE-2020-8203]' }; },
+      canonical_title: 'Prototype Pollution: [CVE-2020-8203]',
+    },
+    {
+      name: 'title with apostrophe',
+      mutate: (f) => { f.vulnerability = { ...f.vulnerability, title: "Denial of Service in Netty's HTTP Parser" }; },
+      canonical_title: "Denial of Service in Netty's HTTP Parser",
+    },
+    {
+      name: 'title with & * ! | >',
+      mutate: (f) => { f.vulnerability = { ...f.vulnerability, title: 'A & B * C ! D | E > F' }; },
+      canonical_title: 'A & B * C ! D | E > F',
+    },
+    {
+      name: 'description with newline (multi-line)',
+      mutate: (f) => { f.vulnerability = { ...f.vulnerability, description: 'Line one.\nLine two with indent.' }; },
+    },
+    {
+      name: 'description with backticks',
+      mutate: (f) => { f.vulnerability = { ...f.vulnerability, description: 'Call `foo()` for `bar`' }; },
+    },
+    {
+      name: 'reference URL with #fragment',
+      mutate: (f) => { f.vulnerability = { ...f.vulnerability, reference_url: 'https://example.com/advisory#details' }; },
+    },
+    {
+      name: 'scoped npm package (@scope/pkg@1.0.0)',
+      mutate: (f) => { f.package_name = '@scope/pkg'; f.installed_version = '1.0.0'; },
+    },
+    {
+      name: 'severity null',
+      mutate: (f) => { f.severity = null; },
+    },
+    {
+      name: 'manifest_path null',
+      mutate: (f) => { f.manifest_path = null; },
+    },
+    {
+      name: 'cvss null, cve null, chain null, chain_available false',
+      mutate: (f) => {
+        f.cvss_score = null;
+        f.vulnerability = { ...f.vulnerability, cve: null };
+        f.dependency_chain = null;
+        f.chain_available = false;
+      },
+    },
+  ];
+
+  for (const tc of cases) {
+    test(tc.name + ' — emits and round-trips', () => {
+      const f = makeFinding();
+      tc.mutate(f);
+      // Build a canonical findings[] entry matching what the writer produces.
+      const canonical = {
+        id: f.id,
+        test_source: 'package-scan',
+        gap_type: 'dependency-security',
+        severity: f.severity == null ? 'medium' : String(f.severity).toLowerCase(),
+        resource_id: f.installed_version ? `${f.package_name}@${f.installed_version}` : f.package_name,
+        repo: f.repo,
+        manifest_path: f.manifest_path,
+        title: f.vulnerability.title,
+        description: f.vulnerability.description,
+        remediation: f.remediation,
+        reference: f.vulnerability.reference_url,
+        cve: f.vulnerability.cve,
+        cvss: f.cvss_score,
+        dependency_chain: f.dependency_chain,
+        chain_available: f.chain_available,
+        direct_or_transitive: f.direct_or_transitive,
+        tool: f.tool,
+      };
+      const payload = makeFrontmatterPayload({ findings: [canonical] });
+      const emitted = _emitYamlFrontmatter(payload);
+      assert.ok(typeof emitted === 'string' && emitted.length > 0);
+      const parsed = _parseEmittedYaml(emitted);
+      assert.deepEqual(parsed, payload);
+    });
+  }
+});
+
+// ─── _emitYamlFrontmatter — null and number handling ──────────────────────────
+
+describe('_emitYamlFrontmatter — null and number handling', () => {
+  test('null emits as literal `null`', () => {
+    const f = makeFinding({ severity: null, cvss_score: null });
+    const canonical = {
+      id: 'pkg-001', test_source: 'package-scan', gap_type: 'dependency-security',
+      severity: 'medium', resource_id: 'lodash@4.17.20', repo: 'api',
+      manifest_path: null, title: 'Title', description: null,
+      remediation: null, reference: null, cve: null, cvss: null,
+      dependency_chain: null, chain_available: false, direct_or_transitive: null,
+      tool: 'snyk',
+    };
+    const payload = makeFrontmatterPayload({ findings: [canonical] });
+    const emitted = _emitYamlFrontmatter(payload);
+    assert.match(emitted, /manifest_path: null/);
+    assert.match(emitted, /cvss: null/);
+    // And not the string form.
+    assert.doesNotMatch(emitted, /manifest_path: "null"/);
+  });
+
+  test('integers emit unquoted', () => {
+    const payload = makeFrontmatterPayload({ repos_scanned: 42, critical: 2, high: 0 });
+    const emitted = _emitYamlFrontmatter(payload);
+    assert.match(emitted, /repos_scanned: 42/);
+    assert.match(emitted, /critical: 2/);
+    assert.match(emitted, /high: 0/);
+  });
+
+  test('floats emit unquoted (e.g., cvss: 7.4)', () => {
+    const canonical = {
+      id: 'pkg-001', test_source: 'package-scan', gap_type: 'dependency-security',
+      severity: 'critical', resource_id: 'lodash@4.17.20', repo: 'api',
+      manifest_path: null, title: 'Title', description: null,
+      remediation: null, reference: null, cve: null, cvss: 7.4,
+      dependency_chain: null, chain_available: false, direct_or_transitive: null,
+      tool: 'snyk',
+    };
+    const payload = makeFrontmatterPayload({ findings: [canonical] });
+    const emitted = _emitYamlFrontmatter(payload);
+    assert.match(emitted, /cvss: 7\.4/);
+    assert.doesNotMatch(emitted, /cvss: "7\.4"/);
+  });
+
+  test('booleans emit as literal true/false', () => {
+    const canonical = {
+      id: 'pkg-001', test_source: 'package-scan', gap_type: 'dependency-security',
+      severity: 'critical', resource_id: 'lodash@4.17.20', repo: 'api',
+      manifest_path: null, title: 'T', description: null,
+      remediation: null, reference: null, cve: null, cvss: null,
+      dependency_chain: null, chain_available: true, direct_or_transitive: null,
+      tool: 'snyk',
+    };
+    const payload = makeFrontmatterPayload({ findings: [canonical] });
+    const emitted = _emitYamlFrontmatter(payload);
+    assert.match(emitted, /chain_available: true/);
+  });
+});
+
+// ─── _emitYamlFrontmatter — refuses disallowed input ──────────────────────────
+
+describe('_emitYamlFrontmatter — refuses disallowed input', () => {
+  test('function value in payload throws', () => {
+    const payload = makeFrontmatterPayload();
+    payload.tool = () => {};
+    assert.throws(() => _emitYamlFrontmatter(payload));
+  });
+
+  test('circular reference throws', () => {
+    const payload = makeFrontmatterPayload();
+    const finding = payload.findings[0];
+    finding.self = finding; // circular
+    assert.throws(() => _emitYamlFrontmatter(payload));
+  });
+
+  test('unsupported nested non-finding object throws', () => {
+    const payload = makeFrontmatterPayload();
+    payload.tool = { nested: { object: 'here' } };
+    assert.throws(() => _emitYamlFrontmatter(payload));
+  });
+});
+
+// ─── _renderBody — summary table ──────────────────────────────────────────────
+
+describe('_renderBody — summary table', () => {
+  test('single repo with one ecosystem renders one data row', () => {
+    const rr = [
+      { repo: 'api', ecosystem: 'node', tool_used: 'snyk', outcome: 'ok', findings: [], durationMs: 1000 },
+    ];
+    const result = makeRunResult({ repo_results: rr, findings: [] });
+    const body = _renderBody(result);
+    assert.match(body, /\| Repo \| Ecosystem \| Tool \| \.snyk policy \| Critical \| High \| Medium \| Low \| Status \|/);
+    assert.match(body, /\| api \| node \| snyk \|/);
+  });
+
+  test('outcome=no_manifests → status "skipped (no manifests)" and em-dash cells', () => {
+    const rr = [{ repo: 'api', ecosystem: null, tool_used: null, outcome: 'no_manifests', findings: [], durationMs: 0 }];
+    const result = makeRunResult({ repo_results: rr, findings: [] });
+    const body = _renderBody(result);
+    assert.match(body, /skipped \(no manifests\)/);
+    assert.match(body, /—/);
+  });
+
+  test('outcome=tool_failure → status "tool failure"', () => {
+    const rr = [{ repo: 'api', ecosystem: 'node', tool_used: 'snyk', outcome: 'tool_failure', findings: [], durationMs: 500 }];
+    const result = makeRunResult({ repo_results: rr, findings: [] });
+    const body = _renderBody(result);
+    assert.match(body, /tool failure/);
+  });
+
+  test('two repos across three ecosystems render three data rows', () => {
+    const rr = [
+      { repo: 'api', ecosystem: 'node', tool_used: 'snyk', outcome: 'ok', findings: [], durationMs: 10 },
+      { repo: 'api', ecosystem: 'python', tool_used: 'snyk', outcome: 'ok', findings: [], durationMs: 10 },
+      { repo: 'web', ecosystem: 'node', tool_used: 'osv-scanner', outcome: 'ok', findings: [], durationMs: 10 },
+    ];
+    const result = makeRunResult({ repo_results: rr, findings: [] });
+    const body = _renderBody(result);
+    // Find the summary table
+    const tableMatch = body.match(/## Summary[\s\S]*?(?=\n##|$)/);
+    assert.ok(tableMatch);
+    const dataRows = tableMatch[0].split('\n').filter(l => /^\| (api|web) \|/.test(l));
+    assert.equal(dataRows.length, 3);
+  });
+});
+
+// ─── _renderBody — per-severity sections ──────────────────────────────────────
+
+describe('_renderBody — per-severity sections', () => {
+  test('findings across all severities → sections in Critical → High → Medium → Low order', () => {
+    const findings = [
+      makeFinding({ id: 'pkg-001', severity: 'critical' }),
+      makeFinding({ id: 'pkg-002', severity: 'high' }),
+      makeFinding({ id: 'pkg-003', severity: 'medium' }),
+      makeFinding({ id: 'pkg-004', severity: 'low' }),
+    ];
+    const rr = [{ repo: 'api', ecosystem: 'node', tool_used: 'snyk', outcome: 'ok', findings, durationMs: 1 }];
+    const result = makeRunResult({ repo_results: rr, findings });
+    const body = _renderBody(result);
+    const idxCritical = body.indexOf('## Critical');
+    const idxHigh = body.indexOf('## High');
+    const idxMedium = body.indexOf('## Medium');
+    const idxLow = body.indexOf('## Low');
+    assert.ok(idxCritical > 0);
+    assert.ok(idxHigh > idxCritical);
+    assert.ok(idxMedium > idxHigh);
+    assert.ok(idxLow > idxMedium);
+  });
+
+  test('empty tier (zero medium findings) → no ## Medium heading', () => {
+    const findings = [
+      makeFinding({ id: 'pkg-001', severity: 'critical' }),
+    ];
+    const rr = [{ repo: 'api', ecosystem: 'node', tool_used: 'snyk', outcome: 'ok', findings, durationMs: 1 }];
+    const result = makeRunResult({ repo_results: rr, findings });
+    const body = _renderBody(result);
+    assert.doesNotMatch(body, /## Medium/);
+    assert.doesNotMatch(body, /## High/);
+    assert.doesNotMatch(body, /## Low/);
+  });
+
+  test('finding block contains CVE / CVSS / Tool / Manifest / Direct/Transitive / Dependency chain / Fix / Reference', () => {
+    const findings = [makeFinding({ id: 'pkg-001', severity: 'critical' })];
+    const rr = [{ repo: 'api', ecosystem: 'node', tool_used: 'snyk', outcome: 'ok', findings, durationMs: 1 }];
+    const result = makeRunResult({ repo_results: rr, findings });
+    const body = _renderBody(result);
+    assert.match(body, /\*\*CVE:\*\*/);
+    assert.match(body, /\*\*CVSS:\*\*/);
+    assert.match(body, /\*\*Tool:\*\*/);
+    assert.match(body, /\*\*Manifest:\*\*/);
+    assert.match(body, /\*\*Direct\/Transitive:\*\*/);
+    assert.match(body, /\*\*Dependency chain:\*\*/);
+    assert.match(body, /\*\*Fix:\*\*/);
+    assert.match(body, /\*\*Reference:\*\*/);
+  });
+
+  test('chain_available false → `unavailable (chain_available: false — recommend Snyk for full chain analysis)`', () => {
+    const findings = [makeFinding({ id: 'pkg-001', severity: 'critical', chain_available: false, dependency_chain: null })];
+    const rr = [{ repo: 'api', ecosystem: 'node', tool_used: 'osv-scanner', outcome: 'ok', findings, durationMs: 1 }];
+    const result = makeRunResult({ repo_results: rr, findings });
+    const body = _renderBody(result);
+    assert.match(body, /unavailable \(chain_available: false — recommend Snyk for full chain analysis\)/);
+  });
+
+  test('description non-null → rendered as blockquote', () => {
+    const findings = [makeFinding({
+      id: 'pkg-001',
+      severity: 'critical',
+      vulnerability: {
+        cve: 'CVE-2020-8203',
+        title: 'Prototype Pollution in lodash',
+        description: 'Multi-line description\nwith details',
+        reference_url: 'https://example.com',
+      },
+    })];
+    const rr = [{ repo: 'api', ecosystem: 'node', tool_used: 'snyk', outcome: 'ok', findings, durationMs: 1 }];
+    const result = makeRunResult({ repo_results: rr, findings });
+    const body = _renderBody(result);
+    assert.match(body, /^> Multi-line description/m);
+    assert.match(body, /^> with details/m);
+  });
+});
+
+// ─── _renderBody — special-case sections ──────────────────────────────────────
+
+describe('_renderBody — special-case sections', () => {
+  test('zero findings + non-empty repo_results → ## Findings clean-scan message', () => {
+    const rr = [
+      { repo: 'api', ecosystem: 'node', tool_used: 'snyk', outcome: 'ok', findings: [], durationMs: 1 },
+      { repo: 'web', ecosystem: 'node', tool_used: 'snyk', outcome: 'ok', findings: [], durationMs: 1 },
+    ];
+    const result = makeRunResult({ repo_results: rr, findings: [] });
+    const body = _renderBody(result);
+    assert.match(body, /## Findings/);
+    assert.match(body, /No vulnerabilities found across 2 scanned repos\./);
+  });
+
+  test('empty repo_results + non-empty diagnostics → ## No targets scanned', () => {
+    const result = makeRunResult({
+      repo_results: [],
+      findings: [],
+      diagnostics: [{ kind: 'tool_unavailable_on_pin', tool: 'snyk', hint: 'Install Snyk CLI' }],
+    });
+    const body = _renderBody(result);
+    assert.match(body, /## No targets scanned/);
+    assert.match(body, /tool_unavailable_on_pin/);
+  });
+
+  test('non-empty diagnostics alongside findings → ## Diagnostics section appended', () => {
+    const findings = [makeFinding({ id: 'pkg-001', severity: 'critical' })];
+    const rr = [{ repo: 'api', ecosystem: 'node', tool_used: 'snyk', outcome: 'ok', findings, durationMs: 1 }];
+    const result = makeRunResult({
+      repo_results: rr,
+      findings,
+      diagnostics: [{ kind: 'lockfile_stale', message: 'Lockfile older than manifest' }],
+    });
+    const body = _renderBody(result);
+    assert.match(body, /## Diagnostics/);
+    const idxDiag = body.indexOf('## Diagnostics');
+    const idxCritical = body.indexOf('## Critical');
+    assert.ok(idxDiag > idxCritical, 'Diagnostics section should come after severity sections');
+  });
+});
+
+// ─── _resolveReportPath — tier 1 (active phase) ───────────────────────────────
+
+describe('_resolveReportPath — tier 1 (active phase)', () => {
+  let tmpDir;
+  test('active_context resolves to existing phase dir → returns phase path', () => {
+    tmpDir = setupPlanningRoot({
+      local: {
+        current_project: 'gsd',
+        execution: { active_context: '151-report-generation-and-command-surface' },
+      },
+    });
+    const phaseDir = path.join(tmpDir, 'projects', 'gsd', 'phases', '151-report-generation-and-command-surface');
+    fs.mkdirSync(phaseDir, { recursive: true });
+    try {
+      const resolved = _resolveReportPath(tmpDir, {});
+      assert.equal(resolved, path.join(phaseDir, '151-PACKAGE-SCAN.md'));
+    } finally {
+      cleanup(tmpDir);
+    }
+  });
+
+  test('active_context points at a phase that does NOT exist → falls through', () => {
+    tmpDir = setupPlanningRoot({
+      local: {
+        current_project: 'gsd',
+        execution: { active_context: '999-phantom-phase' },
+      },
+    });
+    try {
+      const resolved = _resolveReportPath(tmpDir, {});
+      // Should fall through to tier 2 or 3. In this case no projects/ exists,
+      // so tier 2 also can't resolve; tier 3 (project root with timestamp).
+      assert.ok(resolved.includes('PACKAGE-SCAN-'));
+    } finally {
+      cleanup(tmpDir);
+    }
+  });
+});
+
+// ─── _resolveReportPath — tier 2 (active milestone) ───────────────────────────
+
+describe('_resolveReportPath — tier 2 (active milestone)', () => {
+  let tmpDir;
+  test('active_context is milestone slug → returns milestones/{slug}-PACKAGE-SCAN.md', () => {
+    tmpDir = setupPlanningRoot({
+      local: { execution: { active_context: 'v23.1' } },
+    });
+    try {
+      const resolved = _resolveReportPath(tmpDir, {});
+      assert.equal(resolved, path.join(tmpDir, 'milestones', 'v23.1-PACKAGE-SCAN.md'));
+      assert.ok(fs.existsSync(path.join(tmpDir, 'milestones')));
+    } finally {
+      cleanup(tmpDir);
+    }
+  });
+});
+
+// ─── _resolveReportPath — tier 2b (milestone worktree slug) ───────────────────
+
+describe('_resolveReportPath — tier 2b (milestone worktree slug)', () => {
+  let tmpDir;
+  test('active_context is milestone worktree slug with milestone_version → returns milestones/{version}-PACKAGE-SCAN.md', () => {
+    tmpDir = setupPlanningRoot({
+      local: {
+        current_project: 'gsd',
+        execution: { active_context: 'my-milestone-slug' },
+        projects: {
+          gsd: {
+            worktrees: {
+              'my-milestone-slug': {
+                type: 'milestone',
+                mode: null,
+                setup_complete: true,
+                milestone_version: 'v23.1',
+                repos: { 'deliver-great-systems': '/tmp/fake/path' },
+              },
+            },
+          },
+        },
+      },
+    });
+    try {
+      const resolved = _resolveReportPath(tmpDir, {});
+      assert.equal(resolved, path.join(tmpDir, 'milestones', 'v23.1-PACKAGE-SCAN.md'));
+      assert.ok(fs.existsSync(path.join(tmpDir, 'milestones')), 'milestones/ directory should be created');
+    } finally {
+      cleanup(tmpDir);
+    }
+  });
+
+  test('worktree entry has milestone_version: null → falls through to tier 3', () => {
+    tmpDir = setupPlanningRoot({
+      local: {
+        current_project: 'gsd',
+        execution: { active_context: 'my-milestone-slug' },
+        projects: {
+          gsd: {
+            worktrees: {
+              'my-milestone-slug': {
+                type: 'milestone',
+                mode: null,
+                setup_complete: true,
+                milestone_version: null,
+                repos: { 'deliver-great-systems': '/tmp/fake/path' },
+              },
+            },
+          },
+        },
+      },
+    });
+    try {
+      const resolved = _resolveReportPath(tmpDir, {
+        now: () => new Date('2026-04-20T10:15:00Z'),
+      });
+      assert.equal(resolved, path.join(tmpDir, 'PACKAGE-SCAN-2026-04-20-1015.md'));
+    } finally {
+      cleanup(tmpDir);
+    }
+  });
+
+  test('worktree entry missing milestone_version field → falls through to tier 3', () => {
+    tmpDir = setupPlanningRoot({
+      local: {
+        current_project: 'gsd',
+        execution: { active_context: 'my-milestone-slug' },
+        projects: {
+          gsd: {
+            worktrees: {
+              'my-milestone-slug': {
+                type: 'milestone',
+                mode: null,
+                setup_complete: true,
+                repos: { 'deliver-great-systems': '/tmp/fake/path' },
+              },
+            },
+          },
+        },
+      },
+    });
+    try {
+      const resolved = _resolveReportPath(tmpDir, {
+        now: () => new Date('2026-04-20T10:15:00Z'),
+      });
+      assert.equal(resolved, path.join(tmpDir, 'PACKAGE-SCAN-2026-04-20-1015.md'));
+    } finally {
+      cleanup(tmpDir);
+    }
+  });
+
+  test('worktree entry is quick-type (not milestone) → falls through to tier 3', () => {
+    tmpDir = setupPlanningRoot({
+      local: {
+        current_project: 'gsd',
+        execution: { active_context: 'my-milestone-slug' },
+        projects: {
+          gsd: {
+            worktrees: {
+              'my-milestone-slug': {
+                type: 'quick',
+                mode: null,
+                setup_complete: true,
+                milestone_version: 'v23.1',
+                repos: { 'deliver-great-systems': '/tmp/fake/path' },
+              },
+            },
+          },
+        },
+      },
+    });
+    try {
+      const resolved = _resolveReportPath(tmpDir, {
+        now: () => new Date('2026-04-20T10:15:00Z'),
+      });
+      assert.equal(resolved, path.join(tmpDir, 'PACKAGE-SCAN-2026-04-20-1015.md'));
+    } finally {
+      cleanup(tmpDir);
+    }
+  });
+
+  test('milestone_version does not match /^v\\d+(\\.\\d+)?$/ → falls through to tier 3', () => {
+    tmpDir = setupPlanningRoot({
+      local: {
+        current_project: 'gsd',
+        execution: { active_context: 'my-milestone-slug' },
+        projects: {
+          gsd: {
+            worktrees: {
+              'my-milestone-slug': {
+                type: 'milestone',
+                mode: null,
+                setup_complete: true,
+                milestone_version: 'not-a-version',
+                repos: { 'deliver-great-systems': '/tmp/fake/path' },
+              },
+            },
+          },
+        },
+      },
+    });
+    try {
+      const resolved = _resolveReportPath(tmpDir, {
+        now: () => new Date('2026-04-20T10:15:00Z'),
+      });
+      assert.equal(resolved, path.join(tmpDir, 'PACKAGE-SCAN-2026-04-20-1015.md'));
+    } finally {
+      cleanup(tmpDir);
+    }
+  });
+});
+
+// ─── _resolveReportPath — tier 3 (project root, no active context) ────────────
+
+describe('_resolveReportPath — tier 3 (project root, no active context)', () => {
+  let tmpDir;
+  test('no active_context → returns project-root/PACKAGE-SCAN-{YYYY-MM-DD-HHmm}.md', () => {
+    tmpDir = setupPlanningRoot({});
+    try {
+      const resolved = _resolveReportPath(tmpDir, {
+        now: () => new Date('2026-04-17T14:30:00Z'),
+      });
+      // Timestamp formatting uses UTC components of the provided Date; HHmm = 1430.
+      assert.ok(resolved.includes('2026-04-17-1430'));
+      assert.ok(resolved.startsWith(tmpDir));
+    } finally {
+      cleanup(tmpDir);
+    }
+  });
+});
+
+// ─── writePackageScanReport — end-to-end ──────────────────────────────────────
+
+describe('writePackageScanReport — end-to-end', () => {
+  let tmpDir;
+  test('writes file, returns {path, tool_string, n_findings}, frontmatter round-trips', () => {
+    tmpDir = setupPlanningRoot({});
+    try {
+      const findings = [
+        makeFinding({ id: 'pkg-001', severity: 'critical', repo: 'api' }),
+        makeFinding({ id: 'pkg-002', severity: 'high', repo: 'api' }),
+        makeFinding({ id: 'pkg-003', severity: 'medium', repo: 'web' }),
+      ];
+      const rr = [
+        { repo: 'api', ecosystem: 'node', tool_used: 'snyk', outcome: 'ok', findings: findings.slice(0, 2), durationMs: 2000 },
+        { repo: 'web', ecosystem: 'node', tool_used: 'snyk', outcome: 'ok', findings: findings.slice(2), durationMs: 1500 },
+      ];
+      const runResult = makeRunResult({
+        repo_results: rr,
+        findings,
+        tool_per_target: { api: 'snyk', web: 'snyk' },
+      });
+      const info = writePackageScanReport(tmpDir, runResult, {
+        now: () => new Date('2026-04-17T14:30:00Z'),
+      });
+      assert.equal(info.tool_string, 'snyk');
+      assert.equal(info.n_findings, 3);
+      assert.ok(info.path && typeof info.path === 'string');
+      assert.ok(fs.existsSync(info.path));
+      const content = fs.readFileSync(info.path, 'utf-8');
+      assert.ok(content.startsWith('---\ntype: "package-scan"\n'), 'content starts with ---\\ntype: "package-scan"');
+      // Extract the frontmatter section up to and including the closing ---
+      const closeIdx = content.indexOf('\n---\n', 4);
+      assert.ok(closeIdx > 0);
+      const frontSection = content.slice(0, closeIdx + 5);
+      const parsed = _parseEmittedYaml(frontSection);
+      assert.equal(parsed.type, 'package-scan');
+      assert.equal(parsed.critical, 1);
+      assert.equal(parsed.high, 1);
+      assert.equal(parsed.medium, 1);
+      assert.equal(parsed.low, 0);
+      assert.equal(parsed.findings.length, 3);
+      assert.equal(parsed.findings[0].id, 'pkg-001');
+    } finally {
+      cleanup(tmpDir);
+    }
+  });
+});
+
+// ─── frontmatter — snyk_org (UAT Bug 2) ──────────────────────────────────────
+
+describe('frontmatter — snyk_org field (UAT Bug 2)', () => {
+  let tmpDir;
+
+  test('snyk_org emitted in frontmatter when set', () => {
+    tmpDir = setupPlanningRoot({});
+    try {
+      const findings = [makeFinding({ id: 'pkg-001', severity: 'high' })];
+      const rr = [{ repo: 'api', ecosystem: 'node', tool_used: 'snyk', outcome: 'ok', findings, durationMs: 100 }];
+      const result = makeRunResult({ repo_results: rr, findings });
+      result.snyk_org = 'ORG-FRONT-UUID';
+      const info = writePackageScanReport(tmpDir, result, { overridePath: path.join(tmpDir, 'rpt.md') });
+      const content = fs.readFileSync(info.path, 'utf-8');
+      assert.match(content, /snyk_org: "ORG-FRONT-UUID"/);
+      // Position check: snyk_org between tool and repos_scanned
+      const toolIdx = content.indexOf('tool:');
+      const orgIdx = content.indexOf('snyk_org:');
+      const reposIdx = content.indexOf('repos_scanned:');
+      assert.ok(toolIdx < orgIdx && orgIdx < reposIdx,
+        `Expected tool < snyk_org < repos_scanned; got ${toolIdx}, ${orgIdx}, ${reposIdx}`);
+    } finally {
+      cleanup(tmpDir);
+    }
+  });
+
+  test('snyk_org emitted as null when unset', () => {
+    tmpDir = setupPlanningRoot({});
+    try {
+      const findings = [makeFinding({ id: 'pkg-001', severity: 'high' })];
+      const rr = [{ repo: 'api', ecosystem: 'node', tool_used: 'snyk', outcome: 'ok', findings, durationMs: 100 }];
+      const result = makeRunResult({ repo_results: rr, findings });
+      // result.snyk_org intentionally undefined.
+      const info = writePackageScanReport(tmpDir, result, { overridePath: path.join(tmpDir, 'rpt.md') });
+      const content = fs.readFileSync(info.path, 'utf-8');
+      assert.match(content, /snyk_org: null/);
+    } finally {
+      cleanup(tmpDir);
+    }
+  });
+
+  test('snyk_org round-trips through _parseEmittedYaml', () => {
+    tmpDir = setupPlanningRoot({});
+    try {
+      const findings = [makeFinding({ id: 'pkg-001', severity: 'high' })];
+      const rr = [{ repo: 'api', ecosystem: 'node', tool_used: 'snyk', outcome: 'ok', findings, durationMs: 100 }];
+      const result = makeRunResult({ repo_results: rr, findings });
+      result.snyk_org = '5cb2d43f-6064-4fe2-80f8-4a14cef84a5a';
+      const info = writePackageScanReport(tmpDir, result, { overridePath: path.join(tmpDir, 'rpt.md') });
+      const content = fs.readFileSync(info.path, 'utf-8');
+      const closeIdx = content.indexOf('\n---\n', 4);
+      const frontSection = content.slice(0, closeIdx + 5);
+      const parsed = _parseEmittedYaml(frontSection);
+      assert.equal(parsed.snyk_org, '5cb2d43f-6064-4fe2-80f8-4a14cef84a5a');
+    } finally {
+      cleanup(tmpDir);
+    }
+  });
+});
+
+// ─── writePackageScanReport — round-trip failure mode ─────────────────────────
+
+describe('writePackageScanReport — round-trip failure mode', () => {
+  let tmpDir;
+  test('broken runResult (finding.title is a function) throws + no file written', () => {
+    tmpDir = setupPlanningRoot({});
+    try {
+      const bad = makeFinding({ id: 'pkg-001', severity: 'critical' });
+      bad.vulnerability = { cve: null, title: () => {}, description: null, reference_url: null };
+      const runResult = makeRunResult({
+        repo_results: [{ repo: 'api', ecosystem: 'node', tool_used: 'snyk', outcome: 'ok', findings: [bad], durationMs: 1 }],
+        findings: [bad],
+      });
+      let threw = false;
+      let errMsg = '';
+      try {
+        writePackageScanReport(tmpDir, runResult, {});
+      } catch (err) {
+        threw = true;
+        errMsg = err && err.message ? err.message : '';
+      }
+      assert.ok(threw, 'expected a throw');
+      assert.match(errMsg, /YAML emitter/);
+      // No file should have been written in tmpDir or its milestones/.
+      const entries = fs.readdirSync(tmpDir);
+      const wrote = entries.some(e => /PACKAGE-SCAN/.test(e));
+      assert.equal(wrote, false);
+    } finally {
+      cleanup(tmpDir);
+    }
+  });
+});
+
+// ─── writePackageScanReport — input immutability ──────────────────────────────
+
+describe('writePackageScanReport — input immutability', () => {
+  let tmpDir;
+  test('after a successful call, input runResult is unchanged (by reference + deep-equal)', () => {
+    tmpDir = setupPlanningRoot({});
+    try {
+      const findings = [makeFinding({ id: 'pkg-001', severity: 'critical' })];
+      const runResult = makeRunResult({
+        repo_results: [{ repo: 'api', ecosystem: 'node', tool_used: 'snyk', outcome: 'ok', findings, durationMs: 1 }],
+        findings,
+      });
+      const snapshot = JSON.parse(JSON.stringify(runResult));
+      const info = writePackageScanReport(tmpDir, runResult, {});
+      assert.ok(info.path);
+      assert.deepEqual(runResult, snapshot);
+    } finally {
+      cleanup(tmpDir);
+    }
+  });
+});
+
+// ─── frontmatter — tool field aggregation ─────────────────────────────────────
+
+describe('frontmatter — tool field aggregation', () => {
+  let tmpDir;
+  test('all snyk → tool: snyk', () => {
+    tmpDir = setupPlanningRoot({});
+    try {
+      const rr = [
+        { repo: 'a', ecosystem: 'node', tool_used: 'snyk', outcome: 'ok', findings: [], durationMs: 1 },
+        { repo: 'b', ecosystem: 'node', tool_used: 'snyk', outcome: 'ok', findings: [], durationMs: 1 },
+      ];
+      const info = writePackageScanReport(tmpDir, makeRunResult({ repo_results: rr, findings: [] }), {});
+      assert.equal(info.tool_string, 'snyk');
+    } finally {
+      cleanup(tmpDir);
+    }
+  });
+
+  test('mixed (snyk + npm-audit) → tool: mixed', () => {
+    tmpDir = setupPlanningRoot({});
+    try {
+      const rr = [
+        { repo: 'a', ecosystem: 'node', tool_used: 'snyk', outcome: 'ok', findings: [], durationMs: 1 },
+        { repo: 'b', ecosystem: 'node', tool_used: 'npm-audit', outcome: 'ok', findings: [], durationMs: 1 },
+      ];
+      const info = writePackageScanReport(tmpDir, makeRunResult({ repo_results: rr, findings: [] }), {});
+      assert.equal(info.tool_string, 'mixed');
+    } finally {
+      cleanup(tmpDir);
+    }
+  });
+
+  test('all null → tool: none', () => {
+    tmpDir = setupPlanningRoot({});
+    try {
+      const rr = [
+        { repo: 'a', ecosystem: null, tool_used: null, outcome: 'no_manifests', findings: [], durationMs: 0 },
+      ];
+      const info = writePackageScanReport(tmpDir, makeRunResult({ repo_results: rr, findings: [] }), {});
+      assert.equal(info.tool_string, 'none');
+    } finally {
+      cleanup(tmpDir);
+    }
+  });
+});
+
+// ─── frontmatter — severity counts ────────────────────────────────────────────
+
+describe('frontmatter — severity counts', () => {
+  let tmpDir;
+  test('null severity counts as medium (conservative bias)', () => {
+    tmpDir = setupPlanningRoot({});
+    try {
+      const findings = [makeFinding({ id: 'pkg-001', severity: null })];
+      const rr = [{ repo: 'a', ecosystem: 'node', tool_used: 'snyk', outcome: 'ok', findings, durationMs: 1 }];
+      const info = writePackageScanReport(tmpDir, makeRunResult({ repo_results: rr, findings }), {});
+      const content = fs.readFileSync(info.path, 'utf-8');
+      const closeIdx = content.indexOf('\n---\n', 4);
+      const parsed = _parseEmittedYaml(content.slice(0, closeIdx + 5));
+      assert.equal(parsed.medium, 1);
+      assert.equal(parsed.critical, 0);
+    } finally {
+      cleanup(tmpDir);
+    }
+  });
+
+  test('unknown severity counts as medium (conservative fallback)', () => {
+    tmpDir = setupPlanningRoot({});
+    try {
+      // Phase 152 (PKG-23) gives 'info' a first-class mapping → low. Use a
+      // truly unknown token to exercise the fallback-to-medium path.
+      const findings = [makeFinding({ id: 'pkg-001', severity: 'unknown-cvss-tier' })];
+      const rr = [{ repo: 'a', ecosystem: 'node', tool_used: 'snyk', outcome: 'ok', findings, durationMs: 1 }];
+      const info = writePackageScanReport(tmpDir, makeRunResult({ repo_results: rr, findings }), {});
+      const content = fs.readFileSync(info.path, 'utf-8');
+      const closeIdx = content.indexOf('\n---\n', 4);
+      const parsed = _parseEmittedYaml(content.slice(0, closeIdx + 5));
+      assert.equal(parsed.medium, 1);
+    } finally {
+      cleanup(tmpDir);
+    }
+  });
+
+  test('npm-audit info severity counts as low (PKG-23 mapping)', () => {
+    tmpDir = setupPlanningRoot({});
+    try {
+      const findings = [makeFinding({ id: 'pkg-001', severity: 'info', tool: 'npm-audit' })];
+      const rr = [{ repo: 'a', ecosystem: 'node', tool_used: 'npm-audit', outcome: 'ok', findings, durationMs: 1 }];
+      const info = writePackageScanReport(tmpDir, makeRunResult({ repo_results: rr, findings }), {});
+      const content = fs.readFileSync(info.path, 'utf-8');
+      const closeIdx = content.indexOf('\n---\n', 4);
+      const parsed = _parseEmittedYaml(content.slice(0, closeIdx + 5));
+      assert.equal(parsed.low, 1);
+      assert.equal(parsed.medium, 0);
+    } finally {
+      cleanup(tmpDir);
+    }
+  });
+
+  test('lowercased comparison (CRITICAL counted as critical)', () => {
+    tmpDir = setupPlanningRoot({});
+    try {
+      const findings = [makeFinding({ id: 'pkg-001', severity: 'CRITICAL' })];
+      const rr = [{ repo: 'a', ecosystem: 'node', tool_used: 'snyk', outcome: 'ok', findings, durationMs: 1 }];
+      const info = writePackageScanReport(tmpDir, makeRunResult({ repo_results: rr, findings }), {});
+      const content = fs.readFileSync(info.path, 'utf-8');
+      const closeIdx = content.indexOf('\n---\n', 4);
+      const parsed = _parseEmittedYaml(content.slice(0, closeIdx + 5));
+      assert.equal(parsed.critical, 1);
+    } finally {
+      cleanup(tmpDir);
+    }
+  });
+
+  test('zero counts emitted as 0 (present unconditionally)', () => {
+    tmpDir = setupPlanningRoot({});
+    try {
+      const rr = [{ repo: 'a', ecosystem: 'node', tool_used: 'snyk', outcome: 'ok', findings: [], durationMs: 1 }];
+      const info = writePackageScanReport(tmpDir, makeRunResult({ repo_results: rr, findings: [] }), {});
+      const content = fs.readFileSync(info.path, 'utf-8');
+      assert.match(content, /critical: 0/);
+      assert.match(content, /high: 0/);
+      assert.match(content, /medium: 0/);
+      assert.match(content, /low: 0/);
+    } finally {
+      cleanup(tmpDir);
+    }
+  });
+});
+
+// ─── frontmatter — repos_scanned count ────────────────────────────────────────
+
+describe('frontmatter — repos_scanned count', () => {
+  let tmpDir;
+  test('excludes outcome=no_manifests', () => {
+    tmpDir = setupPlanningRoot({});
+    try {
+      const rr = [
+        { repo: 'a', ecosystem: 'node', tool_used: 'snyk', outcome: 'ok', findings: [], durationMs: 1 },
+        { repo: 'b', ecosystem: null, tool_used: null, outcome: 'no_manifests', findings: [], durationMs: 0 },
+      ];
+      const info = writePackageScanReport(tmpDir, makeRunResult({ repo_results: rr, findings: [] }), {});
+      const content = fs.readFileSync(info.path, 'utf-8');
+      assert.match(content, /repos_scanned: 1/);
+    } finally {
+      cleanup(tmpDir);
+    }
+  });
+
+  test('includes outcome=tool_failure (attempt counted)', () => {
+    tmpDir = setupPlanningRoot({});
+    try {
+      const rr = [
+        { repo: 'a', ecosystem: 'node', tool_used: 'snyk', outcome: 'ok', findings: [], durationMs: 1 },
+        { repo: 'b', ecosystem: 'node', tool_used: 'snyk', outcome: 'tool_failure', findings: [], durationMs: 500 },
+      ];
+      const info = writePackageScanReport(tmpDir, makeRunResult({ repo_results: rr, findings: [] }), {});
+      const content = fs.readFileSync(info.path, 'utf-8');
+      assert.match(content, /repos_scanned: 2/);
+    } finally {
+      cleanup(tmpDir);
+    }
+  });
+});
+
+// ─── Phase 151 Plan 03 — command surface artifacts ───────────────────────────
+
+describe('Phase 151 Plan 03 — command surface artifacts', () => {
+  // Repo root: from bin/lib/ go up three levels to the deliver-great-systems
+  // repo root (where commands/ and deliver-great-systems/ both live).
+  const repoRoot = path.resolve(__dirname, '..', '..', '..');
+
+  test('commands/dgs/package-scan.md exists with name + workflow reference', () => {
+    const filePath = path.join(repoRoot, 'commands', 'dgs', 'package-scan.md');
+    assert.ok(fs.existsSync(filePath), 'commands/dgs/package-scan.md must exist');
+    const content = fs.readFileSync(filePath, 'utf-8');
+    assert.match(content, /name: dgs:package-scan/);
+    assert.match(content, /@~\/\.claude\/deliver-great-systems\/workflows\/package-scan\.md/);
+    assert.match(content, /<objective>/);
+    assert.match(content, /<process>/);
+  });
+
+  test('deliver-great-systems/workflows/package-scan.md exists with context_tier=none and run-scan step', () => {
+    const filePath = path.join(repoRoot, 'deliver-great-systems', 'workflows', 'package-scan.md');
+    assert.ok(fs.existsSync(filePath), 'workflows/package-scan.md must exist');
+    const content = fs.readFileSync(filePath, 'utf-8');
+    assert.match(content, /<context_tier>none<\/context_tier>/);
+    assert.match(content, /<step name="run-scan"/);
+    assert.match(content, /dgs-tools\.cjs package-scan/);
+    assert.match(content, /<success_criteria>/);
+  });
+
+  test('deliver-great-systems/references/package-scan-config.md documents all testing.packages.* keys', () => {
+    const filePath = path.join(repoRoot, 'deliver-great-systems', 'references', 'package-scan-config.md');
+    assert.ok(fs.existsSync(filePath), 'references/package-scan-config.md must exist');
+    const content = fs.readFileSync(filePath, 'utf-8');
+    for (const key of [
+      'testing.packages.tool',
+      'testing.packages.severity_threshold',
+      'testing.packages.include_dev_dependencies',
+      'testing.packages.timeout_seconds',
+      'testing.packages.snyk_token',
+    ]) {
+      assert.match(content, new RegExp(key.replace(/\./g, '\\.')), `must mention ${key}`);
+    }
+    assert.match(content, /config-local-set/);
+    assert.match(content, /dgs-tools config-set/);
+    assert.match(content, /## Report placement/);
+  });
+
+  test('deliver-great-systems/templates/package-scan-report.md shows frontmatter + body skeleton', () => {
+    const filePath = path.join(repoRoot, 'deliver-great-systems', 'templates', 'package-scan-report.md');
+    assert.ok(fs.existsSync(filePath), 'templates/package-scan-report.md must exist');
+    const content = fs.readFileSync(filePath, 'utf-8');
+    assert.match(content, /type: package-scan/);
+    assert.match(content, /findings:/);
+    assert.match(content, /test_source/);
+    assert.match(content, /gap_type/);
+    assert.match(content, /manifest_path/);
+    assert.match(content, /## Summary/);
+  });
+});
+
+// ─── Phase 152 Plan 01: severity normalisation (PKG-23) ───────────────────────
+//
+// These tests lock the severity/licence normaliser (replacing the Phase 151
+// stop-gap `_collapseSeverity`), the licence-finding synthesis for Snyk
+// adapter output, and the canonical-field-ordering invariants from the
+// test-gate spec §5a.
+//
+// The tests depend on module exports added in Task 2:
+//   - SEVERITY_MAP
+//   - LICENCE_SEVERITY_MAP
+//   - _mapLicenceToSeverity
+//   - _canonicalFindingsForAdapter
+// ─────────────────────────────────────────────────────────────────────────────
+
+const {
+  SEVERITY_MAP,
+  LICENCE_SEVERITY_MAP,
+  _mapLicenceToSeverity,
+  _canonicalFindingsForAdapter,
+  _mapAdapterFindingToCanonical,
+} = require('./package-scan-report.cjs');
+
+describe('severity normalisation (PKG-23)', () => {
+  describe('SEVERITY_MAP — tool-dialect coverage', () => {
+    test('Snyk + bundler-audit tiers map to canonical', () => {
+      assert.strictEqual(SEVERITY_MAP['critical'], 'critical');
+      assert.strictEqual(SEVERITY_MAP['high'], 'high');
+      assert.strictEqual(SEVERITY_MAP['medium'], 'medium');
+      assert.strictEqual(SEVERITY_MAP['low'], 'low');
+    });
+
+    test('OSV database_specific (uppercase) normalises via lowercased key lookup', () => {
+      // Keys in SEVERITY_MAP are ALL lowercased; _collapseSeverity lowers input.
+      assert.strictEqual(SEVERITY_MAP['critical'], 'critical');
+      assert.strictEqual(SEVERITY_MAP['high'], 'high');
+      assert.strictEqual(SEVERITY_MAP['moderate'], 'medium'); // OSV MODERATE -> medium
+      assert.strictEqual(SEVERITY_MAP['medium'], 'medium');
+      assert.strictEqual(SEVERITY_MAP['low'], 'low');
+    });
+
+    test('npm-audit tiers (critical/high/moderate/low/info)', () => {
+      assert.strictEqual(SEVERITY_MAP['critical'], 'critical');
+      assert.strictEqual(SEVERITY_MAP['high'], 'high');
+      assert.strictEqual(SEVERITY_MAP['moderate'], 'medium');
+      assert.strictEqual(SEVERITY_MAP['low'], 'low');
+      assert.strictEqual(SEVERITY_MAP['info'], 'low');
+    });
+
+    test('SEVERITY_MAP is frozen', () => {
+      assert.ok(Object.isFrozen(SEVERITY_MAP), 'SEVERITY_MAP must be Object.freeze()d');
+    });
+
+    test('_collapseSeverity integrates SEVERITY_MAP — null/unknown map to medium (conservative bias)', () => {
+      const { _collapseSeverity } = require('./package-scan-report.cjs');
+      // pip-audit / govulncheck never emit severity:
+      assert.strictEqual(_collapseSeverity(null), 'medium');
+      assert.strictEqual(_collapseSeverity(undefined), 'medium');
+      // Unknown string:
+      assert.strictEqual(_collapseSeverity('unknown-cvss-tier'), 'medium');
+      // Canonical + dialect values:
+      assert.strictEqual(_collapseSeverity('CRITICAL'), 'critical');
+      assert.strictEqual(_collapseSeverity('HIGH'), 'high');
+      assert.strictEqual(_collapseSeverity('MODERATE'), 'medium');
+      assert.strictEqual(_collapseSeverity('moderate'), 'medium');
+      assert.strictEqual(_collapseSeverity('info'), 'low');
+      assert.strictEqual(_collapseSeverity('LOW'), 'low');
+    });
+  });
+
+  describe('LICENCE_SEVERITY_MAP — SPDX coverage', () => {
+    test('LICENCE_SEVERITY_MAP is frozen', () => {
+      assert.ok(Object.isFrozen(LICENCE_SEVERITY_MAP), 'LICENCE_SEVERITY_MAP must be Object.freeze()d');
+    });
+
+    test('GPL-3.0 family → high', () => {
+      assert.strictEqual(LICENCE_SEVERITY_MAP['gpl-3.0'], 'high');
+      assert.strictEqual(LICENCE_SEVERITY_MAP['gpl-3.0-only'], 'high');
+      assert.strictEqual(LICENCE_SEVERITY_MAP['gpl-3.0-or-later'], 'high');
+    });
+
+    test('AGPL-3.0 family → high', () => {
+      assert.strictEqual(LICENCE_SEVERITY_MAP['agpl-3.0'], 'high');
+      assert.strictEqual(LICENCE_SEVERITY_MAP['agpl-3.0-only'], 'high');
+      assert.strictEqual(LICENCE_SEVERITY_MAP['agpl-3.0-or-later'], 'high');
+    });
+
+    test('LGPL family → medium', () => {
+      assert.strictEqual(LICENCE_SEVERITY_MAP['lgpl-2.1'], 'medium');
+      assert.strictEqual(LICENCE_SEVERITY_MAP['lgpl-2.1-only'], 'medium');
+      assert.strictEqual(LICENCE_SEVERITY_MAP['lgpl-2.1-or-later'], 'medium');
+      assert.strictEqual(LICENCE_SEVERITY_MAP['lgpl-3.0'], 'medium');
+      assert.strictEqual(LICENCE_SEVERITY_MAP['lgpl-3.0-only'], 'medium');
+      assert.strictEqual(LICENCE_SEVERITY_MAP['lgpl-3.0-or-later'], 'medium');
+    });
+
+    test('MPL family → medium', () => {
+      assert.strictEqual(LICENCE_SEVERITY_MAP['mpl-1.1'], 'medium');
+      assert.strictEqual(LICENCE_SEVERITY_MAP['mpl-2.0'], 'medium');
+    });
+
+    test('SSPL family → high (PKG-34)', () => {
+      assert.strictEqual(LICENCE_SEVERITY_MAP['sspl-1.0'], 'high');
+      assert.strictEqual(LICENCE_SEVERITY_MAP['sspl-1.0-only'], 'high');
+    });
+  });
+
+  describe('_mapLicenceToSeverity — 8 raw-input permutations', () => {
+    test('GPL-3.0 (canonical) → high', () => {
+      assert.strictEqual(_mapLicenceToSeverity('GPL-3.0'), 'high');
+    });
+
+    test('agpl-3.0-or-later (already lower) → high', () => {
+      assert.strictEqual(_mapLicenceToSeverity('agpl-3.0-or-later'), 'high');
+    });
+
+    test('LGPL-2.1 → medium', () => {
+      assert.strictEqual(_mapLicenceToSeverity('LGPL-2.1'), 'medium');
+    });
+
+    test('MPL-2.0 → medium', () => {
+      assert.strictEqual(_mapLicenceToSeverity('MPL-2.0'), 'medium');
+    });
+
+    test('MIT → null (permissive)', () => {
+      assert.strictEqual(_mapLicenceToSeverity('MIT'), null);
+    });
+
+    test('Apache-2.0 → null (permissive)', () => {
+      assert.strictEqual(_mapLicenceToSeverity('Apache-2.0'), null);
+    });
+
+    test('BSD-3-Clause → null', () => {
+      assert.strictEqual(_mapLicenceToSeverity('BSD-3-Clause'), null);
+    });
+
+    test('ISC → null', () => {
+      assert.strictEqual(_mapLicenceToSeverity('ISC'), null);
+    });
+
+    test('null / undefined → null (no licence field)', () => {
+      assert.strictEqual(_mapLicenceToSeverity(null), null);
+      assert.strictEqual(_mapLicenceToSeverity(undefined), null);
+    });
+  });
+
+  describe('_canonicalFindingsForAdapter — split + ordering + id derivation', () => {
+    test('Snyk finding with licence GPL-3.0 splits into 2 findings (security + licence)', () => {
+      const adapterFinding = makeFinding({
+        id: 'pkg-007',
+        tool: 'snyk',
+        package_name: 'gpl-dep',
+        installed_version: '2.0.0',
+        severity: 'high',
+        licence: 'GPL-3.0',
+      });
+      const out = _canonicalFindingsForAdapter(adapterFinding);
+      assert.ok(Array.isArray(out), 'returns an array');
+      assert.strictEqual(out.length, 2, 'security + licence = 2 findings');
+
+      const [security, licenceFinding] = out;
+      // Security finding (unchanged shape):
+      assert.strictEqual(security.id, 'pkg-007');
+      assert.strictEqual(security.gap_type, 'dependency-security');
+      assert.strictEqual(security.severity, 'high');
+      // Licence finding:
+      assert.strictEqual(licenceFinding.id, 'pkg-007-lic', 'licence id derived as `${id}-lic`');
+      assert.strictEqual(licenceFinding.gap_type, 'dependency-licence');
+      assert.strictEqual(licenceFinding.severity, 'high');
+      assert.strictEqual(licenceFinding.title, 'Restrictive licence: GPL-3.0');
+      assert.strictEqual(
+        licenceFinding.description,
+        'Package gpl-dep@2.0.0 is licensed under GPL-3.0. Using this dependency may impose copyleft obligations on your project.',
+      );
+      assert.strictEqual(
+        licenceFinding.remediation,
+        'Review licence compatibility or replace with a permissive-licensed alternative.',
+      );
+      assert.strictEqual(licenceFinding.reference, null);
+      assert.strictEqual(licenceFinding.cve, null);
+      assert.strictEqual(licenceFinding.cvss, null);
+      assert.strictEqual(licenceFinding.dependency_chain, null);
+      assert.strictEqual(licenceFinding.chain_available, false);
+      assert.strictEqual(licenceFinding.tool, 'snyk');
+      assert.strictEqual(licenceFinding.test_source, 'package-scan');
+    });
+
+    test('licence finding resource_id matches security finding (correlation on resource_id)', () => {
+      const adapterFinding = makeFinding({
+        id: 'pkg-003',
+        tool: 'snyk',
+        package_name: 'some-pkg',
+        installed_version: '1.2.3',
+        severity: 'high',
+        licence: 'AGPL-3.0',
+      });
+      const [security, licenceFinding] = _canonicalFindingsForAdapter(adapterFinding);
+      assert.strictEqual(security.resource_id, 'some-pkg@1.2.3');
+      assert.strictEqual(licenceFinding.resource_id, 'some-pkg@1.2.3');
+    });
+
+    test('Snyk finding with MIT licence emits only the security finding (no split)', () => {
+      const adapterFinding = makeFinding({
+        id: 'pkg-008',
+        tool: 'snyk',
+        severity: 'high',
+        licence: 'MIT',
+      });
+      const out = _canonicalFindingsForAdapter(adapterFinding);
+      assert.strictEqual(out.length, 1);
+      assert.strictEqual(out[0].gap_type, 'dependency-security');
+    });
+
+    test('non-Snyk tool with licence GPL-3.0 emits only security finding (licence split is Snyk-only per PKG-30)', () => {
+      const adapterFinding = makeFinding({
+        id: 'pkg-009',
+        tool: 'npm-audit',
+        severity: 'high',
+        licence: 'GPL-3.0',
+      });
+      const out = _canonicalFindingsForAdapter(adapterFinding);
+      assert.strictEqual(out.length, 1);
+      assert.strictEqual(out[0].gap_type, 'dependency-security');
+    });
+
+    test('severity moderate (npm-audit) → medium', () => {
+      const adapterFinding = makeFinding({ severity: 'moderate', tool: 'npm-audit' });
+      const out = _canonicalFindingsForAdapter(adapterFinding);
+      assert.strictEqual(out[0].severity, 'medium');
+    });
+
+    test('severity MODERATE (OSV database_specific) → medium', () => {
+      const adapterFinding = makeFinding({ severity: 'MODERATE', tool: 'osv-scanner' });
+      const out = _canonicalFindingsForAdapter(adapterFinding);
+      assert.strictEqual(out[0].severity, 'medium');
+    });
+
+    test('severity info (npm-audit) → low', () => {
+      const adapterFinding = makeFinding({ severity: 'info', tool: 'npm-audit' });
+      const out = _canonicalFindingsForAdapter(adapterFinding);
+      assert.strictEqual(out[0].severity, 'low');
+    });
+
+    test('severity null (pip-audit) → medium (conservative bias)', () => {
+      const adapterFinding = makeFinding({ severity: null, tool: 'pip-audit' });
+      const out = _canonicalFindingsForAdapter(adapterFinding);
+      assert.strictEqual(out[0].severity, 'medium');
+    });
+
+    test('licence finding inherits manifest_path and direct_or_transitive from security finding', () => {
+      const adapterFinding = makeFinding({
+        id: 'pkg-010',
+        tool: 'snyk',
+        severity: 'high',
+        licence: 'GPL-3.0',
+        manifest_path: 'packages/api/package.json',
+        direct_or_transitive: 'direct',
+      });
+      const [_sec, lic] = _canonicalFindingsForAdapter(adapterFinding);
+      assert.strictEqual(lic.manifest_path, 'packages/api/package.json');
+      assert.strictEqual(lic.direct_or_transitive, 'direct');
+    });
+
+    test('security finding with f.id=null keeps id=null; licence finding id stays null', () => {
+      const adapterFinding = makeFinding({ id: null, tool: 'snyk', licence: 'GPL-3.0' });
+      // adjust makeFinding default (it sets 'pkg-001') by override; here we explicitly set null
+      const out = _canonicalFindingsForAdapter(Object.assign({}, adapterFinding, { id: null }));
+      assert.strictEqual(out[0].id, null);
+      assert.strictEqual(out[1].id, null);
+    });
+  });
+
+  describe('canonical field ordering', () => {
+    test('emitted finding lists keys in the exact FINDING_FIELD_ORDER sequence', () => {
+      const adapterFinding = makeFinding({
+        id: 'pkg-042',
+        tool: 'snyk',
+        severity: 'high',
+        manifest_path: 'packages/api/package.json',
+        licence: null,
+      });
+      const [canonical] = _canonicalFindingsForAdapter(adapterFinding);
+      const payload = makeFrontmatterPayload({ findings: [canonical] });
+      const emitted = _emitYamlFrontmatter(payload);
+      // Extract lines belonging to findings[0]; find the first finding entry
+      // block and check key order line-by-line.
+      const EXPECTED_ORDER = [
+        'id', 'test_source', 'gap_type', 'severity', 'resource_id',
+        'repo', 'manifest_path', 'title', 'description', 'remediation',
+        'reference', 'cve', 'cvss', 'dependency_chain', 'chain_available',
+        'direct_or_transitive', 'tool',
+      ];
+      const seenKeys = [];
+      for (const line of emitted.split('\n')) {
+        // The first key line starts with `  - id:`; subsequent lines in the
+        // same entry start with `    <key>:`. Stop at the next `---` fence.
+        const m = line.match(/^\s*(?:-\s+)?([a-z_]+):/);
+        if (!m) continue;
+        const key = m[1];
+        if (EXPECTED_ORDER.includes(key) && !seenKeys.includes(key)) {
+          seenKeys.push(key);
+        }
+      }
+      // seenKeys MAY include top-level fields (type, date, tool, etc.) that
+      // collide with finding field names (e.g., `tool`). Collect only the
+      // keys that appear AFTER the `findings:` header.
+      const findingsHeaderIdx = emitted.indexOf('\nfindings:');
+      assert.ok(findingsHeaderIdx >= 0, 'findings: header must exist');
+      const findingsBlock = emitted.slice(findingsHeaderIdx);
+      const findingKeys = [];
+      for (const line of findingsBlock.split('\n')) {
+        const m = line.match(/^\s*(?:-\s+)?([a-z_]+):/);
+        if (!m) continue;
+        const key = m[1];
+        if (EXPECTED_ORDER.includes(key)) findingKeys.push(key);
+      }
+      // The FIRST occurrence of each expected key must appear in the
+      // documented order.
+      const firstIdx = {};
+      for (let i = 0; i < findingKeys.length; i += 1) {
+        if (firstIdx[findingKeys[i]] === undefined) firstIdx[findingKeys[i]] = i;
+      }
+      for (let i = 1; i < EXPECTED_ORDER.length; i += 1) {
+        const prev = EXPECTED_ORDER[i - 1];
+        const curr = EXPECTED_ORDER[i];
+        if (firstIdx[prev] === undefined || firstIdx[curr] === undefined) continue;
+        assert.ok(
+          firstIdx[prev] < firstIdx[curr],
+          `Key ${prev} must appear before ${curr} in emitted frontmatter`,
+        );
+      }
+    });
+  });
+
+  describe('writePackageScanReport — flatMap licence split integration', () => {
+    test('emits 2 findings (security + licence) for a single Snyk GPL finding', () => {
+      const tmpDir = setupPlanningRoot({ config: { mode: 'v2' } });
+      try {
+        const snykFinding = makeFinding({
+          id: 'pkg-001',
+          tool: 'snyk',
+          severity: 'high',
+          package_name: 'gpl-dep',
+          installed_version: '2.0.0',
+          licence: 'GPL-3.0',
+        });
+        const rr = makeRunResult({
+          findings: [snykFinding],
+          repo_results: [{
+            repo: 'api',
+            ecosystem: 'node',
+            tool_used: 'snyk',
+            outcome: 'ok',
+            findings: [snykFinding],
+            durationMs: 1000,
+          }],
+        });
+        const outPath = path.join(tmpDir, 'OUT.md');
+        const res = writePackageScanReport(tmpDir, rr, { overridePath: outPath, now: () => new Date('2026-04-17T00:00:00.000Z') });
+        const content = fs.readFileSync(res.path, 'utf-8');
+        // Extract frontmatter
+        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, 'flatMap produces 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');
+      } finally {
+        cleanup(tmpDir);
+      }
+    });
+
+    test('pip-audit null severity → medium tier in the emitted canonical finding', () => {
+      const tmpDir = setupPlanningRoot({ config: { mode: 'v2' } });
+      try {
+        const pipFinding = makeFinding({
+          id: 'pkg-002',
+          tool: 'pip-audit',
+          severity: null,
+          package_name: 'requests',
+          installed_version: '2.25.0',
+        });
+        const rr = makeRunResult({
+          findings: [pipFinding],
+          repo_results: [{
+            repo: 'worker', ecosystem: 'python', tool_used: 'pip-audit',
+            outcome: 'ok', findings: [pipFinding], durationMs: 500,
+          }],
+        });
+        const outPath = path.join(tmpDir, 'OUT.md');
+        const res = writePackageScanReport(tmpDir, rr, { overridePath: outPath, now: () => new Date('2026-04-17T00:00:00.000Z') });
+        const content = fs.readFileSync(res.path, 'utf-8');
+        const m = content.match(/^---\n([\s\S]*?)\n---/);
+        const parsed = _parseEmittedYaml('---\n' + m[1] + '\n---');
+        assert.strictEqual(parsed.findings.length, 1);
+        assert.strictEqual(parsed.findings[0].severity, 'medium');
+      } finally {
+        cleanup(tmpDir);
+      }
+    });
+  });
+});
+
+// ─── Phase 153 Plan 02: .snyk policy in report body (PKG-32) ─────────────────
+
+describe('Phase 153: .snyk policy in report body (PKG-32)', () => {
+  test('Summary table contains ".snyk policy" header', () => {
+    const result = makeRunResult({
+      repo_results: [{ repo: 'api', ecosystem: 'node', tool_used: 'snyk', outcome: 'ok', findings: [], durationMs: 1, has_snyk_policy: true, snyk_suppressions_count: 2 }],
+      findings: [],
+    });
+    const body = _renderBody(result);
+    assert.match(body, /\.snyk policy/);
+  });
+
+  test('Summary row for has_snyk_policy:true contains "| yes |"', () => {
+    const result = makeRunResult({
+      repo_results: [{ repo: 'api', ecosystem: 'node', tool_used: 'snyk', outcome: 'ok', findings: [], durationMs: 1, has_snyk_policy: true, snyk_suppressions_count: 0 }],
+      findings: [],
+    });
+    const body = _renderBody(result);
+    assert.match(body, /\| yes \|/);
+  });
+
+  test('per-repo suppression note when count > 0', () => {
+    const result = makeRunResult({
+      repo_results: [{ repo: 'api', ecosystem: 'node', tool_used: 'snyk', outcome: 'ok', findings: [], durationMs: 1, has_snyk_policy: true, snyk_suppressions_count: 2 }],
+      findings: [],
+    });
+    const body = _renderBody(result);
+    assert.match(body, /\.snyk policy applied: 2 vulnerabilit(y|ies) suppressed/);
+  });
+
+  test('has_snyk_policy:false on every repo => column shows "no" + no suppression line', () => {
+    const result = makeRunResult({
+      repo_results: [
+        { repo: 'api', ecosystem: 'node', tool_used: 'snyk', outcome: 'ok', findings: [], durationMs: 1, has_snyk_policy: false, snyk_suppressions_count: 0 },
+        { repo: 'web', ecosystem: 'node', tool_used: 'snyk', outcome: 'ok', findings: [], durationMs: 1, has_snyk_policy: false, snyk_suppressions_count: 0 },
+      ],
+      findings: [],
+    });
+    const body = _renderBody(result);
+    assert.match(body, /\.snyk policy/);
+    assert.match(body, /\| no \|/);
+    assert.doesNotMatch(body, /\.snyk policy applied:/);
+  });
+});
+
+// ─── Phase 153 Plan 05: provenance in canonical + body (PKG-33) ──────────────
+
+describe('Phase 153: provenance in canonical + body (PKG-33)', () => {
+  const {
+    _mapAdapterFindingToCanonical,
+    _emitYamlFrontmatter,
+    _parseEmittedYaml,
+  } = require('./package-scan-report.cjs');
+  const reportModule = require('./package-scan-report.cjs');
+
+  test('_mapAdapterFindingToCanonical preserves introduced_in_commit + introduced_in_plan', () => {
+    const adapterF = makeFinding({ id: 'pkg-001', severity: 'high' });
+    adapterF.introduced_in_commit = 'abc1234';
+    adapterF.introduced_in_plan = '149-01';
+    const canonical = _mapAdapterFindingToCanonical(adapterF);
+    assert.strictEqual(canonical.introduced_in_commit, 'abc1234');
+    assert.strictEqual(canonical.introduced_in_plan, '149-01');
+  });
+
+  test('FINDING_FIELD_ORDER ends with [..., introduced_in_commit, introduced_in_plan]', () => {
+    // The const isn't directly exported, but the canonical mapping result keys
+    // and the YAML emit order both reflect the order. Round-trip through emit.
+    const payload = makeFrontmatterPayload();
+    payload.findings[0].introduced_in_commit = 'abc1234';
+    payload.findings[0].introduced_in_plan = '149-01';
+    const emitted = _emitYamlFrontmatter(payload);
+    // introduced_in_commit and introduced_in_plan must appear AFTER tool in the emitted yaml.
+    const idxTool = emitted.indexOf('tool: "snyk"');
+    const idxCommit = emitted.indexOf('introduced_in_commit:');
+    const idxPlan = emitted.indexOf('introduced_in_plan:');
+    assert.ok(idxTool > 0);
+    assert.ok(idxCommit > idxTool);
+    assert.ok(idxPlan > idxCommit);
+  });
+
+  test('YAML round-trip preserves introduced_in_* fields', () => {
+    const payload = makeFrontmatterPayload();
+    payload.findings[0].introduced_in_commit = 'abc1234';
+    payload.findings[0].introduced_in_plan = '149-01';
+    const emitted = _emitYamlFrontmatter(payload);
+    const parsed = _parseEmittedYaml(emitted);
+    assert.strictEqual(parsed.findings[0].introduced_in_commit, 'abc1234');
+    assert.strictEqual(parsed.findings[0].introduced_in_plan, '149-01');
+  });
+
+  test('_renderBody includes "Introduced in: commit X (plan Y)" when both fields present', () => {
+    const findings = [makeFinding({ id: 'pkg-001', severity: 'critical' })];
+    findings[0].introduced_in_commit = 'abc1234';
+    findings[0].introduced_in_plan = '149-01';
+    const rr = [{ repo: 'api', ecosystem: 'node', tool_used: 'snyk', outcome: 'ok', findings, durationMs: 1 }];
+    const result = makeRunResult({ repo_results: rr, findings });
+    const body = reportModule._renderBody(result);
+    assert.match(body, /\*\*Introduced in:\*\* commit abc1234 \(plan 149-01\)/);
+  });
+
+  test('_renderBody includes "Introduced in: commit X" when only commit known', () => {
+    const findings = [makeFinding({ id: 'pkg-001', severity: 'critical' })];
+    findings[0].introduced_in_commit = 'abc1234';
+    findings[0].introduced_in_plan = null;
+    const rr = [{ repo: 'api', ecosystem: 'node', tool_used: 'snyk', outcome: 'ok', findings, durationMs: 1 }];
+    const result = makeRunResult({ repo_results: rr, findings });
+    const body = reportModule._renderBody(result);
+    assert.match(body, /\*\*Introduced in:\*\* commit abc1234/);
+    assert.doesNotMatch(body, /\(plan/);
+  });
+
+  test('_renderBody includes "Introduced in: unknown" when neither known', () => {
+    const findings = [makeFinding({ id: 'pkg-001', severity: 'critical' })];
+    findings[0].introduced_in_commit = null;
+    findings[0].introduced_in_plan = null;
+    const rr = [{ repo: 'api', ecosystem: 'node', tool_used: 'snyk', outcome: 'ok', findings, durationMs: 1 }];
+    const result = makeRunResult({ repo_results: rr, findings });
+    const body = reportModule._renderBody(result);
+    assert.match(body, /\*\*Introduced in:\*\* unknown/);
+  });
+});
+
+// ─── Phase 153 Plan 03: Licence Compliance section (PKG-30, PKG-34) ──────────
+
+describe('Phase 153: Licence Compliance section (PKG-30, PKG-34)', () => {
+  const reportModule = require('./package-scan-report.cjs');
+  const { LICENCE_SEVERITY_MAP, _mapLicenceToSeverity, _canonicalFindingsForAdapter } = reportModule;
+
+  test('LICENCE_SEVERITY_MAP[sspl-1.0] => high', () => {
+    assert.strictEqual(LICENCE_SEVERITY_MAP['sspl-1.0'], 'high');
+  });
+
+  test('_mapLicenceToSeverity SSPL-1.0 (case-insensitive) => high', () => {
+    assert.strictEqual(_mapLicenceToSeverity('SSPL-1.0'), 'high');
+  });
+
+  test('_canonicalFindingsForAdapter SSPL => 2 canonical findings, licence severity high', () => {
+    const adapterF = {
+      tool: 'snyk',
+      ecosystem: 'node',
+      repo: 'api',
+      manifest_path: null,
+      package_name: 'mongo-db',
+      installed_version: '5.0',
+      vulnerability: { cve: null, title: 't', description: null, reference_url: null },
+      severity: 'low',
+      cvss_score: null,
+      direct_or_transitive: null,
+      dependency_chain: null,
+      chain_available: false,
+      remediation: null,
+      licence: 'SSPL-1.0',
+      id: 'pkg-001',
+    };
+    const out = _canonicalFindingsForAdapter(adapterF);
+    assert.strictEqual(out.length, 2);
+    assert.strictEqual(out[1].severity, 'high');
+    assert.strictEqual(out[1].title, 'Restrictive licence: SSPL-1.0');
+  });
+
+  test('_renderLicenceComplianceSection (snyk + roster populated) renders table with flag column', () => {
+    const out = reportModule._renderLicenceComplianceSection({
+      tool_agg: 'snyk',
+      licence_roster: [
+        { repo: 'api', package_name: 'lodash', installed_version: '4.17.21', licence: 'MIT' },
+        { repo: 'api', package_name: 'gpl-pkg', installed_version: '1.0', licence: 'GPL-3.0' },
+      ],
+    });
+    assert.match(out, /## Licence Compliance/);
+    assert.match(out, /\| Package \| Version \| Repo \| Licence \| Flag \|/);
+    assert.match(out, /\| gpl-pkg \| 1\.0 \| api \| GPL-3\.0 \| RESTRICTIVE \|/);
+    // lodash row should have an empty flag cell.
+    assert.match(out, /\| lodash \| 4\.17\.21 \| api \| MIT \|  \|/);
+  });
+
+  test('_renderLicenceComplianceSection (snyk + empty roster) renders accurate completed note with policy URL (UAT Bug 3)', () => {
+    const out = reportModule._renderLicenceComplianceSection({ tool_agg: 'snyk', licence_roster: [] });
+    assert.match(out, /## Licence Compliance/);
+    // New Snyk-specific completed message.
+    assert.match(out, /Snyk licence scan completed; no restrictive licences flagged/);
+    // References Snyk org-level licence policy config URL.
+    assert.match(out, /app\.snyk\.io.*licen[cs]es?/i);
+    // MUST NOT repeat the non-snyk "use Snyk for full coverage" message.
+    assert.doesNotMatch(out, /use Snyk for full coverage/);
+    // No table rendered (empty roster).
+    assert.doesNotMatch(out, /\| Package \| Version \|/);
+  });
+
+  test('_renderLicenceComplianceSection (non-snyk tool, empty roster) still renders legacy coverage prompt (UAT Bug 3 regression)', () => {
+    const out = reportModule._renderLicenceComplianceSection({ tool_agg: 'osv-scanner', licence_roster: [] });
+    assert.match(out, /Licence scan incomplete -- use Snyk for full coverage/);
+  });
+
+  test('_renderLicenceComplianceSection (non-snyk tool) renders incomplete note even with populated roster', () => {
+    const out = reportModule._renderLicenceComplianceSection({
+      tool_agg: 'osv-scanner',
+      licence_roster: [{ repo: 'api', package_name: 'foo', installed_version: '1.0', licence: 'MIT' }],
+    });
+    assert.match(out, /## Licence Compliance/);
+    assert.match(out, /Licence scan incomplete -- use Snyk for full coverage/);
+  });
+
+  test('_renderLicenceComplianceSection (null inputs) renders incomplete note (defensive)', () => {
+    const out = reportModule._renderLicenceComplianceSection({ tool_agg: null, licence_roster: null });
+    assert.match(out, /Licence scan incomplete -- use Snyk for full coverage/);
+  });
+
+  test('flag mapping: LGPL/MPL => copyleft; AGPL/SSPL => RESTRICTIVE; permissive => blank', () => {
+    const roster = [
+      { repo: 'api', package_name: 'a-lgpl', installed_version: '1.0', licence: 'LGPL-2.1' },
+      { repo: 'api', package_name: 'b-mpl', installed_version: '1.0', licence: 'MPL-2.0' },
+      { repo: 'api', package_name: 'c-agpl', installed_version: '1.0', licence: 'AGPL-3.0' },
+      { repo: 'api', package_name: 'd-sspl', installed_version: '1.0', licence: 'SSPL-1.0' },
+      { repo: 'api', package_name: 'e-apache', installed_version: '1.0', licence: 'Apache-2.0' },
+      { repo: 'api', package_name: 'f-isc', installed_version: '1.0', licence: 'ISC' },
+      { repo: 'api', package_name: 'g-bsd', installed_version: '1.0', licence: 'BSD-3-Clause' },
+    ];
+    const out = reportModule._renderLicenceComplianceSection({ tool_agg: 'snyk', licence_roster: roster });
+    assert.match(out, /a-lgpl.*\| copyleft \|/);
+    assert.match(out, /b-mpl.*\| copyleft \|/);
+    assert.match(out, /c-agpl.*\| RESTRICTIVE \|/);
+    assert.match(out, /d-sspl.*\| RESTRICTIVE \|/);
+    // Apache, ISC, BSD => blank
+    assert.match(out, /e-apache.*\| Apache-2\.0 \|  \|/);
+  });
+
+  test('section ends with blank line (no run-on)', () => {
+    const out = reportModule._renderLicenceComplianceSection({ tool_agg: 'snyk', licence_roster: [] });
+    assert.ok(out.endsWith('\n'), 'must end with newline');
+  });
+
+  test('_renderBody emits Licence Compliance AFTER Summary and BEFORE severity sections', () => {
+    const findings = [makeFinding({ id: 'pkg-001', severity: 'critical' })];
+    const rr = [{ repo: 'api', ecosystem: 'node', tool_used: 'snyk', outcome: 'ok', findings, durationMs: 1 }];
+    const result = makeRunResult({ repo_results: rr, findings });
+    result.licence_roster = [
+      { repo: 'api', package_name: 'lodash', installed_version: '4.17.21', licence: 'MIT' },
+    ];
+    const body = reportModule._renderBody(result);
+    const idxSummary = body.indexOf('## Summary');
+    const idxLicence = body.indexOf('## Licence Compliance');
+    const idxCritical = body.indexOf('## Critical');
+    assert.ok(idxSummary >= 0);
+    assert.ok(idxLicence > idxSummary);
+    assert.ok(idxCritical > idxLicence);
+  });
+});
+
+// ─── Phase 153 Plan 03: licence_roster on runResult ──────────────────────────
+// Note: orchestrator-level tests live in package-scan.test.cjs.
+
+// ─── Phase 153 Plan 04: Cross-repo dedup (PKG-35) ────────────────────────────
+
+describe('Phase 153: Cross-repo dedup (PKG-35)', () => {
+  const reportModule = require('./package-scan-report.cjs');
+  const { _groupFindingsByPackageVersion, _renderCrossRepoSummary } = reportModule;
+
+  function mkF({ pkg = 'lodash', ver = '4.17.21', repo = 'api', sev = 'high', cve = null, title = '' } = {}) {
+    return { package_name: pkg, installed_version: ver, repo, severity: sev, vulnerability: { cve, title } };
+  }
+
+  test('empty findings => []', () => {
+    assert.deepStrictEqual(_groupFindingsByPackageVersion([]), []);
+  });
+
+  test('single finding => one group with repos:[that repo]', () => {
+    const out = _groupFindingsByPackageVersion([mkF()]);
+    assert.strictEqual(out.length, 1);
+    assert.deepStrictEqual(out[0].repos, ['api']);
+  });
+
+  test('two findings same (pkg, ver, cve) different repos => one group repos length 2', () => {
+    const out = _groupFindingsByPackageVersion([
+      mkF({ repo: 'api', cve: 'CVE-2020-8203' }),
+      mkF({ repo: 'web', cve: 'CVE-2020-8203' }),
+    ]);
+    assert.strictEqual(out.length, 1);
+    assert.strictEqual(out[0].repos.length, 2);
+  });
+
+  test('two findings same pkg different versions => 2 groups', () => {
+    const out = _groupFindingsByPackageVersion([
+      mkF({ ver: '4.17.10' }),
+      mkF({ ver: '4.17.21' }),
+    ]);
+    assert.strictEqual(out.length, 2);
+  });
+
+  test('two findings same pkg same ver different CVE => 2 groups', () => {
+    const out = _groupFindingsByPackageVersion([
+      mkF({ cve: 'CVE-2020-8203' }),
+      mkF({ cve: 'CVE-2021-23337' }),
+    ]);
+    assert.strictEqual(out.length, 2);
+  });
+
+  test('findings without cve use title as fallback grouping key', () => {
+    const out = _groupFindingsByPackageVersion([
+      mkF({ cve: null, title: 'Prototype Pollution' }),
+      mkF({ cve: null, title: 'Prototype Pollution', repo: 'web' }),
+    ]);
+    assert.strictEqual(out.length, 1);
+    assert.strictEqual(out[0].repos.length, 2);
+  });
+
+  test('deterministic ordering: severity desc, then repo-count desc, then name asc', () => {
+    const out = _groupFindingsByPackageVersion([
+      mkF({ pkg: 'a-low', sev: 'high', cve: 'X', repo: 'r1' }),
+      mkF({ pkg: 'b-multi', sev: 'high', cve: 'Y', repo: 'r1' }),
+      mkF({ pkg: 'b-multi', sev: 'high', cve: 'Y', repo: 'r2' }),
+      mkF({ pkg: 'c-crit', sev: 'critical', cve: 'Z', repo: 'r1' }),
+      mkF({ pkg: 'd-crit-multi', sev: 'critical', cve: 'W', repo: 'r1' }),
+      mkF({ pkg: 'd-crit-multi', sev: 'critical', cve: 'W', repo: 'r2' }),
+    ]);
+    // Order: critical+repos=2, critical+repos=1, high+repos=2, high+repos=1
+    assert.strictEqual(out[0].package_name, 'd-crit-multi');
+    assert.strictEqual(out[1].package_name, 'c-crit');
+    assert.strictEqual(out[2].package_name, 'b-multi');
+    assert.strictEqual(out[3].package_name, 'a-low');
+  });
+
+  test('_renderCrossRepoSummary([]) returns empty string', () => {
+    assert.strictEqual(_renderCrossRepoSummary([]), '');
+  });
+
+  test('_renderCrossRepoSummary with multi-repo group renders ## Cross-Repo Summary header + table', () => {
+    const groups = [
+      { package_name: 'lodash', installed_version: '4.17.21', cve: 'CVE-2020-8203', severity: 'high', repos: ['api', 'web'], title: '' },
+    ];
+    const out = _renderCrossRepoSummary(groups);
+    assert.match(out, /## Cross-Repo Summary/);
+    assert.match(out, /\| lodash \| 4\.17\.21 \| CVE-2020-8203 \| high \| api, web \|/);
+  });
+});
+
+// ─── Phase 153 Plan 04: Version overlap (PKG-36) ─────────────────────────────
+
+describe('Phase 153: Version overlap (PKG-36)', () => {
+  const reportModule = require('./package-scan-report.cjs');
+  const { _detectVersionOverlaps, _renderVersionOverlap } = reportModule;
+
+  test('empty inputs => []', () => {
+    assert.deepStrictEqual(_detectVersionOverlaps([], []), []);
+  });
+
+  test('single version single repo => no overlap', () => {
+    const out = _detectVersionOverlaps(
+      [{ package_name: 'lodash', installed_version: '4.17.21', repo: 'api' }],
+      []
+    );
+    assert.deepStrictEqual(out, []);
+  });
+
+  test('two versions across two repos => one overlap entry with sorted versions', () => {
+    const out = _detectVersionOverlaps(
+      [
+        { package_name: 'lodash', installed_version: '4.17.21', repo: 'api' },
+        { package_name: 'lodash', installed_version: '4.17.10', repo: 'web' },
+      ],
+      []
+    );
+    assert.strictEqual(out.length, 1);
+    assert.deepStrictEqual(out[0].versions, ['4.17.10', '4.17.21']);
+    assert.deepStrictEqual(out[0].repos['4.17.21'], ['api']);
+    assert.deepStrictEqual(out[0].repos['4.17.10'], ['web']);
+  });
+
+  test('licence roster supplies a version not in findings => overlap detected', () => {
+    const out = _detectVersionOverlaps(
+      [{ package_name: 'lodash', installed_version: '4.17.21', repo: 'api' }],
+      [{ package_name: 'lodash', installed_version: '4.17.10', repo: 'web' }]
+    );
+    assert.strictEqual(out.length, 1);
+  });
+
+  test('same version multiple repos => not an overlap', () => {
+    const out = _detectVersionOverlaps(
+      [
+        { package_name: 'lodash', installed_version: '4.17.21', repo: 'api' },
+        { package_name: 'lodash', installed_version: '4.17.21', repo: 'web' },
+      ],
+      []
+    );
+    assert.deepStrictEqual(out, []);
+  });
+
+  test('three versions across three repos => versions length 3', () => {
+    const out = _detectVersionOverlaps(
+      [
+        { package_name: 'lodash', installed_version: '4.17.21', repo: 'a' },
+        { package_name: 'lodash', installed_version: '4.17.10', repo: 'b' },
+        { package_name: 'lodash', installed_version: '3.10.1', repo: 'c' },
+      ],
+      []
+    );
+    assert.strictEqual(out.length, 1);
+    assert.strictEqual(out[0].versions.length, 3);
+  });
+
+  test('null roster works via findings-only', () => {
+    const out = _detectVersionOverlaps(
+      [
+        { package_name: 'lodash', installed_version: '4.17.21', repo: 'a' },
+        { package_name: 'lodash', installed_version: '4.17.10', repo: 'b' },
+      ],
+      null
+    );
+    assert.strictEqual(out.length, 1);
+  });
+
+  test('_renderVersionOverlap([]) returns empty string', () => {
+    assert.strictEqual(_renderVersionOverlap([]), '');
+  });
+
+  test('_renderVersionOverlap renders ## Dependency Overlap header + table', () => {
+    const out = _renderVersionOverlap([
+      { package_name: 'lodash', versions: ['4.17.10', '4.17.21'], repos: { '4.17.10': ['web'], '4.17.21': ['api'] } },
+    ]);
+    assert.match(out, /## Dependency Overlap/);
+    assert.match(out, /\| lodash \| 4\.17\.10, 4\.17\.21 \|/);
+  });
+});
+
+// ─── Phase 153 Plan 04: body section ordering (PKG-35, PKG-36) ───────────────
+
+describe('Phase 153: body section ordering (PKG-35, PKG-36)', () => {
+  const reportModule = require('./package-scan-report.cjs');
+
+  test('body order: Licence Compliance => Cross-Repo Summary => Dependency Overlap => Critical', () => {
+    const findings = [
+      { id: 'pkg-001', tool: 'snyk', ecosystem: 'node', repo: 'api', manifest_path: null, package_name: 'lodash', installed_version: '4.17.21', severity: 'critical', vulnerability: { cve: 'CVE-X', title: 't', description: null, reference_url: null }, cvss_score: null, dependency_chain: null, chain_available: false, direct_or_transitive: null, fix_version: null, remediation: null, licence: null },
+      { id: 'pkg-002', tool: 'snyk', ecosystem: 'node', repo: 'web', manifest_path: null, package_name: 'lodash', installed_version: '4.17.21', severity: 'critical', vulnerability: { cve: 'CVE-X', title: 't', description: null, reference_url: null }, cvss_score: null, dependency_chain: null, chain_available: false, direct_or_transitive: null, fix_version: null, remediation: null, licence: null },
+      { id: 'pkg-003', tool: 'snyk', ecosystem: 'node', repo: 'api', manifest_path: null, package_name: 'axios', installed_version: '1.0.0', severity: 'high', vulnerability: { cve: 'CVE-Y', title: 't', description: null, reference_url: null }, cvss_score: null, dependency_chain: null, chain_available: false, direct_or_transitive: null, fix_version: null, remediation: null, licence: null },
+      { id: 'pkg-004', tool: 'snyk', ecosystem: 'node', repo: 'web', manifest_path: null, package_name: 'axios', installed_version: '0.27.0', severity: 'high', vulnerability: { cve: 'CVE-Y', title: 't', description: null, reference_url: null }, cvss_score: null, dependency_chain: null, chain_available: false, direct_or_transitive: null, fix_version: null, remediation: null, licence: null },
+    ];
+    const rr = [
+      { repo: 'api', ecosystem: 'node', tool_used: 'snyk', outcome: 'ok', findings: [findings[0], findings[2]], durationMs: 1 },
+      { repo: 'web', ecosystem: 'node', tool_used: 'snyk', outcome: 'ok', findings: [findings[1], findings[3]], durationMs: 1 },
+    ];
+    const result = makeRunResult({ repo_results: rr, findings });
+    result.licence_roster = [{ repo: 'api', package_name: 'lodash', installed_version: '4.17.21', licence: 'MIT' }];
+    const body = reportModule._renderBody(result);
+    const idxLicence = body.indexOf('## Licence Compliance');
+    const idxCross = body.indexOf('## Cross-Repo Summary');
+    const idxOverlap = body.indexOf('## Dependency Overlap');
+    const idxCritical = body.indexOf('## Critical');
+    assert.ok(idxLicence > 0, 'has Licence Compliance');
+    assert.ok(idxCross > idxLicence, 'Cross-Repo Summary after Licence');
+    assert.ok(idxOverlap > idxCross, 'Dependency Overlap after Cross-Repo Summary');
+    assert.ok(idxCritical > idxOverlap, 'Critical section after Dependency Overlap');
+  });
+
+  test('no shared findings + single versions => no Cross-Repo Summary or Dependency Overlap', () => {
+    const findings = [
+      { id: 'pkg-001', tool: 'snyk', ecosystem: 'node', repo: 'api', manifest_path: null, package_name: 'lodash', installed_version: '4.17.21', severity: 'critical', vulnerability: { cve: 'CVE-X', title: 't', description: null, reference_url: null }, cvss_score: null, dependency_chain: null, chain_available: false, direct_or_transitive: null, fix_version: null, remediation: null, licence: null },
+    ];
+    const rr = [
+      { repo: 'api', ecosystem: 'node', tool_used: 'snyk', outcome: 'ok', findings, durationMs: 1 },
+    ];
+    const result = makeRunResult({ repo_results: rr, findings });
+    const body = reportModule._renderBody(result);
+    assert.doesNotMatch(body, /## Cross-Repo Summary/);
+    assert.doesNotMatch(body, /## Dependency Overlap/);
+  });
+});
+
+
+