@blamejs/exceptd-skills 0.12.22 → 0.12.23

package/lib/playbook-runner.js

@@ -48,7 +48,7 @@ const path = require('path');
 const os = require('os');
 const crypto = require('crypto');
 
-// F7: cross-ref-api wraps catalog reads. If cve-catalog.json is corrupt
+// 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
@@ -104,7 +104,7 @@ function loadPlaybook(playbookId) {
   return JSON.parse(fs.readFileSync(p, 'utf8'));
 }
 
-// E12: per-run playbook cache. Each phase function reads runOpts._playbookCache
+// 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.
 
@@ -149,16 +149,17 @@ function deepMerge(a, b) {
  *   3. Mutex. _meta.mutex[] intersect with the in-process active runs set
  *      AND with the filesystem lockfile dir blocks the run.
  *
- * E5: when runOpts.strictPreconditions === true, warn-level outcomes
+ * 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
+ * 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.
  *
- * E6: when a precondition with on_fail='skip_phase' fails, the issue carries
+ * 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.
+ * placeholder rather than executing detect against a missing
+ * prerequisite.
  */
 function preflight(playbook, runOpts = {}) {
   const issues = [];
@@ -185,7 +186,7 @@ function preflight(playbook, runOpts = {}) {
     if (submitted === undefined) {
       const submission_hint = `Submit precondition_checks in your evidence JSON, e.g. { "precondition_checks": { "${pc.id}": true } }. The runner lifts this into runOpts before the gate evaluates.`;
       if (strict) {
-        // E5: strictPreconditions promotes unverified to halt regardless of
+        // 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 {
@@ -213,7 +214,7 @@ function preflight(playbook, runOpts = {}) {
         return { ok: false, blocked_by: 'precondition', reason: `Precondition ${pc.id} failed: ${pc.description}`, issues };
       }
       if (strict) {
-        // E5: warn-level + skip_phase outcomes escalate to halt under 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,
@@ -223,7 +224,7 @@ function preflight(playbook, runOpts = {}) {
         };
       }
       if (pc.on_fail === 'skip_phase') {
-        // E6: emit a skip_phase field so run() can route to a skipped-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.
@@ -266,11 +267,11 @@ function preflight(playbook, runOpts = {}) {
   return { ok: true, issues };
 }
 
-// F28: lockDir lives at a stable global path so two CLI invocations from
+// lockDir lives at a stable global path so two CLI invocations from
 // different working directories still share lock state for cross-process
-// mutex enforcement. Pre-fix this used process.cwd(), which meant invoking
-// the same playbook from /tmp and from /home/user/project simultaneously
-// would each see an empty locks dir and both run unchallenged. The path
+// 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. 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). Override via EXCEPTD_LOCK_DIR for
@@ -287,13 +288,14 @@ function lockFilePath(playbookId) {
   catch { return null; }
 }
 
-// PP P1-1: same-PID stale-lockfile reclaim threshold. A same-process orphan
-// (e.g. an earlier run() that crashed without unlinking, or a try/catch that
+// 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.
+// 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.
 const STALE_LOCK_MS = 30_000;
 
 function acquireLock(playbookId) {
@@ -308,16 +310,14 @@ function acquireLock(playbookId) {
     writePayload();
     return p;
   } catch (e) {
-    // DD P1-3: stale-PID reclaim. Pre-fix the EEXIST path returned null
-    // and callers proceeded UNLOCKED — a process that crashed mid-run
-    // left its lockfile behind and every subsequent invocation silently
-    // ran without mutex protection. 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 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).
     if (e && (e.code === 'EEXIST' || e.code === 'EPERM')) {
       try {
         const raw = fs.readFileSync(p, 'utf8');
@@ -331,13 +331,13 @@ function acquireLock(playbookId) {
           try { fs.unlinkSync(p); } catch {}
           try { writePayload(); return p; } catch { /* fall through */ }
         }
-        // PP P1-1: 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)
+        // 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.
         if (Number.isInteger(pid) && pid === process.pid) {
@@ -359,9 +359,9 @@ function acquireLock(playbookId) {
   }
 }
 
-// DD P1-3: 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.
+// 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.
 function acquireLockDiagnostic(playbookId) {
@@ -394,10 +394,10 @@ function acquireLockDiagnostic(playbookId) {
           return { ok: false, reason: 'reclaim_failed', error: e2.message, lock_path: p, holder_pid: pid };
         }
       }
-      // PP P1-1: same-PID stale-lockfile reclaim (diagnostic variant). Same
+      // 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.
+      // STALE_LOCK_MS is an orphan and must be reclaimed; a fresher one
+      // is legitimate reentrancy and stays held.
       if (Number.isInteger(pid) && pid === process.pid) {
         let mtimeMs = null;
         try { mtimeMs = fs.statSync(p).mtimeMs; } catch {}
@@ -441,7 +441,7 @@ function pidAlive(pid) {
 function govern(playbookId, directiveId, runOpts = {}) {
   const playbook = runOpts._playbookCache || loadPlaybook(playbookId);
   const g = resolvedPhase(playbook, directiveId, 'govern');
-  // F12: sort jurisdiction obligations by window_hours ascending so the
+  // 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.
@@ -557,7 +557,7 @@ function detect(playbookId, directiveId, agentSubmission = {}, runOpts = {}) {
     return null; // truly unknown — fall through
   };
 
-  // E1: per-indicator FP-check attestation map. Operators submit
+  // 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
@@ -572,12 +572,12 @@ function detect(playbookId, directiveId, agentSubmission = {}, runOpts = {}) {
     let fpChecksUnsatisfied = null;
     if (override === 'hit' || override === 'miss' || override === 'inconclusive') {
       verdict = override;
-      // E1: gate 'hit' verdict on per-indicator false_positive_checks_required
+      // 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.
       if (verdict === 'hit' && Array.isArray(ind.false_positive_checks_required) && ind.false_positive_checks_required.length) {
-        // BB P2-4: a hostile or buggy attestation may be a Proxy whose property
+        // 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
@@ -586,13 +586,14 @@ function detect(playbookId, directiveId, agentSubmission = {}, runOpts = {}) {
         // read) and surface a runtime_error so the operator sees why.
         try {
           const attestation = overrides[`${ind.id}__fp_checks`];
-          // S P1-A: arrays satisfy `typeof === 'object'` but are NOT a valid
+          // Arrays satisfy `typeof === 'object'` but are NOT a valid
           // attestation map. A submission like
           //   signal_overrides: { sig__fp_checks: [true, true] }
-          // would previously have its truthy entries matched via the index
+          // 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).
+          // requirement. Reject arrays explicitly so they fall through to
+          // the empty-attestation branch (every required check
+          // unsatisfied).
           const safeAtt = Array.isArray(attestation) ? null : attestation;
           const att = (safeAtt && typeof safeAtt === 'object') ? safeAtt : {};
           const unsatisfied = ind.false_positive_checks_required.filter(fpName => {
@@ -632,9 +633,9 @@ function detect(playbookId, directiveId, agentSubmission = {}, runOpts = {}) {
       // 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.
-      // E2: pre-fix both arms emitted 'inconclusive', so a clean empty run
-      // could never reach not_detected and theater_verdict stayed
-      // 'pending_agent_run' forever.
+      // A clean empty run with no captured artifacts must emit 'miss' so
+      // classification can reach 'not_detected'; otherwise theater_verdict
+      // stays 'pending_agent_run' indefinitely.
       const anyCaptured = Object.values(artifacts).some(a => a && a.captured);
       verdict = anyCaptured ? 'inconclusive' : 'miss';
     }
@@ -664,9 +665,9 @@ function detect(playbookId, directiveId, agentSubmission = {}, runOpts = {}) {
   // confirmed they're all benign" without this override.
   const rawOverride = (agentSubmission.signals && agentSubmission.signals.detection_classification);
   const validOverrides = new Set(['detected', 'inconclusive', 'not_detected', 'clean']);
-  // BB P2-1: any override that's a non-empty string but NOT in the allowlist
-  // (e.g. 'present', 'unknown', '', '  detected  ', 'Detected') must surface
-  // as a runtime_error rather than silently falling through to engine-computed
+  // 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.
@@ -684,17 +685,17 @@ function detect(playbookId, directiveId, agentSubmission = {}, runOpts = {}) {
   }
   const override = overrideIsInAllowlist ? rawOverride : undefined;
 
-  // BB P1-1 / BB P1-2: extend the v0.12.19 S P1-B gate to refuse ALL
-  // classification overrides (`detected`, `clean`, `not_detected`) when any
-  // indicator was FP-downgraded. A submission that maps to `'not_detected'`
-  // (either by literal `not_detected` OR by `'clean'`, which v0.12.19 mapped
-  // 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.
-  // BB P2-2: 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).
+  // 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).
   const anyFpDowngrade = indicatorResults.some(r => Array.isArray(r.fp_checks_unsatisfied) && r.fp_checks_unsatisfied.length > 0);
 
   let classification;
@@ -753,7 +754,7 @@ function detect(playbookId, directiveId, agentSubmission = {}, runOpts = {}) {
     indicators_evaluated_count: indicatorResults.length,
     classification_override_applied: override ? (override === 'clean' ? 'not_detected' : override) : null,
     submission_shape_seen: agentSubmission._original_shape || (agentSubmission.artifacts ? 'nested (v0.10.x)' : 'empty'),
-    // E9: pass through any flat-shape observation collisions detected at
+    // Pass through any flat-shape observation collisions detected at
     // normalize time so analyze() can publish them under
     // analyze.signal_origins_with_collisions.
     _signal_origins_collisions: Array.isArray(agentSubmission._signal_origins_collisions) ? agentSubmission._signal_origins_collisions.slice() : []
@@ -813,14 +814,14 @@ function analyze(playbookId, directiveId, detectResult, agentSignals = {}, runOp
   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);
-  // F17: distinguish OpenVEX/CycloneDX "drop entirely" dispositions
+  // 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).
   const vexFixed = agentSignals.vex_fixed instanceof Set ? agentSignals.vex_fixed
     : (Array.isArray(agentSignals.vex_fixed) ? new Set(agentSignals.vex_fixed) : null);
-  // F20: wrap xref.byCve() so a corrupt catalog (or transient missing-index
+  // Wrap xref.byCve() so a corrupt catalog (or transient missing-index
   // anomaly) surfaces as a runtime_error rather than crashing analyze().
   const _byCveSafe = (id) => {
     try { return xref.byCve(id); }
@@ -838,7 +839,7 @@ function analyze(playbookId, directiveId, detectResult, agentSignals = {}, runOp
   const vexDropped = vexFilter
     ? allCves.filter(c => vexFilter.has(c.cve_id)).map(c => c.cve_id)
     : [];
-  // F17: VEX-fixed CVEs remain in matched/catalog arrays but get annotated
+  // VEX-fixed CVEs remain in matched/catalog arrays but get annotated
   // with vex_status:'fixed' downstream so consumers see them as resolved.
   const vexFixedIds = vexFixed
     ? allCves.filter(c => vexFixed.has(c.cve_id)).map(c => c.cve_id)
@@ -875,7 +876,7 @@ function analyze(playbookId, directiveId, detectResult, agentSignals = {}, runOp
     }
   }
 
-  // F3: indicator-level cve_ref correlation. Indicators may declare a
+  // 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=
@@ -914,7 +915,7 @@ function analyze(playbookId, directiveId, detectResult, agentSignals = {}, runOp
   // carry a non-null correlated_via array; catalog_baseline_cves entries
   // carry correlated_via:null and a `note` clarifying the field's intent.
   const cveShape = (c, correlatedVia) => {
-    // F17: annotate VEX-fixed CVEs with vex_status. matched_cves still
+    // 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."
     const vexStatus = (vexFixed && vexFixed.has(c.cve_id)) ? 'fixed' : null;
@@ -951,26 +952,26 @@ function analyze(playbookId, directiveId, detectResult, agentSignals = {}, runOp
 
   // 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. F18: the "max" reduction across matched CVEs
-  // is intentional — RWEP is a "worst-case real-world exploit priority", not
+  // 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).
-  // F17: 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.
+  // 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.
   const rwepEligible = matchedCves.filter(c => !(vexFixed && vexFixed.has(c.cve_id)));
   const baseRwep = rwepEligible.length ? Math.max(...rwepEligible.map(c => c.rwep_score)) : 0;
 
-  // F5: rwep_factor semantics. Each rwep_input.weight is conditional on the
-  // matched CVE having a corresponding attribute. Pre-fix, every weight fired
-  // unconditionally when its signal_id indicator hit — operators saw RWEP +25
-  // for active_exploitation regardless of whether the matched CVE was actually
-  // under active exploitation. Now we multiply weight by a factor in [0, 1]
-  // derived from the first matched CVE's catalog attribute. 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
+  // 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
@@ -1018,12 +1019,12 @@ function analyze(playbookId, directiveId, detectResult, agentSignals = {}, runOp
     }
   };
 
-  // F6: blast_radius_score validation. Pre-fix, when no agent signal was
-  // supplied the runner silently defaulted to blast_rubric[0].blast_radius_score
-  // — typically the LOWEST-blast rubric entry — which is the opposite of
-  // safe-default. Now: 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'.
+  // 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.
   const blastRubric = an.blast_radius_model?.scoring_rubric || [];
   let blastRadiusScore = null;
   let blastRadiusSignal = 'default';
@@ -1040,7 +1041,7 @@ function analyze(playbookId, directiveId, detectResult, agentSignals = {}, runOp
       }
     }
   }
-  // F5: use the first evidence-correlated CVE as the canonical attribute
+  // 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
@@ -1133,11 +1134,10 @@ function analyze(playbookId, directiveId, detectResult, agentSignals = {}, runOp
   //   detect.classification = inconclusive → theater_verdict = pending_agent_run
   // Aliases 'clean' / 'no_theater' map to 'clear' for ergonomics.
   //
-  // F24: validate against an allowlist. Pre-fix, any free-text string the
-  // operator passed through agentSignals.theater_verdict was accepted, so
-  // downstream consumers (CSAF/SARIF/OpenVEX) emitted bundles with garbage
-  // verdicts like "TODO" or "let me think". Allowlist: clear, present,
-  // theater, pending_agent_run, unknown.
+  // 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.
   const _theaterAllowlist = new Set(['clear', 'present', 'theater', 'pending_agent_run', 'unknown']);
   let theaterVerdict = agentSignals.theater_verdict;
   if (theaterVerdict === 'clean' || theaterVerdict === 'no_theater') theaterVerdict = 'clear';
@@ -1193,12 +1193,12 @@ function analyze(playbookId, directiveId, detectResult, agentSignals = {}, runOp
     // matched_cves when surfacing "what CVEs is the operator actually
     // affected by based on submitted evidence?"
     catalog_baseline_cves: catalogBaselineEntries,
-    // F18: rwep base is reduced via Math.max across matched CVEs. Surface
-    // the reduction strategy as a discoverable field so operators reading the
+    // 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,
-    // F6: visible annotation of where blast_radius_score came from:
+    // 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.
@@ -1209,7 +1209,7 @@ 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,
-      // F25: render verdict_text for both 'theater' AND 'present' verdicts
+      // Render verdict_text for both 'theater' AND 'present' verdicts
       // ('present' is a synonym used by some playbooks for "theater is here").
       verdict_text: (theaterVerdict === 'theater' || theaterVerdict === 'present')
         ? an.compliance_theater_check?.theater_verdict_if_gap
@@ -1231,14 +1231,14 @@ function analyze(playbookId, directiveId, detectResult, agentSignals = {}, runOp
         ? `${vexDropped.length} CVE(s) dropped from analyze because the operator-supplied VEX statement marks them not_affected / resolved / false_positive. They 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 set)."
     } : null,
-    // E3: regex-eval failures surfaced here so operators can see WHICH
+    // 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.
     runtime_errors: (runOpts._runErrors && runOpts._runErrors.length) ? runOpts._runErrors.slice() : (runtimeErrors.length ? runtimeErrors.slice() : []),
-    // E9: collisions when two flat-shape observations targeted the same
+    // Collisions when two flat-shape observations targeted the same
     // indicator id. Empty when there were no collisions or no flat-shape
     // observations submitted.
     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() : [])
@@ -1248,8 +1248,8 @@ function analyze(playbookId, directiveId, detectResult, agentSignals = {}, runOp
 /**
  * Extract VEX disposition sets from a CycloneDX/OpenVEX document.
  *
- * F17: pre-fix this conflated OpenVEX `fixed` and `not_affected` into one
- * "drop" set. They have different semantics:
+ * 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
@@ -1298,7 +1298,7 @@ function vexFilterFromDoc(doc) {
 
 function validate(playbookId, directiveId, analyzeResult, agentSignals = {}, runOpts = {}) {
   const playbook = runOpts._playbookCache || loadPlaybook(playbookId);
-  // E3: surface evalCondition regex errors raised here into the same
+  // Surface evalCondition regex errors raised here into the same
   // run-wide accumulator that analyze() reads.
   const evalCtx = runOpts._runErrors ? { ...agentSignals, _runErrors: runOpts._runErrors } : agentSignals;
   const v = resolvedPhase(playbook, directiveId, 'validate');
@@ -1322,7 +1322,7 @@ function validate(playbookId, directiveId, analyzeResult, agentSignals = {}, run
   // weren't verified — the agent can surface that to the operator.
   if (!selected && paths.length) selected = paths[0];
 
-  // F26: selected_remediation selection logic:
+  // 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
@@ -1335,18 +1335,17 @@ function validate(playbookId, directiveId, analyzeResult, agentSignals = {}, run
   // precondition trace so operators can see why a higher-priority path was
   // skipped.
 
-  // F10: regression schedule. Pre-fix this returned a single ISO string;
-  // now returns a structured object with next_run + event_triggers +
-  // unparseable. Preserve backwards compatibility by keeping
+  // 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.
   const triggers = v.regression_trigger || [];
   const regressionResult = computeRegressionNextRun(triggers);
 
-  // F30: 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).
+  // 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';
@@ -1377,15 +1376,15 @@ function validate(playbookId, directiveId, analyzeResult, agentSignals = {}, run
 }
 
 /**
- * F10: extended interval parser. Supports:
+ * 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.
- * Pre-fix, only Nd was honored; wk/mo/yr/on_event triggers were silently
- * dropped, so a playbook declaring "regression on every release" or
+ * Without all five forms, a playbook declaring "regression on every
+ * release" or
  * "monthly review" lost its schedule entry.
  */
 function parseInterval(intervalStr, now) {
@@ -1473,12 +1472,13 @@ function close(playbookId, directiveId, analyzeResult, validateResult, agentSign
     const obligation = (g.jurisdiction_obligations || []).find(o =>
       `${o.jurisdiction}/${o.regulation} ${o.window_hours}h` === na.obligation_ref
     );
-    // E7: thread runOpts through so computeClockStart can check
+    // Thread runOpts through so computeClockStart can check
     // operator_consent.explicit before auto-stamping detect_confirmed.
     const clockStart = obligation ? computeClockStart(obligation.clock_starts, agentSignals, runOpts) : null;
-    // E7: when the clock event is detect_confirmed AND the classification
-    // matched AND the operator did NOT pass --ack, surface clock_pending_ack
-    // so the notification record is visibly waiting on acknowledgement.
+    // When the clock event is detect_confirmed AND the classification
+    // matched AND the operator did NOT pass --ack, surface
+    // clock_pending_ack so the notification record is visibly waiting on
+    // acknowledgement.
     const clockPendingAck = !clockStart
       && obligation?.clock_starts === 'detect_confirmed'
       && agentSignals?.detection_classification === 'detected'
@@ -1504,13 +1504,13 @@ function close(playbookId, directiveId, analyzeResult, validateResult, agentSign
       // Evidence the regulator expects attached (from the obligation, not
       // just the operator-facing recipient bundle on the notification entry).
       evidence_required: obligation?.evidence_required || na.evidence_attached || [],
-      // F14: track missing interpolation variables so operators see exactly
+      // Track missing interpolation variables so operators see exactly
       // which template vars failed to resolve. Empty array when all
       // placeholders rendered cleanly.
       ...(function () {
         const missing = [];
-        // F20: analyzeFindingShape is a pure transform but defensive-wrap
-        // it so a malformed analyze result (missing matched_cves, etc.)
+        // 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.
         let findingShape;
@@ -1564,13 +1564,13 @@ function close(playbookId, directiveId, analyzeResult, validateResult, agentSign
   const extraFormats = Array.isArray(agentSignals._bundle_formats)
     ? agentSignals._bundle_formats.filter(f => f !== primaryFormat)
     : [];
-  // B: build every bundle once and reuse, so bundle_body and
-  // bundles_by_format[primary] are the same object identity (and hence
-  // identical on every nested timestamp). Pre-fix, buildEvidenceBundle was
-  // invoked twice for the primary format and each invocation crystallised
-  // a fresh Date.now() — operators diffing bundle_body against
-  // bundles_by_format.<primary> saw spurious millisecond drift on
-  // tracking.initial_release_date / timestamp / current_release_date.
+  // 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.
   const evidencePackage = c.evidence_package ? (() => {
     const issuedAt = new Date().toISOString();
     const builtFormats = new Map();
@@ -1639,8 +1639,8 @@ function close(playbookId, directiveId, analyzeResult, validateResult, agentSign
     validate: validateResult,
     finding: analyzeFindingShape(analyzeResult),
     ...agentSignals,
-    // E3: surface evalCondition regex failures from the feeds_into chain
-    // into the same accumulator. Without this the regex failure happens but
+    // 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.
     ...(runOpts._runErrors ? { _runErrors: runOpts._runErrors } : {})
   };
@@ -1665,7 +1665,7 @@ function close(playbookId, directiveId, analyzeResult, validateResult, agentSign
     exception: exception,
     regression_schedule: regressionSchedule,
     feeds_into: feeds,
-    // F21: feeds_into surfaces downstream playbook IDs whose preconditions
+    // 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
@@ -1674,7 +1674,7 @@ function close(playbookId, directiveId, analyzeResult, validateResult, agentSign
   };
 }
 
-// E8: severity ladder for active_exploitation. The worst-of reduction lets
+// 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.
 const ACTIVE_EXPLOITATION_RANK = { none: 0, unknown: 1, suspected: 2, confirmed: 3 };
@@ -1691,10 +1691,10 @@ function worstActiveExploitation(matchedCves) {
   return worst || 'unknown';
 }
 
-// F4: severity ladder derived from rwep_adjusted. Playbooks reference
-// `finding.severity` in feeds_into and escalation_criteria conditions but
-// pre-fix analyzeFindingShape never emitted it, so those conditions silently
-// resolved against undefined. Thresholds:
+// 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
@@ -1712,22 +1712,21 @@ function analyzeFindingShape(a) {
   const rwepAdjusted = a.rwep?.adjusted ?? 0;
   return {
     matched_cve_ids: matched.map(c => c.cve_id).join(', '),
-    // F19: 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.
+    // 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.
     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,
-    // E8: previously this used .find() which returned the first matched CVE
-    // with a truthy active_exploitation. With two CVEs where #1 is
-    // 'suspected' and #2 is 'confirmed', operators saw 'suspected' on
-    // notification drafts — under-stating the threat. Now reduce to the
-    // worst rank across all matched CVEs.
+    // 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.
     active_exploitation: worstActiveExploitation(matched),
     rwep_adjusted: rwepAdjusted,
     rwep_base: a.rwep?.base ?? 0,
-    // F4: severity surface for playbook conditions.
+    // 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,
@@ -1769,7 +1768,7 @@ function buildProductBinding(playbook, sessionId) {
 // surface at least one candidate when any is known. Returns null when no
 // candidate exists — caller MUST omit `locations` rather than emit empty.
 //
-// A: source segments are heterogeneous — many playbook artifacts
+// 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
@@ -1826,24 +1825,24 @@ function getEngineVersion() {
   return _CACHED_PKG_VERSION;
 }
 
-// 3 / P1-4: operator-supplied identity strings (--operator) and
-// publisher namespace URLs (--publisher-namespace) flow into operator-facing
-// CSAF surfaces. Strip ASCII control characters as a defence-in-depth pass —
-// bin/exceptd.js already validates the inputs, but the runner is also called
-// from library consumers that may bypass the CLI surface.
+// 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.
 //
-// MM P1-D: extend the strip to 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 (--operator validation in bin/exceptd.js). 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
+// 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).
 function sanitizeOperatorText(s) {
@@ -1871,12 +1870,12 @@ function buildEvidenceBundle(format, playbook, analyze, validate, agentSignals,
   runOpts = runOpts || {};
   const playbookSlug = urnSlug(playbook._meta.id);
   const { productId, productPurl, productName } = buildProductBinding(playbook, sessionId);
-  // B: pin one `now` value per bundle build (and accept an
+  // 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 crystallised a fresh `Date.now()` and bundle_body
-  // versus bundles_by_format[primary] would diverge on milliseconds.
+  // 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
@@ -1895,16 +1894,16 @@ function buildEvidenceBundle(format, playbook, analyze, validate, agentSignals,
       name: productName,
       product_identification_helper: { purl: productPurl }
     }];
-    // A: `fixed` product_status MUST reflect operator-supplied VEX
-    // disposition (vex_status === 'fixed' — see analyze() F17), 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". Pre-fix the CSAF emitter declared every
-    // live-patchable CVE as fixed regardless of whether the operator's
-    // evidence actually showed the patch applied, producing CSAF documents
-    // that lied 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 `vendor_fix` remediation.
+    // `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
+    // `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
@@ -1936,25 +1935,25 @@ function buildEvidenceBundle(format, playbook, analyze, validate, agentSignals,
       return m[1];
     };
     const csafIdsFor = (id) => {
-      // B: null / undefined / non-string id MUST NOT emit literal
-      // "null" / "undefined" text into the vulnerabilities[] entry. Pre-fix
-      // String(id) coerced both to those literals — strict validators then
-      // rejected the document, and operators saw a phantom "null" CVE in
-      // dashboards. Return null so the caller can skip the entry entirely
-      // and surface a runtime_error for the missing 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.
       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 };
-      // A: 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 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.
       if (id.startsWith('RUSTSEC-')) return { system_name: 'RUSTSEC', text: id };
-      // B: genuinely-unknown prefix surfaces as `exceptd-unknown`
-      // so downstream ingesters know the authority wasn't recognized — pre-fix
-      // every unknown id was misattributed to OSV.
+      // 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.
       return { system_name: 'exceptd-unknown', text: id };
     };
     const CSAF_CVE_RE = /^CVE-\d{4}-\d{4,}$/;
@@ -1967,10 +1966,11 @@ 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],
       }];
-      // B: catalog entries with a missing / non-string cve_id
-      // pre-fix produced 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.
+      // 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) {
@@ -1997,12 +1997,12 @@ function buildEvidenceBundle(format, playbook, analyze, validate, agentSignals,
       // an authoritative "informational" score where there was simply no
       // data.
       //
-      // C: CSAF 2.0 `cvss_v3` ONLY accepts version 3.0 / 3.1.
-      // Catalog vectors prefixed CVSS:2.0/ or CVSS:4.0/ would pre-fix 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.
+      // 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.
       const hasCvss = typeof c.cvss_score === 'number' && typeof c.cvss_vector === 'string' && c.cvss_vector.length > 0;
       const vectorVersion = hasCvss ? csafCvssVersionFromVector(c.cvss_vector) : null;
       const cvssV3Eligible = hasCvss && (vectorVersion === '3.0' || vectorVersion === '3.1');
@@ -2047,15 +2047,16 @@ function buildEvidenceBundle(format, playbook, analyze, validate, agentSignals,
       remediations: [{ category: 'mitigation', details: validate.selected_remediation?.description || `Consult playbook brief: exceptd brief ${playbook._meta.id}.`, product_ids: [productId] }],
       product_status: { known_affected: [productId] }
     }));
-    // D: framework-gap entries used to ride in `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) flagged every run for unknown ids and rendered
-    // false-positive advisories at the framework_gap_mapping length. Now
-    // framework gaps land in `document.notes[]` with `category: details`
-    // where they belong as advisory context, not pseudo-CVEs.
+    // 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.
     const gapNotes = (analyze.framework_gap_mapping || []).map((g, idx) => {
       const lines = [
         `Framework: ${g.framework}`,
@@ -2273,8 +2274,8 @@ function buildEvidenceBundle(format, playbook, analyze, validate, agentSignals,
         } },
         results: [...cveResults, ...indicatorResults, ...gapResults],
         invocations: [{ executionSuccessful: true, properties: stripNulls({
-          // A: apply the B7 stripNulls contract here too — the
-          // `remediation` field is null for any run that didn't surface a
+          // 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.
@@ -2302,11 +2303,11 @@ function buildEvidenceBundle(format, playbook, analyze, validate, agentSignals,
   //        `urn:exceptd:indicator:<playbook>:<indicator-id>` (RFC 8141) so
   //        they pass IRI validation in downstream VEX consumers.
   if (format === 'openvex' || format === 'openvex-0.2.0') {
-    // B: 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. Pre-fix each format
-    // crystallised its own Date.now() value, and the two bundles in
-    // bundles_by_format disagreed on milliseconds.
+    // 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,
@@ -2322,17 +2323,17 @@ function buildEvidenceBundle(format, playbook, analyze, validate, agentSignals,
       if (remediationDescription) return `Apply remediation from validate phase: ${remediationDescription}`;
       return fallback;
     };
-    // A: same `vex_status === 'fixed'` correctness rule as the
-    // CSAF emitter. The catalog `live_patch_available` flag is a global
+    // 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` made OpenVEX statements
-    // claim resolution that the operator hadn't actually 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. Now 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.
+    // 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.
     const cveStatements = analyze.matched_cves.map(c => {
       const stmt = {
         vulnerability: { '@id': `urn:cve:${urnSlug(c.cve_id)}`, name: c.cve_id },
@@ -2429,11 +2430,11 @@ function buildEvidenceBundle(format, playbook, analyze, validate, agentSignals,
     return { format: 'markdown', body: lines.join('\n') };
   }
 
-  // F16: pre-fix the fallback leaked 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 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.
   return {
     format,
     note: 'Unknown format',
@@ -2458,11 +2459,11 @@ function buildEvidenceBundle(format, playbook, analyze, validate, agentSignals,
 function normalizeSubmission(submission, playbook) {
   if (!submission || typeof submission !== "object") return submission || {};
 
-  // F15: signal_overrides must be a plain object. Pre-fix, a non-object
-  // value (string "foo", array [...]) was spread into out.signal_overrides
-  // via `{ ...(submission.signal_overrides || {}) }`. Spreading a string
-  // splatted it into { '0': 'f', '1': 'o', '2': 'o' }, which then
-  // confused detect()'s indicator-id lookup. Strip and log instead.
+  // 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.
   if (submission.signal_overrides !== undefined && submission.signal_overrides !== null
       && (typeof submission.signal_overrides !== 'object' || Array.isArray(submission.signal_overrides))) {
     if (!submission._runErrors) submission._runErrors = [];
@@ -2495,13 +2496,13 @@ function normalizeSubmission(submission, playbook) {
     signals: { ...(submission.signals || {}) },
     precondition_checks: { ...(submission.precondition_checks || {}) },
     _original_shape: 'flat (v0.11.0)',
-    // BB P1-4: normalizeSubmission pushes structured errors (e.g.
-    // signal_overrides_invalid) onto submission._runErrors above. If the
-    // submission is flat, 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 — without this carry,
-    // flat submissions with invalid signal_overrides silently lost the
-    // v0.12.19 U REG-1 contract (errors never reached analyze.runtime_errors).
+    // 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.
     ...(Array.isArray(submission._runErrors) && submission._runErrors.length
       ? { _runErrors: submission._runErrors.slice() }
       : {}),
@@ -2523,7 +2524,7 @@ function normalizeSubmission(submission, playbook) {
   // detect can emit `from_observation` on each indicator result. Diagnostic
   // value for operators chasing "which observation drove this verdict".
   //
-  // E9: when two observations target the same indicator id, last-write-wins
+  // 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.
   out._signal_origins = out._signal_origins || {};
@@ -2605,7 +2606,7 @@ function autoDetectPreconditions(submission, playbook) {
 }
 
 function run(playbookId, directiveId, agentSubmission = {}, runOpts = {}) {
-  // F7: catalog corruption surfaced at module-load now blocks runs cleanly.
+  // Catalog corruption surfaced at module-load blocks runs cleanly.
   if (_xrefLoadError) {
     return {
       ok: false,
@@ -2619,7 +2620,7 @@ function run(playbookId, directiveId, agentSubmission = {}, runOpts = {}) {
   try {
     playbook = loadPlaybook(playbookId);
   } catch (e) {
-    // F20: loadPlaybook failure → structured error (not crash).
+    // loadPlaybook failure → structured error (not crash).
     return {
       ok: false,
       blocked_by: 'playbook_not_found',
@@ -2628,9 +2629,10 @@ function run(playbookId, directiveId, agentSubmission = {}, runOpts = {}) {
     };
   }
 
-  // F8: validate directiveId before any phase runs. Unknown id used to throw
-  // inside analyze()/findDirective() uncaught, surfacing as a 500-style stack
-  // trace. Now returns a clean structured error with the valid directive list.
+  // 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.
   const validDirectives = (playbook.directives || []).map(d => d.id);
   if (!validDirectives.includes(directiveId)) {
     return {
@@ -2647,12 +2649,12 @@ function run(playbookId, directiveId, agentSubmission = {}, runOpts = {}) {
   // / the host platform matches — the runner can answer those itself rather
   // than blocking on AI declaration.
   agentSubmission = normalizeSubmission(agentSubmission, playbook);
-  // F22: capture pre-autoDetect submission preconditions so we report
+  // Capture pre-autoDetect submission preconditions so we report
   // user-declared provenance, not engine-auto-resolved values.
   const originalSubmissionPCs = { ...(agentSubmission.precondition_checks || {}) };
   agentSubmission = autoDetectPreconditions(agentSubmission, playbook);
 
-  // F22: precondition_checks merge order is submission → runOpts (runOpts
+  // 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
@@ -2680,38 +2682,37 @@ function run(playbookId, directiveId, agentSubmission = {}, runOpts = {}) {
   // Cross-process mutex lock for this run. preflight verified no other lock
   // exists; we acquire ours and release in the finally block.
   const lockPath = acquireLock(playbookId);
-  // E12: 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. Cached version saves the redundant I/O + JSON parses.
+  // 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.
   //
-  // F2/F9: session_id generated ONCE here, threaded into close() via
-  // cachedRunOpts.session_id. Pre-fix close() generated its own session_id
-  // independently, so CSAF tracking.id / OpenVEX @id / product PURLs all
-  // diverged from the run()-returned session_id and the on-disk attestation
-  // file name. Operators correlating attestation files to embedded bundle
-  // URNs got mismatched ids.
+  // 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.
   const sessionId = runOpts.session_id || crypto.randomBytes(8).toString('hex');
   const cachedRunOpts = { ...runOpts, _playbookCache: playbook, session_id: sessionId };
-  // E3: run-time error accumulator for evalCondition regex failures and other
+  // Run-time error accumulator for evalCondition regex failures and other
   // non-fatal anomalies surfaced into analyze.runtime_errors[].
   const runErrors = [];
   cachedRunOpts._runErrors = runErrors;
-  // U REG-1: normalizeSubmission may push structured errors (e.g.
-  // signal_overrides_invalid) onto submission._runErrors. Pre-fix these were
-  // stranded — they never reached the run-level accumulator that analyze()
-  // slices into runtime_errors[], so F20's "analyze surfaces all runtime
-  // errors" contract was silently broken. Splice the pre-run errors into
-  // the run-level accumulator and strip the field off the submission so it
-  // doesn't pollute the F1 evidence_hash digest (the hash canonicalizes the
-  // submission and a non-deterministic _runErrors would change it).
+  // 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).
   if (Array.isArray(agentSubmission._runErrors) && agentSubmission._runErrors.length) {
     runErrors.push(...agentSubmission._runErrors);
   }
   if (agentSubmission && Object.prototype.hasOwnProperty.call(agentSubmission, '_runErrors')) {
     delete agentSubmission._runErrors;
   }
-  // E6: phases the runner should SKIP execution for, based on skip_phase
+  // Phases the runner should SKIP execution for, based on skip_phase
   // preconditions surfaced in preflight.issues.
   const skipPhases = new Set();
   for (const issue of (pre.issues || [])) {
@@ -2753,7 +2754,7 @@ 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);
 
-    // E3: analyze() already sliced runOpts._runErrors into
+    // 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
@@ -2767,14 +2768,13 @@ function run(playbookId, directiveId, agentSubmission = {}, runOpts = {}) {
       }
     }
 
-    // F1: evidence_hash binds the operator's submission to the verdict.
-    // Pre-fix the hash only covered { playbook, directive, cves, rwep,
-    // classification } — two operators submitting completely different
-    // evidence that happened to produce the same classification got the
-    // same evidence_hash, breaking the contract that the hash uniquely
-    // identifies a run. Now the hash includes a canonicalized SHA-256 over
-    // the submission (observations, signal_overrides, signals) with sorted
-    // keys recursively. `captured_at` and other timestamp-like fields are
+    // 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).
@@ -2799,7 +2799,7 @@ function run(playbookId, directiveId, agentSubmission = {}, runOpts = {}) {
       evidence_hash: evidenceHash,
       submission_digest: submissionDigest,
       preflight_issues: pre.issues,
-      // F22: source provenance for precondition_checks. Shape:
+      // Source provenance for precondition_checks. Shape:
       //   { '<pc-id>': 'submission' | 'runOpts' | 'merged', ... }
       precondition_check_source: pcSource,
       phases
@@ -2813,7 +2813,7 @@ function run(playbookId, directiveId, agentSubmission = {}, runOpts = {}) {
 // --- helpers ---
 
 /**
- * F1: deterministic JSON stringification with recursively sorted keys.
+ * 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
@@ -2829,7 +2829,7 @@ function canonicalStringify(v) {
 }
 
 /**
- * F1: pick the operator-meaningful fields out of the normalized submission
+ * 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
@@ -2936,7 +2936,7 @@ function evalCondition(expr, ctx, playbook) {
   if (m) {
     const val = resolvePath(ctx, m[1]);
     if (typeof val !== 'string') return false;
-    // E3: an operator-supplied or playbook-supplied regex with a syntax bug
+    // 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
@@ -3015,12 +3015,11 @@ function stripOuterParens(expr) {
  * submits clock_started_at_<event> ISO strings as it progresses through
  * incident-response milestones.
  *
- * E7: per AGENTS.md Phase 7, the legal contract is that the clock starts
+ * 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. Pre-fix, this auto-stamped Date.now() on
- * detect_confirmed whenever the engine classified as detected, which is
- * incorrect: the operator may not have seen the result yet. The corrected
- * semantics:
+ * `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.
  *   - Otherwise, for 'detect_confirmed' with classification='detected':
@@ -3123,9 +3122,9 @@ module.exports = {
   vexFilterFromDoc,
   normalizeSubmission,
   autoDetectPreconditions,
-  // MM P1-D: exposed for tests/audit-vv-trust-fixes.test.js so library-side
-  // direct callers (the fallback path the CLI guard cannot reach) can be
-  // exercised without spawning a CLI subprocess.
+  // Exported so library-side direct callers (the fallback path the CLI
+  // guard cannot reach) can be exercised without spawning a CLI
+  // subprocess.
   sanitizeOperatorText,
   // internal helpers exposed for tests
   _resolvedPhase: resolvedPhase,