mandrel 2.59.0 → 2.61.0

package/.agents/scripts/lib/workers/maintainability-report-worker.js

@@ -1,37 +1,9 @@
 /**
- * lib/workers/maintainability-report-worker.js — CPU-pool worker entry for
- * the native ReviewProvider's per-file maintainability scoring. One file
- * in, the file's full maintainability *report* out (module score, per-method
- * scores, worstMethod). No project config, no git, no provider — just
- * typhonjs-escomplex (via maintainability-engine) and the in-memory TS
- * transpile shim.
- *
- * This is the report-shaped sibling of `maintainability-worker.js`, which
- * returns only the scalar MI score for the baseline gate. The native review
- * needs the richer report (per-method scores feed the critical/warning
- * tiering in `classifyReport`), so this worker calls
- * `calculateReportForFile` instead of `calculateForFile`.
- *
- * Message contract — see lib/cpu-pool.js:
- *   IN  : { item: string }                  — absolute file path to score
- *                                             (reads head content from disk)
- *         { item: { source, label } }       — pre-sourced content to score
- *                                             (Story #3696: the native review
- *                                             sources head content via
- *                                             `git show <headRef>:<path>` and
- *                                             passes the string here so the
- *                                             worker scores the head version,
- *                                             not the on-disk base copy)
- *         { exit: true }                     — drain & terminate
- *   OUT : { ok: true, result: { filePath, report: object | null } }
- *
- * `report` is `null` only when the file genuinely cannot be read (ENOENT
- * or other I/O error) — the native classifier treats a null report the
- * same way the serial path treats a thrown `reportFn` (drop the file).
- * Parse failures inside escomplex still resolve to a `{ parseError: true }`
- * report to preserve parity with the in-process serial path
- * (`calculateReportForFile` returns a parse-error report rather than
- * throwing).
+ * CPU-pool worker for the native review: one file (a path, or
+ * `{ source, label }` holding head content from `git show`) in, its full
+ * maintainability report out. `report` is `null` only on an I/O error (the
+ * file is dropped); a parse failure yields a `parseError` report, matching
+ * the serial path.
  */
 
 import { parentPort } from 'node:worker_threads';
@@ -43,10 +15,7 @@ import { transpileIfNeeded } from '../transpile.js';
 import { serveWorkerMessages } from './serve-worker-messages.js';
 
 /**
- * Score a pre-sourced content string (Story #3696). Mirrors
- * `native.js#scoreSourceReport`: transpile the source by its `label`
- * extension, then report. A null transpile (unsupported / failed) resolves
- * to a parse-error report rather than throwing, matching the disk path.
+ * Report for pre-sourced content; a failed transpile is a parse-error report.
  *
  * @param {string} source
  * @param {string} label  Path used only to pick the transpile mode.
@@ -67,9 +36,7 @@ function reportFromSource(source, label) {
 }
 
 /**
- * Pure handler for a single inbound worker message. Exported so unit
- * tests can drive each branch (exit, malformed item, success, error)
- * without spawning a real `Worker` thread.
+ * Pure handler for one worker message (testable without a `Worker`).
  *
  * @param {unknown} msg
  * @param {{ report?: (filePath: string) => object }} [deps]
@@ -106,11 +73,7 @@ export function handleMaintainabilityReportWorkerMessage(msg, deps = {}) {
       message: { ok: true, result: { filePath, report } },
     };
   } catch (err) {
-    // I/O or other unexpected error (e.g. file deleted between diff and
-    // scoring) — surface as a per-item null report so the run keeps
-    // going. The native classifier maps a null report to a dropped file,
-    // matching the serial path's `classifyChangedFile` try/catch that
-    // returns `{ row: null }` on a thrown reportFn.
+    // A null report drops the file and keeps the run going.
     return {
       kind: 'reply',
       message: {

package/.agents/scripts/lib/workers/maintainability-worker.js

@@ -1,22 +1,8 @@
 /**
- * lib/workers/maintainability-worker.js — CPU-pool worker entry for
- * `calculateAll`. One file in, one score out. No project config, no git,
- * no provider — just typhonjs-escomplex (via maintainability-engine) and
- * the in-memory TS transpile shim.
- *
- * Message contract — see lib/cpu-pool.js:
- *   IN  : { item: string }      — absolute file path to score
- *         { exit: true }        — drain & terminate
- *   OUT : { ok: true, result: { filePath, score, unscorable?, reason? } }
- *
- * `score` is `null` only when the file genuinely cannot be read (ENOENT
- * or other I/O error).
- *
- * A file the kernel cannot analyse comes back as `unscorable: true` with the
- * kernel's own `reason`, rather than as a bare `0`. The `0` is still carried in
- * `score` for wire compatibility, but it is no longer the only signal — the
- * point of the flag is that the caller can *report* the file instead of
- * silently dropping it (see `maintainability-engine.js`'s `UNSCORABLE`).
+ * CPU-pool worker for `calculateAll`: one file path in, one MI score out.
+ * `score` is `null` only on an I/O error. An unanalysable file carries
+ * `unscorable: true` and the kernel's `reason` (with `score: 0` for wire
+ * compatibility) so the caller reports it instead of silently dropping it.
  */
 
 import { parentPort } from 'node:worker_threads';
