@blamejs/exceptd-skills 0.19.33 → 0.19.34

package/lib/citation-resolve.js

@@ -1,24 +1,11 @@
 "use strict";
 
 /**
- * lib/citation-resolve.js
- *
- * Answers "is this CVE/RFC citation valid?" so an agent gets the answer FROM
- * exceptd instead of researching each citation against NVD / the IETF
- * datatracker by hand. Offline-first:
- *
- *   CVE: local catalog -> resolved cache -> (opt-in) one NVD lookup, cached.
- *   RFC: local index    -> resolved cache -> (opt-in) one datatracker lookup.
- *
- * The resolved cache lives at .cache/upstream/resolved/<kind>/<id>.json with a
- * 7-day TTL. The FIRST agent to resolve an uncatalogued id pays one network
- * call and writes the cache; sibling agents (and later offline runs) read it —
- * turning N agents x M citations of redundant lookups into one lookup per id.
- *
- * Network is opt-out: --air-gap / EXCEPTD_AIR_GAP=1 / { noNetwork:true } make
- * resolution offline-only (catalog + cache), returning status "unknown" with a
- * reason rather than reaching out. Network-resolved records are transient
- * (cache only) and are never written into the signed catalog.
+ * Answers "is this CVE/RFC citation valid?" offline-first: local catalog or
+ * index, then the resolved cache, then one opt-in network lookup. --air-gap /
+ * EXCEPTD_AIR_GAP=1 / { noNetwork:true } make it offline-only, returning status
+ * "unknown". Network-resolved records live in the cache only and never enter
+ * the signed catalog.
  */
 
 const fs = require("node:fs");
@@ -45,26 +32,16 @@ function rfcIndex() {
   return _rfc;
 }
 
-// --- resolved-id cache (atomic JSON files, TTL-bounded, integrity-checked) ---
-//
-// The cache feeds security verdicts (and, via citation-hygiene --resolve,
-// attestations), so a record is only trusted if it carries a matching content
-// digest AND its own `resolved_at` is within the freshness window. A file an
-// attacker (or a corrupt/half-written process) edits in place without
-// recomputing `_digest` is rejected as a cache-miss — it can never launder a
-// rejected/fabricated citation into "published". This is the resolved-cache
-// analogue of the prefetch cache's sha256+signature model; full maintainer
-// signing isn't possible operator-side (no private key), so the digest binds
-// the record to itself and makes tampering detectable.
+// The resolved-id cache feeds security verdicts, so a record is trusted only when
+// its `_digest` matches and its own `resolved_at` is inside the freshness window —
+// an in-place edit cannot launder a rejected citation into "published".
 function cachePath(kind, id) {
   // Read the env at call time so tests can isolate the cache per-case.
   const dir = process.env.EXCEPTD_RESOLVE_CACHE_DIR || RESOLVE_CACHE_DIR;
   const safe = id.replace(/[^A-Za-z0-9._-]/g, "_");
   return path.join(dir, kind, `${safe}.json`);
 }
