mandrel 2.3.0 → 2.5.0

package/.agents/scripts/lib/findings/route-finding.js

@@ -32,7 +32,12 @@ import crypto from 'node:crypto';
 
 const SEP = '␟'; // unit separator — keeps fingerprint fields unambiguous
 const MARKER = 'audit-fingerprints:';
+const SEMANTIC_MARKER = 'audit-semantic-keys:';
 const SHA1_RE = /^[0-9a-f]{40}$/;
+// A semantic key round-trips through a comma-joined footer, so it must not
+// carry a comma or a `>` (which would truncate the HTML comment). Both are
+// stripped when the key is built, so this guard is defence-in-depth.
+const SEMANTIC_KEY_RE = /^[^,>]+$/;
 
 /**
  * Normalise a single scalar identity field to a stable string.
@@ -92,6 +97,67 @@ export function fingerprintFinding(finding) {
   return { short: full.slice(0, 12), full, components };
 }
 
+/**
+ * Compute the **location-based semantic key** for a finding. Unlike the
+ * fingerprint (which folds in the title, so any prose rewording mints a fresh
+ * sha), the semantic key is stable across a reworded title and a re-severitied
+ * finding: it is derived solely from the finding's identity *location* —
+ * `area` (the audit dimension) plus `primaryFile`. Two scans that describe the
+ * same problem at the same location produce the same semantic key even when
+ * their titles diverge, so a reworded finding still confirms against the Issue
+ * that already tracks that location.
+ *
+ * Returns the empty string when the location is unknown (no `area` and no
+ * `primaryFile`) — an empty key never confirms a match, exactly as an absent
+ * fingerprint footer never does.
+ *
+ * @param {object} finding — canonical finding ({ area, primaryFile, ... }).
+ * @returns {string}
+ */
+export function semanticKeyFor(finding) {
+  const area = normaliseField(finding?.area);
+  const primaryFile = normaliseField(finding?.primaryFile);
+  if (!area && !primaryFile) return '';
+  const key = `${area}${SEP}${primaryFile}`;
+  return SEMANTIC_KEY_RE.test(key) ? key : key.replace(/[,>]/g, ' ').trim();
+}
+
+/**
+ * Render the machine-readable semantic-key footer for one or more keys
+ * (`<!-- audit-semantic-keys: key,key,... -->`). Stamped alongside the
+ * fingerprint footer by the audit filers so a later reworded finding can
+ * confirm identity by location when its fingerprint has drifted. Round-trips
+ * through {@link parseSemanticKeyFooter}. Empty keys are dropped.
+ *
+ * @param {string | string[]} keys — one semantic key or an array of them.
+ * @returns {string}
+ */
+export function semanticKeyFooter(keys) {
+  const list = (Array.isArray(keys) ? keys : [keys])
+    .filter((k) => typeof k === 'string' && k.length > 0)
+    .map((k) => k.replace(/[,>]/g, ' ').trim())
+    .filter((k) => k.length > 0);
+  return `<!-- ${SEMANTIC_MARKER} ${list.join(',')} -->`;
+}
+
+/**
+ * Extract semantic keys from an Issue body carrying the semantic-key footer.
+ * Internal — the audit filers stamp the footer via {@link semanticKeyFooter};
+ * only the confirmation path here reads it back.
+ *
+ * @param {string} body
+ * @returns {string[]}
+ */
+function parseSemanticKeyFooter(body) {
+  if (typeof body !== 'string') return [];
+  const match = body.match(/<!--\s*audit-semantic-keys:\s*([^>]*?)\s*-->/);
+  if (!match) return [];
+  return match[1]
+    .split(',')
+    .map((s) => s.trim())
+    .filter((s) => s.length > 0);
+}
+
 /**
  * Render the machine-readable fingerprint footer for one or more shas.
  *
@@ -147,6 +213,21 @@ function issueCarriesFingerprint(issue, sha) {
   return parseFingerprintFooter(issue.body).includes(sha);
 }
 
+/**
+ * Confirm an issue body's footer carries the target semantic key. Unlike
+ * {@link issueCarriesFingerprint}, this is strict on a missing body — a
+ * location match is only meaningful when the issue actually carries a
+ * semantic-key footer to compare against.
+ *
+ * @param {{ body?: string }} issue
+ * @param {string} key
+ * @returns {boolean}
+ */
+function issueCarriesSemanticKey(issue, key) {
+  if (!key || typeof issue?.body !== 'string') return false;
+  return parseSemanticKeyFooter(issue.body).includes(key);
+}
+
 /**
  * Decide the route decision from a confirmed matched issue's state.
  * @param {{ state?: string }} issue
@@ -194,23 +275,29 @@ function decideFromConfirmed(confirmed, sha) {
 }
 
 /**
- * Keep only the issue records that have the right wire shape AND carry the
- * target fingerprint in their footer. A semantic candidate that merely *looks*
- * similar but does not carry the sha is dropped here — semantic similarity
- * widens the net; the fingerprint footer is what confirms identity.
+ * Keep only the issue records that have the right wire shape AND carry a
+ * confirming footer. Confirmation is by the exact **fingerprint** footer and,
+ * when a `semanticKey` is supplied (audit dedup opts in via
+ * `options.semanticKeyConfirm`), ALSO by the location-based **semantic-key**
+ * footer. A semantic candidate that merely *looks* similar but carries neither
+ * footer is dropped here — semantic similarity widens the net; a deterministic
+ * footer (fingerprint or semantic key) is what confirms identity. The semantic
+ * key catches a reworded finding whose fingerprint has drifted but whose
+ * location is unchanged.
  *
  * @param {Array<unknown>} hits
- * @param {string} sha
+ * @param {{ sha: string, semanticKey?: string }} identity
  * @returns {Array<{ number: number, state: string }>}
  */
