mandrel 2.59.0 → 2.61.0

package/.agents/scripts/lib/orchestration/diff-magnitude.js

@@ -1,56 +1,14 @@
 /**
- * lib/orchestration/diff-magnitude.js — the changed-line magnitude of a diff,
- * split into implementation and mandated-companion halves (Story #4856).
+ * lib/orchestration/diff-magnitude.js — changed-line magnitude of a diff,
+ * split into implementation and mandated-companion (tests, docs, baselines,
+ * lockfiles) halves, so obeying test-first and doc rules never inflates the
+ * size that bounds the light path.
  *
- * ## Why magnitude, and why the split
- *
- * The light path's diff backstop used to bound scope with a single
- * `maxFiles: 4` ceiling. Measured against this repository's own history that
- * ceiling was wrong in both directions:
- *
- *   - **Too tight.** Of 33 real-work squash merges on `main` (excluding
- *     release-please and `chore(baselines)` automation) only 7 — 21% — touch
- *     four files or fewer; the median is 8. The framework's *own* narrow-diff
- *     scale, `DEFAULT_DIFF_WIDTH.softFiles` in `review-depth.js`, is 15.
- *   - **Blind.** A three-file, 323-line rewrite passed while a 190-file change
- *     was rejected 47× over — even though 186 of those files were tests and its
- *     implementation was 7 files.
- *
- * So the axis is **changed lines over implementation files**, and the companion
- * classes the framework itself mandates are exempt from the count: obeying
- * `rules/testing-standards.md` (test-first), the documentation a change of
- * consequence is expected to touch, and the baseline ratchets must not inflate
- * the number that then rejects the change. Re-counting those same 33 merges on implementation files alone moves
- * the four-file pass rate from 21% to 58%.
- *
- * ## Three contracts worth not rediscovering
- *
- *   1. **Additions plus deletions, never net.** A modified line counts twice
- *      (one `+`, one `-`), which is the intended weighting. Net is actively
- *      broken as a size signal: the merge retiring the planner snapshot is
- *      1119 add+del but **−803** net, so a large deletion would measure as
- *      trivial.
- *   2. **A pure rename is free.** `git diff --numstat` reports `0\t0` for one,
- *      and its path arrives in `old => new` form — normalized here to the
- *      destination so the file still counts toward the implementation tally.
- *   3. **Exemption is from *counting*, never from *risk*.** Nothing here
- *      touches sensitive-path derivation, which every caller runs over the
- *      full changed set including companions.
- *
- * Companion matching runs through the audit suite's picomatch seam as a
- * **positive** glob list negated by the caller. A `!`-prefixed picomatch
- * pattern widens a match rather than narrowing it, so expressing the
- * behavior-bearing exceptions as negations would silently exempt more than
- * intended.
- *
- * Every export is total: no throws. {@link readNumstatRows} owns the one git
- * read; everything else is pure.
- *
- * The public surface is deliberately just those two functions. The numstat
- * parse, the rename normalization, and the companion classifier are internal:
- * each is fully observable through them (a stubbed `gitSpawnFn` drives the
- * parse, an `isCompanionFn` seam drives the classification), so exporting them
- * would widen the module's contract for no caller.
+ * Contracts: lines are additions + deletions, never net (a big deletion is
+ * not trivial); a pure rename is free but its file still counts; exemption
+ * is from counting, never from sensitive-path risk. Companion globs are a
+ * positive list — a `!` picomatch pattern widens rather than narrows. Every
+ * export is total.
  *
  * @module lib/orchestration/diff-magnitude
  */
