@clear-capabilities/agentic-security-scanner 0.160.0 → 0.162.0

package/src/posture/assurance/baseline-inventory.js

@@ -0,0 +1,218 @@
+// The recommendation mappings and the capability inventory that baseline capture
+// (CORE-001) records. Pure data. Every path is relative to the repository root and
+// is VERIFIED against the checkout at capture time: a path that does not exist is
+// reported as a problem, never carried as if it did.
+//
+// Status vocabulary (one per capability, never combined):
+//   implemented  the capability exists, has a source path and a test or artifact,
+//                and no gap against the differentiation PRD is known.
+//   partial      it exists and is tested, and `gap` names exactly what the PRD
+//                still needs on top of it.
+//   unsupported  the PRD calls for it and the checkout does not provide it; `source`
+//                is the existing extension point it would attach to, `evidence` the
+//                test that covers that neighbour, and `gap` says what is absent.
+//   unmeasured   it exists but no current-revision measurement of it is recorded;
+//                `evidence` is the artifact that exists and `gap` says why it is not a
+//                current measurement.
+//
+// This is a statement about what was inspected, not a quality score. Moving an
+// entry to a stronger status needs the new source and evidence paths to land first.
+
+export const RECOMMENDATION_MAPPINGS = Object.freeze([
+  {
+    n: 1, title: 'Refresh real-code evaluation and repair measured misses', priority: 'P0', slice: 'QA-001..QA-008',
+    extensionPoints: ['bench/independent', 'scanner/src/posture/accuracy-scorecard.js', 'scripts/scorecard.mjs', 'docs/scorecard.json'],
+  },
+  {
+    n: 2, title: 'Unify verification and expand trusted runtime oracles', priority: 'P0', slice: 'X-201..X-208',
+    extensionPoints: ['scanner/src/posture/fix-verify.js', 'scanner/src/posture/execution-proof.js', 'scanner/src/posture/verifier.js', 'scanner/src/sandbox/index.js', 'scanner/src/posture/autopilot.js', 'scanner/src/mcp/tools.js'],
+  },
+  {
+    n: 3, title: 'Add a deployment-aware Code Boundaries graph', priority: 'P1', slice: 'X-301..X-308',
+    extensionPoints: ['scanner/src/lineage/runtime-observation.js', 'scanner/src/lineage/observation-adapters.js', 'scanner/src/lineage/observation-correlation.js', 'scanner/src/lineage/cross-repo-link.js', 'scanner/src/lineage/federation-loader.js', 'scanner/src/lineage/drift-policy.js'],
+  },
+  {
+    n: 4, title: 'Execute tenant and business invariants', priority: 'P1', slice: 'X-401..X-408',
+    extensionPoints: ['scanner/src/posture/business-logic.js', 'scanner/src/posture/logic-claims.js', 'scanner/src/posture/specification-mining.js', 'scanner/src/discovery'],
+  },
+  {
+    n: 5, title: 'Enforce coding-agent capabilities', priority: 'P1', slice: 'X-501..X-508',
+    extensionPoints: ['hooks/pre-bash-guard.js', 'hooks/pre-edit-bodyguard.js', 'hooks/dispatch-pre-tool.js', 'scanner/src/egress/policy.js', 'scanner/src/egress/redact.js', 'scanner/src/egress/audit.js', 'scanner/src/sandbox/index.js', 'scanner/src/mcp/server.js'],
+  },
+  {
+    n: 6, title: 'Calibrate model routing against outcomes', priority: 'P2', slice: 'X-601..X-608',
+    extensionPoints: ['scanner/src/posture/model-routing.js', 'scanner/src/posture/model-trust.js', 'scanner/src/posture/cache-economics.js', 'scanner/src/posture/provider-catalog.js'],
+  },
+  {
+    n: 7, title: 'Deliver portable release assurance and resumable portfolios', priority: 'P2', slice: 'X-701..X-708',
+    extensionPoints: ['scanner/src/posture/fleet.js', 'scanner/src/posture/scan-checkpoint.js', 'scanner/src/posture/attestation.js', 'scanner/src/posture/evidence-bundle.js', 'scanner/src/posture/integrity.js', 'scanner/src/posture/retention-policy.js'],
+  },
+]);
+
+const t = (p) => ({ kind: 'test', path: p });
+const a = (p) => ({ kind: 'artifact', path: p });
+
+export const CAPABILITY_INVENTORY = Object.freeze([
+  {
+    id: 'poc-replay', workstream: 2, title: 'Proof-of-concept generation and confined replay',
+    status: 'partial',
+    source: ['scanner/src/posture/poc-generator.js', 'scanner/src/posture/poc-inprocess.js', 'scanner/src/posture/execution-proof.js', 'scanner/src/posture/proof-tier.js'],
+    entryPoints: [{ path: 'scanner/src/posture/execution-proof.js', symbol: 'proveFinding' }, { path: 'scanner/src/posture/proof-tier.js', symbol: 'attachProofTier' }],
+    evidence: [t('scanner/test/poc-generator.test.js'), t('scanner/test/execution-proof.test.js'), t('scanner/test/proof-artifact.test.js')],
+    gap: 'replay is JavaScript/taint oriented and records a proof tier on the finding; there is no class-specific oracle adapter, no patched-negative replay, and no single verification record',
+    prd: ['X-201', 'X-202', 'X-203', 'X-204', 'X-205'],
+  },
+  {
+    id: 'fix-verification', workstream: 2, title: 'Fix verification (rescan, lint, tests, honesty gate, PoC re-check)',
+    status: 'partial',
+    source: ['scanner/src/posture/fix-verify.js', 'scanner/src/posture/fix-verify-loop.js', 'scanner/src/fix/apply-fix-service.js', 'scanner/src/posture/fix-honesty-gate.js'],
+    entryPoints: [{ path: 'scanner/src/posture/fix-verify.js', symbol: 'verifyFix' }, { path: 'scanner/src/fix/apply-fix-service.js', symbol: 'applyVerifiedFix' }],
+    evidence: [t('scanner/test/fix-verify-loop.test.js'), t('scanner/test/fix-verify-tests.test.js'), t('scanner/test/apply-fix-service.test.js'), t('scanner/test/fix-honesty-gate.test.js')],
+    gap: 'results are per-surface shapes, not one versioned record; original-positive, patched-negative and functional-regression evidence are not bound together by digest',
+    prd: ['X-201', 'X-204', 'X-206'],
+  },
+  {
+    id: 'verifier-separation', workstream: 2, title: 'Independent verifier and verification separation',
+    status: 'partial',
+    source: ['scanner/src/posture/verifier.js', 'scanner/src/posture/verification-separation.js', 'scanner/src/posture/verifier-target.js', 'scanner/src/posture/verifier-ephemeral.js'],
+    entryPoints: [],
+    evidence: [t('scanner/test/verifier.test.js'), t('scanner/test/verifier-independence.test.js'), t('scanner/test/verification-separation.test.js')],
+    gap: 'separation is enforced for the existing verifier path; key and label isolation for the new oracle workers is the CORE-003 trust-boundary work',
+    prd: ['CORE-003', 'X-202'],
+  },
+  {
+    id: 'sandbox-confinement', workstream: 2, title: 'Confinement sandbox (namespace, userspace and disabled backends)',
+    status: 'partial',
+    source: ['scanner/src/sandbox/index.js', 'scanner/src/sandbox/capabilities.js', 'scanner/src/sandbox/limits.js', 'scanner/src/sandbox/backend-namespace.js', 'scanner/src/sandbox/backend-userspace.js', 'scanner/src/sandbox/backend-disabled.js'],
+    entryPoints: [{ path: 'scanner/src/sandbox/index.js', symbol: 'runConfined' }],
+    evidence: [t('scanner/test/sandbox.test.js'), t('scanner/test/sandbox-escape.test.js')],
+    gap: 'isolation is probed per backend; descendant-process cleanup, read confinement and per-backend active probes are the CORE-003 work, and enforcement is only advertised on Linux',
+    prd: ['CORE-003', 'X-502', 'X-503'],
+  },
+  {
+    id: 'runtime-observation-imports', workstream: 3, title: 'Runtime observation imports and correlation',
+    status: 'partial',
+    source: ['scanner/src/lineage/runtime-observation.js', 'scanner/src/lineage/observation-adapters.js', 'scanner/src/lineage/observation-store.js', 'scanner/src/lineage/observation-correlation.js', 'scanner/src/posture/telemetry-ingest.js'],
+    entryPoints: [{ path: 'scanner/src/lineage/runtime-observation.js', symbol: 'validateRuntimeObservation' }, { path: 'scanner/src/lineage/observation-store.js', symbol: 'persistObservationImport' }],
+    evidence: [t('scanner/test/lineage/runtime-observation.test.js'), t('scanner/test/lineage/observation-adapters.test.js'), t('scanner/test/lineage/observation-store.test.js'), t('scanner/test/lineage/observation-correlation.test.js')],
+    gap: 'one adapter (native-jsonl) is implemented; observations corroborate lineage edges but do not yet bind to vulnerability hypotheses, and freshness and sampling are not modelled as path states',
+    prd: ['X-302', 'X-303', 'X-305'],
+  },
+  {
+    id: 'cross-repo-federation-drift', workstream: 3, title: 'Cross-repository links, federation and drift policy',
+    status: 'implemented',
+    source: ['scanner/src/lineage/cross-repo-link.js', 'scanner/src/lineage/federation-loader.js', 'scanner/src/lineage/drift-policy.js', 'scanner/src/lineage/graph-diff.js'],
+    entryPoints: [{ path: 'scanner/src/lineage/cross-repo-link.js', symbol: 'validateCrossRepoLink' }],
+    evidence: [t('scanner/test/lineage/cross-repo-link.test.js'), t('scanner/test/lineage/federation-loader.test.js'), t('scanner/test/lineage/drift-policy.test.js')],
+    gap: null,
+    prd: ['X-304', 'X-306'],
+  },
+  {
+    id: 'business-logic-claims', workstream: 4, title: 'Business-logic detection, logic claims and specification mining',
+    status: 'partial',
+    source: ['scanner/src/posture/business-logic.js', 'scanner/src/posture/logic-claims.js', 'scanner/src/posture/specification-mining.js'],
+    entryPoints: [],
+    evidence: [t('scanner/test/business-logic.test.js'), t('scanner/test/logic-claims.test.js'), t('scanner/test/phase3-v3.test.js')],
+    gap: 'claims are advisory findings; there are no declarative approved invariants and no bounded stateful scenario execution',
+    prd: ['X-401', 'X-402', 'X-403', 'X-404'],
+  },
+  {
+    id: 'stateful-invariant-execution', workstream: 4, title: 'Approved invariants, stateful scenarios, state oracles and sequence shrinking',
+    status: 'unsupported',
+    source: ['scanner/src/posture/logic-claims.js', 'scanner/src/discovery'],
+    entryPoints: [],
+    evidence: [t('scanner/test/logic-claims.test.js')],
+    gap: 'no executable invariant contract, approval state, scenario generator, durable-effect oracle or minimizer exists in the checkout',
+    prd: ['X-401', 'X-403', 'X-404', 'X-405'],
+  },
+  {
+    id: 'egress-policy-redaction-audit', workstream: 5, title: 'Central egress policy, outbound redaction and tamper-evident audit',
+    status: 'implemented',
+    source: ['scanner/src/egress/policy.js', 'scanner/src/egress/redact.js', 'scanner/src/egress/audit.js'],
+    entryPoints: [{ path: 'scanner/src/egress/policy.js', symbol: 'evaluateEgress' }, { path: 'scanner/src/egress/redact.js', symbol: 'redactPayload' }, { path: 'scanner/src/egress/audit.js', symbol: 'recordEgressCall' }],
+    evidence: [t('scanner/test/egress-policy.test.js'), t('scanner/test/egress-redact.test.js'), t('scanner/test/egress-audit.test.js'), t('scanner/test/egress-policy-completeness.test.js')],
+    gap: null,
+    prd: ['CORE-004', 'X-504'],
+  },
+  {
+    id: 'agent-hooks', workstream: 5, title: 'Pre-edit, pre-bash and dispatch hooks',
+    status: 'partial',
+    source: ['hooks/pre-bash-guard.js', 'hooks/pre-edit-bodyguard.js', 'hooks/dispatch-pre-tool.js', 'hooks/hooks.json'],
+    entryPoints: [],
+    evidence: [t('scanner/test/pre-bash-guard.test.js'), t('scanner/test/bodyguard.test.js'), t('scanner/test/dispatch-pre-tool.test.js')],
+    gap: 'hooks explain and advise at the prompt layer; no runner mediates filesystem, command or network access, so a hook response is not an enforcement receipt',
+    prd: ['X-501', 'X-502', 'X-505', 'X-507'],
+  },
+  {
+    id: 'mcp-server', workstream: 2, title: 'MCP server tools (including the write-gated fix tools)',
+    status: 'partial',
+    source: ['scanner/src/mcp/server.js', 'scanner/src/mcp/tools.js', 'scanner/src/mcp/validate.js', 'scanner/src/mcp/audit.js'],
+    entryPoints: [],
+    evidence: [t('scanner/test/mcp.test.js'), t('scanner/test/mcp-audit.test.js'), t('scanner/test/mcp-protocol-smoke.test.js')],
+    gap: 'tool results are not yet emitted as the unified verification record',
+    prd: ['X-206'],
+  },
+  {
+    id: 'model-routing-and-trust', workstream: 6, title: 'Model routing, measured trust, cache economics and provider catalog',
+    status: 'partial',
+    source: ['scanner/src/posture/model-routing.js', 'scanner/src/posture/model-trust.js', 'scanner/src/posture/cache-economics.js', 'scanner/src/posture/provider-catalog.js'],
+    entryPoints: [{ path: 'scanner/src/posture/model-trust.js', symbol: 'createTrustLedger' }, { path: 'scanner/src/posture/model-routing.js', symbol: 'routeModelWithTrust' }],
+    evidence: [t('scanner/test/model-routing.test.js'), t('scanner/test/model-trust.test.js'), t('scanner/test/cache-economics.test.js'), t('scanner/test/providers.test.js'), a('bench/router-replay/baseline.json')],
+    gap: 'trust is a per-key miss-rate ledger; there are no adjudicated task strata, calibrated quality intervals, shadow validation or drift circuit breakers',
+    prd: ['X-601', 'X-603', 'X-604', 'X-605'],
+  },
+  {
+    id: 'fleet-checkpoints', workstream: 7, title: 'Fleet runs and scan checkpoints',
+    status: 'partial',
+    source: ['scanner/src/posture/fleet.js', 'scanner/src/posture/scan-checkpoint.js', 'scripts/fleet.mjs'],
+    entryPoints: [{ path: 'scanner/src/posture/scan-checkpoint.js', symbol: 'openCheckpoint' }],
+    evidence: [t('scanner/test/fleet.test.js'), t('scanner/test/scan-checkpoint.test.js')],
+    gap: 'checkpoints resume a single scan; there are no durable leased work units, dependency-hash invalidation or portfolio budgets',
+    prd: ['X-704', 'X-705', 'X-706'],
+  },
+  {
+    id: 'attestation-and-evidence-bundles', workstream: 7, title: 'Run attestation, signed per-finding evidence bundles, integrity and retention',
+    status: 'partial',
+    source: ['scanner/src/posture/attestation.js', 'scanner/src/posture/evidence-bundle.js', 'scanner/src/posture/integrity.js', 'scanner/src/posture/retention-policy.js'],
+    entryPoints: [{ path: 'scanner/src/posture/evidence-bundle.js', symbol: 'signEvidenceBundle' }, { path: 'scanner/src/posture/attestation.js', symbol: 'computeRunAttestation' }],
+    evidence: [t('scanner/test/attestation.test.js'), t('scanner/test/evidence-bundle.test.js'), t('scanner/test/retention-policy.test.js'), t('scanner/test/verify-attestation-cli.test.js')],
+    gap: 'bundles are per finding with a local signer; there is no release assurance manifest, portable package or explicit trust-root policy',
+    prd: ['X-701', 'X-702', 'X-703', 'CORE-003'],
+  },
+  {
+    id: 'accuracy-scorecard', workstream: 1, title: 'Published accuracy scorecard and corpus replay',
+    status: 'implemented',
+    source: ['scanner/src/posture/accuracy-scorecard.js', 'scripts/scorecard.mjs'],
+    entryPoints: [],
+    evidence: [t('scanner/test/accuracy-scorecard.test.js'), t('scanner/test/scorecard.test.js'), a('docs/scorecard.json')],
+    gap: null,
+    prd: ['QA-004'],
+  },
+  {
+    id: 'independent-accuracy-current-engine', workstream: 1, title: 'Current-engine accuracy on independent real code',
+    status: 'unmeasured',
+    source: ['bench/independent/runner.mjs', 'bench/independent/manifest.json'],
+    entryPoints: [],
+    evidence: [a('docs/scorecard.json'), a('docs/INDEPENDENT_POPULATION_ROOT_CAUSE.md')],
+    gap: 'the recorded independent result belongs to an older engine revision; no current-engine adjudicated measurement exists in the checkout',
+    prd: ['QA-001', 'QA-002', 'QA-003'],
+  },
+  {
+    id: 'loop-controller', workstream: 'foundation', title: 'Supervised background implementation controller (Haskell/Nix profile)',
+    status: 'partial',
+    source: ['scripts/loop-engineering/run.mjs', 'scripts/loop-engineering/profiles/haskell-nix.json'],
+    entryPoints: [],
+    evidence: [t('scripts/loop-engineering/test/loop-manifest.test.js'), t('scripts/loop-engineering/test/loop-watchdog.test.js'), t('scripts/loop-engineering/test/loop-recovery.test.js')],
+    gap: 'only the Haskell/Nix profile exists; the assurance-differentiation profile and its protected acceptance suites are not present',
+    prd: ['LOOP-001', 'LOOP-002', 'LOOP-003'],
+  },
+  {
+    id: 'lineage-graph', workstream: 3, title: 'Data Flow Explorer lineage graph (DataFlowGraph v1)',
+    status: 'implemented',
+    source: ['scanner/src/lineage/graph-builder.js', 'scanner/src/lineage/ids.js', 'scanner/src/lineage/schema.js', 'scanner/src/lineage/dataflow-graph.schema.json'],
+    entryPoints: [{ path: 'scanner/src/lineage/ids.js', symbol: 'graphId' }],
+    evidence: [t('scanner/test/lineage/schema.test.js'), t('scanner/test/lineage/ids.test.js')],
+    gap: null,
+    prd: ['X-301'],
+  },
+]);

