@blamejs/exceptd-skills 0.19.33 → 0.19.34

package/lib/playbook-runner.js

@@ -1,46 +1,9 @@
 'use strict';
 
 /**
- * Playbook runner — executes the seven-phase investigation contract defined in
- * lib/schemas/playbook.schema.json:
- *
- *   1. govern    exceptd. Loads GRC context: jurisdiction obligations, theater
- *                fingerprints, framework gaps, skills to preload. Sets the
- *                compliance lens before any investigation runs.
- *   2. direct    exceptd. Scopes the investigation: threat context with current
- *                CVE/TTP citations, RWEP thresholds, framework lag declaration,
- *                skill chain, token budget.
- *   3. look      host AI. Collects typed artifacts (logs/files/processes/
- *                network/etc.) per artifact spec, with air-gap fallbacks.
- *   4. detect    host AI. Evaluates artifacts against typed indicators, applies
- *                false-positive profile, classifies as detected | inconclusive
- *                | not_detected.
- *   5. analyze   exceptd. Computes RWEP from rwep_inputs, scores blast radius,
- *                runs compliance_theater_check, generates framework_gap_mapping
- *                entries, fires escalation_criteria.
- *   6. validate  exceptd. Picks remediation_path by priority + preconditions,
- *                emits validation_tests, renders residual_risk_statement, lists
- *                evidence_requirements, computes regression schedule.
- *   7. close     exceptd. Closes the GRC loop: assembles evidence_package
- *                (signed by default), drafts learning_loop lesson, computes
- *                notification_actions deadlines from govern.jurisdiction_obligations
- *                clock_starts + window_hours, evaluates exception_generation
- *                trigger and renders auditor-ready language, finalizes
- *                regression_schedule.next_run.
- *
- * Currency gate: _meta.threat_currency_score < 50 hard-blocks execution unless
- * the caller passes { forceStale: true }. Below 70 warns. The schema declares
- * the score; the runner enforces.
- *
- * Preconditions: each _meta.preconditions entry has on_fail = halt|warn|skip_phase.
- * Engine evaluates the (host AI-supplied) check value and reacts accordingly.
- *
- * Mutex: an in-process Set tracks active playbook runs. Engine refuses to start
- * a playbook whose _meta.mutex intersects active runs.
- *
- * feeds_into: close() returns a list of downstream playbook IDs whose
- * conditions are satisfied by this run's finding — the agent decides whether
- * to chain into them.
+ * Playbook runner — executes the seven-phase contract declared in
+ * lib/schemas/playbook.schema.json. The engine owns govern, direct, analyze,
+ * validate and close; the host AI owns look and detect.
  */
 
 const fs = require('fs');
@@ -51,15 +14,8 @@ const scoring = require('./scoring');
 const { assertIdComponent } = require('./id-validation');
 const codepointClass = require('../vendor/blamejs/codepoint-class.js');
 
-// cross-ref-api wraps catalog reads. If cve-catalog.json is corrupt
-// JSON, cross-ref-api's loadCatalog (post-v0.12.14) catches the parse
-// failure, returns an empty stub, and accumulates the error in
-// getLoadErrors(). run() probes for accumulated load errors and returns
-// a structured `blocked_by:'catalog_corrupt'` rather than letting analyze
-// silently operate against an empty catalog. Note: the call to
-// xref.byCve below force-touches the catalog so the load error surfaces
-// at module load (it's lazy otherwise), which gives run() a deterministic
-// signal regardless of submission shape.
+// cross-ref-api swallows a corrupt cve-catalog.json into an empty stub and
+// records the failure in getLoadErrors(), which run() probes before analyze.
 let xref;
 let _xrefLoadError = null;
 let _xrefProbed = false;
@@ -74,13 +30,7 @@ try {
   _xrefProbed = true; // require itself failed; nothing left to probe
 }
 