@@ -24,9 +10,7 @@ import { scoreFile } from '../maintainability-engine.js';
 import { serveWorkerMessages } from './serve-worker-messages.js';
 
 /**
- * Pure handler for a single inbound worker message. Exported so unit
- * tests can drive each branch (exit, malformed item, success, error)
- * without spawning a real `Worker` thread.
+ * Pure handler for one worker message (testable without a `Worker`).
  *
  * @param {unknown} msg
  * @param {{ score?: (filePath: string) => { score: number, unscorable: boolean, reason: string|null } }} [deps]

package/.agents/scripts/lib/workers/serve-worker-messages.js

@@ -1,22 +1,6 @@
 /**
- * lib/workers/serve-worker-messages.js — the shared CPU-pool worker skeleton.
- *
- * Every worker under `lib/workers/` is a pure message handler plus the same
- * eight-line `parentPort` wiring: subscribe, run the handler, close on an
- * `exit` verdict, post the reply otherwise. That wiring was copied into all
- * four workers; it lives here once instead (Story #4926).
- *
- * The handler contract is unchanged — see `lib/cpu-pool.js`:
- *   IN  : `{ item: … }` — one unit of work
- *         `{ exit: true }` — drain & terminate
- *   OUT : `{ kind: 'exit' }` | `{ kind: 'reply', message: object }`
- */
-
-/**
- * Wire a pure worker message handler onto a `worker_threads` port.
- *
- * A falsy `port` is a no-op, so a worker module imported directly by a unit
- * test (where `parentPort` is `null`) installs no listener and stays pure.
+ * Wire a pure worker message handler onto a `worker_threads` port. A falsy
+ * port (module imported by a test) is a no-op.
  *
  * @param {import('node:worker_threads').MessagePort|null|undefined} port
  * @param {(msg: unknown) => {kind: 'exit'} | {kind: 'reply', message: object}} handle

package/.agents/scripts/lib/workflow-closure.js

@@ -1,61 +1,17 @@
 /**
- * Workflow read-tier closure resolver (Story #4752).
- *
- * `.agents/workflows/**` is the largest body of instruction Mandrel ships, and
- * until this module it sat in none of the five doc read-tiers `doc-tiers.js`
- * resolves — measured only by a per-file spine ceiling that is satisfied by
- * moving prose into a linked helper. Workflows are a **graph**, not a flat set,
- * so this module resolves each entry point's transitive markdown-link closure
- * into two numbers:
- *
- *   - **mandatory closure** — the entry point plus the transitive closure of
- *     its `mandatoryReads:` frontmatter edges. This is what a session is
- *     *forced* to read, and it is what `check-context-budget.js` ratchets.
- *   - **reachable closure** — the entry point plus every workflow markdown file
- *     transitively linked from it. Recorded as a drift signal, never gated.
- *
- * **The marker is source-side and per-edge.** A workflow declares the reads it
- * requires in its own frontmatter (`mandatoryReads: [path, …]`, flow or block
- * style, resolved relative to the declaring file). Tier is not intrinsic to a
- * helper — the same file is mandatory from one workflow and on-demand from
- * another — so it cannot live in the target. The key is optional: an absent
- * key means zero mandatory edges and is never an error. Every reachable link
- * not named in `mandatoryReads` is classified on-demand.
- *
- * **Entry points** are the workflows a session can be invoked on: every
- * top-level `.agents/workflows/*.md`, plus any `helpers/*.md` whose H1 declares
- * a slash command named after the file itself (`helpers/deliver-story.md` →
- * `# /deliver-story …`) — a command-shaped helper is invoked directly, so it
- * owns a closure of its own. Plain helpers and appendices are reachable, never
- * entry points; counting every file as an entry point would collapse the
- * mandatory/on-demand distinction into "all workflow bytes".
- *
- * **Failure modes are loud** — a ratchet that silently shrinks its own closure
- * is worse than none:
- *   - a `mandatoryReads` entry that does not resolve to a workflow markdown
- *     file throws, naming the declaring workflow and the offending path;
- *   - a cycle among `mandatoryReads` edges throws, naming the cycle.
- * The **reachable** walk is deliberately cycle-*tolerant* rather than fatal:
- * bidirectional prose cross-references are normal and correct authoring (a
- * spine points at its digest, the digest points back at the spine), so that
- * walk terminates via a visited set and counts each file exactly once — it
- * neither loops nor truncates. Only the gated mandatory graph, where a loop is
- * a genuine authoring error, fails closed.
- *
- * The walk is confined to `.agents/workflows/**`: links out to
- * `.agents/rules/**` or `.agents/skills/**` are neither followed nor recorded,
- * because those are already tiered as flat sets by `doc-tiers.js` and
- * following them would double-count them.
- *
- * Security (security-baseline § Data Leakage & Logging): every value returned
- * or thrown is a repo-relative path or a byte count — never file contents.
+ * Workflow read-tier closures per entry point: **mandatory** (transitive
+ * `mandatoryReads:` frontmatter edges — ratcheted by `check-context-budget.js`)
+ * and **reachable** (transitive links — recorded, never gated). Tier is
+ * per-edge, so it lives in the declaring file. An unresolvable or cyclic
+ * mandatory edge throws: a ratchet that silently shrinks is worse than none.
+ * Confined to `.agents/workflows/**` (`doc-tiers.js` tiers the rest). Outputs
+ * are paths and byte counts, never contents.
  */
 
 import nodeFs from 'node:fs';
 import path from 'node:path';
 
 /**
- * Repo-relative root of the workflow tree. The closure never escapes it.
  * @type {string}
  */
 const WORKFLOWS_ROOT = '.agents/workflows';