@@ -59,27 +17,13 @@ import { matchesAnyFilePattern } from '../audit-suite/selector.js';
 import { gitSpawn } from '../git-utils.js';
 
 /**
- * Paths whose churn is a **mandated companion** of a change rather than the
- * change itself, exempt from the implementation line and file counts.
- *
- * Deliberately absent, and load-bearing in their absence: `.agentrc.json`,
- * `.agents/schemas/**`, `.github/workflows/**`, and `package.json`. Those are
- * "config" by file type but behavior by effect, and `.agents/schemas/audit-rules.json`
- * is the sensitive-path SSOT — exempting it would let a change widen the very
- * allowlist that decides whether it is risky.
- *
- * Note the anchoring: `baselines/**` is the generated baseline **data** at the
- * repository root. The baseline *schemas* under `.agents/schemas/baselines/`
- * are unanchored by this pattern and therefore still count as implementation.
- *
- * Markdown is exempt wholesale, which includes `.agents/workflows/**` and
- * `.agents/rules/**`. That is intended: rewriting a workflow contract is not
- * *effort* the way a module rewrite is, and its real guards are the close-time
- * context-budget, doc-link, and docs-reference-sync gates — none of which this
- * ceiling replaces.
+ * Mandated-companion paths, exempt from implementation counts. Deliberately
+ * absent: `.agentrc.json`, `.agents/schemas/**` (incl. the sensitive-path
+ * SSOT), `.github/workflows/**`, `package.json` — behavior by effect.
+ * `baselines/**` is root-anchored, so baseline schemas still count. Markdown
+ * (incl. workflows/rules) is exempt; its guards are the close-time doc gates.
  */
 const COMPANION_PATH_GLOBS = Object.freeze([
-  // Tests — mandated by rules/testing-standards.md's test-first discipline.
   '**/__tests__/**',
   '**/*.test.js',
   '**/*.test.mjs',
@@ -88,24 +32,17 @@ const COMPANION_PATH_GLOBS = Object.freeze([
   '**/*.test.tsx',
   'tests/**',
   'features/**',
-  // Documentation — the prose a change of consequence is expected to refresh.
   'docs/**',
   '**/*.md',
-  // Generated baseline data — written by the ratchets, not hand-authored.
   'baselines/**',
-  // Lockfiles — regenerated wholesale; their line count means nothing.
   'package-lock.json',
   'pnpm-lock.yaml',
   'yarn.lock',
 ]);
 
 /**
- * Normalize a `git diff --numstat` path field to the single file it names.
- * Rename rows arrive as `old => new` or with a braced infix
- * (`dir/{old => new}/file.js`); both resolve to the destination, so a renamed
- * implementation file still counts as one implementation file.
- *
- * Pure and total.
+ * Resolve a numstat rename (`old => new` or `dir/{old => new}/f.js`) to its
+ * destination.
  *
  * @param {string} raw
  * @returns {string}
@@ -123,14 +60,8 @@ function normalizeNumstatPath(raw) {
 }
 
 /**
- * Parse `git diff --numstat` output into per-file rows.
- *
- * Binary rows (`-\t-\tpath`) contribute zero text lines without poisoning the
- * parse. Any line that does not match the numstat shape makes the whole result
- * untrustworthy, so the function returns `null` — the "magnitude unknown"
- * signal every caller fails closed (or fails open) on deliberately.
- *
- * Pure and total.
+ * Parse numstat rows. Binary rows count zero lines; any malformed line
+ * returns `null` ("magnitude unknown").
  *
  * @param {unknown} stdout
  * @returns {Array<{ additions: number, deletions: number, path: string }>|null}
@@ -153,11 +84,8 @@ function parseNumstatRows(stdout) {
 }
 
 /**
- * True when `file` is a mandated companion rather than implementation.
- *
- * Pure and total — a throwing matcher resolves to `false`, which counts the
- * file as implementation. That is the conservative direction: a
- * classification failure must never shrink the measured magnitude.
+ * A throwing matcher yields `false` (implementation): a classification
+ * failure must never shrink the magnitude.
  *
  * @param {unknown} file
  * @param {{ matchFn?: typeof matchesAnyFilePattern }} [deps]
@@ -173,11 +101,7 @@ function isCompanionPath(file, { matchFn = matchesAnyFilePattern } = {}) {
 }
 
 /**
- * Read the per-file numstat rows for the `baseRef...headRef` diff. The one
- * side-effecting function in this module.
- *
- * Total — never throws; returns `null` on any git failure or unparseable
- * output.
+ * Numstat rows for `baseRef...headRef`; `null` on any failure.
  *
  * @param {{
  *   baseRef?: string,
@@ -210,20 +134,9 @@ export function readNumstatRows({
 }
 
 /**
- * Summarize a diff's magnitude, splitting implementation from mandated
- * companions.
- *
- * `implFiles` is counted from `changedFiles` — the canonical
- * `git diff --name-only` enumeration produced by `change-set.js` — rather than
- * from the numstat rows, so file counting uses clean paths from the one
- * enumerator every other consumer reads. `implLines` comes from the numstat
- * rows, which is the only surface carrying line counts.
- *
- * Returns `null` when either input is unusable: the magnitude is then *unknown*,
- * which is deliberately distinct from *zero* so a caller can fail closed on the
- * absence of evidence.
- *
- * Pure and total.
+ * Summarize magnitude. Files come from `change-set.js`'s canonical
+ * enumeration, lines from numstat. `null` (unknown, distinct from zero)
+ * when either input is unusable.
  *
  * @param {{
  *   changedFiles?: unknown,
@@ -248,10 +161,7 @@ export function summarizeDiffMagnitude({
     (f) => typeof f === 'string' && f.trim() !== '',
   );
 
-  // A classification failure resolves to "implementation" — the conservative
-  // direction, since counting a companion as implementation can only ever make
-  // the measured magnitude larger. Guarded here as well as inside the default
-  // classifier so an injected one cannot break this function's totality.
+  // Guarded again so an injected classifier cannot break totality.
   const isCompanion = (file) => {
     try {
       return isCompanionFn(file) === true;

package/.agents/scripts/lib/orchestration/doc-reader.js

@@ -2,12 +2,8 @@ import fs from 'node:fs';
 import path from 'node:path';
 
 /**
- * Read an explicit list of doc files relative to `docsRoot`, returning one
- * `{ name, path, content }` object per file that exists and reads cleanly.
- * Missing or unreadable files are skipped silently. Order is preserved from
- * the input list. This is the shared read/normalize seam the per-Epic docs
- * digest builds on (Story #4338) so there is a single home for the fs read
- * path.
+ * Read doc files relative to `docsRoot`, in input order; missing or
+ * unreadable files are skipped.
  *
  * @param {{ files: string[], docsRoot?: string }} args
  * @returns {Promise<Array<{ name: string, path: string, content: string }>>}

package/.agents/scripts/lib/orchestration/docs-digest.js

@@ -1,34 +1,14 @@
 /**
- * docs-digest.js — per-run docs digest builder (Story #4338).
- *
- * `/mandrel-deliver` story sub-agents previously re-read every file in
- * `project.docsContextFiles` on every Story, re-paying the full docs payload
- * per child. This module produces a single **digest** — one compact markdown
- * outline per configured doc — that the parent threads into every child prompt
- * once. The digest gives each child enough shape (path, size, heading outline
- * with line numbers, and the first paragraph under each `##` section) to decide
- * which full files to pull on demand, instead of ingesting the whole set up
- * front.
- *
- * The heavy lifting of reading + normalizing doc bodies is delegated to
- * `doc-reader.js` (`readDocFiles`), keeping a single home for the fs read path.
- *
- * Story #4433 extends this module with {@link ensureDocsDigest}, a shared
- * generate-and-write export so the planner-context surface
- * (`plan-context.js` / `authoring-context.js`) can produce a session docs
- * digest without duplicating the mkdir+writeFile plumbing shared by
- * `plan-context.js` / `authoring-context.js` and the `/mandrel-deliver` workflow.
+ * docs-digest.js — a compact outline of `project.docsContextFiles` (path,
+ * size, headings with line numbers, first `##` paragraph) so agents pull
+ * full docs on demand instead of ingesting the whole set per Story.
  */
 
 import fs from 'node:fs';
 import path from 'node:path';
 import { readDocFiles } from './doc-reader.js';
 
-/**
- * Level-2 / level-3 markdown heading matcher. Mirrors the outline granularity
- * the planning-context budget already uses so the two surfaces agree on what a
- * "section" is.
- */
+/** `##`/`###` headings — the planning-context budget's section granularity. */
 const HEADING_RE = /^(#{2,3})\s+(.+?)\s*$/;
 
 function byteLen(s) {
@@ -37,10 +17,6 @@ function byteLen(s) {
 }
 
 /**
- * Extract the heading outline (level + text + 1-based line number) from a
- * markdown body. Line numbers let a child jump straight to the section it
- * needs when it pulls the full file.
- *
  * @param {string} content
  * @returns {Array<{ level: number, text: string, line: number }>}
  */
@@ -56,12 +32,10 @@ function extractOutline(content) {
 }
 
 /**
- * The first non-empty paragraph that follows a given heading line, up to the
- * next heading or a blank-line paragraph break. Returns '' when the section
- * has no prose (e.g. a heading immediately followed by a sub-heading).
+ * First paragraph under a heading; '' when the section has no prose.
  *
- * @param {string[]} lines full doc split into lines
- * @param {number} headingLine 1-based line of the heading
+ * @param {string[]} lines
+ * @param {number} headingLine 1-based
  * @returns {string}
  */
 function firstParagraphAfter(lines, headingLine) {
@@ -79,9 +53,6 @@ function firstParagraphAfter(lines, headingLine) {
 }
 
 /**
- * Render one doc's digest section: path + byte size, then a bulleted heading
- * outline where each `##` bullet carries the first paragraph beneath it.
- *
  * @param {{ path: string, content: string }} doc
  * @returns {string} markdown block
  */
@@ -110,15 +81,12 @@ function renderDocSection(doc) {
 }
 
 /**
- * Build the per-run docs digest markdown from the configured docs context
- * files. Missing files are skipped silently (the read seam returns only the
- * files it could stat + read). Returns `null` when there is nothing to digest
- * — i.e. `docsContextFiles` is empty/unset — so callers surface a null
- * `docsDigestPath` rather than writing an empty file.
+ * Build the digest; missing files are skipped. `null` when nothing is
+ * readable, so callers report a null `docsDigestPath` instead of an empty
+ * file.
  *
  * @param {{ docsContextFiles?: string[], docsRoot?: string }} args
- * @returns {Promise<string|null>} the digest markdown, or null when there are
- *   no files to digest.
+ * @returns {Promise<string|null>}
  */
 export async function buildDocsDigest({ docsContextFiles, docsRoot } = {}) {
   const files = Array.isArray(docsContextFiles) ? docsContextFiles : [];
@@ -142,14 +110,8 @@ export async function buildDocsDigest({ docsContextFiles, docsRoot } = {}) {
 }
 
 /**
- * Build the docs digest and write it to `outputPath`, returning `null` (no
- * write) when there is nothing to digest. This is the single shared
- * generate-and-persist export both digest producers call: the per-run
- * `/mandrel-deliver` docs digest (`helpers/deliver-story.md`) and the planner-
- * context digest (`plan-context.js` → `authoring-context.js`, Story
- * #4433). Callers own path construction (temp-root layout, run id, etc.)
- * so both surfaces can keep — or deliberately share — their own convention;
- * this function only owns "build digest, ensure parent dir, write file".
+ * Build and write the digest (`null`, no write, when empty). Shared by the
+ * deliver and planner surfaces; callers own path construction.
  *
  * @param {{ docsContextFiles?: string[], docsRoot?: string, outputPath: string }} args
  * @returns {Promise<{ digest: string, outputPath: string } | null>}

package/.agents/scripts/lib/orchestration/epic-candidates.js

@@ -1,25 +1,12 @@
 /**
- * epic-candidates.js — rank the open container Epics a new plan could join.
- *
- * Story #5155. `plan-persist` has always been able to *create* a container
- * Epic, and to re-adopt one whose fingerprint matches the exact cohort it is
- * re-persisting. Neither helps the case this module exists for: a second plan,
- * days later, adding work that belongs under the Epic a first plan opened. The
- * fingerprint is keyed on the child set, so a different cohort never matches
- * it — by design, since adopting the wrong container silently mis-files a run.
- *
- * So the join has to be a **decision**, not a hash collision: this module
- * surfaces every open Epic with an overlap score, and the operator picks at
- * Gate #3. The list is deliberately **complete rather than thresholded** — a
- * low score is evidence for the operator to weigh, and hiding a candidate is
- * how a plan silently opens its second container for one body of work.
- *
- * Scoring reuses `duplicate-search.js`'s tokenizer and Jaccard overlap rather
- * than growing a second similarity notion in the codebase; like that module's,
- * it is a triage signal and not a semantic search.
+ * epic-candidates.js — rank the open container Epics a new plan could join,
+ * for the operator to pick at Gate #3 (joining a different cohort is a
+ * decision, not a fingerprint match). The list is complete, never
+ * thresholded: hiding a low scorer is how one body of work gets two
+ * containers. Scoring reuses `duplicate-search.js`'s tokenizer and overlap —
+ * a triage signal, not semantic search.
  *
  * @module lib/orchestration/epic-candidates
- * @see Story #5155
  */
 
 import { overlapScore, tokenize } from '../duplicate-search.js';
@@ -29,8 +16,6 @@ import { concurrentMap, FANOUT_CONCURRENCY } from '../util/concurrent-map.js';
 import { isEpicTicket, readEpicChildIds } from './epic-container.js';
 
 /**
- * Build an issue URL for an Epic the provider returned without one.
- *
  * @param {number} id
  * @param {{ owner?: string, repo?: string }} [opts]
  * @returns {string}
@@ -41,16 +26,8 @@ function buildEpicUrl(id, { owner, repo } = {}) {
 }
 
 /**
- * Fetch the titles of an Epic's children, for scoring only.
- *
- * Child titles matter because a container's own title and goal are short and
- * abstract ("Auth hardening", one paragraph), while the seed that should match
- * it is concrete. The children are where the shared vocabulary actually lives.
- *
- * Entirely best-effort: no `getTicket`, an unreadable child, or a throw all
- * degrade to fewer title tokens, never to a failed envelope. A candidate that
- * scores low because its children could not be read is still *listed* — the
- * operator sees every open Epic regardless.
+ * Child titles carry the concrete vocabulary an abstract Epic title lacks.
+ * Best-effort: failures only reduce tokens.
  *
  * @param {{ childIds: number[], provider: object }} opts
  * @returns {Promise<string>} Space-joined child titles ('' when none resolved).
@@ -75,17 +52,11 @@ async function readChildTitles({ childIds, provider }) {
 }
 
 /**
- * Score one open Epic against the seed.
- *
  * @param {{ epic: object, seedTokens: Set<string>, provider: object, owner?: string, repo?: string }} opts
  * @returns {Promise<{ id: number, title: string, url: string, score: number, childIds: number[] }|null>}
  */
 async function scoreEpic({ epic, seedTokens, provider, owner, repo }) {
-  // `listTicketsByLabel` hands back the declared ticket shape, in which `id`
-  // is the issue number. The `number`-then-`id` fallback this replaced read as
-  // defensive and was not: on that shape it never fired, and on a raw REST
-  // payload it was the only thing standing between this and scoring an Epic
-  // under its database id.
+  // Declared ticket shape: `id` is the issue number.
   const id = Number(epic?.id);
   if (!Number.isInteger(id) || id <= 0) return null;
 
@@ -94,9 +65,7 @@ async function scoreEpic({ epic, seedTokens, provider, owner, repo }) {
   const childIds = readEpicChildIds(body);
   const childTitles = await readChildTitles({ childIds, provider });
 
-  // The fingerprint marker and checklist ids are machine noise; the tokenizer
-  // drops short and non-alphabetic tokens, so the corpus is effectively the
-  // title, the `## Goal` prose and the child titles.
+  // The tokenizer drops marker/id noise.
   const corpus = `${title}\n${body}\n${childTitles}`;
   const score = overlapScore(seedTokens, tokenize(corpus));
 
@@ -110,16 +79,8 @@ async function scoreEpic({ epic, seedTokens, provider, owner, repo }) {
 }
 
 /**
- * Find every open container Epic, ranked by overlap with the seed.
- *
- * **Only open Epics are candidates.** A closed Epic is a completed body of
- * work; joining one would reopen a container the epilogue deliberately closed,
- * and silently re-scope a finished plan. The operator files a new Epic or
- * reopens the old one by hand.
- *
- * Failures degrade to `[]` — like the duplicate search, this is a triage
- * signal offered at a gate, and no plan should fail to be authored because
- * the Epic listing was unavailable.
+ * Every open container Epic ranked by seed overlap. Closed Epics are
+ * finished work and never candidates. Failures degrade to `[]`.
  *
  * @param {{
  *   seed: string,
@@ -156,8 +117,7 @@ export async function findOpenEpicCandidates({ seed, provider, owner, repo }) {
     { concurrency: FANOUT_CONCURRENCY },
   );
 
-  // Descending score, then ascending id: a stable order for two Epics that
-  // tie, so the same backlog always renders the same list.
+  // Ties break on id.
   return scored
     .filter((c) => c !== null)
     .sort((a, b) => b.score - a.score || a.id - b.id);

package/.agents/scripts/lib/orchestration/epic-checklist.js

@@ -1,22 +1,9 @@
 /**
- * epic-checklist.js — edit a live Epic body's child checklist in place.
- *
- * Story #5155. `epic-container.js` describes the *shape* of a container and
- * renders one from scratch; this module is the other operation adoption needs
- * — amending a body that already exists, written by someone else, possibly
- * hand-edited since.
- *
- * The two are deliberately separate. Composing may assume everything about the
- * text because it produced all of it; amending may assume almost nothing and
- * must treat every line it did not come to change as untouchable: the `## Goal`
- * prose, the fingerprint marker, the item order, and above all the **checked
- * state** of existing rows. An operator who ticked `- [x] #41` is recording
- * that the Story landed, and a re-render would silently discard it.
- *
- * So the edit is a surgical line insertion rather than a re-render.
+ * epic-checklist.js — amend a live, possibly hand-edited Epic body's child
+ * checklist by surgical line insertion, never a re-render: goal prose,
+ * markers, order and existing checked state are untouchable.
  *
  * @module lib/orchestration/epic-checklist
- * @see Story #5155
  */
 
 import {
@@ -41,13 +28,8 @@ function findLastChecklistIndex(lines) {
 }
 
 /**
- * Where the new rows go, as a `[index, deleteCount]` splice target.
- *
- * Three placements, in priority order, each preserving a different thing:
- * replacing the empty-container placeholder (which would otherwise stand above
- * rows that contradict it), appending after the last existing row (which keeps
- * original-then-appended order on read-back), or opening the section for a body
- * that never had one.
+ * Splice target: replace the empty placeholder, else append after the last
+ * row, else open under the heading.
  *
  * @param {string[]} lines
  * @returns {[number, number]|null} `null` when there is no section to extend.
@@ -69,14 +51,10 @@ function locateInsertion(lines) {
 }
 
 /**
- * Append child ids to an existing Epic body's checklist, idempotently.
- *
- * Idempotence is the load-bearing property: a resumed or re-run persist calls
- * this again with the same cohort, and a second copy of every row would make
- * the container claim children it does not have.
+ * Append child ids idempotently — a re-run persist passes the same cohort.
  *
- * @param {string} body The Epic's current body.
- * @param {number[]} childIds Ids to add.
+ * @param {string} body
+ * @param {number[]} childIds
  * @returns {string} The updated body (byte-identical when nothing was added).
  */
 export function appendEpicChildIds(body, childIds) {
@@ -92,9 +70,7 @@ export function appendEpicChildIds(body, childIds) {
   const target = locateInsertion(lines);
 
   if (target === null) {
-    // A hand-written or foreign Epic with no checklist section. Add one rather
-    // than refusing: `isEpicTicket` already treats such a ticket as a real
-    // Epic, so the adoption must not be the one place that disagrees.
+    // No section: add one, since `isEpicTicket` counts this as an Epic.
     return `${text.replace(/\n+$/, '')}\n\n${CHILDREN_HEADING}\n\n${rows.join('\n')}\n`;
   }