mandrel 2.14.0 → 2.16.0

package/.agents/scripts/lib/cli-usage.js

@@ -0,0 +1,174 @@
+/**
+ * `.agents/scripts/lib/cli-usage.js` — the one implementation of `--help` for
+ * every top-level script under `.agents/scripts/`.
+ *
+ * ## Why
+ *
+ * A script's flag contract used to live in the workflow prose that invoked it
+ * (`deliver-story.md` Step 0 restating `single-story-init.js`'s `--dry-run` /
+ * `--steal`, and so on). Two homes for one contract is a drift class: the
+ * script changes, the prose does not, and the next agent runs a flag that no
+ * longer exists. Moving the enumeration into the script's own `--help` gives
+ * the contract a single home that ships with the code that implements it.
+ *
+ * ## Contract
+ *
+ * `--help` (or `-h`) is a **query**, never an error path:
+ *
+ *   - writes non-empty text to **stdout** and exits **0**;
+ *   - performs no GitHub write, acquires no lease, mutates no working tree.
+ *
+ * stdout — not `Logger.info` — because help output must survive
+ * `AGENT_LOG_LEVEL=silent` and carry no `[Orchestrator]` decoration; this is
+ * the same `process.stdout.write` carve-out that machine-parsable envelopes
+ * use (see `tests/enforcement/no-console.test.js`).
+ *
+ * The short-circuit itself lives in `runAsCli` (`lib/cli-utils.js`), which
+ * fires this module **before** the script's `main` runs — so the "no side
+ * effects" half of the contract holds structurally rather than by each
+ * script remembering to check first.
+ *
+ * ## Usage
+ *
+ *   runAsCli(import.meta.url, main, {
+ *     source: 'my-script',
+ *     usage: {
+ *       invocation: 'node .agents/scripts/my-script.js --story <id> [--json]',
+ *       summary: 'One line on what the script does.',
+ *       flags: [
+ *         ['--story <id>', 'GitHub issue number of the Story (required).'],
+ *         ['--json', 'Emit the envelope as JSON instead of prose.'],
+ *       ],
+ *     },
+ *   });
+ *
+ * A pre-rendered string is accepted too, so a script that already shipped a
+ * hand-written `HELP` block adopts the shared gate without its observable
+ * text changing (`usage: HELP`).
+ */
+
+/** Tokens that request help. */
+export const HELP_FLAGS = Object.freeze(['--help', '-h']);
+
+/** Left column width for the flag table; longer flags wrap to their own line. */
+const FLAG_COLUMN = 22;
+
+/**
+ * Did the caller ask for help? Scans up to the `--` end-of-flags separator so
+ * a positional literally named `--help` after `--` is not mistaken for a
+ * request.
+ *
+ * @param {string[]} argv Argument vector without the node/script entries.
+ * @returns {boolean}
+ */
+export function wantsHelp(argv = []) {
+  if (!Array.isArray(argv)) return false;
+  for (const token of argv) {
+    if (token === '--') return false;
+    if (HELP_FLAGS.includes(token)) return true;
+  }
+  return false;
+}
+
+/**
+ * Normalize one flag entry into `{ flag, description }`. Accepts a
+ * `[flag, description]` pair or an object, so call sites can use whichever
+ * reads better next to their option table.
+ *
+ * @param {[string, string]|{flag: string, description?: string}} entry
+ * @returns {{ flag: string, description: string }}
+ */
+function normalizeFlag(entry) {
+  if (Array.isArray(entry)) {
+    return {
+      flag: String(entry[0] ?? ''),
+      description: String(entry[1] ?? ''),
+    };
+  }
+  return {
+    flag: String(entry?.flag ?? ''),
+    description: String(entry?.description ?? ''),
+  };
+}
+
+/**
+ * Render one `  --flag   description` row, wrapping onto a second line when
+ * the flag itself is wider than the column.
+ *
+ * @param {{ flag: string, description: string }} row
+ * @returns {string}
+ */
+function renderFlagRow({ flag, description }) {
+  if (!description) return `  ${flag}`;
+  if (flag.length >= FLAG_COLUMN) {
+    return `  ${flag}\n  ${' '.repeat(FLAG_COLUMN)}${description}`;
+  }
+  return `  ${flag.padEnd(FLAG_COLUMN)}${description}`;
+}
+
+/**
+ * Append the `--help` row unless the spec already documents it, so every
+ * rendered block is self-describing without each call site repeating it.
+ *
+ * @param {Array<{ flag: string, description: string }>} rows
+ * @returns {Array<{ flag: string, description: string }>}
+ */
+function withHelpRow(rows) {
+  const documented = rows.some((r) => r.flag.split(/[\s,]/)[0] === '--help');
+  if (documented) return rows;
+  return [...rows, { flag: '--help', description: 'Show this message.' }];
+}
+
+/**
+ * Render a usage spec into the text `--help` prints.
+ *
+ * @param {{
+ *   invocation: string,
+ *   summary?: string,
+ *   flags?: Array<[string, string]|{flag: string, description?: string}>,
+ *   notes?: string[],
+ * }} spec
+ * @returns {string} Text block, newline-terminated.
+ */
+export function formatUsage(spec) {
+  const rows = withHelpRow((spec?.flags ?? []).map(normalizeFlag));
+  const blocks = [`Usage: ${spec?.invocation ?? ''}`.trim()];
+  if (spec?.summary) blocks.push(spec.summary);
+  blocks.push(['Flags:', ...rows.map(renderFlagRow)].join('\n'));
+  for (const note of spec?.notes ?? []) blocks.push(note);
+  return `${blocks.join('\n\n')}\n`;
+}
+
+/**
+ * Coerce either accepted `usage` shape — a spec object or a pre-rendered
+ * string — into the text to print.
+ *
+ * @param {object|string} usage
+ * @returns {string}
+ */
+export function renderUsage(usage) {
+  if (typeof usage === 'string') {
+    return usage.endsWith('\n') ? usage : `${usage}\n`;
+  }
+  return formatUsage(usage);
+}
+
+/**
+ * Answer a help request. Returns `true` when help was requested (and printed),
+ * `false` when the caller should carry on with its normal path.
+ *
+ * Never throws on a missing/blank `usage`: a script whose spec renders empty
+ * still owes the contract non-empty stdout, so a minimal line is emitted
+ * rather than a silent exit that reads as a broken CLI.
+ *
+ * @param {string[]} argv
+ * @param {object|string} usage
+ * @param {{ write: (s: string) => void }} [out] Defaults to `process.stdout`.
+ * @returns {boolean}
+ */
+export function respondToHelp(argv, usage, out = process.stdout) {
+  if (!wantsHelp(argv)) return false;
+  const text = renderUsage(usage ?? '');
+  out.write(text.trim().length > 0 ? text : 'Usage: (no flags documented)\n');
+  return true;
+}