@@ -63,10 +19,8 @@ const WORKFLOWS_ROOT = '.agents/workflows';
 /** Path-segment count of a top-level workflow (`.agents/workflows/x.md`). */
 const TOP_LEVEL_DEPTH = 3;
 
-// All RegExp instances are built via the constructor (rather than literal
-// `/.../`) so the maintainability engine's AST walker (typhonjs-escomplex) can
-// score this file — it crashes on `RegExpLiteral` nodes. Same workaround as
-// lib/audit-suite/frontmatter.js.
+// RegExp constructors, not literals: typhonjs-escomplex (the MI engine)
+// crashes on `RegExpLiteral` nodes.
 // biome-ignore-start lint/complexity/useRegexLiterals: typhonjs-escomplex MI workaround
 const FRONTMATTER_RE = new RegExp(String.raw`^---\r?\n([\s\S]*?)\r?\n---`);
 const NEWLINE_RE = new RegExp(String.raw`\r?\n`);
@@ -77,7 +31,6 @@ const COMMAND_H1_RE = new RegExp(String.raw`^#\s+/([A-Za-z0-9._-]+)`, 'm');
 // biome-ignore-end lint/complexity/useRegexLiterals: typhonjs-escomplex MI workaround
 
 /**
- * Default fs surface — the same injectable subset `doc-tiers.js` uses.
  * @typedef {{
  *   readdirSync: (p: string, o?: object) => any[],
  *   readFileSync: (p: string, enc: string) => string,
@@ -86,13 +39,10 @@ const COMMAND_H1_RE = new RegExp(String.raw`^#\s+/([A-Za-z0-9._-]+)`, 'm');
  */
 
 /**
- * A loaded workflow document.
  * @typedef {{ rel: string, bytes: number, source: string }} WorkflowDoc
  */
 
 /**
- * Strip surrounding quotes and whitespace from a scalar YAML value.
- *
  * @param {string} value
  * @returns {string}
  */
