mandrel 2.59.0 → 2.61.0

package/.agents/scripts/lib/checks/loop-health.js

@@ -1,34 +1,8 @@
 /**
- * loop-health.js — read-only retro-scope check for the feedback-loop
- * substrate (Epic #4406 / Story #4419, the terminal slice).
- *
- * The original feedback-loop drift shipped silently because an empty
- * feedback report is indistinguishable from a healthy one. This standing
- * self-check closes that gap: at retro time it samples the on-disk signal
- * substrate the sibling Stories established and surfaces the two ways the
- * repaired loop can regress without anyone noticing:
- *
- *   1. **Schema-invalid signal lines.** It tails the most recent
- *      {@link MAX_SAMPLE_LINES} lines of every `signals.ndjson` stream under
- *      the run temp tree and validates each against the canonical
- *      `signal-event.schema.json` (via `validateSignal`, the same validator
- *      the writer uses — no hand-rolled drift).
- *   2. **Un-actioned retro proposals.** It reads the retro mirror
- *      (`temp/run-<id>/retro.md`, Story #4418) and flags any actionable
- *      "Proposed issues" item that carries neither a filed-issue reference
- *      (`Filed: [#N](url)`) nor lives under the explicit "One-off /
- *      discarded" record.
- *
- * Contract:
- *   - Scope `retro`, `autoCorrect: 'refuse-and-print'` — read-only by
- *     construction; the runner refuses `autoFix` under the retro scope.
- *   - A clean substrate (valid lines, every proposal filed or
- *     discarded) yields **zero findings**, preserving the compact retro
- *     shape. Only when a concern is non-zero does `detect` return a single
- *     combined finding naming every non-clean dimension.
- *   - No new provider plumbing: `detect(state)` reads `state.cwd` from the
- *     existing cwd-scoped checks-registry state, anchors it to the main
- *     checkout root, and reads the temp tree directly.
+ * Read-only retro check for the feedback-loop substrate — an empty feedback
+ * report looks healthy, so this surfaces schema-invalid signal samples
+ * (validated with the writer's own validator) and actionable retro
+ * proposals neither filed nor discarded. A clean substrate yields no finding.
  */
 
 import { readdirSync, readFileSync, statSync } from 'node:fs';
@@ -37,18 +11,11 @@ import path from 'node:path';
 import { mainCheckoutRoot, tempRootFrom } from '../config/temp-paths.js';
 import { validateSignal } from '../observability/signal-validator.js';
 