-// sha256 over the record's canonical bytes (sorted keys, `_digest` excluded).
-// `resolved_at` IS covered, so the staleness clock can't be rewritten apart
-// from the verdict.
+// sha256 over canonical bytes (sorted keys, `_digest` excluded); covers `resolved_at`.
 function recordDigest(record) {
   const canon = {};
   for (const k of Object.keys(record).sort()) {
@@ -78,20 +55,14 @@ function cacheGet(kind, id) {
     const p = cachePath(kind, id);
     const record = JSON.parse(fs.readFileSync(p, "utf8"));
     if (!record || typeof record !== "object") return null;
-    // Integrity: a record without a matching digest is tampered/corrupt → miss.
     if (typeof record._digest !== "string" || record._digest !== recordDigest(record)) return null;
-    // Freshness keyed on the record's own resolved_at (not file mtime, which a
-    // `touch` can reset). Reject future-dated records as a poisoning signal,
-    // mirroring the prefetch cache's future-date guard.
+    // resolved_at, not file mtime which `touch` resets; a future-dated record is poisoning.
     const ts = Date.parse(record.resolved_at || "");
     if (!Number.isFinite(ts)) return null;
     const age = Date.now() - ts;
     if (age < -60_000 || age > CACHE_TTL_MS) return null;
-    // Bind the record to the requested key — a digest proves self-consistency,
-    // not that this is the record FOR the looked-up id/kind. A digest-valid
-    // record written under one filename but carrying a different internal
-    // id/kind would otherwise be served for the wrong lookup (a swapped-file
-    // poisoning that the self-digest cannot catch). Mismatch → cache miss.
+    // The digest proves self-consistency, not that this is the record FOR this
+    // id/kind — a valid record filed under another name must not be served.
     if (record.kind !== kind) return null;
     if (kind === "cve") {
       if (typeof record.id !== "string" || record.id.toUpperCase() !== String(id).toUpperCase()) return null;
@@ -108,9 +79,7 @@ function cachePut(kind, id, record) {
     fs.mkdirSync(path.dirname(p), { recursive: true });
     const signed = { ...record };
     signed._digest = recordDigest(signed);
-    // Random suffix (not just pid) so two cachePut calls for the same id in one
-    // process — a Promise.all fan-out or worker threads sharing a pid — don't
-    // race the same tmp path. Matches lib/prefetch.js writeFileAtomic.
+    // Random suffix, not just pid: an in-process fan-out would race the same tmp path.
     const tmp = `${p}.${process.pid}.${crypto.randomBytes(4).toString("hex")}.tmp`;
     fs.writeFileSync(tmp, JSON.stringify(signed));
     fs.renameSync(tmp, p); // atomic — concurrent readers never see a half-written file
@@ -127,9 +96,7 @@ function isAirGap(opts) {
  * from:   format | catalog | cache | network | offline | error
  */
 async function resolveCve(id, opts = {}) {
-  // Trim before the format test — matches resolveRfc — so a whitespace-only
-  // identifier is "fabricated/malformed" (empty form) rather than a literal
-  // whitespace string fed straight into CVE_RE.
+  // Trim before the format test so a whitespace-only id is malformed, not fed to CVE_RE.
   const cveId = String(id || "").trim().toUpperCase();
   const base = { id: cveId, kind: "cve" };
 
@@ -153,10 +120,7 @@ async function resolveCve(id, opts = {}) {
     };
   }
 
-  // 1b. alias lookup — an id may be carried as an alias of a curated entry
-  //     (e.g. a CVE for a sub-incident folded into a campaign-level MAL-* key).
-  //     Catalogued-by-alias must resolve offline too, or `exceptd cve <alias>`
-  //     would report unknown for an incident the catalog actually covers.
+  // 1b. alias lookup — a catalogued-by-alias id must resolve offline too.
   for (const k of Object.keys(catalog)) {
     if (k === "_meta") continue;
     const e = catalog[k];
@@ -178,7 +142,6 @@ async function resolveCve(id, opts = {}) {
   const cached = cacheGet("cve", cveId);
   if (cached) return { ...cached, from: "cache" };
 
-  // 3. offline / air-gap: cannot resolve uncatalogued ids without network
   if (isAirGap(opts)) {
     return { ...base, status: "unknown", from: "offline",
       reason: "air-gap: not in local catalog and no cached resolution — verify against NVD when online" };
@@ -188,9 +151,7 @@ async function resolveCve(id, opts = {}) {
       reason: "not in local catalog and no cached resolution (network disabled)" };
   }
 
-  // 4. resolve once via NVD, then cache for sibling agents.
-  // opts._validateCve is a test seam (inject a fake validator); production uses
-  // the real NVD-backed validator.
+  // Resolve once via NVD, then cache. opts._validateCve is a test seam.
   let validateCve = opts._validateCve;
   if (!validateCve) {
     try { ({ validateCve } = require("../sources/validators/cve-validator.js")); }
@@ -203,11 +164,8 @@ async function resolveCve(id, opts = {}) {
   if (v.status === "unreachable") {
     return { ...base, status: "unknown", from: "offline", reason: "NVD unreachable — retry online" };
   }
-  // NVD is the authority for a CVE's existence and lifecycle. validateCve only
-  // returns "unreachable" when EVERY source fails — if NVD is down but KEV/EPSS
-  // answer, it returns match/drift with sources.nvd.reachable === false. Do NOT
-  // declare "published" on KEV/EPSS alone during an NVD outage; that would
-  // falsely validate an unconfirmed (or nonexistent) identifier.
+  // "unreachable" means EVERY source failed, so an NVD outage with KEV/EPSS still
+  // answering slips through. NVD is the existence authority: never publish on KEV alone.
   const nvd = v.fetched && v.fetched.sources && v.fetched.sources.nvd;
   if (!nvd || nvd.reachable !== true) {
     return { ...base, status: "unknown", from: "offline",
@@ -223,9 +181,7 @@ async function resolveCve(id, opts = {}) {
     id: cveId, kind: "cve", status,
     cvss: v.fetched?.cvss_score ?? null,
     kev: v.fetched?.in_kev ?? null,
-    // NVD English description — carries the product/scope a citation must match,
-    // so an agent can confirm status=published applies to the right product
-    // without a second manual NVD lookup.
+    // The NVD description carries the product/scope a citation must match.
     product: v.fetched?.description ?? null,
     nvd_vuln_status: v.fetched?.nvd_vuln_status ?? null,
     cve_tags: v.fetched?.cve_tags || [],
@@ -238,11 +194,8 @@ async function resolveCve(id, opts = {}) {
 
 /**
  * Resolve an RFC citation. Returns { id, kind:"rfc", number, title, rfc_status,
- * found, from, ... }. The local index covers the whole RFC series — current
- * AND obsoleted/historic (the latter carry `_obsoleted` + `obsoleted_by`) — so
- * number->title resolution, including "is this RFC superseded?", is fully
- * offline. A number absent from the index is almost certainly nonexistent (or
- * an UNKNOWN-status placeholder); the optional network step confirms.
+ * found, from, ... }. A number absent from the local index is almost certainly
+ * nonexistent; the optional network step confirms.
  */
 async function resolveRfc(id, opts = {}) {
   const raw = String(id || "").trim();
@@ -255,7 +208,7 @@ async function resolveRfc(id, opts = {}) {
   const num = Number(m[1]);
   const key = `RFC-${num}`;
 
-  // 1. local index (offline, whole current series)
+  // 1. local index (offline)
   const entry = rfcIndex()[key];
   if (entry && typeof entry === "object") {
     return {
@@ -268,7 +221,6 @@ async function resolveRfc(id, opts = {}) {
     };
   }
 
-  // 2. resolved cache
   const cached = cacheGet("rfc", String(num));
   if (cached) return { ...cached, from: "cache" };
 

package/lib/collectors/ai-api.js

@@ -1,21 +1,9 @@
 "use strict";
 
 /**
- * lib/collectors/ai-api.js
- *
- * Companion collector for the `ai-api` playbook. Scans shell rc
- * files for cleartext AI API key exports, plus the standard
- * credential carriers (~/.aws, ~/.kube, ~/.config/gcloud) for
+ * Companion collector for the `ai-api` playbook: scans shell rc files for
+ * cleartext AI API key exports, plus ~/.aws, ~/.kube and ~/.config/gcloud for
  * long-lived credentials likely to authenticate against AI APIs.
- *
- * Non-deterministic indicators (ai-api-egress-from-unexpected-
- * process, ai-api-anomalous-volume, ai-api-beaconing-cadence,
- * base64-or-encoded-payload-in-prompts) require ss/netstat/auditd
- * traces and process-list correlation that fall outside the
- * stdlib-only collector contract. They stay unflipped — the runner
- * returns inconclusive and operator-supplied evidence completes
- * the verdict.
- *
  * Interface: see lib/collectors/README.md
  */
 
@@ -31,10 +19,8 @@ function readSafe(full, max = 256 * 1024) {
     fd = fs.openSync(full, "r");
     const s = fs.fstatSync(fd);
     if (s.size > max) return null;
-    // readFileSync(fd) loops read() to EOF — a single readSync may return
-    // fewer than s.size bytes on network/FUSE/sync-backed fds, which would
-    // leave the buffer tail NUL-filled and silently drop trailing content.
-    // Reading via the already-open fd keeps the fstat-then-read TOCTOU-free.
+    // readFileSync(fd) loops to EOF; a single readSync can return short on a
+    // network or FUSE fd. Reading the open fd keeps fstat-then-read TOCTOU-free.
     return fs.readFileSync(fd, "utf8");
   } catch { return null; }
   finally { if (fd !== undefined) { try { fs.closeSync(fd); } catch { /* non-fatal */ } } }
@@ -44,9 +30,7 @@ function fileExists(full) {
   try { return fs.statSync(full).isFile(); } catch { return false; }
 }
 
-// Cleartext AI-API-key export patterns. Matches the standard
-// `export VAR=value` and `VAR=value` shell shapes plus fish-style
-// `set -gx VAR value`.
+// Cleartext key exports: `export VAR=value`, `VAR=value`, fish `set -gx VAR value`.
 const AI_KEY_PATTERNS = [
   { id: "openai",       re: /(?:^|\n)\s*(?:export\s+|set\s+-gx\s+)?OPENAI_API_KEY\s*[= ]\s*['"]?sk-[A-Za-z0-9_-]{20,}/m },
   { id: "anthropic",    re: /(?:^|\n)\s*(?:export\s+|set\s+-gx\s+)?ANTHROPIC_API_KEY\s*[= ]\s*['"]?sk-ant-[A-Za-z0-9_-]{20,}/m },
@@ -56,20 +40,15 @@ const AI_KEY_PATTERNS = [
   { id: "cohere",       re: /(?:^|\n)\s*(?:export\s+|set\s+-gx\s+)?COHERE_API_KEY\s*[= ]\s*['"]?[A-Za-z0-9-]{30,}/m },
 ];
 
-// Capture the exported value so the false_positive_checks_required entries
-// (placeholder demotion, entropy floor) can be evaluated. The export
-// patterns above end at the prefix; widen to grab the trailing token.
+// The patterns above end at the prefix; these capture the exported value so
+// the placeholder and entropy-floor FP checks have something to evaluate.
 const AI_KEY_VALUE_RE = {
   openai: /OPENAI_API_KEY\s*[= ]\s*['"]?(sk-[A-Za-z0-9_-]+)/,
   anthropic: /ANTHROPIC_API_KEY\s*[= ]\s*['"]?(sk-ant-[A-Za-z0-9_-]+)/,
   huggingface: /(?:HUGGINGFACE_TOKEN|HF_TOKEN)\s*[= ]\s*['"]?(hf_[A-Za-z0-9]+)/,
-  // Azure/Google/Cohere keys carry no vendor prefix, so the captured value IS
-  // the entropy body. Without these, cleartextFpIndices found no value for an
-  // azure/google/cohere-only dotfile, returned an empty attestation, and the
-  // runner downgraded a real cleartext-key hit to inconclusive — the indicator
-  // fired then vanished for half the supported vendors. The 30-char entropy
-  // floor (the `: 30` else-branch below) and PLACEHOLDER_RE both apply, since
-  // the prefix-strip leaves these values unchanged.
+  // Azure, Google and Cohere keys carry no vendor prefix, so the captured value
+  // IS the entropy body. Drop one of these and cleartextFpIndices attests nothing
+  // for such a dotfile, downgrading a real hit to inconclusive.
   azure: /AZURE_OPENAI(?:_API)?_KEY\s*[= ]\s*['"]?([A-Za-z0-9]{20,})/,
   google: /(?:GOOGLE_API_KEY|GOOGLE_GENAI_API_KEY|GEMINI_API_KEY)\s*[= ]\s*['"]?([A-Za-z0-9_-]{20,})/,
   cohere: /COHERE_API_KEY\s*[= ]\s*['"]?([A-Za-z0-9-]{30,})/,
@@ -85,12 +64,9 @@ function scanShellRc(content) {
   return hits;
 }
 
-// Deterministic false_positive_checks_required evaluation for
-// cleartext-api-key-in-dotfile. Returns the satisfiable indices for the
-// exports found across the canonical dotfiles (intersection — an index is
-// only attested if every export satisfies it). Canonical home rc / dotfile
-// paths are never under examples/tests/fixtures, so the path check [1] is
-// always satisfied here.
+// The satisfiable false_positive_checks_required indices for
+// cleartext-api-key-in-dotfile, intersected across every export found. Canonical
+// home dotfiles are never under examples/tests/fixtures, so [1] always holds.
 function cleartextFpIndices(content) {
   const sat = new Set(["0", "1", "2"]);
   let sawAny = false;
@@ -101,8 +77,7 @@ function cleartextFpIndices(content) {
     const value = m[1];
     // [0] not a documented placeholder / sk-test- fixture
     if (PLACEHOLDER_RE.test(value)) sat.delete("0");
-    // [2] entropy floor: OpenAI sk-* >= 48 post-prefix, Anthropic sk-ant-* >= 40,
-    //     HuggingFace hf_* >= 30.
+    // [2] entropy floor, post-prefix: OpenAI 48, Anthropic 40, others 30.
     const floor = vendor === "openai" ? 48 : vendor === "anthropic" ? 40 : 30;
     const body = value.replace(/^sk-ant-(?:api03|admin01)-|^sk-(?:proj-|svcacct-|admin-)?|^hf_/, "");
     if (body.length < floor) sat.delete("2");
@@ -128,9 +103,8 @@ function parseAwsCredentials(content) {
   const staticProfiles = [];
   const accessKeyIds = [];
   for (const [name, kv] of Object.entries(profiles)) {
-    // long-lived-aws-keys: aws_access_key_id present AND no
-    // aws_session_token sibling (STS temporary creds carry the
-    // session token; IAM-user long-lived keys do not).
+    // Long-lived means an access key id with no session-token sibling: STS
+    // temporary credentials always carry one, IAM-user keys never do.
     if (kv["aws_access_key_id"] && !kv["aws_session_token"]) {
       staticProfiles.push(name);
       accessKeyIds.push(kv["aws_access_key_id"]);
@@ -187,12 +161,10 @@ function collect({ cwd = process.cwd(), env = process.env, args = {} } = {}) {
   const root = path.resolve(cwd);
   const home = (env && env.HOME) || (env && env.USERPROFILE) || os.homedir();
 
-  // Shell rc + dotfile candidates.
   const shellRcs = [
     ".bashrc", ".bash_profile", ".zshrc", ".zprofile", ".profile",
     path.join(".config", "fish", "config.fish"),
   ].map(rel => path.join(home, rel));
-  // Glob fish/conf.d/*.
   try {
     const fishConfD = path.join(home, ".config", "fish", "conf.d");
     for (const e of fs.readdirSync(fishConfD)) {
@@ -227,7 +199,6 @@ function collect({ cwd = process.cwd(), env = process.env, args = {} } = {}) {
   }
   const cleartextAnyHit = Object.keys(cleartextHitsByFile).length > 0;
 
-  // AWS / GCP / kube reuse.
   const awsCredsPath = path.join(home, ".aws", "credentials");
   const awsCredsContent = fileExists(awsCredsPath) ? readSafe(awsCredsPath) : null;
   const awsParsed = parseAwsCredentials(awsCredsContent);
@@ -249,13 +220,9 @@ function collect({ cwd = process.cwd(), env = process.env, args = {} } = {}) {
     "kubeconfig-with-static-token": kubeStaticToken ? "hit" : "miss",
   };
 
-  // Per-indicator __fp_checks attestation. Each canonical-path credential
-  // store the collector reads is never under an examples/tests/fixtures path,
-  // so the path-based FP checks are satisfied; value-based checks (placeholder,
-  // entropy, sample-credential, cluster-locality) are evaluated deterministically.
-  // Network / sts-validity checks are left unattested so the runner still
-  // downgrades those. Without this, a real cleartext key or static token
-  // surfaced by `collect` is downgraded to inconclusive after `run`.
+  // Per-indicator __fp_checks attestation. Path checks hold because every store
+  // read here is a canonical home path; network and STS-validity checks stay
+  // unattested. With no attestation at all, a real hit downgrades to inconclusive.
   if (cleartextAnyHit && cleartextFp && cleartextFp.size) {
     const att = {};
     for (const idx of cleartextFp) att[idx] = true;
@@ -278,8 +245,7 @@ function collect({ cwd = process.cwd(), env = process.env, args = {} } = {}) {
     // [1] client_email is a real *@*.gserviceaccount.com (not example/test)
     const ce = gcloudParsed.clientEmail || "";
     if (/@[^@\s]+\.gserviceaccount\.com$/i.test(ce) && !/@example\.com$|@test\./i.test(ce)) att["1"] = true;
-    // [2] canonical ADC path (not under examples/) AND no GOOGLE_APPLICATION_CREDENTIALS
-    //     redirecting away from it
+    // [2] canonical ADC path, with no GOOGLE_APPLICATION_CREDENTIALS redirect
     if (!(env && env.GOOGLE_APPLICATION_CREDENTIALS)) att["2"] = true;
     if (Object.keys(att).length) signal_overrides["gcp-service-account-json__fp_checks"] = att;
   }

package/lib/collectors/cicd-pipeline-compromise.js

@@ -1,32 +1,18 @@
 "use strict";
 
 /**
- * lib/collectors/cicd-pipeline-compromise.js
- *
- * Companion collector for the `cicd-pipeline-compromise` playbook.
- * Consumer-side CI/CD posture: walks .github/workflows/*.yml,
- * .gitlab-ci.yml, .circleci/config.yml, and the project's
- * infra/terraform/policies dirs for OIDC trust JSON. Flips
- * deterministic indicators that detect the published-Action and
- * fork-PR attack classes documented in the playbook.
- *
- * Skipped indicators (require GitHub API or HSM/KMS access, left
- * unflipped so the runner returns inconclusive):
- *
- *   self-hosted-runner-non-ephemeral    needs GitHub API (runners list)
- *   runner-scoped-signing-key           needs HSM/KMS inspection
- *
- * Interface: see lib/collectors/README.md
+ * Companion collector for the `cicd-pipeline-compromise` playbook: walks CI
+ * workflow YAML and the infra / terraform / policies dirs for OIDC trust JSON.
+ * `self-hosted-runner-non-ephemeral` and `runner-scoped-signing-key` are left
+ * unflipped (GitHub runners API / HSM inspection), so they report inconclusive.
+ * Interface: lib/collectors/README.md.
  */
 
 const fs = require("node:fs");
 const path = require("node:path");
 const { codeExcludeSet, isLinkedWorktreeDir, buildEvidenceLocations } = require("./scan-excludes");
 
-// Shared code-scope name exclusions (dependency caches, build output, VCS +
-// agent scratch). Threaded into the OIDC-policy descent so a trust JSON in a
-// build-output dir (e.g. `dist/`) is not scanned — consistent with the other
-// tree-walking collectors.
+// Shared code-scope exclusions, so a trust JSON under `dist/` is not scanned.
 const OIDC_WALK_EXCLUDES = codeExcludeSet();
 
 const COLLECTOR_ID = "cicd-pipeline-compromise";
@@ -37,10 +23,8 @@ function readSafe(p, max = 512 * 1024) {
     fd = fs.openSync(p, "r");
     const s = fs.fstatSync(fd);
     if (s.size > max) return null;
-    // readFileSync(fd) loops read() to EOF — a single readSync may return
-    // fewer than s.size bytes on network/FUSE/sync-backed fds, which would
-    // leave the buffer tail NUL-filled and silently drop trailing content.
-    // Reading via the already-open fd keeps the fstat-then-read TOCTOU-free.
+    // readFileSync(fd) loops read() to EOF; a single readSync can return short on
+    // a network or FUSE fd. Reading the open fd keeps fstat-then-read TOCTOU-free.
     return fs.readFileSync(fd, "utf8");
   } catch { return null; }
   finally { if (fd !== undefined) { try { fs.closeSync(fd); } catch { /* non-fatal */ } } }
@@ -72,20 +56,13 @@ function walkWorkflows(root) {
   return out;
 }
 
-// `on:` trigger detection. Workflows declare triggers via four
-// canonical YAML shapes:
-//   - scalar:     `on: push`
-//   - inline list: `on: [push, pull_request_target]`
-//   - block list:  `on:\n  - push\n  - pull_request_target`
-//   - mapping:     `on:\n  push:\n  pull_request_target:`
-// Heuristic accepts all four.
+// Trigger detection across the four canonical `on:` shapes: scalar
+// (`on: push`), inline list, block list, and mapping.
 function workflowHasTrigger(content, name) {
   if (new RegExp(`^\\s*on:\\s*['"]?${name}['"]?\\s*(?:#.*)?$`, "m").test(content)) return true; // allow:dynamic-regex — `name` is a hardcoded trigger literal (pull_request_target / issue_comment / pull_request), never operator/file input
   const listMatch = content.match(/^\s*on:\s*\[([^\]]*)\]/m);
   if (listMatch && new RegExp(`(?:^|,)\\s*['"]?${name}['"]?\\s*(?:,|$)`).test(listMatch[1])) return true; // allow:dynamic-regex — `name` is a hardcoded trigger literal, never operator/file input
-  // block list AND mapping forms both follow `on:\n` with indented
-  // continuation lines. Capture the block and inspect for either
-  // `- <name>` (list) or `<name>:` (mapping) within it.
+  // Block-list and mapping forms both follow `on:\n` with indented continuations.
   const blockMatch = content.match(/^\s*on:\s*\n((?:[ \t]+[^\n]+\n?)+)/m);
   if (blockMatch) {
     if (new RegExp(`^[ \\t]+-\\s+['"]?${name}['"]?\\s*(?:#.*)?\\s*$`, "m").test(blockMatch[1])) return true; // allow:dynamic-regex — `name` is a hardcoded trigger literal, never operator/file input
@@ -94,13 +71,9 @@ function workflowHasTrigger(content, name) {
   return false;
 }
 
-// Find `actions/checkout` step blocks and return true when any one
-// of them carries a `ref:` line referencing the PR head. Each step
-// block is delimited by the next sibling `- ` at the same
-// indentation (or de-indented line, meaning we've left steps[]).
-// Binding the ref match to the checkout step prevents false hits
-// when another unrelated step references the PR head while the
-// actual checkout is safely fetching the base ref.
+// True when an `actions/checkout` step block carries a `ref:` naming the PR head.
+// Binding the ref to the checkout step keeps an unrelated step's reference to the
+// PR head from reading as a hit while the checkout fetches the base ref.
 function checkoutBindsPrHead(content) {
   const lines = content.split(/\r?\n/);
   for (let i = 0; i < lines.length; i++) {
@@ -114,8 +87,7 @@ function checkoutBindsPrHead(content) {
       const indentM = line.match(/^(\s*)\S/);
       if (!indentM) continue;
       const indent = indentM[1].length;
-      // Next sibling step starts with `-` at the same indent, or
-      // any line de-indented past the step base ends the block.
+      // The block ends at a sibling `-` on the same indent, or any de-indent.
       if (indent < baseIndent) { blockEnd = j; break; }
       if (indent === baseIndent && line.trim().startsWith("- ")) { blockEnd = j; break; }
     }
@@ -139,18 +111,12 @@ function scanWorkflow(content, rel) {
   const hasPRTarget = workflowHasTrigger(content, "pull_request_target");
   const hasIssueComment = workflowHasTrigger(content, "issue_comment");
 
-  // pull-request-target-with-pr-checkout: PRT trigger AND the
-  // PR-head ref reference is bound to an actions/checkout step
-  // (not to an unrelated step that happens to read head_ref).
   if (hasPRTarget && checkoutBindsPrHead(content)) {
     hits["pull-request-target-with-pr-checkout"].push({ file: rel, snippet: "pull_request_target trigger + checkout of PR head" });
   }
 
-  // workflow-injection-sink: ${{ github.event.<title|body|...> }}
-  // interpolated directly inside a `run:` block. Conservative form:
-  // file-wide presence of one of the dangerous expressions AND the
-  // expression appears outside an `env:` mapping context that would
-  // have made it safe.
+  // workflow-injection-sink: an attacker-controlled `${{ github.event.* }}`
+  // interpolated inside a `run:` block, outside a safe `env:` mapping.
   if (hasPRTarget || hasIssueComment || workflowHasTrigger(content, "pull_request")) {
     const dangerousExprs = [
       /\$\{\{\s*github\.event\.pull_request\.(?:title|body|head\.ref)\s*\}\}/,
@@ -162,17 +128,12 @@ function scanWorkflow(content, rel) {
     const lines = content.split(/\r?\n/);
     for (let i = 0; i < lines.length; i++) {
       const line = lines[i];
-      // Quick filter: dangerous expression on this line?
       const matchedExpr = dangerousExprs.find(re => re.test(line));
       if (!matchedExpr) continue;
-      // If the dangerous expr is inside an `env:` mapping (key: value
-      // shape on a YAML env block), the shell sees it as a variable
-      // and it's not an injection sink. Walk back up to 3 lines to
-      // find the nearest preceding YAML key indicator.
+      // Inside an `env:` mapping the shell sees a variable, not a sink.
       const ctx = lines.slice(Math.max(0, i - 3), i + 1).join("\n");
       const isEnvBinding = /^\s+[A-Z_][A-Z0-9_]*:\s*['"]?\$\{\{\s*github\.event/m.test(ctx);
-      // Detect `run:` proximity. The expression must land inside a
-      // run-block; otherwise it's an `env:` binding or `with:` arg.
+      // The expression counts only inside a run-block.
       const inRun = /^\s+run:/m.test(ctx) || /^\s+\|/m.test(ctx) || lines[i].trim().startsWith("- run:");
       if (inRun && !isEnvBinding) {
         hits["workflow-injection-sink"].push({ file: rel, line: i + 1, snippet: line.trim().slice(0, 160) });
@@ -181,17 +142,14 @@ function scanWorkflow(content, rel) {
     }
   }
 
-  // actions-floating-tag-pin: `uses: <owner>/<repo>@<ref>` where ref
-  // isn't a 40-char hex SHA AND owner isn't `actions` (first-party
-  // GitHub repos excluded by the playbook predicate). Excludes local
-  // composite actions (`uses: ./`).
+  // actions-floating-tag-pin: `uses: <owner>/<repo>@<ref>` where ref is not a
+  // 40-char hex SHA; owner `actions` and local composite actions are excluded.
   const lines2 = content.split(/\r?\n/);
   for (let i = 0; i < lines2.length; i++) {
-    // A real `uses:` line is never multiple KB. Skip overlong lines so a
-    // crafted whitespace run can't drive regex backtracking.
+    // A real `uses:` line is never multiple KB; skipping overlong ones keeps a
+    // crafted whitespace run from driving regex backtracking.
     if (lines2[i].length > 4096) continue;
-    // `^[ \t]*(?:-[ \t]*)?` anchors the indentation once, then an optional
-    // `- ` list marker — no overlapping `\s*` runs that backtrack.
+    // Indentation is anchored once, then an optional `- ` — no overlapping `\s*`.
     const m = lines2[i].match(/^[ \t]*(?:-[ \t]*)?uses:\s*['"]?([^'"\s#]+)['"]?/);
     if (!m) continue;
     const refStr = m[1];
@@ -208,15 +166,12 @@ function scanWorkflow(content, rel) {
     }
   }
 
-  // secret-exposed-to-fork-pr: pull_request_target trigger + the
-  // workflow references `secrets.X` for any X other than GITHUB_TOKEN.
-  // Pull-request-from-forks (without target) requires runtime info
-  // to detect fork status — left to operator evidence.
+  // secret-exposed-to-fork-pr: a pull_request_target trigger plus a `secrets.X`
+  // reference for any X other than GITHUB_TOKEN. A plain pull_request from a fork
+  // needs runtime fork status, so it stays operator evidence.
   if (hasPRTarget) {
-    // Compare the captured secret NAME exactly to GITHUB_TOKEN. An unanchored
-    // /secrets\.GITHUB_TOKEN/ substring test also matched custom secrets such
-    // as GITHUB_TOKEN_PROD, silently treating them as the built-in token and
-    // dropping a real fork-PR secret exposure (false negative).
+    // The captured secret NAME is compared exactly: an unanchored
+    // /secrets\.GITHUB_TOKEN/ also matches a custom GITHUB_TOKEN_PROD.
     const nonDefault = [];
     for (const m of content.matchAll(/\$\{\{\s*secrets\.([A-Z_][A-Z0-9_]*)\s*\}\}/g)) {
       if (m[1] !== "GITHUB_TOKEN") nonDefault.push(m[0]);
@@ -230,10 +185,8 @@ function scanWorkflow(content, rel) {
 }
 
 function scanOidcPolicies(root) {
-  // Walk infra/ + terraform/ + policies/ (depth 4) for *.json that
-  // names token.actions.githubusercontent.com AND has a wildcarded
-  // sub-claim. The playbook lists `repo:<org>/*:*`, `repo:*:*`, and
-  // bare `*` as wildcard shapes.
+  // Walks the infra dirs to depth 4 for *.json naming
+  // token.actions.githubusercontent.com with a wildcarded sub-claim.
   const rootDirs = ["infra", "terraform", "policies", ".aws", ".github"].map(d => path.join(root, d));
   const finds = [];
   function walk(dir, depth) {
@@ -245,10 +198,7 @@ function scanOidcPolicies(root) {
       if (OIDC_WALK_EXCLUDES.has(e.name)) continue;
       const full = path.join(dir, e.name);
       if (e.isDirectory()) {
-        // Skip linked git worktrees (gitdir-pointer `.git` file), e.g.
-        // agent-created repo copies under `.claude/worktrees/<id>/`
-        // nested below a scanned policy/infra dir — rescanning them
-        // double-counts the same OIDC trust documents.
+        // A linked worktree holds the same trust documents; rescanning double-counts.
         if (isLinkedWorktreeDir(full)) continue;
         walk(full, depth + 1);
         continue;
@@ -256,14 +206,8 @@ function scanOidcPolicies(root) {
       if (!e.isFile() || !/\.json$/i.test(e.name)) continue;
       const text = readSafe(full);
       if (!text) continue;
-      // The authoritative OIDC sub-claim detection is the self-anchored patterns
-      // below — each is bound to the leading `"` of the JSON key
-      // (`"token.actions.githubusercontent.com:sub"`), so a lookalike issuer
-      // such as `"eviltoken.actions…"` cannot match. No separate substring
-      // pre-filter on the issuer host: it added nothing the anchored patterns
-      // don't already enforce, and a bare host-substring check reads as an
-      // incomplete URL sanitization.
-      // sub-claim wildcards. Cover the three shapes the playbook lists.
+      // Each pattern is bound to the leading `"` of the JSON key, so a lookalike
+      // issuer like `"eviltoken.actions…"` cannot match.
       const subWildcard =
         /"token\.actions\.githubusercontent\.com:sub"\s*:\s*"\*"/.test(text) ||
         /"token\.actions\.githubusercontent\.com:sub"\s*:\s*"repo:\*[^"]*"/.test(text) ||
@@ -280,8 +224,7 @@ function collect({ cwd = process.cwd(), env = process.env, args = {} } = {}) {
   const startTime = Date.now();
   const root = path.resolve(cwd);
 
-  // cwd-is-repo precondition: .git directory present. Outside a
-  // repo we have no workflows / no OIDC trust JSON to walk.
+  // Outside a repo there are no workflows and no OIDC trust JSON to walk.
   const cwdIsRepo = fs.existsSync(path.join(root, ".git"));
   if (!cwdIsRepo) {
     return {
@@ -324,11 +267,8 @@ function collect({ cwd = process.cwd(), env = process.env, args = {} } = {}) {
     "wildcarded-oidc-sub-claim": oidcWildcards.length > 0 ? "hit" : "miss",
   };
 
-  // Per-indicator file locations for every indicator flipped to "hit", so a
-  // SARIF result points at the workflow YAML (or OIDC trust JSON) that
-  // triggered it. Line-scanned indicators (workflow-injection-sink,
-  // actions-floating-tag-pin) carry a real line; the trigger-shape and
-  // OIDC-wildcard indicators record the file only and surface as file-level.
+  // File locations for every indicator flipped to "hit", so a SARIF result points
+  // at the YAML or trust JSON behind it; without a line it surfaces as file-level.
   const evidence_locations = {};
   const evidenceSources = { ...aggregateHits, "wildcarded-oidc-sub-claim": oidcWildcards };
   for (const [id, list] of Object.entries(evidenceSources)) {
@@ -374,17 +314,9 @@ function collect({ cwd = process.cwd(), env = process.env, args = {} } = {}) {
   };
 
   return {
-    // Attest preconditions.
-    //   ci-config-readable — the collector just walked workflow YAML
-    //     + OIDC trust JSON; filesystem reads succeeded. Auto-true.
-    //   operator-owns-ci-fleet — REQUIRES explicit operator opt-in via
-    //     `--attest-ownership` (or args.attestOwnership === true). The
-    //     playbook gates this `on_fail: halt`; running collect against
-    //     any cwd (e.g. `--cwd /other/repo`) does NOT implicitly attest
-    //     ownership of that fleet's CI authorization scope. Operators
-    //     who own the CI fleet they're auditing pass the flag; running
-    //     collect | run without the flag halts at the runner's
-    //     preflight gate (as the playbook intends).
+    // operator-owns-ci-fleet requires explicit opt-in through `--attest-ownership`:
+    // pointing collect at any cwd does NOT attest ownership of that fleet's CI
+    // authorization scope, and the playbook gates the precondition `on_fail: halt`.
     precondition_checks: {
       "cwd-is-repo": true,
       "ci-config-readable": true,