mandrel 2.14.0 → 2.15.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/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,
+    },
   };
 }
 

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

@@ -356,7 +356,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 +364,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 +386,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,16 +440,16 @@ 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
+ * 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.
@@ -920,7 +925,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