mandrel 2.60.0 → 2.62.0

package/.agents/scripts/lib/source-text/strip-js-comments.js

@@ -1,43 +1,16 @@
 // .agents/scripts/lib/source-text/strip-js-comments.js
 /**
- * The one string-literal-aware JavaScript comment stripper.
+ * The one string-literal-aware JS comment stripper, for guards that grep for
+ * a pattern in real code (so a guard's own rationale cannot satisfy it).
  *
- * Several guards in this repository grep source text for a pattern that must
- * appear in real code rather than in a docblock — a CLI citation, an import
- * specifier, a schema path. Each grew its own stripper, and the four
- * implementations disagreed on what a stripped block comment leaves behind:
- * one preserved newlines only, one deleted the comment outright (losing line
- * numbers), one blanked it to whitespace, and one used a regex that did not
- * honour string literals at all. A fix to any of them silently missed the
- * others, and a guard whose own rationale mentions the pattern it greps for
- * can satisfy itself if the stripping is wrong.
- *
- * **Semantics: comment bodies become equivalent whitespace.** Every character
- * of a comment is replaced by a space except newlines, which survive. That is
- * the most information-preserving of the four behaviours and the only one that
- * is safe for all of them:
- *
- *   - line and column positions are unchanged, so a guard can report a
- *     `file:line` that matches the original source;
- *   - a regex looking for code cannot match comment text, because none
- *     survives;
- *   - the output is the same length as the input, so byte offsets hold.
- *
- * String and template literals are copied through verbatim, so a `//` inside a
- * URL or a `/*` inside a message is not mistaken for a comment opener. Escape
- * sequences are honoured, so an escaped quote does not end the literal early.
- *
- * An unterminated comment or literal runs to end of input rather than
- * throwing: this is a lint helper reading files that may be mid-edit, and a
- * crash there would be a worse failure than a slightly over-stripped tail.
- *
- * Builtins only — no dependency, so the guards that run before a consumer's
- * install can use it.
+ * Every comment character except newlines becomes a space, so line, column
+ * and byte offsets all survive. Literals pass through verbatim, honouring
+ * escapes. An unterminated comment or literal runs to end of input rather
+ * than throwing — files may be mid-edit. Builtins only, so it runs before a
+ * consumer's install.
  */
 
 /**
- * Replace every non-newline character of `text` with a space.
- *
  * @param {string} text
  * @returns {string}
  */