@@ -106,8 +56,6 @@ function unquote(value) {
 }
 
 /**
- * Convert a path to posix separators.
- *
  * @param {string} p
  * @returns {string}
  */
@@ -116,8 +64,6 @@ function toPosix(p) {
 }
 
 /**
- * Return the raw frontmatter block of a markdown source (`''` when absent).
- *
  * @param {string} source
  * @returns {string}
  */
@@ -127,8 +73,7 @@ function frontmatterBlock(source) {
 }
 
 /**
- * Collect a YAML block-sequence (`- item`) starting at `start`. Blank lines are
- * skipped; the first non-item, non-blank line ends the sequence.
+ * YAML block sequence from `start`; blank lines skipped, first other line ends it.
  *
  * @param {string[]} lines
  * @param {number} start
@@ -149,8 +94,6 @@ function blockSequence(lines, start) {
 }
 
 /**
- * Split a YAML flow sequence (`[a.md, b.md]`) into its scalar items.
- *
  * @param {string} inline
  * @returns {string[]}
  */
@@ -163,9 +106,7 @@ function flowSequence(inline) {
 }
 
 /**
- * Parse the optional `mandatoryReads:` frontmatter list from a workflow source.
- * Supports the flow (`[a.md, b.md]`), block (`- a.md` lines), and single-scalar
- * forms. An absent key resolves to `[]` — zero mandatory edges, never an error.
+ * `mandatoryReads:` in flow, block, or scalar form; absent key → `[]`.
  *
  * @param {string} source
  * @returns {string[]} raw specifiers, relative to the declaring file
@@ -181,7 +122,7 @@ function parseMandatoryReads(source) {
 }
 
 /**
- * Harvest every markdown link target in a source, anchors stripped.
+ * Markdown link targets, anchors stripped.
  *
  * @param {string} source
  * @returns {string[]}
@@ -196,9 +137,8 @@ function parseLinkTargets(source) {
 }
 
 /**
- * Resolve a link/`mandatoryReads` specifier declared in `fromRel` to a known
- * workflow doc, or `null` when it is external, non-markdown, or outside the
- * workflow tree.
+ * Resolve a specifier to a known workflow doc, or `null` when external,
+ * non-markdown, or outside the workflow tree.
  *
  * @param {string} fromRel repo-relative posix path of the declaring file
  * @param {string} spec
@@ -213,11 +153,6 @@ function resolveSpec(fromRel, spec, docs) {
 }
 
 /**
- * Resolve a workflow's declared mandatory edges. Throws when an entry does not
- * resolve to a workflow markdown file — a mandatory read pointing at nothing is
- * a silent hole in the ratchet, so it fails loudly, naming both the declaring
- * workflow and the offending path.
- *
  * @param {WorkflowDoc} doc
  * @param {Map<string, WorkflowDoc>} docs
  * @returns {string[]}
@@ -237,9 +172,7 @@ function mandatoryEdges(doc, docs) {
 }
 
 /**
- * Depth-first walk of the mandatory-edge graph. Cycle-fatal: a `mandatoryReads`
- * loop is an authoring error, so it throws naming the cycle rather than looping
- * or silently truncating the closure.
+ * Cycle-fatal DFS of the mandatory-edge graph.
  *
  * @param {string} rel
  * @param {Map<string, WorkflowDoc>} docs
@@ -264,10 +197,7 @@ function walkMandatory(rel, docs, stack, seen) {
 }
 
 /**
- * Breadth-first walk of the markdown-link graph. Cycle-tolerant by design:
- * bidirectional cross-references between a spine and its helper are correct
- * authoring, so the visited set makes the walk terminate with each file counted
- * exactly once.
+ * Cycle-tolerant BFS of the link graph; each file counted once.
  *
  * @param {string} rel
  * @param {Map<string, WorkflowDoc>} docs
@@ -289,8 +219,7 @@ function walkReachable(rel, docs) {
 }
 
 /**
- * Recursively collect repo-relative posix paths of every `.md` file under an
- * absolute directory. An unreadable directory yields nothing (silent skip).
+ * Recursive `.md` listing; an unreadable directory yields nothing.
  *
  * @param {FsLike} fs
  * @param {string} dirAbs
@@ -315,8 +244,6 @@ function listMarkdown(fs, dirAbs, root, out) {
 }
 
 /**
- * Load every workflow markdown file into a `rel -> { rel, bytes, source }` map.
- *
  * @param {string} root absolute repo root
  * @param {FsLike} fs
  * @returns {Map<string, WorkflowDoc>}
@@ -333,19 +260,15 @@ function loadDocs(root, fs) {
         source: fs.readFileSync(abs, 'utf8'),
       });
     } catch {
-      // Unreadable file — skipped silently, like the sibling tier resolvers.
+      // Unreadable file — skipped.
     }
   }
   return docs;
 }
 
 /**
- * True when a workflow is invocable in its own right: a top-level workflow, or
- * a helper whose H1 declares a slash command **named after the file itself**
- * (`helpers/deliver-story.md` → `# /deliver-story …`). The self-naming test is
- * what separates an invocable helper from an appendix that merely titles itself
- * after the command it documents (`helpers/deliver-reference.md` →
- * `# /mandrel-deliver — reference appendix`), which is read on demand, never invoked.
+ * Top-level workflow, or a helper whose H1 slash command matches its own
+ * filename — an appendix titled after the command it documents is not.
  *
  * @param {WorkflowDoc} doc
  * @returns {boolean}
@@ -357,8 +280,6 @@ function isEntryPoint(doc) {
 }
 
 /**
- * Materialize a path set as sorted `{ path, bytes }` entries.
- *
  * @param {Iterable<string>} rels
  * @param {Map<string, WorkflowDoc>} docs
  * @returns {Array<{ path: string, bytes: number }>}
@@ -370,8 +291,6 @@ function toEntries(rels, docs) {
 }
 
 /**
- * Sum the on-disk bytes of a path set.
- *
  * @param {Iterable<string>} rels
  * @param {Map<string, WorkflowDoc>} docs
  * @returns {number}
@@ -383,10 +302,8 @@ function sumBytes(rels, docs) {
 }
 
 /**
- * Resolve the workflow tier: every entry point's transitive markdown-link
- * closure, partitioned into the gated mandatory set and the recorded on-demand
- * remainder. Returns empty collections when `.agents/workflows` is absent — an
- * entry point resolving empty is skipped silently.
+ * Resolve every entry point's closures, partitioned into mandatory and
+ * on-demand; empty collections when `.agents/workflows` is absent.
  *
  * @param {string} root absolute repo root
  * @param {{ fs?: FsLike }} [opts]

package/.agents/scripts/lib/workspace-provisioner.js

@@ -1,40 +1,16 @@
 /**
- * workspace-provisioner.js
- *
- * Central authority for populating a fresh worktree (or remote-runner checkout)
- * with gitignored workspace files — by default `.env`, `.mcp.json`, and the
- * operator's local-override files (`.agentrc.local.json`,
- * `.agents/instructions.local.md`) — plus any other files declared in
- * `.agentrc.json orchestration.workspaceFiles`. The local-override files are
- * provisioned so a worktree-isolated agent honors the §1.E local-override
- * contract (e.g. `github.operatorHandle`) rather than silently falling back to
- * the committed `.agentrc.json` placeholders. Every caller that needs these
- * files in a non-main checkout should go through this module; ad-hoc copy
- * logic elsewhere in the codebase is a bug.
- *
- * Public API:
- *   - `provision({ sourceRoot, targetWorktree, files?, logger? })` — copies
- *     each listed file from source to target, skipping any that already exist
- *     at the target. Returns `{ copied, skipped, missing }`.
- *   - `verify({ worktree, files?, sourceRoot? })` — throws when a required
- *     file is missing. When `sourceRoot` is passed, the error carries a
- *     copy-ready remediation command the operator can run verbatim.
- *   - `resolveWorkspaceFiles(orchestrationConfig)` — resolves the list honoring
- *     the new `orchestration.workspaceFiles` key, the legacy
- *     `orchestration.worktreeIsolation.bootstrapFiles`, and the default.
- *   - `DEFAULT_WORKSPACE_FILES` — `['.env', '.mcp.json', '.agentrc.local.json',
- *     '.agents/instructions.local.md']`.
+ * The single authority for copying gitignored workspace files (`.env`,
+ * `.mcp.json`, local overrides) into a non-main checkout, so a worktree agent
+ * honours local overrides instead of committed placeholders. Ad-hoc copy
+ * logic elsewhere is a bug.
  */
 
 import fs from 'node:fs';
 import path from 'node:path';
 import { NOOP_LOGGER } from './Logger.js';
 
