mandrel 2.59.0 → 2.61.0

package/.agents/scripts/lib/project-root.js

@@ -1,12 +1,6 @@
 /**
- * lib/project-root.js — side-effect-free leaf module for the repository
- * root path.
- *
- * Extracted from `config-resolver.js` (Story #3993) so the ~10 importers
- * that need only the path constant no longer transitively load the
- * stateful config subsystem (module-global caches + `.env` load side
- * effect). `config-resolver.js` re-exports this constant, so its barrel
- * surface is unchanged.
+ * lib/project-root.js — side-effect-free leaf for the repo root, so
+ * importers avoid loading the stateful config subsystem.
  */
 
 import path from 'node:path';

package/.agents/scripts/lib/provider-factory.js

@@ -1,13 +1,4 @@
-/**
- * Provider Factory — resolves the configured ticketing provider to a concrete class.
- *
- * Accepts the canonical resolved config object (the wrapper returned by
- * `resolveConfig()` with `config.github` populated). The legacy
- * `orchestration`-shaped argument is no longer supported as part of the
- * Epic #2880 hard cutover; see `.agents/rules/git-conventions-reference.md#contract-cutovers-—-no-shim-layer`.
- *
- * @see docs/v5-implementation-plan.md Sprint 1B
- */
+/** Provider factory — resolved config → concrete ticketing provider. */
 
 import { GitHubProvider } from '../providers/github.js';
 
