mandrel 2.14.0 → 2.16.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';
@@ -356,7 +361,7 @@ function resolveRiskHeuristics(config = {}) {
 
 /**
  * Ceilings a seed's advisory complexity signals must fit for the plan
- * workflow to **suggest** `/deliver-light` at Gate #1 (Story #4741 R3 plan-side
+ * workflow to **suggest** the light path at Gate #1 (Story #4741 R3 plan-side
  * handshake). Framework constants, not operator knobs — mirroring the
  * conservative intent of `complexity-gate.js`'s `STORY_SHAPE_CEILINGS`
  * (small, mostly-additive, non-sensitive) but read against the *seed-time*
@@ -364,9 +369,14 @@ function resolveRiskHeuristics(config = {}) {
  *
  * The suggestion is **advisory only and never an automatic reroute**: it
  * surfaces at Gate #1 for the operator to decide, and under `--yes` it is
- * recorded on the envelope while planning proceeds unchanged. `/deliver-light`
- * is a sibling Story; these ceilings define the plan side of the routing
- * handshake independently of it.
+ * recorded on the envelope while planning proceeds unchanged.
+ *
+ * These ceilings are deliberately NOT the ones the light path itself applies
+ * (Story #4760). A confirmed suggestion routes into
+ * `workflows/helpers/deliver-light.md`, whose gate re-judges the *predicted
+ * shape* against `STORY_SHAPE_CEILINGS`. Two checks at two different stages:
+ * this one screens a seed, that one decides. Collapsing them would make a
+ * confirm a bypass.
  *
  *   - `maxArtifacts`           — enumerated seed items (one artifact each).
  *   - `maxRiskHeuristicHits`   — any risk-heuristic hit disqualifies: risk
@@ -381,9 +391,9 @@ const DELIVER_LIGHT_SUGGESTION_CEILINGS = Object.freeze({
 });
 
 /**
- * Derive the advisory `/deliver-light` suggestion from a seed's complexity
- * signals (Story #4741 AC-6). Pure and total: a malformed / missing signal
- * bag fails conservative (not suggested), never throws.
+ * Derive the advisory light-path suggestion from a seed's complexity signals
+ * (Story #4741 AC-6). Pure and total: a malformed / missing signal bag fails
+ * conservative (not suggested), never throws.
  *
  * `automatic: false` is part of the contract — the suggestion is surfaced for
  * the operator, never a silent reroute of a non-interactive run.
@@ -435,27 +445,198 @@ export function buildDeliverLightSuggestion(complexitySignals) {
     ceilings,
     reasons: suggested
       ? [
-          `seed fits the /deliver-light ceilings (≤${ceilings.maxArtifacts} artifacts, ` +
+          `seed fits the light-path ceilings (≤${ceilings.maxArtifacts} artifacts, ` +
             'no risk-heuristic hits, no sensitive-path classes) — the operator ' +
-            'may prefer /deliver-light for this scope',
+            'may prefer /deliver for this scope',
         ]
       : reasons,
   };
 }
 
 /**
- * Attach the advisory `/deliver-light` 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 }),
   };
 }
 
@@ -696,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,
@@ -858,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,
@@ -920,7 +1104,7 @@ function extractPriorArtifacts(priorBody) {
 /**
  * Build the amendment (delta) envelope — `plan-context --amends #<id>`
  * (Story #4741 AC-4, R3-A). The heavy-amendment counterpart to routing a
- * light amendment through `/deliver-light`: instead of re-interrogating the
+ * light amendment through the light path: instead of re-interrogating the
  * repo from scratch (`buildAuthoringContext`'s codebase snapshot and the BDD /
  * memory / feedback probes), the envelope composes a DELTA from what already
  * exists — the prior Story's body, its acceptance criteria (the real
@@ -983,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/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

@@ -137,22 +137,31 @@ 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,
+    });
+  } 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;