-// Keep in sync with `WORKTREE_ISOLATION_DEFAULTS.bootstrapFiles` in
-// `./config/worktree-isolation.js`. The local-override files are listed even
-// though they are frequently absent — `provision()` skips missing sources and
-// `verify()` callers filter to files present at the source first, so a missing
-// override never fails a worktree create.
+// Keep in sync with `WORKTREE_ISOLATION_DEFAULTS.bootstrapFiles`. Often-absent
+// overrides are safe: missing sources are skipped, never fatal.
 export const DEFAULT_WORKSPACE_FILES = [
   '.env',
   '.mcp.json',
@@ -43,10 +19,8 @@ export const DEFAULT_WORKSPACE_FILES = [
 ];
 
 /**
- * Resolve the list of workspace files to provision.
- *
- * Precedence: explicit `orchestration.workspaceFiles` → legacy
- * `orchestration.worktreeIsolation.bootstrapFiles` → `DEFAULT_WORKSPACE_FILES`.
+ * `workspaceFiles` → legacy `worktreeIsolation.bootstrapFiles` (still
+ * schema-accepted) → defaults.
  *
  * @param {object} [orchestrationConfig]
  * @returns {string[]}
@@ -54,18 +28,12 @@ export const DEFAULT_WORKSPACE_FILES = [
 export function resolveWorkspaceFiles(orchestrationConfig) {
   const cfg = orchestrationConfig ?? {};
   if (Array.isArray(cfg.workspaceFiles)) return cfg.workspaceFiles.slice();
-  // Legacy `worktreeIsolation.bootstrapFiles` fallback — surviving callers:
-  // tests/lib/workspace-provisioner.test.js, tests/lib/worktree/bootstrapper.test.js,
-  // and consumer projects' `.agentrc.json` (config-schema still accepts it).
   const legacy = cfg.worktreeIsolation?.bootstrapFiles;
   if (Array.isArray(legacy)) return legacy.slice();
   return DEFAULT_WORKSPACE_FILES.slice();
 }
 
 /**
- * Validate a workspace-file name — must be relative, no `..`, no NULs, no
- * absolute paths.
- *
  * @param {string} name
  * @returns {string|null}  null on success, reason string on failure.
  */
@@ -79,15 +47,13 @@ function invalidNameReason(name) {
 }
 
 /**
- * Copy configured workspace files from `sourceRoot` into `targetWorktree`.
- * Existing target files are preserved (never overwritten). Missing sources are
- * silently skipped and reported in the `missing` array.
+ * Never overwrites a target file; missing sources are reported, not fatal.
  *
  * @param {object} opts
- * @param {string} opts.sourceRoot     Absolute path to the main repo.
- * @param {string} opts.targetWorktree Absolute path to the target worktree.
- * @param {string[]} [opts.files]      File list; defaults to DEFAULT_WORKSPACE_FILES.
- * @param {object} [opts.logger]       `{ info, warn, error }`.
+ * @param {string} opts.sourceRoot
+ * @param {string} opts.targetWorktree
+ * @param {string[]} [opts.files]
+ * @param {object} [opts.logger]
  * @returns {{ copied: string[], skipped: string[], missing: string[] }}
  */
 export function provision({
@@ -143,17 +109,13 @@ export function provision({
 }
 
 /**
- * Throw if any required workspace file is missing from `worktree`. Used as a
- * runtime guard (called right after every worktree create in
- * `single-story-init.js`) and as a test oracle.
- *
- * When `sourceRoot` is supplied, the thrown error carries the missing target
- * path and an exact `cp`/`copy` command the operator can paste to remediate.
+ * Throw if a required file is missing; with `sourceRoot`, the error carries a
+ * paste-ready copy command.
  *
  * @param {object} opts
  * @param {string} opts.worktree
  * @param {string[]} [opts.files]
- * @param {string} [opts.sourceRoot] Main repo path; enables remediation hint.
+ * @param {string} [opts.sourceRoot]
  */
 export function verify({
   worktree,