-function confirmFingerprint(hits, sha) {
+function confirmCandidates(hits, { sha, semanticKey = '' }) {
   if (!Array.isArray(hits)) return [];
   return hits.filter(
     (h) =>
       h &&
       typeof h.number === 'number' &&
       typeof h.state === 'string' &&
-      issueCarriesFingerprint(h, sha),
+      (issueCarriesFingerprint(h, sha) ||
+        issueCarriesSemanticKey(h, semanticKey)),
   );
 }
 
@@ -245,11 +332,18 @@ function confirmFingerprint(hits, sha) {
  *   Meaning-first candidate search over open+closed issues (and Epic
  *   sub-issues). When supplied, runs FIRST; its candidates are then
  *   fingerprint-confirmed.
+ * @param {object} [options]
+ * @param {boolean} [options.semanticKeyConfirm=false] — also confirm a
+ *   candidate by the location-based semantic-key footer, not the fingerprint
+ *   alone. Opt-in so the audit dedup path catches a reworded finding at an
+ *   unchanged location while the qa-explore path (which does not stamp
+ *   semantic-key footers) stays fingerprint-exact and byte-identical.
  * @returns {Promise<{ decision: 'new'|'update-existing'|'duplicate'|'regression-of-closed', matchedIssue: object|null, fingerprint: string }>}
  */
 export async function routeFinding(
   finding,
   { searchIssues, searchCandidates } = {},
+  options = {},
 ) {
   if (
     typeof searchCandidates !== 'function' &&
@@ -261,6 +355,7 @@ export async function routeFinding(
   }
 
   const { full: sha } = fingerprintFinding(finding);
+  const semanticKey = options.semanticKeyConfirm ? semanticKeyFor(finding) : '';
 
   // Stage 1: semantic candidate pass first (when wired); else fingerprint
   // lookup. Both yield a candidate pool drawn from open AND closed issues.
@@ -269,15 +364,18 @@ export async function routeFinding(
       ? await searchCandidates(finding)
       : await searchIssues(sha);
 
-  // Stage 2: confirm identity by fingerprint footer over the candidate pool.
-  const confirmed = confirmFingerprint(hits, sha);
+  // Stage 2: confirm identity by fingerprint footer (and, when opted in, the
+  // location-based semantic-key footer) over the candidate pool.
+  const confirmed = confirmCandidates(hits, { sha, semanticKey });
 
   return decideFromConfirmed(confirmed, sha);
 }
 
 export const __testing = {
   MARKER,
+  SEMANTIC_MARKER,
   SEP,
-  confirmFingerprint,
+  confirmCandidates,
   decideFromConfirmed,
+  issueCarriesSemanticKey,
 };

package/.agents/scripts/lib/observability/runtime-friction.js

@@ -159,6 +159,68 @@ export async function emitRuntimeFriction({
   }
 }
 
+/**
+ * Emit the recovery counterpart of a `story-blocked` record when a Story
+ * leaves `agent::blocked` for an active state (Story #4622).
+ *
+ * A transient block that self-resolves — lease contention or a stale label
+ * read under concurrent shared-checkout pressure (swarm-os friction #581) —
+ * still fired a `story-blocked` record at the block flip, which the retro
+ * composer counts toward the `story-blocked` recurrence total exactly like a
+ * terminal block. This emits a companion `story-blocked` record carrying the
+ * `details.recovered: true` discriminator, so the composer can net the whole
+ * incident out (see `retro-proposals.js`). The category is deliberately kept
+ * as `story-blocked` rather than a new bucket: a distinct category would
+ * itself aggregate into a routable proposal, re-introducing the noise.
+ *
+ * Best-effort; never throws.
+ *
+ * @param {object} args
+ * @param {number} args.storyId
+ * @param {string} [args.fromState] The state parked at (`agent::blocked`).
+ * @param {string} [args.toState]   The active state recovered into.
+ * @param {object} [args.config]
+ * @returns {Promise<boolean>} true when a record was appended.
+ */
+export async function emitBlockRecoveredFriction({
+  storyId,
+  fromState,
+  toState,
+  config,
+} = {}) {
+  return emitRuntimeFriction({
+    storyId,
+    category: RUNTIME_FRICTION_CATEGORIES.STORY_BLOCKED,
+    tool: 'transitionTicketState',
+    details: {
+      recovered: true,
+      fromState: fromState ?? null,
+      toState: toState ?? null,
+    },
+    config,
+  });
+}
+
+/**
+ * Pure predicate: is this signal a recovery-marked `story-blocked` record?
+ * Shared with the retro composer so the "recovered" discriminator is read
+ * from one place. A record is a recovery marker when its category is
+ * `story-blocked` and `details.recovered === true`.
+ *
+ * @param {object} signal
+ * @returns {boolean}
+ */
+export function isRecoveredBlockSignal(signal) {
+  return (
+    signal !== null &&
+    typeof signal === 'object' &&
+    signal.category === RUNTIME_FRICTION_CATEGORIES.STORY_BLOCKED &&
+    signal.details !== null &&
+    typeof signal.details === 'object' &&
+    signal.details.recovered === true
+  );
+}
+
 /**
  * Decide whether a `story-deliver-terminal` envelope is worth a friction
  * record, and describe it. **Pure** — no I/O — so the (interesting) policy

package/.agents/scripts/lib/orchestration/resolve-stories.js

@@ -62,7 +62,7 @@ function normalizeIssueLabels(issue) {
  *
  * @param {object} issue
  * @param {number} [requestedId] The id the operator asked for, for error text.
- * @returns {{ id, title, body, url, labels, state }}
+ * @returns {{ id, title, body, url, labels, state, assignees }}
  */
 export function toStoryRecord(issue, requestedId) {
   const id = Number(issue?.number ?? issue?.id ?? requestedId);
@@ -93,6 +93,14 @@ export function toStoryRecord(issue, requestedId) {
     url: issue?.html_url ?? issue?.url ?? null,
     labels,
     state: String(issue?.state ?? 'open').toLowerCase(),
+    // The assignee list carries the Story lease (`ticket-lease.js`): its sole
+    // assignee is the operator that owns the in-flight run. The probe reads it
+    // to withhold a Story another operator holds (`live-probe.js`), so it is
+    // threaded onto the record here rather than dropped. `issueToTicket`
+    // already reduces assignees to bare login strings; keep only those.
+    assignees: Array.isArray(issue?.assignees)
+      ? issue.assignees.filter((a) => typeof a === 'string' && a.length > 0)
+      : [],
   };
 }
 

package/.agents/scripts/lib/orchestration/retro-proposals.js

@@ -34,6 +34,11 @@
  * @typedef {Object} FrictionSignal
  * @property {string} category   Free-form bucket (e.g. `"lint-loop"`).
  * @property {"framework"|"consumer"} source
+ * @property {number} [storyId]  Emitting Story id (used to net out recovered
+ *                               `story-blocked` incidents — Story #4622).
+ * @property {object} [details]  Kind-specific payload; a `story-blocked`
+ *                               record with `details.recovered === true` is a
+ *                               recovery marker.
  *
  * @typedef {Object} BlockedEvent
  * @property {number} ticketId
@@ -68,6 +73,11 @@
  * @property {DiscardedItem[]}  discarded
  */
 
+import {
+  isRecoveredBlockSignal,
+  RUNTIME_FRICTION_CATEGORIES,
+} from '../observability/runtime-friction.js';
+
 /**
  * Empty result helper — returned for zero-input callers so the consumer
  * never needs to defensively spread undefineds.
@@ -89,6 +99,44 @@ function asString(value) {
   return value.trim();
 }
 
+/**
+ * Net transient (self-resolved) blocks out of the signal stream before it is
+ * aggregated (Story #4622).
+ *
+ * A `blocked → active` recovery emits a `story-blocked` record carrying
+ * `details.recovered === true`. When a Story has such a marker, its block was
+ * transient — lease contention or a stale label read under concurrent
+ * shared-checkout pressure (swarm-os friction #581) that cleared on a later
+ * beat — not a terminal HITL pause. This drops **every** `story-blocked`
+ * record for such a Story (both the original block and its recovery marker),
+ * so the retro counts only Stories still parked at `agent::blocked`.
+ *
+ * The netting is by `storyId`, not 1:1 pairing: a Story that ever recovered
+ * from a block in the run is treated as non-terminal for the whole run. That
+ * is a deliberate coarsening — the aggregate is a routing heuristic, not an
+ * incident ledger, and the signal stream carries no reliable ordering to
+ * reconstruct interleaved block/recover cycles. Non-`story-blocked` records
+ * and Stories with no recovery marker pass through untouched.
+ *
+ * @param {FrictionSignal[]} signals
+ * @returns {FrictionSignal[]}
+ */
+function netOutRecoveredBlocks(signals) {
+  const recoveredStoryIds = new Set();
+  for (const sig of signals) {
+    if (isRecoveredBlockSignal(sig) && Number.isInteger(sig.storyId)) {
+      recoveredStoryIds.add(sig.storyId);
+    }
+  }
+  if (recoveredStoryIds.size === 0) return signals;
+  return signals.filter((sig) => {
+    if (sig === null || typeof sig !== 'object') return true;
+    const isBlocked =
+      sig.category === RUNTIME_FRICTION_CATEGORIES.STORY_BLOCKED;
+    return !(isBlocked && recoveredStoryIds.has(sig.storyId));
+  });
+}
+
 /**
  * Aggregate friction signals by `category`, tracking per-source counts and
  * arrival order so we can pick a dominant source deterministically.
@@ -403,7 +451,7 @@ export function composeRoutedProposals(input) {
   } = normalised;
 
   return routeCategoryBuckets({
-    byCategory: aggregateByCategory(signals),
+    byCategory: aggregateByCategory(netOutRecoveredBlocks(signals)),
     blockedForceActionable: blockedForceMap(unresolvedBlockedEvents),
     anchorId,
     anchorKind,

package/.agents/scripts/lib/orchestration/single-story-close/phases/post-land.js

@@ -29,8 +29,11 @@
  * is best-effort and records its own reason.
  */
 
+import path from 'node:path';
+
 import { gitSpawn as defaultGitSpawn } from '../../../git-utils.js';
 import { Logger } from '../../../Logger.js';
+import { acquireLockWithWait as defaultAcquireLockWithWait } from '../../../single-story-sweep/sweep-lock.js';
 import {
   executeFastForward as defaultExecuteFastForward,
   planFastForward as defaultPlanFastForward,
@@ -38,6 +41,21 @@ import {
 import { reassertStatusColumn as defaultReassertStatusColumn } from '../../reassert-status-column.js';
 import { captureStoryFollowUps as defaultCaptureStoryFollowUps } from '../../story-follow-ups.js';
 
+/**
+ * Lockfile that serializes the local-checkout git mutations of the land tail
+ * across concurrent closes. Keyed on the **main checkout** (never a
+ * worktree): every concurrent `single-story-close` runs its tail against the
+ * same `cwd`, so anchoring the lock under that checkout's `.git` directory
+ * makes them all contend on one file. `.git` is always present, is one per
+ * checkout, and is never itself tracked, so it is a safe rendezvous home.
+ *
+ * @param {string} cwd Main checkout root.
+ * @returns {string}
+ */
+function postLandLockPath(cwd) {
+  return path.join(cwd, '.git', 'mandrel-post-land-tail.lock');
+}
+
 /**
  * Run one tail step, converting any throw into a `false` + reason. Keeps
  * each step's own body free of defensive boilerplate while guaranteeing the
@@ -210,6 +228,19 @@ async function stepBaseFastForward({
  * after the ref reap so `git branch -D` is not fighting a checkout that just
  * moved HEAD.
  *
+ * **Cross-process serialization (Story #4622).** The two local-checkout
+ * mutations — `stepRefCleanup` (`git branch -D`) and `stepBaseFastForward`
+ * (fast-forward `baseBranch`) — run inside a best-effort cross-process lock
+ * keyed on the main checkout. Under concurrent delivery (multiple
+ * story-workers closing against one shared checkout + per-Story worktrees),
+ * an unserialized tail races on the `main` ref and the worktree registry —
+ * the `refCleanup:false` ("used by worktree") / `baseFastForward:false`
+ * ("not-fast-forward") signature reported in swarm-os friction #579. The
+ * GitHub-touching steps stay OUTSIDE the lock so a contended checkout never
+ * delays them. The lock is never load-bearing: on sustained contention the
+ * bounded wait expires and the mutations run anyway (proceeding is the same
+ * best-effort contract every tail step already has).
+ *
  * @param {object} args
  * @param {number} args.storyId
  * @param {string} args.storyBranch
@@ -223,6 +254,7 @@ async function stepBaseFastForward({
  * @param {Function} [args.gitSpawnFn]              Test seam.
  * @param {Function} [args.planFastForwardFn]       Test seam.
  * @param {Function} [args.executeFastForwardFn]    Test seam.
+ * @param {Function} [args.acquireLockWithWaitFn]   Test seam.
  * @returns {Promise<{ followUps: boolean, statusResync: boolean, refCleanup: boolean, baseFastForward: boolean, details: Record<string, string|null> }>}
  */
 export async function runPostLandTail({
@@ -238,6 +270,7 @@ export async function runPostLandTail({
   gitSpawnFn = defaultGitSpawn,
   planFastForwardFn = defaultPlanFastForward,
   executeFastForwardFn = defaultExecuteFastForward,
+  acquireLockWithWaitFn = defaultAcquireLockWithWait,
 }) {
   progress?.('POST-LAND', `🧾 Running land tail for Story #${storyId}...`);
 
@@ -264,21 +297,46 @@ export async function runPostLandTail({
       }),
     { name: 'status-column resync', progress },
   );
-  const refCleanup = await step(
-    () => stepRefCleanup({ cwd, storyBranch, progress, gitSpawnFn }),
-    { name: 'local ref cleanup', progress },
-  );
-  const baseFastForward = await step(
-    () =>
-      stepBaseFastForward({
-        cwd,
-        baseBranch,
-        progress,
-        planFastForwardFn,
-        executeFastForwardFn,
-      }),
-    { name: 'base fast-forward', progress },
-  );
+  // Local-checkout mutations: serialized behind a best-effort cross-process
+  // lock (Story #4622). Acquire once, run both steps, release in `finally`.
+  const lockCfg = config?.delivery?.postLandLock ?? {};
+  const lock = await acquireLockWithWaitFn({
+    lockPath: postLandLockPath(cwd),
+    waitMs: lockCfg.waitMs,
+    pollMs: lockCfg.pollMs,
+    timeoutMs: lockCfg.timeoutMs,
+    ownerId: `post-land-${storyId}`,
+  });
+  if (!lock.acquired) {
+    // Never load-bearing: proceed anyway. The bounded wait already gave the
+    // concurrent holder its window; blocking the land on a lock we could not
+    // take would turn a best-effort damper into a false negative.
+    progress?.(
+      'POST-LAND',
+      `⚠️ post-land lock not acquired (${lock.reason}); proceeding unserialized.`,
+    );
+  }
+  let refCleanup;
+  let baseFastForward;
+  try {
+    refCleanup = await step(
+      () => stepRefCleanup({ cwd, storyBranch, progress, gitSpawnFn }),
+      { name: 'local ref cleanup', progress },
+    );
+    baseFastForward = await step(
+      () =>
+        stepBaseFastForward({
+          cwd,
+          baseBranch,
+          progress,
+          planFastForwardFn,
+          executeFastForwardFn,
+        }),
+      { name: 'base fast-forward', progress },
+    );
+  } finally {
+    if (lock.acquired) lock.release();
+  }
 
   const tail = {
     followUps: followUps.ok,

package/.agents/scripts/lib/orchestration/story-close/phases/local-lens-review.js

@@ -30,6 +30,58 @@ import { computeChangeSet } from '../../change-set.js';
  */
 const STORY_SCOPE_LENS_DEPTH = 'light';
 
+/**
+ * Render the host-MUST-walk roster of materialized lens-prompt artifacts
+ * (Story #4627). The Story-scope lens pass materializes each matched lens's
+ * substituted prompt body to a scoped artifact file; the default review
+ * provider is a mechanical sweep that never reads them, so the artifacts are
+ * inert unless the close's stdout tells the host to walk them. This mirrors
+ * the plan-run audit-roster comment's "host MUST walk each" contract
+ * (`run-epilogue.js`): the close names each artifact path and the host reads
+ * each one against the diff.
+ *
+ * Pure: derives the block from the `runAuditSuite` envelope's `workflows[]`,
+ * keeping only entries that actually wrote an artifact. Returns `null` when no
+ * artifact was written (nothing to walk), so the caller emits nothing.
+ *
+ * Module-local: an implementation detail of {@link runLocalLensReview}, whose
+ * host-MUST-walk output rides out on the `progress` stream. Exercised through
+ * that public entry point (assert the progress lines name each artifact path)
+ * rather than imported directly, so it adds no production-dead public export.
+ *
+ * @param {object|null} materialized the `runAuditSuite` result envelope.
+ * @returns {string|null} the roster block, or `null` when there is nothing to walk.
+ */
+function renderLensArtifactRoster(materialized) {
+  const paths = (materialized?.workflows ?? [])
+    .map((w) => w?.artifactPath)
+    .filter((p) => typeof p === 'string' && p.length > 0);
+  if (paths.length === 0) return null;
+  return [
+    `Lens prompts materialized (host MUST read/walk each against the Story diff):`,
+    ...paths.map((p) => `  - ${p}`),
+  ].join('\n');
+}
+
+/**
+ * Build the `runAuditSuite` substitutions for the Story-scope lens pass
+ * (Story #4627). Resolves the `{{changedFiles}}` token from the actual Story
+ * diff (newline-joined, the shape the lens templates' `## Scope` block reads)
+ * and the `{{ticketId}}` token from the Story id when known. Both are built-in
+ * substitution keys (`substitutions.js#BUILT_IN_SUBSTITUTION_KEYS`), so the
+ * runner accepts them without a per-lens `substitutionKeys` declaration.
+ *
+ * @param {{ changedFiles: string[], storyId?: number|string|null }} args
+ * @returns {Record<string, string>}
+ */
+function buildLensSubstitutions({ changedFiles, storyId }) {
+  const substitutions = { changedFiles: changedFiles.join('\n') };
+  if (storyId != null && `${storyId}`.length > 0) {
+    substitutions.ticketId = String(storyId);
+  }
+  return substitutions;
+}
+
 /**
  * Enumerate the files changed in the `baseRef...headRef` diff. Thin adapter over
  * the shared {@link computeChangeSet} enumerator (Story #4593) that flattens its
@@ -120,10 +172,20 @@ function resolveLensChangeSet({
  * for standalone callers that supply no list; see {@link resolveLensChangeSet}
  * for the three-state contract.
  *
+ * Story #4627 — the pass now delivers lens **content** to a reader. It threads
+ * `{{changedFiles}}` / `{{ticketId}}` substitutions and an `artifactPrefix`
+ * into `runAuditSuite` so each matched lens's substituted prompt body is
+ * written to a scoped artifact under the run's audit output dir, then emits a
+ * host-MUST-walk roster of those artifact paths to the close's stdout. Before
+ * this the default review provider dropped the materialized envelope, so the
+ * pass was a progress log line with no reader.
+ *
  * @param {{
  *   baseRef: string,
  *   headRef: string,
  *   changedFiles?: string[]|null,
+ *   storyId?: number|string|null,
+ *   artifactPrefix?: string,
  *   progress: (tag: string, msg: string) => void,
  *   progressTag?: string,
  *   gitSpawnFn?: import('../../change-set.js').GitSpawnFn,
@@ -135,12 +197,15 @@ function resolveLensChangeSet({
  *   lenses: string[],
  *   skipped: boolean,
  *   materialized: object|null,
+ *   artifactPaths: string[],
  * }>}
  */
 export async function runLocalLensReview({
   baseRef,
   headRef,
   changedFiles: injectedChangedFiles,
+  storyId,
+  artifactPrefix,
   progress,
   progressTag = 'CODE-REVIEW',
   gitSpawnFn = gitSpawn,
@@ -152,6 +217,7 @@ export async function runLocalLensReview({
     lenses: [],
     skipped: true,
     materialized: null,
+    artifactPaths: [],
   };
   try {
     const changedFiles = resolveLensChangeSet({
@@ -168,16 +234,30 @@ export async function runLocalLensReview({
       );
       return empty;
     }
-    const materialized = await runAuditSuiteFn({ auditWorkflows: lenses });
+    // Scope the artifact filenames to this Story so concurrent closes on a
+    // shared audit output dir cannot clobber each other's prompts.
+    const effectivePrefix =
+      artifactPrefix ?? (storyId != null ? `story-${storyId}` : 'story-scope');
+    const materialized = await runAuditSuiteFn({
+      auditWorkflows: lenses,
+      substitutions: buildLensSubstitutions({ changedFiles, storyId }),
+      artifactPrefix: effectivePrefix,
+    });
     progress(
       progressTag,
       `Ran ${lenses.length} local lens(es) at ${STORY_SCOPE_LENS_DEPTH} depth: ${lenses.join(', ')}.`,
     );
+    const roster = renderLensArtifactRoster(materialized);
+    if (roster) progress(progressTag, roster);
+    const artifactPaths = (materialized?.workflows ?? [])
+      .map((w) => w?.artifactPath)
+      .filter((p) => typeof p === 'string' && p.length > 0);
     return {
       depth: STORY_SCOPE_LENS_DEPTH,
       lenses,
       skipped: false,
       materialized,
+      artifactPaths,
     };
   } catch (err) {
     // The lens pass is advisory: a git or materialization failure must not

package/.agents/scripts/lib/orchestration/story-close/phases/review-core.js

@@ -110,6 +110,7 @@ export async function runStoryReviewCore({
     baseRef,
     headRef,
     changedFiles: changeSet.files,
+    storyId: storyIdNum,
     progress,
     progressTag,
     gitSpawnFn,