mandrel 2.59.0 → 2.61.0

package/.agents/scripts/lib/audit-to-stories/parse-audit-md.js

@@ -1,30 +1,15 @@
 /**
- * lib/audit-to-stories/parse-audit-md.js — Parse `audit-*-results.md` reports.
- *
- * Extracts the `## Detailed Findings` section of an audit report and turns
- * every `### <title>` block into a normalised finding record. Every audit lens
- * report now shares one findings contract (Story #4625): a `Critical | High |
- * Medium | Low` severity scale, a mandated `Location:` path anchor, and a
- * dimension axis. Lenses still label the axes slightly differently — `Severity`
- * vs `Impact`, `Dimension` vs `Category` vs `Type` — so the parser captures
- * every key/value pair the block carries and normalises the two axes the
- * downstream pipeline relies on (severity + dimension), harvesting the
- * `Location:` field into `files[]` ahead of prose scraping.
- *
- * Pure: no filesystem I/O. The caller supplies the report text and source
- * path; the parser returns plain objects.
+ * Parse `## Detailed Findings` of audit reports into normalised findings.
+ * Pure.
  */
 
 import path from 'node:path';
 
 import { normalizeSeverity } from '../findings/severity.js';
 
-// A lens writes its field bullets either way round — `- **Severity:** High`
-// (colon inside the bold run) or `- **Severity**: High` (colon outside it).
-// Accepting only the first silently dropped the axis of every finding written
-// the second way: it parsed as prose, so the block carried no severity, and the
-// grouping-header rule below then read the whole finding as an organisational
-// heading. Both spellings are the same field.
+// Accept the colon inside or outside the bold run (`**Severity:**` and
+// `**Severity**:`); missing either drops the axis and misreads the finding as a
+// grouping header.
 const KEY_LINE = /^\s*-\s*\*\*([^:*]+?)\s*(?::\*\*|\*\*\s*:)\s*(.*)$/;
 const HEADING_FINDING = /^(#{3,4})\s+(.+?)\s*$/;
 const SEVERITY_KEY_LINE =
@@ -49,22 +34,9 @@ function unwrapInlineCode(value) {
 }
 
 /**
- * Resolve a raw severity/impact token to a canonical level, or `null` when the
- * token carries no recognisable severity at all.
- *
- * The vocabulary itself is NOT written down here (Story #4877). This module used
- * to carry its own alias table covering `critical|high|medium|mod|moderate|low`
- * — four of the canonical five levels, missing `info`. A lens that graded a
- * finding `Info` or `Informational` (which the shared severity scale now
- * sanctions) therefore parsed to `null`, tallied as `unknown`, and was dropped
- * by every severity-filtered run, `--severity low` included. Delegating to the
- * canonical normaliser in `lib/findings/severity.js` means this parser cannot
- * know a narrower vocabulary than the rest of the pipeline.
- *
- * `null` — rather than the normaliser's `info` fallback — remains the
- * no-severity answer, because {@link deriveSeverity} walks several candidate
- * keys and needs to distinguish "this key had no severity" from "this key said
- * `info`".
+ * Delegates to the canonical normaliser so this parser never knows a narrower
+ * vocabulary than the pipeline. Returns `null` (not `info`) for no severity,
+ * so {@link deriveSeverity} can tell "no severity" from "said `info`".
  *
  * @param {unknown} token
  * @returns {string|null}
@@ -98,36 +70,13 @@ function deriveDimension(fields, fallbackDimension) {
 }
 
 /**
- * Harvest the mandated `Location:` field into concrete file paths. Every
- * non-retired lens template now carries a `- **Location:** <path>:<line>`
- * bullet (Story #4625); extracting it here — ahead of the heuristic prose
- * scrape — gives a finding a deterministic identity anchor instead of relying
- * on whatever path text happens to appear in the prose. The value may wrap the
- * path in backticks and/or append a `:line` (or `:line:col`) suffix; both are
- * stripped. Only tokens that look like paths (containing a separator) survive.
+ * Repo-relative path, or `null` for an absolute (outside `repoRoot`) or
+ * degenerate token. A bare root-level file (`AGENTS.md`) is accepted in
+ * structured fields; `requireSeparator` rejects it in prose, where it is more
+ * likely a word.
  *
- * @param {Record<string, string>} fields
- * @returns {string[]}
- */
-/**
- * Normalise a raw path token to a repo-relative path, or `null` when the
- * token is not a usable file reference.
- *
- * Three shapes historically leaked through and poisoned grouping downstream:
- * an **absolute** path (which can never match a repo-relative group key), a
- * **degenerate** token such as a bare `/`, and — most damagingly — a
- * **root-level** file such as `AGENTS.md`, which the old slash-only guard
- * discarded outright even when it was the finding's explicit `Location:`.
- *
- * `requireSeparator` is what keeps that third fix from over-reaching. In the
- * **structured** fields — the title anchor and `Location:` — a bare
- * `AGENTS.md` is unambiguously a file, so the separator is not required. In
- * free **prose**, a bare `description.md` is far more likely to be a word than
- * a path, so the separator stays mandatory there.
- *
- * @param {string} raw — the token as it appeared in the report.
- * @param {string} [repoRoot] — absolute repo root; absolute tokens beneath it
- *   are relativised. Omitted (the pure default) leaves absolutes to be dropped.
+ * @param {string} raw
+ * @param {string} [repoRoot] Absolute tokens beneath it are relativised.
  * @param {{ requireSeparator?: boolean }} [options]
  * @returns {string|null}
  */
@@ -151,8 +100,7 @@ function normalisePathToken(raw, repoRoot, { requireSeparator = false } = {}) {
       }
     }
   }