@@ -46,12 +19,9 @@ function blank(text) {
 }
 
 /**
- * Index just past the string or template literal opening at `start`.
- * Runs to end of input when the literal is never closed.
- *
  * @param {string} text
  * @param {number} start - index of the opening quote
- * @returns {number}
+ * @returns {number} index just past the literal, or end of input.
  */
 function endOfLiteral(text, start) {
   const quote = text[start];
@@ -69,9 +39,6 @@ function endOfLiteral(text, start) {
 }
 
 /**
- * Strip JavaScript comments, replacing their bodies with equivalent
- * whitespace so line numbers, columns and byte offsets all survive.
- *
  * @param {string} source - JavaScript source text. Nullish is treated as empty.
  * @returns {string} the source with every comment body blanked to whitespace
  */

package/.agents/scripts/lib/stdio-flush.js

@@ -1,39 +1,16 @@
-// .agents/scripts/lib/stdio-flush.js
 /**
- * Stdio drain helper (Story #4783).
- *
- * `process.stdout` / `process.stderr` are only synchronous when they point at
- * a TTY or a regular file. On a **pipe** — every `cmd | consumer`, every
- * `child_process` capture, every `$(...)` substitution — Node writes
- * asynchronously once the 64 KiB kernel pipe buffer fills: `write()` returns
- * `false` and the remaining bytes sit in the stream's internal queue until the
- * reader drains it.
- *
- * `process.exit()` does not wait for that queue. Anything still buffered when
- * the process terminates is discarded, so a CLI that emits more than a pipe
- * buffer's worth of output and then exits eagerly silently truncates — the
- * exit code still reads green, and the consumer parses a half-written
- * envelope. `runAsCli` is the shared boundary where that used to happen for
- * every `.agents/scripts` entry point.
- *
- * The fix is to stop exiting eagerly (set `process.exitCode` and let the loop
- * drain naturally). This helper is the belt-and-braces half: an explicit await
- * on the queued bytes, so the flush is complete before the CLI's last frame
- * unwinds even when something further out terminates the process.
+ * Stdio drain helper. On a pipe, stdout/stderr write asynchronously once the
+ * kernel buffer fills, and `process.exit()` discards the queue — a green exit
+ * with a truncated envelope. CLIs set `exitCode` instead of exiting; this
+ * explicitly awaits the queued bytes as the second guard.
  *
  * @module stdio-flush
  */
 
 /**
- * Await the point at which one writable stream's queued bytes have been handed
- * to the OS. Resolves immediately when the stream has nothing queued, is not
- * writable, or is not a stream at all — a flush must never be the reason a
- * process hangs.
- *
- * Both settle paths are covered: the zero-length `write()` callback (which
- * fires after every previously queued chunk, since writes are ordered) and the
- * `'drain'` event (which fires when a backed-up stream empties). Whichever
- * lands first resolves; the other is detached.
+ * Resolve once queued bytes reach the OS, via whichever of the ordered empty
+ * `write()` callback or `'drain'` lands first. Resolves immediately for
+ * anything not flushable — a flush must never hang a process.
  *
  * @param {NodeJS.WritableStream & { writableLength?: number, writableEnded?: boolean, destroyed?: boolean }} [stream]
  * @returns {Promise<void>}
@@ -52,18 +29,14 @@ function drainStream(stream) {
       resolve();
     };
     stream.once?.('drain', done);
-    // The write callback fires once this (empty) chunk — and therefore every
-    // chunk queued ahead of it — has been flushed to the underlying handle.
     stream.write('', done);
   });
 }
 
 /**
- * Await the drain of the process's stdio streams. Never rejects: a stream that
- * errored, closed, or was never writable resolves as already-flushed.
+ * Never rejects.
  *
- * @param {Array<NodeJS.WritableStream|undefined>} [streams] Defaults to
- *   `[process.stdout, process.stderr]`.
+ * @param {Array<NodeJS.WritableStream|undefined>} [streams]
  * @returns {Promise<void>}
  */
 export async function flushStdio(streams = [process.stdout, process.stderr]) {

package/.agents/scripts/lib/story-adjacency.js

@@ -1,26 +1,8 @@
 /**
- * lib/story-adjacency.js — the single story-level adjacency builder.
- *
- * Both pre-v2 Epic wave wrappers and the v2 `/mandrel-deliver` ready-set path bottom out in the shared
- * `lib/Graph.js` kernel (`detectCycle` / `assignLayers` / `computeWaves`),
- * but each historically re-implemented the step that turns a list of Story
- * records into the `Map<storyId, number[]>` adjacency the kernel consumes.
- * This module is now the one home for that step; the live consumer is:
- *
- *   - `lib/wave-runner/ready-set.js` (`planReadySet`, the path-agnostic
- *     continuous scheduler the `stories-wave-tick.js` adapter dispatches through)
- *   - `stories-wave-tick.js` (for cycle detection, before delegating
- *     selection to `planReadySet`)
- *
- * (Pre-v2: `epic-runner/phases/build-wave-dag.js` and `dispatch-pipeline.js`
- * also called here; both entry seams were deleted.)
- *
- * Dependency source order (must stay aligned with `manifest-builder.js` and
- * `helpers/deliver-story.md` so planning and runtime scheduling never disagree):
- *   1. Canonical: `blocked by #NNN` / `depends on #NNN` parsed from the
- *      Story body via `parseBlockedBy` (the same parser planning uses).
- *   2. Fallback: an explicit `dependencies` (ticket shape) or
- *      `dependsOn` (operator-DAG shape) array on the Story record.
+ * The single Story-records → `Map<storyId, number[]>` adjacency builder for
+ * the `lib/Graph.js` kernel. Dependency sources must match planning
+ * (`manifest-builder.js`) so scheduling never disagrees: body `blocked by` /
+ * `depends on` refs, unioned with a `dependencies` / `dependsOn` array.
  *
  * @module lib/story-adjacency
  */
@@ -28,28 +10,14 @@
 import { parseBlockedBy } from './dependency-parser.js';
 
 /**
- * Build a story-level adjacency map (`Map<storyId, dependencyIds[]>`)
- * from an ordered list of Story records.
- *
- * Each record contributes one adjacency entry keyed by
- * `Number(record.id ?? record.number)`. Dependencies are the deduped
- * union of body-parsed `blocked by` references and the record's
- * explicit `dependencies` / `dependsOn` array, with self-edges and
- * non-integer ids always dropped.
+ * Self-edges and non-integer ids are always dropped.
  *
  * @param {Array<{id?: number|string, number?: number, body?: string,
  *   dependencies?: Array<number|string>, dependsOn?: Array<number|string>}>} stories
- *   Story records (live ticket payloads, fixture tickets, or operator
- *   DAG nodes).
  * @param {object} [opts]
- * @param {boolean} [opts.dropForeign=false] When `false` (the v2 default,
- *   matching the `/mandrel-deliver` path — `stories-wave-tick.js` and the
- *   `planReadySet` core), the operator-DAG contract is preserved: a
- *   dependency on an id absent from the input is treated as not-yet-done
- *   and withholds the dependent until it completes. When `true` (the
- *   pre-v2 Epic-scoped-wrapper semantics), edges pointing at ids outside
- *   the supplied story set are dropped so the DAG stays closed over the
- *   scheduled set.
+ * @param {boolean} [opts.dropForeign=false] Default keeps edges to ids absent
+ *   from the input (treated as not-yet-done, withholding the dependent);
+ *   `true` drops them so the DAG is closed over the supplied set.
  * @returns {Map<number, number[]>}
  */
 export function buildStoryAdjacency(stories, { dropForeign = false } = {}) {

package/.agents/scripts/lib/story-body/body-format-lints.js

@@ -1,73 +1,29 @@
 /**
- * body-format-lints.js — SSOT for the deterministic body-format lints that can
- * REJECT an authored Story body at persist time, plus the mechanical auto-fix
- * inference a failing dry-run surfaces (Story #4684).
+ * body-format-lints.js — SSOT for the deterministic lints that can reject an
+ * authored Story body at persist time (rendered into the story-author prompt
+ * so a first draft is lint-clean), plus the mechanical `## Changes` fix-it.
  *
- * The problem this closes: deterministic format rules (structured `## Changes`
- * bullet shape, non-empty sections) used to be discovered only as persist
- * dry-run failures — every miss cost a full re-author round-trip at
- * resident-context prices. This module is the single home for two remedies:
- *
- *   1. `BODY_FORMAT_LINTS` — the enumerated rejecting lints, each carrying a
- *      concrete good/bad example. `templates/decomposer-prompts.js` renders
- *      them into the story-author system prompt so the first draft is
- *      lint-clean by construction; a test enumerates the registry against the
- *      rendered prompt (Story #4684 AC-1).
- *   2. `suggestPathEntryFix` — the mechanical rewrite. `story-body.js`
- *      (`parsePathEntry`) and `task-body-validator.js`
- *      (`collectChangesErrors`) call it so a failing lint emits the corrected
- *      form ready to paste rather than a bare reject (AC-2), and the persist
- *      dry-run applies the same salvage for real (Story #5312,
- *      `plan-persist/changes-repair.js`).
- *
- * Story #5312 deleted the `verify-tier-suffix` / `verify-manual-reason` lints
- * with the tier suffix itself: a `verify[]` entry is any command, and the
- * `manual:<reason>` escape is gone with the rule it escaped. Story #5342
- * deleted `verify-non-empty`: an empty `verify[]` is a dry-run warning, not a
- * refusal, so it is no longer a rejecting lint — this registry carries only
- * the rules that still refuse.
- *
- * Import hygiene: this module imports only the cycle-free
- * `file-assumption-enum.js` leaf. It must NOT import `story-body.js` or
- * `task-body-validator.js` — both import this module, and either back-edge
- * would introduce a cycle (see the note in `file-assumption-enum.js`).
+ * Imports only the cycle-free `file-assumption-enum.js` leaf: story-body.js
+ * and task-body-validator.js both import this module, so importing either
+ * back would create a cycle.
  */
 
 import { FILE_ASSUMPTION_VALUES } from '../orchestration/file-assumption-enum.js';
 
-/**
- * The default assumption a mechanical `## Changes` auto-fix proposes. Most
- * bare-path bullets an author drops are in-place edits, so `refactors-existing`
- * is the safe default — the fix-it text tells the author to switch it to
- * `creates` / `deletes` when the edit is net-new or a removal.
- */
+// Most bare-path bullets are in-place edits; the fix-it text tells the author
+// to switch to creates/deletes when needed.
 const DEFAULT_SUGGESTED_ASSUMPTION = 'refactors-existing';
 
 /**
- * The bare-path bullet grammar (Story #5342, widened by Story #5361) — the
- * **one** definition of what a `## Changes` / `## References` bullet has to
- * look like to be a path rather than prose.
- *
- * It lives here, in the cycle-free lint leaf, because two consumers need the
- * identical judgment and neither may import the other: the story-body parser
- * (`story-body.js#parsePathEntry`) and the persist repair pass
- * (`plan-persist/changes-repair.js`). They carried a copy each, and the
- * copies drifted.
- *
- * A bullet is a path when it is a single token git could track: any run of
- * non-whitespace, optionally wrapped in a matched pair of backticks. That
- * admits the shapes the earlier `[\w@*-]*[/.][\w@./*-]+` class refused
- * outright — route-segment paths (`app/[slug]/page.tsx`,
- * `app/(marketing)/page.tsx`, `src/routes/$id.svelte`) and extensionless
- * top-level files (`Makefile`) — while still refusing prose, since
- * whitespace is the one thing that reliably marks a sentence.
+ * The one definition of a path bullet, shared by the story-body parser and
+ * the persist repair pass (which cannot import each other). Any single
+ * non-whitespace token, optionally backtick-wrapped — this admits route
+ * segments (`app/[slug]/page.tsx`) and extensionless files (`Makefile`) while
+ * whitespace still marks prose.
  */
 const BARE_PATH_TOKEN_RE = /^(?:`([^\s`]+)`|([^\s`]+))$/;
 
 /**
- * Read the bare path token out of a bullet, or `null` when the bullet is not
- * one single token.
- *
  * @param {unknown} raw
  * @returns {string|null} The path, with any wrapping backticks peeled.
  */