-// Probe the catalog (parse it, surface any load error) LAZILY on first need
-// rather than at module load. The probe parses the ~2.6MB CVE catalog (~8.5ms);
-// doing it eagerly charged that to every cheap verb (brief/ask/lint/
-// discover) that never analyzes. run() calls this before the analyze path, so
-// a corrupt catalog still surfaces as blocked_by:'catalog_corrupt' before
-// analyze — just not on verbs that don't touch the catalog. Memoized: probes
-// at most once per process.
+// Lazy and memoized: only a verb that analyzes pays the ~2.6MB catalog parse.
 function getXrefLoadError() {
   if (_xrefProbed) return _xrefLoadError;
   _xrefProbed = true;
@@ -101,24 +51,13 @@ function getXrefLoadError() {
 const ROOT = path.join(__dirname, '..');
 const PLAYBOOK_DIR = process.env.EXCEPTD_PLAYBOOK_DIR || path.join(ROOT, 'data', 'playbooks');
 
-// In-process mutex tracker. Survives only the current Node process.
-// Persistent cross-process coordination is out of scope — that's for the GRC
-// platform integration, not the runner.
+// In-process mutex tracker; survives only the current Node process.
 const _activeRuns = new Set();
 
-// Bounded push into a runtime_errors array with per-kind caps, optional
-// per-kind dedupe, and a total cap. A long-running detect/analyze loop that
-// rejects a malformed catalog entry on every iteration would otherwise let
-// runtime_errors grow unbounded and balloon the bundle output. When the cap
-// fires the helper records a `_truncated` sentinel so downstream consumers
-// see the drop without needing to compare cardinalities.
-//
-//   opts.cap        per-kind cap (default 100)
-//   opts.totalCap   total array cap (default 1000)
-//   opts.dedupeKey  optional fn(entry) returning a string key. When supplied,
-//                   a push with the same (kind, dedupeKey) tuple is skipped.
-//
-// Returns true if the entry was pushed, false otherwise (capped or deduped).
+// Bounded push into a runtime_errors array: opts.cap (100) per kind,
+// opts.totalCap (1000) overall, opts.dedupeKey(entry) collapsing same-(kind,
+// key) pushes. A capped push records a `_truncated` sentinel instead, and
+// returns false — true means the entry was pushed.
 function pushRunError(arr, entry, opts) {
   if (!Array.isArray(arr) || !entry || typeof entry !== 'object') return false;
   opts = opts || {};
@@ -149,10 +88,7 @@ function pushRunError(arr, entry, opts) {
   return true;
 }
 
-// Unwrap a legacy `{ _regex_eval_error: { source, expr, message } }` record
-// into the flat fields pushRunError dedupes on. Used by evalCondition()'s
-// regex-failure path so per-(source, expr) duplicates collapse to one entry
-// plus a `_truncated` sentinel when the cap fires.
+// Flatten a `_regex_eval_error` record into the fields pushRunError dedupes on.
 function _regexErrorPayload(rec) {
   if (rec && typeof rec === 'object' && rec._regex_eval_error) {
     const { source, expr, message } = rec._regex_eval_error;
@@ -161,8 +97,6 @@ function _regexErrorPayload(rec) {
   return { _regex_eval_error: rec };
 }
 
-// --- catalog access ---
-
 function listPlaybooks() {
   if (!fs.existsSync(PLAYBOOK_DIR)) return [];
   return fs.readdirSync(PLAYBOOK_DIR)
@@ -171,26 +105,20 @@ function listPlaybooks() {
 }
 
 function loadPlaybook(playbookId) {
-  // Traversal defense co-located with the path.join — every caller gets it,
-  // not just the CLI dispatcher's pre-validation wrapper.
+  // Traversal defense sits with the path.join so every caller gets it, not
+  // only the CLI dispatcher.
   assertIdComponent(playbookId, 'playbook');
   const p = path.join(PLAYBOOK_DIR, `${playbookId}.json`);
   if (!fs.existsSync(p)) throw new Error(`Playbook not found: ${playbookId} (expected ${p})`);
   return JSON.parse(fs.readFileSync(p, 'utf8'));
 }
 
-// Per-run playbook cache. Each phase function reads runOpts._playbookCache
-// before falling back to loadPlaybook(). run() sets _playbookCache once at
-// entry so seven phases share one disk read + JSON parse instead of seven.
-
 function findDirective(playbook, directiveId) {
   const d = playbook.directives.find(x => x.id === directiveId);
   if (!d) throw new Error(`Directive not found: ${directiveId} in playbook ${playbook._meta.id}`);
   return d;
 }
 
-// --- phase-resolution: merge playbook.phases with directive.phase_overrides ---
-
 function resolvedPhase(playbook, directiveId, phaseName) {
   const base = playbook.phases[phaseName] || {};
   const directive = playbook.directives.find(x => x.id === directiveId);
@@ -204,55 +132,28 @@ function deepMerge(a, b) {
   if (typeof b !== 'object' || Array.isArray(b)) return b;
   const out = { ...a };
   for (const [k, v] of Object.entries(b)) {
-    // Skip prototype-polluting keys. phase_overrides come from the Ed25519-
-    // signed catalog today, but deepMerge is an exported utility (_deepMerge)
-    // and must never rebind a prototype if reused with parsed/operator input —
-    // same guard as the precondition_checks merge below. `out[k]=` on
-    // k='__proto__' would invoke the prototype-rebinding setter.
+    // `out[k]=` on k='__proto__' invokes the prototype-rebinding setter, and
+    // deepMerge is exported (_deepMerge) so it may see parsed operator input.
     if (k === '__proto__' || k === 'constructor' || k === 'prototype') continue;
     out[k] = (k in out) ? deepMerge(out[k], v) : v;
   }
   return out;
 }
 
-// --- pre-flight: currency + preconditions + mutex ---
-
 /**
- * Pre-flight gate. Three concerns:
- *
- *   1. Currency. threat_currency_score < 50 hard-blocks unless
- *      runOpts.forceStale=true. < 70 emits a warning issue.
- *   2. Preconditions. _meta.preconditions[] entries with on_fail in
- *      {halt, warn, skip_phase} are evaluated against
- *      runOpts.precondition_checks[id]. Missing values → precondition_unverified
- *      issue (plus halt if on_fail=halt). False values → precondition_warn or
- *      precondition_skip per on_fail.
- *   3. Mutex. _meta.mutex[] intersect with the in-process active runs set
- *      AND with the filesystem lockfile dir blocks the run.
- *
- * When runOpts.strictPreconditions === true, warn-level outcomes
- * (precondition_warn, precondition_unverified with on_fail=warn or
- * skip_phase) are ESCALATED to halts. The function returns ok:false
- * with blocked_by='precondition' and an issues array containing
- * precondition_halt entries. Callers wanting "CI gate: any unverified
- * precondition is a failure" pass strictPreconditions=true.
- *
- * When a precondition with on_fail='skip_phase' fails, the issue carries
- * skip_phase: 'detect' (default) so run() can route to a skipped-phase
- * placeholder rather than executing detect against a missing
- * prerequisite.
+ * Pre-flight gate over currency, preconditions and mutex.
+ * runOpts.strictPreconditions escalates every warn-level precondition outcome
+ * to a halt; an on_fail='skip_phase' failure instead emits an issue carrying
+ * skip_phase (default 'detect'), which run() routes to a skipped placeholder.
  */
 function preflight(playbook, runOpts = {}) {
   const issues = [];
   const meta = playbook._meta;
   const strict = runOpts.strictPreconditions === true;
 
-  // 1. Currency gate
   const score = meta.threat_currency_score;
-  // A non-numeric score (absent / null / NaN from a malformed _meta) must HARD
-  // BLOCK, not slip through: `undefined < 50` is false, which would silently
-  // bypass the staleness gate on exactly the playbooks whose currency metadata
-  // is broken. Treat "no usable score" as the most-stale state.
+  // No usable score is the most-stale state: `undefined < 50` is false, which
+  // would bypass the gate on exactly the broken metadata.
   const scoreUsable = typeof score === 'number' && !Number.isNaN(score);
   if ((!scoreUsable || score < 50) && !runOpts.forceStale) {
     return {
@@ -268,14 +169,11 @@ function preflight(playbook, runOpts = {}) {
     issues.push({ kind: 'currency_warn', message: `threat_currency_score = ${score} (< 70). Threat model is stale — recommend running the skill-update-loop before relying on findings.` });
   }
 
-  // 2. Preconditions
   for (const pc of meta.preconditions || []) {
     const submitted = runOpts.precondition_checks?.[pc.id];
     if (submitted === undefined) {
       const submission_hint = `Submit precondition_checks in your evidence JSON, e.g. { "precondition_checks": { "${pc.id}": true } }. Pass via --evidence <file.json> or pipe to stdin with --evidence -. The runner lifts precondition_checks into runOpts before the gate evaluates.`;
       if (strict) {
-        // strictPreconditions promotes unverified to halt regardless of
-        // declared on_fail.
         issues.push({ kind: 'precondition_halt', id: pc.id, check: pc.check, on_fail: pc.on_fail, submission_hint, escalated_from: 'precondition_unverified' });
         return {
           ok: false,
@@ -303,15 +201,13 @@ function preflight(playbook, runOpts = {}) {
           ok: false,
           blocked_by: 'precondition',
           reason: `Precondition ${pc.id} failed: ${pc.description}`,
-          // Explicit-false halts carry a specific remediation so the renderer
-          // prefers it over the generic platform-gate hint — an intent/ownership
-          // gate (e.g. operator-owns-ci-fleet) is not a platform mismatch.
+          // Its own remediation, so the renderer prefers it to the generic
+          // platform-gate hint: an ownership gate is not a platform mismatch.
           remediation: `Precondition ${pc.id} was submitted as false: ${pc.description} Attest it as true and re-run — submit precondition_checks {"${pc.id}": true} in your evidence JSON, or pass the owning collector's attestation flag at collect time (for example: collect cicd-pipeline-compromise --attest-ownership).`,
           issues
         };
       }
       if (strict) {
-        // Warn-level + skip_phase outcomes escalate to halt under strict.
         issues.push({ kind: 'precondition_halt', id: pc.id, message: pc.description, escalated_from: pc.on_fail === 'skip_phase' ? 'precondition_skip' : 'precondition_warn' });
         return {
           ok: false,
@@ -321,10 +217,6 @@ function preflight(playbook, runOpts = {}) {
         };
       }
       if (pc.on_fail === 'skip_phase') {
-        // Emit a skip_phase field so run() can route to a skipped-phase
-        // placeholder. Default target phase is 'detect' (the most common
-        // skip target — preconditions typically gate host-side detection).
-        // Playbooks may override via pc.skip_phase.
         issues.push({ kind: 'precondition_skip', id: pc.id, message: pc.description, skip_phase: pc.skip_phase || 'detect' });
       } else {
         issues.push({ kind: 'precondition_warn', id: pc.id, message: pc.description });
@@ -332,17 +224,14 @@ function preflight(playbook, runOpts = {}) {
     }
   }
 
-  // 3. Mutex — both intra-process (in-memory Set) AND cross-process
-  // (filesystem lockfile under .exceptd/locks/<playbook>.lock). v0.11.0 only
-  // enforced intra-process; v0.11.1 adds cross-process so two parallel CLI
-  // invocations of mutex-conflicting playbooks correctly race-detect.
+  // Both the in-process Set and the lockfile, so two parallel CLI invocations
+  // of conflicting playbooks race-detect.
   for (const conflictId of meta.mutex || []) {
     if (_activeRuns.has(conflictId)) {
       return { ok: false, blocked_by: 'mutex', reason: `Mutex conflict (intra-process): playbook ${conflictId} is currently active and listed in this playbook's mutex set.`, issues };
     }
     const lockPath = lockFilePath(conflictId);
     if (lockPath && fs.existsSync(lockPath)) {
-      // Stale-lock detection: if the recorded PID is dead, ignore the lock.
       try {
         const lock = JSON.parse(fs.readFileSync(lockPath, 'utf8'));
         if (lock.pid && !pidAlive(lock.pid)) {
@@ -364,27 +253,10 @@ function preflight(playbook, runOpts = {}) {
   return { ok: true, issues };
 }
 
-// lockDir lives at a stable per-user path so two CLI invocations from
-// different working directories still share lock state for cross-process
-// mutex enforcement. A process.cwd()-relative dir would let invocations
-// from /tmp and from /home/user/project simultaneously each see an empty
-// locks dir and both run unchallenged.
-//
-// Resolution order (most-specific first):
-//   1. EXCEPTD_LOCK_DIR        explicit container/CI override
-//   2. EXCEPTD_HOME || ~/.exceptd  + /locks/<platform>   per-user default
-//   3. os.tmpdir()/exceptd-locks-<platform>              last-resort fallback
-//      when the per-user home is non-writable (read-only home, restricted
-//      sandbox/CI runner).
-//
-// The per-user home (mirroring the orchestrator's watch.lock + attestation
-// roots) is both the safer location — a per-user dir is not the
-// world-writable shared OS tempdir a preplant/symlink attack targets — and
-// the better fit for lockDir's stated goal: ~/.exceptd is per-user-stable
-// across working directories, whereas the shared tmpdir is the weaker
-// choice. The path keys on os.platform() so Windows/macOS/Linux locks live
-// under separate directories (avoids cross-platform stale-PID confusion when
-// a host is shared across OSes via networked FS).
+// EXCEPTD_LOCK_DIR, then (EXCEPTD_HOME || ~/.exceptd)/locks/<platform>, then
+// os.tmpdir() when the home is non-writable. The path must not depend on the
+// working directory, or two invocations see different lock sets and both run
+// unchallenged. The platform segment separates PIDs on a shared networked FS.
 function resolveLockDir() {
   if (process.env.EXCEPTD_LOCK_DIR) return process.env.EXCEPTD_LOCK_DIR;
   const home = process.env.EXCEPTD_HOME || (os.homedir() && path.join(os.homedir(), '.exceptd'));
@@ -392,10 +264,8 @@ function resolveLockDir() {
     const dir = path.join(home, 'locks', process.platform);
     try {
       fs.mkdirSync(dir, { recursive: true, mode: 0o700 });
-      // Probe writability with a marker; remove on success. A home that
-      // mkdirs but can't be written (read-only mount, restrictive ACL) must
-      // fall through to the tmpdir fallback rather than silently no-op every
-      // lock write.
+      // A home that mkdirs but cannot be written must fall through to tmpdir
+      // rather than no-op every lock write.
       const probe = path.join(dir, `.write-probe-${process.pid}`);
       fs.writeFileSync(probe, '');
       fs.unlinkSync(probe);
@@ -407,9 +277,7 @@ function resolveLockDir() {
 
 function lockDir() {
   const dir = resolveLockDir();
-  // Owner-only (0700): the mutex lock files inside use O_EXCL ('wx'), but
-  // tightening the parent directory keeps another local user from listing or
-  // tampering with this user's lock set.
+  // Owner-only: another local user must not list or tamper with this lock set.
   try { fs.mkdirSync(dir, { recursive: true, mode: 0o700 }); } catch { /* exists / EACCES — non-fatal */ }
   return dir;
 }
@@ -419,24 +287,13 @@ function lockFilePath(playbookId) {
   catch { return null; }
 }
 
-// Same-PID stale-lockfile reclaim threshold. A same-process orphan (e.g.
-// an earlier run() that crashed without unlinking, or a try/catch that
-// swallowed the release) older than this is presumed dead and reclaimed.
-// 30s mirrors lib/refresh-external.js and lib/prefetch.js; long enough
-// that no legitimate playbook hold reaches it (govern/look/run phases
-// complete well inside one second per playbook), short enough that a
-// wedged process recovers within one CI step rather than the rest of its
-// lifetime.
+// Same-PID stale-lockfile threshold, matching lib/refresh-external.js and
+// lib/prefetch.js. No legitimate playbook hold reaches 30s.
 const STALE_LOCK_MS = 30_000;
 
-// Create the mutex lock file with an exclusive, owner-only descriptor
-// (O_CREAT | O_EXCL | 0o600 via openSync 'wx'). The lock-file NAME is
-// deliberately predictable — it IS the cross-process mutex, so every contender
-// must agree on it; security comes from the exclusive create (a preplanted file
-// or symlink makes the open throw EEXIST/EPERM, never a silent follow), the
-// 0o700 lock directory, and the 0o600 mode — written through openSync so the
-// secure-create primitive is explicit rather than a bare writeFileSync. Throws
-// EEXIST when the lock is already held, which every caller already handles.
+// Exclusive owner-only create ('wx', 0o600). The file NAME is predictable by
+// design — it IS the mutex — and safety comes from the exclusive create, which
+// throws EEXIST/EPERM on a preplanted file or symlink rather than following it.
 function writeLockFile(p, playbookId) {
   const fd = fs.openSync(p, 'wx', 0o600);
   try {
@@ -454,14 +311,9 @@ function acquireLock(playbookId) {
     writePayload();
     return p;
   } catch (e) {
-    // Stale-PID reclaim. Without it, a process that crashed mid-run
-    // leaves its lockfile behind and every subsequent invocation runs
-    // UNLOCKED. Mirror withCatalogLock's pattern: parse the recorded pid,
-    // probe with `process.kill(pid, 0)`. ESRCH means the holder is dead —
-    // unlink and retry once. EPERM (alive, different user) or any other
-    // condition: leave the lock alone and return null with a diagnostic so
-    // the caller knows acquisition failed because the lock is genuinely
-    // held (not because the FS is broken or the playbook id is malformed).
+    // Stale-PID reclaim: without it a crashed process's lockfile leaves every
+    // later invocation running UNLOCKED. ESRCH means dead; EPERM means alive
+    // under another user, and the lock stands.
     if (e && (e.code === 'EEXIST' || e.code === 'EPERM')) {
       try {
         const raw = fs.readFileSync(p, 'utf8');
@@ -475,15 +327,9 @@ function acquireLock(playbookId) {
           try { fs.unlinkSync(p); } catch {}
           try { writePayload(); return p; } catch { /* fall through */ }
         }
-        // Same-PID stale-lockfile reclaim. If the recorded pid is ours,
-        // the only way to escape an orphaned same-process lockfile is by
-        // mtime. Do NOT blindly reclaim same-PID — legitimate reentrancy
-        // (e.g. nested run() within one process) must still return null
-        // so the caller knows the lock is held. A fresh same-PID lockfile
-        // is reentrancy; one older than STALE_LOCK_MS is an orphan from
-        // a crashed prior hold (or a try/catch that swallowed the release)
-        // and must be reclaimed — otherwise the process can never acquire
-        // this lock again for the rest of its lifetime.
+        // Same-PID reclaim goes by mtime: a fresh lockfile is legitimate
+        // reentrancy and stays held, while an older one is an orphan that
+        // would deny this process the lock for the rest of its lifetime.
         if (Number.isInteger(pid) && pid === process.pid) {
           try {
             const stat = fs.statSync(p);
@@ -495,19 +341,13 @@ function acquireLock(playbookId) {
         }
       } catch { /* unreadable lockfile — treat as held by a live process */ }
     }
-    // Lock genuinely held (or filesystem error). Returning null keeps
-    // back-compat with existing call sites that test `if (!lockPath)`.
-    // Callers that want a clearer diagnostic should call
-    // `acquireLockDiagnostic` instead.
+    // Null on failure — the contract every call site tests as `if (!lockPath)`.
     return null;
   }
 }
 
-// Callers needing to distinguish "couldn't acquire because the lock is
-// genuinely held by a live process" from "couldn't acquire because of an
-// unexpected error" can use this thin diagnostic wrapper.
-// Returns either { ok: true, path } or { ok: false, reason, lock_path?, holder_pid? }.
-// The bare `acquireLock` keeps its historical null-on-failure contract.
+// acquireLock, but separating "held by a live process" from an unexpected
+// error: { ok:true, path } or { ok:false, reason, lock_path?, holder_pid? }.
 function acquireLockDiagnostic(playbookId) {
   const p = lockFilePath(playbookId);
   if (!p) return { ok: false, reason: 'no_lock_path' };
@@ -534,10 +374,7 @@ function acquireLockDiagnostic(playbookId) {
           return { ok: false, reason: 'reclaim_failed', error: e2.message, lock_path: p, holder_pid: pid };
         }
       }
-      // Same-PID stale-lockfile reclaim (diagnostic variant). Same
-      // semantics as in acquireLock: a same-process lockfile older than
-      // STALE_LOCK_MS is an orphan and must be reclaimed; a fresher one
-      // is legitimate reentrancy and stays held.
+      // Same-PID reclaim, same mtime semantics as acquireLock.
       if (Number.isInteger(pid) && pid === process.pid) {
         let mtimeMs = null;
         try { mtimeMs = fs.statSync(p).mtimeMs; } catch {}
@@ -569,20 +406,12 @@ function pidAlive(pid) {
   catch (e) { return e.code !== 'ESRCH'; }
 }
 
-// --- phase 1: govern ---
-
-/**
- * Load GRC context for the agent. Returns jurisdiction obligations (with
- * window_hours + clock_starts so close() can compute deadlines later), theater
- * fingerprints, framework gap summary, and skills to preload.
- */
+// Phase 1. GRC context for the agent. Jurisdiction obligations carry
+// window_hours + clock_starts because close() computes deadlines from them.
 function govern(playbookId, directiveId, runOpts = {}) {
   const playbook = runOpts._playbookCache || loadPlaybook(playbookId);
   const g = resolvedPhase(playbook, directiveId, 'govern');
-  // Sort jurisdiction obligations by window_hours ascending so the
-  // tightest deadline (e.g. DORA's 4h, NIS2's 24h, GDPR's 72h) surfaces
-  // first. Operators reading the govern output for ack-time briefing need
-  // the most urgent clock at the top of the list.
+  // Ascending window_hours: the tightest clock heads the list.
   const obligations = (g.jurisdiction_obligations || []).slice().sort((a, b) => {
     const aw = (a && typeof a.window_hours === 'number') ? a.window_hours : Number.POSITIVE_INFINITY;
     const bw = (b && typeof b.window_hours === 'number') ? b.window_hours : Number.POSITIVE_INFINITY;
@@ -600,16 +429,11 @@ function govern(playbookId, directiveId, runOpts = {}) {
     theater_fingerprints: g.theater_fingerprints || [],
     framework_context: g.framework_context || {},
     skill_preload: g.skill_preload || [],
-    // v0.11.12 (#124): --ack belongs semantically in govern (it acknowledges
-    // the jurisdiction_obligations surfaced here). Carry it forward so
-    // phases.govern.operator_consent reflects the consent state. Null when
-    // --ack was not passed.
+    // --ack acknowledges the obligations surfaced here; null when not passed.
     operator_consent: runOpts.operator_consent || null
   };
 }
 
-// --- phase 2: direct ---
-
 function direct(playbookId, directiveId, runOpts = {}) {
   const playbook = runOpts._playbookCache || loadPlaybook(playbookId);
   const d = resolvedPhase(playbook, directiveId, 'direct');
@@ -625,8 +449,6 @@ function direct(playbookId, directiveId, runOpts = {}) {
   };
 }
 
-// --- phase 3: look (engine emits, agent executes) ---
-
 function look(playbookId, directiveId, runOpts = {}) {
   const playbook = runOpts._playbookCache || loadPlaybook(playbookId);
   const l = resolvedPhase(playbook, directiveId, 'look');
@@ -636,11 +458,8 @@ function look(playbookId, directiveId, runOpts = {}) {
     playbook_id: playbookId,
     directive_id: directiveId,
     air_gap_mode: airGap,
-    // Preconditions are surfaced here so the host AI can verify them with its
-    // own probes (Bash:test -f /proc/version, etc.) and declare the results
-    // back through submission.precondition_checks. Without this list, the AI
-    // is blind to the gate and run() will halt with a precondition_unverified
-    // failure the AI can't diagnose. See AGENTS.md Hard Rule context.
+    // The host AI probes these itself and declares the results through
+    // submission.precondition_checks; without the list it is blind to the gate.
     preconditions: (playbook._meta.preconditions || []).map(pc => ({
       id: pc.id,
       description: pc.description,
@@ -653,14 +472,10 @@ function look(playbookId, directiveId, runOpts = {}) {
     },
     artifacts: (l.artifacts || []).map(a => ({
       ...a,
-      // Surface the air-gap alternative as the primary source when air_gap_mode
-      // is active, so the agent doesn't accidentally hit the network.
       source: airGap && a.air_gap_alternative ? a.air_gap_alternative : a.source,
       _original_source: a.source,
-      // In air-gap mode an artifact with NO air_gap_alternative silently keeps
-      // its original (possibly network-bound) source — defeating air-gap with no
-      // signal. Flag it so the agent treats the source as not-offline-verified
-      // and the gap is observable instead of a silent network fallback.
+      // An artifact with no alternative keeps its possibly network-bound
+      // source, so the flag marks it not-offline-verified.
       ...(airGap && !a.air_gap_alternative ? { air_gap_alternative_missing: true } : {}),
     })),
     collection_scope: l.collection_scope,
@@ -669,16 +484,12 @@ function look(playbookId, directiveId, runOpts = {}) {
   };
 }
 
-// --- phase 4: detect ---
-
 /**
- * Evaluate artifacts the agent submitted against the playbook's typed
- * indicators. Returns a per-indicator hit/miss/inconclusive verdict plus a
+ * Phase 4. Evaluates submitted artifacts against the playbook's typed
+ * indicators: a per-indicator hit/miss/inconclusive verdict plus a
  * minimum_signal classification (detected | inconclusive | not_detected).
- *
- * The agent submits `artifacts` as { artifact_id: { value, captured: true|false, reason? } }
- * and (optionally) `signal_overrides` as { indicator_id: 'hit'|'miss'|'inconclusive' } to
- * record an indicator outcome the agent computed using its own pattern matching.
+ * The agent submits `artifacts` as { artifact_id: { value, captured, reason? } }
+ * and optionally `signal_overrides` as { indicator_id: verdict }.
  */
 function detect(playbookId, directiveId, agentSubmission = {}, runOpts = {}) {
   const playbook = runOpts._playbookCache || loadPlaybook(playbookId);
@@ -686,13 +497,8 @@ function detect(playbookId, directiveId, agentSubmission = {}, runOpts = {}) {
   const artifacts = agentSubmission.artifacts || {};
   const overrides = agentSubmission.signal_overrides || {};
 
-  // v0.11.4 (#71): canonicalize the indicator result vocabulary. Operators
-  // submit shapes like "no_hit" / "clean" / "ok" / false from years of
-  // CI/security tooling convention; the engine internally uses
-  // hit | miss | inconclusive. Without canonicalization every flat-shape
-  // observation with result:"no_hit" silently fell through to inconclusive
-  // and broke per-indicator detection. Canonicalization happens here so
-  // both detect() and normalizeSubmission consumers see the same outcomes.
+  // Operators submit the CI/security vocabulary ("no_hit", "clean", "ok"); the
+  // engine speaks hit | miss | inconclusive.
   const canonicalize = (v) => {
     if (v === true || v === 'hit' || v === 'detected' || v === 'positive') return 'hit';
     if (v === false || v === 'miss' || v === 'no_hit' || v === 'no-hit' || v === 'clean' || v === 'clear' || v === 'not_hit' || v === 'ok' || v === 'pass' || v === 'negative') return 'miss';
@@ -700,19 +506,9 @@ function detect(playbookId, directiveId, agentSubmission = {}, runOpts = {}) {
     return null; // truly unknown — fall through
   };
 
-  // Per-indicator FP-check attestation map. Operators submit
-  //   signal_overrides: { '<indicator-id>__fp_checks': { '<fp-check-name>': true } }
-  // to declare which named false_positive_checks_required[] entries on the
-  // indicator have been satisfied. An unverified FP check downgrades the
-  // verdict from 'hit' to 'inconclusive' and surfaces fp_checks_unsatisfied
-  // on the per-indicator result. See AGENTS.md Hard Rule #6 (compliance
-  // theater) and AGENTS.md §"detect (AI)" — a `hit` without its FP checks
-  // is not yet a `detected` classification.
-  // Optional per-indicator evidence locations the submission supplies
-  // (`evidence_locations: { "<indicator-id>": ["path", {uri,startLine}] }`).
-  // Threaded onto each firing indicator so the SARIF renderer can populate
-  // results[].locations — without this, secret/file findings ship
-  // location-less and GitHub code-scanning drops them.
+  // `evidence_locations: { "<indicator-id>": ["path", {uri,startLine}] }`,
+  // threaded onto each firing indicator so the SARIF renderer can fill
+  // results[].locations — GitHub code-scanning drops a location-less result.
   const _evLocs = (agentSubmission && typeof agentSubmission.evidence_locations === 'object'
     && agentSubmission.evidence_locations !== null && !Array.isArray(agentSubmission.evidence_locations))
     ? agentSubmission.evidence_locations : {};
@@ -723,35 +519,22 @@ function detect(playbookId, directiveId, agentSubmission = {}, runOpts = {}) {
     let fpChecksUnsatisfied = null;
     if (override === 'hit' || override === 'miss' || override === 'inconclusive') {
       verdict = override;
-      // Gate 'hit' verdict on per-indicator false_positive_checks_required
-      // satisfaction. The FP-check attestation arrives as a sibling key
-      // '<id>__fp_checks' in signal_overrides; default behavior (no
-      // attestation) treats every required FP check as UNSATISFIED.
+      // A 'hit' is gated on the indicator's false_positive_checks_required,
+      // attested through a sibling signal_overrides key '<id>__fp_checks'. No
+      // attestation leaves every check UNSATISFIED and downgrades the verdict.
       if (verdict === 'hit' && Array.isArray(ind.false_positive_checks_required) && ind.false_positive_checks_required.length) {
-        // A hostile or buggy attestation may be a Proxy whose property
-        // accessors throw. The filter below reads `att[fpName]` for each
-        // required check; an exception inside the read would crash detect()
-        // and abort the entire run. Wrap the FP-check evaluation in a
-        // try/catch: on throw, treat ALL required checks as unsatisfied
-        // (safest default — never silently honor an attestation we couldn't
-        // read) and surface a runtime_error so the operator sees why.
+        // A Proxy attestation whose getters throw must not abort the run: on
+        // throw every check is unsatisfied — never honor an unreadable one.
         try {
           const attestation = overrides[`${ind.id}__fp_checks`];
-          // Arrays satisfy `typeof === 'object'` but are NOT a valid
-          // attestation map. A submission like
-          //   signal_overrides: { sig__fp_checks: [true, true] }
-          // would otherwise have its truthy entries matched via the index
-          // fallback (att['0'] === true), silently bypassing every FP-check
-          // requirement. Reject arrays explicitly so they fall through to
-          // the empty-attestation branch (every required check
-          // unsatisfied).
+          // An array satisfies `typeof === 'object'` but is not an attestation
+          // map: `[true, true]` would match through the index fallback below
+          // and bypass every FP-check requirement.
           const safeAtt = Array.isArray(attestation) ? null : attestation;
           const att = (safeAtt && typeof safeAtt === 'object') ? safeAtt : {};
           const unsatisfied = ind.false_positive_checks_required.filter(fpName => {
-            // Match either by exact name string OR by indexed key '0', '1', ...
-            // because false_positive_checks_required entries are free-text
-            // strings, not ids. Operators may attest either by the literal
-            // string or by index. Default: unsatisfied.
+            // The entries are free text, not ids, so an operator may attest by
+            // the literal string or by index. Anything else is unsatisfied.
             if (att[fpName] === true) return false;
             const idx = ind.false_positive_checks_required.indexOf(fpName);
             if (idx !== -1 && att[String(idx)] === true) return false;
@@ -762,10 +545,6 @@ function detect(playbookId, directiveId, agentSubmission = {}, runOpts = {}) {
             fpChecksUnsatisfied = unsatisfied;
           }
         } catch (e) {
-          // Treat every required check as unsatisfied — we couldn't trust the
-          // attestation map. Surface the throw so operators can chase the
-          // root cause (Proxy with a throwing getter, frozen object that
-          // tripped invariants, etc.).
           verdict = 'inconclusive';
           fpChecksUnsatisfied = ind.false_positive_checks_required.slice();
           if (runOpts && Array.isArray(runOpts._runErrors)) {
@@ -778,12 +557,8 @@ function detect(playbookId, directiveId, agentSubmission = {}, runOpts = {}) {
         }
       }
     } else {
-      // An override WAS supplied for this indicator but its value didn't
-      // canonicalize to hit/miss/inconclusive (e.g. "maybe", "present", a
-      // number). Pre-fix this was silently dropped — the operator believed
-      // they'd asserted a result but the signal vanished, yielding a false
-      // not_detected. Surface it as a runtime_error (mirrors the
-      // classification_override_invalid signal) so the drop is visible.
+      // An override that did not canonicalize ("maybe", a number). Dropping it
+      // silently turns an asserted result into a false not_detected.
       if (rawOverride !== undefined && runOpts && Array.isArray(runOpts._runErrors)) {
         pushRunError(runOpts._runErrors, {
           kind: 'signal_override_unrecognized',
@@ -792,12 +567,9 @@ function detect(playbookId, directiveId, agentSubmission = {}, runOpts = {}) {
           message: `signal_overrides["${ind.id}"] value was not recognized (expected hit/miss/inconclusive or a boolean); the signal was ignored.`,
         }, { dedupeKey: e => e.indicator_id || '' });
       }
-      // Without a usable override, treat any captured artifact as evidence
-      // the indicator could be evaluated. Mark inconclusive if any artifact
-      // was captured (engine doesn't pattern-match raw artifact content; the
-      // host AI is responsible for that). With NO captured artifacts, this is
-      // a clean empty submission — emit 'miss' so the run can reach
-      // classification:'not_detected' rather than getting stuck inconclusive.
+      // The engine does not pattern-match raw artifact content, so a captured
+      // artifact means only that the indicator COULD be evaluated. Nothing
+      // captured is an empty submission, which 'miss' lets reach not_detected.
       const anyCaptured = Object.values(artifacts).some(a => a && a.captured);
       verdict = anyCaptured ? 'inconclusive' : 'miss';
     }
@@ -811,8 +583,7 @@ function detect(playbookId, directiveId, agentSubmission = {}, runOpts = {}) {
     };
   });
 
-  // false-positive profile — engine highlights which FP tests the agent
-  // should still run against any indicator the agent reported as 'hit'.
+  // The FP tests the agent still owes for each indicator it reported as 'hit'.
   const fpChecksRequired = (det.false_positive_profile || []).filter(fp =>
     indicatorResults.find(r => r.id === fp.indicator_id && r.verdict === 'hit')
   );
@@ -821,20 +592,12 @@ function detect(playbookId, directiveId, agentSubmission = {}, runOpts = {}) {
   const hasDeterministicHit = hits.some(r => r.deterministic);
   const hasHighConfHit = hits.some(r => r.confidence === 'high' || r.confidence === 'deterministic');
 
-  // Agent override: if signals.detection_classification is explicitly set to
-  // one of the four legal values, honor it. Engine computes its own
-  // classification as a fallback. Use the override when the agent has run the
-  // full false_positive_profile checks and reached an explicit verdict —
-  // engine-computed classification can't represent "I saw the indicators and
-  // confirmed they're all benign" without this override.
+  // The agent's own verdict after running the full false_positive_profile: the
+  // engine classification cannot express "I saw these and they are all benign".
   const rawOverride = (agentSubmission.signals && agentSubmission.signals.detection_classification);
   const validOverrides = new Set(['detected', 'inconclusive', 'not_detected', 'clean']);
-  // Any override that's a non-empty string but NOT in the allowlist (e.g.
-  // 'present', 'unknown', '', '  detected  ', 'Detected') surfaces as a
-  // runtime_error rather than silently falling through to engine-computed
-  // classification. Operators submitting case variants / whitespace-padded
-  // strings deserve a clear diagnostic, not a quiet downgrade. Treat the
-  // override as absent for classification purposes once recorded.
+  // Matching is exact — case-sensitive, unpadded. A near-miss surfaces a
+  // runtime_error and is then treated as absent.
   const overrideIsString = typeof rawOverride === 'string';
   const overrideIsInAllowlist = overrideIsString && validOverrides.has(rawOverride);
   if (rawOverride !== undefined && rawOverride !== null && !overrideIsInAllowlist) {
@@ -849,28 +612,19 @@ function detect(playbookId, directiveId, agentSubmission = {}, runOpts = {}) {
   }
   const override = overrideIsInAllowlist ? rawOverride : undefined;
 
-  // Refuse ALL classification overrides (`detected`, `clean`,
-  // `not_detected`) when any indicator was FP-downgraded. A submission
-  // that maps to `'not_detected'` (either literally or via `'clean'`,
-  // which maps to `'not_detected'` at this site) MUST NOT hide a
-  // `verdict: 'hit'` indicator whose `false_positive_checks_required[]`
-  // were unattested — that's a strictly worse false-negative outcome than
-  // allowing 'detected' through. Substitute 'inconclusive' and emit a
-  // runtime_error.
-  // Record indicator IDs and an unsatisfied-checks count ONLY — never the
-  // literal FP-check check-name strings (those are an attestation-bypass
-  // hint for a hostile agent reading the runtime_errors).
+  // Every classification override is refused once any indicator was
+  // FP-downgraded. The runtime_error records indicator ids and an unsatisfied
+  // count only: the literal check names are an attestation-bypass hint.
   const anyFpDowngrade = indicatorResults.some(r => Array.isArray(r.fp_checks_unsatisfied) && r.fp_checks_unsatisfied.length > 0);
 
   let classification;
-  // Track whether the override was actually honored, so we don't report a
-  // refused override as "applied" (L6).
+  // A refused override must not be reported as applied.
   let overrideEffective = !!override;
   if (override) {
     classification = override === 'clean' ? 'not_detected' : override;
     if (anyFpDowngrade) {
       const substituted = 'inconclusive';
-      const attempted = override; // record what the operator submitted, not the mapped form
+      const attempted = override; // what the operator submitted, not the mapped form
       classification = substituted;
       overrideEffective = false;
       if (runOpts && Array.isArray(runOpts._runErrors)) {
@@ -885,12 +639,9 @@ function detect(playbookId, directiveId, agentSubmission = {}, runOpts = {}) {
         }, { dedupeKey: e => String(e.attempted) });
       }
     } else if (classification === 'not_detected' && hasDeterministicHit) {
-      // A not_detected/clean override must not silently bury a DETERMINISTIC
-      // hit. A deterministic indicator firing is high-signal evidence; hiding
-      // it as not_detected is a strictly worse false-negative than leaving the
-      // run inconclusive. (Probabilistic hits remain overridable — that's the
-      // legitimate "I confirmed these are benign" workflow.) Substitute
-      // inconclusive and surface why.
+      // A deterministic hit cannot be buried under not_detected/clean — a
+      // worse false negative than an inconclusive run. Probabilistic hits stay
+      // overridable; that is the legitimate "these are benign" path.
       classification = 'inconclusive';
       overrideEffective = false;
       if (runOpts && Array.isArray(runOpts._runErrors)) {
@@ -919,57 +670,31 @@ function detect(playbookId, directiveId, agentSubmission = {}, runOpts = {}) {
     false_positive_checks_required: fpChecksRequired,
     classification,
     minimum_signal_basis: det.minimum_signal?.[classification === 'detected' ? 'detected' : classification === 'not_detected' ? 'not_detected' : 'inconclusive'],
-    // v0.11.3 #71: surface what detect actually consumed. Operators reading
-    // the detect output now see whether their flat-shape observations + the
-    // signal_overrides + the classification override all reached the runner.
+    // What detect consumed, so an operator can see what reached the runner.
     observations_received: Object.keys(agentSubmission.artifacts || {}),
     signals_received: Object.keys(agentSubmission.signal_overrides || {}),
-    // v0.11.4 (#73): downstream consumers iterating `indicators_evaluated`
-    // expect an array, not a count. Restore as array; provide
-    // `indicators_evaluated_count` for callers wanting the integer.
+    // An array — indicators_evaluated_count carries the integer.
     indicators_evaluated: indicatorResults.map(i => ({
       signal_id: i.id,
       outcome: i.verdict,
       confidence: i.confidence,
-      // v0.11.5 #85: surface which observation produced this indicator's
-      // outcome (when the agent submitted it via flat-shape observation +
-      // indicator + result fields). Null when no observation drove the
-      // indicator (engine-computed default).
+      // The observation behind this outcome; null on the engine default.
       from_observation: agentSubmission._signal_origins?.[i.id] || null,
     })),
     indicators_evaluated_count: indicatorResults.length,
-    // Only report the override as applied when it was actually honored — a
-    // refused override (FP-downgrade or deterministic-hit masking) left
-    // `classification` as inconclusive, so reporting the attempted value here
-    // would contradict the verdict.
+    // Null for a refused override, which would contradict the verdict.
     classification_override_applied: (override && overrideEffective) ? (override === 'clean' ? 'not_detected' : override) : null,
     submission_shape_seen: agentSubmission._original_shape || (agentSubmission.artifacts ? 'nested (v0.10.x)' : 'empty'),
-    // Pass through any flat-shape observation collisions detected at
-    // normalize time so analyze() can publish them under
-    // analyze.signal_origins_with_collisions.
+    // Republished by analyze() as analyze.signal_origins_with_collisions.
     _signal_origins_collisions: Array.isArray(agentSubmission._signal_origins_collisions) ? agentSubmission._signal_origins_collisions.slice() : []
   };
 }
 
-// --- phase 5: analyze ---
-
-/**
- * Mirror the FIRED detect indicators (verdict === 'hit') into a flat
- * `{ <indicator-id>: true }` map for the escalation / feeds_into / precondition
- * eval contexts. Indicator hits arrive from the collector / AI evidence path as
- * `signal_overrides` (which detect() reads); the condition contexts spread
- * `agentSubmission.signals`, NOT signal_overrides — so an escalation written as
- * `<indicator-id> == true` (the catalog's canonical form) stayed false even when
- * that indicator DETECTED, unless the operator redundantly re-submitted the id
- * under `signals`. The standard `exceptd collect <playbook>` path never does
- * that, so the entire indicator-gated escalation/chain layer was dead on the
- * real evidence path. Mirroring fired indicators here binds the condition layer
- * to the detect layer. Only verdict 'hit' (FP-checks satisfied) is mirrored — an
- * 'inconclusive' indicator is unconfirmed and must not fire an escalation. The
- * map is spread with the LOWEST precedence (before agentSignals, which is before
- * the engine roots) so an operator can still override a specific id and the
- * engine-computed values always win.
- */
+// Mirror the fired detect indicators into a flat `{ <indicator-id>: true }` map
+// for the escalation / feeds_into / precondition contexts, which spread
+// `signals` and not `signal_overrides`. Only verdict 'hit' mirrors: an
+// 'inconclusive' indicator is unconfirmed and must not fire an escalation.
+// Spread at the LOWEST precedence, so engine values still win.
 function firedIndicatorSignals(detectIndicators) {
   const out = {};
   for (const ind of (detectIndicators || [])) {
@@ -978,66 +703,31 @@ function firedIndicatorSignals(detectIndicators) {
   return out;
 }
 
-/**
- * RWEP composition + blast-radius scoring + theater check + framework gap
- * mapping + escalation evaluation. Inputs are the detect result + any
- * agent-submitted signal_values (e.g. blast_radius classification).
- */
+// Phase 5. RWEP composition, blast-radius scoring, theater check, framework gap
+// mapping and escalation evaluation, from the detect result plus agent signals.
 function analyze(playbookId, directiveId, detectResult, agentSignals = {}, runOpts = {}) {
   const playbook = runOpts._playbookCache || loadPlaybook(playbookId);
   const an = resolvedPhase(playbook, directiveId, 'analyze');
   const directive = findDirective(playbook, directiveId);
-  // F6/F20/F24: when analyze() is called directly (not via run()), no
-  // runtime-error accumulator exists in runOpts. Ensure there's always a
-  // local array so blast_radius / theater / xref errors surface in the
-  // returned analyze.runtime_errors.
+  // A direct analyze() call carries no accumulator, and without a local one
+  // blast_radius / theater / xref errors never reach analyze.runtime_errors.
   if (!Array.isArray(runOpts._runErrors)) {
     runOpts = { ...runOpts, _runErrors: [] };
   }
 
-  // Resolve catalogued CVEs from the domain.cve_refs list. This list is the
-  // playbook's CVE scan-coverage enumeration — every CVE this playbook can
-  // detect. By itself it is NOT a statement that the operator is affected by
-  // any of these CVEs; affected-ness requires evidence correlation in detect.
-  //
-  // Two distinct sets are computed below:
-  //
-  //   catalogBaselineCves — every CVE the playbook scans for, with full
-  //       per-CVE catalog context (RWEP / KEV / CVSS / AI-discovery /
-  //       active-exploitation / patch state). Always populated when the
-  //       playbook has domain.cve_refs. Each entry carries correlated_via=null
-  //       and a `note` flagging it as catalog-only.
-  //
-  //   matchedCves       — CVEs the operator's submitted evidence actually
-  //       correlates to. Correlation paths:
-  //         (a) An indicator fired (verdict === 'hit') whose attack_ref or
-  //             atlas_ref intersects the CVE's attack_refs / atlas_refs in
-  //             the catalog.
-  //         (b) An agentSignal explicitly references the CVE id with a
-  //             truthy value (`agentSignals[cveId] === true`) or with a
-  //             string value 'hit' / 'detected' / 'affected'.
-  //       Each entry carries correlated_via=<reason string> so downstream
-  //       consumers (CSAF / SARIF / OpenVEX / human renderer) can show the
-  //       provenance, and so an empty matchedCves means "no evidence
-  //       correlated to operator's submission" rather than "playbook has
-  //       no CVEs of interest."
-  //
-  // VEX filter (agentSignals.vex_filter): a set of CVE IDs the operator has
-  // formally declared not_affected via CycloneDX/OpenVEX. VEX-dropped CVEs
-  // are removed from BOTH arrays (they're not affected — neither correlated
-  // nor part of effective scan coverage for this run).
+  // domain.cve_refs enumerates the playbook's scan coverage, never a claim that
+  // the operator is affected. catalogBaselineCves is all of it with
+  // correlated_via null; matchedCves is the subset the evidence correlates to,
+  // and correlated_via names what tied them. agentSignals.vex_filter removes
+  // entries from BOTH arrays.
   const cveRefs = playbook.domain.cve_refs || [];
   const vexFilter = agentSignals.vex_filter instanceof Set ? agentSignals.vex_filter
     : (Array.isArray(agentSignals.vex_filter) ? new Set(agentSignals.vex_filter) : null);
-  // Distinguish OpenVEX/CycloneDX "drop entirely" dispositions
-  // (not_affected / false_positive) from "keep but annotate" dispositions
-  // (fixed / resolved). vexFilterFromDoc returns the union; the "fixed" set
-  // is computed below from agentSignals.vex_fixed when the operator passes
-  // it (CLI populates it from the VEX doc alongside vex_filter).
+  // not_affected / false_positive drop entirely; fixed / resolved are kept and
+  // annotated. The CLI populates vex_fixed from the VEX doc.
   const vexFixed = agentSignals.vex_fixed instanceof Set ? agentSignals.vex_fixed
     : (Array.isArray(agentSignals.vex_fixed) ? new Set(agentSignals.vex_fixed) : null);
-  // Wrap xref.byCve() so a corrupt catalog (or transient missing-index
-  // anomaly) surfaces as a runtime_error rather than crashing analyze().
+  // A corrupt catalog or missing index becomes a runtime_error, not a crash.
   const _byCveSafe = (id) => {
     try { return xref.byCve(id); }
     catch (e) {
@@ -1054,24 +744,19 @@ function analyze(playbookId, directiveId, detectResult, agentSignals = {}, runOp
   const vexDropped = vexFilter
     ? allCves.filter(c => vexFilter.has(c.cve_id)).map(c => c.cve_id)
     : [];
-  // VEX-fixed CVEs remain in matched/catalog arrays but get annotated
-  // with vex_status:'fixed' downstream so consumers see them as resolved.
-  // Source from catalogBaselineCves (post-vexFilter survivors), NOT allCves: a
-  // CVE the operator marked BOTH not_affected (dropped by vexFilter) AND fixed
-  // is contradictory, and listing it as fixed while it's absent from
-  // matched/baseline would have it appear in fixed_cves but nowhere else.
+  // From the post-vexFilter survivors, not allCves: a CVE marked BOTH
+  // not_affected and fixed would land in fixed_cves and nowhere else.
   const vexFixedIds = vexFixed
     ? catalogBaselineCves.filter(c => vexFixed.has(c.cve_id)).map(c => c.cve_id)
     : [];
 
-  // Build correlation map: cve_id -> array of "indicator_hit:<id>" / "signal:<id>" reasons.
+  // cve_id -> array of "indicator_hit:<id>" / "signal:<id>" reasons.
   const correlationsByCve = new Map();
   const addCorrelation = (cveId, reason) => {
     if (!correlationsByCve.has(cveId)) correlationsByCve.set(cveId, []);
     const arr = correlationsByCve.get(cveId);
     if (!arr.includes(reason)) arr.push(reason);
   };
-  // (a) indicator-hit → CVE via shared attack_ref / atlas_ref.
   const playbookDetect = resolvedPhase(playbook, directiveId, 'detect');
   const indicatorRefs = new Map(); // indicator.id -> { attack_ref, atlas_ref }
   for (const ind of (playbookDetect.indicators || [])) {
@@ -1087,7 +772,6 @@ function analyze(playbookId, directiveId, detectResult, agentSignals = {}, runOp
       if (attackHit || atlasHit) addCorrelation(c.cve_id, `indicator_hit:${fired.id}`);
     }
   }
-  // (b) agentSignals explicitly referencing a CVE id.
   for (const c of catalogBaselineCves) {
     const sig = agentSignals[c.cve_id];
     if (sig === true || sig === 'hit' || sig === 'detected' || sig === 'affected') {
@@ -1095,14 +779,9 @@ function analyze(playbookId, directiveId, detectResult, agentSignals = {}, runOp
     }
   }
 
-  // Indicator-level cve_ref correlation. Indicators may declare a
-  // cve_ref (string OR string[]) naming CVEs whose presence the indicator
-  // pattern-matches. When such an indicator fires AND the named CVE exists
-  // in the catalog, the CVE joins matched_cves with correlated_via=
-  // 'indicator_cve_ref:<indicator-id>'. The catalog lookup also brings in
-  // CVEs the playbook didn't enumerate in domain.cve_refs — they're appended
-  // to the working catalog set so the downstream matchedCves filter picks
-  // them up. Dedupe is automatic via correlationsByCve (Map keyed on cve_id).
+  // An indicator's own cve_ref (string or string[]), correlated as
+  // 'indicator_cve_ref:<indicator-id>'. This reaches CVEs domain.cve_refs
+  // never enumerated, which join the working set for the filter below.
   const extraCatalogCves = [];
   const seenCatalogIds = new Set(catalogBaselineCves.map(c => c.cve_id));
   for (const fired of firedIndicators) {
@@ -1111,7 +790,6 @@ function analyze(playbookId, directiveId, detectResult, agentSignals = {}, runOp
     const raw = indicator.cve_ref;
     const refs = Array.isArray(raw) ? raw : (typeof raw === 'string' && raw ? [raw] : []);
     for (const cveId of refs) {
-      // VEX-drop these the same as catalog CVEs.
       if (vexFilter && vexFilter.has(cveId)) continue;
       let cveEntry = catalogBaselineCves.find(c => c.cve_id === cveId);
       if (!cveEntry) {
@@ -1129,24 +807,15 @@ function analyze(playbookId, directiveId, detectResult, agentSignals = {}, runOp
 
   const matchedCves = workingCatalogCves.filter(c => correlationsByCve.has(c.cve_id));
 
-  // Per-CVE shape — identical between matched_cves and catalog_baseline_cves
-  // so consumers can iterate either without branching. matched_cves entries
-  // carry a non-null correlated_via array; catalog_baseline_cves entries
-  // carry correlated_via:null and a `note` clarifying the field's intent.
+  // One shape for both arrays, so consumers iterate either without branching.
   const cveShape = (c, correlatedVia) => {
-    // Annotate VEX-fixed CVEs with vex_status. matched_cves still
-    // includes them so audit trails and SBOM reports surface "we know this
-    // is in scope but vendor declared it fixed."
+    // VEX-fixed CVEs stay in matched_cves so the audit trail keeps them.
     const vexStatus = (vexFixed && vexFixed.has(c.cve_id)) ? 'fixed' : null;
     return {
       cve_id: c.cve_id,
-      // attack_class is the coarse chainable taxonomy (kernel-lpe /
-      // mcp-supply-chain / ai-c2 / prompt-injection / container-escape / …)
-      // the sbom -> deep-dive feeds_into rules quantify over
-      // (`any matched_cve.attack_class == 'kernel-lpe'`). It comes from the
-      // catalog entry's explicit attack_class only — no fuzzy inference from
-      // the free-form `type`, so an unclassified CVE stays null and the chain
-      // correctly does not fire (no false escalation) rather than misrouting.
+      // What the sbom → deep-dive feeds_into rules quantify over. The catalog
+      // entry's explicit attack_class only — never inferred from the free-form
+      // `type`, so an unclassified CVE stays null and the chain does not fire.
       attack_class: c.entry?.attack_class ?? null,
       rwep: c.rwep_score,
       cvss_score: c.entry?.cvss_score ?? null,
@@ -1177,33 +846,16 @@ function analyze(playbookId, directiveId, detectResult, agentSignals = {}, runOp
     note: 'Catalog-baseline entry — this CVE is in the playbook\'s scan coverage but no submitted evidence correlated to it. Not a statement that the operator is affected.',
   }));
 
-  // RWEP composition: start from the per-CVE rwep_score of evidence-correlated
-  // matches (NOT catalog baseline) so RWEP base reflects what the operator's
-  // evidence actually surfaced. The "max" reduction across matched CVEs is
-  // intentional — RWEP is a "worst-case real-world exploit priority", not
-  // an arithmetic average. The most-exploitable CVE in the set drives the
-  // base; secondary CVEs add via rwep_inputs adjustments below rather than
-  // through base summing (which would double-count overlapping risk).
-  // vex_status='fixed' CVEs do NOT drive the base — vendor declared them
-  // resolved. They still appear in matched_cves for audit traceability but
-  // don't elevate RWEP.
+  // Evidence-correlated matches only, reduced with max: RWEP is a worst-case
+  // priority, so the most-exploitable CVE sets the base and summing bases would
+  // double-count overlapping risk. A vex_status='fixed' CVE never drives it.
   const rwepEligible = matchedCves.filter(c => !(vexFixed && vexFixed.has(c.cve_id)));
   const baseRwep = rwepEligible.length ? Math.max(...rwepEligible.map(c => c.rwep_score)) : 0;
 
-  // rwep_factor semantics: each rwep_input.weight is conditional on the
-  // matched CVE having a corresponding attribute. Multiply weight by a
-  // factor in [0, 1] derived from the first matched CVE's catalog
-  // attribute so a weight only fires when its CVE-attribute supports it
-  // (e.g. active_exploitation +25 only when the matched CVE is under
-  // active exploitation). blast_radius is sourced from the analyze-phase
-  // blast_radius_score / 5 (rubric ceiling). Negative weights
-  // (patch_available, live_patch_available) keep their sign so a patched
-  // CVE deducts the full magnitude when the catalog confirms a
-  // patch is available.
-  //
-  // Aliasing: playbooks ship rwep_factor values `public_poc` and
-  // `ai_weaponization` for what F5 calls `poc_available` and `ai_factor`.
-  // Both spellings resolve here.
+  // Each rwep_input.weight scales by a [0, 1] factor from the matched CVE's
+  // catalog attributes. Negative weights keep their sign, so a patched CVE
+  // deducts in full. `public_poc` and `ai_weaponization` are catalog aliases for
+  // `poc_available` and `ai_factor`; both spellings resolve.
   const _factorScale = (factorName, cve, blastScore) => {
     if (!cve) return 0;
     switch (factorName) {
@@ -1211,15 +863,9 @@ function analyze(playbookId, directiveId, detectResult, agentSignals = {}, runOp
         return cve.cisa_kev === true ? 1 : 0;
       case 'active_exploitation': {
         const v = cve.active_exploitation || (cve.entry && cve.entry.active_exploitation);
-        // Route through the shared scoring resolver instead of an inline
-        // `ladder[v] ?? 0` lookup so a stray-cased value ('Confirmed') scales
-        // identically to the catalog scorer AND an out-of-vocabulary value
-        // ('in-the-wild') surfaces the RWEP_AE_UNRECOGNISED warning rather than
-        // silently zeroing the active-exploitation weight. activeExploitationMultiplier
-        // (not the bare resolveActiveExploitation().multiplier) is used precisely so
-        // the no-match path is OBSERVABLE — the "out-of-vocab token must surface,
-        // not silently default" class. For every canonical catalog value the
-        // returned multiplier is identical to the prior inline lookup.
+        // The shared resolver, not an inline `ladder[v] ?? 0`: a stray-cased
+        // value scales as the catalog scorer scales it, and an out-of-vocabulary
+        // one raises RWEP_AE_UNRECOGNISED instead of silently zeroing.
         return scoring.activeExploitationMultiplier(v);
       }
       case 'poc_available':
@@ -1242,24 +888,19 @@ function analyze(playbookId, directiveId, detectResult, agentSignals = {}, runOp
       case 'reboot_required':
         return cve.entry?.patch_required_reboot === true ? 1 : 0;
       case 'blast_radius': {
-        // blast_radius weights scale by the 0-5 rubric score so a max-blast
-        // finding gets full weight and a low-blast finding gets a fraction.
         if (typeof blastScore !== 'number' || blastScore < 0) return 0;
         return Math.min(1, blastScore / 5);
       }
       default:
-        // Unknown factor: fire as binary (legacy behavior) so playbooks with
-        // novel rwep_factor strings don't silently zero out.
+        // An unrecognised factor fires binary, so a playbook shipping a novel
+        // rwep_factor string does not silently zero out.
         return 1;
     }
   };
 
-  // blast_radius_score validation. No supplied value → null +
-  // signal='default'. Supplied value out of [0,5] → null +
-  // signal='rejected' + runtime_error. Supplied value in range → use it +
-  // signal='supplied'. The runner never defaults to a rubric entry — that
-  // would be the opposite of safe-default when the rubric's lowest entry
-  // is the LOWEST-blast row.
+  // blast_radius_score: in-range is 'supplied', absent is null + 'default',
+  // out of [0,5] is null + 'rejected' + runtime_error. Never a rubric entry —
+  // the rubric's lowest row is the LOWEST-blast one, so a guess understates.
   const blastRubric = an.blast_radius_model?.scoring_rubric || [];
   let blastRadiusScore = null;
   let blastRadiusSignal = 'default';
@@ -1276,56 +917,26 @@ function analyze(playbookId, directiveId, detectResult, agentSignals = {}, runOp
       }
     }
   }
-  // Use the first evidence-correlated CVE as the canonical attribute
-  // source for factor scaling. If matchedCves is empty there's no per-CVE
-  // evidence to gate on. v0.12.15: the prior fallback was
-  // `factorCve = null` → every factor returned 0 → catalog-shape playbooks
-  // (secrets, library-author, crypto-codebase, framework, cred-stores,
-  // containers, runtime, crypto, ai-api) that detect WITHOUT a per-CVE
-  // evidence correlation emitted `weight_applied: 0` for every fired
-  // indicator, producing `adjusted: 0` for every detection. The e2e suite
-  // caught this — 9/20 scenarios failed `json_path_min.adjusted >= N`.
-  //
-  // Domain-level fallback: when no evidence-correlated CVE is available,
-  // use the highest-rwep_score entry from `workingCatalogCves` (which is
-  // built from `playbook.domain.cve_refs[]` — the playbook's canonical
-  // "what we're about"). This preserves factor-scaling semantics while
-  // recognizing that a catalog-shape playbook's threat class is already
-  // declared by its domain refs. The factor-scale annotation surfaces
-  // `factor_cve_source: 'evidence' | 'domain' | 'none'` so operators see
-  // which fallback was used.
+  // Factor scaling reads one CVE, resolved in order and annotated as
+  // factor_cve_source: 'evidence' (an RWEP-eligible match), 'domain' (the
+  // highest-rwep entry from domain.cve_refs), or 'none'.
   let factorCveSource = 'none';
-  // Prefer an RWEP-eligible (non-VEX-fixed) matched CVE to drive factor
-  // scaling — a vendor-patched CVE must not inflate adjusted RWEP via its
-  // exploitation / KEV / PoC multipliers. Do NOT fall back to matchedCves[0]:
-  // when EVERY evidence-correlated CVE is VEX-fixed (rwepEligible empty but
-  // matchedCves non-empty) the finding is remediated, so factor scaling must be
-  // suppressed entirely — base is already 0 and the fired factors must not
-  // raise the adjusted score (a vendor-fixed CVE's KEV/exploitation/PoC would
-  // otherwise lift it above 0). The domain-CVE and class-weight fallbacks below
-  // are skipped in that case too, so every fired factor scales by 0 via
-  // _factorScale(factor, null, …).
+  // Never fall back to matchedCves[0]: when every correlated CVE is VEX-fixed
+  // the finding is remediated, and a patched CVE's KEV / exploitation / PoC
+  // multipliers would lift the adjusted score above its base of 0.
   const allMatchedVexFixed = matchedCves.length > 0 && rwepEligible.length === 0;
   let factorCve = rwepEligible[0] || null;
   if (factorCve) {
     factorCveSource = 'evidence';
   } else if (!allMatchedVexFixed && workingCatalogCves.length > 0) {
-    // Highest rwep_score from domain refs.
     factorCve = workingCatalogCves.reduce((worst, c) =>
       (typeof c.rwep_score === 'number' && (!worst || c.rwep_score > worst.rwep_score)) ? c : worst,
     null);
     if (factorCve) factorCveSource = 'domain';
   }
-  // v0.12.15: five shipped playbooks (secrets, library-author,
-  // crypto-codebase, framework, cred-stores, containers, runtime, crypto,
-  // ai-api) ship with empty `domain.cve_refs` because their attack class is
-  // class-of-vulnerability rather than CVE-specific. For those playbooks
-  // neither evidence-correlation NOR the domain-CVE fallback yields a
-  // factorCve, so every fired indicator's `weight_applied` was forced to
-  // zero by `_factorScale` returning 0. Fall back to the pre-v0.12.14
-  // semantics for this case only: apply the declared weight as-is
-  // (factor_scale=1, legacy semantics). The factor_cve_source annotation
-  // surfaces 'class' so operators see which mode the run used.
+  // A class-of-vulnerability playbook ships an empty domain.cve_refs, so
+  // neither rung above yields a factorCve and every indicator would scale to
+  // zero. Those apply the declared weight as-is, annotated 'class'.
   const _classScaleFallback = !factorCve && !allMatchedVexFixed;
   let adjustedRwep = baseRwep;
   const rwepBreakdown = [];
@@ -1336,17 +947,10 @@ function analyze(playbookId, directiveId, detectResult, agentSignals = {}, runOp
       rwepBreakdown.push({ signal_id: input.signal_id, rwep_factor: input.rwep_factor, weight_applied: 0, fired: false, factor_scale: 0 });
       continue;
     }
-    // v0.12.15: class-of-vulnerability playbooks (no factorCve from
-    // evidence OR domain) apply weights as-is via the legacy semantics.
-    // For CVE-anchored playbooks, scale by the matched CVE's attributes.
-    // Class fallback covers blast_radius too — when the agent submitted a
-    // blast score, _factorScale honors it; otherwise the class-fallback
-    // applies full weight (matching pre-v0.12.14 behavior, where every
-    // fired indicator contributed its full declared weight).
+    // An operator-supplied blast score is honored in either mode.
     let scale, factorCveSourceForBreakdown;
     if (_classScaleFallback) {
       if (input.rwep_factor === 'blast_radius' && typeof blastRadiusScore === 'number') {
-        // Operator-supplied blast score is still honored even in class mode.
         scale = Math.min(1, blastRadiusScore / 5);
       } else {
         scale = 1;
@@ -1370,20 +974,9 @@ function analyze(playbookId, directiveId, detectResult, agentSignals = {}, runOp
   }
   adjustedRwep = Math.max(0, Math.min(100, adjustedRwep));
 
-  // compliance_theater_check — engine surfaces the test; agent runs it; we
-  // accept the verdict in agentSignals.theater_verdict. When agent didn't
-  // submit a verdict but the detect phase reached a clear classification,
-  // derive one rather than leaving the field stuck in 'pending_agent_run':
-  //   detect.classification = not_detected → theater_verdict = clear
-  //   detect.classification = detected     → theater_verdict = pending_agent_run
-  //                                          (agent still must run reality_test)
-  //   detect.classification = inconclusive → theater_verdict = pending_agent_run
-  // Aliases 'clean' / 'no_theater' map to 'clear' for ergonomics.
-  //
-  // Validate agentSignals.theater_verdict against an allowlist so
-  // downstream consumers (CSAF/SARIF/OpenVEX) never emit bundles with
-  // garbage verdicts like "TODO" or free-text strings. Allowlist: clear,
-  // present, theater, pending_agent_run, unknown.
+  // The engine surfaces the theater test, the agent runs it, and the verdict
+  // arrives as agentSignals.theater_verdict. The allowlist keeps free text out
+  // of the CSAF / SARIF / OpenVEX bundles.
   const _theaterAllowlist = new Set(['clear', 'present', 'theater', 'pending_agent_run', 'unknown']);
   let theaterVerdict = agentSignals.theater_verdict;
   if (theaterVerdict === 'clean' || theaterVerdict === 'no_theater') theaterVerdict = 'clear';
@@ -1403,50 +996,29 @@ function analyze(playbookId, directiveId, detectResult, agentSignals = {}, runOp
   }
   theaterVerdict = theaterVerdict || (an.compliance_theater_check ? 'pending_agent_run' : null);
 
-  // framework_gap_mapping — engine emits the mapping verbatim; analyze does
-  // not compute new gaps here, just attaches the playbook-declared ones.
+  // The playbook-declared gaps, emitted verbatim; analyze computes none.
   const frameworkGaps = an.framework_gap_mapping || [];
 
-  // escalation criteria are evaluated AFTER the analyze result is assembled
-  // (below the result literal) so conditions can reference `analyze.*` and
-  // `finding.*` paths — the same roots close()'s feeds_into context
-  // resolves. The flat keys (rwep, blast_radius_score, theater_verdict,
-  // agent signals) remain available unchanged.
+  // Escalation criteria evaluate below the result literal so their conditions
+  // can reference `analyze.*` and `finding.*`.
   const escalations = [];
-  const runtimeErrors = []; // E3: collect regex-eval errors during analyze
+  const runtimeErrors = [];
   const evalCtxRoot = { _runErrors: runOpts._runErrors || runtimeErrors };
 
   const result = {
     phase: 'analyze',
     playbook_id: playbookId,
     directive_id: directiveId,
-    // Hard Rule #1 (AGENTS.md): every CVE reference must carry CVSS + KEV +
-    // PoC + AI-discovery + active-exploitation + patch/live-patch availability.
-    // Pull every required field from the catalog entry; null is only emitted
-    // when the catalog itself lacks the value, never when we just forgot to
-    // forward it. EPSS is included because validate-cves --live populates it.
-    //
-    // matched_cves — evidence-correlated only. Each entry has a non-null
-    // correlated_via[] array naming the indicator hits or agent signals that
-    // tied the operator's submission to this CVE. Empty array means the
-    // playbook's scan coverage saw no matching evidence in this run.
+    // Every CVE entry carries CVSS, KEV, PoC, AI-discovery, active-exploitation
+    // and patch state (AGENTS.md Hard Rule #1) from the catalog: a null means
+    // the catalog lacks the value, never that the runner dropped it.
     matched_cves: matchedCveEntries,
-    // catalog_baseline_cves — every CVE the playbook scans for, with the
-    // same per-CVE shape but correlated_via=null and a note explaining the
-    // field is scan-coverage metadata, NOT an operator-affected list. Use
-    // this when surfacing "what CVEs does this playbook check for?" Use
-    // matched_cves when surfacing "what CVEs is the operator actually
-    // affected by based on submitted evidence?"
+    // Scan coverage, not an affected list; correlated_via is null throughout.
     catalog_baseline_cves: catalogBaselineEntries,
-    // rwep base is reduced via Math.max across matched CVEs. Surface the
-    // reduction strategy as a discoverable field so operators reading the
-    // bundle understand the semantics without grepping source.
     rwep: { base: baseRwep, adjusted: adjustedRwep, breakdown: rwepBreakdown, threshold: directive ? resolvedPhase(playbook, directiveId, 'direct').rwep_threshold : null, _rwep_base_strategy: 'max' },
     blast_radius_score: blastRadiusScore,
-    // Visible annotation of where blast_radius_score came from:
-    //   'supplied'  — operator/agent provided a value in [0, 5].
-    //   'default'   — no value supplied; runner returned null (no rubric guess).
-    //   'rejected'  — value supplied but out of range; treated as default + runtime_error.
+    // 'supplied' | 'default' (none given, no rubric guess) | 'rejected'
+    // (out of range; treated as default and surfaced as a runtime_error).
     blast_radius_signal: blastRadiusSignal,
     blast_radius_basis: blastRubric.find(r => r.blast_radius_score === blastRadiusScore) || null,
     compliance_theater_check: {
@@ -1454,58 +1026,38 @@ function analyze(playbookId, directiveId, detectResult, agentSignals = {}, runOp
       audit_evidence: an.compliance_theater_check?.audit_evidence,
       reality_test: an.compliance_theater_check?.reality_test,
       verdict: theaterVerdict,
-      // Render verdict_text for both 'theater' AND 'present' verdicts
-      // ('present' is a synonym used by some playbooks for "theater is here").
+      // 'present' is a playbook synonym for 'theater'; both render the text.
       verdict_text: (theaterVerdict === 'theater' || theaterVerdict === 'present')
         ? an.compliance_theater_check?.theater_verdict_if_gap
         : null
     },
     framework_gap_mapping: frameworkGaps,
     escalations,
-    // v0.11.5 (#82): expose detect's per-indicator results + classification
-    // here so close()'s bundle builders can iterate indicators that fired
-    // and emit them as SARIF results / OpenVEX statements / CSAF notes.
-    // Prefixed with underscore to signal "for internal/render use".
+    // Underscore marks these render-internal: close()'s bundle builders read
+    // them to emit SARIF results / OpenVEX statements / CSAF notes.
     _detect_indicators: detectResult.indicators || [],
     _detect_classification: detectResult.classification,
-    // Non-underscore alias so catalog feeds_into / escalation conditions that
-    // reference the natural `analyze.classification` path resolve (the
-    // underscore-prefixed key was render-internal only, so those conditions
-    // resolved undefined and were silently dead — e.g. citation-hygiene →
-    // sbom, crypto-codebase → secrets). The underscore key stays for the
-    // SARIF/CSAF render consumers. On the detect-skip path run() re-sets
-    // analyze.classification to 'skipped', which is the same value
-    // detectResult.classification already carries there, so this is benign.
+    // The path catalog feeds_into / escalation conditions actually write —
+    // without the alias they resolve undefined and are silently dead.
     classification: detectResult.classification,
     vex: vexFilter ? {
       filter_applied: true,
       dropped_cve_count: vexDropped.length,
       dropped_cves: vexDropped,
-      // Vendor-fixed CVEs are a KEEP disposition — they stay in matched_cves
-      // annotated vex_status:'fixed' and never enter vexDropped. Surface them
-      // so the two dispositions are distinguishable and the note can be
-      // accurate (the drop note must not list a keep-disposition as a reason).
+      // A keep disposition — these stay in matched_cves, never in vexDropped.
       fixed_cves: vexFixedIds,
       fixed_cve_count: vexFixedIds.length,
       note: vexDropped.length
         ? `${vexDropped.length} CVE(s) dropped from analyze because the operator-supplied VEX statement marks them not_affected / false_positive. Vendor-fixed CVEs are NOT dropped — they remain in matched_cves with vex_status:'fixed'. The dropped CVEs remain in cve-catalog.json; the disposition lives in the VEX file.`
         : "VEX filter supplied; zero matches dropped (no CVEs in domain.cve_refs matched the VEX not-affected / false_positive set)."
     } : null,
-    // Regex-eval failures surfaced here so operators can see WHICH
-    // condition expression crashed without the runner dying. Only present
-    // when at least one evalCondition() call hit a regex exception during
-    // this analyze pass; runOpts._runErrors is the same accumulator
-    // populated by run() across all phases, so callers reading this field
-    // see every regex problem in the run.
+    // The run-wide accumulator: every non-fatal anomaly, without the run dying.
     runtime_errors: (runOpts._runErrors && runOpts._runErrors.length) ? runOpts._runErrors.slice() : (runtimeErrors.length ? runtimeErrors.slice() : []),
-    // Collisions when two flat-shape observations targeted the same
-    // indicator id. Empty when there were no collisions or no flat-shape
-    // observations submitted.
+    // Two flat-shape observations that targeted the same indicator id.
     signal_origins_with_collisions: Array.isArray(agentSignals?._signal_origins_collisions) ? agentSignals._signal_origins_collisions.slice() : (Array.isArray(detectResult?._signal_origins_collisions) ? detectResult._signal_origins_collisions.slice() : [])
   };
 
-  // analyzeFindingShape is a pure transform but defensive-wrap it (same as
-  // close()) so a malformed analyze result can't abort escalation handling.
+  // Wrapped so a malformed analyze result cannot abort escalation handling.
   let findingShape;
   try { findingShape = analyzeFindingShape(result); }
   catch (e) {
@@ -1516,47 +1068,24 @@ function analyze(playbookId, directiveId, detectResult, agentSignals = {}, runOp
   }
   for (const ec of an.escalation_criteria || []) {
     if (evalCondition(ec.condition, { ...firedIndicatorSignals(detectResult.indicators), ...agentSignals, ...evalCtxRoot, rwep: adjustedRwep, blast_radius_score: blastRadiusScore, theater_verdict: theaterVerdict, compliance_theater_check: result.compliance_theater_check, jurisdiction_obligations: (playbook.phases && playbook.phases.govern && playbook.phases.govern.jurisdiction_obligations) || [], analyze: result, matched_cve: result.matched_cves || [],
-        // finding.* is two-sourced: the engine computes the CVE/severity-derived
-        // keys (severity, rwep_adjusted, matched_cve_*, blast_radius_score,
-        // active_exploitation, framework/control_id_first) via analyzeFindingShape,
-        // while the DESCRIPTIVE keys the catalog conditions gate on
-        // (finding.includes_*, finding.cve_class, finding.tool_surface, …) are
-        // host-AI-asserted — the agent knows whether the finding includes a
-        // cloud-role-assumption path. Merge agent-supplied finding sub-fields
-        // UNDER the engine shape so the descriptive keys survive while engine-owned
-        // keys still WIN on collision (a poisoning signals.finding.severity can't
-        // override the engine-computed severity). The !Array.isArray guard rejects
-        // an array (typeof [] === 'object') that would inject numeric-index noise;
-        // null is already excluded by the leading &&.
+        // finding.* is two-sourced: analyzeFindingShape computes the
+        // CVE/severity keys, while the descriptive ones the catalog gates on
+        // (finding.includes_*, cve_class, tool_surface) are host-AI-asserted.
+        // Agent fields merge UNDER the engine shape; !Array.isArray rejects an
+        // array's numeric-index noise.
         finding: { ...(agentSignals.finding && typeof agentSignals.finding === 'object' && !Array.isArray(agentSignals.finding) ? agentSignals.finding : {}), ...findingShape } }, playbook)) {
       escalations.push({ condition: ec.condition, action: ec.action, target_playbook: ec.target_playbook || null });
     }
   }
-  // Escalation evaluation may have appended regex-eval diagnostics; refresh
-  // the snapshot so analyze.runtime_errors reflects them.
+  // Escalation evaluation may have appended diagnostics; refresh the snapshot.
   result.runtime_errors = (runOpts._runErrors && runOpts._runErrors.length) ? runOpts._runErrors.slice() : (runtimeErrors.length ? runtimeErrors.slice() : []);
   return result;
 }
 
-/**
- * Extract VEX disposition sets from a CycloneDX/OpenVEX document.
- *
- * OpenVEX `fixed` and `not_affected` must NOT collapse into a single
- * "drop" set — they have different semantics:
- *
- *   - not_affected / false_positive → drop from matched_cves entirely.
- *     The vendor has formally declared the product not vulnerable; the CVE
- *     is not in scope.
- *   - fixed / resolved → KEEP in matched_cves but annotate vex_status:'fixed'.
- *     The product was vulnerable; the vendor shipped a patch. Operators
- *     still need audit trails, SBOM coverage, and confirmation that the
- *     fix landed in their build.
- *
- * Returns a `Set<string>` for the legacy "drop" set (the function's
- * historical contract), with `.fixed` attached as an own property for
- * callers that want the split. The CLI passes both as
- * agentSignals.vex_filter + agentSignals.vex_fixed to analyze().
- */
+// The VEX disposition sets of a CycloneDX/OpenVEX document, which must not
+// collapse into one "drop" set: not_affected / false_positive drop from
+// matched_cves, while fixed / resolved are KEPT and annotated. Returns the drop
+// set as a Set with the fixed set attached as its own `.fixed` property.
 function vexFilterFromDoc(doc) {
   const out = new Set();
   const fixed = new Set();
@@ -1565,9 +1094,6 @@ function vexFilterFromDoc(doc) {
     return out;
   }
 
-  // CycloneDX shape — analysis.state values per CycloneDX VEX spec:
-  //   not_affected / false_positive → drop
-  //   resolved                       → fixed-annotation
   for (const v of (doc.vulnerabilities || [])) {
     const state = v.analysis && v.analysis.state;
     if (state === 'not_affected' || state === 'false_positive') {
@@ -1576,7 +1102,6 @@ function vexFilterFromDoc(doc) {
       if (v.id) fixed.add(v.id);
     }
   }
-  // OpenVEX shape
   for (const s of (doc.statements || [])) {
     const id = s.vulnerability && (s.vulnerability['@id'] || s.vulnerability.name || s.vulnerability);
     if (typeof id !== 'string') continue;
@@ -1587,11 +1112,8 @@ function vexFilterFromDoc(doc) {
   return out;
 }
 
-// Cap a summary line at `max` chars on a word boundary, appending an ellipsis
-// so a truncated line is visibly marked rather than cut mid-token. A raw
-// .slice() left blocked-preflight summaries ending mid-word ("...and conne")
-// with no signal that anything was dropped (the full text remains in the JSON
-// envelope's reason/remediation fields).
+// Cap on a word boundary and mark the cut, so a truncated line reads as
+// truncated. The full text stays in the envelope's reason / remediation.
 function capSummary(s, max = 240) {
   if (typeof s !== 'string' || s.length <= max) return s;
   const slice = s.slice(0, max - 1);
@@ -1600,30 +1122,18 @@ function capSummary(s, max = 240) {
   return base.replace(/[\s—.,;:-]+$/, '') + '…';
 }
 
-// --- phase 6: validate ---
-
 function validate(playbookId, directiveId, analyzeResult, agentSignals = {}, runOpts = {}) {
   const playbook = runOpts._playbookCache || loadPlaybook(playbookId);
-  // Remediation-path preconditions are evaluated through the SAME evalCondition
-  // the analyze/close phases use, so the precondition context must expose the
-  // SAME engine-computed roots those phases thread in — otherwise a precondition
-  // that gates on `rwep`, `finding.severity`, `matched_cve.*`,
-  // `blast_radius_score`, or `theater_verdict` resolves null and can NEVER be
-  // satisfied, so its remediation path is only ever reachable as the priority
-  // fallback (kernel's `any matched_cve.vector matches 'userns|bpf|ptrace|kptr'`
-  // hardening-compensation path was permanently unsatisfiable for this reason).
-  // agentSignals spread FIRST so the engine-computed values WIN on collision (a
-  // poisoning signals.rwep can't override the engine value) — mirrors the
-  // escalation (analyze) and feeds_into (close) contexts. finding.* merges the
-  // host-AI-asserted descriptive keys UNDER the engine shape with the same
-  // !Array.isArray guard used there.
+  // Remediation-path preconditions run through the same evalCondition as
+  // analyze and close, so this context must expose the same engine-computed
+  // roots: one gating on `rwep`, `finding.severity` or `matched_cve.*`
+  // otherwise resolves null and can never be satisfied. agentSignals spread
+  // FIRST so engine values win on collision.
   const govern = (playbook.phases && playbook.phases.govern) || {};
   let findingShape = {};
   try { findingShape = analyzeFindingShape(analyzeResult || {}); } catch { findingShape = {}; }
   const evalCtx = {
-    // Fired detect indicators mirrored in (lowest precedence) so a precondition
-    // referencing an indicator id resolves on the collector path. See
-    // firedIndicatorSignals.
+    // Lowest precedence, so an indicator id resolves on the collector path.
     ...firedIndicatorSignals(analyzeResult && analyzeResult._detect_indicators),
     ...agentSignals,
     rwep: analyzeResult && analyzeResult.rwep ? analyzeResult.rwep.adjusted : undefined,
@@ -1638,12 +1148,10 @@ function validate(playbookId, directiveId, analyzeResult, agentSignals = {}, run
   };
   const v = resolvedPhase(playbook, directiveId, 'validate');
 
-  // Pick the highest-priority remediation_path whose preconditions are all
-  // either satisfied by agentSignals or marked unverified=allow.
+  // Lower priority number sorts first, per the schema convention.
   const paths = (v.remediation_paths || []).slice().sort((a, b) => a.priority - b.priority);
-  // Indicators that actually fired this run — used to prefer a remediation
-  // that addresses the finding (via its for_signals linkage) over the bare
-  // priority-1 default when no path's preconditions are verified.
+  // The indicators that fired, so a remediation linked to one through
+  // for_signals can outrank the bare priority-1 default.
   const firedSignalIds = new Set(
     (analyzeResult._detect_indicators || []).filter(i => i.verdict === 'hit').map(i => i.id)
   );
@@ -1661,15 +1169,9 @@ function validate(playbookId, directiveId, analyzeResult, agentSignals = {}, run
     if (allSatisfied) satisfiedIds.add(p.id);
     considered.push({ id: p.id, priority: p.priority, all_satisfied: allSatisfied, addresses_fired_signal: addressesFired(p), preconditions: pcResult });
   }
-  // Precedence (paths is priority-sorted, so `find` returns the highest-priority
-  // match). Relevance to a fired indicator outranks a satisfied-but-unrelated
-  // path: recommending a ready-to-apply remediation that does NOT address the
-  // finding (just because its preconditions happen to hold) was the original
-  // defect — for_signals must beat it.
-  //   1. addresses a fired indicator AND preconditions satisfied (relevant + ready)
-  //   2. addresses a fired indicator (relevant; operator must meet its preconditions)
-  //   3. preconditions satisfied (no fired-signal-linked path — actionable fallback)
-  //   4. priority-1 (nothing else — at least propose the top path)
+  // paths is priority-sorted, so each `find` takes the highest-priority match.
+  // Relevance to a fired indicator outranks a satisfied-but-unrelated path. The
+  // last rung is priority-1, so something is always proposed.
   const selected =
     paths.find(p => addressesFired(p) && satisfiedIds.has(p.id))
     || paths.find(addressesFired)
@@ -1677,30 +1179,11 @@ function validate(playbookId, directiveId, analyzeResult, agentSignals = {}, run
     || paths[0]
     || null;
 
-  // selected_remediation selection logic:
-  //   1. Iterate remediation_paths sorted by priority ASC (lower number =
-  //      higher priority per schema convention).
-  //   2. Pick the FIRST path whose every precondition (evaluated against
-  //      agentSignals + playbook context) is satisfied.
-  //   3. Fallback: when nothing satisfies, surface the highest-priority
-  //      path anyway so the agent has SOMETHING to propose to the operator —
-  //      better than emitting null and forcing the agent to guess.
-  // Above this block: paths.sort + the loop populating `considered` +
-  // `selected`. `remediation_options_considered[]` carries the full per-path
-  // precondition trace so operators can see why a higher-priority path was
-  // skipped.
-
-  // Regression schedule. Returns a structured object with next_run +
-  // event_triggers + unparseable. Backwards compatibility: keep
-  // regression_next_run as the ISO string (or null) so existing CSAF /
-  // attestation consumers don't break; expose the structured form
-  // separately.
+  // regression_next_run stays the plain ISO string CSAF and attestation
+  // consumers read; the structured form sits alongside it.
   const triggers = v.regression_trigger || [];
   const regressionResult = computeRegressionNextRun(triggers);
 
-  // Reason annotation for null next_run — operators see WHY a schedule
-  // didn't emit a calendar date (no day intervals declared, every trigger
-  // is event-driven, or every trigger was unparseable).
   let nextRunReason = null;
   if (!regressionResult.next_run) {
     if (triggers.length === 0) nextRunReason = 'no_regression_triggers_declared';
@@ -1730,18 +1213,9 @@ function validate(playbookId, directiveId, analyzeResult, agentSignals = {}, run
   };
 }
 
-/**
- * Extended interval parser. Supports:
- *   <N>d   — N days
- *   <N>wk  — N weeks
- *   <N>mo  — N calendar months (Date.setMonth semantics)
- *   <N>yr  — N calendar years
- *   on_event — event-triggered, no date computed; surfaces in
- *              regression_event_triggers[] for the consumer.
- * Without all five forms, a playbook declaring "regression on every
- * release" or
- * "monthly review" lost its schedule entry.
- */
+// `<N>d`, `<N>wk`, `<N>mo` and `<N>yr` return a date, months and years by
+// Date.setMonth / setFullYear semantics. `on_event` computes no date and
+// surfaces in regression_event_triggers[]; anything else is { unparseable }.
 function parseInterval(intervalStr, now) {
   if (!intervalStr || typeof intervalStr !== 'string') return null;
   const s = intervalStr.trim();
@@ -1774,9 +1248,8 @@ function computeRegressionNextRun(triggers) {
     const parsed = parseInterval(t.interval, now);
     if (!parsed) continue;
     if (parsed.event) {
-      // Shipped playbooks key the trigger string as `condition`; `trigger` /
-      // `event` are accepted for external/fixture submissions. Reading only
-      // the latter two left regression_event_triggers[].trigger always null.
+      // Shipped playbooks key the trigger string as `condition`; `trigger` and
+      // `event` are the spellings external submissions and fixtures use.
       eventTriggers.push({ interval: t.interval, trigger: t.trigger || t.event || t.condition || null });
       continue;
     }
@@ -1793,51 +1266,28 @@ function computeRegressionNextRun(triggers) {
   };
 }
 
-// --- phase 7: close ---
-
-/**
- * Assemble the closure artifacts:
- *   - evidence_package (CSAF-2.0 shaped if requested; signed if signing key present)
- *   - learning_loop lesson template populated with current finding context
- *   - notification_actions with computed ISO 8601 deadlines from clock_starts + window_hours
- *   - exception_generation auditor-ready language if trigger fires
- *   - regression_schedule.next_run from validate.regression_next_run
- *   - feeds_into chaining suggestions
- */
+// Phase 7. The closure artifacts: the evidence_package (signed when a session
+// key is present), the learning_loop lesson, notification_actions with deadlines
+// from clock_starts + window_hours, the auditor-ready exception language, the
+// regression schedule and the feeds_into chaining suggestions.
 function close(playbookId, directiveId, analyzeResult, validateResult, agentSignals = {}, runOpts = {}) {
   const playbook = runOpts._playbookCache || loadPlaybook(playbookId);
   const c = resolvedPhase(playbook, directiveId, 'close');
   const g = resolvedPhase(playbook, directiveId, 'govern');
-  // F2/F9: run() generates session_id once and threads it via runOpts.session_id.
-  // Pre-fix, close() generated its own session_id independently of run()'s,
-  // so CSAF tracking.id, OpenVEX @id, the attestation file name on disk, and
-  // the run()-returned session_id were all different hex strings — operators
-  // couldn't correlate the attestation file with the bundle URN inside it.
-  // crypto.randomBytes() fallback only fires for direct close() calls that
-  // bypass run() (e.g. unit tests).
+  // run() mints session_id once and threads it here, so CSAF tracking.id, the
+  // OpenVEX @id and the on-disk attestation name are one identifier.
   const sessionId = runOpts.session_id || crypto.randomBytes(8).toString('hex');
 
-  // v0.12.27: when opt-in deterministic bundle mode is set, resolve the
-  // single frozen epoch used by every timestamp surface below. Cached for
-  // the whole close() call so notification_actions, regression_schedule,
-  // and the bundle emitter all agree on the same Date.
+  // One frozen epoch for every timestamp surface below, so notification_actions,
+  // regression_schedule and the bundle emitter agree on the same instant.
   const deterministic = runOpts.bundleDeterministic === true;
   const frozenEpoch = deterministic ? resolveFrozenEpoch(runOpts, playbook) : null;
 
-  // notification_actions — compute ISO deadlines from clock_starts events.
-  // v0.11.12 (#123): enrich each entry with the matched obligation's
-  // jurisdiction/regulation/window_hours/evidence_required fields. The
-  // playbook's notification_actions entry only carries `obligation_ref` +
-  // `draft_notification` + `recipient`; without enrichment, operators reading
-  // `jurisdiction_notifications[i].jurisdiction` got `undefined`. The
-  // upstream `govern.jurisdiction_obligations` has the real data — carry it
-  // forward. `notification_deadline` is published as an alias for `deadline`
-  // (matches the field name compliance teams expect on a notification record).
-  // Which engine phases completed in this run. analyze_complete /
-  // validate_complete jurisdictional clocks auto-start (under --ack) only when
-  // their named phase actually ran — by the time close() executes, a
-  // populated analyzeResult / validateResult proves the phase completed in the
-  // same synchronous pass.
+  // A playbook's notification_actions entry carries only obligation_ref,
+  // recipient and draft_notification; jurisdiction, regulation, window_hours
+  // and evidence_required merge in from the govern obligation below. The
+  // analyze_complete and validate_complete clocks auto-start only when a
+  // populated result proves their phase ran in this pass.
   const phaseFlags = {
     analyze_complete: !!(analyzeResult && typeof analyzeResult === 'object'),
     validate_complete: !!(validateResult && typeof validateResult === 'object'),
@@ -1847,29 +1297,23 @@ function close(playbookId, directiveId, analyzeResult, validateResult, agentSign
       o && typeof o === 'object' &&
       `${o.jurisdiction}/${o.regulation} ${o.window_hours}h` === na.obligation_ref
     );
-    // A non-empty obligation_ref that resolves to nothing leaves the
-    // jurisdiction / regulation / deadline fields null below — surface it as a
-    // runtime_error so the unmatched ref is observable, not a silent null record.
+    // An unresolved obligation_ref would leave the record's fields all null.
     if (!obligation && na && typeof na.obligation_ref === 'string' && na.obligation_ref &&
         Array.isArray(runOpts && runOpts._runErrors)) {
       pushRunError(runOpts._runErrors, { kind: 'unresolved_obligation_ref', obligation_ref: na.obligation_ref }, { dedupeKey: x => x.obligation_ref || '' });
     }
-    // Thread runOpts + the engine-computed classification through so
-    // computeClockStart can check operator_consent.explicit before
-    // auto-stamping detect_confirmed, and so an engine-confirmed detection
-    // starts the clock even without a separately-submitted classification.
+    // computeClockStart checks operator_consent.explicit before auto-stamping,
+    // and takes the engine classification so an engine-confirmed detection
+    // starts the clock without a separately submitted one.
     const engineClassification = analyzeResult?._detect_classification || null;
     const clockStart = obligation
       ? computeClockStart(obligation.clock_starts, agentSignals, runOpts, engineClassification, phaseFlags, frozenEpoch)
       : null;
-    // A valid clock is a real Date whose getTime() is finite. computeClockStart
-    // already returns null on an unparseable operator timestamp, but guard the
-    // arithmetic below independently so no caller (or future code path) can
-    // ever reach new Date(NaN).toISOString() and crash the close phase.
+    // Guarded independently of computeClockStart so no path reaches
+    // new Date(NaN).toISOString() and crashes the close phase.
     const clockValid = clockStart instanceof Date && !Number.isNaN(clockStart.getTime());
-    // Surface clock_pending_ack when an auto-startable event was confirmed but
-    // the operator did NOT pass --ack, so the notification record is visibly
-    // waiting on acknowledgement rather than silently stalled.
+    // An auto-startable event that fired without --ack leaves the record
+    // visibly waiting on acknowledgement rather than silently stalled.
     const autoStartEvent = obligation
       && (obligation.clock_starts === 'detect_confirmed'
         || obligation.clock_starts === 'analyze_complete'
@@ -1884,54 +1328,39 @@ function close(playbookId, directiveId, analyzeResult, validateResult, agentSign
       && autoStartEvent
       && eventReady
       && !(runOpts && runOpts.operator_consent && runOpts.operator_consent.explicit === true);
-    // window_hours must be a finite number before it enters the deadline
-    // arithmetic — a malformed obligation with an undefined/null/non-number
-    // window_hours would otherwise compute `getTime() + NaN` and crash the
-    // close phase at `new Date(NaN).toISOString()`. Runtime validation of the
-    // playbook is not enforced, so guard here independently of the schema.
+    // The playbook is not schema-validated at runtime, and a non-number
+    // window_hours computes `getTime() + NaN`, crashing close().
     const windowValid = obligation && typeof obligation.window_hours === 'number' && Number.isFinite(obligation.window_hours);
     const deadline = obligation && clockValid && windowValid
       ? new Date(clockStart.getTime() + obligation.window_hours * 3600 * 1000).toISOString()
       : 'pending_clock_start_event';
-    // A notification_action whose obligation_ref was specified but resolves to
-    // no obligation is an internally-inconsistent playbook (the schema requires
-    // obligation_ref to name a real govern obligation). The unmatched ref is
-    // already surfaced as a runtime_error above; drop the record rather than
-    // emit a null-jurisdiction/regulation entry that pollutes the deadline list.
+    // Already a runtime_error above; the record is dropped rather than
+    // polluting the deadline list with a null-jurisdiction entry.
     if (!obligation && na && typeof na.obligation_ref === 'string' && na.obligation_ref) {
       return null;
     }
     return {
       ...na,
-      // Carry obligation metadata forward so each notification entry is
-      // operationally usable on its own (calendar deadlines, regulator
-      // routing, evidence checklist).
+      // Each entry must stand alone: deadline, routing, evidence checklist.
       jurisdiction: obligation?.jurisdiction || null,
       regulation: obligation?.regulation || null,
       obligation_type: obligation?.obligation || null,
       window_hours: obligation?.window_hours ?? null,
       clock_start_event: obligation?.clock_starts || null,
-      // Use the validity gate, not optional-chaining: optional-chaining only
-      // short-circuits null/undefined, so a (hypothetical) Invalid Date would
-      // still reach .toISOString() and throw. clockValid guarantees a finite
-      // instant before we serialize.
+      // clockValid, not optional chaining: `?.` only short-circuits
+      // null/undefined, so an Invalid Date would still reach .toISOString().
       clock_started_at: clockValid ? clockStart.toISOString() : null,
       ...(clockPendingAck ? { clock_pending_ack: true } : {}),
       deadline,
       // Alias matching compliance-team vocabulary.
       notification_deadline: deadline,
-      // Evidence the regulator expects attached (from the obligation, not
-      // just the operator-facing recipient bundle on the notification entry).
+      // What the regulator expects attached, per the obligation.
       evidence_required: obligation?.evidence_required || na.evidence_attached || [],
-      // Track missing interpolation variables so operators see exactly
-      // which template vars failed to resolve. Empty array when all
-      // placeholders rendered cleanly.
+      // Which template vars failed to resolve; empty when all rendered.
       ...(function () {
         const missing = [];
-        // analyzeFindingShape is a pure transform but defensive-wrap it
-        // so a malformed analyze result (missing matched_cves, etc.)
-        // can't bring down the whole close phase. Failures surface in
-        // runtime_errors via runOpts._runErrors when available.
+        // Wrapped so a malformed analyze result cannot bring down close();
+        // the failure surfaces through runOpts._runErrors instead.
         let findingShape;
         try { findingShape = analyzeFindingShape(analyzeResult); }
         catch (e) {
@@ -1949,27 +1378,17 @@ function close(playbookId, directiveId, analyzeResult, validateResult, agentSign
       })(),
     };
   };
-  // enrichNotification returns null for an unresolved specified obligation_ref
-  // (already surfaced as a runtime_error); filter those out so the notification
-  // list never carries a null-jurisdiction record.
   const notificationActions = (c.notification_actions || []).map(enrichNotification).filter(Boolean);
 
-  // A govern obligation that declares a notification duty but has no
-  // matching close.notification_actions entry would otherwise never surface
-  // in the phase-7 record set — its regulatory clock stays invisible to
-  // operators reading jurisdiction_notifications. Synthesize a record for
-  // each uncovered notify-type obligation so the deadline is computed and
-  // visible. The synthesized entry carries no draft template (the playbook
-  // declared none) and is marked synthesized_from_obligation so operators
-  // can tell it apart from a playbook-authored action.
+  // A notify obligation with no matching close.notification_actions entry would
+  // leave its regulatory clock invisible. The synthesized record carries no
+  // draft and is marked synthesized_from_obligation.
   const coveredObligationRefs = new Set((c.notification_actions || []).map(na => na.obligation_ref));
   for (const o of (g.jurisdiction_obligations || [])) {
     if (!o || typeof o !== 'object') continue; // skip a null/malformed obligation rather than crash close() during synthesis
     if (!String(o.obligation || '').startsWith('notify')) continue;
-    // A notify obligation with a non-number window_hours is malformed: it would
-    // synthesize a "…/… undefinedh" ref and could not produce a real deadline.
-    // Surface it as a runtime_error and skip synthesis rather than emit a bogus
-    // record (the deadline guard in enrichNotification also prevents the crash).
+    // A non-number window_hours would synthesize a "…/… undefinedh" ref that
+    // can never produce a deadline; surface it and skip the synthesis.
     if (typeof o.window_hours !== 'number' || !Number.isFinite(o.window_hours)) {
       if (Array.isArray(runOpts && runOpts._runErrors)) {
         pushRunError(runOpts._runErrors, { kind: 'malformed_obligation_window_hours', obligation: `${o.jurisdiction}/${o.regulation}` }, { dedupeKey: x => x.obligation || '' });
@@ -1987,23 +1406,15 @@ function close(playbookId, directiveId, analyzeResult, validateResult, agentSign
     if (synthesized) notificationActions.push(synthesized);
   }
 
-  // exception_generation — evaluate trigger.
   let exception = null;
   if (c.exception_generation) {
     const closeEvalCtx = runOpts._runErrors ? { ...agentSignals, _runErrors: runOpts._runErrors } : agentSignals;
     const triggered = evalCondition(c.exception_generation.trigger_condition, closeEvalCtx, playbook);
     if (triggered) {
       const t = c.exception_generation.exception_template;
-      // Track unresolved ${placeholder} tokens the SAME way the draft_notification
-      // render does (missing_interpolation_vars). Exception-template tokens are
-      // operator-fill values (affected_host_count, compensating_controls,
-      // patch_available_status, …) that analyzeFindingShape does NOT supply and
-      // that operators rarely pre-stage on the standard `exceptd run` path, so the
-      // auditor-ready risk-acceptance language otherwise ships literal
-      // `<MISSING:…>` tokens with no machine-readable signal of which placeholders
-      // failed. Surface them as exception.missing_interpolation_vars (empty when
-      // all resolved) so a `ci`/JSON consumer — and the operator filling the
-      // exception — sees exactly what still needs a value.
+      // Exception-template tokens are operator-fill values analyzeFindingShape
+      // does not supply, so the auditor-ready language routinely renders
+      // `<MISSING:…>`. missing_interpolation_vars names which.
       const exMissing = [];
       const findingShape = (() => { try { return analyzeFindingShape(analyzeResult); } catch { return {}; } })();
       exception = {
@@ -2017,16 +1428,15 @@ function close(playbookId, directiveId, analyzeResult, validateResult, agentSign
           framework_id: playbook.domain.frameworks_in_scope[0] || 'unspecified',
           control_id: analyzeResult.framework_gap_mapping?.[0]?.claimed_control || 'unspecified',
           ciso_name: agentSignals.ciso_name || '<CISO NAME>',
-          // v0.12.27: deterministic mode roots acceptance_date in the
-          // frozen epoch so two runs against the same evidence emit the
-          // same auditor-facing date.
+          // Deterministic mode roots the auditor-facing date in the frozen
+          // epoch, so two runs over the same evidence agree.
           acceptance_date: (deterministic ? frozenEpoch : new Date().toISOString()).slice(0, 10),
           duration_expiry: agentSignals.duration_expiry || 'until vendor patch'
         }, exMissing),
         missing_interpolation_vars: exMissing,
       };
-      // Make the unresolved-placeholder gap observable to JSON/ci consumers, not
-      // just present on the exception object.
+      // Also on runtime_errors, so JSON/ci consumers see the gap without
+      // walking into the exception object.
       if (exMissing.length && Array.isArray(runOpts._runErrors)) {
         pushRunError(runOpts._runErrors,
           { kind: 'exception_unresolved_placeholders', placeholders: exMissing.slice() },
@@ -2035,26 +1445,15 @@ function close(playbookId, directiveId, analyzeResult, validateResult, agentSign
     }
   }
 
-  // evidence_package — playbook declares one primary bundle_format; the
-  // operator may request additional formats via agentSignals._bundle_formats
-  // (e.g. SARIF for GitHub Code Scanning + OpenVEX for supply-chain tooling
-  // alongside the CSAF default).
   const primaryFormat = c.evidence_package?.bundle_format || 'csaf-2.0';
   const extraFormats = Array.isArray(agentSignals._bundle_formats)
     ? agentSignals._bundle_formats.filter(f => f !== primaryFormat)
     : [];
-  // Build every bundle once and reuse, so bundle_body and
-  // bundles_by_format[primary] share object identity (and timestamps).
-  // Without memoisation, buildEvidenceBundle gets invoked twice for the
-  // primary format and each invocation crystallises a fresh Date.now() —
-  // operators diffing bundle_body against bundles_by_format.<primary> see
-  // spurious millisecond drift on tracking.initial_release_date /
-  // timestamp / current_release_date.
+  // Each bundle is built once, so bundle_body and bundles_by_format[primary]
+  // share identity — a second build would crystallise a fresh Date.now().
   const evidencePackage = c.evidence_package ? (() => {
-    // v0.12.27: deterministic mode pins issuedAt to the frozen epoch so
-    // CSAF tracking.{initial_release_date,current_release_date,
-    // generator.date,revision_history[0].date} and OpenVEX timestamp +
-    // statements[].timestamp all collapse to a single, byte-stable value.
+    // Deterministic mode pins issuedAt so every CSAF tracking date and every
+    // OpenVEX timestamp collapses to one byte-stable value.
     const issuedAt = deterministic ? frozenEpoch : new Date().toISOString();
     const builtFormats = new Map();
     const buildOnce = (format) => {
@@ -2064,12 +1463,8 @@ function close(playbookId, directiveId, analyzeResult, validateResult, agentSign
       return builtFormats.get(format);
     };
     const primaryBody = buildOnce(primaryFormat);
-    // bundles_by_format must always be an object keyed by the
-    // primary format, even when no extra formats were requested. Pre-fix it
-    // was null in the single-format case, forcing downstream tooling into a
-    // `bundles_by_format ?? { [primaryFormat]: bundle_body }` shim in every
-    // consumer. Now the field is canonically present so iteration is
-    // uniform across single- and multi-format emissions.
+    // Always an object keyed by the primary format, even for a single format,
+    // so consumers iterate uniformly instead of shimming a null.
     const byFormat = Object.fromEntries(
       [primaryFormat, ...extraFormats].map(f => [f, buildOnce(f)])
     );
@@ -2095,7 +1490,6 @@ function close(playbookId, directiveId, analyzeResult, validateResult, agentSign
     evidencePackage.signature_pending = 'No session_key provided. Sign with Ed25519 via `node $(exceptd path)/lib/sign.js sign-evidence <bundle.json>` post-emit (contributor checkout) or `exceptd doctor --fix` to enable signing.';
   }
 
-  // learning_loop lesson
   const lesson = c.learning_loop?.enabled ? {
     enabled: true,
     attack_vector: interpolate(c.learning_loop.lesson_template.attack_vector, analyzeFindingShape(analyzeResult)),
@@ -2106,19 +1500,12 @@ function close(playbookId, directiveId, analyzeResult, validateResult, agentSign
     proposed_for_zeroday_lessons_id: `lesson-${playbook._meta.id}-${sessionId}`
   } : { enabled: false };
 
-  // regression_schedule
-  //
-  // v0.12.27: deterministic mode re-derives next_run from the frozen epoch
-  // rather than wall-clock-now-at-validate-time. Without this, two runs
-  // against the same evidence diverge on next_run by the interval between
-  // the two `validate()` invocations. Frozen base + the same interval set
-  // = byte-identical schedule.
+  // Re-derived from the frozen epoch: taken from wall-clock-at-validate-time,
+  // two runs diverge by the interval between their validate() calls.
   const regressionSchedule = c.regression_schedule ? (() => {
     let nextRun = validateResult.regression_next_run;
     if (deterministic) {
-      // Re-derive against the validate phase's trigger set (not the
-      // close phase's regression_schedule subtree — close has no triggers
-      // of its own, just the canonical interval declared upstream).
+      // Against the validate phase's triggers — close declares none of its own.
       const v = resolvedPhase(playbook, directiveId, 'validate');
       nextRun = frozenRegressionNextRun(v.regression_trigger || [], new Date(frozenEpoch));
     }
@@ -2129,69 +1516,35 @@ function close(playbookId, directiveId, analyzeResult, validateResult, agentSign
     };
   })() : null;
 
-  // feeds_into chaining — full analyze result is exposed so conditions can
-  // reference `analyze.compliance_theater_check.verdict` etc.
+  // The whole analyze result, so conditions can reference `analyze.*` paths.
   const feedsCtx = {
-    // Fired detect indicators (verdict 'hit') mirrored in so a feeds_into
-    // condition written as `<indicator-id> == true` resolves on the standard
-    // collector path (signal_overrides), not only when the id is re-submitted
-    // under signals. Lowest precedence — operator signals and engine values win.
+    // Lowest precedence, so a feeds_into condition written as
+    // `<indicator-id> == true` resolves on the standard collector path.
     ...firedIndicatorSignals(analyzeResult && analyzeResult._detect_indicators),
-    // Operator-submitted signals come FIRST so the engine-computed reserved
-    // keys below always win — otherwise a submitted signals.rwep / finding /
-    // analyze would override the engine value the feeds_into condition tests
-    // and could suppress a legitimate downstream chain.
+    // Operator signals FIRST so the engine keys below win: a submitted
+    // signals.rwep must not override the value the condition tests.
     ...agentSignals,
     rwep: analyzeResult.rwep?.adjusted,
-    // Bare-token parity with the escalation context (analyze()): catalog
-    // feeds_into conditions reference the unqualified tokens `blast_radius_score`
-    // and `theater_verdict` (e.g. framework.json's feeds_into into sbom). Without
-    // these top-level keys resolvePath returns null and `null >= 4` is false
-    // regardless of the engine-computed blast radius, so the chain is dead. They
-    // are spread AFTER ...agentSignals so the engine value wins over any
-    // operator-submitted signals.blast_radius_score / signals.theater_verdict.
+    // Bare-token parity with the escalation context: catalog conditions write
+    // these unqualified, and without the top-level keys resolvePath returns
+    // null, so `null >= 4` kills the chain whatever the engine computed.
     blast_radius_score: analyzeResult.blast_radius_score,
     theater_verdict: analyzeResult.compliance_theater_check?.verdict,
-    // Bare top-level `compliance_theater_check` so catalog conditions that
-    // reference `compliance_theater_check.verdict` unqualified (framework.json's
-    // feeds_into into sbom) resolve — without it resolvePath returns null and the
-    // clause is dead regardless of the engine verdict. The `analyze.*` alias
-    // below stays for conditions that use the qualified path.
     compliance_theater_check: analyzeResult.compliance_theater_check,
-    // Govern-phase jurisdiction obligations so feeds_into conditions like
-    // `… AND jurisdiction_obligations contains 'EU'` (framework → sbom) resolve.
     jurisdiction_obligations: (g && g.jurisdiction_obligations) || (playbook.phases && playbook.phases.govern && playbook.phases.govern.jurisdiction_obligations) || [],
-    // theater_score follows lib/framework-gap.js's convention: HIGH = more
-    // theater detected (worse). A 'theater' verdict (a gap exists) is the
-    // concerning case, so it scores 100; a clear verdict scores 0. (Earlier
-    // this was inverted, so a feeds_into condition like `theater_score >= 50`
-    // would have failed to fire exactly when a gap was found.)
-    // 'present' is an allowlisted theater-equivalent verdict (the same
-    // gap-present set verdict_text uses at line 1426 and the allowlist comment
-    // names at line 1352-1353), so it must score 100 (gap detected = worse), not
-    // 0. Scoring only the 'theater' spelling left a 'present' verdict scored as
-    // clear — inverted for any future feeds_into condition gating on theater_score.
+    // theater_score follows lib/framework-gap.js: high means more theater, so a
+    // gap-present verdict scores 100 and 'clear' scores 0. 'present' is the
+    // allowlisted synonym for 'theater' and must score with it.
     theater_score: (analyzeResult.compliance_theater_check?.verdict === 'theater' || analyzeResult.compliance_theater_check?.verdict === 'present') ? 100 : 0,
-    // Top-level matched_cve array so the shipped sbom feeds_into quantifiers
-    // (`any matched_cve.attack_class == 'kernel-lpe'`, … IN ['ai-c2', …]) re-root
-    // at each matched CVE. Without it the quantifier head resolves null and the
-    // sbom -> kernel/mcp/ai-api deep-dive chains stay dead even when a matched
-    // CVE carries the attack_class. The `analyze.matched_cves` alias stays for
-    // conditions that use the qualified path.
+    // The head the sbom feeds_into quantifiers re-root at; without the
+    // top-level key it resolves null and the deep-dive chains stay dead.
     matched_cve: analyzeResult.matched_cves || [],
     analyze: analyzeResult,
     validate: validateResult,
-    // finding.* is two-sourced: the engine computes the CVE/severity-derived keys
-    // via analyzeFindingShape; the DESCRIPTIVE keys the catalog feeds_into
-    // conditions gate on (finding.includes_*, cve_class, tool_surface,
-    // mcp_server_location, pipeline_credentials_in_scope, …) are host-AI-asserted.
-    // Merge the agent-supplied finding sub-fields UNDER the engine shape so the
-    // descriptive keys survive while engine-owned keys WIN on collision. Same
-    // shape + guards as the escalation ctx above.
+    // Same two-sourced finding.* shape and guards as the escalation context.
     finding: { ...(agentSignals.finding && typeof agentSignals.finding === 'object' && !Array.isArray(agentSignals.finding) ? agentSignals.finding : {}), ...analyzeFindingShape(analyzeResult) },
-    // Surface evalCondition regex failures from the feeds_into chain into
-    // the same accumulator. Without this the regex failure happens but
-    // analyze.runtime_errors[] never sees it.
+    // Without the accumulator, a feeds_into condition failure never reaches
+    // analyze.runtime_errors[].
     ...(runOpts._runErrors ? { _runErrors: runOpts._runErrors } : {})
   };
   const feeds = (playbook._meta.feeds_into || [])
@@ -2205,32 +1558,22 @@ function close(playbookId, directiveId, analyzeResult, validateResult, agentSign
     evidence_package: evidencePackage,
     learning_loop: lesson,
     notification_actions: notificationActions,
-    // v0.11.10 (#104): operators expected the field name
-    // `jurisdiction_notifications`. Surface it as an alias for the full
-    // notification_actions list, plus a `jurisdiction_clocks_count` that
-    // mirrors `ci.summary.jurisdiction_clocks_started` — the count of
-    // notifications whose clock has actually started (clock_started_at != null).
+    // Alias for notification_actions. jurisdiction_clocks_count mirrors
+    // ci.summary.jurisdiction_clocks_started — those whose clock has started.
     jurisdiction_notifications: notificationActions,
     jurisdiction_clocks_count: notificationActions.filter(n => n && n.clock_started_at != null).length,
     exception: exception,
     regression_schedule: regressionSchedule,
     feeds_into: feeds,
-    // feeds_into surfaces downstream playbook IDs whose preconditions
-    // were satisfied by this run. The runner does NOT automatically chain
-    // into them — the agent / operator decides whether to invoke them.
-    // Surface that contract on the result so consumers don't assume an
-    // automated handoff happened.
+    // The runner never chains into feeds_into itself; the agent or operator
+    // decides. Stated on the result so no consumer assumes a handoff happened.
     feeds_into_auto_chained: false,
   };
 }
 
-// Severity ladder for active_exploitation. The worst-of reduction lets
-// analyzeFindingShape report the most-exploited CVE in the matched set, not
-// the first-encountered one. Higher index = worse.
-// `theoretical` (PoC exists, no in-the-wild use) must rank between `none` and
-// `unknown`; omitting it made `?? -1` lose to the -1 start, so an all-theoretical
-// matched set wrongly reduced to 'unknown' and a theoretical+none set dropped
-// the theoretical entry entirely. This vocabulary is first-class in scoring.js.
+// Severity ladder for active_exploitation, higher being worse. Every value in
+// scoring.js's vocabulary must appear — an omitted one falls to `?? -1`, loses
+// to the -1 start, and drops out of the reduction entirely.
 const ACTIVE_EXPLOITATION_RANK = { none: 0, theoretical: 1, unknown: 2, suspected: 3, confirmed: 4 };
 
 function worstActiveExploitation(matchedCves) {
@@ -2242,19 +1585,13 @@ function worstActiveExploitation(matchedCves) {
     const rank = ACTIVE_EXPLOITATION_RANK[v] ?? -1;
     if (rank > worstRank) { worst = v; worstRank = rank; }
   }
-  // Empty / all-unrecognized matched set → 'none' (a draft must not assert
-  // 'unknown' exploitation it never observed).
+  // An empty or all-unrecognized set is 'none': a draft must not assert
+  // 'unknown' exploitation it never observed.
   return worst || 'none';
 }
 
-// Severity ladder derived from rwep_adjusted. Playbooks reference
-// `finding.severity` in feeds_into and escalation_criteria conditions;
-// emit it so those conditions resolve against a real value rather than
-// undefined. Thresholds:
-//   rwep >= 80 → critical
-//   rwep >= 50 → high
-//   rwep >= 20 → medium
-//   rwep <  20 → low
+// The value playbooks gate on as `finding.severity` in feeds_into and
+// escalation_criteria; without it those conditions resolve undefined.
 function severityForRwep(rwep) {
   const r = typeof rwep === 'number' ? rwep : 0;
   if (r >= 80) return 'critical';
@@ -2268,23 +1605,17 @@ function analyzeFindingShape(a) {
   const rwepAdjusted = a.rwep?.adjusted ?? 0;
   return {
     matched_cve_ids: matched.map(c => c.cve_id).join(', '),
-    // Sibling array form for consumers that want to iterate IDs without
-    // re-splitting the joined string. The joined form stays for backwards
-    // compatibility with notification-draft templates that interpolate
-    // `${matched_cve_ids}` verbatim.
+    // The joined form is what notification-draft templates interpolate as
+    // `${matched_cve_ids}`; this is for consumers that want to iterate.
     matched_cve_ids_array: matched.map(c => c.cve_id),
     matched_cve_count: matched.length,
     kev_listed_count: matched.filter(c => c.cisa_kev).length,
-    // Reduce active_exploitation to the worst rank across all matched
-    // CVEs. A .find() lookup would return the first truthy entry — e.g.
-    // 'suspected' on CVE #1 when CVE #2 is 'confirmed' — under-stating
-    // the threat in notification drafts.
-    // Exclude VEX-fixed (vendor-patched) CVEs: a notification draft must not
-    // assert active exploitation sourced from an already-remediated CVE.
+    // Worst rank, not the first truthy entry: a draft reporting 'suspected'
+    // while another CVE is 'confirmed' understates the threat. VEX-fixed CVEs
+    // are excluded — a draft must not source exploitation from a fixed CVE.
     active_exploitation: worstActiveExploitation(matched.filter(c => c.vex_status !== 'fixed')),
     rwep_adjusted: rwepAdjusted,
     rwep_base: a.rwep?.base ?? 0,
-    // Severity surface for playbook conditions.
     severity: severityForRwep(rwepAdjusted),
     blast_radius_score: a.blast_radius_score ?? 0,
     framework_id_first: a.framework_gap_mapping?.[0]?.framework || null,
@@ -2292,18 +1623,10 @@ function analyzeFindingShape(a) {
   };
 }
 
-// Map a vulnerability identifier to its issuing authority + the canonical
-// human-readable advisory URL for that authority. CVE ids resolve to NVD;
-// GHSA/OSV/RUSTSEC/SNYK each have their own advisory database. A MAL- malicious
-// -package id has no public per-id advisory page, so helpUri is null (the id is
-// still labelled with its system_name). An unrecognised prefix resolves to a
-// null helpUri rather than a fabricated link.
-//
-// Used by the SARIF rule emitter (helpUri) so non-CVE matched ids no longer
-// get a hardcoded nvd.nist.gov/vuln/detail/<id> URL — that URL 404s for every
-// MAL-/GHSA-/OSV-/RUSTSEC- id and mislabels it as an NVD CVE. The same
-// prefix→authority knowledge lives in the CSAF ids[] branch (csafIdsFor); both
-// derive from this table so the two exports cannot drift.
+// A vulnerability identifier's issuing authority and canonical advisory URL. An
+// id with no public per-id page, and an unrecognised prefix, both resolve to a
+// null helpUri rather than a fabricated link: an nvd.nist.gov URL 404s for a
+// non-CVE id. The CSAF ids[] branch (csafIdsFor) carries the same knowledge.
 const CVE_ID_RE = /^CVE-\d{4}-\d{4,}$/;
 function advisoryAuthorityFor(id) {
   if (typeof id !== 'string' || !id) return { system_name: null, helpUri: null };
@@ -2312,21 +1635,17 @@ function advisoryAuthorityFor(id) {
   if (id.startsWith('OSV-')) return { system_name: 'OSV', helpUri: `https://osv.dev/vulnerability/${id}` };
   if (id.startsWith('RUSTSEC-')) return { system_name: 'RUSTSEC', helpUri: `https://rustsec.org/advisories/${id}.html` };
   if (id.startsWith('SNYK-')) return { system_name: 'Snyk', helpUri: `https://security.snyk.io/vuln/${id}` };
-  // Malicious-package ids have no canonical per-id advisory page; label the
-  // authority but emit no link rather than a fabricated NVD URL.
   if (id.startsWith('MAL-')) return { system_name: 'Malicious-Package', helpUri: null };
   return { system_name: 'exceptd-unknown', helpUri: null };
 }
 
-// Route a vulnerability identifier to its registry-specific URN namespace.
-// CVE-/GHSA-/RUSTSEC-/MAL-* identifiers each have a registered URN namespace;
-// unrecognised prefixes route to the `urn:exceptd:advisory:` private
-// namespace so OpenVEX statements still carry a valid IRI per RFC 8141.
+// Route a vulnerability identifier to its registered URN namespace, or to the
+// private `urn:exceptd:advisory:` one, so every OpenVEX statement carries a
+// valid IRI per RFC 8141.
 function vulnIdToUrn(id) {
   if (typeof id !== 'string' || id.length === 0) return `urn:exceptd:advisory:${urnSlug(id)}`;
-  // Registered identifiers keep their canonical case in the NSS so the @id
-  // matches the OpenVEX `name` / CSAF id exactly. The private advisory
-  // namespace slugs arbitrary text, so it stays lowercase.
+  // Registered identifiers keep their canonical case so the @id matches the
+  // OpenVEX `name` / CSAF id; the private namespace slugs text and lowercases.
   const canonical = urnSlug(id, true);
   if (/^CVE-/i.test(id)) return `urn:cve:${canonical}`;
   if (/^GHSA-/i.test(id)) return `urn:ghsa:${canonical}`;
@@ -2335,26 +1654,16 @@ function vulnIdToUrn(id) {
   return `urn:exceptd:advisory:${urnSlug(id)}`;
 }
 
-// Build a CSAF product_tree.branches[] tree (vendor → product_name →
-// product_version). Sources of vendor/product/version, in priority order:
-//   (1) catalog entry `affected_products: [{ vendor, product, version }]`
-//   (2) heuristic parse of `affected_components[]` strings — accepts
-//       `vendor/product@version` and `vendor product version` shapes.
-// Unparseable component strings emit a `csaf_branch_unparseable` runtime
-// error and are dropped from the tree. Sort alphabetical at each level so
-// the output is deterministic across runs.
-//
-// Returns `{ branches, productIds }`. productIds is a stable enumeration
-// CSAFPID-0..N keyed by (vendor, product, version) insertion order so other
-// emit paths can reference the leaf products by id later.
+// Build a CSAF product_tree.branches[] from the catalog's `affected_products`
+// records, falling back to a heuristic parse of `affected_components[]`.
+// Unparseable components raise `csaf_branch_unparseable` and drop; each level
+// sorts alphabetically for determinism. Returns { branches, productIds,
+// cveProductIds }, the last binding each CVE to the leaves it contributed so
+// the caller can reference them from vulnerabilities[].product_status.
 function buildCsafBranches(matchedCves, runOpts) {
-  // Build a (vendor → product → Set<version>) map.
   const tree = new Map();
-  // Track which CVE contributed each leaf so the emitted CSAFPID-N product_ids
-  // can be bound back into that CVE's vulnerabilities[].product_status — without
-  // this the branch tree's per-version products are referenced by nothing and a
-  // CSAF consumer correlating product_status to the tree resolves only the
-  // generic synthetic product. leafKey = vendor\0product\0version.
+  // Without the per-CVE binding the version leaves are referenced by nothing,
+  // and product_status correlates only to the synthetic product.
   const leafKey = (vendor, product, version) => JSON.stringify([vendor, product, version]);
   const cveLeaves = new Map(); // cve_id → Set<leafKey>
   const addLeaf = (vendor, product, version, cveId) => {
@@ -2369,13 +1678,11 @@ function buildCsafBranches(matchedCves, runOpts) {
     }
   };
 
-  // Comparison / range operators that appear between a package name and a
-  // version in the catalog's dominant `package OP version` affected_versions
-  // shape (e.g. "linux-kernel >= 4.14", "runc <= 1.1.11", "litellm < 1.83.7").
-  // These are operators, never package names.
+  // What sits between package and version in the catalog's dominant
+  // `package OP version` shape. These are never package names.
   const RANGE_OP_RE = /^(<=|>=|==|!=|~>|<|>|=|~|\^)$/;
 
-  // Heuristic parser. Returns { vendor, product, version } or null.
+  // Returns { vendor, product, version } or null.
   const parseComponentString = (s) => {
     if (typeof s !== 'string' || !s.trim()) return null;
     const trimmed = s.trim();
@@ -2383,27 +1690,19 @@ function buildCsafBranches(matchedCves, runOpts) {
     let m = trimmed.match(/^([^/\s@]+)\/([^/\s@]+)@(.+)$/);
     if (m) return { vendor: m[1], product: m[2], version: m[3].trim() };
     const parts = trimmed.split(/\s+/);
-    // `package OP version` — the catalog's dominant shape. The token before
-    // the version is a comparison/range operator, so the PACKAGE is the
-    // product name and the operator belongs to the version qualifier, not the
-    // product_name. Pre-fix this split named the product after the operator
-    // ('>=', '<', '=='), corrupting the CSAF affected-product list. Carry the
-    // operator into the version string ('>= 4.14') so the range qualifier
-    // survives while the product_name stays the real package. Multiple leading
-    // operator tokens (a compound range emitted as one string) collapse into
-    // the version qualifier too.
+    // `package OP version`. The operator belongs to the version qualifier
+    // ('>= 4.14'), not the product_name — naming the product after '>=' or '<'
+    // corrupts the CSAF affected-product list.
     if (parts.length >= 3 && RANGE_OP_RE.test(parts[1])) {
       const product = parts[0];
       const versionTokens = parts.slice(1);
-      // Only accept the shape when the trailing token is an actual version
-      // (starts with a digit or v\d) — otherwise it isn't a `package OP version`.
+      // The shape only holds when the trailing token really is a version.
       const lastTok = versionTokens[versionTokens.length - 1];
       if (/^v?\d/.test(lastTok)) {
         return { vendor: product, product, version: versionTokens.join(' ') };
       }
     }
-    // `vendor product version` — exactly three whitespace-separated tokens
-    // where the last token starts with a digit or `v\d`.
+    // `vendor product version`, where the last token starts with a digit or `v\d`.
     if (parts.length >= 3) {
       const last = parts[parts.length - 1];
       if (/^v?\d/.test(last)) {
@@ -2438,7 +1737,6 @@ function buildCsafBranches(matchedCves, runOpts) {
     }
   }
 
-  // Sort + emit.
   const productIds = [];
   const leafKeyToPid = new Map();
   let pidCounter = 0;
@@ -2471,8 +1769,6 @@ function buildCsafBranches(matchedCves, runOpts) {
       }),
     };
   });
-  // Per-CVE CSAFPID binding so the caller can add the version leaves to each
-  // vulnerability's product_status.known_affected.
   const cveProductIds = {};
   for (const [cveId, keys] of cveLeaves.entries()) {
     const pids = [];
@@ -2482,11 +1778,9 @@ function buildCsafBranches(matchedCves, runOpts) {
   return { branches, productIds, cveProductIds };
 }
 
-// Slugify a string into a URN-safe segment (RFC 8141 NSS). Empty input →
-// 'unknown' so we never emit zero-length segments. preserveCase keeps the
-// canonical case of registered identifiers (e.g. CVE-2026-43284) — the NSS is
-// case-sensitive per RFC 8141, and the OpenVEX `name`/CSAF id fields carry the
-// canonical case, so the URN @id must match rather than fold to lowercase.
+// Slugify into a URN-safe segment (RFC 8141 NSS); empty input returns
+// 'unknown', never a zero-length segment. The NSS is case-sensitive, so
+// preserveCase keeps a registered identifier matching its OpenVEX / CSAF form.
 function urnSlug(s, preserveCase = false) {
   if (s == null) return 'unknown';
   let str = String(s);
@@ -2497,10 +1791,9 @@ function urnSlug(s, preserveCase = false) {
   return slug.length ? slug : 'unknown';
 }
 
-// Build the canonical product binding shared by CSAF + OpenVEX. CSAF's
-// product_tree must declare every product referenced from
-// vulnerabilities[].product_status; OpenVEX statements MUST carry a
-// `products` array per spec §4.3.
+// The product binding CSAF and OpenVEX share: product_tree must declare every
+// product product_status references, and an OpenVEX statement MUST carry a
+// `products` array (spec §4.3).
 function buildProductBinding(playbook, sessionId) {
   const playbookSlug = urnSlug(playbook._meta.id);
   const sessionSlug = urnSlug(sessionId || 'session');
@@ -2513,30 +1806,10 @@ function buildProductBinding(playbook, sessionId) {
   };
 }
 
-// Best-effort SARIF location list for an indicator hit. Indicator records
-// don't carry a direct artifact reference; we fall back to the playbook's
-// look-phase artifact source paths (the inspected files/processes). GitHub
-// Code Scanning hides results without `artifactLocation.uri`, so we
-// surface at least one candidate when any is known. Returns null when no
-// candidate exists — caller MUST omit `locations` rather than emit empty.
-//
-// Source segments are heterogeneous — many playbook artifacts
-// describe a shell-command capture (`uname -r`) or human prose, not a real
-// file or URI. SARIF `artifactLocation.uri` is defined as a URI reference
-// (RFC 3986); shell-command text + prose breaks downstream consumers
-// (GitHub Code Scanning rejects with "invalid URI" or renders garbled).
-// We accept only path-shaped candidates: absolute POSIX paths, `~`-home
-// paths, relative paths, drive-prefixed Windows paths, or file-URI
-// strings. Everything else (commands, English) is dropped, and locations
-// is omitted entirely when no candidate survives.
-// Path-shape predicate: accept anything that begins with a POSIX absolute
-// path (`/...`), home (`~/...` or `~`), relative dot (`./...`, `../...`,
-// or a bare `.`), drive-prefixed Windows path (`C:\...`, `C:/...`), or a
-// `file:` URI. Also accept simple relative names that contain a slash
-// (e.g. `etc/os-release`, `subdir/file.json`) — these are common in
-// playbook artifact source fields. Reject anything with internal
-// whitespace (commands like `uname -r`, prose like `kpatch list || ls
-// /sys/kernel/livepatch`) or that looks like a sentence.
+// Path-shape predicate for a SARIF artifactLocation.uri candidate. A
+// look-artifact `source` is as often a shell command or prose as a file, and
+// SARIF requires an RFC 3986 URI reference — anything with internal whitespace
+// is a command or a sentence, not a path.
 function looksLikePath(src) {
   if (typeof src !== 'string') return false;
   const trimmed = src.trim();
@@ -2549,20 +1822,16 @@ function looksLikePath(src) {
   if (/^[A-Za-z0-9_.+-]+[/\\][^\s]+$/.test(trimmed)) return true;  // bare relative path
   return false;
 }
+// Physical SARIF locations for an indicator hit, or null — on which the caller
+// must omit `locations` rather than emit an empty array. Submission-supplied
+// evidence_locations give a real file; look-artifact sources are the fallback.
 function sarifLocationsForIndicator(playbook, indicator) {
-  // Prefer per-indicator evidence locations the submission supplied (threaded
-  // onto the firing indicator by detect()). Each entry is a path string or
-  // { uri, startLine?, endLine? }. This is what gives SARIF results a real
-  // file location instead of the coarse playbook-source fallback below.
   const ev = indicator && Array.isArray(indicator.evidence_locations) ? indicator.evidence_locations : null;
   if (ev && ev.length) {
     const locs = [];
     for (const e of ev) {
-      // SARIF artifactLocation.uri is a URI reference (RFC 3986) — the path
-      // separator must be `/`. Operator/agent-supplied evidence on Windows
-      // arrives with backslashes; normalize them so the emitted SARIF is
-      // valid (the collectors already normalize via buildEvidenceLocations,
-      // but submission-threaded locations bypass that path).
+      // artifactLocation.uri is an RFC 3986 reference, so the separator must be
+      // `/`; submission-threaded locations bypass the collectors' normalization.
       if (typeof e === "string" && e.trim()) {
         locs.push({ physicalLocation: { artifactLocation: { uri: e.trim().replace(/\\/g, "/") } } });
       } else if (e && typeof e === "object" && typeof e.uri === "string" && e.uri.trim()) {
@@ -2586,27 +1855,18 @@ function sarifLocationsForIndicator(playbook, indicator) {
   return [{ physicalLocation: { artifactLocation: { uri: candidates[0] } } }];
 }
 
-// Locations for a finding-class SARIF result, with a guaranteed non-empty
-// fallback. sarifLocationsForIndicator returns a PHYSICAL location only when the
-// agent supplied evidence_locations or the playbook's look-artifact source is a
-// bare path token; the dominant catalog shape is a prose / glob / shell-command
-// source (which carries whitespace and is rejected by looksLikePath), so the
-// physical fallback is null for ~most playbooks. A SARIF result with no
-// `locations[]` is silently DROPPED by GitHub Code Scanning — so a result with
-// no concrete file still gets a `logicalLocations` entry naming its rule, which
-// is SARIF-conformant (§3.33), keeps the finding attributable + visible in the
-// alerts list and in SARIF viewers, and is honest (there is no physical file to
-// point at when the agent supplied no evidence location). Physical location is
-// always preferred when available.
+// Locations for a finding-class SARIF result, never empty: GitHub Code Scanning
+// silently DROPS a result with no `locations[]`, and most playbooks have no
+// physical location to give. A rule-naming `logicalLocations` entry is
+// SARIF-conformant (§3.33) and honest about there being no file to point at.
 function sarifResultLocations(playbook, indicator, fqRuleId) {
   const phys = sarifLocationsForIndicator(playbook, indicator);
   if (phys && phys.length) return phys;
   return [{ logicalLocations: [{ name: fqRuleId, fullyQualifiedName: fqRuleId, kind: 'rule' }] }];
 }
 
-// Resolve the package version once per process so CSAF tracking.generator
-// can name the engine that emitted the advisory. Best-effort read — bundle
-// emission must not crash if package.json is missing (e.g. exotic install).
+// The engine version CSAF tracking.generator names, resolved once per process.
+// Bundle emission must not crash on an install where package.json is unreadable.
 let _CACHED_PKG_VERSION = null;
 function getEngineVersion() {
   if (_CACHED_PKG_VERSION != null) return _CACHED_PKG_VERSION;
@@ -2619,16 +1879,9 @@ function getEngineVersion() {
   return _CACHED_PKG_VERSION;
 }
 
-// v0.12.27: deterministic-bundle epoch resolution. Priority:
-//   1. runOpts.bundleEpoch (operator-supplied --bundle-epoch <ISO>)
-//   2. playbook._meta.last_threat_review (the freshness anchor that already
-//      gates every shipped playbook — stable across re-runs of the same
-//      catalog version)
-//   3. '1970-01-01T00:00:00Z' fallback (effectively impossible in practice
-//      because every shipped playbook carries last_threat_review, but
-//      guarantees the deterministic path never crashes on a malformed
-//      playbook).
-// Returns a full ISO-8601 timestamp (date-only inputs are normalised).
+// The deterministic-bundle epoch: runOpts.bundleEpoch, then
+// playbook._meta.last_threat_review (stable across re-runs of one catalog
+// version), then 1970 so a malformed playbook cannot crash the path.
 function resolveFrozenEpoch(runOpts, playbook) {
   const raw = runOpts && runOpts.bundleEpoch
     ? runOpts.bundleEpoch
@@ -2638,11 +1891,8 @@ function resolveFrozenEpoch(runOpts, playbook) {
   catch { return '1970-01-01T00:00:00Z'; }
 }
 
-// Recompute regression_schedule.next_run against a frozen `now` so two
-// deterministic-mode runs of the same playbook produce byte-identical
-// schedules. Mirrors computeRegressionNextRun but with an injected base
-// date. Returns the soonest ISO timestamp or null when no interval-based
-// trigger fired.
+// computeRegressionNextRun against an injected base date, so two
+// deterministic-mode runs produce byte-identical schedules.
 function frozenRegressionNextRun(triggers, frozenNow) {
   let soonest = null;
   for (const t of (triggers || [])) {
@@ -2653,42 +1903,19 @@ function frozenRegressionNextRun(triggers, frozenNow) {
   return soonest ? soonest.toISOString() : null;
 }
 
-// Operator-supplied identity strings (--operator) and publisher namespace
-// URLs (--publisher-namespace) flow into operator-facing CSAF surfaces.
-// Strip ASCII control characters as defence in depth — bin/exceptd.js
-// already validates the CLI inputs, but the runner is also called from
-// library consumers that may bypass the CLI surface.
-//
-// Strip Unicode bidi / format / control / surrogate / private-use /
-// unassigned categories (\p{C} under the `u` regex flag) so direct
-// library callers of buildEvidenceBundle cannot smuggle a U+202E "RTL
-// OVERRIDE" or zero-width joiner past the sanitiser the way the CLI
-// already refuses. NFC-normalise first so a decomposed sequence can't
-// combine past the codepoint check; cap the result at 256 codepoints
-// (NOT UTF-16 code units) so a string of astral-plane codepoints can't
-// smuggle a longer-than-256-display string past the cap by exploiting
-// JavaScript's surrogate-pair string length. Returns null on rejection
-// (empty after strip, or NFC normalise threw); callers (the
-// publisher-namespace + contact_details + tracking.generator sites)
-// treat null as "operator-unclaimed" and route through the existing
-// fallback (publisher.namespace = urn:exceptd:operator:unknown +
-// bundle_publisher_unclaimed runtime warning).
+// --operator and --publisher-namespace land on operator-facing CSAF surfaces.
+// bin/exceptd.js validates the CLI inputs, but a library consumer bypasses it
+// and must not be able to smuggle a U+202E RTL OVERRIDE or a zero-width joiner
+// into a bundle. Null on rejection, which callers treat as operator-unclaimed.
 function sanitizeOperatorText(s) {
   if (typeof s !== 'string') return null;
-  // NFC first: a Cf codepoint may be expressed as a base + combining mark
-  // that recomposes into the format category under NFC. Normalise so the
-  // strip catches it.
+  // NFC first: a Cf codepoint can arrive as a base plus combining mark that
+  // only recomposes into the format category under normalisation.
   let normalised;
   try { normalised = s.normalize('NFC'); }
   catch { return null; }
-  // Two-pass strip. First remove the named threat families (bidi-override /
-  // C0-control / zero-width / null) via the shared vendored codepoint tables,
-  // so the family vocabulary has a single source of truth. Then strip any
-  // remaining General Category C codepoint: \p{C} (Cc/Cf/Cs/Co/Cn) is the
-  // backstop — it is strictly broader than the family union (also catches
-  // U+007F, U+0080-009F, private-use, unassigned), so the family pass is a
-  // documented-intent superset removal and the result is identical to the
-  // single \p{C} strip.
+  // The named threat families go through the shared vendored tables, so that
+  // vocabulary has one source of truth; \p{C} is the strictly broader backstop.
   const familyStripped = codepointClass.applyCharStripPolicies(normalised, {
     bidiPolicy: 'strip',
     controlPolicy: 'strip',
@@ -2698,79 +1925,33 @@ function sanitizeOperatorText(s) {
   const stripped = familyStripped.replace(/\p{C}/gu, '');
   const trimmed = stripped.trim();
   if (trimmed.length === 0) return null;
-  // Cap at 256 codepoints (Array.from counts codepoints, not UTF-16 code
-  // units, so a 256-codepoint astral-plane string isn't silently extended
-  // past the cap by surrogate-pair encoding).
+  // 256 CODEPOINTS, counted with Array.from: a `.length` cap measures UTF-16
+  // code units, so astral-plane text would slip a longer string past it.
   const cps = Array.from(trimmed);
   if (cps.length <= 256) return cps.join('');
   return cps.slice(0, 256).join('');
 }
 
 /**
- * Build a single evidence bundle in the requested machine-readable format.
- *
- * Positional contract — the seven phase functions cache the closure over
- * `playbook`, `analyze`, and `validate` so consumers don't reach into the
- * runner's intermediate state. Library callers that bypass close() (e.g.
- * external dashboards re-rendering a stored attestation) MUST honor the
- * same parameter order, names, and types.
- *
- * @param {string}   format        Output dialect. One of: 'csaf-2.0',
- *                                 'sarif' / 'sarif-2.1.0', 'openvex' /
- *                                 'openvex-0.2.0', 'summary', 'markdown'.
- *                                 Unknown values return a stub with
- *                                 supported_formats so callers can branch.
- * @param {object}   playbook      Playbook record loaded via loadPlaybook().
- *                                 Provides _meta.id / version, domain.name,
- *                                 phases.look.artifacts (for SARIF
- *                                 locations), and feeds_into / mutex.
- * @param {object}   analyze      Output of analyze(). Carries matched_cves,
- *                                 _detect_indicators, framework_gap_mapping,
- *                                 rwep, blast_radius_score,
- *                                 _detect_classification.
- * @param {object}   validate     Output of validate(). Carries
- *                                 selected_remediation, remediation_paths,
- *                                 evidence_requirements,
- *                                 residual_risk_statement.
- * @param {object}   agentSignals Agent-submitted signals (signal_overrides
- *                                 merged + cleaned). Drives the OpenVEX
- *                                 vex_status:'fixed' attestation trail and
- *                                 the CSAF cvss_v3 score-block gate.
- * @param {string}   sessionId    Run session id (threaded from run()).
- *                                 Becomes part of CSAF tracking.id,
- *                                 OpenVEX @id, and the on-disk attestation
- *                                 file name so all three correlate.
- * @param {string=}  issuedAt     Optional ISO 8601 timestamp. Pinning this
- *                                 across multi-format emits keeps CSAF /
- *                                 OpenVEX / SARIF agreed on milliseconds;
- *                                 each call would otherwise crystallise a
- *                                 fresh Date.now().
- * @param {object=}  runOpts      Operator / library knobs. Recognised
- *                                 fields: operator, publisherNamespace,
- *                                 csafStatus, tlp, _runErrors accumulator.
- * @returns {object}              The requested format's document body.
+ * Build one evidence bundle in the requested format ('csaf-2.0', 'sarif',
+ * 'openvex', 'summary', 'markdown', 'json' and their versioned spellings). An
+ * unrecognised format returns a stub carrying supported_formats. `sessionId`
+ * becomes part of the CSAF tracking.id, the OpenVEX @id and the attestation
+ * name, so all three correlate. `issuedAt` pins the timestamp across a
+ * multi-format emit, without which each call crystallises its own Date.now().
+ * `runOpts` is read for operator, publisherNamespace, csafStatus, tlp and the
+ * _runErrors accumulator.
  */
 function buildEvidenceBundle(format, playbook, analyze, validate, agentSignals, sessionId, issuedAt, runOpts) {
   runOpts = runOpts || {};
   const playbookSlug = urnSlug(playbook._meta.id);
   const { productId, productPurl, productName } = buildProductBinding(playbook, sessionId);
-  // Pin one `now` value per bundle build (and accept an
-  // upstream-provided issuedAt) so multi-format emit produces identical
-  // tracking timestamps across CSAF / OpenVEX / SARIF when close() is
-  // building several formats from the same run. Without the parameter,
-  // each invocation crystallises a fresh `Date.now()` and bundle_body
-  // versus bundles_by_format[primary] diverge on milliseconds.
   const now = typeof issuedAt === 'string' && issuedAt ? issuedAt : new Date().toISOString();
 
-  // CSAF-2.0 shape. v0.11.5 (#82): include vulnerabilities for both matched
-  // catalogue CVEs AND fired indicators (treated as advisory pseudo-CVEs
-  // under `exceptd:` namespace), so playbooks without catalogue CVEs still
-  // emit a non-empty bundle.
-  //
-  // v0.12.12 (B5): emit a product_tree so csaf_security_advisory documents
-  // pass NVD/ENISA/Red Hat dashboard validation. Every vulnerability
-  // entry references the product via product_status so the binding is
-  // real, not cosmetic.
+  // CSAF-2.0. vulnerabilities[] covers matched catalogue CVEs AND fired
+  // indicators (as pseudo-CVEs), so a playbook with no catalogue CVEs still
+  // emits a non-empty bundle. Every entry references the product through
+  // product_status, which NVD / ENISA / Red Hat dashboards validate.
   if (format === 'csaf-2.0') {
     const indicatorHits = (analyze._detect_indicators || []).filter(i => i.verdict === 'hit');
     const fullProductNames = [{
@@ -2778,28 +1959,17 @@ function buildEvidenceBundle(format, playbook, analyze, validate, agentSignals,
       name: productName,
       product_identification_helper: { purl: productPurl }
     }];
-    // `fixed` product_status MUST reflect operator-supplied VEX
-    // disposition (vex_status === 'fixed' — see analyze()), not the
-    // catalog's global `live_patch_available` flag. The catalog flag
-    // means "vendor publishes a live-patch in the world", not "operator
-    // deployed it on this host". Declaring every live-patchable CVE as
-    // fixed regardless of operator evidence would produce CSAF documents
-    // that lie to downstream NVD / Red Hat dashboards. When
-    // live_patch_available is the only signal, status stays
-    // known_affected and the live-patch route is surfaced as a
+    // A `fixed` product_status reflects the operator's VEX disposition, never
+    // the catalog's live_patch_available flag: that flag says the vendor
+    // publishes a live-patch, not that this operator deployed it, and treating
+    // it as fixed makes the document lie to downstream dashboards.
+    // Live-patch-only stays known_affected, with the route offered as a
     // `vendor_fix` remediation.
-    // CSAF §3.2.1.2 restricts the `cve` field to the CVE-id
-    // regex `^CVE-[0-9]{4}-[0-9]{4,}$`. The catalog also keys non-CVE
-    // identifiers off `cve_id` (MAL-2026-3083, GHSA-…, OSV-…); strict
-    // validators (BSI CSAF validator, ENISA dashboard) refuse documents that
-    // place non-CVE values in `cve`. Branch by prefix and route non-CVE ids
-    // to the `ids[]` array with a real `system_name`.
     //
-    // CSAF §3.2.1.5 requires `cvss_v3.vectorString` when a
-    // cvss_v3 score block is emitted. Drop the entire score block when the
-    // catalog has no CVSS data (score AND vector both unset); otherwise
-    // include version + baseScore + vectorString + baseSeverity from the
-    // catalog entry.
+    // CSAF §3.2.1.2 restricts `cve` to `^CVE-[0-9]{4}-[0-9]{4,}$`, and the
+    // catalog also keys MAL-/GHSA-/OSV- identifiers off cve_id, so those route
+    // to `ids[]`. §3.2.1.5 requires a vectorString whenever a cvss_v3 block is
+    // emitted, so the block is dropped when there is neither score nor vector.
     const csafCvssSeverity = (score) => {
       if (typeof score !== 'number') return null;
       if (score >= 9.0) return 'CRITICAL';
@@ -2812,39 +1982,27 @@ function buildEvidenceBundle(format, playbook, analyze, validate, agentSignals,
       if (typeof vec !== 'string') return '3.1';
       const m = vec.match(/^CVSS:(\d+\.\d+)\//);
       if (!m) return '3.1';
-      // Returns the declared version verbatim. The CALLER is responsible for
-      // gating cvss_v3 emission to 3.0 / 3.1 per CSAF 2.0 schema. 2.0 and
-      // 4.0 vectors are tagged here for diagnostic clarity but never reach
-      // the cvss_v3 block downstream.
+      // The declared version, verbatim — gating emission to 3.0 / 3.1 per the
+      // CSAF 2.0 schema is the CALLER's job.
       return m[1];
     };
     const csafIdsFor = (id) => {
-      // null / undefined / non-string id MUST NOT emit literal "null" /
-      // "undefined" text into the vulnerabilities[] entry. String(id)
-      // would coerce both to those literals; strict validators then
-      // reject the document and operators see a phantom "null" CVE in
-      // dashboards. Return null so the caller skips the entry entirely
-      // and surfaces a runtime_error for the missing id.
+      // Null for a missing id, so the caller drops the entry: String(id) puts
+      // literal "null" text into vulnerabilities[], which validators reject.
       if (typeof id !== 'string' || !id) return null;
       if (id.startsWith('GHSA-'))    return { system_name: 'GHSA', text: id };
       if (id.startsWith('MAL-'))     return { system_name: 'Malicious-Package', text: id };
       if (id.startsWith('OSV-'))     return { system_name: 'OSV', text: id };
       if (id.startsWith('SNYK-'))    return { system_name: 'Snyk', text: id };
-      // RUSTSEC advisories carry their own tracking authority
-      // (https://rustsec.org); mis-routing them to system_name 'OSV'
-      // loses the upstream provenance link and confuses downstream
-      // ingesters that resolve by (system_name, text) pair.
+      // RUSTSEC is its own tracking authority; routing it to 'OSV' breaks the
+      // (system_name, text) pair downstream ingesters resolve by.
       if (id.startsWith('RUSTSEC-')) return { system_name: 'RUSTSEC', text: id };
-      // Genuinely-unknown prefix surfaces as `exceptd-unknown` so
-      // downstream ingesters see that the authority wasn't recognised
-      // rather than misattributing every unknown id to OSV.
+      // An unrecognised authority says so, rather than being misattributed.
       return { system_name: 'exceptd-unknown', text: id };
     };
     const CSAF_CVE_RE = /^CVE-\d{4}-\d{4,}$/;
 
-    // Build the product-tree branches up front so each CVE's per-version CSAFPID
-    // leaves can be bound into its product_status.known_affected (and the same
-    // tree reused for product_tree below — buildCsafBranches is not re-run).
+    // Built up front so the CSAFPID leaves bind into product_status below.
     const csafProductTree = buildCsafBranches(analyze.matched_cves || [], runOpts);
 
     const cveVulns = analyze.matched_cves.map(c => {
@@ -2855,11 +2013,6 @@ function buildEvidenceBundle(format, playbook, analyze, validate, agentSignals,
           || (c.live_patch_available ? 'Vendor publishes a live-patch — see CVE catalog `live_patch_tools` for the operator-side step.' : 'See selected remediation path.'),
         product_ids: [productId],
       }];
-      // Catalog entries with a missing / non-string cve_id would
-      // otherwise produce literal `text: "null"` / `text: "undefined"`
-      // entries under ids[]. Skip the vulnerability entry entirely and
-      // surface a runtime_error so the catalog gap is visible to
-      // operators / CI gates.
       const idIsCve = typeof c.cve_id === 'string' && CSAF_CVE_RE.test(c.cve_id);
       let idEntry = null;
       if (!idIsCve) {
@@ -2875,28 +2028,12 @@ function buildEvidenceBundle(format, playbook, analyze, validate, agentSignals,
           return null;
         }
       }
-      // only emit cvss_v3 score block when we have a real
-      // vector string AND a numeric score. Pre-fix every vuln carried
-      // `cvss_v3: { base_score: 0 }` even when the catalog had no CVSS
-      // signal — strict validators reject the truncated block, and
-      // `base_score: 0` was a downstream-misleading default that suggested
-      // an authoritative "informational" score where there was simply no
-      // data.
-      //
-      // CSAF 2.0 `cvss_v3` ONLY accepts version 3.0 / 3.1. Catalog
-      // vectors prefixed CVSS:2.0/ or CVSS:4.0/ would otherwise emit a
-      // cvss_v3 block with version: '2.0' / '4.0', which strict
-      // validators (BSI CSAF Validator) reject outright. Drop the block
-      // for non-3.x vectors and surface a runtime_error so operators can
-      // see why their CVSS data didn't make it through.
+      // A real vector AND a numeric score: an emitted `base_score: 0` reads as
+      // an authoritative "informational" score where there is simply no data.
       const hasCvss = typeof c.cvss_score === 'number' && typeof c.cvss_vector === 'string' && c.cvss_vector.length > 0;
-      // Strict CVSS 3.1 parse (lib/scoring.parseCvss31Vector). The pre-fix
-      // permissive regex accepted any CVSS:X.Y/... prefix and would emit a
-      // cvss_v3 block keyed off a malformed vector — strict validators
-      // (BSI CSAF Validator, ENISA dashboard) then reject the whole
-      // document. Strict parse failures surface as a `csaf_cvss_invalid`
-      // runtime_error, the cvss_v3 block is omitted, and the rest of the
-      // vulnerability entry (product_status, remediations, etc.) survives.
+      // cvss_v3 accepts only 3.0 / 3.1, and validators reject a block keyed off
+      // a 2.0 / 4.0 or malformed vector. A strict-parse failure raises
+      // csaf_cvss_invalid and omits the block alone — the entry survives.
       let strictParse = null;
       if (hasCvss) {
         strictParse = scoring.parseCvss31Vector(c.cvss_vector);
@@ -2920,10 +2057,8 @@ function buildEvidenceBundle(format, playbook, analyze, validate, agentSignals,
         }
       }] : [];
       const base = {
-        // CSAF Profile 4 (security_advisory) mandatory test 6.1.27.5 requires
-        // every /vulnerabilities[] item to carry `notes`. Without this the
-        // CVE-keyed entries failed strict validation (the indicator pseudo-CVE
-        // entries already carried notes; real-CVE entries did not).
+        // CSAF Profile 4 mandatory test 6.1.27.5: every /vulnerabilities[]
+        // item carries `notes`.
         notes: [{
           category: 'description',
           text: `${c.cve_id}: RWEP ${c.rwep}${c.active_exploitation ? `, active_exploitation=${c.active_exploitation}` : ''}${c.cisa_kev ? ', CISA KEV' : ''}.`,
@@ -2931,44 +2066,30 @@ function buildEvidenceBundle(format, playbook, analyze, validate, agentSignals,
         scores,
         threats: c.active_exploitation === 'confirmed' ? [{ category: 'exploit_status', details: `Active exploitation confirmed${c.cisa_kev ? ' (CISA KEV)' : ''}.` }] : [],
         remediations,
-        // Bind this CVE's per-version CSAFPID leaves (from the product tree) into
-        // known_affected, so a CSAF consumer correlating product_status back to
-        // the branches tree resolves the real affected versions, not only the
-        // opaque synthetic product. The leaves are parsed from affected_products
-        // / affected_versions — VULNERABLE version ranges — so they belong ONLY
-        // under known_affected. The VEX-fixed disposition keeps just the synthetic
-        // target product under `fixed`; adding affected ranges there would
-        // mislabel vulnerable versions as fixed releases.
+        // The CSAFPID leaves are VULNERABLE ranges, so they belong only under
+        // known_affected. `fixed` keeps the synthetic product alone — affected
+        // ranges there would read as fixed releases.
         product_status: isFixed
           ? { fixed: [productId] }
           : { known_affected: [productId, ...(csafProductTree.cveProductIds[c.cve_id] || [])] }
       };
-      // route by id shape.
       if (idIsCve) {
         return { cve: c.cve_id, ...base };
       }
       return { ids: [idEntry], ...base };
     }).filter(v => v != null);
     const indicatorVulns = indicatorHits.map(i => ({
-      // CSAF `system_name` values land in operator-facing validators; the
-      // "exceptd-indicator" pseudo-authority is namespaced enough that NVD /
-      // Red Hat / ENISA dashboards render it as a non-CVE finding without
-      // misattributing to a real registry (CVE, GHSA, OSV).
+      // The 'exceptd-indicator' pseudo-authority is namespaced so NVD / Red Hat
+      // / ENISA dashboards render a non-CVE finding without misattributing it
+      // to a real registry.
       ids: [{ system_name: 'exceptd-indicator', text: `${playbook._meta.id}:${i.id}` }],
       notes: [{ category: 'description', text: `Indicator ${i.id} fired (${i.confidence}${i.deterministic ? ' / deterministic' : ''}) in playbook ${playbook._meta.id}.` }],
       remediations: [{ category: 'mitigation', details: validate.selected_remediation?.description || `Consult playbook brief: exceptd brief ${playbook._meta.id}.`, product_ids: [productId] }],
       product_status: { known_affected: [productId] }
     }));
-    // Framework-gap entries land in `document.notes[]` with
-    // `category: details` rather than `vulnerabilities[]` with
-    // `ids: [{ system_name: 'exceptd-framework-gap' }]`. The `system_name`
-    // slot is reserved for recognised vulnerability tracking authorities
-    // (CVE, GHSA, etc.); exceptd-framework-gap is not one, and every
-    // downstream CSAF consumer (NVD ingester, Red Hat dashboard, ENISA
-    // validator) would flag the run for unknown ids and render
-    // false-positive advisories at the framework_gap_mapping length.
-    // Notes are the right home for advisory context that is not itself
-    // a pseudo-CVE.
+    // Framework gaps belong in document.notes[], not vulnerabilities[]: the
+    // system_name slot is for recognised tracking authorities, and a made-up
+    // one renders a false-positive advisory per gap downstream.
     const gapNotes = (analyze.framework_gap_mapping || []).map((g, idx) => {
       const lines = [
         `Framework: ${g.framework}`,
@@ -2982,14 +2103,10 @@ function buildEvidenceBundle(format, playbook, analyze, validate, agentSignals,
         text: lines.join('\n'),
       };
     });
-    // CSAF §3.1.7.4 publisher.namespace MUST be the trust
-    // anchor of the entity publishing the advisory — the OPERATOR running the
-    // scan, not the tool vendor. Pre-fix every CSAF emitted by the runner
-    // claimed https://exceptd.com as namespace, falsely attributing
-    // responsibility for advisory accuracy to the tooling provider. Resolve
-    // in priority order: explicit --publisher-namespace > --operator if it
-    // looks URL-shaped > fallback `urn:exceptd:operator:unknown` with a note
-    // documenting the gap.
+    // CSAF §3.1.7.4: publisher.namespace is the trust anchor of the entity
+    // publishing the advisory — the OPERATOR running the scan, not the tool
+    // vendor, who is not answerable for its accuracy. Resolved as
+    // --publisher-namespace, then a URL-shaped --operator, then a marked fallback.
     const operatorClean = sanitizeOperatorText(runOpts.operator);
     const explicitNs = sanitizeOperatorText(runOpts.publisherNamespace);
     let publisherNamespace;
@@ -3009,14 +2126,8 @@ function buildEvidenceBundle(format, playbook, analyze, validate, agentSignals,
       title: 'Publisher namespace not supplied',
       text: 'No --publisher-namespace and no URL-shaped --operator were supplied to this run. CSAF §3.1.7.4 requires the namespace to be the publisher\'s trust anchor — i.e. the OPERATOR running the scan, not the tooling vendor. Re-emit with `--publisher-namespace https://your-org.example` (or a URL-shaped `--operator`) to attribute responsibility for advisory accuracy correctly.'
     }] : [];
-    // ALSO surface the unclaimed-publisher condition through
-    // the structured runtime_errors[] accumulator so machine-readable
-    // consumers (CI gates, dashboards) can branch on it without parsing
-    // notes[] prose. The orchestrator's post-close pass folds late-pushed
-    // _runErrors into phases.analyze.runtime_errors before the run-level
-    // return, so the warning surfaces alongside other run-time anomalies.
-    // De-dupe: only push once per bundle-build pass (multi-format emit
-    // builds CSAF once via memoization, so this fires at most once per run).
+    // Also on runtime_errors[], so a CI gate can branch on the unclaimed
+    // publisher without parsing notes[] prose.
     if (publisherNamespaceSource === 'fallback' && Array.isArray(runOpts._runErrors)) {
       pushRunError(runOpts._runErrors, {
         kind: 'bundle_publisher_unclaimed',
@@ -3025,11 +2136,8 @@ function buildEvidenceBundle(format, playbook, analyze, validate, agentSignals,
       }, { dedupeKey: () => 'singleton' });
     }
 
-    // thread the validated --operator name into
-    // tracking.generator (engine identity) AND publisher.contact_details
-    // (operator-of-record). engine.version is read from the package once per
-    // process. contact_details is omitted when no operator was supplied so
-    // the field doesn't carry a misleading null.
+    // contact_details is the operator-of-record, omitted entirely when no
+    // operator was supplied rather than carrying a misleading null.
     const publisherBlock = {
       category: 'vendor',
       name: 'exceptd',
@@ -3037,42 +2145,29 @@ function buildEvidenceBundle(format, playbook, analyze, validate, agentSignals,
     };
     if (operatorClean) publisherBlock.contact_details = operatorClean;
 
-    // CSAF §3.1.11.3.5.1 defines `final` as an immutable
-    // advisory; subsequent re-emits against the same tracking.id are
-    // refused by strict validators (BSI CSAF Validator). Runtime detection
-    // runs with no operator review loop are inherently revisable, so the
-    // default is `interim`. Operators who have reviewed and are ready to
-    // promote pass `--csaf-status final` (threaded via runOpts.csafStatus);
-    // any other value falls back to `interim` rather than emitting an
-    // unrecognized status word.
+    // CSAF §3.1.11.3.5.1 makes `final` immutable — validators refuse a re-emit
+    // against the same tracking.id — and a detection run with no operator
+    // review loop is revisable, so the default is `interim`. --csaf-status
+    // promotes it; anything unrecognised falls back rather than being emitted.
     const allowedCsafStatuses = new Set(['draft', 'interim', 'final']);
     const csafStatus = allowedCsafStatuses.has(runOpts.csafStatus)
       ? runOpts.csafStatus
       : 'interim';
 
-    // CSAF §3.1.4 `distribution.tlp`. Optional. When the operator supplies
-    // `--tlp <label>` (threaded as runOpts.tlp), emit
-    // distribution.tlp.label + distribution.text. CSAF allows omission of
-    // the whole distribution block when no level is declared; the
-    // pre-fix runner had no surface for this at all.
+    // CSAF §3.1.4 distribution.tlp is optional, and the whole block is omitted
+    // when --tlp declares no level.
     const allowedTlp = new Set(['CLEAR', 'GREEN', 'AMBER', 'AMBER+STRICT', 'RED']);
-    // CSAF 2.0 §3.2.1.5.2 pins tlp.label to the TLP 1.0 enum
-    // (WHITE/GREEN/AMBER/RED). Map the modern TLP 2.0 labels the CLI accepts
-    // onto that enum so the emitted document stays schema-valid for strict
-    // CSAF 2.0 consumers, while preserving the operator's exact label in the
-    // free-form `text` field. (CLEAR≡WHITE; AMBER+STRICT carries AMBER's
-    // disclosure scope plus a stricter handling note.)
+    // CSAF 2.0 §3.2.1.5.2 pins tlp.label to the TLP 1.0 enum, so the TLP 2.0
+    // labels the CLI accepts map onto it and the operator's exact label
+    // survives in the free-form `text`.
     const CSAF_TLP_LABEL = { CLEAR: 'WHITE', GREEN: 'GREEN', AMBER: 'AMBER', 'AMBER+STRICT': 'AMBER', RED: 'RED' };
     const csafDistribution = (runOpts.tlp && allowedTlp.has(runOpts.tlp))
       ? { tlp: { label: CSAF_TLP_LABEL[runOpts.tlp] }, text: `TLP:${runOpts.tlp}` }
       : null;
 
-    // CSAF 2.0: an advisory with zero vulnerabilities is a csaf_informational_advisory
-    // (Profile 5, which does not require /vulnerabilities) rather than a
-    // csaf_security_advisory (Profile 4, where an empty vulnerabilities array is
-    // semantically wrong and warns under strict profile validators). A clean run
-    // becomes an informational attestation; any firing CVE/indicator keeps the
-    // security-advisory category.
+    // A zero-vulnerability advisory is informational (the profile that does not
+    // require /vulnerabilities), not a security advisory with an empty array —
+    // which is semantically wrong and warns under strict profile validators.
     const csafCategory = (cveVulns.length + indicatorVulns.length) > 0
       ? 'csaf_security_advisory'
       : 'csaf_informational_advisory';
@@ -3083,59 +2178,49 @@ function buildEvidenceBundle(format, playbook, analyze, validate, agentSignals,
         publisher: publisherBlock,
         title: `exceptd finding: ${playbook.domain.name} (${analyze.matched_cves.length} CVE(s), ${indicatorHits.length} indicator hit(s), ${(analyze.framework_gap_mapping || []).length} framework gap(s))`,
         notes: [...namespaceFallbackNote, ...gapNotes],
-        // Profile 3 (csaf_informational_advisory) mandatory test 6.1.27.2
-        // requires /document/references with at least one `external` item. A
-        // security_advisory carries its references inside the vulnerabilities,
-        // so add this only for the informational (clean-run) profile.
+        // Mandatory test 6.1.27.2 requires /document/references with at least
+        // one `external` item; a security_advisory carries its references
+        // inside the vulnerabilities instead.
         ...(csafCategory === 'csaf_informational_advisory' ? {
           references: [{ category: 'external', summary: `exceptd playbook: ${playbook._meta.id}`, url: `https://exceptd.com/playbooks/${playbook._meta.id}` }],
         } : {}),
         ...(csafDistribution ? { distribution: csafDistribution } : {}),
         tracking: {
-          // F2/F9: CSAF tracking.id binds to the run's session_id (threaded
-          // from run() via close()) so attestation file names, OpenVEX
-          // @id, and CSAF tracking.id all share the same correlation
-          // identifier. Pre-fix the timestamp was used, so two runs in
-          // the same millisecond collided and one run's documents
-          // referenced ids that didn't match anything else on disk.
+          // Keyed on session_id, not a timestamp: two runs in the same
+          // millisecond would collide, and the id must match the OpenVEX @id
+          // and the attestation file name on disk.
           id: `exceptd-${playbook._meta.id}-${sessionId}`,
           status: csafStatus,
           version: playbook._meta.version,
-          // name the engine that emitted the advisory.
-          // CSAF §3.1.11.3.2 places this under tracking.generator.engine.
+          // CSAF §3.1.11.3.2 places the emitting engine here.
           generator: {
             engine: { name: 'exceptd', version: getEngineVersion() },
             date: now,
           },
           initial_release_date: now,
           current_release_date: now,
-          // CSAF 6.1.30 requires homogeneous versioning (all version_t use the
-          // same scheme) and 6.1.16 requires tracking.version === the last
-          // revision_history number. tracking.version is the playbook semver,
-          // so the single revision entry must carry that same semver (not the
-          // integer "1", which mixed schemes AND mismatched the version).
+          // CSAF 6.1.30 requires one versioning scheme throughout and 6.1.16
+          // requires tracking.version to equal the last revision_history
+          // number. tracking.version is the playbook semver, so this entry
+          // carries the same semver — an integer "1" would break both.
           revision_history: [{ number: playbook._meta.version, date: now, summary: 'Initial finding emission' }]
         }
       },
-      // CSAF Profile 3 (informational_advisory) forbids /vulnerabilities
-      // (mandatory test 6.1.27.3) and an informational advisory carrying a
-      // /product_tree is misleading (§4.3 — a reader must assume every named
-      // product is affected). Emit both ONLY for the security_advisory profile;
-      // a clean run's informational advisory carries neither.
+      // The informational profile forbids /vulnerabilities (test 6.1.27.3),
+      // and a /product_tree there is misleading — §4.3 has the reader assume
+      // every named product is affected. Both are security-advisory only.
       ...(csafCategory === 'csaf_security_advisory' ? {
         product_tree: (function () {
-          // Synthesize a 3-level branches tree (vendor → product → version)
-          // from catalog data. CSAF §3.1.5.1 makes branches[] strongly
-          // recommended because NVD / ENISA / Red Hat dashboards render the
-          // affected-product list off the branches tree, not full_product_names[].
+          // NVD / ENISA / Red Hat dashboards render the affected-product list
+          // off branches[], not full_product_names[] (CSAF §3.1.5.1).
           const branches = csafProductTree.branches;
           const tree = { full_product_names: fullProductNames };
           if (branches.length > 0) tree.branches = branches;
           return tree;
         })(),
         vulnerabilities: (function () {
-          // v0.12.27: deterministic mode sorts vulnerabilities[] by their
-          // primary identifier ascending; default mode preserves insertion order.
+          // Deterministic mode sorts by primary identifier; otherwise
+          // insertion order stands.
           const all = [...cveVulns, ...indicatorVulns];
           if (runOpts && runOpts.bundleDeterministic === true) {
             const keyOf = (v) => (typeof v.cve === 'string' && v.cve)
@@ -3159,30 +2244,14 @@ function buildEvidenceBundle(format, playbook, analyze, validate, agentSignals,
     };
   }
 
-  // SARIF 2.1.0 — GitHub Code Scanning / VS Code SARIF Viewer / Azure DevOps
-  // / most static-analysis tooling.
-  //
-  // v0.12.12 (B6): thread artifact source paths through to
-  // result.locations[].physicalLocation.artifactLocation.uri. GitHub Code
-  // Scanning hides results without populated locations, so the heuristic
-  // ensures clean playbook runs still surface findings in the alerts UI.
-  // v0.12.12 (B7): omit null property-bag keys so SARIF viewers don't
-  // render empty fields.
   if (format === 'sarif' || format === 'sarif-2.1.0') {
+    // Null property-bag keys render as empty rows in SARIF viewers.
     const stripNulls = (obj) => Object.fromEntries(Object.entries(obj).filter(([, v]) => v != null));
-    // SARIF rule ids are global within a single sarif-log run.
-    // Pre-fix, generic ruleIds like `framework-gap-0` (and shared CVE ids
-    // across playbooks) collided when results from multiple playbook runs
-    // were merged into one SARIF document — GitHub Code Scanning de-dupes
-    // by ruleId, so the second playbook's rule definition silently
-    // overwrote the first. Prefix every ruleId with the playbook slug so
-    // every rule definition is unambiguously attributable to one playbook,
-    // and cross-playbook merges retain all results.
+    // Rule ids are global within a sarif-log run and GitHub Code Scanning
+    // de-dupes by ruleId, so a generic id (`framework-gap-0`, a shared CVE id)
+    // would let one playbook's rule silently overwrite another's on merge.
     const rulePrefix = `${playbookSlug}/`;
-    // CVE-match results get the coarse playbook-source location fallback
-    // (passing a null indicator skips the per-indicator evidence-locations
-    // branch). Without any `locations`, GitHub Code Scanning silently DROPS
-    // these results — the highest-severity result class would never surface.
+    // A null indicator takes the coarse playbook-source location fallback.
     const cveResults = analyze.matched_cves.map(c => {
       const result = {
         ruleId: `${rulePrefix}${c.cve_id}`,
@@ -3198,9 +2267,8 @@ function buildEvidenceBundle(format, playbook, analyze, validate, agentSignals,
           blast_radius_score: analyze.blast_radius_score,
         }),
       };
-      // Always carry a location (physical when known, else a rule-scoped
-      // logicalLocations fallback) so GitHub Code Scanning does not drop the
-      // highest-severity result class.
+      // Always a location — physical when known, else the rule-scoped logical
+      // fallback — or Code Scanning drops the highest-severity result class.
       result.locations = sarifResultLocations(playbook, null, result.ruleId);
       return result;
     });
@@ -3224,32 +2292,27 @@ function buildEvidenceBundle(format, playbook, analyze, validate, agentSignals,
     });
     const gapResults = (analyze.framework_gap_mapping || []).map((g, idx) => ({
       ruleId: `${rulePrefix}framework-gap-${idx}`,
-      // Framework gaps are control-design observations, not vulnerabilities —
-      // SARIF §3.27.9 `kind: informational` routes them appropriately. That
-      // same clause requires: when kind !== 'fail', a present `level` SHALL be
-      // 'none'. Pairing 'informational' with 'note' is a schema violation that
-      // strict validators / GitHub code-scanning reject — use 'none'.
+      // Framework gaps are control-design observations, not vulnerabilities.
+      // SARIF §3.27.9 requires a present `level` to be 'none' whenever kind is
+      // not 'fail' — pairing 'informational' with 'note' is a schema violation
+      // strict validators and Code Scanning reject.
       kind: 'informational',
       level: 'none',
       message: { text: `${g.framework}: ${g.claimed_control} — ${g.actual_gap}${g.required_control ? '. Required: ' + g.required_control : ''}` },
       properties: stripNulls({ kind: 'framework_gap', framework: g.framework, control: g.claimed_control }),
     }));
     const cveRules = analyze.matched_cves.map(c => {
-      // Resolve the issuing authority by id shape rather than hardcoding NVD.
-      // A non-CVE matched id (MAL-/GHSA-/OSV-/RUSTSEC-/SNYK-) must NOT carry an
-      // nvd.nist.gov URL — that link 404s and presents the id as an NVD CVE.
       const authority = advisoryAuthorityFor(c.cve_id);
       const isCve = CVE_ID_RE.test(typeof c.cve_id === 'string' ? c.cve_id : '');
       const rule = {
         id: `${rulePrefix}${c.cve_id}`,
-        // For a non-CVE id, qualify the short description with its authority so
-        // a SARIF viewer doesn't read e.g. a MAL- id as an NVD CVE.
+        // A non-CVE id is qualified by its authority so a viewer does not read
+        // a MAL- id as an NVD CVE.
         shortDescription: { text: isCve ? c.cve_id : `${c.cve_id} (${authority.system_name || 'non-CVE advisory'})` },
         fullDescription: { text: `RWEP ${c.rwep} · KEV=${c.cisa_kev} · active_exploitation=${c.active_exploitation}` },
         defaultConfiguration: { level: c.rwep >= 90 ? 'error' : c.rwep >= 70 ? 'warning' : 'note' },
       };
-      // helpUri is optional in SARIF 2.1.0; omit it entirely when the authority
-      // has no canonical per-id advisory page rather than emit a broken link.
+      // helpUri is optional; omitting it beats emitting a link that 404s.
       if (authority.helpUri) rule.helpUri = authority.helpUri;
       return rule;
     });
@@ -3275,11 +2338,6 @@ function buildEvidenceBundle(format, playbook, analyze, validate, agentSignals,
         } },
         results: [...cveResults, ...indicatorResults, ...gapResults],
         invocations: [{ executionSuccessful: (analyze._detect_classification !== 'inconclusive'), properties: stripNulls({
-          // Apply the stripNulls contract here too — the `remediation`
-          // field is null for any run that didn't surface a
-          // selected_remediation, and SARIF viewers render null property
-          // values as visible empty rows. Same helper as the result
-          // property bags above.
           playbook: playbook._meta.id, classification: analyze._detect_classification || 'unknown',
           rwep_adjusted: analyze.rwep?.adjusted || 0,
           remediation: validate.selected_remediation?.id || null,
@@ -3288,27 +2346,11 @@ function buildEvidenceBundle(format, playbook, analyze, validate, agentSignals,
     };
   }
 
-  // OpenVEX 0.2.0 — supply-chain VEX statements.
-  //
-  // v0.12.12 (B1-B4): correctness sweep against the OpenVEX 0.2.0 spec.
-  //  - B1: every statement now carries a `products` array (spec MUST).
-  //  - B2: `status` derives from the verdict + confidence rather than being
-  //        hard-coded to `under_investigation`. Hits emit `affected` with
-  //        an action_statement; misses emit `not_affected` with a
-  //        justification; inconclusive findings keep `under_investigation`.
-  //  - B3: framework gaps are control-design observations, not
-  //        vulnerabilities — they are removed from the VEX emit path. They
-  //        remain in CSAF (informational notes) and SARIF (kind:
-  //        informational rules).
-  //  - B4: vulnerability `@id` values switch to the registered URN namespace
-  //        `urn:exceptd:indicator:<playbook>:<indicator-id>` (RFC 8141) so
-  //        they pass IRI validation in downstream VEX consumers.
+  // OpenVEX 0.2.0. Every statement carries a `products` array (spec MUST) and a
+  // status from the verdict: a hit is `affected` with an action_statement, a
+  // miss `not_affected` with a justification, anything else
+  // `under_investigation`. Framework gaps never enter this path.
   if (format === 'openvex' || format === 'openvex-0.2.0') {
-    // Reuse the bundle-wide `now` so OpenVEX `timestamp` aligns with
-    // CSAF `document.tracking.initial_release_date` when both formats are
-    // emitted in the same close() pass. A per-format Date.now() would
-    // cause the two bundles in bundles_by_format to disagree on
-    // milliseconds.
     const issued = now;
     const productEntry = {
       '@id': productPurl,
@@ -3324,17 +2366,9 @@ function buildEvidenceBundle(format, playbook, analyze, validate, agentSignals,
       if (remediationDescription) return `Apply remediation from validate phase: ${remediationDescription}`;
       return fallback;
     };
-    // Same `vex_status === 'fixed'` correctness rule as the CSAF
-    // emitter. The catalog `live_patch_available` flag is a global
-    // "vendor publishes a live-patch" signal, not an operator-host
-    // disposition. Treating it as `status: fixed` would make OpenVEX
-    // statements claim resolution the operator hadn't attested to. VEX
-    // consumers downstream of CISA / SBOM / supply-chain pipelines treat
-    // `fixed` as authoritative — emitting it without operator attestation
-    // is a downstream-misleading bug. The OpenVEX statement says
-    // `affected` (with action_statement pointing to the remediation,
-    // which may itself be the vendor live-patch route) unless the
-    // operator declared `vex_status: fixed` on the matched CVE.
+    // As in the CSAF emitter, only an operator-declared vex_status:'fixed'
+    // yields `fixed`: supply-chain consumers treat it as authoritative, so the
+    // catalog's live_patch_available flag must not claim an unattested fix.
     const cveStatements = analyze.matched_cves.map(c => {
       const stmt = {
         vulnerability: { '@id': vulnIdToUrn(c.cve_id), name: c.cve_id },
@@ -3344,13 +2378,8 @@ function buildEvidenceBundle(format, playbook, analyze, validate, agentSignals,
       };
       if (c.vex_status === 'fixed') {
         stmt.status = 'fixed';
-        // OpenVEX 0.2.0 §4.1: `fixed` is an operator-attested resolution,
-        // not a global vendor flag. Augment the impact_statement with an
-        // evidence trail so downstream supply-chain consumers can chase
-        // the attestation back to the operator's submitted evidence.
-        // Short-hash is deterministic for the same (cve_id, signals)
-        // input — re-emitting the bundle for the same submission yields
-        // the same trail.
+        // A trail back to the operator's submission, hashed deterministically
+        // over (cve_id, signals) so a re-emit yields the same one.
         const trailSrc = canonicalStringify({
           cve_id: c.cve_id,
           vex_status: 'fixed',
@@ -3379,10 +2408,8 @@ function buildEvidenceBundle(format, playbook, analyze, validate, agentSignals,
           impact_statement: `Indicator ${i.id} (${i.verdict}; ${i.confidence}${i.deterministic ? '/deterministic' : ''}) in playbook ${playbook._meta.id}.`,
         };
         if (i.verdict === 'hit') {
-          // Deterministic and high-confidence hits both map to `affected`.
-          // The `deterministic` flag describes regex specificity, not
-          // operator-evidence confidence — neither warrants
-          // under_investigation when the indicator actually fired.
+          // `deterministic` describes regex specificity, not evidence
+          // confidence, so a fired indicator is `affected` either way.
           stmt.status = 'affected';
           stmt.action_statement = actionStatementFor(`Run \`exceptd brief ${playbook._meta.id}\` for context.`);
         } else if (i.verdict === 'miss') {
@@ -3393,15 +2420,8 @@ function buildEvidenceBundle(format, playbook, analyze, validate, agentSignals,
         }
         return stmt;
       });
-    // OpenVEX `author` identifies the entity attesting to the
-    // disposition — for an operator-run scan that is the operator, not the
-    // tool vendor. Mirror the CSAF publisher.namespace fallback ladder so a
-    // downstream supply-chain consumer keying on `author` resolves to the
-    // operator URN. Pre-fix every OpenVEX document falsely attributed
-    // dispositions to the tooling provider. Falls back to
-    // urn:exceptd:operator:unknown + bundle_publisher_unclaimed runtime
-    // warning if neither runOpts.operator nor runOpts.publisherNamespace
-    // is supplied.
+    // `author` is the entity attesting to the disposition — the operator, not
+    // the tool vendor. Same fallback ladder as the CSAF publisher.namespace.
     const vexOperatorClean = sanitizeOperatorText(runOpts.operator);
     const vexExplicitNs = sanitizeOperatorText(runOpts.publisherNamespace);
     let vexAuthor;
@@ -3411,9 +2431,8 @@ function buildEvidenceBundle(format, playbook, analyze, validate, agentSignals,
       vexAuthor = vexOperatorClean;
     } else {
       vexAuthor = 'urn:exceptd:operator:unknown';
-      // Same shape + singleton dedupe as the CSAF path so a multi-format emit
-      // produces one canonical bundle_publisher_unclaimed entry that machine
-      // consumers can read consistently (reason/remediation, not message).
+      // Same shape and singleton dedupe as the CSAF path, so a multi-format
+      // emit produces one canonical bundle_publisher_unclaimed entry.
       pushRunError(runOpts._runErrors, {
         kind: 'bundle_publisher_unclaimed',
         reason: 'OpenVEX author fell back to urn:exceptd:operator:unknown because no --publisher-namespace and no URL-shaped --operator were supplied. Disposition attribution is unclaimed on this VEX document.',
@@ -3422,17 +2441,15 @@ function buildEvidenceBundle(format, playbook, analyze, validate, agentSignals,
     }
     return {
       '@context': 'https://openvex.dev/ns/v0.2.0',
-      // F2/F9: OpenVEX @id baked from session_id (not Date.now()) so the
-      // document URN aligns with CSAF tracking.id and on-disk
-      // attestation file name. Falls back to a urnSlug if sessionId
-      // somehow arrived empty.
+      // Baked from session_id, not Date.now(), so the document URN aligns with
+      // the CSAF tracking.id and the on-disk attestation file name.
       '@id': `https://exceptd.com/vex/${playbookSlug}/${urnSlug(sessionId || 'session')}`,
       author: vexAuthor,
       timestamp: issued,
       version: 1,
       statements: (function () {
-        // v0.12.27: deterministic mode sorts statements[] by
-        // vulnerability['@id'] ascending. Insertion order otherwise.
+        // Deterministic mode sorts by vulnerability['@id']; otherwise
+        // insertion order stands.
         const all = [...cveStatements, ...indicatorStatements];
         if (runOpts && runOpts.bundleDeterministic === true) {
           const keyOf = (s) => (s && s.vulnerability && typeof s.vulnerability['@id'] === 'string')
@@ -3444,9 +2461,6 @@ function buildEvidenceBundle(format, playbook, analyze, validate, agentSignals,
     };
   }
 
-  // v0.11.0 redesign #39: --format summary emits a 5-line digest for CI gates
-  // and human triage. Drops everything except verdict + RWEP + blast +
-  // feeds_into + jurisdiction clock count.
   if (format === 'summary') {
     return {
       format: 'summary',
@@ -3480,14 +2494,8 @@ function buildEvidenceBundle(format, playbook, analyze, validate, agentSignals,
     return { format: 'markdown', body: lines.join('\n') };
   }
 
-  // Native structured-JSON bundle — a superset of `summary` carrying the full
-  // finding record. This is the declared bundle_format for the secrets /
-  // cred-stores / runtime / citation-hygiene playbooks; without an explicit
-  // branch their default bundle fell through to the Unknown-format placeholder
-  // below. Reuses the pinned `now` so multi-format builds stay
-  // timestamp-consistent, and exposes the same finding fields the supported
-  // csaf / markdown branches already surface — `json` is an intentional,
-  // operator-selectable format, not the fallback leak path.
+  // A superset of `summary` carrying the full finding record, and the declared
+  // bundle_format of several shipped playbooks — not the fallback below.
   if (format === 'json') {
     return {
       format: 'json',
@@ -3505,11 +2513,8 @@ function buildEvidenceBundle(format, playbook, analyze, validate, agentSignals,
     };
   }
 
-  // The fallback must NOT leak raw analyze + validate internals (matched
-  // CVEs, framework gaps, residual-risk statements) under an arbitrary
-  // "format" name — operators piping output to logging or third-party
-  // tooling could leak finding details just by typo'ing the format flag.
-  // Return the shape advertisement only.
+  // The supported formats and nothing else: emitting analyze and validate
+  // internals here leaks finding details on a typo'd format flag.
   return {
     format,
     note: 'Unknown format',
@@ -3517,34 +2522,20 @@ function buildEvidenceBundle(format, playbook, analyze, validate, agentSignals,
   };
 }
 
-// --- orchestrate: full run in one call ---
-
-/**
- * v0.11.0 flat submission shape → v0.10.x nested shape. The flat shape is:
- *
- *   {
- *     observations: {
- *       <artifact-id>: { captured, value, indicator?, result? } | "<precondition-value>",
- *     },
- *     verdict: { theater, classification, blast_radius }
- *   }
- *
- * Already-nested submissions pass through unchanged.
- */
+// Translate the flat submission shape into the engine's nested one; an
+// already-nested submission passes through unchanged. Flat is:
+//   { observations: { <artifact-id>: { captured, value, indicator?, result? }
+//                                     | "<precondition-value>" },
+//     verdict: { theater, classification, blast_radius } }
 function normalizeSubmission(submission, playbook) {
   if (!submission || typeof submission !== "object") return submission || {};
 
-  // signal_overrides must be a plain object. Without this guard, a
-  // non-object value (string "foo", array [...]) is spread into
-  // out.signal_overrides via `{ ...(submission.signal_overrides || {}) }`
-  // — spreading a string splatters it into { '0': 'f', '1': 'o', '2': 'o' },
-  // which confuses detect()'s indicator-id lookup. Strip and log instead.
+  // signal_overrides must be a plain object: spreading a string splatters it
+  // into { '0': 'f', '1': 'o', … } and confuses detect()'s indicator lookup.
   if (submission.signal_overrides !== undefined && submission.signal_overrides !== null
       && (typeof submission.signal_overrides !== 'object' || Array.isArray(submission.signal_overrides))) {
-    // Clone before mutating _runErrors so a frozen / shared input
-    // submission isn't modified in place. Pre-fix a caller passing a
-    // frozen submission (Object.freeze for safety, or a shared reference
-    // across parallel runs) threw uncaught on the _runErrors push.
+    // Clone before touching _runErrors: the caller's submission may be frozen,
+    // or shared across parallel runs.
     const carry = Array.isArray(submission._runErrors) ? submission._runErrors.slice() : [];
     pushRunError(carry, {
       kind: 'signal_overrides_invalid',
@@ -3554,17 +2545,12 @@ function normalizeSubmission(submission, playbook) {
     submission = { ...submission, signal_overrides: {}, _runErrors: carry };
   }
 
-  // v0.11.3 #71 fix: the CLI may inject `signals._bundle_formats` before
-  // calling normalize (for --format <fmt> support). Pre-0.11.3 normalize
-  // detected the injected `signals` key and bailed, leaving the flat
-  // `observations` / `verdict` untranslated and breaking detect. The shape
-  // detector now treats `observations` or `verdict` as authoritative for
-  // "this is flat" — even when nested keys also exist — and merges any
-  // pre-existing nested keys into the normalized result.
+  // `observations` or `verdict` decides the shape even when nested keys are
+  // present: the CLI injects `signals._bundle_formats` before calling this,
+  // and reading that as "already nested" leaves the flat keys untranslated.
   const hasFlat = submission.observations || submission.verdict;
 
   if (!hasFlat) {
-    // Truly already-nested. Mark shape and return.
     if (!submission._original_shape) submission._original_shape = 'nested (v0.10.x)';
     return submission;
   }
@@ -3574,18 +2560,13 @@ function normalizeSubmission(submission, playbook) {
     signal_overrides: { ...(submission.signal_overrides || {}) },
     signals: { ...(submission.signals || {}) },
     precondition_checks: { ...(submission.precondition_checks || {}) },
-    // Carry per-indicator evidence locations through flat normalization so
-    // detect() can thread them onto firing indicators for SARIF results[].locations.
+    // Carried through so detect() can thread them onto firing indicators for
+    // SARIF results[].locations.
     ...(submission.evidence_locations && typeof submission.evidence_locations === 'object'
       ? { evidence_locations: submission.evidence_locations } : {}),
     _original_shape: 'flat (v0.11.0)',
-    // normalizeSubmission pushes structured errors (e.g.
-    // signal_overrides_invalid) onto submission._runErrors above. For flat
-    // submissions the fresh `out` literal built here loses that accumulator
-    // unless we forward it; run()'s harvest at the entry to detect/analyze
-    // reads agentSubmission._runErrors, so without the carry, flat
-    // submissions with invalid signal_overrides drop the errors before
-    // they can reach analyze.runtime_errors.
+    // run() harvests the accumulator from agentSubmission._runErrors, which
+    // the fresh `out` literal would otherwise drop.
     ...(Array.isArray(submission._runErrors) && submission._runErrors.length
       ? { _runErrors: submission._runErrors.slice() }
       : {}),
@@ -3593,9 +2574,6 @@ function normalizeSubmission(submission, playbook) {
   const knownPreconditions = new Set((playbook?._meta?.preconditions || []).map(p => p.id));
   const knownArtifacts = new Set((playbook?.phases?.look?.artifacts || []).map(a => a.id));
 
-  // v0.11.4 (#71): canonicalize indicator outcome strings here too so the
-  // signal_overrides object handed to detect() carries the runner's expected
-  // hit|miss|inconclusive vocabulary regardless of what the operator typed.
   const canonicalizeOutcome = (v) => {
     if (v === true || v === 'hit' || v === 'detected' || v === 'positive') return 'hit';
     if (v === false || v === 'miss' || v === 'no_hit' || v === 'no-hit' || v === 'clean' || v === 'clear' || v === 'not_hit' || v === 'ok' || v === 'pass' || v === 'negative') return 'miss';
@@ -3603,13 +2581,9 @@ function normalizeSubmission(submission, playbook) {
     return v; // leave unrecognized values for detect() to decide
   };
 
-  // v0.11.5 (#85): track which observation produced each signal_override so
-  // detect can emit `from_observation` on each indicator result. Diagnostic
-  // value for operators chasing "which observation drove this verdict".
-  //
-  // When two observations target the same indicator id, last-write-wins
-  // silently. Track discards in _signal_origins_collisions so analyze can
-  // surface analyze.signal_origins_with_collisions for batch evidence runs.
+  // Which observation produced each signal_override, so detect can emit
+  // `from_observation`. Two observations on one indicator is last-write-wins,
+  // and the discard is recorded as a collision for analyze to publish.
   out._signal_origins = out._signal_origins || {};
   out._signal_origins_collisions = out._signal_origins_collisions || [];
   for (const [key, val] of Object.entries(submission.observations || {})) {
@@ -3619,15 +2593,10 @@ function normalizeSubmission(submission, playbook) {
     }
     if (typeof val === "object" && val !== null) {
       const aid = knownArtifacts.has(key) ? key : (val.artifact || key);
-      // Preserve every evidence-bearing key the observation carried, not just
-      // `value`. An observation whose secret/path lives under a non-`value`
-      // key (e.g. { path, matched, reason } — a natural collector shape) was
-      // previously collapsed to { value: undefined, captured } here, silently
-      // discarding the actual evidence. Two observations capturing DIFFERENT
-      // secrets under path/matched then hashed and diffed byte-identical, so
-      // `attest diff` reported a false "unchanged" and masked real drift.
-      // The reserved control keys (artifact/indicator/result) drive
-      // signal_overrides below and are intentionally not echoed as evidence.
+      // Every evidence-bearing key survives, not just `value`: a collector shape
+      // like { path, matched, reason } would collapse to { value: undefined,
+      // captured }, so two observations capturing DIFFERENT secrets hash
+      // byte-identical. artifact/indicator/result are control keys, not evidence.
       const { artifact: _a, indicator: _i, result: _r, captured: _c, value: _v, ...evidence } = val;
       const normalizedArtifact = { captured: val.captured !== false };
       if (val.value !== undefined) normalizedArtifact.value = val.value;
@@ -3639,9 +2608,6 @@ function normalizeSubmission(submission, playbook) {
       if (val.indicator && val.result !== undefined) {
         const newVerdict = canonicalizeOutcome(val.result);
         if (out.signal_overrides[val.indicator] !== undefined && out._signal_origins[val.indicator] !== undefined) {
-          // Collision: a prior observation already set this indicator.
-          // Record the prior (which is now discarded) into the collision
-          // log, then overwrite with the new one (last-write-wins).
           out._signal_origins_collisions.push({
             indicator_id: val.indicator,
             source_observation_key: out._signal_origins[val.indicator],
@@ -3661,18 +2627,9 @@ function normalizeSubmission(submission, playbook) {
   if (v.classification) out.signals.detection_classification = v.classification;
   if (v.blast_radius !== undefined) out.signals.blast_radius_score = v.blast_radius;
 
-  // Carry over precondition_checks if the operator supplied them at the top
-  // level even in the flat shape.
-  //
-  // The prior `Object.assign(out.precondition_checks,
-  // submission.precondition_checks)` form re-invoked the `__proto__` setter when
-  // the operator submitted JSON containing a `__proto__` key. JSON.parse keeps
-  // `__proto__` as an own data property (CreateDataProperty), but Object.assign
-  // reads it via `[[Get]]` and writes via `[[Set]]`, which DOES trigger the
-  // prototype-rebinding setter. The polluted prototype is confined to
-  // `out.precondition_checks` (not global Object.prototype), but any future code
-  // path that calls `.hasOwnProperty()` directly on the bag would observe the
-  // pollution. Switch to own-key iteration so the prototype stays unmodified.
+  // Own-key iteration, never Object.assign: JSON.parse keeps a submitted
+  // `__proto__` as an own data property, but Object.assign writes it through
+  // [[Set]] and triggers the prototype-rebinding setter on the bag.
   if (submission.precondition_checks) {
     for (const k of Object.keys(submission.precondition_checks)) {
       if (k === '__proto__' || k === 'constructor' || k === 'prototype') continue;
@@ -3683,13 +2640,9 @@ function normalizeSubmission(submission, playbook) {
   return out;
 }
 
-/**
- * Smart precondition auto-detect (redesign #9). Some preconditions are
- * mechanically answerable by the runner itself — host platform, cwd
- * readability, command-on-PATH. The AI shouldn't have to declare these;
- * we resolve them ourselves and only escalate to AI declaration when the
- * check requires intent (e.g. "operator authorized this scan").
- */
+// Answer the preconditions the runner can answer itself — host platform, cwd
+// readability, command-on-PATH — leaving only the ones that require intent
+// ("operator authorized this scan") for the AI to declare.
 function autoDetectPreconditions(submission, playbook) {
   const fs = require('fs');
   const out = { ...(submission || {}) };
@@ -3712,17 +2665,14 @@ function autoDetectPreconditions(submission, playbook) {
       const probe = spawnSync(process.platform === 'win32' ? 'where' : 'which', [cmdName], { stdio: 'ignore' });
       out.precondition_checks[pc.id] = probe.status === 0;
     }
-    // Intent-requiring checks (e.g. "operator_authorized == true") are NOT
-    // auto-resolved — the AI / operator still declares them. We leave them
-    // undefined and the preflight gate handles missing values per on_fail.
+    // An intent check ("operator_authorized == true") is left undefined for
+    // the operator to declare; preflight handles the missing value per on_fail.
   }
   return out;
 }
 
+// The seven phases in one call.
 function run(playbookId, directiveId, agentSubmission = {}, runOpts = {}) {
-  // Catalog corruption blocks runs cleanly. Probed lazily here (before the
-  // analyze path) rather than at module load, so cheap verbs don't pay the
-  // catalog-parse cost.
   const xrefErr = getXrefLoadError();
   if (xrefErr) {
     return {
@@ -3737,7 +2687,6 @@ function run(playbookId, directiveId, agentSubmission = {}, runOpts = {}) {
   try {
     playbook = loadPlaybook(playbookId);
   } catch (e) {
-    // loadPlaybook failure → structured error (not crash).
     return {
       ok: false,
       blocked_by: 'playbook_not_found',
@@ -3746,10 +2695,8 @@ function run(playbookId, directiveId, agentSubmission = {}, runOpts = {}) {
     };
   }
 
-  // Validate directiveId before any phase runs. An unknown id would
-  // otherwise throw inside analyze() / findDirective() uncaught, surfacing
-  // as a 500-style stack trace; instead return a clean structured error
-  // with the valid directive list.
+  // Before any phase runs: an unknown id otherwise throws uncaught inside
+  // findDirective() and surfaces as a stack trace.
   const validDirectives = (playbook.directives || []).map(d => d.id);
   if (!validDirectives.includes(directiveId)) {
     return {
@@ -3760,27 +2707,15 @@ function run(playbookId, directiveId, agentSubmission = {}, runOpts = {}) {
     };
   }
 
-  // v0.11.0: accept flat submission shape (observations + verdict). Normalize
-  // to the engine's internal nested shape before preflight/detect. Smart
-  // precondition auto-detect (redesign #9) fires here when the cwd is readable
-  // / the host platform matches — the runner can answer those itself rather
-  // than blocking on AI declaration.
   agentSubmission = normalizeSubmission(agentSubmission, playbook);
-  // Capture pre-autoDetect submission preconditions so we report
-  // user-declared provenance, not engine-auto-resolved values.
+  // Captured before auto-detect so the provenance report distinguishes what
+  // the operator declared from what the engine resolved.
   const originalSubmissionPCs = { ...(agentSubmission.precondition_checks || {}) };
   agentSubmission = autoDetectPreconditions(agentSubmission, playbook);
 
-  // precondition_checks merge order is submission → runOpts (runOpts
-  // wins on collision). This is intentional: runOpts represents the most
-  // recent caller intent (CLI flags / programmatic injection from a host
-  // process), whereas submission was captured earlier during evidence
-  // collection. The order is documented here AND surfaced as
-  // preflight.precondition_check_source on the result so callers can see
-  // whether the value came from the submission, runOpts, or both
-  // (merged with runOpts winning). Provenance reports the ORIGINAL submission
-  // contents — autoDetectPreconditions adds engine-derived values that
-  // wouldn't be meaningful as "submission" provenance.
+  // precondition_checks merge submission → runOpts, runOpts winning as the
+  // most recent caller intent; the submission was captured earlier, during
+  // evidence collection. precondition_check_source names which side won.
   const fullSubmissionPCs = agentSubmission.precondition_checks || {};
   const runOptsPCs = runOpts.precondition_checks || {};
   const mergedPCs = { ...fullSubmissionPCs, ...runOptsPCs };
@@ -3788,23 +2723,15 @@ function run(playbookId, directiveId, agentSubmission = {}, runOpts = {}) {
   for (const k of Object.keys(mergedPCs)) {
     const inOrigSub = Object.prototype.hasOwnProperty.call(originalSubmissionPCs, k);
     const inRun = Object.prototype.hasOwnProperty.call(runOptsPCs, k);
-    // A key present in neither the original submission nor runOpts was filled
-    // in by autoDetectPreconditions (engine-derived host/platform facts) —
-    // report it as 'auto', not 'submission'. Otherwise: submission ∩ runOpts =
-    // a genuine programmatic override of a submitted value ('merged');
-    // runOpts-only = 'runOpts'; submission-only = 'submission'.
+    // In neither side means autoDetectPreconditions supplied it ('auto'); in
+    // both means a programmatic override of a submitted value ('merged').
     if (!inOrigSub && !inRun) pcSource[k] = 'auto';
     else pcSource[k] = (inOrigSub && inRun) ? 'merged' : (inRun ? 'runOpts' : 'submission');
   }
   const pre = preflight(playbook, { ...runOpts, precondition_checks: mergedPCs });
   if (!pre.ok) {
-    // Blocked results MUST carry playbook_id + directive_id at the
-    // result root, the same as successful results. Without this,
-    // consumers iterating results[] can't identify which playbook
-    // produced a preflight failure without joining against
-    // playbooks_run[] by array index. `verdict:"blocked"` +
-    // `summary_line` keep the flat result-envelope shape consistent
-    // across both branches.
+    // A blocked result carries the same envelope fields as a successful one, so
+    // a consumer iterating results[] can name the playbook that failed.
     const summaryLine = capSummary(`${playbookId}: blocked at preflight (${pre.blocked_by || 'unknown'}) — ${pre.reason || ''}`);
     return {
       ok: false,
@@ -3822,21 +2749,13 @@ function run(playbookId, directiveId, agentSubmission = {}, runOpts = {}) {
     };
   }
 
-  // Cross-process mutex lock for this run. Use the diagnostic variant so a
-  // CONFIRMED live foreign holder BLOCKS the run. The bare acquireLock returned
-  // null on a lost race (the TOCTOU window between preflight's check and the
-  // acquire) and the run then proceeded UNLOCKED, defeating the mutex. Block
-  // only on `held_by_live_pid` — same-PID reentrancy and FS quirks still
-  // proceed best-effort (lockPath null), so no legitimate nested/edge case
-  // regresses. Released in the finally block.
+  // The diagnostic variant, because bare acquireLock returns null on a race
+  // lost in the TOCTOU window since preflight's check, and the run would then
+  // proceed UNLOCKED. Released in the finally block below.
   const lockResult = acquireLockDiagnostic(playbookId);
-  // Block ONLY on a confirmed live foreign holder with a real numeric pid.
-  // acquireLockDiagnostic also returns reason:'held_by_live_pid' with
-  // holder_pid:null for a MALFORMED/truncated lockfile (it can't parse a pid to
-  // probe). Blocking on that would let one corrupted lockfile left by a crash
-  // deny every future run forever. A null-pid (malformed) lock instead falls
-  // through to proceed best-effort (lockPath null) — matching how the preflight
-  // mutex check treats unparsable lockfiles as stale.
+  // Only on a confirmed live foreign holder with a real pid. A malformed
+  // lockfile reports held_by_live_pid too, with holder_pid null, and blocking on
+  // that lets one file left by a crash deny every future run forever.
   if (!lockResult.ok && lockResult.reason === 'held_by_live_pid'
       && Number.isInteger(lockResult.holder_pid) && lockResult.holder_pid > 0) {
     return {
@@ -3854,26 +2773,11 @@ function run(playbookId, directiveId, agentSubmission = {}, runOpts = {}) {
   }
   const lockPath = lockResult.ok ? lockResult.path : null;
   _activeRuns.add(playbookId);
-  // Parse the playbook once at run() entry and thread the parsed object
-  // through each phase via runOpts._playbookCache. Each phase otherwise
-  // calls loadPlaybook() independently; for a single run that's seven
-  // reads + parses of the same file. Caching saves the redundant I/O +
-  // JSON parses.
-  //
-  // session_id is generated ONCE here and threaded into close() via
-  // cachedRunOpts.session_id so CSAF tracking.id / OpenVEX @id / product
-  // PURLs / on-disk attestation filenames all share one identifier.
-  // Without the single-source-of-truth, close() would mint its own id
-  // and operators correlating attestation files to embedded bundle URNs
-  // would see mismatches.
-  //
-  // v0.12.27: when runOpts.bundleDeterministic is set AND the operator did
-  // not pass --session-id, derive the session_id from the submission shape
-  // so two runs against identical evidence produce the same id (and
-  // therefore the same CSAF tracking.id / OpenVEX @id / attestation file
-  // name). Mirrors the evidence_hash path further down but is computed
-  // here so close() can thread it through. Operator-supplied --session-id
-  // still wins on collision.
+  // The playbook is parsed once and threaded through every phase as
+  // runOpts._playbookCache. session_id is minted once, so the CSAF tracking.id,
+  // OpenVEX @id, product PURLs and attestation filename carry one correlatable
+  // identifier. Under bundleDeterministic it derives from the submission, so two
+  // runs over identical evidence agree; --session-id still wins.
   let sessionId;
   if (runOpts.session_id) {
     sessionId = runOpts.session_id;
@@ -3884,12 +2788,9 @@ function run(playbookId, directiveId, agentSubmission = {}, runOpts = {}) {
         .update(canonicalStringify(extractSubmissionForHash(agentSubmission)))
         .digest('hex');
     } catch (e) {
-      // canonicalStringify deliberately throws (EVIDENCE_TOO_DEEP) on
-      // pathological nesting. The mutex lockfile and the _activeRuns entry
-      // are already held here, but the protecting try/finally below has
-      // not opened yet — release both before rethrowing, or the leaked
-      // lockfile blocks every subsequent run of this playbook for as long
-      // as this PID lives.
+      // canonicalStringify throws EVIDENCE_TOO_DEEP on pathological nesting,
+      // and the try/finally below has not opened yet — a leaked lockfile would
+      // block every later run of this playbook for this PID's lifetime.
       _activeRuns.delete(playbookId);
       releaseLock(lockPath);
       throw e;
@@ -3902,24 +2803,19 @@ function run(playbookId, directiveId, agentSubmission = {}, runOpts = {}) {
     sessionId = crypto.randomBytes(8).toString('hex');
   }
   const cachedRunOpts = { ...runOpts, _playbookCache: playbook, session_id: sessionId };
-  // Run-time error accumulator for evalCondition regex failures and other
-  // non-fatal anomalies surfaced into analyze.runtime_errors[].
+  // The run-level accumulator behind analyze.runtime_errors[].
   const runErrors = [];
   cachedRunOpts._runErrors = runErrors;
-  // normalizeSubmission may push structured errors (e.g.
-  // signal_overrides_invalid) onto submission._runErrors. Splice them
-  // into the run-level accumulator so analyze.runtime_errors[] surfaces
-  // them, and strip the field off the submission so it doesn't pollute
-  // the evidence_hash digest (the hash canonicalizes the submission and
-  // a non-deterministic _runErrors would change it).
+  // Splice in what normalizeSubmission pushed, then strip the field off the
+  // submission: the evidence_hash canonicalizes the submission, and a
+  // non-deterministic _runErrors would change the digest.
   if (Array.isArray(agentSubmission._runErrors) && agentSubmission._runErrors.length) {
     runErrors.push(...agentSubmission._runErrors);
   }
   if (agentSubmission && Object.prototype.hasOwnProperty.call(agentSubmission, '_runErrors')) {
     delete agentSubmission._runErrors;
   }
-  // Phases the runner should SKIP execution for, based on skip_phase
-  // preconditions surfaced in preflight.issues.
+  // Phases to skip, from the skip_phase preconditions preflight surfaced.
   const skipPhases = new Set();
   for (const issue of (pre.issues || [])) {
     if (issue.kind === 'precondition_skip' && issue.skip_phase) {
@@ -3948,10 +2844,9 @@ function run(playbookId, directiveId, agentSubmission = {}, runOpts = {}) {
         observations_received: [],
         signals_received: []
       };
-      // analyze() must still run, but with an empty submission so it doesn't
-      // resolve indicator hits against a non-existent detect result.
+      // analyze still runs, on an empty submission so it cannot resolve
+      // indicator hits against a detect result that never happened.
       phases.analyze  = analyze(playbookId, directiveId, phases.detect, {}, cachedRunOpts);
-      // Annotate analyze with the skip vocabulary so consumers can branch.
       phases.analyze.classification = 'skipped';
     } else {
       phases.detect   = detect(playbookId, directiveId, agentSubmission, cachedRunOpts);
@@ -3960,19 +2855,12 @@ function run(playbookId, directiveId, agentSubmission = {}, runOpts = {}) {
     phases.validate = validate(playbookId, directiveId, phases.analyze, agentSubmission.signals || {}, cachedRunOpts);
     phases.close    = close(playbookId, directiveId, phases.analyze, phases.validate, agentSubmission.signals || {}, cachedRunOpts);
 
-    // analyze() already sliced runOpts._runErrors into
-    // phases.analyze.runtime_errors at return time. Validate + close may
-    // have pushed additional regex errors AFTER analyze returned; surface
-    // those onto phases.analyze.runtime_errors so the field reflects every
-    // regex failure in the run. De-dupe by JSON shape so the analyze-time
-    // snapshot doesn't double-count.
+    // analyze() snapshotted the accumulator when it returned; validate and
+    // close push after that, so late entries merge back in.
     if (runErrors.length && phases.analyze) {
-      // `_truncated` sentinels are pushed by pushRunError when a per-kind
-      // or total cap fires. They aggregate via in-place `dropped` increments,
-      // so the same sentinel object is BOTH in the analyze snapshot AND in
-      // the late-push `runErrors` ref. Skip them on the dedupe-merge pass
-      // to keep the snapshot's authoritative dropped-count, rather than
-      // double-stamping a second sentinel with the same `dropped` value.
+      // A `_truncated` sentinel aggregates through in-place `dropped`
+      // increments, so the same object sits in both arrays; skipping it keeps
+      // one authoritative count instead of stamping a duplicate.
       const existing = new Set(
         (phases.analyze.runtime_errors || [])
           .filter(e => !(e && e.kind === '_truncated'))
@@ -3984,16 +2872,10 @@ function run(playbookId, directiveId, agentSubmission = {}, runOpts = {}) {
       }
     }
 
-    // evidence_hash binds the operator's submission to the verdict. The
-    // hash must include the canonicalized submission (observations,
-    // signal_overrides, signals) — keying it on only { playbook, directive,
-    // cves, rwep, classification } would let two operators with completely
-    // different evidence collide on the same hash whenever their
-    // classifications match. Use SHA-256 over the recursively sorted
-    // submission. `captured_at` and other timestamp-like fields are
-    // INTENTIONALLY excluded so that re-running with the same submission
-    // produces the same hash — `reattest` relies on this to detect drift
-    // (different submission → different hash → drift exists).
+    // evidence_hash covers the canonicalized submission itself: keyed on only
+    // { playbook, directive, cves, rwep, classification }, two operators with
+    // different evidence collide whenever their classifications match.
+    // Timestamps are excluded so one submission always hashes the same.
     const submissionDigest = crypto.createHash('sha256')
       .update(canonicalStringify(extractSubmissionForHash(agentSubmission)))
       .digest('hex');
@@ -4007,24 +2889,14 @@ function run(playbookId, directiveId, agentSubmission = {}, runOpts = {}) {
       }))
       .digest('hex');
 
-    // Hoist the operator-facing summary to the result root so a `ci`
-    // consumer does not have to walk into phases.detect.classification
-    // + phases.analyze.rwep.adjusted separately to answer the most
-    // common ops question ("did this playbook detect anything?").
-    //
-    // Verdict source: phases.detect.classification is the canonical
-    // signal — one of detected / not_detected / inconclusive / pending
-    // / skipped. validate() does NOT carry a `verdict` field, so
-    // sourcing the hoist from phases.validate.verdict would degrade
-    // every non-blocked result to the fallback "inconclusive".
+    // Hoisted to the result root so a `ci` consumer answers "did this detect
+    // anything?" without walking into phases. detect.classification is the
+    // canonical verdict — validate() carries no `verdict` field.
     const verdict = (phases.detect && phases.detect.classification) || 'inconclusive';
     const rwepScore = phases.analyze && phases.analyze.rwep && typeof phases.analyze.rwep.adjusted === 'number'
       ? phases.analyze.rwep.adjusted : null;
-    // Top finding = first matched CVE-id when present; otherwise the dominant
-    // FIRED indicator's id (the signal that actually drove the verdict), not
-    // the verdict string itself. Echoing the classification made top_finding
-    // carry no information beyond `verdict` and duplicated it in summary_line
-    // (e.g. "detected (rwep=10, detected, ...)"). The full set lives in phases.
+    // The first matched CVE id, else the fired indicator that drove the
+    // verdict — never the classification, which duplicates `verdict`.
     let topFinding = null;
     if (phases.analyze && Array.isArray(phases.analyze.matched_cves) && phases.analyze.matched_cves.length) {
       topFinding = phases.analyze.matched_cves[0].cve_id;
@@ -4034,14 +2906,9 @@ function run(playbookId, directiveId, agentSubmission = {}, runOpts = {}) {
         && phases.detect.classification !== 'not_detected'
         && phases.detect.classification !== 'inconclusive'
         && phases.detect.classification !== 'pending') {
-      // Only on a real detection verdict: surface the FIRED indicator that
-      // best explains the result. Gating on the verdict keeps a stray hit on
-      // an inconclusive/not-detected run from advertising a finding. Prefer the
-      // indicator that actually drove the RWEP score — the greatest
-      // weight_applied among fired, weight-bearing rwep_inputs — so the
-      // headline names the finding that produced the number shown beside it.
-      // Fall back to the dominant fired indicator (deterministic/high
-      // confidence), then the first hit, when no weighted signal fired.
+      // Only on a real detection verdict, so a stray hit on an inconclusive run
+      // cannot advertise a finding. The indicator that drove the RWEP score
+      // wins, then the dominant fired indicator, then the first hit.
       const breakdown = (phases.analyze.rwep && Array.isArray(phases.analyze.rwep.breakdown))
         ? phases.analyze.rwep.breakdown : [];
       const driver = breakdown
@@ -4052,12 +2919,9 @@ function run(playbookId, directiveId, agentSubmission = {}, runOpts = {}) {
       if (driver && driver.signal_id) topFinding = driver.signal_id;
       else if (dominant && dominant.id) topFinding = dominant.id;
     }
-    // Evidence completeness: indicators-evaluated vs indicators-known
-    // distinguishes "ran fully and found nothing" from "couldn't
-    // actually evaluate". Without this, the two states look identical
-    // at the result-root level — a not_detected verdict with zero
-    // indicators-evaluated reads the same as one with every indicator
-    // evaluated and miss.
+    // Evaluated against known separates "ran fully and found nothing" from
+    // "could not evaluate" — a not_detected verdict over zero indicators
+    // otherwise reads exactly like one where every indicator missed.
     const indicatorsKnown = (playbook.phases && playbook.phases.detect && playbook.phases.detect.indicators)
       ? playbook.phases.detect.indicators.length : null;
     const indicatorsEvaluated = phases.detect && typeof phases.detect.indicators_evaluated_count === 'number'
@@ -4076,10 +2940,7 @@ function run(playbookId, directiveId, agentSubmission = {}, runOpts = {}) {
       playbook_id: playbookId,
       directive_id: directiveId,
       session_id: sessionId,
-      // Flat top-level fields (B2 + B6 + B9). Operators no longer need
-      // to spelunk through phases.* to get the answer to the most
-      // common question. The phases tree is still present below for
-      // anyone who needs the full CSAF / analyze / detect dumps.
+      // The flat answer; the phases tree below carries the full dumps.
       verdict,
       rwep_score: rwepScore,
       top_finding: topFinding,
@@ -4090,15 +2951,12 @@ function run(playbookId, directiveId, agentSubmission = {}, runOpts = {}) {
       evidence_hash: evidenceHash,
       submission_digest: submissionDigest,
       preflight_issues: pre.issues,
-      // Non-fatal collector notices (e.g. a file skipped for exceeding the
-      // scan size limit) surfaced from the submission so a `collect | run`
-      // consumer can see what the collector could not scan. Advisory only:
-      // never affects verdict, rwep, or evidence_completeness.
+      // What the collector could not scan. Advisory only — never affects
+      // verdict, rwep or evidence_completeness.
       ...(Array.isArray(agentSubmission.collector_errors) && agentSubmission.collector_errors.length
         ? { collector_warnings: agentSubmission.collector_errors }
         : {}),
-      // Source provenance for precondition_checks. Shape:
-      //   { '<pc-id>': 'submission' | 'runOpts' | 'merged', ... }
+      // { '<pc-id>': 'submission' | 'runOpts' | 'merged' | 'auto', … }
       precondition_check_source: pcSource,
       phases
     };
@@ -4108,25 +2966,15 @@ function run(playbookId, directiveId, agentSubmission = {}, runOpts = {}) {
   }
 }
 
-// --- helpers ---
-
-/**
- * Deterministic JSON stringification with recursively sorted keys.
- * Without sorted keys two semantically identical submissions ({a:1, b:2}
- * vs {b:2, a:1}) would hash to different digests, breaking reattest's
- * "same submission → same hash" contract. Arrays preserve order
- * (submission order is meaningful for evidence). null + primitives pass
- * through directly. Avoids JSON.stringify's replacer indirection because
- * a top-level array would otherwise miss the canonicalization recursion.
- */
+// Deterministic JSON with recursively sorted keys: {a:1, b:2} and {b:2, a:1}
+// must hash alike or reattest's "same submission → same hash" breaks. Array
+// order is preserved — submission order is meaningful for evidence. Throws
+// EVIDENCE_TOO_DEEP past CANONICAL_MAX_DEPTH.
 const CANONICAL_MAX_DEPTH = 200;
 function canonicalStringify(v, _depth = 0) {
   if (v === null || typeof v !== 'object') return JSON.stringify(v);
-  // Bounded recursion: adversarial (or accidental) deeply-nested evidence
-  // would otherwise overflow the stack with an opaque "internal error". This
-  // runs on every run() (evidence_hash + session_id derivation), so the guard
-  // turns a crash into an actionable rejection. 200 levels is far beyond any
-  // legitimate submission.
+  // Deeply-nested evidence would overflow the stack with an opaque internal
+  // error; 200 is far beyond any legitimate submission.
   if (_depth > CANONICAL_MAX_DEPTH) {
     const e = new Error(`evidence nesting exceeds the maximum depth of ${CANONICAL_MAX_DEPTH} — flatten the submission`);
     e.code = 'EVIDENCE_TOO_DEEP';
@@ -4137,20 +2985,12 @@ function canonicalStringify(v, _depth = 0) {
   return '{' + keys.map(k => JSON.stringify(k) + ':' + canonicalStringify(v[k], _depth + 1)).join(',') + '}';
 }
 
-// Re-key an artifacts map by the stable indicator id each artifact was bound to
-// (recovered by inverting _signal_origins: indicator-id -> observation-key), so
-// the evidence_hash reflects the evidence VALUE + its stable binding rather than
-// the operator's free-text observation label. Without this, two submissions with
-// identical (indicator, value) evidence under different observation keys
-// (obs-kver vs x1) hashed differently and attest/reattest reported false drift —
-// the attest diff re-keys the COMPARISON (bin/exceptd.js); the hash itself was
-// not covered. Collision-safe (mirrors that helper): re-key only when the stable
-// id is not already a DISTINCT original key and has not been claimed by an
-// earlier entry, else keep the original key so no artifact is silently dropped.
+// Re-key an artifacts map by the stable indicator id, recovered by inverting
+// _signal_origins, so evidence_hash reflects the evidence VALUE and its binding
+// rather than the operator's free-text observation label. bin/exceptd.js re-keys
+// the attest COMPARISON the same way. Collision-safe: a stable id already used
+// as a distinct key keeps the original, dropping nothing.
 function _rekeyArtifactsByStableId(artifacts, signalOrigins) {
-  // The sole caller (extractSubmissionForHash) only invokes this inside
-  // `if (sub.artifacts && typeof sub.artifacts === 'object')`, so `artifacts`
-  // is always a non-null object — guard only on the re-key map being usable.
   if (!signalOrigins || typeof signalOrigins !== 'object') return artifacts;
   const obsKeyToIndicator = {};
   for (const [indicatorId, obsKey] of Object.entries(signalOrigins)) {
@@ -4167,20 +3007,13 @@ function _rekeyArtifactsByStableId(artifacts, signalOrigins) {
   return out;
 }
 
-/**
- * Pick the operator-meaningful fields out of the normalized submission
- * for hashing. captured_at, _signal_origins, _signal_origins_collisions,
- * and _original_shape are intentionally excluded — they're either
- * timestamps (would break "same submission → same hash") or runner-internal
- * provenance metadata that isn't part of what the operator submitted.
- */
+// The operator-meaningful fields of a normalized submission, for hashing.
+// captured_at, _signal_origins, _signal_origins_collisions and _original_shape
+// are excluded as timestamps, which break "same submission → same hash", or as
+// runner-internal provenance the operator never submitted.
 function extractSubmissionForHash(sub) {
   if (!sub || typeof sub !== 'object') return {};
   const pick = {};
-  // Strip captured_at from artifact entries so timestamp drift doesn't
-  // perturb the digest. The semantic content (value + captured-ness +
-  // optional indicator binding) is what matters for "did the operator
-  // submit the same evidence?".
   if (sub.artifacts && typeof sub.artifacts === 'object') {
     const stripped = {};
     for (const [k, v] of Object.entries(sub.artifacts)) {
@@ -4191,45 +3024,26 @@ function extractSubmissionForHash(sub) {
         stripped[k] = v;
       }
     }
-    // Re-key by the stable indicator id so the digest reflects the evidence
-    // VALUE + its binding, never the operator's free-text observation label.
-    // Identical (indicator, value) evidence under different observation keys
-    // must produce the SAME evidence_hash / submission_digest / session_id.
     pick.artifacts = _rekeyArtifactsByStableId(stripped, sub._signal_origins);
   }
   if (sub.signal_overrides && typeof sub.signal_overrides === 'object') {
     pick.signal_overrides = sub.signal_overrides;
   }
   if (sub.signals && typeof sub.signals === 'object') {
-    // vex_filter and vex_fixed may be Sets — convert to sorted arrays so
-    // canonicalStringify can serialize them.
+    // vex_filter and vex_fixed arrive as Sets; sorted arrays serialize.
     const signals = {};
     for (const [k, v] of Object.entries(sub.signals)) {
-      // Underscore-prefixed signal keys are runner-internal / output-rendering
-      // directives, NOT operator evidence: `_bundle_formats` (the CLI sets it
-      // from `--format sarif|openvex|csaf`) only chooses which bundle close()
-      // renders — the analyzed posture is identical. Hashing it broke the
-      // "same evidence → same evidence_hash" contract: two runs over identical
-      // evidence that differ only in `--format` produced different digests and
-      // a self-contradicting attest diff. Exclude every `_`-prefixed signal key
-      // (matches the file-wide "underscore = internal" convention). vex_filter /
-      // vex_fixed are deliberately NOT excluded — they DROP CVEs from
-      // matched_cves and change the finding, so they are posture-affecting
-      // evidence; excluding them would make reattest blind to a VEX-driven
-      // posture change (a real drift hidden behind an unchanged hash).
+      // An underscore-prefixed signal is a render directive, not evidence:
+      // hashing `_bundle_formats` makes two runs differing only in --format
+      // produce different digests. vex_filter and vex_fixed stay IN — they drop
+      // CVEs and change the finding.
       if (k.startsWith('_')) continue;
       if (v instanceof Set) signals[k] = Array.from(v).sort();
       else signals[k] = v;
     }
-    // Omit an empty signals bag rather than recording `signals: {}`. A
-    // submission whose ONLY signal was a `_`-prefixed render directive
-    // (`{ _bundle_formats: [...] }`, injected by `ci`/`run --format`) reduces to
-    // {} after the filter above; the baseline no-format submission carries no
-    // `signals` key at all. Recording `{}` vs omitting it would hash identical
-    // evidence as `{signals:{}}` vs no-signals and reintroduce the exact
-    // --format-driven evidence_hash / session-id drift this exclusion exists to
-    // prevent. Only attach signals when at least one operator-meaningful key
-    // survived.
+    // An empty bag is omitted, not recorded as `signals: {}`: a submission whose
+    // only signal was a render directive reduces to {} here while the baseline
+    // has no `signals` key, reintroducing the --format drift filtered above.
     if (Object.keys(signals).length > 0) pick.signals = signals;
   }
   if (sub.precondition_checks && typeof sub.precondition_checks === 'object') {
@@ -4244,13 +3058,10 @@ function extractSubmissionForHash(sub) {
   return pick;
 }
 
-// Identity fields a `contains`/`includes` membership test targets when the
-// array holds objects (e.g. jurisdiction_obligations records). Membership is
-// field-scoped to these so a non-identity field (clock_starts, obligation,
-// regulation, a free-form tag) that happens to equal the member cannot satisfy
-// the predicate. `jurisdiction` is the only field the catalog's object-array
-// `contains` conditions target today; the allowlist is the seam to extend if a
-// future condition deliberately matches a different identity field.
+// The identity fields a `contains`/`includes` test targets when the array holds
+// objects. Scoping membership to these keeps a non-identity field that happens
+// to equal the member (a clock_starts of 'detect_confirmed', a free-form tag
+// reading 'EU') from satisfying the predicate.
 const OBJECT_MEMBERSHIP_FIELDS = ['jurisdiction'];
 
 function evalCondition(expr, ctx, playbook) {
@@ -4261,44 +3072,23 @@ function evalCondition(expr, ctx, playbook) {
   if (expr === 'true') return true;
   if (expr === 'false') return false;
 
-  // Honor operator precedence: OR is lower precedence than AND, so split on OR
-  // first. splitAtTopLevel walks the expression depth-aware so parens correctly
-  // group sub-expressions — i.e. `A OR (B AND C)` parses with B,C as one AND
-  // group rather than splitting at the inner AND.
+  // OR binds looser than AND, so it splits first; splitAtTopLevel is
+  // depth-aware, so `A OR (B AND C)` keeps B and C as one group.
   const orParts = splitAtTopLevel(expr, 'OR');
   if (orParts.length > 1) return orParts.some(s => evalCondition(s, ctx, playbook));
 
   const andParts = splitAtTopLevel(expr, 'AND');
   if (andParts.length > 1) return andParts.every(s => evalCondition(s, ctx, playbook));
 
-  // Quantifier prefix: catalog conditions write `any <path> <op> <value>`
-  // (e.g. framework.json's feeds_into `any compliance_theater_check.verdict ==
-  // 'theater' …`). An unhandled `any `/`all ` prefix is unparseable and falls
-  // through to `false`, silently disabling the clause it gates. Strip the
-  // quantifier and re-evaluate the inner comparison: when the LHS path resolves
-  // to a scalar (the framework theater_verdict case) the quantifier is prose
-  // emphasis and the scalar comparison is the intended test; when the LHS first
-  // segment resolves to an array, apply the predicate existentially (`any`) /
-  // universally (`all`) across its elements. The inner clause is only the leaf
-  // comparison (the surrounding AND/OR has already been split off above).
+  // Catalog conditions write `any <path> <op> <value>`. An array head applies
+  // the predicate existentially or universally across its elements; a scalar
+  // head means the quantifier was prose and the comparison is the real test.
   const quant = expr.match(/^(any|all)\s+(.+)$/);
   if (quant) {
     const [, kind, inner] = quant;
-    // `any head.rest <op|keyword> …` → re-root the predicate at each element of
-    // `head` and apply it existentially (`any`) / universally (`all`). The head
-    // is the FIRST dotted-path token of the inner clause; what follows it (`==`,
-    // `IN [...]`, `contains`, `matches /…/`, `>=`, …) is operator-agnostic — the
-    // inner clause is re-evaluated whole against `{ …ctx, [head]: el }`, so every
-    // operator the leaf parser already understands works under a quantifier.
-    // Earlier this branch only re-rooted clauses whose operator was in the
-    // comparison set (`>=|<=|==|=|<|>|!=`); `IN`/`contains`/`matches` were
-    // omitted, so e.g. sbom.json's `any matched_cve.attack_class IN
-    // ['ai-c2','prompt-injection']` (the sbom→ai-api feeds_into trigger) fell
-    // through to a whole-ctx eval where `matched_cve.attack_class` resolved to
-    // undefined on the array and the clause was permanently false, while the
-    // sibling `== 'kernel-lpe'` quantifiers fired. Requiring a `.`-qualified head
-    // keeps the bare-token form (`any <path>`) routed to the non-emptiness branch
-    // below.
+    // The clause is re-evaluated WHOLE against `{ …ctx, [head]: el }`, so every
+    // operator the leaf parser understands works under a quantifier. A
+    // `.`-qualified head routes the bare `any <path>` form to the branch below.
     const headMatch = inner.match(/^([A-Za-z_][\w-]*)(?:\.[A-Za-z_][\w-]*)+(?:[\s.[]|$)/);
     if (headMatch) {
       const head = headMatch[1];
@@ -4308,44 +3098,24 @@ function evalCondition(expr, ctx, playbook) {
         return kind === 'all' ? arr.length > 0 && arr.every(test) : arr.some(test);
       }
     }
-    // Bare-quantifier non-emptiness form: `any <path>` / `all <path>` with no
-    // comparison operator is a quantifier OVER the resolved collection itself —
-    // the author's intent is "at least one X exists" (`any`) / "every X is
-    // truthy" (`all`), i.e. a non-emptiness / existence test. sbom.json's
-    // `any actively_exploited_match …` EU CRA Art.14 (24h) notify_legal
-    // escalation is the canonical case. Without this, the inner bare token has
-    // no operator, so no comparison branch parses it and it falls through to
-    // condition_unparsed → false, silently disabling the escalation even when
-    // the array holds entries. Match ONLY a pure dotted-path token (no operator,
-    // keyword, bracket, or space); anything with a comparison/keyword still
-    // routes to the prose fall-through below so a genuinely malformed inner
-    // clause stays observable.
+    // `any <path>` with no operator quantifies over the collection itself. The
+    // match is a pure dotted-path token, so a malformed inner clause falls
+    // through to the diagnostic instead of reading as an existence test.
     if (/^[A-Za-z_][\w-]*(?:\.[A-Za-z_][\w-]*)*$/.test(inner)) {
       const v = resolvePath(ctx, inner);
       if (Array.isArray(v)) {
         return kind === 'all' ? v.length > 0 && v.every(Boolean) : v.length > 0;
       }
-      // Non-array scalar: existence/truthiness (null/undefined/0/'' → false).
       return !!v;
     }
-    // Scalar (or unresolved-array) LHS: the quantifier is prose; evaluate the
-    // bare inner comparison. If it still doesn't parse it falls through to the
-    // condition_unparsed diagnostic below, so a genuinely malformed clause stays
-    // observable rather than silently passing.
+    // The quantifier was prose: evaluate the bare inner comparison.
     return evalCondition(inner, ctx, playbook);
   }
 
-  // Membership clauses (`contains`/`includes`/`IN [...]`) parse fine but resolve
-  // their LHS path to a collection. When that path does NOT exist in ctx (the
-  // resolved value is null/undefined — an authoring typo in the LHS token, or a
-  // wrong-shape ctx that never populated the collection), the branch returns a
-  // silent `false` that disables whatever escalation / feeds_into the clause
-  // gates with no signal. The clause PARSED, so condition_unparsed (a
-  // parse-failure diagnostic) never fires. Surface a distinct, low-severity
-  // condition_path_unresolved so an LHS-path typo is observable — deduped on the
-  // condition string like condition_unparsed. A present-but-empty array (or any
-  // present value that simply isn't a collection) is a LEGITIMATE false, not an
-  // unresolved path, so it does NOT push: only a literally-absent path does.
+  // A clause whose LHS path is absent from ctx parses fine and returns a silent
+  // false, disabling what it gates without firing condition_unparsed. Only a
+  // literally-absent path pushes: a present-but-empty array, or any present
+  // non-collection, is a legitimate false.
   const pushPathUnresolved = () => {
     const target = (ctx && Array.isArray(ctx._runErrors)) ? ctx._runErrors
       : (playbook && Array.isArray(playbook._runErrors)) ? playbook._runErrors
@@ -4356,71 +3126,49 @@ function evalCondition(expr, ctx, playbook) {
     }
   };
 
-  // "rwep >= 90". The LHS/RHS path tokens admit hyphens because signal and
-  // indicator IDs are canonically hyphenated across the catalog (e.g.
-  // `no-security-md`, `kver-in-affected-range`); a `\w`-only token silently
-  // failed to match every hyphenated condition and fell through to `false`.
+  // "rwep >= 90". Path tokens admit hyphens because signal and indicator ids
+  // are canonically hyphenated across the catalog, and a `\w`-only token
+  // matches none of them — every such condition falls silently to `false`.
   let m = expr.match(/^([A-Za-z_][\w-]*(?:\.[A-Za-z_][\w-]*)*)\s*(>=|<=|==|=|<|>|!=)\s*(['"]?)([^'"]+)\3$/);
   if (m) {
     const [, lhs, op, quote, rhsRaw] = m;
     const lv = resolvePath(ctx, lhs);
-    // A DOTTED (multi-segment) LHS that resolves absent is a suspicious dead
-    // condition (authoring typo / wrong-shape ctx) — the same silent-false class
-    // the contains/includes/IN branches already surface. Surface it as
-    // condition_path_unresolved (observability only; the boolean result is
-    // unchanged). Use `== null` (not strict undefined): resolvePath returns
-    // `null` for a missing INTERMEDIATE parent and `undefined` for a missing
-    // LEAF, so a strict-undefined gate would miss `analyze.classification` when
-    // `analyze` itself is absent. Bare single-segment flags
-    // (agent_has_filesystem_read, operator-submitted signals) are legitimately
-    // absent and do NOT push. A present-but-null flag is a legitimate false:
-    // single-segment, so the dot guard already excludes it. pushPathUnresolved
-    // dedupes on the condition string and is per-kind capped, so it can't spam.
+    // Diagnostics only; the boolean is unchanged. `== null`, not strict
+    // undefined: resolvePath returns null for a missing intermediate parent and
+    // undefined for a missing leaf. A bare single-segment flag is legitimately
+    // absent and does not push.
     if (lhs.includes('.') && lv == null) pushPathUnresolved();
     let rv = rhsRaw;
     if (quote) {
-      // Explicit quoted string literal — keep as-is.
+      // A quoted literal stays as written.
     } else if (rv === 'true') rv = true;
     else if (rv === 'false') rv = false;
     else if (!isNaN(parseFloat(rv)) && /^-?\d+(\.\d+)?$/.test(rv.trim())) rv = parseFloat(rv);
     else if (/^[a-z_][\w.-]*$/i.test(rv.trim())) {
-      // Unquoted identifier — treat as a context path. Falls through to the
-      // raw string if resolution returns undefined (matches the prior behavior
-      // for literals like `theater` that aren't quoted).
+      // An unquoted identifier is a context path, falling back to the raw
+      // string when it does not resolve (an unquoted literal like `theater`).
       const resolved = resolvePath(ctx, rv.trim());
       if (resolved !== undefined && resolved !== null) rv = resolved;
     }
-    // Severity is an ordinal word ladder (low < medium < high < critical), not
-    // a lexically-ordered string. When both sides are severity words, compare
-    // by rank so `severity >= 'high'` includes 'critical' (raw string `>=`
-    // would exclude it: 'critical' < 'high' lexicographically).
+    // Severity is an ordinal ladder, not a lexical one: with raw string `>=`,
+    // `severity >= 'high'` EXCLUDES 'critical', because 'critical' < 'high'.
     const SEV = { low: 0, medium: 1, high: 2, critical: 3 };
     const lr = SEV[String(lv).toLowerCase()], rr = SEV[String(rv).toLowerCase()];
     let a = (lr !== undefined && rr !== undefined) ? lr : lv;
     let b = (lr !== undefined && rr !== undefined) ? rr : rv;
     const isOrdering = op === '>=' || op === '<=' || op === '>' || op === '<';
     if (isOrdering && (lr === undefined || rr === undefined)) {
-      // Duration literals carry a unit suffix (`24h`, `7d`, `30min`) — the
-      // catalog writes ordering comparisons against them (kernel.json's
-      // `reboot_window > 24h` raise_severity escalation). The RHS-coercion
-      // above only converts a BARE numeric (`/^-?\d+(\.\d+)?$/`), so a unit-
-      // suffixed literal stays a string. A numeric LHS then compares against a
-      // string RHS (`48 > '24h'` → `48 > NaN` → false: a 48h window silently
-      // fails to escalate) and a string LHS compares lexicographically
-      // (`'6h' > '24h'` → `'6' > '2'` → true: a 6h window WRONGLY escalates).
-      // Normalize both sides to canonical hours when a duration unit appears on
-      // either side: a unit-suffixed literal converts by its unit family; a
-      // bare number is taken in the same family as the duration it is compared
-      // against (hours-equivalent magnitude). The comparison is then numeric.
+      // The catalog writes ordering comparisons against unit-suffixed duration
+      // literals (`reboot_window > 24h`), which the RHS coercion above leaves as
+      // strings: `48 > '24h'` becomes `48 > NaN`, and `'6h' > '24h'` compares as
+      // `'6' > '2'`. Both sides normalize to hours instead.
       const la = parseDurationHours(a), ba = parseDurationHours(b);
       if ((la !== null || ba !== null) && la !== null && ba !== null) {
         a = la; b = ba;
       } else if (
         // Two non-numeric, non-severity, non-duration strings under an ordering
-        // operator is a silently-degraded comparison (lexicographic / NaN) — the
-        // clause PARSED so condition_unparsed never fires. Surface a distinct
-        // condition_type_mismatch so the degraded comparison is observable
-        // (the boolean result is unchanged; this is diagnostics only).
+        // operator degrade to a lexicographic or NaN comparison. The clause
+        // parsed, so only condition_type_mismatch makes that observable.
         typeof a !== 'number' && typeof b !== 'number' &&
         !(typeof a === 'string' && /^-?\d+(?:\.\d+)?$/.test(a.trim())) &&
         !(typeof b === 'string' && /^-?\d+(?:\.\d+)?$/.test(b.trim()))
@@ -4444,22 +3192,10 @@ function evalCondition(expr, ctx, playbook) {
     }
   }
 
-  // "scope.targets includes named_remote" — `contains` is accepted as a
-  // synonym for `includes` (the catalog uses both); hyphenated paths + members
-  // are admitted for the same reason as the comparison branch above.
-  // The member may be a bare token OR a quoted string (the catalog's
-  // `jurisdiction_obligations contains 'EU'` / `contains 'EU/EU CRA Art.14 24h'`
-  // forms). When the array holds objects (jurisdiction_obligations are records
-  // like `{ jurisdiction:'EU', regulation:'NIS2 Art.21', … }`), membership is
-  // field-TARGETED: it matches an identity field of the obligation, not ANY
-  // field value. An unscoped `Object.values(el).includes(member)` over-matched
-  // — `contains 'EU'` would be satisfied by a non-jurisdiction field that
-  // happened to equal 'EU' (e.g. a tag), and `contains 'detect_confirmed'`
-  // would match the unrelated `clock_starts` field that holds that exact value
-  // in the shipped obligations. Scoping to OBJECT_MEMBERSHIP_FIELDS keeps the
-  // intended "the obligation is for jurisdiction X" semantic and prevents a
-  // future field collision (or an operator-/agent-supplied obligations array)
-  // from forcing a notify_legal escalation via a non-jurisdiction field.
+  // "scope.targets includes named_remote". `contains` is a synonym the catalog
+  // also writes, and the member may be bare or quoted. Against objects,
+  // membership is scoped to OBJECT_MEMBERSHIP_FIELDS: an unscoped
+  // `Object.values(el).includes(member)` over-matches.
   m = expr.match(/^([A-Za-z_][\w-]*(?:\.[A-Za-z_][\w-]*)*)\s+(?:includes|contains)\s+(?:'([^']+)'|"([^"]+)"|([\w-]+))$/);
   if (m) {
     const member = m[2] !== undefined ? m[2] : (m[3] !== undefined ? m[3] : m[4]);
@@ -4475,25 +3211,11 @@ function evalCondition(expr, ctx, playbook) {
     );
   }
 
-  // "matched_cve.attack_class IN ['kernel-lpe', 'rce']" — membership against a
-  // bracketed literal list; members may be quoted or bare. A scalar LHS must be
-  // in the list; an array LHS must intersect it. Unhandled before, so every
-  // `IN [...]` escalation/feeds_into atom fell through to a silent false.
-  // The member list is split quote-aware: a naive `split(',')` is unaware of
-  // quotes, so a quoted member that itself contains a comma (`'EU, US'`) would
-  // be broken into two members (`EU` and `US`), neither of which equals the
-  // author's intended whole member — the clause then evaluated false with no
-  // diagnostic (the regex still matched the bracket, so condition_unparsed never
-  // fired). splitInMembers walks the list tracking single/double quote state and
-  // only splits on commas at quote-depth 0, then strips the surrounding quotes.
-  // The CLOSING `]` is located quote-aware too: a `[^\]]*` capture stops at the
-  // FIRST `]`, so a quoted member containing a literal `]` (`'a]b'`) truncated
-  // the list early and left trailing text the `$` anchor couldn't match — the
-  // whole clause then fell through to condition_unparsed for every input. The
-  // matching bracket is now found at quote-depth 0 (an unquoted `]` is still the
-  // terminator; a `]` inside a quoted member is part of that member). Trailing
-  // text after the closing bracket, or an unterminated bracket, still fails to
-  // match and surfaces as condition_unparsed.
+  // "matched_cve.attack_class IN ['kernel-lpe', 'rce']" — a scalar LHS must be
+  // in the list, an array LHS must intersect it. Both the member split and the
+  // closing bracket are quote-aware: `split(',')` tears `'EU, US'` into members
+  // that match nothing, and a `[^\]]*` capture truncates `'a]b'`. Either failure
+  // evaluates false with no diagnostic, since the regex still matched.
   m = expr.match(/^([A-Za-z_][\w-]*(?:\.[A-Za-z_][\w-]*)*)\s+IN\s+\[/);
   if (m) {
     const body = sliceInBracketBody(expr.slice(m[0].length));
@@ -4501,44 +3223,29 @@ function evalCondition(expr, ctx, playbook) {
       const members = splitInMembers(body);
       const lv = resolvePath(ctx, m[1]);
       if (Array.isArray(lv)) return lv.some((x) => members.includes(String(x)));
-      // lv == null means the LHS path doesn't exist in ctx (typo / wrong-shape) —
-      // surface it as condition_path_unresolved so the dead clause is observable,
-      // mirroring the contains/includes branch. A present scalar that's simply not
-      // in the member list is a legitimate false and pushes nothing.
+      // An absent LHS path is a dead clause, as in the membership branch; a
+      // present scalar simply not in the list is a legitimate false.
       if (lv == null) { pushPathUnresolved(); return false; }
       return members.includes(String(lv));
     }
-    // body === null → no quote-depth-0 closing `]` ends the string; fall through
-    // to the condition_unparsed diagnostic so the malformed clause stays visible.
+    // No closing bracket at quote-depth 0 — fall through to condition_unparsed.
   }
 
-  // "matched_cve.vector matches /regex/" — both delimiters are accepted: the
-  // slash form `matches /re/` and the quote form `matches 're'` / `matches "re"`.
-  // The catalog authors both (mcp.json's feeds_into uses the quoted form), and a
-  // delimiter-specific parser silently disabled whichever form it didn't match —
-  // the same class as the hyphenated-token gap above.
+  // "matched_cve.vector matches /regex/". The catalog authors the slash and the
+  // quote form, and a one-delimiter parser silently disables the other.
   m = expr.match(/^([A-Za-z_][\w-]*(?:\.[A-Za-z_][\w-]*)*)\s+matches\s+(?:\/(.+)\/|'([^']+)'|"([^"]+)")$/);
   if (m) {
     const pattern = m[2] !== undefined ? m[2] : (m[3] !== undefined ? m[3] : m[4]);
     const val = resolvePath(ctx, m[1]);
     if (typeof val !== 'string') return false;
-    // An operator-supplied or playbook-supplied regex with a syntax bug
-    // (or pathological backtracking) must NOT crash the engine mid-analyze.
-    // Catch construction + test exceptions, return false, and push a
-    // structured _regex_eval_error into ctx._runErrors (when present) so
-    // analyze() can surface analyze.runtime_errors[] without losing the
-    // diagnostic.
+    // A regex with a syntax bug must not crash the engine mid-analyze: the
+    // clause returns false and the failure reaches analyze.runtime_errors[].
     try {
       return new RegExp(pattern, 'i').test(val); // allow:dynamic-regex — pattern comes from an Ed25519-signed catalog playbook condition (/…/ or '…'), so it cannot be attacker-controlled without breaking the signature; the try/catch covers construction-time syntax errors only (it does NOT defend against catastrophic backtracking — do not reuse this shape for operator-supplied patterns)
     } catch (e) {
       const errorRec = { _regex_eval_error: { source: m[1], expr: pattern, message: e && e.message ? String(e.message) : String(e) } };
-      // Two sites where ctx may carry an accumulator: runOpts._runErrors
-      // (threaded from run()) or ctx._runErrors directly. Prefer the runOpts
-      // form; fall back to ctx.
-      // Tag with a `kind` so pushRunError can apply per-kind cap + dedupe
-      // (same source+expr regex error firing N times per playbook would
-      // otherwise spam runtime_errors). The original `_regex_eval_error`
-      // payload is preserved for backward compatibility.
+      // The `kind` tag is what lets pushRunError cap and dedupe: one bad regex
+      // otherwise fires once per evaluated element.
       const taggedErr = { kind: 'regex_eval_error', ..._regexErrorPayload(errorRec) };
       const target = (ctx && Array.isArray(ctx._runErrors)) ? ctx._runErrors
         : (playbook && Array.isArray(playbook._runErrors)) ? playbook._runErrors
@@ -4552,11 +3259,9 @@ function evalCondition(expr, ctx, playbook) {
     }
   }
 
-  // A condition the mini-language can't parse is a DEAD condition — it returns
-  // false for every input, silently disabling whatever escalation / feeds_into
-  // chain / precondition it gates. Surface it as a runtime_error so a dead
-  // condition is observable instead of an invisible `false` (this is how an
-  // authoring typo or an unimplemented operator gets caught at runtime).
+  // An unparseable condition is a DEAD condition: false for every input,
+  // silently disabling what it gates. The runtime_error is how an authoring
+  // typo or an unimplemented operator gets caught at all.
   if (process.env.EXCEPTD_DEBUG) console.warn(`[runner] unknown condition: ${expr}`);
   {
     const target = (ctx && Array.isArray(ctx._runErrors)) ? ctx._runErrors
@@ -4574,15 +3279,9 @@ function resolvePath(obj, dot) {
   return dot.split('.').reduce((acc, k) => acc == null ? null : acc[k], obj);
 }
 
-/**
- * Normalize a duration operand to canonical hours for a numeric comparison.
- * Accepts a unit-suffixed literal (`24h`, `7d`, `2wk`, `30min`) and converts by
- * its unit family, OR a bare number / numeric string (returned as its own
- * magnitude — the catalog writes `reboot_window > 24h` where the LHS resolves to
- * a bare hour count). Returns null for anything that is not a recognized
- * duration or plain number, so the caller can detect that BOTH sides normalized
- * before comparing numerically (and surface a type-mismatch otherwise).
- */
+// Normalize a duration operand to hours: a unit-suffixed literal by its unit, a
+// bare number as its own magnitude. Null for anything else, so the caller can
+// require BOTH sides to normalize before comparing.
 const DURATION_UNIT_HOURS = {
   h: 1, hr: 1, hrs: 1,
   m: 1 / 60, min: 1 / 60,
@@ -4593,7 +3292,6 @@ function parseDurationHours(v) {
   if (typeof v === 'number') return Number.isFinite(v) ? v : null;
   if (typeof v !== 'string') return null;
   const s = v.trim();
-  // Bare numeric string (no unit) — take its magnitude as-is.
   if (/^-?\d+(?:\.\d+)?$/.test(s)) return parseFloat(s);
   const m = s.match(/^(\d+(?:\.\d+)?)\s*(h|hr|hrs|d|day|days|wk|w|m|min)$/i);
   if (!m) return null;
@@ -4601,26 +3299,17 @@ function parseDurationHours(v) {
   return mult === undefined ? null : parseFloat(m[1]) * mult;
 }
 
-/**
- * Depth-aware splitter — split `expr` at occurrences of ` <sep> ` (with
- * surrounding spaces) that are at parenthesis depth 0. Returns the (trimmed)
- * sub-expression list. Used by evalCondition so `A OR (B AND C)` splits into
- * [`A`, `(B AND C)`] on OR, instead of naively splitting at the inner AND.
- */
+// Split `expr` at each ` <sep> ` sitting at parenthesis depth 0, so
+// `A OR (B AND C)` splits into [`A`, `(B AND C)`] rather than at the inner AND.
 function splitAtTopLevel(expr, sep) {
   const parts = [];
   const needle = ' ' + sep + ' ';
   let depth = 0, buf = '', i = 0, quote = null;
   while (i < expr.length) {
     const ch = expr[i];
-    // Inside a quoted string literal, parens and the ` AND `/` OR ` needle are
-    // LITERAL text, not boolean structure. A regex member like `matches 'foo('`
-    // carries an unbalanced `(` that — counted blindly — would leave depth=1 so
-    // a real top-level OR/AND would never split at depth 0 (silently disabling
-    // the disjunct/conjunct), and a member like `contains 'EU AND US'` would be
-    // torn at the inner ` AND ` as if it were an operator. Track quote state and
-    // skip both while inside a quote. An unescaped matching quote closes the
-    // literal; `\'`/`\"` stay in. Mirrors splitInMembers' quote-aware walk.
+    // Inside a quoted literal, parens and the needle are text, not structure:
+    // `matches 'foo('` counted blindly leaves depth 1 so no later top-level
+    // OR/AND ever splits, and `contains 'EU AND US'` is torn at its inner ` AND `.
     if (quote) {
       if (ch === '\\' && i + 1 < expr.length) { buf += ch + expr[i + 1]; i += 2; continue; }
       if (ch === quote) quote = null;
@@ -4642,16 +3331,9 @@ function splitAtTopLevel(expr, sep) {
   return parts;
 }
 
-/**
- * Quote-aware splitter for the body of an `IN [...]` member list. Splits on
- * commas that are OUTSIDE any quoted run, then strips the surrounding quotes and
- * trims each member. A naive `.split(',')` is quote-unaware, so a quoted member
- * that contains a comma (`'EU, US'`) would be torn into two members; this walks
- * the string tracking single/double quote state so a comma inside a quoted run
- * is treated as a literal part of that member. Bare (unquoted) members are
- * supported too — the catalog authors both forms (`'ai-c2', 'prompt-injection'`
- * and bare `kernel-lpe`). Empty members (e.g. a trailing comma) are dropped.
- */
+// Split an `IN [...]` member list on commas outside any quoted run, stripping
+// the quotes; a comma inside a quoted member (`'EU, US'`) belongs to it. Bare
+// and quoted members both parse, and empty members are dropped.
 function splitInMembers(listStr) {
   const out = [];
   let buf = '';
@@ -4671,20 +3353,10 @@ function splitInMembers(listStr) {
   return out.filter((s) => s.length);
 }
 
-/**
- * Locate the closing `]` of an `IN [...]` list quote-aware and return the body
- * between the (already-consumed) `[` and that `]`. `rest` is the text after the
- * opening bracket. The terminator is the first `]` encountered at quote-depth 0;
- * a `]` inside a single/double-quoted member (`'a]b'`) is part of the member, not
- * the terminator. A `[^\]]*` regex capture instead stops at the FIRST `]`, so a
- * quoted `]` truncated the list and left trailing text the `$` anchor rejected —
- * the clause then fell through to condition_unparsed for every input.
- *
- * Returns the body string on success, or `null` when the list is malformed:
- * unterminated (no quote-depth-0 `]`) or carrying non-whitespace text after the
- * closing bracket. `null` lets the caller fall through to the condition_unparsed
- * diagnostic so a malformed clause stays observable rather than passing silently.
- */
+// The body of an `IN [...]` list, given the text after the opening bracket. The
+// terminator is the first `]` at quote-depth 0; one inside a quoted member
+// (`'a]b'`) belongs to the member. Null when the list is unterminated or carries
+// trailing text, so the caller falls through to condition_unparsed.
 function sliceInBracketBody(rest) {
   let quote = null;
   for (let i = 0; i < rest.length; i++) {
@@ -4692,25 +3364,18 @@ function sliceInBracketBody(rest) {
     if (quote) { if (ch === quote) quote = null; continue; }
     if (ch === "'" || ch === '"') { quote = ch; continue; }
     if (ch === ']') {
-      // The bracket must be the final structural token: only whitespace may
-      // follow. Anything else (e.g. `IN ['a'] AND …` reaching here, or stray
-      // trailing text) is malformed for this leaf parser.
+      // Only whitespace may follow: the bracket is the final structural token
+      // for this leaf parser.
       return rest.slice(i + 1).trim() === '' ? rest.slice(0, i) : null;
     }
   }
-  return null; // no quote-depth-0 closing bracket → unterminated list
+  return null; // unterminated list
 }
 
-/**
- * Strip a balanced pair of outer parens, if and only if the very first and last
- * characters are matching parens at the same depth boundary. `(A) AND (B)` keeps
- * its parens; `((A AND B))` peels one layer. The depth scan is quote-aware: a
- * paren inside a quoted string literal (e.g. a regex member `matches '(a|b)'` or
- * an unbalanced `matches 'foo('`) is literal text, not grouping structure, so it
- * must not move the depth counter — otherwise a quoted `)` could make the outer
- * pair look unbalanced (skipping a legitimate strip) or an unbalanced quoted `(`
- * could make a non-wrapping pair look outer-spanning (stripping wrongly).
- */
+// Peel one balanced pair of outer parens, only when the first and last
+// characters match at the same depth boundary: `((A AND B))` loses a layer,
+// `(A) AND (B)` keeps both. The depth scan skips quoted literals — counting a
+// paren in `matches '(a|b)'` misreads which pair, if any, is the outer one.
 function stripOuterParens(expr) {
   while (expr.length >= 2 && expr[0] === '(' && expr[expr.length - 1] === ')') {
     let depth = 0;
@@ -4734,28 +3399,12 @@ function stripOuterParens(expr) {
   return expr;
 }
 
-// Parse an operator-supplied clock_started_at_<event> timestamp into a valid
-// Date, host-timezone-independently. Two failure modes a raw `new Date(s)`
-// silently produces are guarded here:
-//
-//   1. Unparseable value ('not-a-date', '2026-13-99'). new Date() returns an
-//      Invalid Date — a truthy object whose getTime() is NaN. Calling
-//      .toISOString() on it later throws RangeError, which crashes the
-//      deadline math in close() and propagates uncaught out of run(),
-//      destroying the entire phase-7 notification/CSAF/deadline output. We
-//      return { date: null } so the caller routes to the pending-clock branch
-//      instead of crashing.
-//
-//   2. Zone-less ISO ('2026-06-12T10:00:00' or '2026-06-12 10:00:00'). new
-//      Date() interprets a designator-less datetime in the HOST timezone, so
-//      the published statutory deadline shifts by the host's UTC offset — a
-//      4h DORA window computed on a UTC-7 host lands 7h late. We normalize the
-//      space separator to 'T' and append 'Z' so a zone-less value is read as
-//      UTC deterministically on every host, and flag assumed_utc so the caller
-//      can surface that the zone was assumed.
-//
-// Returns { date, assumed_utc } where date is a valid Date or null, and
-// assumed_utc is true only when a zone-less value was coerced to UTC.
+// Parse a clock_started_at_<event> timestamp host-timezone-independently,
+// returning { date, assumed_utc } with a null date on rejection. A bare
+// `new Date(s)` fails twice here: an unparseable value yields an Invalid Date
+// whose .toISOString() throws later, crashing the deadline math in close(); and
+// a zone-less ISO value is read in the HOST timezone, shifting a statutory
+// deadline by the host's UTC offset. Such a value is coerced to UTC.
 function parseOperatorClock(raw) {
   if (typeof raw !== 'string') {
     const d = new Date(raw);
@@ -4763,10 +3412,8 @@ function parseOperatorClock(raw) {
   }
   const trimmed = raw.trim();
   if (!trimmed) return { date: null, assumed_utc: false };
-  // A full ISO datetime whose only missing piece is the zone designator:
-  // YYYY-MM-DD, a 'T' or single space separator, HH:MM(:SS(.ms)?)?, and NO
-  // trailing 'Z' / [+-]HH:MM offset. Date-only values (YYYY-MM-DD) are already
-  // parsed as UTC midnight by spec, so they are left untouched.
+  // A full ISO datetime missing only its zone designator. A date-only value is
+  // already parsed as UTC midnight by spec and is left alone.
   let assumedUtc = false;
   let candidate = trimmed;
   const zonelessDateTime = /^\d{4}-\d{2}-\d{2}[ T]\d{2}:\d{2}(:\d{2}(\.\d+)?)?$/;
@@ -4779,45 +3426,17 @@ function parseOperatorClock(raw) {
   return { date: d, assumed_utc: assumedUtc };
 }
 
-/**
- * Compute the start instant for a jurisdictional clock event. The agent
- * submits clock_started_at_<event> ISO strings as it progresses through
- * incident-response milestones.
- *
- * Per AGENTS.md Phase 7, the legal contract is that the clock starts
- * from OPERATOR AWARENESS — not from the moment the engine emits a
- * `detected` classification. Auto-stamping Date.now() on detect_confirmed
- * whenever the engine classifies as detected would be incorrect: the
- * operator may not have seen the result yet. Semantics:
- *
- *   - If the agent explicitly submits clock_started_at_<event>: use it,
- *     after validating it parses and normalizing a zone-less value to UTC.
- *     An unparseable value returns null (clock stays pending) and surfaces
- *     a runtime error naming the offending key, instead of crashing close().
- *   - Otherwise, for 'detect_confirmed' with classification='detected', and
- *     for 'analyze_complete' / 'validate_complete' once their phase has run:
- *     stamp `now` ONLY if runOpts.operator_consent?.explicit === true
- *     (i.e. the operator passed --ack). The analyze/validate phases provably
- *     complete inside the same synchronous run before close() computes these
- *     clocks, so under --ack there is no operator-awareness gap. Without
- *     --ack, return null and the caller (close()) surfaces clock_pending_ack:
- *     true on the notification_actions entry so the operator sees that the
- *     clock is waiting on acknowledgement.
- *   - 'manual' and any other event without an explicit timestamp: return null.
- *
- * `phaseFlags` carries which engine phases completed in this run
- * ({ analyze_complete, validate_complete }) so the auto-stamp for those two
- * events only fires when the named phase actually ran.
- */
+// The start instant for a jurisdictional clock event. The legal contract is that
+// the clock starts from OPERATOR AWARENESS, not from the moment the engine emits
+// a `detected` classification. An explicitly submitted clock_started_at_<event>
+// wins. detect_confirmed on a detected classification, and analyze_complete /
+// validate_complete once phaseFlags says their phase ran, auto-stamp `now` ONLY
+// under runOpts.operator_consent.explicit (--ack). Everything else is null.
 function computeClockStart(eventName, agentSignals, runOpts = {}, engineClassification = null, phaseFlags = {}, frozenEpoch = null) {
-  // The agent submits clock_started_at_<event> ISO strings as it progresses.
   const key = `clock_started_at_${eventName}`;
   if (agentSignals && agentSignals[key]) {
     const { date, assumed_utc } = parseOperatorClock(agentSignals[key]);
     if (!date) {
-      // A present-but-unparseable timestamp must not crash the close phase via
-      // a downstream new Date(NaN).toISOString(). Null routes to the pending
-      // branch; the runtime error tells the operator which field was bad.
       if (runOpts && Array.isArray(runOpts._runErrors)) {
         pushRunError(runOpts._runErrors, {
           kind: 'invalid_clock_value',
@@ -4840,26 +3459,15 @@ function computeClockStart(eventName, agentSignals, runOpts = {}, engineClassifi
     }
     return date;
   }
-  // Auto-stamp gate. Detection is "confirmed" when EITHER the agent submitted
-  // detection_classification:'detected' OR the engine itself classified the
-  // detect phase as 'detected'. Pre-fix only the agent-submitted signal was
-  // honored, so an engine-confirmed detection (indicators fired from
-  // signal_overrides without a separate classification submission) never
-  // started the regulatory clock — notification deadlines silently stalled.
+  // Confirmed from EITHER a submitted detection_classification or the engine's
+  // own verdict: indicators fired through signal_overrides carry no separate
+  // classification, and their regulatory clock would stall silently.
   const detected = agentSignals?.detection_classification === 'detected'
     || engineClassification === 'detected';
   const ack = !!(runOpts && runOpts.operator_consent && runOpts.operator_consent.explicit === true);
   if (!ack) return null;
-  // detect_confirmed auto-starts on a confirmed detection. analyze_complete /
-  // validate_complete auto-start once their engine phase has run in this same
-  // pass — the event literally names a phase that completed synchronously
-  // before close(), so --ack closes the awareness gap exactly as it does for
-  // detect_confirmed.
-  // Deterministic bundle mode roots every auto-started clock in the single
-  // frozen epoch so two runs over the same evidence emit identical
-  // clock_started_at and deadline values; otherwise the clock starts at
-  // wall-clock now. Operator-supplied clock timestamps (handled above) are
-  // never overridden — they are the explicit input.
+  // Deterministic mode roots every auto-started clock in the frozen epoch, so
+  // two runs over the same evidence agree.
   const autoNow = () => (frozenEpoch ? new Date(frozenEpoch) : new Date());
   if (eventName === 'detect_confirmed' && detected) return autoNow();
   if (eventName === 'analyze_complete' && phaseFlags && phaseFlags.analyze_complete === true) return autoNow();
@@ -4867,24 +3475,17 @@ function computeClockStart(eventName, agentSignals, runOpts = {}, engineClassifi
   return null;
 }
 
+// The agentSignals lookup key for a precondition expression: the leading path
+// token, hyphens included, since a hyphenated id is the catalog norm.
 function expressionKey(expr) {
-  // For agentSignals precondition lookups — strip operators/values to leave key.
-  // Admits hyphens so a hyphenated precondition id (the catalog norm) resolves
-  // to the full key instead of being truncated at the first hyphen.
   const m = expr.match(/^([A-Za-z_][\w-]*(?:\.[A-Za-z_][\w-]*)*)/);
   return m ? m[1] : expr;
 }
 
-/**
- * Substitute ${var} placeholders against ctx. F14: pre-fix, missing keys
- * silently re-emitted the literal `${var}` placeholder, so notification
- * drafts could ship to regulators with `${cisa_kev_due_date}` rendered as
- * the raw template — a visible failure that operators wouldn't catch
- * before sending. Now: render as `<MISSING:${var}>` so the failure mode
- * is loud, AND if a tracker array is passed as the third argument,
- * collect the missing keys for caller surfacing as
- * missing_interpolation_vars[].
- */
+// Substitute ${var} placeholders against ctx. An unresolved key renders as
+// `<MISSING:key>`, never the literal `${key}` — a notification draft otherwise
+// reaches a regulator with a raw template in it. missingTracker, when an array,
+// collects the keys for missing_interpolation_vars[].
 function interpolate(tpl, ctx, missingTracker) {
   if (!tpl || typeof tpl !== 'string') return tpl;
   return tpl.replace(/\$\{(\w+)\}/g, (_, key) => {
@@ -4897,8 +3498,7 @@ function interpolate(tpl, ctx, missingTracker) {
   });
 }
 
-// --- pre-run discovery API: list all directives across all playbooks ---
-
+// Pre-run discovery: every directive across every playbook.
 function plan(opts = {}) {
   const ids = opts.playbookIds || listPlaybooks();
   return {
@@ -4919,8 +3519,7 @@ function plan(opts = {}) {
         directives: pb.directives.map(d => {
           const overrideDirect = d.phase_overrides?.direct || {};
           const threatContext = overrideDirect.threat_context || baseDirect.threat_context || null;
-          // Bug #46: include description by default (not just under --directives).
-          // Operators picking a directive need operator-facing prose.
+          // An operator picking a directive needs operator-facing prose.
           const desc = d.description
             || (threatContext ? (threatContext.split(/(?<=[.!?])\s+/)[0] || "").slice(0, 240) : null)
             || pb.domain?.name
@@ -4948,9 +3547,8 @@ module.exports = {
   vexFilterFromDoc,
   normalizeSubmission,
   autoDetectPreconditions,
-  // Exported so library-side direct callers (the fallback path the CLI
-  // guard cannot reach) can be exercised without spawning a CLI
-  // subprocess.
+  // Exported so the library-side path the CLI guard cannot reach is testable
+  // without spawning a subprocess.
   sanitizeOperatorText,
   // internal helpers exposed for tests
   _resolvedPhase: resolvedPhase,
@@ -4967,7 +3565,7 @@ module.exports = {
   _advisoryAuthorityFor: advisoryAuthorityFor,
   _computeClockStart: computeClockStart,
   _worstActiveExploitation: worstActiveExploitation,
-  // Re-exported from scoring so parity between the catalog scorer and the
-  // runtime evaluator is checkable (and enforced by a test) at the seam.
+  // Re-exported from scoring so a test can enforce parity between the catalog
+  // scorer and the runtime evaluator at the seam.
   _activeExploitationLadder: scoring.ACTIVE_EXPLOITATION_LADDER,
 };