package/.agents/scripts/lib/cli-utils.js

@@ -16,6 +16,7 @@
 
 import path from 'node:path';
 import { fileURLToPath } from 'node:url';
+import { respondToHelp } from './cli-usage.js';
 import { formatCliError } from './error-redactor.js';
 
 /**
@@ -37,12 +38,21 @@ export function isDirectInvocation(importMetaUrl) {
  * `main` is funnelled through either the caller-supplied `onError` callback
  * or the default handler (prefixed stderr line + `process.exit(exitCode)`).
  *
+ * A `usage` option makes the script self-describing: when the argv carries
+ * `--help` / `-h`, the rendered usage block goes to stdout and `main` is
+ * **never invoked**. That ordering is the whole point — it makes "`--help`
+ * performs no GitHub write, acquires no lease, and mutates no working tree"
+ * structurally true for every adopting script, rather than something each
+ * `main` has to remember to check before its first side effect.
+ *
  * @param {string} importMetaUrl        Caller's `import.meta.url`.
  * @param {() => Promise<unknown>} main The CLI's main function.
  * @param {object} [options]
  * @param {string} [options.source='CLI']           Prefix used in the default error message.
  * @param {number} [options.exitCode=1]             Exit code used by the default error handler.
  * @param {(err: Error) => void} [options.onError]  Full override of the error handler.
+ * @param {object|string} [options.usage]           Usage spec (or pre-rendered
+ *   text) printed for `--help`; see `lib/cli-usage.js`.
  */
 export function runAsCli(importMetaUrl, main, options = {}) {
   if (!isDirectInvocation(importMetaUrl)) return;
@@ -52,7 +62,9 @@ export function runAsCli(importMetaUrl, main, options = {}) {
     onError,
     propagateExitCode = false,
     errorPrefix,
+    usage,
   } = options;
+  if (usage && respondToHelp(process.argv.slice(2), usage)) return;
   const promise = main();
   if (propagateExitCode) {
     promise.then((code) => process.exit(code ?? 0));

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`,

package/.agents/scripts/lib/doc-tiers.js

@@ -29,11 +29,19 @@
  *                       converted spawn boots on **instead of** the always-loaded
  *                       closure, so it is budgeted independently (per-file ≤8KB
  *                       ceiling gated by `check-context-budget.js`).
+ *   - `workflow` /    — the `.agents/workflows/**` read-tier (Story #4752),
+ *     `workflowOnDemand` resolved as each entry point's transitive
+ *                       markdown-link closure by
+ *                       [`workflow-closure.js`](workflow-closure.js): the files
+ *                       an entry point's `mandatoryReads:` frontmatter forces
+ *                       you to read (`workflow`, gated) versus the reachable
+ *                       remainder (`workflowOnDemand`, recorded only).
  *
  * A file that could appear in more than one tier is kept in its **highest**
  * tier only (alwaysLoaded > mandatoryRead > digestVisible > onDemand), so the
  * arrays partition the doc set with no double-counting. `agentBoot` is disjoint
- * from the read-tiers (it lives under `.agents/agents/`, not the doc/rules set).
+ * from the read-tiers (it lives under `.agents/agents/`, not the doc/rules set),
+ * and so are the workflow tiers (confined to `.agents/workflows/`).
  *
  * The closure is discovered by parsing `@`-import references and following
  * them recursively (cycle-safe via a visited set). A candidate `@`-token only
@@ -47,6 +55,7 @@
 
 import nodeFs from 'node:fs';
 import path from 'node:path';
+import { resolveWorkflowClosures } from './workflow-closure.js';
 
 /**
  * Basename of the always-loaded entry document (the root of the closure).
@@ -212,18 +221,31 @@ export function docsContextPaths(config) {
 }
 
 /**
- * Resolve the four documentation read-tiers, each entry `{ path, bytes }`,
+ * Resolve the documentation read-tiers, each entry `{ path, bytes }`,
  * partitioned so no path appears in more than one tier (highest tier wins).
+ * `workflowClosure` rides alongside the tiers as the per-entry-point workflow
+ * measurement (Story #4752) — its `reachableTotalBytes` is a recorded drift
+ * signal, never a gate.
  *
  * @param {object} config resolved config (`resolveConfig()` output)
  * @param {{ root?: string, fs?: FsLike }} [opts]
- * @returns {{ tiers: {
- *   alwaysLoaded: Array<{ path: string, bytes: number }>,
- *   mandatoryRead: Array<{ path: string, bytes: number }>,
- *   digestVisible: Array<{ path: string, bytes: number }>,
- *   onDemand: Array<{ path: string, bytes: number }>,
- *   agentBoot: Array<{ path: string, bytes: number }>,
- * } }}
+ * @returns {{
+ *   tiers: {
+ *     alwaysLoaded: Array<{ path: string, bytes: number }>,
+ *     mandatoryRead: Array<{ path: string, bytes: number }>,
+ *     digestVisible: Array<{ path: string, bytes: number }>,
+ *     onDemand: Array<{ path: string, bytes: number }>,
+ *     agentBoot: Array<{ path: string, bytes: number }>,
+ *     workflow: Array<{ path: string, bytes: number }>,
+ *     workflowOnDemand: Array<{ path: string, bytes: number }>,
+ *   },
+ *   workflowClosure: {
+ *     mandatoryTotalBytes: number,
+ *     reachableTotalBytes: number,
+ *     entryPoints: Array<{ path: string, mandatoryBytes: number, reachableBytes: number }>,
+ *   },
+ * }}
+ * @throws {Error} on an unresolvable `mandatoryReads` entry or a mandatory cycle
  */
 export function resolveDocTiers(
   config,
@@ -265,8 +287,29 @@ export function resolveDocTiers(
   //    are standalone system prompts, disjoint from the doc read-tiers.
   const agentBoot = collect(listAgentDefs(root, fs));
 
+  // 6. workflow: each entry point's transitive markdown-link closure (#4752),
+  //    split into the gated mandatory set and the recorded on-demand remainder.
+  //    The walk is confined to `.agents/workflows/**`, and `collect` still
+  //    de-dupes, so no path is counted against two tiers.
+  const closure = resolveWorkflowClosures(root, { fs });
+  const workflow = collect(closure.mandatoryFiles.map((e) => e.path));
+  const workflowOnDemand = collect(closure.onDemandFiles.map((e) => e.path));
+
   return {
-    tiers: { alwaysLoaded, mandatoryRead, digestVisible, onDemand, agentBoot },
+    tiers: {
+      alwaysLoaded,
+      mandatoryRead,
+      digestVisible,
+      onDemand,
+      agentBoot,
+      workflow,
+      workflowOnDemand,
+    },
+    workflowClosure: {
+      mandatoryTotalBytes: closure.mandatoryTotalBytes,
+      reachableTotalBytes: closure.reachableTotalBytes,
+      entryPoints: closure.entryPoints,
+    },
   };
 }