mandrel 2.15.0 → 2.16.0

package/.agents/docs/workflows.md

@@ -32,7 +32,7 @@ by `node .agents/scripts/generate-workflows-doc.js`; `npm run docs:check`
 fails when it drifts from the on-disk workflow set. To change a command’s
 description, edit the workflow file’s front-matter and regenerate.
 
-## Commands (24)
+## Commands (25)
 
 | Command | Description |
 | --- | --- |
@@ -57,6 +57,7 @@ description, edit the workflow file’s front-matter and regenerate.
 | `/git-deliver` | Single ad-hoc delivery command for working-tree changes. Detects the git setup and escalates to the right terminal step — commit only, commit + push, or commit + push + open a PR with native auto-merge — picking the default from observable state and letting flags pin any level explicitly. Replaces the retired git-commit-all, git-push, and git-pr-all trio. |
 | `/mandrel-update` | npm-era upgrade wraparound for a Mandrel consumer. Runs `npx mandrel update` (resolve newest published version → install → re-materialize `.agents/` → migrate → doctor → surface changelog) as the single mechanical step, then walks the operator through the judgment wraparound the CLI deliberately leaves unowned: reconcile `.agentrc.json`, install the stabilized quality-gate surface, refresh the harness permission allowlist, reconcile the consumer's `AGENTS.md` / runbooks against the surfaced changelog, and stage + commit the staged lockfile bump. |
 | `/plan` | Unified planning entry point. Interrogate → author → persist. Emits one Story by default; splits into N>1 only under the default-single split policy. |
+| `/prototype` | Operator-invoked UI prototype pass. Discovers the consumer's design-system SSOT first, then — only after the operator confirms — writes exactly one self-contained HTML file under the gitignored workspace-root temp tree, so a layout can be reviewed before its UI acceptance criteria are authored. |
 | `/qa-assist` | Human-led QA assist loop — set up, then ride a rolling multi-observation intake session. The operator reports observations in any order; the agent enriches each (repro + root-cause file:line + coverage verdict for bugs; analysis + options + recommendation for enhancements), asks clarifying questions only when ambiguous, and appends a redacted ledger item — recording, never planning — to a persistent, resumable session under temp/qa/. Only when the operator says they are done does it review the full ledger and hand off to /plan. |
 | `/qa-explore` | Agent-led exploratory-QA loop — the agent Plans a surface with an explicit static-vs-drive method choice, drives it (browser MCP or static), and captures ledger items read-only, then Triages — a bounded per-surface session, HITL-gated at every phase transition, routed through the shared dedup/coverage/classification/missing-test/redaction/session core under temp/qa/ |
 | `/qa-run` | Drive Gherkin scenarios through a real browser as an agent-driven QA sweep |

package/.agents/scripts/deliver-light.js