-/**
- * Lines sampled from the tail of each `signals.ndjson` stream. The check is
- * a health probe, not an exhaustive audit — the most recent window is a
- * representative sample that keeps the read bounded on long streams.
- */
+/** Tail window per stream: a bounded health probe, not an audit. */
 const MAX_SAMPLE_LINES = 200;
 
 /**
- * Locate the most-recently-touched `run-<id>` temp tree under
- * `<baseDir>/<tempRoot>` (the layout `lib/config/temp-paths.js` creates).
- * Returns `{ epicId, epicDir }` or `null` when no run temp tree exists (a
- * fresh checkout, or a context with no run in flight).
+ * Most-recently-touched `run-<id>` temp tree, or `null`.
  *
  * @param {string} baseDir  The main checkout root.
  * @param {{ tempRoot?: string, fsImpl?: { readdirSync: typeof readdirSync, statSync: typeof statSync } }} [opts]
@@ -87,8 +54,7 @@ export function resolveEpicTempTree(
 }
 
 /**
- * Enumerate every `signals.ndjson` stream under an Epic temp tree: the
- * Epic-level wave-lifecycle stream plus each per-Story stream.
+ * The run-level stream plus each per-Story stream.
  *
  * @param {string} epicDir
  * @param {{ fsImpl?: { readdirSync: typeof readdirSync, statSync: typeof statSync } }} [opts]
@@ -123,9 +89,7 @@ export function findSignalStreams(epicDir, { fsImpl } = {}) {
 }
 
 /**
- * Tail `maxLines` of a single stream and count how many sampled lines fail
- * the canonical schema (a JSON parse failure counts as invalid). A missing
- * or unreadable stream contributes zero — absence is not invalidity.
+ * Unparseable lines count as invalid; an unreadable stream counts zero.
  *
  * @param {string} streamPath
  * @param {{ validate?: typeof validateSignal, maxLines?: number, readImpl?: typeof readFileSync }} [opts]
@@ -165,12 +129,8 @@ export function sampleStreamInvalidCount(
 }
 
 /**
- * Scan a retro mirror body for actionable proposals that were neither filed
- * nor discarded. An actionable proposal is a `- **Title**` item under a
- * `### Proposed issues` heading whose body carries a paste-ready
- * `gh issue create` stanza (the un-filed fallback) instead of a
- * `Filed: [#N](url)` reference. Discarded proposals live under the separate
- * "### One-off / discarded" heading and are never scanned here.
+ * Unfiled = a `### Proposed issues` item carrying a `gh issue create` stanza
+ * and no `Filed:` line. Discarded proposals sit under another heading.
  *
  * @param {string} retroText
  * @returns {string[]}  Titles of unfiled actionable proposals.
@@ -211,9 +171,7 @@ export function scanRetroMirror(retroText) {
 }
 
 /**
- * Core detection: locate the Epic temp tree under `baseDir`, sample its
- * signal streams, and scan its retro mirror. Returns a single combined
- * finding when either dimension is non-clean, else `null`.
+ * One combined finding when either dimension is non-clean, else `null`.
  *
  * @param {string} baseDir
  * @param {{

package/.agents/scripts/lib/checks/state.js

@@ -1,34 +1,9 @@
 /**
- * checks/state.js — Scope-aware state assembler for the checks registry.
+ * Scope-aware, memoized state assembler for the checks registry: each scope
+ * probes only the keys its checks need.
  *
- * `assembleState({ scope })` returns the subset of environment/git/fs probes
- * that checks declared for the given scope actually need. The runner in
- * `index.js` filters the registry by `scope` first, then asks this module
- * for state; the per-scope projection keeps probe cost proportional to the
- * call site (e.g. `story-close` does not pay for `diagnose` probes, and
- * the `retro` consumer only probes inputs the retro-scoped checks need).
- *
- * Privacy contract:
- *   - The `env` projection records **presence only** (`'set' | 'missing'`).
- *     It must never return, log, or otherwise expose the value of any
- *     environment variable. Specifically `GITHUB_TOKEN` and similarly
- *     scoped secrets are reduced to a single `'set'` / `'missing'` string
- *     before reaching the caller.
- *   - The `fs` projection records the **existence** of bootstrap files
- *     (`.env`, `.mcp.json`, `.worktrees/`); it does not read their contents.
- *
- * Memoization:
- *   - Results are cached per-scope by a module-local `Map`. Repeated calls
- *     with the same scope reuse the prior result without re-running any
- *     probe (verifiable via a probe spy in unit tests).
- *   - Different scopes get independent entries — they probe different keys
- *     and must not share a cached object.
- *   - `clearStateCache()` is exported for tests so a fresh probe matrix can
- *     be observed without restarting the process.
- *
- * Probes are injectable for testing. Production callers omit the `probes`
- * option and get the real `git` / `fs` / `process.env` probes; tests pass
- * spy probes to assert call counts and shapes.
+ * Privacy contract: `env` records presence only (`'set' | 'missing'`), never a
+ * value; `fs` records existence only, never contents.
  */
 
 import { spawnSync } from 'node:child_process';
@@ -36,17 +11,11 @@ import { existsSync } from 'node:fs';
 import path from 'node:path';
 
 /**
- * Scope → declared keys. Each scope only assembles the state its checks
- * need. Adding a new scope (or extending an existing one) is a deliberate
- * edit here — checks should not silently grow the probe surface.
- *
- * Keys are namespaced by category (`git.*`, `fs.*`, `env.*`) so the probe
- * dispatcher can route them without re-parsing.
+ * Scope → probe keys (`git.*`, `fs.*`, `env.*`). Growing the probe surface is
+ * a deliberate edit here.
  *
  * @type {Record<string, readonly string[]>}
  */
