mandrel 2.59.0 → 2.61.0

package/.agents/scripts/lib/audit-suite/substitutions.js

@@ -1,36 +1,16 @@
 /**
- * lib/audit-suite/substitutions.js — `{{key}}` template substitution helpers.
- *
- * Extracted from `.agents/scripts/run-audit-suite.js` (Story #963, Epic #946).
- *
- * Three concerns live here:
- *   1. `applySubstitutions` — pure string templating used on each workflow body.
- *   2. `parseSubstitutionPairs` / `applyImplicitSubstitutions` — CLI-side glue
- *      that turns `--substitution key=value` pairs and `--ticket` / `--base-branch`
- *      flags into the substitutions map the runner consumes.
- *   3. `computeAllowedKeys` — the per-run allow-list (built-ins ∪ rule-declared
- *      keys) used by the runner to reject unknown caller substitutions before
- *      any workflow is loaded.
- *
- * No filesystem, no provider, no validation throws beyond `parseSubstitutionPairs`
- * (which is defensive against malformed CLI input).
+ * `{{key}}` substitution for audit workflow bodies, plus the CLI glue and the
+ * per-run allowed-key set.
  */
 
 import { ValidationError } from '../errors/index.js';
 
-/**
- * Built-in substitution keys that are always available regardless of which
- * audits are requested. `auditOutputDir` is sourced from the resolved paths;
- * `ticketId` and `baseBranch` are populated from CLI flags or caller args.
- */
 export const BUILT_IN_SUBSTITUTION_KEYS = Object.freeze([
   'auditOutputDir',
   'ticketId',
   'baseBranch',
-  // Newline-joined change-set file list, populated by Epic-mode callers
-  // (e.g. `epic-audit`) from `selectAudits().context.changedFiles`.
-  // Absent in manual `/audit-*` invocations — lens templates handle the
-  // unsubstituted literal as "no scope filter".
+  // Newline-joined change set; when unsubstituted, lens templates read the
+  // literal as "no scope filter".
   'changedFiles',
 ]);
 
