mandrel 2.59.0 → 2.61.0

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

@@ -1,24 +1,14 @@
 /**
- * phases/local-lens-review.js — the Story-scope local-lens pass.
- *
- * Extracted from `phases/code-review.js` (Story #4603) so the review spine and
- * the lens pass each carry one reason to change. The spine
- * (`runStoryReviewCore`) owns the single per-close-run diff enumeration and the
- * `runCodeReview` invocation; this module owns lens selection + materialization.
- *
- * Shift-left tier (Epic #4405): local concerns are cheap to decide on a single
- * Story's diff, so the maker-blind Story-scope review runs its matched local
- * lenses here, inside the story-close subprocess, rather than paying a deeper
- * pass at Epic close.
+ * phases/local-lens-review.js — the Story-scope local-lens pass: selects the
+ * local lenses matching the Story diff and materializes their prompts. The
+ * review spine (`runStoryReviewCore`) owns diff enumeration and code review.
  */
 
 import {
   evaluateLensDiffFloor,
-  resolveLensDiffFloor,
   runAuditSuite,
   selectLocalLenses,
 } from '../../../audit-suite/index.js';
-import { resolveConfig } from '../../../config-resolver.js';
 import { gitSpawn } from '../../../git-utils.js';
 import {
   emitRuntimeFriction,
@@ -26,35 +16,12 @@ import {
 } from '../../../observability/runtime-friction.js';
 import { computeChangeSet } from '../../change-set.js';
 
-/**
- * The review depth the Story-scope local-lens pass runs at. Fixed for this
- * tier — it is not risk-scaled like the code-review pillar depth.
- *
- * Module-local: it is an implementation detail of {@link runLocalLensReview}
- * (it rides out on the returned envelope's `depth` field), not a public seam.
- * Tests assert the observable `'light'` on that envelope rather than importing
- * the constant, so it stays off the public surface (Story #4603).
- */
+/** Fixed for this tier; not risk-scaled. */
 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.
+ * Roster of materialized lens-prompt artifacts the host MUST walk — the
+ * default review provider never reads them, so without this they are inert.
  *
  * @param {object|null} materialized the `runAuditSuite` result envelope.
  * @returns {string|null} the roster block, or `null` when there is nothing to walk.
@@ -71,12 +38,7 @@ function renderLensArtifactRoster(materialized) {
 }
 
 /**
- * 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.
+ * Built-in substitution keys, so no per-lens declaration is needed.
  *
  * @param {{ changedFiles: string[], storyId?: number|string|null }} args
  * @returns {Record<string, string>}
@@ -90,26 +52,14 @@ function buildLensSubstitutions({ changedFiles, storyId }) {
 }
 
 /**
- * Enumerate the files changed in the `baseRef...headRef` diff. Thin adapter over
- * the shared {@link computeChangeSet} enumerator (Story #4593) that flattens its
- * `files: string[]|null` envelope to this phase's historical `[]`-on-failure
- * contract: the lens roster treats "nothing changed" and "diff unknown"
- * identically, because an unknown diff matches no `filePatterns` and therefore
- * adds no lens work either way.
- *
- * Best-effort and total — never throws, mirroring the advisory posture of the
- * surrounding review phase. Retained as the self-enumeration fallback for
- * {@link runLocalLensReview} when no change set is injected.
+ * Never throws: an unknown diff returns `[]`, which matches no lens, same as
+ * an empty one.
  *
  * @param {{
  *   baseRef: string,
  *   headRef: string,
  *   gitSpawnFn?: import('../../change-set.js').GitSpawnFn,
  * }} args
- * Module-local (Story #4603): a private fallback of {@link runLocalLensReview},
- * exercised through that public entry point rather than imported directly, so it
- * adds no public export a production path fails to reach.
- *
  * @returns {string[]} Changed file paths, or `[]` on any failure.
  */
 function enumerateChangedFiles({ baseRef, headRef, gitSpawnFn = gitSpawn }) {
@@ -117,28 +67,9 @@ function enumerateChangedFiles({ baseRef, headRef, gitSpawnFn = gitSpawn }) {
 }
 
 /**
- * Resolve the change set the lens roster reads, honouring all THREE injection
- * states (Story #4603 — the fix for #4593's single-enumeration leak).
- *
- * The distinction between `null` and `undefined` is load-bearing and mirrors
- * the sibling contract in `orchestration/code-review.js#resolveInjectedChangedFiles`:
- *
- *   - **array**     — the caller's change set; use it verbatim.
- *   - **`null`**    — the caller (`runStoryReviewCore`) already tried and the
- *                     diff is unenumerable. Re-running git here would only fail
- *                     again, so degrade straight to the fail-safe empty roster.
- *   - **`undefined`** — nobody enumerated (standalone callers), so the shared
- *                     enumerator runs as the fallback.
- *
- * The prior `Array.isArray()` discriminator collapsed `null` and `undefined`
- * into one branch and re-spawned git on the unenumerable path, contradicting the
- * spine's documented "the one enumeration per close run" invariant.
- *
- * Module-local (Story #4603): a private detail of {@link runLocalLensReview}.
- * The three-state contract is asserted through that public entry point (does an
- * injected `null` re-spawn git? does `undefined` self-enumerate?), so it needs
- * no public export — keeping the fix from re-introducing the very kind of
- * production-dead public symbol this Story's ratchet root-cause is about.
+ * Three-state injection: an array is used verbatim; `null` means the spine
+ * already failed to enumerate, so don't re-spawn git; `undefined` means
+ * nobody enumerated, so self-enumerate.
  *
  * @param {{
  *   changedFiles: string[]|null|undefined,
@@ -161,40 +92,11 @@ function resolveLensChangeSet({
 }
 
 /**
- * Run the Story-scope local-lens pass: select the LOCAL-tier lenses whose
- * `filePatterns` match the actual Story diff (`baseRef...headRef`) and
- * materialize their lens-prompt bodies at `light` depth. Called only from
- * `runStoryReviewCore`, never in the delivering child's (maker's) context, so a
- * maker never grades its own work.
- *
- * A diff that matches no local lens adds **no** lens work: the roster is empty
- * and `runAuditSuite` is never invoked. Best-effort and total — a git or
- * materialization failure degrades to `{ skipped: true, lenses: [] }` and is
- * logged via `progress`, matching the advisory posture the review phase already
- * takes for provider/transport failures.
- *
- * Story #4593 — `changedFiles` is injected by `runStoryReviewCore`, which
- * computes the change set once per close run and hands the same list to this
- * pass and to `runCodeReview`. Self-enumeration is the **fallback only**, kept
- * 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.
- *
- * Story #4699 — the **lens diff-floor**. When the caller supplies a known
- * `changedLineCount` and the diff sits strictly below the configured floor
- * (`delivery.review.lensDiffFloor`, default 40) with zero sensitive-path
- * hits, the pass records the matched roster but skips materialization
- * entirely (`skipped: true` with the lenses retained and a `floorSkip`
- * verdict) — the maker-blind code-review pillar and every hard gate are
- * untouched. An unknown line count, a disabled floor, or a sensitive-path
- * hit all fail open to the full materialization.
+ * Run the maker-blind Story-scope lens pass (called only from
+ * `runStoryReviewCore`). No matching lens → no lens work. A diff below the
+ * lens diff-floor with no sensitive-path hits records the roster but skips
+ * materialization; an unknown line count fails open. Advisory: any failure
+ * degrades to a skipped envelope plus a friction signal.
  *
  * @param {{
  *   baseRef: string,
@@ -209,7 +111,6 @@ function resolveLensChangeSet({
  *   gitSpawnFn?: import('../../change-set.js').GitSpawnFn,
  *   selectLocalLensesFn?: typeof selectLocalLenses,
  *   runAuditSuiteFn?: typeof runAuditSuite,
- *   resolveConfigFn?: typeof resolveConfig,
  *   evaluateLensDiffFloorFn?: typeof evaluateLensDiffFloor,
  *   emitToolDegradationFn?: typeof emitRuntimeFriction,
  * }} args
@@ -235,7 +136,6 @@ export async function runLocalLensReview({
   gitSpawnFn = gitSpawn,
   selectLocalLensesFn = selectLocalLenses,
   runAuditSuiteFn = runAuditSuite,
-  resolveConfigFn = resolveConfig,
   evaluateLensDiffFloorFn = evaluateLensDiffFloor,
   emitToolDegradationFn = emitRuntimeFriction,
 }) {
@@ -263,16 +163,11 @@ export async function runLocalLensReview({
       return empty;
     }
 
-    // Lens diff-floor (Story #4699). Deliberately evaluated AFTER lens
-    // selection so a floor-skip still records WHICH lenses it skipped —
-    // the findings-yield ledger needs the roster either way.
+    // After selection so a floor-skip still records which lenses it skipped.
     const floorVerdict = evaluateLensDiffFloorFn({
       changedFiles,
       changedLineCount,
-      floor:
-        typeof lensDiffFloor === 'number'
-          ? lensDiffFloor
-          : resolveLensDiffFloor(safeResolveConfig(resolveConfigFn)),
+      floor: lensDiffFloor,
     });
     if (floorVerdict.skip) {
       progress(
@@ -290,8 +185,7 @@ export async function runLocalLensReview({
         artifactPaths: [],
       };
     }
-    // Scope the artifact filenames to this Story so concurrent closes on a
-    // shared audit output dir cannot clobber each other's prompts.
+    // Story-scoped names so concurrent closes can't clobber each other.
     const effectivePrefix =
       artifactPrefix ?? (storyId != null ? `story-${storyId}` : 'story-scope');
     const materialized = await runAuditSuiteFn({
@@ -317,10 +211,7 @@ export async function runLocalLensReview({
       artifactPaths,
     };
   } catch (err) {
-    // The lens pass is advisory: a git or materialization failure must not
-    // fail the close. Log, route the tool-execution degradation to friction
-    // telemetry (Story #4699 — degradations are operational signals, not
-    // findings), and degrade to a skipped envelope.
+    // Degradations are operational signals (friction), not findings.
     progress(
       progressTag,
       `⚠️ local lens pass failed (continuing without it): ${err?.message ?? err}`,
@@ -336,24 +227,8 @@ export async function runLocalLensReview({
         },
       });
     } catch {
-      // Observability must never fail the close (best-effort contract).
+      // Observability must never fail the close.
     }
     return empty;
   }
 }
-
-/**
- * Resolve config for the floor read without letting a resolver failure
- * fail the (advisory) lens pass. Module-local: a degraded config simply
- * yields the framework-default floor.
- *
- * @param {typeof resolveConfig} resolveConfigFn
- * @returns {object|undefined}
- */
-function safeResolveConfig(resolveConfigFn) {
-  try {
-    return resolveConfigFn();
-  } catch {
-    return undefined;
-  }
-}

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

@@ -1,13 +1,6 @@
 /**
- * phases/review-core.js — the shared Story-scope review spine.
- *
- * Extracted from the Epic-era `phases/code-review.js` (Story #4603) so the
- * spine belonged to neither close path. `runStoryReviewCore` is the one
- * implementation `runCodeReview` is called through; since Story #5006 retired
- * the Epic-attached phase, its sole caller is the v2 standalone path
- * (`single-story-close/phases/code-review.js#runStoryScopeReview`). It stays
- * here — the shared-spine contract (Story #3653) is what keeps the maker-blind
- * review invocation out of a phase file.
+ * phases/review-core.js — the shared Story-scope review spine; keeps the
+ * maker-blind `runCodeReview` invocation out of any phase file.
  */
 
 import { countChangedLines } from '../../../audit-suite/index.js';
@@ -18,35 +11,15 @@ import { runCodeReview } from '../../code-review.js';
 import { runLocalLensReview } from './local-lens-review.js';
 
 /**
- * Invoke `runCodeReviewFn` with the canonical Story-scope envelope and return
- * the raw result.
- *
- * The caller is responsible for error handling and result interpretation —
- * this function propagates throws rather than swallowing them, because the
- * two callers have different advisory postures:
- *
- *   - Epic-attached close: swallows throws (non-blocking advisory, same as
- *     `refresh.js`).
- *   - Standalone close: propagates throws (a review failure stops the close).
+ * Run the local-lens pass and `runCodeReview` over one change set and return
+ * the review result. Throws propagate; the caller picks the advisory posture.
+ * Review depth is derived by `runCodeReview` from the changed files and is
+ * input-only — it never alters the output envelope.
  *
- * Review depth is not passed in: `runCodeReview` derives it from the changed
- * files — their sensitive-path intersection plus their count (Story #4542, which
- * retired the planner-authored risk envelope this spine used to forward). Depth
- * remains an **input-only** signal: it tells the provider how thorough to be and
- * never alters the review's output envelope or the posted structured-comment
- * body.
- *
- * Story #4593 — this spine is the **single injection point** for the change set.
- * It enumerates `baseRef...headRef` exactly once via {@link computeChangeSet}
- * and threads the resulting list into both the local-lens pass and
- * `runCodeReview`, which otherwise each enumerated the diff for themselves. Both
- * consumers ultimately route through `deriveChangeLevel`, so feeding them one
- * list is what makes the lens roster and the review depth provably agree about
- * what changed — even when a commit lands between the two calls.
- *
- * Story #4603 — the invariant now holds on the failure path too: an unenumerable
- * diff injects an explicit `null`, and both consumers distinguish that from
- * `undefined` ("nobody enumerated") rather than re-spawning git.
+ * The diff is enumerated exactly once here and injected into both consumers,
+ * so lens roster and review depth agree on what changed even if a commit
+ * lands in between. An unenumerable diff injects `null` ("already tried"),
+ * which both consumers honour without re-spawning git.
  *
  * @param {{
  *   storyId: number|string,
@@ -63,10 +36,8 @@ import { runLocalLensReview } from './local-lens-review.js';
  *   countChangedLinesFn?: typeof countChangedLines,
  *   appendFindingsYieldFn?: typeof appendFindingsYield,
  * }} args
- * @returns {Promise<object>} Raw result envelope from `runCodeReview`, augmented
- *   with a `localLensReview` field carrying the Story-scope local-lens pass
- *   outcome (Epic #4405, Story #4409) and the `changeSet` this run computed
- *   (Story #4593).
+ * @returns {Promise<object>} The `runCodeReview` result plus
+ *   `localLensReview` and the computed `changeSet`.
  */
 export async function runStoryReviewCore({
   storyId,
@@ -85,17 +56,10 @@ export async function runStoryReviewCore({
 }) {
   const storyIdNum = Number(storyId);
 
-  // The one enumeration per close run. Every consumer below is injected from
-  // this list; none of them re-derives the diff. `files` is `null` when the
-  // diff is unenumerable — an explicit "already tried" signal both consumers
-  // honour without retrying (Story #4603).
   const changeSet = computeChangeSetFn({ baseRef, headRef, gitSpawnFn });
 
-  // The one changed-LINE enumeration (Story #4699 — the lens diff-floor's
-  // size signal). Probed only when the file enumeration succeeded with a
-  // non-empty set: a null/empty set already yields an empty lens roster, so
-  // a second git spawn would buy nothing. `null` = count unknown → the
-  // floor fails open (no skip).
+  // Line count for the lens diff-floor, probed only for a non-empty file set;
+  // `null` = unknown, and the floor fails open.
   const changedLineCount =
     Array.isArray(changeSet.files) && changeSet.files.length > 0
       ? countChangedLinesFn({ baseRef, headRef, gitSpawnFn })
@@ -118,11 +82,6 @@ export async function runStoryReviewCore({
     opts.commentTargetId = commentTargetId;
   }
 
-  // Shift-left local-lens pass (Epic #4405). Runs matched local lenses at
-  // `light` depth against the actual Story diff, inside this close-subprocess
-  // spine so the maker never grades its own work. Advisory — it never blocks
-  // the close and its outcome rides on the returned envelope for downstream
-  // consumers.
   const localLensReview = await runLocalLensReviewFn({
     baseRef,
     headRef,
@@ -136,9 +95,7 @@ export async function runStoryReviewCore({
 
   const result = await runCodeReviewFn(opts);
 
-  // Findings-yield ledger (Story #4699) — record what this close's lens
-  // pass produced (or floor-skipped) so the roster can later be tuned on
-  // measurement. Best-effort: a ledger failure never fails the review.
+  // Best-effort findings-yield ledger, for tuning the roster on measurement.
   try {
     const yieldEntries = buildLensYieldEntries(localLensReview);
     if (yieldEntries !== null) {
@@ -160,15 +117,7 @@ export async function runStoryReviewCore({
 }
 
 /**
- * Fold the lens-pass envelope into per-lens findings-yield entries
- * (Story #4699). One entry per lens in the matched roster: the lens name,
- * the count of materialization findings attributed to it, and whether the
- * diff-floor skipped its materialization. Returns `null` when the roster is
- * empty (nothing ran, nothing skipped — no record to write).
- *
- * Module-local: an implementation detail of {@link runStoryReviewCore},
- * asserted through the appended record's shape rather than imported
- * directly.
+ * One findings-yield entry per matched lens; `null` for an empty roster.
  *
  * @param {object|null|undefined} localLensReview
  * @returns {Array<{ lens: string, findings: number, skippedByFloor: boolean }>|null}

package/.agents/scripts/lib/orchestration/story-deliver-terminal-schema.js

@@ -1,30 +1,8 @@
 /**
- * story-deliver-terminal-schema.js — load `story-deliver-terminal.schema.json`
- * and validate envelopes against it.
- *
- * Split out of `story-deliver-terminal.js` so the envelope WRITER holds only
- * the contract's shape and vocabulary, and this module holds the one thing
- * the writer must never depend on at call time: the filesystem.
- *
- * That separation is the fix, not just tidiness. `single-story-close.js`
- * invoked by a *worktree-relative* path runs the Story worktree's own copy of
- * the script and then **reaps that worktree** as one of its phases. The schema
- * used to be read lazily, on the first envelope build — which happens after
- * the reap — so the read hit a path that no longer existed. The throw landed
- * inside the close CLI's error path, so a Story whose PR had merged, whose
- * label was `agent::done`, and whose post-land tail was green exited non-zero
- * emitting NO envelope at all: the delivery engine's documented return
- * contract lost to a success, recoverable only by a second close run from the
- * main checkout.
- *
- * Two guarantees close that, and both live here:
- *
- *   1. The schema is read and parsed ONCE, at module load. The parsed schema
- *      outlives the file, so what happens to the directory afterwards is
- *      irrelevant. Compilation stays lazy — it needs no filesystem — so an
- *      import costs one small read and nothing else.
- *   2. An unreadable schema DEGRADES validation rather than throwing. A
- *      schema violation still fails loudly; see {@link validateTerminalEnvelope}.
+ * Load `story-deliver-terminal.schema.json` and validate envelopes. The schema
+ * is read ONCE at module load: close may run from a worktree it later reaps,
+ * so a lazy read after the reap would lose the envelope. An unreadable schema
+ * degrades validation rather than throwing.
  */
 
 import fs from 'node:fs';
@@ -36,14 +14,6 @@ import addFormats from 'ajv-formats';
 
 const __dirname = path.dirname(fileURLToPath(import.meta.url));
 
-/**
- * Absolute path to the shipped schema — the SSOT this module reads.
- *
- * Module-private, like every other `SCHEMA_PATH` in the tree
- * (`validation-evidence.js`, `signal-validator.js`): the path is an
- * implementation detail of loading, and callers want the verdict, not the
- * location.
- */
 const SCHEMA_PATH = path.resolve(
   __dirname,
   '..',
@@ -54,9 +24,7 @@ const SCHEMA_PATH = path.resolve(
 );
 
 /**
- * Read and parse the shipped schema. Never throws: a read failure is recorded
- * on the returned source and degrades validation downstream, because importing
- * this module must never be what breaks a delivery.
+ * Never throws: importing this module must never break a delivery.
  *
  * @returns {{ schema: object|null, error: string|null }}
  */
@@ -71,28 +39,17 @@ function loadSchemaSource() {
   }
 }
 
-/**
- * The schema, read and parsed at module load. Deliberately eager — see the
- * module header for the failure that made it so.
- *
- * @type {{ schema: object|null, error: string|null }}
- */
+/** @type {{ schema: object|null, error: string|null }} */
 const SCHEMA_SOURCE = loadSchemaSource();
 
 /**
- * Compiled validators keyed by the source object they came from.
- *
- * A `WeakMap` rather than one module-level slot so an injected `schemaSource`
- * (the test seam) can never poison the validator the production path memoizes.
+ * Keyed by source so an injected test source never poisons production's.
  *
  * @type {WeakMap<object, Function>}
  */
 const VALIDATORS = new WeakMap();
 
 /**
- * Compile (once per source) and return the terminal-envelope validator, or
- * `null` when the source carries no usable schema.
- *
  * @param {{ schema: object|null }} source
  * @returns {Function|null}
  */
@@ -110,13 +67,8 @@ function getValidator(source) {
 let _unvalidatedWarned = false;
 
 /**
- * Announce — once per process — that an envelope is going out unvalidated.
- *
- * Written straight to stderr rather than through `Logger.warn` for the same
- * reason `emitTerminalEnvelope` bypasses `Logger.info`: the envelope itself is
- * unsuppressible, so the notice that one was not checked has to be too. Under
- * `AGENT_LOG_LEVEL=silent` a level-gated warning would vanish and the degrade
- * would be invisible.
+ * Once per process, straight to stderr: like the envelope itself, the notice
+ * must survive `AGENT_LOG_LEVEL=silent`.
  *
  * @param {string|null|undefined} error
  * @returns {void}
@@ -132,20 +84,12 @@ function warnUnvalidated(error) {
 }
 
 /**
- * Validate a candidate envelope against the shipped schema.
- *
- * When the schema is unavailable the result reports `validated: false` and
- * `valid: true` — a **deliberate degrade**, not an oversight. Losing the shape
- * check costs a guard against a malformed envelope; throwing here costs the
- * envelope entirely, and the envelope is the documented return contract of the
- * delivery engine. An unvalidated terminal a caller can act on beats no
- * terminal at all, so the unreadable-schema case degrades and says so on
- * stderr while a schema *violation* still fails loudly at the writer.
+ * With no schema: `valid: true, validated: false` — deliberately, since an
+ * unvalidated envelope beats none. A violation still fails at the writer.
  *
  * @param {object} envelope
  * @param {{ schemaSource?: { schema: object|null, error: string|null } }} [opts]
- *   `schemaSource` is a test seam — production always uses the eagerly loaded
- *   module-level source.
+ *   Test seam.
  * @returns {{ valid: boolean, errors: string[], validated: boolean }}
  */
 export function validateTerminalEnvelope(