@@ -79,18 +79,29 @@ import { createProvider } from './lib/provider-factory.js';
 const HELP = `\
 Usage:
   deliver-light.js --prompt <text> [--creates csv] [--refactors csv]
-                   [--acceptance n] [--route lite|full] [--reason <text>]
+                   [--acceptance n] [--kinds csv] [--magnitude m]
+                   [--uncertainty u] [--route lite|full] [--reason <text>]
                    [--amends '#id'] [--yes]
   deliver-light.js --backstop --story <id>
 
 The thin /deliver-light entry point: suitability gate → inline receipt Story →
 the same single-story-init.js / single-story-close.js engine /deliver uses.
 
+The gate judges EFFORT and RISK, not artifact counts: N instances of one
+mechanical edit is one kind at N sites. It rejects only clearly-epic work; the
+--backstop pass enforces size against the actual diff.
+
 Gate options:
   --prompt <text>    Operator prompt describing the change. Required for the gate.
   --creates <csv>    Predicted NEW file paths (comma-separated).
   --refactors <csv>  Predicted edited/existing file paths (comma-separated).
-  --acceptance <n>   Predicted acceptance-criteria count (default 1).
+  --acceptance <n>   Predicted acceptance-criteria count (default 1). Not capped.
+  --kinds <csv>      Distinct KINDS of change (default: one per assumption, so
+                     N same-shaped edits count once).
+  --magnitude <m>    Coarse effort bucket: trivial | moderate | substantial
+                     (default moderate; substantial routes to /plan).
+  --uncertainty <u>  determined (the request fixes the shape) | needs-design
+                     (default determined; needs-design routes to /plan).
   --route <r>        Ledgered model verdict route: lite | full.
   --reason <text>    Recorded reason for a lite verdict (required for lite).
   --amends <#id>     Mark this as an amendment of an existing issue.
@@ -166,17 +177,25 @@ export function synthesizeAcceptance(count) {
  *   creates?: string[],
  *   refactors?: string[],
  *   acceptance?: number,
+ *   kinds?: string[],
+ *   magnitude?: string,
+ *   uncertainty?: string,
  *   route?: string,
  *   reason?: string,
  *   yes?: boolean,
  *   injectedRules?: object,
- * }} args
+ * }} args `kinds` / `magnitude` / `uncertainty` are the declared effort-and-risk
+ *   axes the gate judges (Story #4764); omitting them declares no signal, not a
+ *   small one — an unrecognized bucket fails closed.
  * @returns {{ action: string, suitability: object, outcome: object }}
  */
 export function runLightGate({
   creates = [],
   refactors = [],
   acceptance,
+  kinds,
+  magnitude,
+  uncertainty,
   route,
   reason,
   yes = false,
@@ -186,6 +205,9 @@ export function runLightGate({
   const suitability = deriveLightSuitability({
     predictedChanges,
     predictedAcceptance: synthesizeAcceptance(acceptance),
+    predictedKinds: kinds,
+    predictedMagnitude: magnitude,
+    predictedUncertainty: uncertainty,
     verdict: { route, reason },
     injectedRules,
   });
@@ -355,6 +377,9 @@ export async function runGateMode(values, deps = {}) {
     acceptance: values.acceptance
       ? Number.parseInt(String(values.acceptance), 10)
       : 1,
+    kinds: parseCsvPaths(values.kinds),
+    magnitude: values.magnitude,
+    uncertainty: values.uncertainty,
     route: values.route,
     reason: values.reason,
     yes: values.yes === true,
@@ -417,6 +442,9 @@ async function main() {
       creates: { type: 'string' },
       refactors: { type: 'string' },
       acceptance: { type: 'string' },
+      kinds: { type: 'string' },
+      magnitude: { type: 'string' },
+      uncertainty: { type: 'string' },
       route: { type: 'string' },
       reason: { type: 'string' },
       amends: { type: 'string' },

package/.agents/scripts/lib/close-validation/process.js

@@ -11,22 +11,48 @@ import { spawn } from 'node:child_process';
  * Pipe a child stream's output line-by-line through `emit`, prepending
  * `prefix` to each line. Tail bytes without a trailing newline flush on
  * `end` so the operator never loses the last line of a gate's output.
+ *
+ * ## The drain must stay cheap (Story #4766)
+ *
+ * This handler runs on the reader side of the child's stdout/stderr pipe.
+ * Every microsecond spent here is a microsecond the pipe is not being read,
+ * and once the OS pipe buffer fills, the child's own write blocks — or, on a
+ * non-blocking pipe, fails outright with `EAGAIN`. A gate child is not
+ * obliged to survive that: Biome's `biome_console` `.unwrap()`s the error and
+ * aborts the process with exit 101, so a green lint verdict presents as a
+ * failed close. Two consequences bind everything on this path:
+ *
+ *   1. Splitting is O(chunk), not O(chunk × lines) — the scan advances a
+ *      `start` index instead of re-slicing the buffer once per line, so a
+ *      64KB chunk carrying 500 lines does not copy 16MB.
+ *   2. **`emit` MUST NOT block.** A synchronous per-line file write is
+ *      exactly the stall this path cannot afford; the close path's capture
+ *      sink (`single-story-close/gate-log.js`) buffers to an async stream for
+ *      that reason.
  */
 function pipePrefixed(stream, prefix, emit) {
   let buf = '';
   stream.setEncoding('utf8');
   stream.on('data', (chunk) => {
     buf += chunk;
-    while (true) {
-      const nl = buf.indexOf('\n');
-      if (nl === -1) break;
-      emit(prefix + buf.slice(0, nl));
-      buf = buf.slice(nl + 1);
+    let start = 0;
+    let nl = buf.indexOf('\n', start);
+    while (nl !== -1) {
+      emit(prefix + buf.slice(start, nl));
+      start = nl + 1;
+      nl = buf.indexOf('\n', start);
     }
+    if (start > 0) buf = buf.slice(start);
   });
   stream.on('end', () => {
-    if (buf.length > 0) emit(prefix + buf);
+    if (buf.length > 0) {
+      emit(prefix + buf);
+      buf = '';
+    }
   });
+  // A pipe-level error (EIO on a vanished child) must not become an
+  // unhandled 'error' event that takes the whole close down.
+  stream.on('error', () => {});
 }
 
 /** Wire the AbortSignal so an abort kills the child. Returns the cleanup fn. */
@@ -68,6 +94,18 @@ export function gateExitCode(code, sig) {
 const BIOME_NO_FILES_PROCESSED =
   'No files were processed in the specified paths';
 
+/**
+ * How many trailing gate lines the "No files were processed" probe retains.
+ *
+ * The marker only ever appears when biome processed nothing, and in that case
+ * its whole output is a handful of lines — so a bounded tail always contains
+ * it when it is there at all. Retaining a tail rather than the full transcript
+ * keeps the drain path's per-line work O(1) in the volume of gate output
+ * (Story #4766): the previous `captured += line` grew a string without limit,
+ * on the one gate (biome/format) whose output is the loudest.
+ */
+const MARKER_PROBE_TAIL_LINES = 32;
+
 /**
  * Whether biome's combined gate output carries the "No files were processed"
  * marker. Pure function — no I/O. Exported for unit coverage (Story #4292).
@@ -85,8 +123,11 @@ export function isBiomeNoFilesProcessed(output) {
  * Default async gate runner — used by `runCloseValidation` when no `runner`
  * is injected. Spawns the gate via `child_process.spawn`, prefixes every
  * stdout/stderr line with `[gate-name] ` (so concurrent gates don't bleed
- * into each other in the operator's terminal), and resolves only when the
- * child exits.
+ * into each other in the operator's terminal), and resolves only once the
+ * child has exited and both stdio pipes are drained.
+ *
+ * `opts.log` is the drain sink and **must not block** — see `pipePrefixed`
+ * above for what a synchronous per-line write costs the child (Story #4766).
  *
  * Honours `opts.signal`: a TERM is delivered to the child the moment the
  * signal fires, so a sibling gate's failure aborts the rest of the wave
@@ -119,13 +160,14 @@ export function defaultGateRunner(cmd, args, opts = {}) {
   const prefix = gateName ? `[${gateName}] ` : '';
   const emit =
     typeof log === 'function' ? log : (m) => process.stdout.write(`${m}\n`);
-  // Capture the combined output only when we may need to inspect it for the
-  // biome "No files were processed" marker — otherwise the stream is purely
-  // piped through to the operator (no retained buffer).
-  let captured = '';
+  // Retain a bounded tail only when we may need to inspect it for the biome
+  // "No files were processed" marker — otherwise the stream is purely piped
+  // through to the operator (no retained buffer).
+  const recent = [];
   const tap = tolerateNoFilesProcessed
     ? (line) => {
-        captured += `${line}\n`;
+        recent.push(line);
+        if (recent.length > MARKER_PROBE_TAIL_LINES) recent.shift();
         emit(line);
       }
     : emit;
@@ -133,13 +175,17 @@ export function defaultGateRunner(cmd, args, opts = {}) {
   pipePrefixed(child.stderr, prefix, tap);
   const detach = attachGateAbortHandler(child, signal);
   return new Promise((resolve) => {
-    child.on('exit', (code, sig) => {
+    // 'close', not 'exit' (Story #4766): 'close' fires only once the child has
+    // exited AND both stdio pipes have been fully drained and closed, so no
+    // gate ever reports its status while lines are still in flight. Resolving
+    // on 'exit' raced the tail of a high-volume gate's output.
+    child.on('close', (code, sig) => {
       detach();
       const status = gateExitCode(code, sig);
       if (
         status !== 0 &&
         tolerateNoFilesProcessed &&
-        isBiomeNoFilesProcessed(captured)
+        isBiomeNoFilesProcessed(recent.join('\n'))
       ) {
         emit(
           `${prefix}↳ biome processed zero files (all changed paths are config-ignored); treating as a clean skip`,