@@ -39,10 +19,7 @@ function escapeRegExp(str) {
 }
 
 /**
- * Pure: replace every occurrence of `{{key}}` in `content` with the matching
- * value from `substitutions`. Keys are escaped for regex safety. Unrecognised
- * placeholders are left intact — validation of the substitution map happens
- * upstream in {@link computeAllowedKeys}.
+ * Unrecognised placeholders are left intact; keys are validated upstream.
  *
  * @param {string} content
  * @param {Record<string, string>} substitutions
@@ -60,8 +37,7 @@ export function applySubstitutions(content, substitutions) {
 }
 
 /**
- * Parse repeated `--substitution key=value` CLI pairs into a flat object.
- * Throws {@link ValidationError} on malformed entries (missing `=` or empty key).
+ * Throws {@link ValidationError} on a missing `=` or empty key.
  *
  * @param {string[]} [pairs]
  * @returns {Record<string, string>}
@@ -84,13 +60,11 @@ export function parseSubstitutionPairs(pairs = []) {
 }
 
 /**
- * Mutate `substitutions` in place to fold in CLI-derived defaults that should
- * only override when the operator hasn't already supplied them via
- * `--substitution`. Pulled out of `main` so the precedence rules can be
- * unit-tested without the CLI layer.
+ * Fill `ticketId`/`baseBranch` from flags in place, unless an explicit
+ * `--substitution` already set them.
  *
- * @param {Record<string, unknown>} values parsed CLI values
- * @param {Record<string, string|undefined>} substitutions mutable map
+ * @param {Record<string, unknown>} values
+ * @param {Record<string, string|undefined>} substitutions
  */
 export function applyImplicitSubstitutions(values, substitutions) {
   if (values.ticket && substitutions.ticketId === undefined) {
@@ -102,10 +76,8 @@ export function applyImplicitSubstitutions(values, substitutions) {
 }
 
 /**
- * Aggregate the allowed substitution key set for a run: built-ins plus
- * per-audit declared keys across the requested auditWorkflows. Audits that
- * are not registered in rules are ignored here — the runner rejects them with
- * a findings entry before substitution matters.
+ * Built-ins plus each requested audit's declared keys; unregistered audits
+ * are rejected elsewhere.
  *
  * @param {{ audits?: Record<string, { substitutionKeys?: string[] }> }} rules
  * @param {string[]} auditWorkflows

package/.agents/scripts/lib/audit-suite/workflow-loader.js

@@ -1,21 +1,13 @@
 /**
- * lib/audit-suite/workflow-loader.js — Filesystem IO for audit workflows.
- *
- * Extracted from `.agents/scripts/run-audit-suite.js` (Story #963, Epic #946).
- *
- * The runner injects either {@link loadWorkflow} (production) or a stub (tests)
- * via `injectedLoadWorkflow`. Same for {@link defaultWriteArtifact} and
- * `injectedWriteArtifact`. Keeping the IO bound here lets the runner module
- * stay free of `node:fs` imports and stay easy to unit-test.
+ * Filesystem IO for audit workflows, kept out of the runner so tests can
+ * inject stubs.
  */
 
 import fs from 'node:fs/promises';
 import path from 'node:path';
 
 /**
- * Read an audit workflow markdown file. Returns `null` when the file is
- * missing — the runner converts that into a `low`-severity finding rather
- * than throwing, so a missing workflow doesn't fail the suite.
+ * `null` when missing; the runner records a finding rather than failing.
  *
  * @param {string} auditName
  * @param {string} workflowsDir absolute path to the workflows root
@@ -32,10 +24,6 @@ export async function loadWorkflow(auditName, workflowsDir) {
 }
 
 /**
- * Default artifact writer used when the caller passes a `--run-id` /
- * `artifactPrefix`. Creates the artifacts dir on demand and returns the
- * absolute path of the file written.
- *
  * @param {string} artifactsDir
  * @param {string} fileName
  * @param {string} content

package/.agents/scripts/lib/audit-to-stories/audit-label-taxonomy.js

@@ -1,29 +1,7 @@
 /**
- * lib/audit-to-stories/audit-label-taxonomy.js — the closed set of GitHub
- * labels an audit sweep may create or generate (Story #4877).
- *
- * There are two sides to a label axis and they used to be written down in
- * different places, which is how they drifted:
- *
- *   - the **creator** — `audit-labels-bootstrap.js`, which ran `gh label create`
- *     over the `audit::<lens>` list and nothing else;
- *   - the **generator** — `audit-to-stories/build-story-body.js`, which emitted
- *     `type::story`, `audit::<lens>` and — as a bare string literal —
- *     `risk::high`.
- *
- * `risk::high` was therefore generated by the filer and defined by **no**
- * taxonomy: not `LABEL_TAXONOMY` (the repo-wide bootstrap), not the audit
- * bootstrap. A generated label the repository has never created is the exact
- * failure shape that made every `gh issue create` in the feedback loop fail in
- * Story #4828. This module is the one list both sides read, so the creator
- * cannot fall behind the generator again.
- *
- * It lives under `lib/` rather than inside the bootstrap CLI so the generator
- * can import it without a lib → top-level-script edge (and without dragging the
- * CLI's config/`gh` dependencies into a pure body builder).
- *
- * Label *names* come from `lib/label-constants.js` — the repo-wide SSOT for
- * label spelling — so a rename still lands in one place.
+ * The closed set of labels an audit sweep may create or generate — the one
+ * list both the bootstrap (creator) and the Story-body builder (generator)
+ * read, so the creator cannot fall behind the generator.
  */
 
 import { auditLabelFooter } from '../findings/route-finding.js';
@@ -35,12 +13,7 @@ import {
 } from '../label-constants.js';
 import { AUDIT_LENSES, auditLabelsForFindings } from './audit-lenses.js';
 
-/**
- * Per-lens label presentation, keyed by canonical lens name. A lens absent from
- * this map falls back to {@link DEFAULT_LENS_META}, so adding an `audit-*`
- * workflow to `AUDIT_LENSES` still yields a label without registering
- * colour/description here first.
- */
+/** A lens absent here falls back to {@link DEFAULT_LENS_META}. */
 const LENS_META = Object.freeze({
   accessibility: {
     color: 'c5def5',
@@ -110,11 +83,7 @@ function hex(color) {
   return String(color).replace('#', '');
 }
 
-/**
- * The `audit::<lens>` half of the taxonomy, one per `/audit-<lens>` workflow.
- * Derived from the same `AUDIT_LENSES` SSOT that `build-story-body.js` derives
- * its labels from, so the creator and the deriver cannot drift (Story #4195).
- */
+/** Derived from the same `AUDIT_LENSES` SSOT the generator uses. */
 const AUDIT_LENS_LABELS = Object.freeze(
   AUDIT_LENSES.map((name) => ({
     name: `audit::${name}`,
@@ -123,13 +92,8 @@ const AUDIT_LENS_LABELS = Object.freeze(
 );
 
 /**
- * The story-axis labels an audit-generated Story carries alongside its
- * `audit::<lens>` labels.
- *
- * The `type::` / `agent::` entries are also in `LABEL_TAXONOMY` (the repo-wide
- * bootstrap). Creating a label twice is a no-op, so the overlap costs nothing
- * and means an audit sweep does not silently depend on the repo-wide bootstrap
- * having run first.
+ * Overlaps the repo-wide taxonomy on purpose (re-creating is a no-op), so an
+ * audit sweep does not depend on the repo-wide bootstrap having run.
  */
 const AUDIT_STORY_AXIS_LABELS = Object.freeze([
   {
@@ -137,14 +101,8 @@ const AUDIT_STORY_AXIS_LABELS = Object.freeze([
     color: hex(LABEL_COLORS.TYPE),
     description: 'Story work item',
   },
-  // Created, never generated — the one deliberate asymmetry in this module.
-  // The filer emits no `agent::` state (see `STATIC_LABELS` in
-  // build-story-body.js): a freshly-filed audit Story is not delivery-ready,
-  // and `/mandrel-plan` stamps this label as its terminal flip after
-  // enrichment. The bootstrap still creates it so that flip has a label to
-  // apply on a repo where only the audit bootstrap has been run. The drift
-  // this module guards runs the other way — a generator inventing names the
-  // creator never made — so a creator-only entry is safe (Story #5229).
+  // Created, never generated: `/mandrel-plan` applies it after enrichment.
+  // A creator-only entry is safe; the guarded drift is generator-only names.
   {
     name: AGENT_LABELS.READY,
     color: hex(LABEL_COLORS.AGENT),
@@ -159,10 +117,6 @@ const AUDIT_STORY_AXIS_LABELS = Object.freeze([
   },
 ]);
 
-/**
- * Every label the audit sweep defines — the closed set the bootstrap creates
- * and {@link definesAuditLabel} answers against.
- */
 export const AUDIT_LABEL_TAXONOMY = Object.freeze([
   ...AUDIT_LENS_LABELS,
   ...AUDIT_STORY_AXIS_LABELS,
@@ -171,13 +125,6 @@ export const AUDIT_LABEL_TAXONOMY = Object.freeze([
 const DEFINED_NAMES = new Set(AUDIT_LABEL_TAXONOMY.map((l) => l.name));
 
 /**
- * True when `name` is a label this taxonomy defines.
- *
- * The enforcement point is the label **generator** (`build-story-body.js`),
- * which routes every label it derives through this predicate and refuses to
- * emit one the taxonomy does not define — closing the drift in the direction it
- * actually happened: a generator inventing names the bootstrap never created.
- *
  * @param {unknown} name
  * @returns {boolean}
  */
@@ -186,18 +133,9 @@ export function definesAuditLabel(name) {
 }
 
 /**
- * Render the `audit-labels` footer for a group of findings.
- *
  * The dedup corpus is listed by `audit::*` label, so a Story filed without one
- * is absent from the pool an indexed run matches against — and with an index in
- * play the exact lookup is answered locally and never reaches the provider, so
- * a fingerprint footer alone cannot rescue it. Carrying the labels through the
- * seed is what lets the chained planning path stamp them without the authoring
- * agent being asked to notice them (Story #5307).
- *
- * Lives here rather than beside {@link auditLabelsForFindings} because it needs
- * {@link definesAuditLabel}, and the taxonomy already depends on the lens list —
- * the reverse edge would be a cycle.
+ * is invisible to an indexed run; the seed carries the labels so the planning
+ * path stamps them. Lives here (not in audit-lenses) to avoid an import cycle.
  *
  * @param {Array<object>} findings
  * @returns {string} the footer, or '' when no finding resolves to a label.

package/.agents/scripts/lib/audit-to-stories/audit-lenses.js

@@ -1,26 +1,12 @@
 /**
- * lib/audit-to-stories/audit-lenses.js — SSOT for the canonical audit lens
- * taxonomy.
- *
- * The `/audit-<lens>` workflows each emit a report named
- * `audit-<lens>-results.md`. The `audit::<lens>` GitHub label set is keyed off
- * exactly these lens names — never off a finding's fine-grained `dimension`
- * text. `build-story-body.js` derives a group's `audit::<lens>` labels from
- * each finding's `sourceReport` basename via {@link lensFromSourceReport}, and
- * `audit-labels-bootstrap.js` creates one `audit::<lens>` label per entry in
- * {@link AUDIT_LENSES}. Centralising the list here keeps the label producer
- * (bootstrap) and the label deriver (story-body) from drifting apart.
- *
- * Pure: no I/O.
- *
- * @see Story #4195 — junk `audit::<dimension>` label derivation.
+ * SSOT for the audit lens names. `audit::<lens>` labels key off these (via
+ * each finding's report basename), never off a finding's `dimension` text.
+ * Pure.
  */
 
 /**
- * The canonical lens names, one per `/audit-<lens>` workflow under
- * `.agents/workflows/` (excluding the `audit-to-stories` and `audit-fan-out`
- * meta-workflows, which produce no `audit-<lens>-results.md` of their own).
- * Adding a new `audit-*` workflow MUST add its lens name here.
+ * One per `/audit-<lens>` workflow that emits `audit-<lens>-results.md`; a
+ * new `audit-*` lens workflow MUST be added here.
  *
  * @type {ReadonlyArray<string>}
  */
@@ -44,7 +30,6 @@ export const AUDIT_LENSES = Object.freeze([
   'ux-ui',
 ]);
 
-/** O(1) membership set for {@link isCanonicalLens}. */
 const LENS_SET = new Set(AUDIT_LENSES);
 
 /**
@@ -56,16 +41,8 @@ export function isCanonicalLens(lens) {
 }
 
 /**
- * Derive the canonical lens name from an `audit-<lens>-results.md` source
- * report path. The derivation is basename-only (the directory — typically
- * `temp/audits/` — is irrelevant) and matches the exact
- * `audit-<lens>-results.md` shape the audit workflows emit. Backslash and
- * forward-slash separators are both handled so a Windows-authored path
- * resolves identically.
- *
- * Returns `null` when the path does not match the expected shape or the
- * extracted lens is not one of the canonical {@link AUDIT_LENSES} — callers
- * drop a `null` so a stray report name can never mint a junk `audit::*` label.
+ * Basename-only, either separator. `null` for a non-matching or non-canonical
+ * name, so a stray report can never mint a junk label.
  *
  * @param {unknown} sourceReport — e.g. `temp/audits/audit-clean-code-results.md`.
  * @returns {string|null} the canonical lens (`clean-code`) or `null`.
@@ -83,14 +60,8 @@ export function lensFromSourceReport(sourceReport) {
 }
 
 /**
- * Derive the deduped, sorted set of canonical `audit::<lens>` labels for a
- * collection of findings, keyed off each finding's `sourceReport` basename.
- * Findings whose `sourceReport` does not resolve to a canonical lens
- * contribute no label (never a junk one). Multi-lens groups (findings from
- * more than one report) yield one label per distinct lens.
- *
  * @param {Array<{ sourceReport?: unknown }>} findings
- * @returns {string[]} sorted `audit::<lens>` labels.
+ * @returns {string[]} sorted, deduped `audit::<lens>` labels.
  */
 export function auditLabelsForFindings(findings) {
   const lenses = new Set();

package/.agents/scripts/lib/audit-to-stories/build-story-body.js

@@ -1,25 +1,6 @@
 /**
- * lib/audit-to-stories/build-story-body.js
- *
- * Render the canonical Story body for the standalone grouping mode so a
- * generated audit Story clears the same inline-contract bar the decomposer
- * enforces (`assertEveryStoryHasInlineContract`): a clean goal, observable
- * `acceptance[]`, a populated `changes[]` footprint, and a non-empty,
- * tier-tagged `verify[]` (Story #4270).
- *
- * Pure: returns { title, body, labels }. Labels carry one canonical
- * `audit::<lens>` per distinct source report represented in the merge
- * (derived from each finding's `sourceReport` basename, NEVER from the
- * fine-grained `dimension` text — see Story #4195), plus `type::story` and
- * (when any finding is Critical) `risk::high`. Deliberately **no `agent::`
- * state label** — see {@link STATIC_LABELS}.
- *
- * The body is serialized via the canonical story-body serializer
- * (`.agents/scripts/lib/story-body/story-body.js`) so the output round-trips
- * through `parse()` / `serialize()`. Audit-specific content (agent prompts,
- * context links, fingerprint footer) is appended after the canonical sections
- * as extended markdown — it is informational only and is not part of the
- * structured contract.
+ * Render a standalone audit Story body that clears the inline-contract bar,
+ * with audit extras appended as informational markdown. Pure.
  */
 
 import path from 'node:path';
@@ -32,32 +13,11 @@ import {
   renderSemanticKeyFooter,
 } from './finding-adapter.js';
 
-// The story-axis labels every generated audit Story carries, and the one it
-// deliberately does NOT: an `agent::` state.
-//
-// This used to be `[TYPE_LABELS.STORY, AGENT_LABELS.READY]`, which put every
-// Story the sweep filed one step from execution. `agent::ready` is precisely
-// what `/mandrel-deliver` reads as "available for pickup", and the bodies
-// reaching this function are audit prose — a synthesized acceptance line per
-// finding and an Agent Prompts section that is empty whenever the lens
-// captured no `agentPrompt`. Filing them ready contradicted the sweep's own
-// shipped runbook, whose enrich-before-you-deliver step says not to point
-// `/mandrel-deliver` at a freshly-filed audit Story; the label said the
-// opposite of the prose, and the label is the half a machine reads.
-//
-// The state axis therefore belongs to whoever enriches the finding:
-// `/mandrel-plan` stamps `agent::ready` as its terminal flip once the Story
-// has a `## Spec`, real acceptance criteria and runnable verify lines. An
-// absent `agent::` label is a legal initial state — `isValidTransition`
-// treats a null from-state as the initial-entry edge and permits any target —
-// so nothing downstream has to special-case the gap (Story #5229).
+// Deliberately no `agent::` state label: audit prose is not ready for pickup.
+// `/mandrel-plan` stamps `agent::ready` once enriched; an absent state is a
+// legal initial state for `isValidTransition`.
 const STATIC_LABELS = Object.freeze([TYPE_LABELS.STORY]);
 
-// The verify[] contract every generated audit Story carries. These commands
-// exist in this repo's harness (package.json scripts) so the Story satisfies
-// the inline-contract bar with runnable, tier-tagged gates rather than
-// placeholder prose. Kept as a frozen constant so the same contract is
-// asserted by the unit suite.
 const DEFAULT_VERIFY = Object.freeze([
   'npm run lint (validate)',
   'npm test (unit)',
@@ -68,11 +28,7 @@ function uniq(items) {
 }
 
 /**
- * The goal is the group intent only — the synthesized `group.title`. It
- * carries no leading ordinal (`1.`/`2.`) and no `[SEVERITY]` / `(dimension)`
- * prefix (the polluted shape Story #4270 replaced); those signals live in the
- * per-finding fingerprint footer and the extended Agent Prompts section, not
- * in the goal.
+ * The group intent only — no ordinal or `[SEVERITY]`/`(dimension)` prefix.
  *
  * @param {object} group
  * @returns {string}
@@ -82,14 +38,6 @@ function goalFromGroup(group) {
 }
 
 /**
- * Map every distinct file mentioned across the merge onto a canonical
- * `changes[]` PathEntry (`{ path, assumption }`). Audit findings remediate
- * code that already exists, so the assumption is `refactors-existing`.
- *
- * `group.files` is an array post-`groupFindings`; fall back to scanning the
- * findings' own `files[]` when an upstream caller hands a group whose `files`
- * aggregate was not materialized.
- *
  * @param {object} group
  * @returns {Array<{ path: string, assumption: string }>}
  */
@@ -107,15 +55,8 @@ function changesFromGroup(group) {
 }
 
 /**
- * Build an observable acceptance item from a single finding: a checkable
- * end-state a reviewer can confirm, NOT the verbatim recommendation
- * paragraph. The recommendation prose is preserved verbatim in the Agent
- * Prompts / fingerprint footer for the implementer; the acceptance line is
- * the binding, confirmable outcome.
- *
- * Shape: `<title> is remediated in <primary file>: the recommended end-state
- * holds and the finding is no longer reproducible.` — anchored on the finding
- * title and primary file so the reviewer knows exactly what to check.
+ * A checkable end-state anchored on title and primary file, not the verbatim
+ * recommendation (which stays in the prompts/footer).
  *
  * @param {object} finding
  * @returns {string}
@@ -135,9 +76,6 @@ function acceptanceCriteriaFromGroup(group) {
 }
 
 /**
- * Resolve the `edges[]` sequencing anchored on this group. Each edge whose
- * `fromGroupKey` matches this group's key contributes its `toGroupKey`.
- *
  * @param {object} group
  * @param {Array<{ fromGroupKey: string, toGroupKey: string }>} edges
  * @returns {string[]}
@@ -152,27 +90,10 @@ function sequencingDepsForGroup(group, edges) {
 }
 
 /**
- * Resolve this group's sequencing to canonical `#N` issue refs, or `[]` when
- * the caller has no issue numbers yet (Story #5044).
- *
- * Group keys are the only identifier that exists at *emit* time — the issues
- * are not numbered — which is why this used to render as a prose
- * `## Sequencing` block that nothing could act on. Standalone audit Stories
- * therefore hardcoded `depends_on: []`, and their only actual serializer was
- * an accident: their shared provenance footers collided under the delivery
- * footprint guard. Narrowing that scrape removes the accident, so the ordering
- * has to become real in the same change.
- *
- * The resolution is the two-pass shape `plan-persist` already uses: create every
- * issue first, then re-render each body with the now-known numbers and mirror
- * the same edges as native `blocked_by` relations. An edge whose target was not
- * created (deduped against an existing Issue, suppressed by the ledger) simply
- * drops — a `blocked by #undefined` would be worse than an absent edge.
- *
- * A **plain object**, deliberately, not a `Map`: the same map is handed to
- * `applyBlockedByDependencies`, which indexes it with property access, so a
- * `Map` there would silently resolve every lookup to `undefined`, skip every
- * edge, and report success having written nothing. One shape, both halves.
+ * Group keys → `#N` refs, or `[]` before issues are numbered (first pass).
+ * Edges whose target was not created drop. `issueByGroupKey` must be a plain
+ * object: `applyBlockedByDependencies` indexes the same map by property, so a
+ * `Map` would silently skip every edge.
  *
  * @param {string[]} deps                     Group keys this group depends on.
  * @param {Record<string, number>|null} issueByGroupKey
@@ -196,16 +117,8 @@ function agentPromptsSection(group) {
 }
 
 /**
- * Link each source audit report **once**.
- *
- * This used to render `- [\`path\`](path)` — the same
- * `temp/audits/audit-<lens>-results.md` in the link text and again in the URL,
- * byte-identical across every Story of a same-lens sweep. That doubled a token
- * the delivery footprint guard scraped as edit intent, so a lens's whole cohort
- * serialized on a report none of them would ever write to (Story #5044). The
- * guard now ignores markdown-link URLs and temp-root paths, but rendering the
- * path twice was never useful to a reader either: the file name is the label,
- * the path is the target.
+ * Link each source report once (basename label, path target); repeating the
+ * path is a token the footprint guard can scrape as edit intent.
  *
  * @param {object} group
  * @returns {string}
@@ -217,21 +130,14 @@ function contextLinksFromGroup(group) {
       .filter((s) => typeof s === 'string'),
   );
   if (reports.length === 0) return '_(no source audit reports captured)_';
-  // `path.basename` rather than `split('/')`: on win32 it splits on both
-  // separators, so an absolute Windows path yields the file name instead of
-  // the whole path — which would render the path twice in one link and
-  // re-create the very duplication this function exists to remove.
+  // `path.basename` splits on both separators on win32; `split('/')` would
+  // leave a Windows path whole and render it twice.
   return reports.map((r) => `- [${path.basename(r)}](${r})`).join('\n');
 }
 
 function labelsForGroup(group) {
-  // Derive `audit::<lens>` from each finding's `sourceReport` basename
-  // (`audit-<lens>-results.md` → `audit::<lens>`), NOT from the finding's
-  // fine-grained `dimension` text. The dimension is free-form prose
-  // ("stale-description", "dry", "efficiency (cpu)") and minting
-  // `audit::<dimension>` from it produced non-existent labels; only the 14
-  // canonical lens labels are valid. Multi-lens groups carry one label per
-  // distinct source report. See Story #4195.
+  // `audit::<lens>` comes from each `sourceReport` basename, never from the
+  // free-form `dimension` text, which mints non-existent labels.
   const auditLabels = auditLabelsForFindings(group.findings ?? []);
   const labels = [...STATIC_LABELS, ...auditLabels];
   const hasCritical = (group.findings ?? []).some(
@@ -242,17 +148,8 @@ function labelsForGroup(group) {
 }
 
 /**
- * Refuse to generate a label the audit bootstrap taxonomy does not define
- * (Story #4877).
- *
- * Story #4195 fixed half of this: `audit::<dimension>` labels minted from
- * free-form dimension prose ("stale-description", "dry") named labels that did
- * not exist, so derivation moved to the closed lens list. The other half stayed
- * open — `risk::high` was a bare string literal here, defined by no taxonomy —
- * and nothing checked the generated set against anything at all. Throwing is
- * deliberate: a label the repo has never created is dropped or fails the create
- * outright, and a filer that silently loses `risk::high` on a Critical merge is
- * worse than a loud failure at the point of generation.
+ * Throws rather than emit a label the repo lacks: a create would drop or fail
+ * on it, and silently losing `risk::high` on a Critical is worse.
  *
  * @param {string[]} labels
  * @returns {string[]} the same labels, when every one is defined.
@@ -272,20 +169,13 @@ function assertLabelsInTaxonomy(labels) {
 }
 
 /**
+ * Second pass passes `issueByGroupKey` so edges render as `blocked by #N`.
+ *
  * @param {object} params
  * @param {object} params.group — output of `groupFindings` (one entry).
  * @param {Array<{ fromGroupKey: string, toGroupKey: string }>} [params.edges]
- *   — the dependency `edges[]` emitted by `groupFindings`. Edges anchored on
- *   this group are carried through to `depends_on[]`; omit when no sequencing
- *   is known.
- * @param {Record<string, number>|null} [params.issueByGroupKey]
- *   — group key → opened issue number. Supplied on the **second** pass, once
- *   the issues exist, so this group's edges render as canonical
- *   `blocked by #N` footers (Story #5044). Omit on the first pass.
+ * @param {Record<string, number>|null} [params.issueByGroupKey] Second pass only.
  * @returns {{ title: string, body: string, labels: string[], groupKey: string, dependsOn: string[] }}
- *   `groupKey` and `dependsOn` are the caller's handle on the second pass:
- *   they name this Story and the groups it must follow, so the caller can map
- *   both onto issue numbers without re-deriving the grouping.
  */
 export function buildStoryBody({ group, edges = [], issueByGroupKey = null }) {
   if (!group || !Array.isArray(group.findings)) {
@@ -294,11 +184,6 @@ export function buildStoryBody({ group, edges = [], issueByGroupKey = null }) {
   const title = group.title;
   const dependsOn = sequencingDepsForGroup(group, edges);
 
-  // Build the canonical StoryBody object from the audit group data. The
-  // acceptance + verify arrays are populated so the body clears the
-  // inline-contract bar; changes[] carries the file footprint. `depends_on`
-  // is empty on the first pass (the blockers have no issue numbers yet) and
-  // carries real `#N` refs on the second — see dependencyRefs.
   const storyBody = {
     goal: goalFromGroup(group),
     changes: changesFromGroup(group),
@@ -310,15 +195,12 @@ export function buildStoryBody({ group, edges = [], issueByGroupKey = null }) {
     depends_on: dependencyRefs(dependsOn, issueByGroupKey),
   };
 
-  // The `---` / `blocked by #N` footer is the canonical serializer's own, so
-  // the body round-trips through `parse()` and `/mandrel-deliver`'s resolver reads the
-  // ordering from the same place it reads every other Story's.
+  // The serializer's own footer, so `/mandrel-deliver` reads the ordering
+  // where it reads every other Story's.
   const canonicalSections = serialize(storyBody, {
     includeFooter: storyBody.depends_on.length > 0,
   });
 
-  // Append audit-specific extended sections (agent prompts, context links,
-  // provenance footers) that are not part of the canonical shape.
   const body = [
     canonicalSections,
     '',