-// Story-close probe surface: branch list + worktree set. Story #1289
-// introduced the `npm-test` alias.
 const STORY_CLOSE_KEYS = Object.freeze([
   'git.headRef',
   'git.localBranches',
@@ -73,33 +42,25 @@ const SCOPE_KEYS = Object.freeze({
     'fs.dotEnv',
     'fs.dotMcp',
   ]),
-  // git.coreBare: core-bare-clean declares scope ['story-close', 'retro',
-  // 'npm-test']; without the probe key its detect() reads undefined and the
-  // retro leg is a silent no-op (#4580).
+  // core-bare-clean runs in retro; without git.coreBare its detect() is a
+  // silent no-op.
   retro: Object.freeze(['git.headRef', 'git.coreBare', 'fs.worktrees']),
   diagnose: DIAGNOSE_KEYS,
 });
 
 /**
- * Module-local cache. Keyed by `${scope}::${cwd}` so a test that swaps cwd
- * does not collide with a prior probe matrix.
+ * Keyed by `${scope}::${cwd}`.
  *
  * @type {Map<string, StateObject>}
  */
 const cache = new Map();
 
-/**
- * Clear the memoization cache. Tests call this between cases to observe a
- * fresh probe matrix without restarting the process.
- */
 export function clearStateCache() {
   cache.clear();
 }
 
 /**
- * Default git probe — `spawnSync` wrapper that never throws. A non-zero
- * exit is reported as `{ ok: false, stdout: '' }` so callers can treat the
- * absence of a ref as "missing" rather than crashing the probe assembly.
+ * Never throws; a failure reads as `{ ok: false }`.
  *
  * @param {string} cwd
  * @param {...string} args
@@ -114,8 +75,6 @@ function defaultGitProbe(cwd, ...args) {
 }
 
 /**
- * Default fs probe — `existsSync` wrapper. Never reads file contents.
- *
  * @param {string} absPath
  * @returns {boolean}
  */
@@ -124,9 +83,6 @@ function defaultFsProbe(absPath) {
 }
 
 /**
- * Default env probe — returns `'set' | 'missing'` for the named variable.
- * Never returns the value.
- *
  * @param {string} name
  * @returns {'set' | 'missing'}
  */
@@ -135,9 +91,6 @@ function defaultEnvProbe(name) {
 }
 
 /**
- * Probe the current HEAD ref (short / abbreviated form). Returns the branch
- * name, or `null` when git cannot resolve HEAD (detached / non-repo).
- *
  * @param {object} args
  * @param {string} args.cwd
  * @param {(cwd: string, ...args: string[]) => { ok: boolean, stdout: string }} args.git
@@ -149,9 +102,6 @@ function probeHeadRef({ cwd, git }) {
 }
 
 /**
- * Split a newline-delimited `for-each-ref --format='%(refname:short)'`
- * payload into a trimmed, non-empty short-name list.
- *
  * @param {{ ok: boolean, stdout: string }} result
  * @returns {string[]}
  */
@@ -165,9 +115,6 @@ function parseBranchList(result) {
 }
 
 /**
- * Probe all local branches (`refs/heads/`), short-name form. Used by checks
- * that grep over the branch list for legacy naming patterns.
- *
  * @param {object} args
  * @param {string} args.cwd
  * @param {(cwd: string, ...args: string[]) => { ok: boolean, stdout: string }} args.git
@@ -180,8 +127,6 @@ function probeLocalBranches({ cwd, git }) {
 }
 
 /**
- * Probe `core.bare`. Returns the config value, or `null` when unset.
- *
  * @param {object} args
  * @param {string} args.cwd
  * @param {(cwd: string, ...args: string[]) => { ok: boolean, stdout: string }} args.git
@@ -193,11 +138,7 @@ function probeCoreBare({ cwd, git }) {
 }
 
 /**
- * Handler map keyed by git probe field name (the part after `git.`). Each
- * handler receives `{ cwd, git }` and returns the field's value.
- *
- * Story #3351: replaces the prior if/else ladder so each probe is
- * independently testable.
+ * Keyed by the field after `git.`.
  *
  * @type {Record<string, (ctx: { cwd: string, git: (cwd: string, ...args: string[]) => { ok: boolean, stdout: string } }) => unknown>}
  */