@@ -17,16 +8,6 @@ const PROVIDERS = {
 };
 
 /**
- * Create a ticketing provider instance from the canonical resolved config.
- *
- * The canonical contract is:
- *   - `config.github` carries the GitHub provider config block
- *     (`owner`, `repo`, `projectNumber`, `projectOwner`, `operatorHandle`,
- *     and friends).
- *   - Today GitHub is the only supported provider, so the provider name is
- *     inferred from the presence of `config.github`. When additional
- *     providers land, this resolver will gain a `config.provider` discriminator.
- *
  * @param {object|null} config - The resolved config wrapper (`resolveConfig()` output).
  * @param {{ token?: string }} [opts] - Override options (e.g., test token).
  * @returns {import('../lib/ITicketingProvider.js').ITicketingProvider}
@@ -68,11 +49,7 @@ export function createProvider(config, opts = {}) {
   return new ProviderClass(providerConfig, opts);
 }
 
-/**
- * Infer the provider name from the resolved config. Today the only
- * supported value is `'github'`; a future provider would add a discriminator
- * field on the top-level config and this helper would consult it.
- */
+/** An explicit `config.provider` wins; otherwise a `github` block implies it. */
 function resolveProviderName(config) {
   if (typeof config.provider === 'string') return config.provider;
   if (config.github) return 'github';

package/.agents/scripts/lib/qa/console-allowlist.js

@@ -1,46 +1,18 @@
 /**
  * console-allowlist.js — deterministic console-message → finding filter.
- *
- * Story #3295 (Feature #3289 "Instrumentation, inspection & findings",
- * Epic #3214). The QA harness captures per-surface console messages via
- * `list_console_messages` and must turn genuine console errors into
- * structured findings while suppressing benign, expected noise. The
- * suppression contract is the `qa.consoleAllowlist` array bound in
- * `.agentrc.json` (landed by Story #3293): a list of inline patterns that
- * mark a console message as expected.
- *
- * This module is the pure, side-effect-free decision layer. Given a list of
- * captured console messages and the consumer's `consoleAllowlist`, it returns
- * one structured finding per non-allowlisted console error and drops every
- * message matched by an allowlist pattern. Determinism is load-bearing:
- * re-running the filter over the same captured console with the same allowlist
- * always yields the same findings in the same order, so the surrounding
- * harness produces stable, diffable evidence.
- *
- * The emitted finding aligns with the `F#` finding shape from Tech Spec #3285
- * (`{ id, classification, surface, symptom, likelyRootCause, disposition,
- * acceptance, evidence: { console[], network[] } }`). This module produces the
- * console-derived subset; `/qa-run` (Story #4330) maps each such finding onto a
- * `QaLedgerItem` (`qa-ledger.schema.json`) before routing it through the shared
- * classify/route/dedup/promote core, leaving richer enrichment
- * (likely-root-cause heuristics, drafting) to those later layers.
+ * Each non-allowlisted console error becomes one `F#` finding (console-derived
+ * subset); `qa.consoleAllowlist` patterns suppress expected noise.
  */
 
 /**
- * Console message levels that the harness treats as error-grade. Only
- * messages at one of these levels can become a finding; `log`, `info`,
- * `debug`, and `warning` are never escalated by this module.
+ * Only these levels can become a finding.
  *
  * @type {ReadonlySet<string>}
  */
 const ERROR_LEVELS = new Set(['error', 'severe']);
 
 /**
- * Normalise a captured console message into `{ level, text }`. Capture
- * surfaces (`list_console_messages`, raw CDP, etc.) disagree on field names,
- * so accept the common spellings and coerce defensively. A message with no
- * recoverable text normalises to an empty string (which never matches an
- * allowlist pattern and never reads as an error symptom).
+ * Capture surfaces disagree on field names, so accept the common spellings.
  *
  * @param {unknown} message
  * @returns {{ level: string, text: string }}
@@ -59,17 +31,11 @@ function normaliseMessage(message) {
 }
 
 /**
- * Decide whether a console message text is matched by any allowlist pattern.
- *
- * Each allowlist entry is matched as a case-sensitive substring against the
- * message text. Substring (not regex) matching is the deliberate contract:
- * patterns stay readable in `.agentrc.json`, an operator never has to escape
- * regex metacharacters, and the decision is trivially deterministic. An empty
- * or blank pattern is ignored (it would otherwise match everything and
- * silently swallow every error).
+ * Case-sensitive substring match (not regex, so operators never escape
+ * metacharacters). A blank pattern is ignored — it would swallow every error.
  *
  * @param {string} text Normalised console message text.
- * @param {string[]} allowlist Inline benign-console patterns.
+ * @param {string[]} allowlist
  * @returns {boolean} `true` when the message is allowlisted (suppress it).
  */
 export function isAllowlisted(text, allowlist) {
@@ -85,11 +51,6 @@ export function isAllowlisted(text, allowlist) {
 }
 
 /**
- * Build a structured finding for a single non-allowlisted console error.
- * The `id` is assigned by the caller (1-based finding index across a surface)
- * so the surrounding harness controls finding numbering across console and
- * network evidence.
- *
  * @param {{ level: string, text: string }} message Normalised console error.
  * @param {{ surface?: string, index: number }} ctx
  * @returns {object} Structured `F#` finding (console-derived subset).
@@ -111,22 +72,12 @@ function buildFinding(message, ctx) {
 }
 
 /**
- * Filter captured console messages through the `consoleAllowlist` and emit a
- * structured finding for each non-allowlisted console error.
- *
- * Behaviour contract:
- * - A console **error** (level `error`/`severe`) whose text matches no
- *   allowlist pattern becomes exactly one finding.
- * - A console message matched by any allowlist pattern is suppressed — no
- *   finding — even when it is an error.
- * - Non-error levels (`log`, `info`, `warning`, …) are never escalated.
- * - Findings are returned in capture order; ids are assigned `F1`, `F2`, …
- *   in that order.
+ * Findings in capture order, ids `F1`, `F2`, …
  *
  * @param {Array<unknown>} messages Captured console messages.
  * @param {string[]} [allowlist] `qa.consoleAllowlist` patterns.
- * @param {{ surface?: string }} [opts] Surface label for the finding.
- * @returns {object[]} Structured findings (possibly empty).
+ * @param {{ surface?: string }} [opts]
+ * @returns {object[]}
  */
 export function filterConsoleMessages(messages, allowlist = [], opts = {}) {
   if (!Array.isArray(messages)) {

package/.agents/scripts/lib/qa/qa-session.js

@@ -1,32 +1,9 @@
 /**
- * QA exploratory-session resume helper — Story #3723, Epic #3686.
- *
- * A `/qa-explore` run captures observations into a per-session ledger
- * (one `QaLedgerItem` per line, see `.agents/schemas/qa-ledger.schema.json`
- * from Story #3716). For an f5-safety resume to work, a later run with the
- * *same* session-id must read the on-disk ledger, carry forward the still
- * un-triaged findings as a rolling backlog, and append to — never overwrite —
- * the existing file.
- *
- * This module owns three small seams:
- *   - {@link resolveSessionId}  — a stable session-id for a run.
- *   - {@link ledgerPathFor}     — the ledger path under `<tempRoot>/qa/`.
- *   - {@link readLedger}        — parse an existing ledger into items plus the
- *                                 un-triaged subset (the rolling backlog).
- *
- * {@link resolveQaSession} composes them: it resolves the id and path, reads
- * any existing ledger, and reports whether the file already existed so the
- * caller knows to *reuse* rather than re-create it.
- *
- * Evidence persisted in the ledger MUST already be scrubbed of secrets and
- * PII per `.agents/rules/security-baseline.md` (see `lib/qa/redact-evidence.js`)
- * before it reaches disk; this module only reads what is already there.
- *
- * The ledger round-trip is field-preserving: {@link readLedger} parses each
- * line as a whole `QaLedgerItem` and returns it untouched, so optional fields
- * such as the Triage `routedTo` finding-to-issue link
- * (see `.agents/schemas/qa-ledger.schema.json`) survive a read/append cycle
- * intact rather than being dropped on resume.
+ * QA exploratory-session resume helper. A resumed run with the same
+ * session-id reads the on-disk NDJSON ledger, carries forward un-triaged items
+ * as the rolling backlog, and appends — never overwrites. Items round-trip
+ * untouched so optional fields (e.g. `routedTo`) survive. Evidence must be
+ * redacted before it reaches the ledger; this module only reads.
  */
 
 import crypto from 'node:crypto';
@@ -35,22 +12,15 @@ import path from 'node:path';
 
 import { tempRootFrom } from '../config/temp-paths.js';
 
-/** Directory segment (under `tempRoot`) that holds every QA session ledger. */
 const QA_LEDGER_DIRNAME = 'qa';
 
 /**
- * Triaged dispositions, mirrored from the `disposition` enum in
- * `.agents/schemas/qa-ledger.schema.json`. An item carrying any of these has
- * already been triaged; anything else (absent, null, empty, or unrecognized)
- * is still part of the rolling backlog.
+ * Mirrors the `disposition` enum in `qa-ledger.schema.json`; anything else
+ * (absent, null, unrecognized) is still backlog.
  */
 export const TRIAGED_DISPOSITIONS = Object.freeze(['file', 'defer', 'dismiss']);
 
 /**
- * True when a ledger item has **not** yet been triaged — i.e. its
- * `disposition` is not one of the canonical triaged values. These items are
- * the rolling backlog a resume run carries forward.
- *
  * @param {{ disposition?: unknown }} item
  * @returns {boolean}
  */
@@ -60,10 +30,7 @@ export function isUntriaged(item) {
 }
 
 /**
- * Normalize an arbitrary session label into a filesystem-safe slug. Keeps
- * alphanumerics, dot, dash, and underscore; collapses everything else to a
- * single dash. Guards against path traversal so a hostile label can never
- * escape the `qa/` directory.
+ * Filesystem-safe slug; guards against a hostile label escaping `qa/`.
  *
  * @param {string} raw
  * @returns {string}
@@ -77,9 +44,7 @@ function slugifySessionId(raw) {
 }
 
 /**
- * Derive a fresh, stable session-id when the caller supplies none. The id is
- * date-prefixed for human scannability and suffixed with short entropy so two
- * runs on the same day never collide.
+ * Date-prefixed with short entropy so same-day runs never collide.
  *
  * @returns {string}
  */
@@ -90,11 +55,7 @@ function deriveSessionId() {
 }
 
 /**
- * Resolve a stable session-id for a run.
- *
- * Precedence: an explicit `sessionId` option wins; otherwise the
- * `QA_SESSION_ID` environment variable; otherwise a freshly derived id. An
- * explicit or environment id is slugified so it is safe to use as a filename.
+ * Explicit `sessionId`, then `QA_SESSION_ID`, then a derived id.
  *
  * @param {{ sessionId?: string, env?: NodeJS.ProcessEnv }} [opts]
  * @returns {string}
@@ -112,11 +73,9 @@ export function resolveSessionId(opts = {}) {
 }
 
 /**
- * The ledger path for a session: `<tempRoot>/qa/<sessionId>.ndjson`.
- *
- * @param {string} sessionId A slug-safe session-id (see {@link resolveSessionId}).
- * @param {object} [config] Resolved config bag (for `project.paths.tempRoot`).
- * @returns {string}
+ * @param {string} sessionId
+ * @param {object} [config]
+ * @returns {string} `<tempRoot>/qa/<sessionId>.ndjson`
  */
 export function ledgerPathFor(sessionId, config) {
   const slug = slugifySessionId(sessionId);
@@ -124,9 +83,7 @@ export function ledgerPathFor(sessionId, config) {
 }
 
 /**
- * Parse a single ndjson line into a ledger item, or `null` when the line is
- * blank or not valid JSON. Malformed lines are skipped rather than thrown so a
- * partially-written ledger from a crashed run still resumes.
+ * Malformed lines are skipped so a crashed run's partial ledger still resumes.
  *
  * @param {string} line
  * @returns {object | null}
@@ -142,12 +99,6 @@ function parseLine(line) {
 }
 
 /**
- * Read and parse an existing ledger from disk.
- *
- * Returns the full parsed `items` array plus `untriaged` — the subset whose
- * disposition is not yet triaged (the rolling backlog). A missing ledger is
- * not an error: it yields empty arrays and `exists: false`.
- *
  * @param {string} ledgerPath
  * @param {{ fsImpl?: typeof fs }} [opts]
  * @returns {{ exists: boolean, items: object[], untriaged: object[] }}
@@ -163,12 +114,7 @@ export function readLedger(ledgerPath, opts = {}) {
 }
 
 /**
- * Resolve a QA exploratory session: a stable session-id, the ledger path
- * under `<tempRoot>/qa/`, and the current ledger contents (parsed items plus
- * the un-triaged rolling backlog).
- *
- * `reused` is `true` when a ledger already exists for this session-id — the
- * signal that a resume run must append to, not overwrite, the file.
+ * `reused: true` means a ledger exists and the run must append to it.
  *
  * @param {{
  *   sessionId?: string,

package/.agents/scripts/lib/qa/redact-evidence.js

@@ -1,48 +1,12 @@
 /**
- * redact-evidence.js — deterministic secrets/PII scrubber for captured evidence.
- *
- * Story #3717 (Feature #3713, Epic #3686), broadened by Story #3737. The QA
- * harness captures evidence strings (console text, network bodies, error
- * symptoms) that may carry sensitive material. The security baseline
- * (`.agents/rules/security-baseline.md` § Data Leakage & Logging, § Secrets
- * Management) forbids persisting or posting that material to disk or GitHub.
- * This module is the redaction pass that runs **before** any such persistence.
- *
- * The rule set covers the full security-baseline secret/PII taxonomy:
- * bearer tokens, session cookies, email addresses, **passwords**, **API keys**,
- * **credit-card numbers (PANs)**, and **SSNs**. Story #3737 added the last four
- * classes (the #3686 epic-audit + PR #3736 code-review flagged the original
- * scope as narrower than the baseline it advertises) and tightened the
- * session-cookie rule so a benign `name=value` pair whose name merely
- * *contains* a session word (e.g. `author=Jane`, `outside=cold`) is no longer
- * over-redacted (the M1 cookie over-redaction finding).
- *
- * Like its sibling `console-allowlist.js`, this is the pure, side-effect-free
- * decision layer: given an evidence string, it returns the string with every
- * matched secret/PII span replaced by a fixed placeholder. Determinism is
- * load-bearing — re-running the pass over the same input always yields the
- * same output, which gives the harness two guarantees the acceptance criteria
- * pin directly:
- *
- *   1. Idempotence — running `redactEvidence` over already-redacted text is a
- *      no-op, because each placeholder contains none of the patterns that
- *      triggered a redaction. The fixed-point property means the harness can
- *      redact eagerly without worrying about double-scrubbing corrupting
- *      evidence.
- *   2. Pass-through — a string matching no rule is returned byte-for-byte
- *      unchanged, so benign evidence is never mangled.
- *
- * Each placeholder is distinct per rule so a reader of the redacted evidence
- * can still tell *what kind* of secret was scrubbed without seeing its value.
+ * redact-evidence.js — deterministic secrets/PII scrubber run before QA
+ * evidence is persisted or posted (security baseline § Data Leakage).
+ * Idempotent (placeholders match no rule) and pass-through for benign text.
  */
 
 /**
- * Placeholder tokens substituted for each redacted span. Each is deliberately
- * free of any character that the redaction patterns match (no `@`, no token
- * charset run long enough to re-trigger, no `=` cookie assignment, no digit
- * run long enough to read as a PAN/SSN), which is what makes the pass a fixed
- * point — feeding a redacted string back in matches nothing and changes
- * nothing.
+ * Per-rule placeholders, free of anything a pattern matches (`@`, `=`, long
+ * token or digit runs) so the pass is a fixed point.
  *
  * @type {Readonly<Record<string, string>>}
  */
@@ -57,44 +21,28 @@ const PLACEHOLDERS = Object.freeze({
 });
 
 /**
- * Session-secret cookie-name words. A cookie assignment is redacted only when
- * one of these appears as a whole `_`/`.`/`-`-delimited segment of the cookie
- * name — so `sessionId`, `connect.sid`, `auth_token`, `csrf_token`, and
- * `JSESSIONID` match, but `author`, `outside`, `presidency`, and `tokenize`
- * (which merely *contain* a session substring) do not. This segment anchoring
- * is the M1 over-redaction fix.
+ * Must appear as a whole `_`/`.`/`-` segment of the cookie name, so
+ * `connect.sid` matches but `author` or `tokenize` do not.
  *
  * @type {string}
  */
 const SESSION_WORDS = 'session|sessionid|sid|auth|token|jsessionid|csrf|xsrf';
 
 /**
- * Build the case-insensitive session-cookie pattern. The cookie name is one or
- * more `_`/`.`/`-`-delimited segments where at least one segment *is* a session
- * word (boundaries `^`, `_`, `.`, `-`, `$` on both sides), followed by `=` and
- * a value up to the next `;`, whitespace, or end of string.
- *
  * @returns {RegExp}
  */
 function buildCookiePattern() {
   const segment = '[A-Za-z0-9]+';
   const sessionSegment = `(?:${SESSION_WORDS})`;
-  // name = optional leading segments, a session segment, optional trailing
-  // segments, all joined by `_`/`.`/`-`. The (?:...) around the whole name is
-  // captured so `replace` can preserve it.
   const name = `(?:${segment}[._-])*${sessionSegment}(?:[._-]${segment})*`;
-  // The value charset excludes `[` so an already-substituted placeholder
-  // (`[REDACTED:…]`, emitted by an earlier value-masking rule such as
-  // apiKeyAssignment on `access_token=…`) is not re-matched and re-labelled as
-  // a session cookie. This keeps rule order hermetic and the pass idempotent.
+  // The value excludes `[` so a placeholder emitted by an earlier rule is not
+  // re-labelled as a session cookie.
   return new RegExp(`\\b(${name})=([^;\\s[]+)`, 'gi');
 }
 
 /**
- * Decide whether a digit run (optionally space/hyphen grouped) is a 13–19 digit
- * credit-card number. Used by the credit-card rule's `replace` to confirm the
- * digit count after the loose pattern matches, so a longer numeric id is never
- * partially masked.
+ * Confirms 13–19 digits after the loose match, so a longer numeric id is
+ * never partially masked.
  *
  * @param {string} candidate
  * @returns {boolean}
@@ -105,59 +53,31 @@ function isCreditCard(candidate) {
 }
 
 /**
- * Ordered redaction rules. Order matters:
- *   - the bearer-token rule runs before the cookie rule so an
- *     `Authorization: Bearer …` header is classified as a token rather than
- *     swept up by a broader cookie match;
- *   - the password and API-key rules run before the cookie rule so a
- *     `password=…` / `api_key=…` assignment is classified by its own
- *     placeholder rather than read as a session cookie;
- *   - the credit-card and SSN rules run before the email rule so a bare digit
- *     run is classified before the email pass; the email rule runs last so an
- *     address embedded in an already-redacted span is never re-scrubbed.
- *
- * Each `pattern` is a global `RegExp` (case-insensitive where the surrounding
- * keywords are alphabetic). The `replace` is a function so a rule can preserve
- * a non-secret prefix (the `Bearer ` keyword, the key name, the cookie name)
- * while masking only the secret value.
+ * Order matters: bearer, password and API-key rules precede the cookie rule
+ * so those assignments get their own placeholder; digit rules precede email;
+ * email runs last.
  *
  * @type {ReadonlyArray<{ name: string, pattern: RegExp, replace: (match: string, ...groups: string[]) => string }>}
  */
 const RULES = Object.freeze([
-  // Bearer tokens: `Bearer <token>` (RFC 6750 Authorization header value).
-  // Preserve the `Bearer ` keyword; mask the credential. The token charset
-  // covers base64url / JWT-style values (letters, digits, `-`, `_`, `.`, `+`,
-  // `/`, `=`). Require at least 8 chars so a literal word like "Bearer none"
-  // is not mistaken for a credential.
+  // ≥8 chars so "Bearer none" is not a credential.
   {
     name: 'bearer',
     pattern: /\b(Bearer)\s+([A-Za-z0-9\-._+/=]{8,})/gi,
     replace: (_match, keyword) => `${keyword} ${PLACEHOLDERS.bearer}`,
   },
-  // Passwords: a `password` / `passwd` / `pwd` assignment in the common
-  // shapes — `password=...`, `pwd: ...`, JSON `"password": "..."`. Preserve
-  // the key and the assignment punctuation (`=`, `:`, optional quotes); mask
-  // the value up to the next delimiter (`&`, `;`, `,`, whitespace, matching
-  // quote, or end of string). Requires a non-empty value so a bare
-  // `password=` is left alone.
   {
     name: 'password',
     pattern: /\b(passwd|password|pwd)(["']?\s*[:=]\s*)(["']?)([^"'&;,\s]+)\3/gi,
     replace: (_match, key, sep, quote) =>
       `${key}${sep}${quote}${PLACEHOLDERS.password}${quote}`,
   },
-  // API keys (provider-prefixed): Stripe / GitHub `<prefix>_<token>`,
-  // OpenAI/Anthropic `sk-<token>`, Google `AIza<token>`, AWS `AKIA<id>`.
-  // Masked whole.
   {
     name: 'apiKeyPrefixed',
     pattern:
       /\b(?:sk|pk|rk|ghp|gho|ghs|ghu|ghr)[-_][A-Za-z0-9][A-Za-z0-9_-]{10,}\b|\bAIza[A-Za-z0-9\-_]{20,}\b|\bAKIA[A-Z0-9]{16}\b/g,
     replace: () => PLACEHOLDERS.apiKey,
   },
-  // API keys (assignment form): `api_key=...`, `apikey: "..."`,
-  // `access-token=...`, `secret_key=...`. Preserve the key name; mask the
-  // value.
   {
     name: 'apiKeyAssignment',
     pattern:
@@ -165,35 +85,22 @@ const RULES = Object.freeze([
     replace: (_match, key, sep, quote) =>
       `${key}${sep}${quote}${PLACEHOLDERS.apiKey}${quote}`,
   },
-  // Session cookies: a cookie assignment whose name carries a session-secret
-  // word as a whole delimited segment (see SESSION_WORDS / buildCookiePattern).
-  // Preserve the cookie name and `=`; mask the value up to the next `;`,
-  // whitespace, or end of string.
   {
     name: 'cookie',
     pattern: buildCookiePattern(),
     replace: (_match, name) => `${name}=${PLACEHOLDERS.cookie}`,
   },
-  // Credit-card numbers (PANs): 13–19 digit runs, optionally grouped by single
-  // spaces or hyphens (`4111 1111 1111 1111`, `4111-1111-1111-1111`,
-  // `4111111111111111`). The loose pattern matches a digit/separator run; the
-  // `replace` confirms the 13–19 digit count before masking so a longer
-  // numeric id is never partially redacted. Bounded by non-digit edges.
   {
     name: 'creditCard',
     pattern: /(?<![\d-])\d(?:[ -]?\d){12,18}(?![\d-])/g,
     replace: (match) => (isCreditCard(match) ? PLACEHOLDERS.creditCard : match),
   },
-  // US Social Security Numbers: `NNN-NN-NNNN`. Masked whole. Hyphen-separated
-  // form only — a bare 9-digit run is intentionally not treated as an SSN to
-  // avoid clobbering benign numeric ids.
+  // Hyphenated form only; a bare 9-digit run is too often a benign id.
   {
     name: 'ssn',
     pattern: /\b\d{3}-\d{2}-\d{4}\b/g,
     replace: () => PLACEHOLDERS.ssn,
   },
-  // Email addresses (RFC 5322 pragmatic subset). Masked whole — the local
-  // part and domain are both PII.
   {
     name: 'email',
     pattern: /\b[A-Za-z0-9._%+-]+@[A-Za-z0-9.-]+\.[A-Za-z]{2,}\b/g,
@@ -202,20 +109,8 @@ const RULES = Object.freeze([
 ]);
 
 /**
- * Scrub the full security-baseline secret/PII taxonomy — bearer tokens,
- * passwords, API keys, session cookies, credit-card numbers, SSNs, and email
- * addresses — from an evidence string before it is persisted to disk or posted
- * to GitHub.
- *
- * Contract:
- * - Each matched secret/PII span is replaced by a rule-specific placeholder.
- * - The pass is **idempotent**: `redactEvidence(redactEvidence(s)) ===
- *   redactEvidence(s)` for all `s`, because placeholders match no rule.
- * - A string matching no rule is returned **unchanged** (referential
- *   identity is preserved for the no-match case).
- * - A non-string input is coerced defensively: `null`/`undefined` and
- *   non-string values return an empty string, so the redactor never throws on
- *   malformed evidence and never leaks a stringified secret-bearing object.
+ * Non-string input returns '' so a secret-bearing object is never
+ * stringified.
  *
  * @param {unknown} evidence Raw captured evidence text.
  * @returns {string} Redacted evidence (or the original string when no rule
@@ -227,9 +122,6 @@ export function redactEvidence(evidence) {
   }
   let result = evidence;
   for (const rule of RULES) {
-    // Reset lastIndex defensively — the shared global RegExp instances carry
-    // mutable state across calls, and `String.prototype.replace` resets it,
-    // but an explicit reset keeps each call hermetic and order-independent.
     rule.pattern.lastIndex = 0;
     result = result.replace(rule.pattern, rule.replace);
   }
@@ -237,9 +129,6 @@ export function redactEvidence(evidence) {
 }
 
 /**
- * The placeholder tokens this module substitutes, exported so callers (and
- * tests) can assert on them without hard-coding the literal strings.
- *
  * @type {Readonly<Record<string, string>>}
  */
 export const REDACTION_PLACEHOLDERS = PLACEHOLDERS;