mandrel 2.15.0 → 2.17.0

package/.agents/scripts/lib/orchestration/plan-context.js

@@ -18,6 +18,11 @@
  */
 
 import { readFile } from 'node:fs/promises';
+import { readAuditRulesSync } from '../audit-suite/audit-rules-reader.js';
+import {
+  hasWebSurface,
+  matchesAnyFilePattern,
+} from '../audit-suite/selector.js';
 import { getLimits } from '../config-resolver.js';
 import { findSimilarOpenStories } from '../duplicate-search.js';
 import { Logger } from '../Logger.js';
@@ -449,18 +454,189 @@ export function buildDeliverLightSuggestion(complexitySignals) {
 }
 
 /**
- * Attach the advisory light-path suggestion to a complexity-signals bag
- * as a **nested** field (Story #4741). Nesting — rather than a new top-level
- * envelope key — keeps every existing per-mode envelope key set byte-stable
- * (AC-5): the suggestion is derived from the signals it rides on.
+ * The `audit-rules.json` lens `target` value marking a lens applicable only to
+ * a project with a rendered frontend.
+ */
+const WEB_LENS_TARGET = 'web';
+
+/**
+ * How many matched UI paths the `uiSurface` signal carries. The signal rides the
+ * `--out` stdout digest, which has a ~2KB contract, and a seed can predict up to
+ * `MAX_PREDICTED_PATHS` paths — enumerating all of them would let one UI-heavy
+ * seed blow that budget. The full count travels beside the sample as
+ * `matchedPathCount`, so nothing is silently lost.
+ */
+const UI_MATCHED_PATH_SAMPLE = 5;
+
+/**
+ * Union of the `triggers.filePatterns` globs every `target: "web"` lens
+ * registers in `audit-rules.json` — the framework's shipped declaration of
+ * "this path is part of a rendered UI surface". Read from the manifest rather
+ * than re-listed here: a second copy of the glob set would be a second thing to
+ * keep in sync, and the manifest is already the place an operator extends it.
+ *
+ * @param {{ audits?: Record<string, object> }} rules
+ * @returns {string[]} Deduplicated globs, in manifest order.
+ */
+function resolveWebFilePatterns(rules) {
+  const patterns = new Set();
+  for (const entry of Object.values(rules?.audits ?? {})) {
+    if (entry?.target !== WEB_LENS_TARGET) continue;
+    for (const glob of entry?.triggers?.filePatterns ?? []) {
+      if (typeof glob === 'string' && glob !== '') patterns.add(glob);
+    }
+  }
+  return [...patterns];
+}
+
+/**
+ * Which predicted paths sit on a UI surface, per the web lens globs.
+ *
+ * An unreadable manifest is **indeterminate**, not "no match": the signal fails
+ * OPEN in the same direction {@link hasWebSurface} does, because a spurious
+ * mention of an operator-invoked command costs nothing while a missed one costs
+ * the whole point of the offer.
+ *
+ * @param {string[]} predictedPaths
+ * @returns {{ matchedPaths: string[], indeterminate: boolean }}
+ */
+function resolveWebFootprintMatch(predictedPaths) {
+  let patterns;
+  try {
+    patterns = resolveWebFilePatterns(readAuditRulesSync());
+  } catch {
+    return { matchedPaths: [], indeterminate: true };
+  }
+  return {
+    matchedPaths: predictedPaths.filter((p) =>
+      matchesAnyFilePattern(patterns, [p]),
+    ),
+    indeterminate: false,
+  };
+}
+
+/**
+ * The one sentence a `uiSurface` signal carries — why the offer fires, or why it
+ * does not. Kept in one place so the fired and unfired shapes stay one object.
+ *
+ * @param {{
+ *   detected: boolean,
+ *   webSurface: boolean,
+ *   indeterminate: boolean,
+ *   sample: string[],
+ *   count: number,
+ * }} facts
+ * @returns {string}
+ */
+function uiSurfaceReason({
+  detected,
+  webSurface,
+  indeterminate,
+  sample,
+  count,
+}) {
+  if (!detected) {
+    return webSurface
+      ? 'no predicted path matches a web lens filePattern — nothing to prototype'
+      : 'project has no rendered web surface — nothing to prototype';
+  }
+  if (indeterminate) {
+    return 'web-capable project and the UI-path manifest could not be read — offering /prototype rather than dropping the option';
+  }
+  const elided = count - sample.length;
+  const shown =
+    elided > 0 ? `${sample.join(', ')}, +${elided} more` : sample.join(', ');
+  return `web-capable project and the predicted footprint touches ${count} UI path(s) (${shown}) — the operator may want /prototype before UI acceptance criteria are authored`;
+}
+
+/**
+ * Derive the advisory **UI-surface** signal from a seed's predicted footprint.
+ *
+ * Two observables, both already shipped, ANDed together:
+ *
+ *   1. the project is web-capable at all (`hasWebSurface` — the same
+ *      applicability predicate the `target: "web"` audit lenses gate on), and
+ *   2. at least one predicted path matches a web lens `filePattern`.
+ *
+ * No new detection surface and no new `.agentrc.json` key: both halves are
+ * derived from the consumer's own checkout, so a frontend-less project — this
+ * repository included — resolves falsey and the offer never fires.
+ *
+ * The signal carries **no routing authority** (`automatic: false`): `/plan`
+ * may say that a plan touches UI and that `/prototype` exists, and must never
+ * invoke it. Pure over its inputs and total — a malformed signal bag or an
+ * unreadable manifest degrades, never throws.
+ *
+ * @param {{
+ *   complexitySignals?: object|null,
+ *   config?: object,
+ *   cwd?: string,
+ * }} [args]
+ * @returns {{
+ *   detected: boolean,
+ *   automatic: false,
+ *   advisory: true,
+ *   webSurface: boolean,
+ *   matchedPaths: string[],
+ *   matchedPathCount: number,
+ *   reasons: string[],
+ * }} `matchedPaths` is a bounded sample
+ *   ({@link UI_MATCHED_PATH_SAMPLE}); `matchedPathCount` is the full total.
+ */
+function buildUiSurfaceSignal({ complexitySignals, config, cwd } = {}) {
+  const predictedPaths = Array.isArray(complexitySignals?.predictedPaths)
+    ? complexitySignals.predictedPaths.filter((p) => typeof p === 'string')
+    : [];
+  const projectRoot =
+    typeof cwd === 'string' && cwd !== '' ? cwd : process.cwd();
+
+  let webSurface;
+  try {
+    webSurface = hasWebSurface({ config, projectRoot });
+  } catch {
+    webSurface = true; // indeterminate ⇒ fail open
+  }
+
+  const { matchedPaths, indeterminate } =
+    resolveWebFootprintMatch(predictedPaths);
+  const detected = webSurface && (indeterminate || matchedPaths.length > 0);
+  const sample = matchedPaths.slice(0, UI_MATCHED_PATH_SAMPLE);
+
+  return {
+    detected,
+    automatic: /** @type {const} */ (false),
+    advisory: /** @type {const} */ (true),
+    webSurface,
+    matchedPaths: sample,
+    matchedPathCount: matchedPaths.length,
+    reasons: [
+      uiSurfaceReason({
+        detected,
+        webSurface,
+        indeterminate,
+        sample,
+        count: matchedPaths.length,
+      }),
+    ],
+  };
+}
+
+/**
+ * Attach the advisory routing/offer signals to a complexity-signals bag as
+ * **nested** fields (Story #4741). Nesting — rather than new top-level envelope
+ * keys — keeps every existing per-mode envelope key set byte-stable: both are
+ * derived from the signals they ride on.
  *
  * @param {object} complexitySignals
- * @returns {object} the same signals plus `deliverLightSuggestion`.
+ * @param {{ config?: object, cwd?: string }} [context]
+ * @returns {object} the same signals plus `deliverLightSuggestion` and
+ *   `uiSurface`.
  */