@@ -78,10 +34,8 @@ export function matchBarePathToken(raw) {
 }
 
 /**
- * Whether a rejected bullet is prose — it carries whitespace, so no path
- * grammar could ever have admitted it. The counterpart failure is a
- * single token that still names no usable path; the two get different
- * refusals because they need different fixes.
+ * Prose (carries whitespace) versus a single non-path token — distinct
+ * failures with distinct fixes.
  *
  * @param {unknown} raw
  * @returns {boolean}
@@ -90,33 +44,23 @@ export function isProseBullet(raw) {
   return typeof raw === 'string' && /\s/.test(raw.trim());
 }
 
-// A token that looks like a file path / glob / module id: it carries a `/` or a
-// `.`-separated segment. Deliberately loose — the suggestion is best-effort, and
-// a false positive only produces an unhelpful (still-valid) fix-it string.
+// Deliberately loose: a false positive only yields an unhelpful fix-it.
 const PATH_LIKE_RE = /[\w@*-]*[/.][\w@./*-]+/;
 
 /**
- * Propose the canonical `{ path, assumption }` object form for a `## Changes` /
- * `## References` bullet an author wrote as a bare path string (or a humanized
- * bullet with a bad assumption). Returns `null` when no path-shaped token can
- * be salvaged.
- *
- * The returned string is inline-JSON that round-trips cleanly back through the
- * story-body parser, so it is paste-ready.
+ * Paste-ready inline-JSON `{ path, assumption }` for a rejected bullet, or
+ * `null` when no path-shaped token can be salvaged.
  *
  * @param {unknown} raw
  * @returns {string|null} e.g. `{"path":"src/app.js","assumption":"refactors-existing"}`.
  */
 export function suggestPathEntryFix(raw) {
   if (typeof raw !== 'string') return null;
-  // Strip a leading markdown bullet marker.
   let s = raw
     .trim()
     .replace(/^[-*]\s+/, '')
     .trim();
-  // Take the segment before any humanized "— assumption" tail.
   s = s.split('—')[0].trim();
-  // Peel surrounding backticks / quotes.
   s = s
     .replace(/^[`'"]+/, '')
     .replace(/[`'"]+$/, '')
@@ -126,21 +70,16 @@ export function suggestPathEntryFix(raw) {
 }
 
 /**
- * A single deterministic body-format lint the persist path enforces.
- *
  * @typedef {object} BodyFormatLint
  * @property {string}  id          Stable identifier (also the prompt anchor).
- * @property {string}  summary     One-line statement of the requirement.
- * @property {string}  badExample  A form the lint rejects.
- * @property {string}  goodExample The lint-clean form to author instead.
+ * @property {string}  summary
+ * @property {string}  badExample
+ * @property {string}  goodExample
  * @property {boolean} autoFixable Whether a failing dry-run emits a fix-it.
  */
 
 /**
- * The enumerated deterministic lints that can reject an authored Story body at
- * persist time. Each carries a concrete example so the story-author prompt can
- * state the requirement example-first (Story #4684 AC-1). The one `autoFixable`
- * lint is the mechanical rewrite the dry-run applies (Story #5312).
+ * Only rules that still refuse; warnings live elsewhere.
  *
  * @type {ReadonlyArray<BodyFormatLint>}
  */

package/.agents/scripts/lib/story-body/footer-block.js

@@ -1,42 +1,23 @@
 /**
- * footer-block.js — the Story body's `---` footer grammar.
- *
- * A Story body is prose an operator edits. Its **declared dependency edges**
- * are not: they live in a footer block, in one exact line shape, and that
- * distinction is the whole safety property. An unanchored whole-body scan
- * (what `parseBlockedBy` used to be) turned any sentence that merely mentioned
- * a blocker into a real dispatch gate — an example, a changelog note, an
- * acceptance criterion quoting the phrase — and withheld the Story until an
- * unrelated issue closed.
- *
- * This module is the single home for that grammar. Both readers go through it:
- * `lib/story-body/story-body.js` (what a body round-trips as `depends_on`) and
- * `lib/dependency-parser.js` (what gates dispatch). Sharing one implementation
- * is what keeps them from drifting apart into two different answers about the
- * same body.
+ * footer-block.js — the Story body's `---` footer grammar, shared by the body
+ * parser and the dispatch-edge parser so they cannot disagree. Dependency
+ * edges are declared only by an exact line in the footer; an unanchored body
+ * scan turned any sentence mentioning a blocker into a real dispatch gate.
  *
  * @module lib/story-body/footer-block
  */
 
-/**
- * The one line shape that declares a dependency edge: `blocked by #N` alone on
- * its own line inside the footer block. Anchored at both ends deliberately —
- * `depends on #N`, `Blocked by: #N`, and `blocked by #N once X lands` all
- * declare nothing.
- */
+// Anchored at both ends: `Blocked by: #N` or `blocked by #N once X` declare
+// nothing.
 const FOOTER_BLOCKED_BY_LINE_RE = /^blocked by\s+(#\d+)$/i;
 
-/** A `---` rule on its own line. */
 const FOOTER_RULE_RE = /^---\s*$/;
 
-/** Footer keys that qualify a bare `---` rule as the footer separator. */
 const FOOTER_KEY_RE = /^(parent:|Epic:|blocked by)/im;
 
 /**
- * True when line `index` opens the footer block: a `---` on its own line whose
- * remaining lines start with a recognised footer key (`parent:`, `Epic:`,
- * `blocked by`). A `---` opening a thematic break or a table mid-body is
- * therefore not mistaken for the footer.
+ * A `---` counts only when later lines start with a footer key, so a mid-body
+ * thematic break is not mistaken for the footer.
  *
  * @param {string} line
  * @param {string[]} lines
@@ -49,16 +30,8 @@ export function isFooterSeparator(line, lines, index) {
 }
 
 /**
- * Return the footer block of a body — everything after the footer separator —
- * or `''` when the body carries no footer.
- *
- * Module-private: `parseFooterBlockedByIds` is its only caller. The body
- * parser splits its own sections and reaches for `parseFooterBlockedByRefs`
- * with the footer it already has, so exporting this would ship a symbol with
- * no consumer.
- *
  * @param {string} body
- * @returns {string}
+ * @returns {string} everything after the footer separator, or ''.
  */
 function extractFooterBlock(body) {
   if (!body) return '';
@@ -68,11 +41,8 @@ function extractFooterBlock(body) {
 }
 
 /**
- * Extract the `blocked by #N` refs from an already-split footer block, as the
- * `"#N"` strings a Story body's `depends_on` field round-trips.
- *
  * @param {string} footerBlock
- * @returns {string[]}
+ * @returns {string[]} `"#N"` refs, as `depends_on` round-trips them.
  */
 export function parseFooterBlockedByRefs(footerBlock) {
   if (!footerBlock) return [];
@@ -83,11 +53,8 @@ export function parseFooterBlockedByRefs(footerBlock) {
 }
 
 /**
- * Parse a body's declared blocker issue **numbers**, deduped — the
- * dispatch-edge view of the same footer the body parser reads.
- *
  * @param {string} body
- * @returns {number[]}
+ * @returns {number[]} deduped blocker issue numbers.
  */
 export function parseFooterBlockedByIds(body) {
   const ids = parseFooterBlockedByRefs(extractFooterBlock(body)).map((ref) =>