package/src/posture/assurance/baseline.js

@@ -0,0 +1,322 @@
+// Baseline capture (CORE-001): what this checkout actually is, before the
+// differentiation work changes it.
+//
+// Principles:
+//   - READ-ONLY. Capture reads source, runs read-only git and version queries, and
+//     returns a manifest. It writes nothing; the CLI writes only to a path that
+//     `assertSafeOutput` accepts, which is never inside an application source root.
+//   - NOTHING IS FABRICATED. Every environmental fact is `{status:'known', value}`
+//     or `{status:'unknown', reason}`. A tool that is missing, a bundle that is
+//     absent, a repository with no HEAD: each is recorded as unknown with the reason.
+//   - EXACT BYTES. Digests are over working-tree bytes, so uncommitted edits move
+//     them, and the dirty path list says which files differ from HEAD.
+//   - EVIDENCE IS BOUND TO WHAT IT COVERS. Each capability records the digest of
+//     every source and evidence file it cites. `evaluateBaseline` compares a fresh
+//     capture to a recorded one and invalidates exactly the capabilities whose cited
+//     files changed; unrelated user changes are kept, listed and never touched.
+//
+// The manifest is not deterministic across machines (it records HEAD, dirty paths
+// and tool versions), so it is generated on demand and not committed.
+
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+import { spawnSync } from 'node:child_process';
+import { hardenGitArgs, hardenGitEnv } from '../../util/git-hardening.js';
+import { STATE_DIR_NAME } from '../state-dir.js';
+import { digestOf, digestOfBytes } from './identity.js';
+import { RECOMMENDATION_MAPPINGS, CAPABILITY_INVENTORY } from './baseline-inventory.js';
+
+export const BASELINE_SCHEMA = 'agentic-security/baseline-manifest';
+export const BASELINE_VERSION = '1.0.0';
+export const CAPABILITY_STATUSES = Object.freeze(['implemented', 'partial', 'unsupported', 'unmeasured']);
+
+// Directories whose contents are application source: capture never writes here.
+export const SOURCE_ROOTS = Object.freeze(['scanner/src', 'scanner/bin', 'scanner/scripts', 'hooks', 'commands', 'agents', 'scripts']);
+// What the source digest covers.
+export const SOURCE_DIGEST_PATHS = Object.freeze(['scanner/src', 'scanner/bin', 'scanner/package.json', 'scanner/package-lock.json']);
+const BUNDLE_PATH = 'scanner/dist/agentic-security.mjs';
+
+const known = (value) => ({ status: 'known', value });
+const unknown = (reason) => ({ status: 'unknown', reason });
+
+function defaultExec(cmd, args, { cwd, timeoutMs = 15_000 } = {}) {
+  const r = spawnSync(cmd, args, { cwd, encoding: 'utf8', timeout: timeoutMs, env: cmd === 'git' ? hardenGitEnv() : process.env, maxBuffer: 64 * 1024 * 1024 });
+  if (r.error) return { status: null, stdout: '', stderr: String(r.error.code || r.error.message) };
+  return { status: r.status, stdout: r.stdout || '', stderr: r.stderr || '' };
+}
+
+function git(runCmd, root, args) {
+  return runCmd('git', hardenGitArgs(args), { cwd: root });
+}
+
+function fileDigest(root, rel) {
+  try {
+    const st = fs.lstatSync(path.join(root, rel));
+    if (!st.isFile()) return null;
+    return digestOfBytes(fs.readFileSync(path.join(root, rel)));
+  } catch { return null; }
+}
+
+function tool(runCmd, root, cmd, args) {
+  const r = runCmd(cmd, args, { cwd: root });
+  if (r.status !== 0 || !r.stdout.trim()) return unknown(`${cmd} ${args.join(' ')} did not report a version${r.stderr ? ` (${String(r.stderr).trim().split('\n')[0]})` : ''}`);
+  return known(r.stdout.trim().split('\n')[0]);
+}
+
+/** Parse `git status --porcelain=v1 -z`. Renames carry two paths; both are reported. */
+export function parsePorcelain(out) {
+  const parts = out.split('\0').filter(Boolean);
+  const entries = [];
+  for (let i = 0; i < parts.length; i++) {
+    const rec = parts[i];
+    const xy = rec.slice(0, 2); const p = rec.slice(3);
+    if (xy[0] === 'R' || xy[0] === 'C') { entries.push({ path: p, xy }); i++; if (parts[i]) entries.push({ path: parts[i], xy: 'R-from' }); continue; }
+    entries.push({ path: p, xy });
+  }
+  return entries;
+}
+
+function classify(xy) {
+  if (xy === '??') return 'untracked';
+  if (xy.includes('D')) return 'deleted';
+  if (xy === 'R-from') return 'renamed-from';
+  if (xy[0] !== ' ' && xy[1] !== ' ') return 'staged-and-modified';
+  if (xy[0] !== ' ') return 'staged';
+  return 'modified';
+}
+
+function collectSourceFiles(runCmd, root) {
+  const r = git(runCmd, root, ['ls-files', '-z', '--cached', '--others', '--exclude-standard', '--', ...SOURCE_DIGEST_PATHS]);
+  if (r.status !== 0) return null;
+  return [...new Set(r.stdout.split('\0').filter(Boolean))].sort();
+}
+
+/**
+ * Capture the baseline. `exec` and `now` are injectable so tests can prove the
+ * unknown paths and stay clock-free; `inventory`/`mappings` default to the real ones.
+ */
+export function captureBaseline({
+  root, exec: runCmd = defaultExec, now = () => new Date().toISOString(),
+  inventory = CAPABILITY_INVENTORY, mappings = RECOMMENDATION_MAPPINGS,
+} = {}) {
+  if (!root) throw new Error('captureBaseline needs a root');
+  const problems = [];
+  const abs = path.resolve(root);
+
+  // ---- git state
+  const headR = git(runCmd, abs, ['rev-parse', 'HEAD']);
+  const head = headR.status === 0 && /^[0-9a-f]{40,64}$/.test(headR.stdout.trim()) ? known(headR.stdout.trim()) : unknown('no git HEAD could be resolved');
+  const branchR = git(runCmd, abs, ['rev-parse', '--abbrev-ref', 'HEAD']);
+  const branch = branchR.status === 0 ? known(branchR.stdout.trim()) : unknown('branch could not be resolved');
+  const statusR = git(runCmd, abs, ['status', '--porcelain=v1', '-z', '--untracked-files=all']);
+  let dirty;
+  if (statusR.status !== 0) dirty = unknown('git status failed; the worktree state is not known');
+  else {
+    dirty = known(parsePorcelain(statusR.stdout).map(e => ({ path: e.path, change: classify(e.xy), digest: fileDigest(abs, e.path) })).sort((x, y) => x.path.localeCompare(y.path)));
+  }
+
+  // ---- digests
+  const files = collectSourceFiles(runCmd, abs);
+  let sourceDigest;
+  if (!files) sourceDigest = unknown('source file list unavailable (git ls-files failed)');
+  else {
+    const lines = [];
+    for (const f of files) { const d = fileDigest(abs, f); if (d) lines.push(`${f}\0${d}`); }
+    sourceDigest = known({ digest: digestOf(lines), fileCount: lines.length, covers: [...SOURCE_DIGEST_PATHS] });
+  }
+  const bundleBytes = fileDigest(abs, BUNDLE_PATH);
+  let bundle;
+  if (!bundleBytes) bundle = unknown(`${BUNDLE_PATH} is not present in this checkout`);
+  else {
+    let sidecar = null;
+    try { sidecar = fs.readFileSync(path.join(abs, `${BUNDLE_PATH}.sha256`), 'utf8').trim().split(/\s+/)[0] || null; } catch { /* no sidecar */ }
+    bundle = known({ path: BUNDLE_PATH, digest: bundleBytes, sidecar: sidecar ? `sha256:${sidecar}` : null, sidecarMatches: sidecar ? `sha256:${sidecar}` === bundleBytes : null });
+  }
+
+  // ---- versions
+  let pkg = null;
+  try { pkg = JSON.parse(fs.readFileSync(path.join(abs, 'scanner/package.json'), 'utf8')); } catch { /* reported below */ }
+  const versions = {
+    node: known(process.version),
+    platform: known(`${process.platform}-${process.arch}`),
+    scanner: pkg?.version ? known(pkg.version) : unknown('scanner/package.json has no readable version'),
+    npm: tool(runCmd, abs, 'npm', ['--version']),
+    git: tool(runCmd, abs, 'git', ['--version']),
+    python3: tool(runCmd, abs, 'python3', ['--version']),
+  };
+
+  // ---- feature entry points that exist now
+  const entryPoints = {
+    packageBin: pkg?.bin ? known(pkg.bin) : unknown('no bin map in scanner/package.json'),
+    npmScripts: pkg?.scripts ? known(Object.keys(pkg.scripts).sort()) : unknown('no scripts in scanner/package.json'),
+    commands: listDir(abs, 'commands', f => f.endsWith('.md')),
+    hooks: listDir(abs, 'hooks', f => f.endsWith('.js') && !f.endsWith('.test.js')),
+  };
+
+  // ---- seven recommendation mappings, each extension point verified
+  const recMappings = mappings.map(m => {
+    const ext = m.extensionPoints.map(p => ({ path: p, exists: exists(abs, p) }));
+    for (const e of ext) if (!e.exists) problems.push(`mapping ${m.n}: extension point '${e.path}' does not exist`);
+    return { n: m.n, title: m.title, priority: m.priority, slice: m.slice, extensionPoints: ext };
+  });
+
+  // ---- capability inventory
+  const capabilities = inventory.map(c => {
+    const sourceDigests = {}; const evidenceDigests = {};
+    for (const p of c.source) sourceDigests[p] = pathDigest(abs, p);
+    for (const e of c.evidence) evidenceDigests[e.path] = pathDigest(abs, e.path);
+    const missing = [...Object.entries(sourceDigests), ...Object.entries(evidenceDigests)].filter(([, d]) => d === null).map(([p]) => p);
+    for (const p of missing) problems.push(`capability '${c.id}': path '${p}' does not exist`);
+    const symbols = c.entryPoints.map(ep => ({ ...ep, exported: symbolExported(abs, ep.path, ep.symbol) }));
+    for (const s of symbols) if (!s.exported) problems.push(`capability '${c.id}': '${s.symbol}' is not exported by ${s.path}`);
+    if (!CAPABILITY_STATUSES.includes(c.status)) problems.push(`capability '${c.id}': status '${c.status}' is not one of ${CAPABILITY_STATUSES.join(', ')}`);
+    if (c.status === 'implemented' && c.gap) problems.push(`capability '${c.id}': 'implemented' must not carry a gap`);
+    if (c.status !== 'implemented' && !c.gap) problems.push(`capability '${c.id}': '${c.status}' must say what is missing`);
+    if (!c.source.length) problems.push(`capability '${c.id}': no source path`);
+    if (!c.evidence.length) problems.push(`capability '${c.id}': no test or artifact`);
+    return {
+      id: c.id, workstream: c.workstream, title: c.title, status: c.status, gap: c.gap, prd: c.prd,
+      source: c.source, evidence: c.evidence, entryPoints: symbols,
+      pathsMissing: missing, sourceDigests, evidenceDigests,
+    };
+  });
+
+  const manifest = {
+    schema: BASELINE_SCHEMA, schemaVersion: BASELINE_VERSION,
+    repository: { head, branch, dirtyPaths: dirty },
+    digests: { source: sourceDigest, bundle },
+    versions, entryPoints,
+    recommendationMappings: recMappings,
+    capabilities,
+    problems,
+  };
+  manifest.baselineId = digestOf(manifest);
+  // The capture time is real but is not part of the identity.
+  manifest.capturedAt = now();
+  return manifest;
+}
+
+function exists(root, rel) { try { fs.accessSync(path.join(root, rel)); return true; } catch { return false; } }
+
+function listDir(root, rel, keep) {
+  try { return known(fs.readdirSync(path.join(root, rel)).filter(keep).sort()); } catch { return unknown(`${rel}/ is not readable`); }
+}
+
+/** Digest of a file, or of a directory as the digest of its files' digests; null when the path does not exist. */
+function pathDigest(root, rel) {
+  const p = path.join(root, rel);
+  let st;
+  try { st = fs.lstatSync(p); } catch { return null; }
+  if (st.isFile()) return digestOfBytes(fs.readFileSync(p));
+  if (!st.isDirectory()) return null;
+  const lines = [];
+  const walk = (d, prefix) => {
+    for (const e of fs.readdirSync(d, { withFileTypes: true }).sort((x, y) => x.name.localeCompare(y.name))) {
+      if (e.name === STATE_DIR_NAME || e.name === 'node_modules') continue;
+      const full = path.join(d, e.name);
+      if (e.isDirectory()) walk(full, `${prefix}${e.name}/`);
+      else if (e.isFile()) lines.push(`${prefix}${e.name}\0${digestOfBytes(fs.readFileSync(full))}`);
+    }
+  };
+  walk(p, '');
+  return digestOf(lines);
+}
+
+function symbolExported(root, rel, symbol) {
+  try {
+    const text = fs.readFileSync(path.join(root, rel), 'utf8');
+    return new RegExp(`^\\s*export\\s+(?:async\\s+)?(?:function\\*?|const|class)\\s+${symbol}\\b`, 'm').test(text)
+      || new RegExp(`^\\s*export\\s*\\{[^}]*\\b${symbol}\\b`, 'm').test(text);
+  } catch { return false; }
+}
+
+/**
+ * Compare a recorded baseline with a fresh capture of the same checkout.
+ *
+ * - A capability is `invalidated` when any source or evidence file it cites
+ *   changed or disappeared; it lists the changed paths. Otherwise it stays `valid`.
+ * - Dirty paths are classified: `retained` (already dirty at baseline, same bytes),
+ *   `changedSince` (dirty at baseline, bytes now different), `introduced` (newly
+ *   dirty), `resolved` (was dirty, now clean). Each is split into `applicable`
+ *   (cited by some capability) and `unrelated`. Unrelated changes never invalidate
+ *   anything and are always disclosed.
+ */
+export function evaluateBaseline(recorded, current) {
+  const capabilities = recorded.capabilities.map(rc => {
+    const cc = current.capabilities.find(x => x.id === rc.id);
+    const changed = [];
+    if (!cc) changed.push('(capability no longer inventoried)');
+    else {
+      for (const [p, d] of Object.entries(rc.sourceDigests)) if (cc.sourceDigests[p] !== d) changed.push(p);
+      for (const [p, d] of Object.entries(rc.evidenceDigests)) if (cc.evidenceDigests[p] !== d) changed.push(p);
+    }
+    return { id: rc.id, status: rc.status, validity: changed.length ? 'invalidated' : 'valid', changedPaths: changed };
+  });
+
+  const cited = new Set();
+  const citedDirs = [];
+  for (const c of recorded.capabilities) for (const p of [...c.source, ...c.evidence.map(e => e.path)]) { cited.add(p); citedDirs.push(p.replace(/\/$/, '')); }
+  const isApplicable = (p) => citedDirs.some(c => p === c || p.startsWith(`${c}/`));
+
+  const rd = recorded.repository.dirtyPaths; const cd = current.repository.dirtyPaths;
+  const userChanges = { comparable: rd.status === 'known' && cd.status === 'known', retained: [], changedSince: [], introduced: [], resolved: [] };
+  if (userChanges.comparable) {
+    const before = new Map(rd.value.map(e => [e.path, e])); const after = new Map(cd.value.map(e => [e.path, e]));
+    const tag = (e, kind) => ({ path: e.path, change: e.change, scope: isApplicable(e.path) ? 'applicable' : 'unrelated', kind });
+    for (const [p, e] of after) {
+      const b = before.get(p);
+      if (!b) userChanges.introduced.push(tag(e, 'introduced'));
+      else if (b.digest === e.digest) userChanges.retained.push(tag(e, 'retained'));
+      else userChanges.changedSince.push(tag(e, 'changedSince'));
+    }
+    for (const [p, e] of before) if (!after.has(p)) userChanges.resolved.push(tag(e, 'resolved'));
+  }
+
+  const same = (a, b) => JSON.stringify(a) === JSON.stringify(b);
+  return {
+    baselineId: recorded.baselineId,
+    headChanged: !same(recorded.repository.head, current.repository.head),
+    bundleChanged: !same(recorded.digests.bundle, current.digests.bundle),
+    sourceChanged: !same(recorded.digests.source, current.digests.source),
+    capabilities,
+    invalidated: capabilities.filter(c => c.validity === 'invalidated').map(c => c.id),
+    valid: capabilities.filter(c => c.validity === 'valid').map(c => c.id),
+    userChanges,
+  };
+}
+
+/** A manifest is only as trustworthy as its own shape: check statuses, unknown-marking and the id. */
+export function validateBaseline(m) {
+  const errors = [];
+  if (!m || typeof m !== 'object') return { ok: false, errors: ['not an object'] };
+  if (m.schema !== BASELINE_SCHEMA) errors.push('schema mismatch');
+  if (!/^1\./.test(String(m.schemaVersion))) errors.push('unsupported schemaVersion');
+  const check = (name, v) => {
+    if (!v || (v.status !== 'known' && v.status !== 'unknown')) errors.push(`${name}: not a known/unknown fact`);
+    else if (v.status === 'unknown' && (!v.reason || 'value' in v)) errors.push(`${name}: an unknown fact needs a reason and no value`);
+    else if (v.status === 'known' && !('value' in v)) errors.push(`${name}: a known fact needs a value`);
+  };
+  check('head', m.repository?.head); check('branch', m.repository?.branch); check('dirtyPaths', m.repository?.dirtyPaths);
+  check('digests.source', m.digests?.source); check('digests.bundle', m.digests?.bundle);
+  for (const [k, v] of Object.entries(m.versions || {})) check(`versions.${k}`, v);
+  if (!Array.isArray(m.recommendationMappings) || m.recommendationMappings.length !== 7) errors.push('exactly seven recommendation mappings are required');
+  for (const c of m.capabilities || []) if (!CAPABILITY_STATUSES.includes(c.status)) errors.push(`capability ${c.id}: bad status`);
+  const { baselineId, capturedAt, ...rest } = m;
+  if (baselineId !== digestOf(rest)) errors.push('baselineId does not match the manifest content');
+  return { ok: errors.length === 0, errors };
+}
+
+/**
+ * Where a baseline may be written. Never inside an application source root, and
+ * never over a file git tracks (which would change application source).
+ */
+export function assertSafeOutput(root, outPath, runCmd = defaultExec) {
+  const abs = path.resolve(root); const out = path.resolve(outPath);
+  const rel = path.relative(abs, out);
+  if (rel.startsWith('..') || path.isAbsolute(rel)) return { ok: true, reason: 'outside the repository' };
+  const inSource = SOURCE_ROOTS.some(r => rel === r || rel.startsWith(`${r}${path.sep}`));
+  if (inSource) return { ok: false, reason: `'${rel}' is inside an application source root` };
+  const tracked = git(runCmd, abs, ['ls-files', '--error-unmatch', '--', rel]);
+  if (tracked.status === 0) return { ok: false, reason: `'${rel}' is tracked by git; refusing to overwrite application files` };
+  return { ok: true, reason: 'untracked path outside the source roots' };
+}