-function withDeliverLightSuggestion(complexitySignals) {
+function withAdvisorySignals(complexitySignals, { config, cwd } = {}) {
   return {
     ...complexitySignals,
     deliverLightSuggestion: buildDeliverLightSuggestion(complexitySignals),
+    uiSurface: buildUiSurfaceSignal({ complexitySignals, config, cwd }),
   };
 }
 
@@ -701,14 +877,16 @@ async function buildSeedFileModeEnvelope({
     // authority. The planner authors the trivial-vs-standard verdict; persist
     // validates a lite claim against the authored Story's shape. The nested
     // `deliverLightSuggestion` is the advisory plan-side routing handshake
-    // (Story #4741 AC-6) — never an automatic reroute.
-    complexitySignals: withDeliverLightSuggestion(
+    // (Story #4741 AC-6) and `uiSurface` the advisory /prototype offer —
+    // neither is ever an automatic reroute.
+    complexitySignals: withAdvisorySignals(
       buildComplexitySignals({
         seedText: content,
         config,
         riskHeuristics: heuristics,
         cwd,
       }),
+      { config, cwd },
     ),
     duplicates,
     docsContext,
@@ -863,13 +1041,14 @@ async function buildTicketsModeEnvelope({
     mode: 'tickets',
     sourceTickets,
     seed: { text: seed, path: null },
-    complexitySignals: withDeliverLightSuggestion(
+    complexitySignals: withAdvisorySignals(
       buildComplexitySignals({
         seedText: seed,
         config,
         riskHeuristics: heuristics,
         cwd,
       }),
+      { config, cwd },
     ),
     duplicates,
     docsContext,
@@ -988,13 +1167,14 @@ async function buildAmendmentModeEnvelope({
     },
     // The prior body is the seed the delta is authored against.
     seed: { text: priorBody, path: null },
-    complexitySignals: withDeliverLightSuggestion(
+    complexitySignals: withAdvisorySignals(
       buildComplexitySignals({
         seedText: priorBody,
         config,
         riskHeuristics: heuristics,
         cwd,
       }),
+      { config, cwd },
     ),
     duplicates,
     // No plan temp dir and no from-scratch repo interrogation — the prior

package/.agents/scripts/lib/orchestration/single-story-close/failed-terminal.js

@@ -0,0 +1,122 @@
+/**
+ * single-story-close/failed-terminal.js — the `failed` terminal a close
+ * emits when a phase crashes, and the gate reconstruction it carries.
+ *
+ * Split out of `single-story-close.js` so the CLI entry stays an entry: it
+ * parses args, dispatches the runner, and maps a terminal onto an exit code.
+ * The reasoning about which gates had run by the time a phase died belongs
+ * with the envelope it feeds, not in the file that owns process lifetime.
+ *
+ * The runner deliberately throws rather than returning a failure (a red gate
+ * must not look like a return value), so without this the most common
+ * non-happy ending — a failing close-validation gate — would emit **no
+ * envelope at all**, exiting 1 with only a stderr line while the workflow
+ * docs promise the agent a `failed` envelope naming the phase.
+ */
+
+import { Logger } from '../../Logger.js';
+import {
+  buildTerminalEnvelope,
+  NEXT_COMMANDS,
+} from '../story-deliver-terminal.js';
+
+/**
+ * The close pipeline's phase order, as `setPhase` walks it. Only used to
+ * decide whether a gate had already run when a later phase died.
+ */
+const PHASE_ORDER = Object.freeze([
+  'init',
+  'wrong-tree-guard',
+  'close-validation',
+  'base-sync',
+  'push',
+  'pull-request',
+  'code-review',
+  'auto-merge',
+  'confirm-merge',
+  'post-land',
+  'done',
+]);
+
+/** Each reported gate and the pipeline phase that decides it. */
+const GATE_PHASES = Object.freeze([
+  ['validation', 'close-validation'],
+  ['baseSync', 'base-sync'],
+  ['codeReview', 'code-review'],
+]);
+
+/**
+ * Report every gate's outcome for a run that died at `phase`.
+ *
+ * The schema's contract: "A gate the run skipped … reports `skipped` rather
+ * than being omitted, so a missing gate is never mistaken for a passing one."
+ * The previous shape named only the gate that died and omitted the rest
+ * entirely — exactly the ambiguity the contract forbids.
+ *
+ * Reconstructed from the phase order, which is sound because the pipeline is
+ * strictly sequential: reaching phase N means every gate before it completed.
+ * A gate whose phase the run never reached is `skipped`; one the operator
+ * turned off via `--skip-validation` / `--skip-sync` is `skipped` too (it did
+ * not pass — it never ran).
+ *
+ * @param {string} phase The phase the run died in.
+ * @param {{ skipValidation?: boolean, skipSync?: boolean }} args Parsed CLI args.
+ * @returns {Record<string, 'passed'|'failed'|'skipped'>}
+ */
+export function gatesForFailedPhase(phase, args = {}) {
+  const skipped = { validation: args.skipValidation, baseSync: args.skipSync };
+  const failedAt = PHASE_ORDER.indexOf(phase);
+  const gates = {};
+  for (const [gate, gatePhase] of GATE_PHASES) {
+    const at = PHASE_ORDER.indexOf(gatePhase);
+    if (gatePhase === phase) gates[gate] = 'failed';
+    else if (failedAt < 0 || at > failedAt) gates[gate] = 'skipped';
+    else gates[gate] = skipped[gate] ? 'skipped' : 'passed';
+  }
+  return gates;
+}
+
+/**
+ * Build the `failed` terminal for a phase that crashed. Every close
+ * invocation emits exactly one envelope; this is the path that keeps that
+ * true when a phase dies.
+ *
+ * `err.closePhase` is tagged by the runner's phase tracker.
+ *
+ * **Never throws.** This runs on the path that already has one failure in
+ * hand, so a second failure here must not REPLACE the first: an
+ * envelope-build error surfacing as the run's cause sends the operator to
+ * diagnose the wrong thing entirely — a close whose PR had already merged
+ * once reported a schema `ENOENT` as its fatal error, because the worktree
+ * holding the script had been reaped mid-run. On failure this returns null
+ * and the caller rethrows the original.
+ *
+ * @param {unknown} err
+ * @param {{ storyId?: string|number, skipValidation?: boolean, skipSync?: boolean }} args
+ *   Parsed CLI args — the story id the envelope reports on, plus the skip
+ *   flags `gatesForFailedPhase` needs.
+ * @returns {object|null} A validated envelope, or null when even the story id
+ *   is unknown (a usage error — there is nothing to report an envelope about)
+ *   or the envelope itself could not be assembled.
+ */
+export function failedTerminalFor(err, args = {}) {
+  const phase = err?.closePhase ?? 'init';
+  const storyId = Number(args.storyId);
+  if (!Number.isInteger(storyId) || storyId <= 0) return null;
+  try {
+    return buildTerminalEnvelope({
+      storyId,
+      status: 'failed',
+      phase,
+      gates: gatesForFailedPhase(phase, args),
+      failure: { reason: String(err?.message ?? err) },
+      nextCommand: NEXT_COMMANDS.recover(storyId),
+      elapsedSeconds: 0,
+    });
+  } catch (buildErr) {
+    Logger.error(
+      `[single-story-close] ⚠️ Could not assemble the failed terminal envelope: ${buildErr?.message ?? buildErr}. Reporting the original failure instead.`,
+    );
+    return null;
+  }
+}

package/.agents/scripts/lib/orchestration/single-story-close/gate-log.js

@@ -36,6 +36,24 @@
  * The sink never throws. A log directory that cannot be written degrades to
  * inline streaming — losing the size bound is strictly better than losing the
  * gate output that says why a close failed.
+ *
+ * ## Why the artifact is written asynchronously (Story #4766)
+ *
+ * This sink is the `log` callable that `close-validation/process.js` invokes
+ * from inside the gate child's stdout/stderr `'data'` handler — once per line.
+ * The first cut wrote each line with `fs.writeSync`, which blocks the event
+ * loop while the child keeps writing: the OS pipe buffer fills, the child's
+ * write fails with `EAGAIN`, and a child that does not tolerate that dies. On
+ * a clean `main` `biome ci .` already emits ~625 lines, and it aborts with
+ * exit 101 (a `biome_console` panic, not a lint violation) when it happens —
+ * so the first gate of any close could die on plumbing while its verdict was
+ * green.
+ *
+ * So the write path buffers into an async stream instead: per-line work is
+ * O(1) and never touches a syscall on the drain path. The cost is that the
+ * artifact is not on disk the instant a line is logged, which is why the sink
+ * exposes {@link GateLogSink#flush} — callers await it before reading,
+ * replaying, or naming the artifact as final.
  */
 
 import nodeFs from 'node:fs';
@@ -65,9 +83,9 @@ function logNameFor(storyId) {
  */
 class GateLogSink {
   /**
-   * @param {{ logPath: string|null, streamInline: boolean, write: (line: string) => void, emit: (line: string) => void }} args
+   * @param {{ logPath: string|null, streamInline: boolean, write: (line: string) => void, flush?: () => Promise<void>, emit: (line: string) => void }} args
    */
-  constructor({ logPath, streamInline, write, emit }) {
+  constructor({ logPath, streamInline, write, flush, emit }) {
     /** Absolute path of the artifact, or `null` when capture is unavailable. */
     this.logPath = logPath;
     /** Whether lines are ALSO echoed inline as they arrive. */
@@ -75,6 +93,7 @@ class GateLogSink {
     /** Number of lines captured so far. */
     this.lineCount = 0;
     this._write = write;
+    this._flush = flush ?? (() => Promise.resolve());
     this._emit = emit;
     this._tail = [];
   }
@@ -96,6 +115,19 @@ class GateLogSink {
     };
   }
 
+  /**
+   * Settle the artifact: wait for every buffered line to reach disk and close
+   * the file. Idempotent, never throws, and a no-op on the degraded (no
+   * artifact) path. Await it before reading {@link GateLogSink#logPath} or
+   * handing the path to anyone — the write path is async precisely so it never
+   * stalls a gate child's pipe.
+   *
+   * @returns {Promise<void>}
+   */
+  flush() {
+    return this._flush();
+  }
+
   /**
    * The success-path digest: one line, no gate output. Names the artifact so
    * the caller can open it on demand rather than carrying it all session.
@@ -129,6 +161,50 @@ class GateLogSink {
   }
 }
 
+/**
+ * Wrap an already-open artifact fd in a non-blocking line writer.
+ *
+ * `write` hands the line to a `fs.WriteStream` — O(1), no syscall on the
+ * caller's stack — and `flush` ends the stream, resolving once every buffered
+ * line has reached disk (or the stream has errored; a half-written artifact is
+ * still better than a dead close). Both are best-effort by construction: the
+ * stream's `'error'` is absorbed, so nothing here can abort a close.
+ *
+ * @param {typeof nodeFs} fs
+ * @param {string} logPath
+ * @param {number} handle
+ * @returns {{ write: (line: string) => void, flush: () => Promise<void> }}
+ */
+function createArtifactWriter(fs, logPath, handle) {
+  const stream = fs.createWriteStream(logPath, { fd: handle, autoClose: true });
+  stream.on('error', () => {
+    /* best-effort: a mid-run write failure must not abort the close */
+  });
+  let ending = null;
+  return {
+    write: (line) => {
+      if (ending) return;
+      try {
+        stream.write(`${line}\n`);
+      } catch {
+        /* best-effort: see above */
+      }
+    },
+    flush: () => {
+      ending ??= new Promise((resolve) => {
+        const settle = () => resolve();
+        stream.once('error', settle);
+        try {
+          stream.end(settle);
+        } catch {
+          settle();
+        }
+      });
+      return ending;
+    },
+  };
+}
+
 /**
  * Build the gate-output sink for one close run.
  *
@@ -155,14 +231,14 @@ export function createGateLogSink({
   const verbose = (level ?? resolveLevel()) === 'verbose';
   const dir = logDir ?? path.join(cwd, 'temp', 'orchestration');
 
-  let handle = null;
+  let writer = null;
   let logPath = null;
   try {
     fs.mkdirSync(dir, { recursive: true });
     logPath = path.join(dir, logNameFor(storyId));
     // Truncate: each close run owns its artifact outright, so a re-run never
     // hands the reader a file interleaving two runs' gates.
-    handle = fs.openSync(logPath, 'w');
+    writer = createArtifactWriter(fs, logPath, fs.openSync(logPath, 'w'));
   } catch {
     // No artifact — fall back to inline streaming rather than dropping the
     // gate output on the floor.
@@ -174,13 +250,11 @@ export function createGateLogSink({
     });
   }
 
-  const write = (line) => {
-    try {
-      fs.writeSync(handle, `${line}\n`);
-    } catch {
-      /* best-effort: a mid-run write failure must not abort the close */
-    }
-  };
-
-  return new GateLogSink({ logPath, streamInline: verbose, write, emit });
+  return new GateLogSink({
+    logPath,
+    streamInline: verbose,
+    write: writer.write,
+    flush: writer.flush,
+    emit,
+  });
 }

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

@@ -33,6 +33,13 @@
  * needs the evidence in front of them. `AGENT_LOG_LEVEL=verbose` restores
  * live streaming.
  *
+ * Projection advisories (Story #4776). `baseBranch`, `storyBranch` and the
+ * resolved `config` are forwarded to `runCloseValidation` so its projection
+ * phase can run. They surface, after the gates pass, which committed
+ * baseline rows the post-merge tree would breach and the exact
+ * `*:update` + `baseline-refresh:` remedy — advisory only, so the close
+ * verdict is unchanged.
+ *
  * `runCloseValidation`, `buildDefaultGates`, and `runScopedFormatAutofix`
  * are accepted as injected dependencies so the parent CLI's cache-busted
  * bindings win in tests that mock the upstream module URLs.
@@ -137,22 +144,38 @@ export async function runCloseValidationPhase({
   // Story #4736 — one sink for both `log` seams (gate construction and gate
   // execution), so nothing in the chain can route around the artifact.
   const gateLog = createGateLogSink({ storyId, cwd });
-  const validation = await runCloseValidation({
-    cwd,
-    worktreePath,
-    gates: buildDefaultGates({
-      config,
-      baseBranch,
-      cwd: worktreePath || cwd,
+  let validation;
+  try {
+    validation = await runCloseValidation({
+      cwd,
+      worktreePath,
+      gates: buildDefaultGates({
+        config,
+        baseBranch,
+        cwd: worktreePath || cwd,
+        log: gateLog.log,
+      }),
       log: gateLog.log,
-    }),
-    log: gateLog.log,
-    storyId,
-    // Story #4250 — standalone storyId-anchored evidence keyspace. No
-    // epicId; the standalone flag routes the cache to
-    // temp/standalone/stories/story-<id>/validation-evidence.json.
-    standalone: true,
-  });
+      storyId,
+      // Story #4250 — standalone storyId-anchored evidence keyspace. No
+      // epicId; the standalone flag routes the cache to
+      // temp/standalone/stories/story-<id>/validation-evidence.json.
+      standalone: true,
+      // Story #4776 — the branch pair and resolved config the advisory
+      // projections need. Without them the runner skips the projection
+      // phase entirely, which is the correct behaviour for resume/legacy
+      // callers that have no story branch to diff.
+      baseBranch,
+      storyBranch,
+      config,
+    });
+  } finally {
+    // Story #4766 — gate lines are buffered to an async stream so the drain
+    // never blocks a gate child's pipe. Settle the artifact before anything
+    // reads it, replays from it, or reports its path — including on the throw
+    // path, where the artifact is the only surviving record.
+    await gateLog.flush();
+  }
   if (!validation.ok) {
     const [first] = validation.failed;
     const { gate, status, cwd: gateCwd } = first;