-  // A path that is still absolute lives outside the repo — it can never be a
-  // valid group key, so drop it rather than let it become one.
+  // Still absolute ⇒ outside the repo; never a valid group key.
   if (out.startsWith('/') || out.startsWith('\\') || /^[A-Za-z]:/.test(out)) {
     return null;
   }
@@ -163,10 +111,8 @@ function normalisePathToken(raw, repoRoot, { requireSeparator = false } = {}) {
 }
 
 /**
- * The finding-block skeleton mandates that a title lead with the primary file
- * the finding lives in (``### `path/to/file.ext` — title``). That anchor is
- * the most reliable primary-file signal a block carries, so it seeds `files[]`
- * ahead of `Location:` and prose scraping — `pickPrimaryFile` takes `files[0]`.
+ * The mandated title anchor (``### `path` — title``) is the strongest
+ * primary-file signal, so it seeds `files[0]` ahead of `Location:` and prose.
  */
 function deriveTitleFile(title, repoRoot) {
   const match = TITLE_ANCHOR.exec(typeof title === 'string' ? title : '');
@@ -175,6 +121,12 @@ function deriveTitleFile(title, repoRoot) {
   return normalised ? [normalised] : [];
 }
 
+/**
+ * `Location:` paths with `:line` suffixes and backticks stripped.
+ *
+ * @param {Record<string, string>} fields
+ * @returns {string[]}
+ */
 function deriveLocationFiles(fields, repoRoot) {
   const raw = fields.location;
   if (typeof raw !== 'string' || raw.trim().length === 0) return [];
@@ -265,10 +217,6 @@ function splitFindingBlocks(reportText) {
 }
 
 /**
- * Does this block carry the axis line that makes it a finding rather than a
- * section header? The skeleton mandates `Severity` (or its `Impact` alias), so
- * its absence is the signal that a heading is organisational.
- *
  * @param {{ bodyLines: string[] }} block
  * @returns {boolean}
  */
@@ -277,12 +225,6 @@ function carriesSeverity(block) {
 }
 
 /**
- * Does this block carry any `- **Key:** value` field bullet at all? A finding
- * block is a field record; a grouping header is a heading with prose (or
- * nothing) under it. Read together with {@link carriesSeverity} this is what
- * lets an axis-less heading be recognised as organisational **without** having
- * to see `####` children under it.
- *
  * @param {{ bodyLines: string[] }} block
  * @returns {boolean}
  */
@@ -291,10 +233,8 @@ function carriesFieldBullet(block) {
 }
 
 /**
- * A block that declares nothing: no severity axis and no field bullets. A
- * `### Robust` header whose whole body is `_No findings._` is the canonical
- * case — it used to parse as a severity-less finding with no files and no
- * recommendation, which an unattended sweep then filed as an empty Story.
+ * No severity and no field bullets (e.g. a header over `_No findings._`) —
+ * never a finding, or an unattended sweep files an empty Story.
  *
  * @param {{ bodyLines: string[] }} block
  * @returns {boolean}
@@ -304,29 +244,10 @@ function isEmptyBlock(block) {
 }
 
 /**
- * Decide whether a `###` block is a **grouping header** rather than a finding,
- * reading its **whole subtree** — its own body and its `####` children.
- *
- * Several lenses nest their findings one level deeper: a `###` per dimension
- * (`### Perceivable`), each holding `####` finding blocks. Read flat, that
- * report parsed as one severity-less finding per dimension, and the unattended
- * sweep filed those empties. The subtree rule this applies, in order:
- *
- *   1. A block whose own body carries the severity axis **or any field
- *      bullet** is a finding. Its `####` sub-sections fold back into its body
- *      rather than splitting into phantom findings, so flat reports parse
- *      exactly as before.
- *   2. A block whose title leads with a backticked path — the anchor the
- *      finding-block skeleton mandates — is a finding even when its own body
- *      is empty, because its fields live under a `#### Evidence`-style
- *      sub-section. Folding is what stops that sub-section's heading from
- *      becoming the finding's title.
- *   3. Otherwise it is a grouping header when its children look like findings:
- *      any child carrying its own path anchor, or more than one child carrying
- *      the severity axis. A **single** axis-bearing child under an anchorless
- *      header is the `#### Evidence` shape again, so it folds.
- *   4. A block with no children at all and nothing declared is a grouping
- *      header (or a stray heading) either way — it yields no finding.
+ * Is a `###` block a grouping header over `####` findings? Not if it declares
+ * fields or leads with a path anchor (its `#### Evidence` children fold in).
+ * Otherwise yes when it has no children, any anchored child, or more than one
+ * severity-bearing child; a single such child is the Evidence shape and folds.
  *
  * @param {{ title: string, bodyLines: string[] }} parent
  * @param {Array<{ title: string, bodyLines: string[] }>} children
@@ -341,10 +262,6 @@ function isGroupingHeader(parent, children) {
 }
 
 /**
- * Fold the flat heading stream into findings: emit a grouping header's
- * children, fold a finding's sub-sections into its own body, and drop every
- * block that declares nothing.
- *
  * @param {Array<{ level: number, title: string, bodyLines: string[] }>} blocks
  * @returns {Array<{ level: number, title: string, bodyLines: string[] }>}
  */
@@ -383,11 +300,6 @@ function foldGroupingHeaders(blocks) {
 }
 
 /**
- * Slice the `## Executive Summary` section out of a report, or `null` when the
- * report declares none. The tally the cross-check trusts is the one the report
- * envelope mandates *there*; a `Severity tally:` string anywhere else is prose
- * quoting the format, not a declaration.
- *
  * @param {string} markdown
  * @returns {{ start: number, end: number }|null} character offsets.
  */
@@ -403,22 +315,12 @@ function executiveSummaryRange(markdown) {
 }
 
 /**
- * Read every `Severity tally:` line the report carries, scoped to its
- * Executive Summary and failing closed on more than one.
- *
- * The tally is what lets a consumer cross-check what the lens says it found
- * against what the parser actually extracted — a parse that silently drops
- * findings is otherwise indistinguishable from a clean report. That only holds
- * while exactly one line claims to be the tally. A report whose prose quotes
- * the format a second time (a remediation section restating a lens's output,
- * say) used to have whichever line the regex reached first silently adopted as
- * the declaration, so the cross-check compared the parse against an arbitrary
- * one of two numbers. Both are now reported and the report fails.
+ * The declared severity tally, for cross-checking the parse against what the
+ * lens says it found. Fails closed (`duplicate`) on more than one tally line,
+ * since adopting either would make the cross-check arbitrary. `Info` is never
+ * counted.
  *
- * `Info` is never counted (the severity scale already excludes it from
- * scheduled work).
- *
- * @param {string} markdown — full report text.
+ * @param {string} markdown
  * @returns {{ tally: {critical:number,high:number,medium:number,low:number}|null,
  *   matches: string[], duplicate: boolean }}
  */
@@ -430,8 +332,6 @@ export function readSeverityTally(markdown) {
   const matches = [];
   TALLY_LINE_GLOBAL.lastIndex = 0;
   for (const hit of markdown.matchAll(TALLY_LINE_GLOBAL)) {
-    // Outside an Executive Summary the whole document is the scope; with one,
-    // a line beyond it is a stray that must not be adopted silently.
     matches.push({ text: hit[0].trim(), groups: hit, index: hit.index });
   }
   const scoped = range
@@ -483,14 +383,9 @@ function parseBlockFields(bodyLines) {
 }
 
 /**
- * Parse a single audit report's markdown text into a list of normalised
- * findings.
- *
  * @param {object} params
- * @param {string} params.markdown — full report text.
- * @param {string} params.sourceReport — path used for `sourceReport` field
- *   and dimension inference when the report omits a `Dimension:` / `Category:`
- *   / `Type:` line.
+ * @param {string} params.markdown
+ * @param {string} params.sourceReport Also the fallback dimension source.
  * @returns {Array<{
  *   dimension: string,
  *   severity: 'critical'|'high'|'medium'|'low'|null,
@@ -547,13 +442,10 @@ export function parseAuditReport({ markdown, sourceReport, repoRoot }) {
 }
 
 /**
- * Parse N audit reports and return a flat findings array. Reports without a
- * `## Detailed Findings` section yield zero entries rather than throwing —
- * an audit can legitimately come back empty.
+ * A report without `## Detailed Findings` yields no entries (legitimately empty).
  *
  * @param {Array<{ markdown: string, sourceReport: string }>} reports
- * @param {{ repoRoot?: string }} [options] — `repoRoot` relativises absolute
- *   paths quoted in a report so they can match repo-relative group keys.
+ * @param {{ repoRoot?: string }} [options]
  * @returns {Array<ReturnType<typeof parseAuditReport>[number]>}
  */
 export function parseAuditReports(reports, { repoRoot } = {}) {

package/.agents/scripts/lib/audit-to-stories/seed-from-findings.js

@@ -1,20 +1,6 @@
 /**
- * lib/audit-to-stories/seed-from-findings.js
- *
- * Build the `/mandrel-plan --seed`-shaped one-pager markdown that the audit-to-
- * stories Single-plan grouping path emits for `/mandrel-plan` to consume.
- *
- * The seed renders the canonical one-pager sections so the authoring
- * pass can sharpen it without having to invent context:
- *   - Problem Statement (aggregated severity profile)
- *   - Recommended Direction (rollup of recommendations by dimension)
- *   - Key Assumptions (carries the source-report links forward)
- *   - MVP Scope (the findings themselves, flat — Story #5332)
- *   - Key Files (explicit file paths so `/mandrel-plan` authoring has concrete
- *     anchors)
- *   - Not Doing (out-of-scope items by convention)
- *
- * Pure: returns a string. The caller decides where to persist it.
+ * Render the `/mandrel-plan --seed` one-pager for the single-plan audit path.
+ * Pure: returns a string.
  */
 
 import { SEVERITIES } from '../findings/severity.js';
@@ -39,12 +25,6 @@ const DIMENSION_LABEL = {
   architecture: 'Architecture',
 };
 
-/**
- * The severity profile in the seed's Problem Statement is ordered and bucketed
- * by the canonical scale (Story #4877) rather than by a fourth local copy of
- * it. The list this replaces omitted `info`, so an informational finding was
- * absent from the profile the planner reads even when it survived the filter.
- */
 const SEVERITY_ORDER = SEVERITIES;
 
 function tallySeverities(findings) {
@@ -93,15 +73,8 @@ function formatRecommendedDirection(findings) {
 }
 
 /**
- * The findings, flat (Story #5332).
- *
- * This section used to render one numbered bullet per `groupFindings` group
- * under a `## Grouping` directive — a partition the seed had already decided
- * before the planner read a word of it, and at a grain (`groupFindings`'s) the
- * planner's cohesion judgment never got to review. The measured result was a
- * sweep of 44 findings arriving as 18 Stories. The seed now states what was
- * found and lets N reach the planner undecided; container grouping is Gate
- * #3's call at persist, where N is known.
+ * Flat, not grouped: the seed must not pre-decide the Story partition; that
+ * is the planner's cohesion call.
  *
  * @param {object[]} findings
  * @returns {string}
@@ -118,17 +91,9 @@ function formatFindingsList(findings) {
 }
 
 /**
- * The machine-readable dedup identity, one footer set per group.
- *
- * Deliberately **not** folded into one footer over the whole sweep, and
- * deliberately not attached to a visible bullet. Each group's fingerprint and
- * location-based semantic-key footers are the identity the next sweep matches
- * on (Story #4626), and the `audit::*` labels are the reason it ever looks at
- * the issue at all — an indexed sweep answers exact lookups from the labelled
- * pool without reaching the provider, so a Story missing the labels is
- * invisible however good its fingerprints (Story #5307). They are HTML
- * comments, so they carry no partition to the planner's eye while staying
- * byte-identical to what the standalone-Stories path emits.
+ * Per-group dedup footers (fingerprint, semantic key, `audit::*` labels) as
+ * HTML comments: invisible to the planner, byte-identical to the standalone
+ * path. Without the labels an indexed sweep never sees the Story.
  *
  * @param {object[]} groups
  * @returns {string}

package/.agents/scripts/lib/audit-to-stories/wire-dependencies.js

@@ -1,30 +1,6 @@
 /**
- * lib/audit-to-stories/wire-dependencies.js — turn a standalone audit cohort's
- * detected group edges into declared ordering, once the issues exist.
- *
- * `groupFindings` detects `edges[]` between finding groups, but at emit time
- * the groups have no issue numbers, so the ordering could only be rendered as
- * prose. Every standalone audit Story therefore shipped with `depends_on: []`,
- * and what actually kept a cohort from being co-dispatched onto colliding
- * branches was an **accident**: siblings shared the sweep-wide audit provenance
- * footers `plan-persist` stamps, and the delivery footprint guard scraped
- * path-shaped tokens out of them. Story #5044 narrows that scrape, which is why
- * this module lands with it — removing the accidental serializer without giving
- * the cohort a real one would leave it less ordered than before.
- *
- * The shape is `plan-persist`'s two-pass crossing (`plan-persist/story-ops.js`),
- * because it is the same problem: **create every issue first, then mirror the
- * edges**. Both halves are written:
- *
- *   1. The **body footer** (`---` / `blocked by #N`) — canonical, parsed by
- *      `/mandrel-deliver`'s resolver, and the fallback when the dependencies API is
- *      unavailable.
- *   2. The **native `blocked_by` relation** — visible in the GitHub UI,
- *      readable without parsing markdown, and settable by an operator later.
- *
- * Native mirroring is **non-fatal by design**, matching `plan-persist`: the
- * footer has already been written by the time it runs, so a dependencies API
- * that says no costs visibility, not ordering.
+ * Turn a created audit cohort's group edges into `blocked by #N` footers plus
+ * a native `blocked_by` mirror (non-fatal: the footer already orders).
  *
  * @module lib/audit-to-stories/wire-dependencies
  */
@@ -34,25 +10,15 @@ import { Logger } from '../Logger.js';
 import { buildStoryBody } from './build-story-body.js';
 
 /**
- * Re-render each created Story's body with its blockers resolved to `#N`, and
- * mirror the same edges as native `blocked_by` relations.
- *
- * Groups whose issue was not created — deduped against an existing Issue,
- * suppressed by the ledger, or simply not in `issueByGroupKey` — are skipped
- * rather than guessed at, and an edge pointing at one drops with them
- * (`dependencyRefs` filters it). A `blocked by #undefined` would gate a Story
- * on nothing forever, which is strictly worse than the un-ordered cohort this
- * replaces.
+ * Groups (and edges to groups) with no created issue are skipped: a
+ * `blocked by #undefined` would gate a Story on nothing forever.
  *
  * @param {object} args
- * @param {Array<object>} args.groups          The `create`-eligible groups, in
- *   the order their issues were opened.
+ * @param {Array<object>} args.groups          The `create`-eligible groups.
  * @param {Array<{ fromGroupKey: string, toGroupKey: string }>} [args.edges]
  * @param {Record<string, number>} args.issueByGroupKey  Group key → issue number.
  * @param {(issueNumber: number, body: string) => Promise<unknown>} args.updateBody
- *   Persist a re-rendered body. Injected so the caller owns the provider call.
- * @param {object|null} [args.provider] Provider for native edge mirroring.
- *   Omit (or pass one without the dependency ports) to write footers only.
+ * @param {object|null} [args.provider] Omit to write footers only.
  * @returns {Promise<{
  *   storiesWired: number,
  *   bodiesUpdated: number,
@@ -92,13 +58,7 @@ export async function wireAuditStoryEdges({
 }
 
 /**
- * Re-render every group that both has an issue **and** has at least one blocker
- * whose issue also exists.
- *
- * A group with no resolvable blocker is deliberately left alone rather than
- * rewritten to an identical body: an issue-body update is a mutation and a
- * notification, and doing it for a no-op edit is noise on every Story of every
- * sweep.
+ * Only groups with a resolvable blocker: a no-op body update still notifies.
  *
  * @param {object} args
  * @returns {Array<{ groupKey: string, issueNumber: number, body: string, blockerKeys: string[] }>}
@@ -124,13 +84,8 @@ function collectWiredStories({ groups, edges, issueByGroupKey }) {
 }
 
 /**
- * Mirror the declared edges as native GitHub `blocked_by` relations.
- *
- * Two shape hazards this crossing inherits from `plan-persist`, both silent if
- * missed: `applyBlockedByDependencies` indexes `slugToIssueNumber` with plain
- * property access (so it must be a plain object, never a `Map` — a `Map` yields
- * `undefined` for every lookup, skips every edge, and reports success having
- * written nothing), and it reads `dependsOn`, not `depends_on`.
+ * Silent hazards: `slugToIssueNumber` must be a plain object (a `Map` skips
+ * every edge and reports success), and the helper reads `dependsOn`.
  *
  * @param {object} args
  * @returns {Promise<{ edgesAdded: number, edgesSkipped: number, edgesFailed: number }|null>}
@@ -151,9 +106,7 @@ async function mirrorNativeEdges({ provider, wired, issueByGroupKey }) {
   try {
     const { gh, owner, repo } = provider.getDependencyWriteContext();
     const summary = await applyBlockedByDependencies({
-      // The group key IS the slug here — it is the stable identifier both
-      // sides of an edge are keyed by — so `issueByGroupKey` is already the
-      // slug→number map the helper wants.
+      // The group key is the slug, so `issueByGroupKey` is the slug map.
       stories: wired.map((s) => ({
         slug: s.groupKey,
         dependsOn: s.blockerKeys,

package/.agents/scripts/lib/baseline-loader.js

@@ -1,76 +1,37 @@
 import { createGitInterface } from './git-utils.js';
 
 /**
- * baseline-loader.js — read a JSON baseline file at an arbitrary git ref.
- *
- * Story #1120 (Tech Spec #902) moved close-validation gate execution into the
- * Story worktree and wants every gate to compare against the baseline as it
- * exists on `epic/<id>` HEAD, not against whatever `baselines/*.json` happens
- * to be on the main checkout's working tree at close time. This helper is
- * the single seam every gate uses to do that — it shells out to
- * `git show <ref>:<path>`, parses the JSON, and memoizes the parsed object
- * in an in-process Map keyed by `${ref}:${path}` so a single close run
- * never re-spawns `git show` for the same (ref, path) pair.
- *
- * Caching contract:
- *   - The cache lives on the module — one instance per Node process. A
- *     close run is short-lived enough that staleness across invocations is
- *     not a concern (the next close re-imports the module).
- *   - Tests can call `clearBaselineCache()` to reset between cases. Real
- *     callers never need to.
- *
- * Failure modes:
- *   - Unresolvable ref / missing path → throws `Error` whose message names
- *     the ref AND the path so operators can act without scraping the
- *     stderr blob underneath.
- *   - `git show` succeeds but stdout is not parseable JSON → throws an
- *     Error tagged `parse-error` that names the ref + path.
- *   - The cache stores the parsed object on success; failures are NOT
- *     cached so a transient git failure doesn't poison subsequent calls.
+ * Read a JSON baseline at a git ref (`git show <ref>:<path>`), so gates
+ * compare against the committed baseline rather than the working tree.
+ * Memoized per process; failures are not cached, so a transient git error
+ * cannot poison later calls.
  */
 
 const _cache = new Map();
 
 /**
- * Build the cache key. Exported for tests that want to assert exact key
- * collisions (different refs vs. different paths must never collide).
- *
  * @param {string} ref
  * @param {string} path
  * @returns {string}
  */
 export function cacheKeyFor(ref, path) {
-  // `\u0000` is a control character that cannot legally appear in either a
-  // git ref name (per `git check-ref-format`) or a POSIX path component, so
-  // using it as the structural separator guarantees no collision between
-  // (ref="a", path="b:c") and (ref="a:b", path="c"). Tests assert this.
+  // NUL is legal in neither a ref nor a path, so keys cannot collide.
   return `${ref}\u0000${path}`;
 }
 
-/**
- * Reset the in-process cache. Tests use this to keep cases independent.
- * Production callers never need to call it.
- */
+/** Test-only cache reset. */
 export function clearBaselineCache() {
   _cache.clear();
 }
 
 /**
- * Read the JSON baseline at `path` as it exists at the git `ref`.
- *
- * @param {string} ref           Git ref (e.g. `epic/1114`, `HEAD`).
- * @param {string} path          Repo-relative path (e.g. `baselines/maintainability.json`).
+ * @param {string} ref
+ * @param {string} path Repo-relative.
  * @param {object} [opts]
- * @param {string} [opts.cwd]    Working directory for `git show`. Defaults to
- *                               `process.cwd()`. Must be a real git workdir.
- * @param {ReturnType<typeof createGitInterface>} [opts.git] Injected git
- *                               interface — production callers omit this;
- *                               tests pass a mock.
- * @returns {unknown} Parsed JSON value (`object` for baseline shapes; the
- *   helper does not constrain the schema — that contract belongs to the
- *   caller, e.g. `getBaseline` for the maintainability shape).
- * @throws {Error} When the ref/path is unresolvable or the blob is not
- *   parseable JSON. The cache is NOT populated on failure.
+ * @param {string} [opts.cwd]
+ * @param {ReturnType<typeof createGitInterface>} [opts.git]
+ * @returns {unknown} Parsed JSON; the schema is the caller's contract.
+ * @throws {Error} Naming ref and path, on an unresolvable blob or bad JSON.
  */
 export function readBaselineAtRef(ref, path, opts = {}) {
   if (typeof ref !== 'string' || ref.length === 0) {

package/.agents/scripts/lib/baseline-schema-registry.js

@@ -1,16 +1,6 @@
-// ---------------------------------------------------------------------------
-// Canonical baseline schema registry (Story #1888).
-//
-// The shared envelope schema and the eight per-kind row/rollup schemas live
-// under .agents/schemas/baselines/. Consumers compile them through a single
-// AJV instance so cross-references (per-kind schemas `allOf` the envelope)
-// resolve without each callsite re-registering the envelope.
-//
-// `BASELINE_SCHEMA_FILES` is the source of truth for the registered set —
-// the mirror-drift test reads it back and compares against the on-disk
-// directory listing to catch a new schema landing under baselines/ without
-// being registered here.
-// ---------------------------------------------------------------------------
+// Baseline schema registry: one AJV instance, so per-kind schemas' `allOf`
+// envelope references resolve. `BASELINE_SCHEMA_FILES` must match the
+// on-disk listing (a mirror-drift test enforces it).
 
 import { readFileSync } from 'node:fs';
 import path from 'node:path';
@@ -35,24 +25,17 @@ export const BASELINE_ENVELOPE_FILE = 'baseline-envelope.schema.json';
 
 /** Per-kind baseline schema filenames in stable registration order. */
 export const BASELINE_KIND_SCHEMA_FILES = Object.freeze([
-  'lint.schema.json',
   'coverage.schema.json',
   'crap.schema.json',
   'maintainability.schema.json',
   'mutation.schema.json',
-  'lighthouse.schema.json',
   'bundle-size.schema.json',
   'duplication.schema.json',
 ]);
 
 /**
- * Report schemas that live under `.agents/schemas/baselines/` but describe
- * an *engine's output about* the baselines rather than a committed baseline
- * (Story #4902). They are registered here for two reasons: the AJV instance
- * below is the one place a caller can compile a baselines-directory schema
- * without re-registering the envelope, and the mirror-drift test compares
- * this registry against the on-disk listing — an unregistered file there is
- * drift regardless of which category it belongs to.
+ * Schemas for engine reports about baselines, not baselines themselves;
+ * registered because every file in the directory must be.
  */
 const BASELINE_REPORT_SCHEMA_FILES = ['audit-baselines-envelope.schema.json'];
 

package/.agents/scripts/lib/baselines/component-matcher.js

@@ -1,18 +1,9 @@
 /**
- * component-matcher.js — shared helper for matching a row's key (path or
- * route) against a components-registry entry's `includes` prefix.
- *
- * Hoisted out of six baseline-kind modules (coverage, crap, lint,
- * maintainability, mutation, lighthouse) which all shipped byte-equivalent
- * copies of this predicate. See Story #2464.
+ * Identity or prefix-with-slash match of a row key against a component's
+ * `includes`.
  *
  * @param {{ includes?: string } | null | undefined} component
- *   A components-registry entry. Treated as non-matching when nullish or
- *   when `includes` is not a string.
- * @param {string} p
- *   The row's key field — `path` for code-shaped rows or `route` for
- *   lighthouse-shaped rows. The matcher is identity-equal or
- *   prefix-with-slash; callers normalize the row shape before invoking.
+ * @param {string} p Row key: `path`, or `route` for lighthouse.
  * @returns {boolean}
  */
 export function componentMatches(component, p) {