@@ -208,9 +149,6 @@ const GIT_PROBES = Object.freeze({
 });
 
 /**
- * Build the git projection for a key list by iterating the `GIT_PROBES`
- * handler map.
- *
  * @param {readonly string[]} keys
  * @param {string} cwd
  * @param {(cwd: string, ...args: string[]) => { ok: boolean, stdout: string }} git
@@ -229,8 +167,6 @@ function probeGit(keys, cwd, git) {
 }
 
 /**
- * Build the fs projection for a key list.
- *
  * @param {readonly string[]} keys
  * @param {string} cwd
  * @param {(absPath: string) => boolean} fs
@@ -253,8 +189,6 @@ function probeFs(keys, cwd, fs) {
 }
 
 /**
- * Build the env projection for a key list. Presence only.
- *
  * @param {readonly string[]} keys
  * @param {(name: string) => 'set' | 'missing'} env
  * @returns {Record<string, 'set' | 'missing'>}
@@ -270,17 +204,13 @@ function probeEnv(keys, env) {
 }
 
 /**
- * Scope-aware state assembler. Returns a frozen state object with
- * `{ git, fs, env, scope }` projections populated only for the keys the
- * scope declares. Memoized per `(scope, cwd)`.
+ * Frozen state with projections for the scope's keys only; memoized per
+ * `(scope, cwd)` unless `probes` are injected.
  *
  * @param {object} [opts]
- * @param {string} [opts.scope]  Required in practice — every consumer is
- *   scope-specific. An undefined scope returns an empty projection (used
- *   only by tests that want to verify the no-op path).
+ * @param {string} [opts.scope]  Undefined yields an empty projection.
  * @param {string} [opts.cwd=process.cwd()]
- * @param {object} [opts.probes]  Test injection — `{ git, fs, env }` spies.
- *   Production callers omit this and get the default probes.
+ * @param {object} [opts.probes]  `{ git, fs, env }` test spies.
  * @returns {StateObject}
  *
  * @typedef {object} StateObject
@@ -300,8 +230,7 @@ export function assembleState({ scope, cwd = process.cwd(), probes } = {}) {
   const envProbe = probes?.env ?? defaultEnvProbe;
   const gitProjection = probeGit(keys, cwd, gitProbe);
   const fsProjection = probeFs(keys, cwd, fsProbe);
-  // Story #1289: `cwd` is surfaced so fs-scanning checks target the
-  // worktree they were assembled for.
+  // `cwd` lets fs-scanning checks target the worktree they were assembled for.
   const state = Object.freeze({
     scope,
     cwd,
@@ -310,16 +239,12 @@ export function assembleState({ scope, cwd = process.cwd(), probes } = {}) {
     env: Object.freeze(probeEnv(keys, envProbe)),
   });
   if (!probes) {
-    // Only memoize the default-probe path. Tests with injected spies want
-    // to observe call counts on every invocation.
     cache.set(cacheKey, state);
   }
   return state;
 }
 
 /**
- * Expose the scope → key map for tests and `/diagnose --show-scope`.
- *
  * @returns {Record<string, readonly string[]>}
  */
 export function getScopeKeys() {

package/.agents/scripts/lib/checks/story-init-not-backgrounded.js

@@ -1,29 +1,8 @@
 /**
- * story-init-not-backgrounded — refuse-and-print check.
- *
- * Detects orchestration call sites that invoke `single-story-init.js` via
- * the Bash tool's `run_in_background: true` mode (with subsequent `Monitor`
- * waiting on completion) instead of a synchronous Bash call with a
- * 10-minute timeout. This guards the failure mode where `Monitor`'s wait
- * is not equivalent to script exit — a sub-agent that exits during a
- * Monitor wait kills `single-story-init.js` mid-run, leaving a
- * half-initialized worktree.
- *
- * Scope: 'story-close', 'retro'. The check runs at every
- * preflight surface that has the opportunity to invoke Story init —
- * primarily `/mandrel-deliver`'s init step — and surfaces as a retro audit
- * signal if the failure mode resurfaces during a sprint.
- *
- * The check is `refuse-and-print`. Auto-rewriting an orchestration call
- * site would change runtime behavior on a script the operator may be
- * actively iterating on; the fixCommand prints the canonical
- * synchronous-call replacement pattern so they can apply it deliberately.
- *
- * Implementation note: we scan `.agents/` (markdown + js) for the
- * juxtaposition of a `story-init.js` reference (which also matches
- * `single-story-init.js` as a suffix) and a backgrounding token
- * (`run_in_background: true`, the literal `Monitor` tool name as a
- * fan-out target, or `&` shell backgrounding) within a small line window.
+ * Flags call sites that background `single-story-init.js` instead of calling
+ * it synchronously: a sub-agent exiting during a `Monitor` wait kills init
+ * mid-run and leaves a half-initialized worktree. Refuse-and-print, since
+ * rewriting a call site would change behaviour the operator may be editing.
  */
 
 import nodeFs from 'node:fs';
@@ -33,15 +12,8 @@ const SCAN_ROOT_DEFAULT = '.agents';
 const WINDOW_LINES = 20;
 
 /**
- * Backgrounding tokens. We only match shapes that are unambiguously
- * *invocation* syntax, never narrative prose like "do not use Monitor"
- * (which legitimately appears in docs warning against the antipattern).
- *
- * - `run_in_background: true` — Bash tool's backgrounding flag.
- * - `detached: true` — child_process.spawn options that detach the
- *   subprocess from the parent's lifecycle, equivalent to backgrounding.
- * - `single-story-init.js &` — POSIX shell ampersand backgrounding
- *   (the pattern matches the `story-init.js` suffix of both names).
+ * Invocation syntax only, never prose like "do not use Monitor" that docs
+ * legitimately carry.
  */
 const BACKGROUND_TOKENS = [
   /run_in_background\s*:\s*true/,
@@ -50,15 +22,6 @@ const BACKGROUND_TOKENS = [
 ];
 
 /**
- * Walk a directory recursively, yielding absolute file paths for `.js`
- * and `.md` sources. Skips `node_modules`, `.worktrees`, and directories
- * starting with `.git`.
- *
- * The optional final `fsImpl` parameter defaults to the real `node:fs`
- * (`.agents/rules/test-seams.md` rule 1) and is forwarded to the recursive
- * call rather than re-acquired there (rule 4), so a test drives the whole walk
- * through a plain stub object instead of module mocking (rule 5).
- *
  * @param {string} dir
  * @param {typeof nodeFs} [fsImpl]
  * @returns {string[]}
@@ -92,16 +55,7 @@ export function walkSources(dir, fsImpl = nodeFs) {
 }
 
 /**
- * For one file, return an array of `{ line, kind }` offences: every line
- * referencing `story-init.js` (including `single-story-init.js`) that has
- * a backgrounding token in the same ±WINDOW_LINES window.
- *
- * The check explicitly excludes the `single-story-init.js` file itself and
- * any dedicated check module (this file): the source-of-truth
- * implementation legitimately mentions itself.
- *
- * Pure: it is handed the already-read source, so it needs no filesystem seam
- * of its own.
+ * Every `story-init.js` line with a backgrounding token within ±WINDOW_LINES.
  *
  * @param {string} file
  * @param {string} src
@@ -109,11 +63,8 @@ export function walkSources(dir, fsImpl = nodeFs) {
  */
 export function scanFile(file, src) {
   const offences = [];
-  // Don't flag the actual story-init script, self-references, or the
-  // parallel-tooling helper — the helper documents both Rule 2
-  // (run_in_background) and the story-init backgrounding anti-pattern in
-  // adjacent bullets, which collides with the scanner's ±20-line window
-  // even though there is no real invocation in the prose.
+  // Skip the script, this check, and parallel-tooling.md, whose adjacent
+  // prose bullets fall inside one window with no real invocation.
   const basename = path.basename(file);
   if (
     basename === 'single-story-init.js' ||
@@ -160,9 +111,7 @@ export default {
 
   /**
    * @param {{ cwd?: string, scanRoot?: string, scope?: string }} [state]
-   * @param {typeof nodeFs} [fsImpl] Optional final filesystem seam; defaults
-   *   to the real `node:fs` (`.agents/rules/test-seams.md` rule 1) and is
-   *   forwarded to {@link walkSources} rather than re-acquired (rule 4).
+   * @param {typeof nodeFs} [fsImpl]
    */
   detect(state, fsImpl = nodeFs) {
     const cwd = state?.cwd ?? process.cwd();

package/.agents/scripts/lib/checks/subagent-agent-tool-required.js

@@ -1,43 +1,8 @@
 /**
- * subagent-agent-tool-required — supported-depth guard (refuse-and-print).
- *
- * Nested `Agent` dispatch from a sub-agent is **supported** on this Claude
- * Code build (verified depth 2, announced max depth 5 — Claude Code
- * 2.1.202, re-spiked 2026-07-08; see Epic #4385 / watch #2870). A level-1
- * sub-agent carries `Agent` in its primary toolset and can spawn a working
- * level-2 sub-agent. Declaring `Agent` in a sub-agent workflow is therefore
- * a legitimate design choice, **not** an automatic runtime failure.
- *
- * What this check guards is the one case that still fails: a fan-out whose
- * declared nesting depth exceeds the announced/supported ceiling. A dispatch
- * chain deeper than the harness supports will silently fail at runtime, so a
- * workflow that declares `Agent` together with a `nesting-depth` beyond the
- * ceiling is flagged as a blocker. A sub-agent that declares `Agent` at a
- * supported depth (the common case — an undeclared depth is treated as the
- * shallow level-1 fan-out) produces no finding.
- *
- * This inverts the historical guard (Story #4387): the check used to refuse
- * `Agent` in *any* sub-agent workflow on the now-false rationale that
- * sub-agents cannot dispatch. It no longer strips a real capability; it only
- * catches an over-deep fan-out. The self-healing surface is preserved — it is
- * re-scoped, not removed.
- *
- * Scope: 'retro'. Surfaces as audit signal at retro.
- *
- * The check is `refuse-and-print` — auto-rewriting a workflow's declared
- * depth or tool list would silently change runtime behavior in ways the
- * operator may not have intended. The fixCommand explains how to bring the
- * fan-out back under the ceiling (reduce the declared depth or split the
- * deepest level out), and is explicit that stripping `Agent` is NOT the fix.
- *
- * Implementation note: we scan `.agents/workflows/*.md` for workflow files
- * whose frontmatter or body identifies them as a sub-agent role AND whose
- * `tools:` declaration includes `Agent`, then read the workflow's declared
- * `nesting-depth`. The marker for "sub-agent" is the phrase `sub-agent`
- * appearing in the description / overview region. The depth is read from a
- * `nesting-depth:` (or `agent-depth:`) frontmatter field, or a
- * `<!-- nesting-depth: N -->` body marker; an absent declaration is treated
- * as depth 1 (a single, shallow fan-out level).
+ * Flags a sub-agent workflow that declares `Agent` with a fan-out deeper than
+ * the supported nesting ceiling — such a chain fails silently at runtime.
+ * Nested dispatch at a supported depth is legitimate. Refuse-and-print:
+ * rewriting depth or tools would change runtime behaviour unasked.
  */
 
 import { readdirSync, readFileSync } from 'node:fs';
@@ -46,21 +11,14 @@ import path from 'node:path';
 const WORKFLOWS_DIR_DEFAULT = path.join('.agents', 'workflows');
 
 /**
- * Announced maximum nesting depth the Claude Code harness supports for
- * sub-agent fan-out. Depth 2 is independently verified; depths 3–5 are
- * announced but not yet re-spiked (Epic #4385 / watch #2870). A workflow
- * declaring a fan-out deeper than this ceiling is flagged. Operators can pin
- * a stricter (or, once verified, looser) ceiling via `state.supportedDepth`.
+ * Harness-announced ceiling (only depth 2 is verified); `state.supportedDepth` overrides.
  *
  * @type {number}
  */
 export const ANNOUNCED_MAX_DEPTH = 5;
 
 /**
- * Walk a workflow directory and return absolute `.md` file paths
- * (non-recursive — the workflows surface is one level deep; helpers/
- * sub-directory holds procedural modules that are not invoked as
- * sub-agents in their own right).
+ * Non-recursive: `helpers/` modules are never sub-agents themselves.
  *
  * @param {string} dir
  * @returns {string[]}
@@ -78,9 +36,6 @@ function listWorkflowFiles(dir) {
 }
 
 /**
- * Extract the frontmatter block (between leading `---` lines) and the
- * body. Returns `{ frontmatter, body }` strings (either may be empty).
- *
  * @param {string} src
  * @returns {{ frontmatter: string, body: string }}
  */
@@ -89,19 +44,14 @@ function splitFrontmatter(src) {
   const end = src.indexOf('\n---', 3);
   if (end === -1) return { frontmatter: '', body: src };
   const frontmatter = src.slice(3, end);
-  // Skip past the closing `---` and the trailing newline.
   const bodyStart = src.indexOf('\n', end + 4);
   const body = bodyStart === -1 ? '' : src.slice(bodyStart + 1);
   return { frontmatter, body };
 }
 
 /**
- * True if the workflow document declares itself as a sub-agent. We
- * accept either the literal phrase `sub-agent` in the
- * description/overview region or the explicit phrase `runs as a
- * sub-agent`. The marker has to appear early in the document — past
- * the first ~100 lines we treat the mention as historical context
- * rather than a role declaration.
+ * `sub-agent` within the first 100 lines is a role declaration; later
+ * mentions are context.
  *
  * @param {string} src
  * @returns {boolean}
@@ -112,34 +62,25 @@ function isSubAgentWorkflow(src) {
 }
 
 /**
- * Inspect a workflow's `tools:` declaration (frontmatter OR inline body
- * note) for an `Agent` entry. Returns the offending textual fragment
- * (for the finding's detail field), or `null` if no `Agent` tool is
- * declared.
+ * Find an `Agent` entry in a flow- or block-style `tools:` list, in
+ * frontmatter or body; returns the fragment for the finding detail.
  *
  * @param {{ frontmatter: string, body: string }} parts
  * @returns {string | null}
  */
 function findAgentToolDeclaration(parts) {
   const { frontmatter, body } = parts;
-  // Frontmatter YAML — match either `tools: [..., Agent, ...]` (flow
-  // style) or block style with `- Agent`.
   const flowMatch = frontmatter.match(/tools\s*:\s*\[(.*?)\]/s);
   if (flowMatch && /\bAgent\b/.test(flowMatch[1])) {
     return `frontmatter tools: ${flowMatch[0].slice(0, 120)}`;
   }
-  // Block-style: `tools:` followed by `- item` lines. Use `m` flag and
-  // tolerate the trailing item line having no newline before the
-  // frontmatter terminator.
+  // The last item may lack a newline before the frontmatter terminator.
   const blockMatch = frontmatter.match(
     /tools\s*:\s*\n((?:[ \t]*-[ \t]*[^\n]+\n?)+)/,
   );
   if (blockMatch && /^[ \t]*-[ \t]*Agent\b/m.test(blockMatch[1])) {
     return `frontmatter tools (block): ${blockMatch[0].split('\n')[0]}`;
   }
-  // Body: same shape, e.g. operators sometimes document the tool list
-  // in a "## Tools" section. We accept either of the YAML shapes
-  // appearing in fenced code or inline.
   const bodyFlow = body.match(/tools\s*:\s*\[(.*?)\]/s);
   if (bodyFlow && /\bAgent\b/.test(bodyFlow[1])) {
     return `body tools: ${bodyFlow[0].slice(0, 120)}`;
@@ -152,12 +93,8 @@ function findAgentToolDeclaration(parts) {
 }
 
 /**
- * Parse the workflow's declared nesting depth. A sub-agent that declares
- * `Agent` may also declare how deep its fan-out reaches via a
- * `nesting-depth:` (or `agent-depth:`) frontmatter field, or a
- * `<!-- nesting-depth: N -->` marker in the body. Returns the integer
- * depth, or `null` when no depth is declared (the caller treats an absent
- * declaration as the shallow level-1 fan-out).
+ * From a `nesting-depth:`/`agent-depth:` frontmatter field or a
+ * `<!-- nesting-depth: N -->` body marker; `null` when undeclared.
  *
  * @param {{ frontmatter: string, body: string }} parts
  * @returns {number | null}
@@ -176,10 +113,6 @@ function parseDeclaredDepth(parts) {
 }
 
 /**
- * Resolve the supported depth ceiling for a detect run. Operators may pin a
- * stricter (or, once verified, looser) ceiling via `state.supportedDepth`;
- * an unset or non-positive-integer override falls back to the announced max.
- *
  * @param {{ supportedDepth?: unknown } | null | undefined} state
  * @returns {number}
  */
@@ -227,9 +160,7 @@ export default {
       const parts = splitFrontmatter(src);
       const where = findAgentToolDeclaration(parts);
       if (!where) continue;
-      // Declaring `Agent` is legitimate. Only a fan-out deeper than the
-      // supported ceiling is a runtime hazard; an undeclared depth is the
-      // shallow level-1 fan-out and always within the ceiling.
+      // An undeclared depth is the shallow level-1 fan-out.
       const depth = parseDeclaredDepth(parts) ?? 1;
       if (depth <= ceiling) continue;
       offences.push({