mandrel 2.60.0 → 2.61.0

package/.agents/scripts/evidence-gate.js

@@ -1,34 +1,10 @@
 #!/usr/bin/env node
 
 /**
- * evidence-gate.js — evidence-aware wrapper around a single shell gate.
- *
- * Tech Spec #819 §"Evidence record (Story 7)" — `/mandrel-deliver` Phase 3
- * (close-validation) runs `npm run lint` and `npm test` against the Epic
- * branch before opening the PR.
- * If the same gate has already passed against the current `git rev-parse
- * HEAD` (recorded earlier in the local hot path), this wrapper logs a skip
- * and exits 0 instead of re-spawning the runner. On run, a successful
- * gate is recorded so the next invocation can skip in turn.
- *
- * Usage:
- *   node .agents/scripts/evidence-gate.js \
- *     --standalone --scope-id <storyId> --gate <name> \
- *     [--worktree <path>] [--no-evidence] -- <cmd> [args...]
- *
- * Examples:
- *   node .agents/scripts/evidence-gate.js --standalone --scope-id 4250 --gate lint \
- *     --worktree .worktrees/story-4250 -- npm run lint
- *   node .agents/scripts/evidence-gate.js --standalone --scope-id 4250 --gate test \
- *     --worktree .worktrees/story-4250 -- npm test
- *
- * `--standalone` (Story #4250) is required: the evidence file is anchored on
- * the Story id at
- * `<tempRoot>/standalone/stories/story-<sid>/validation-evidence.json` — the
- * same keyspace the standalone close consults, so the acceptance-self-eval
- * critic's verify[] runs (lint / typecheck) are shared with the close.
- * v2.0.0 removed the Epic tier along with the `--epic-id` Epic-keyed
- * keyspace.
+ * Runs one gate, skipping it when evidence shows the same gate already
+ * passed for the current HEAD and tree, and recording a pass for the next
+ * caller. `--standalone` is required: it keys evidence by Story id, the same
+ * keyspace close consults, so worker-side verify[] runs credit the close.
  */
 
 import { spawnSync } from 'node:child_process';
@@ -44,12 +20,6 @@ import {
   treeFingerprint,
 } from './lib/validation-evidence.js';
 
-/**
- * Split argv at the first `--` and return both halves. The wrapper consumes
- * everything before `--`; the runner receives everything after.
- *
- * Exported for testing.
- */
 export function splitOnDashDash(argv) {
   const idx = argv.indexOf('--');
   if (idx === -1) return { wrapperArgs: argv, runnerArgs: [] };
@@ -59,11 +29,6 @@ export function splitOnDashDash(argv) {
   };
 }
 
-/**
- * Parse the wrapper-side argv (before `--`).
- *
- * Exported for testing.
- */
 export function parseWrapperArgs(argv) {
   const { values } = parseArgs({
     args: argv,
@@ -96,16 +61,9 @@ function resolveHeadShaDefault(cwd, gitSpawnFn) {
 }
 
 /**
- * The pair of keys an evidence record is written and read under: the commit
- * this gate ran at, and the content identity of the tree it ran against
- * (Story #5278).
- *
- * Both are read from the **spawn** cwd — the Story worktree when one is
- * supplied — so the keys describe the tree the gate actually saw. The tree
- * fingerprint is what keeps this gate credited across close's own base-sync
- * fast-forward, which moves HEAD between the deposit and the gates that would
- * spend it; see `validation-evidence.js#treeFingerprint`.
- *
+ * Read from the spawn cwd so the keys describe the tree the gate saw. The
+ * tree fingerprint keeps credit across close's base-sync fast-forward, which
+ * moves HEAD between deposit and spend.
  * @param {{ spawnCwd: string, gitSpawnFn: Function, useEvidence: boolean }} args
  * @returns {{ headSha: string|null, inputFingerprint: string|null }}
  */
@@ -118,34 +76,21 @@ function resolveEvidenceKeys({ spawnCwd, gitSpawnFn, useEvidence }) {
 }
 
 /**
- * Runner-shaped entry-point: takes the parsed wrapper args + runner args and
- * executes the gate. Pure-ish (modulo IO) — all side-effects are routed via
- * the injection hooks so tests can stub `gitSpawn`, `spawnSync`, and the
- * evidence store without touching disk or spawning processes.
- *
- * Exported for tests + the CLI `main()`.
- *
  * @param {object} params
- * @param {number}   params.scopeId      — Story ID (positive integer).
- * @param {boolean}  [params.standalone] — Required. Routes to the
- *   storyId-anchored standalone keyspace (Story #4250).
- * @param {string}   params.gate         — Logical gate name (`lint`, `typecheck`, …).
- * @param {boolean}  params.useEvidence  — When false, force the runner.
- * @param {string}   params.cwd          — Evidence cwd (locates the temp
- *   tree). The runner is spawned in `worktreePath` when set, else `cwd`.
- * @param {string|null} [params.worktreePath] — Spawn cwd override (Story #1120).
- *   When set, the runner runs in the Story worktree and the HEAD-SHA used as
- *   the evidence cache key is read from the worktree, not from `cwd`.
- * @param {string[]} params.runnerArgs   — `[cmd, ...args]` from after `--`.
- * @param {object}   [deps]              — Optional injection hooks (tests).
- * @param {Function} [deps.gitSpawnFn]   — Stub for `gitSpawn`.
- * @param {Function} [deps.spawnFn]      — Stub for `spawnSync`.
- * @param {Function} [deps.shouldSkipFn] — Stub for `shouldSkip`.
- * @param {Function} [deps.recordPassFn] — Stub for `recordPass`.
- * @param {object}   [deps.logger]       — Logger-shaped object (info/error/warn/fatal).
- * @returns {{ status: number, skipped: boolean }} Outcome summary. `status`
- *   is the runner's exit code (0 = pass), `skipped` is true when evidence
- *   short-circuited the runner.
+ * @param {number}   params.scopeId
+ * @param {boolean}  [params.standalone]
+ * @param {string}   params.gate
+ * @param {boolean}  params.useEvidence
+ * @param {string}   params.cwd          — evidence cwd (locates the temp tree)
+ * @param {string|null} [params.worktreePath] — spawn cwd and HEAD source
+ * @param {string[]} params.runnerArgs
+ * @param {object}   [deps]
+ * @param {Function} [deps.gitSpawnFn]
+ * @param {Function} [deps.spawnFn]
+ * @param {Function} [deps.shouldSkipFn]
+ * @param {Function} [deps.recordPassFn]
+ * @param {object}   [deps.logger]
+ * @returns {{ status: number, skipped: boolean }}
  */
 export async function runEvidenceGate(params, deps = {}) {
   const {
@@ -165,9 +110,6 @@ export async function runEvidenceGate(params, deps = {}) {
     runnerArgs,
   } = params ?? {};
 
-  // `--standalone` (Story #4250) routes the evidence file to the
-  // storyId-anchored keyspace so the acceptance-self-eval critic can record
-  // verify[] evidence into the same keyspace the standalone close consults.
   if (
     !scopeId ||
     !standalone ||
@@ -180,14 +122,10 @@ export async function runEvidenceGate(params, deps = {}) {
     );
     return { status: 1, skipped: false };
   }
-  // Evidence-store opts shared by shouldSkip + recordPass below.
   const evidenceStoreOpts = { cwd, standalone };
 
-  // Spawn cwd is the worktree when supplied — every gate command sees the
-  // Story branch's tree, not the main checkout. Evidence cwd stays anchored
-  // to the main checkout so the temp tree resolves under the main
-  // `.git/`. The HEAD-SHA used as the cache key is read from the spawn cwd
-  // (the worktree), so cache entries key against the Story branch's HEAD.
+  // The gate runs in the worktree; evidence stays anchored to the main
+  // checkout so the temp tree resolves under the main `.git/`.
   const spawnCwd = worktreePath ?? cwd;
   const [cmd, ...cmdArgs] = runnerArgs;
   const configHash = hashCommandConfig({ cmd, args: cmdArgs, cwd: spawnCwd });

package/.agents/scripts/file-ci-gap.js

@@ -1,18 +1,9 @@
 #!/usr/bin/env node
 /**
- * file-ci-gap.js — the CI-remediation Option-2 filing command.
- *
- * `rules/ci-remediation.md` sends three verdicts here — `pre-existing`,
- * `capacity`, `unreproducible-tier` — each meaning "this red check is real,
- * and fixing it is not this delivery's job". The rule used to say "file a
- * `meta::framework-gap` issue" and stop, leaving the agent to hand-run
- * `gh issue create` wherever it was standing. This is the mechanism behind
- * that sentence: evidence from the CI digest, ownership routing, fingerprint
- * dedup, the `friction` comment, and the `agent::blocked` flip in one call.
- *
- * It files an **intake** issue, never a Story: `/mandrel-plan <id>` graduates
- * it on the next planning pass. Delivery never blocks on planning — see
- * `lib/orchestration/ci-gap-intake.js` for why that split is load-bearing.
+ * CI-remediation Option-2 filing: for a red check that is real but not this
+ * delivery's to fix, files (or updates, by fingerprint) an intake issue in
+ * the owning repo, comments `friction` on the Story, and optionally blocks it.
+ * It files intake, never a Story, so delivery never blocks on planning.
  */
 
 import { parseArgs } from 'node:util';
@@ -84,15 +75,9 @@ const USAGE = {
 };
 
 /**
- * Wire the live GitHub ports the intake filer writes through.
- *
- * `gh` is the transport rather than the provider facade because a filing can
- * target a repository other than the configured one, and `gh issue create
- * --repo` is the surface that already does that (the graduators file
- * cross-repo the same way).
- *
+ * `gh` rather than the provider facade: a filing may target another repo.
  * @param {object} opts
- * @returns {object} ports for `fileCiGapIntake`
+ * @returns {object}
  */
 function liveIntakePorts({ provider, searchRepo, cwd, logger }) {
   const labelCache = new Map();
@@ -104,9 +89,7 @@ function liveIntakePorts({ provider, searchRepo, cwd, logger }) {
         repo: searchRepo.repo,
       }),
     createIssue: async ({ owner, repo, title, body, labels }) => {
-      // `gh issue create --label <absent>` fails outright, so a brand-new
-      // routing label (meta::platform-gap, friction::unreproducible-tier)
-      // has to exist before the create — not after it errors.
+      // `gh issue create` fails outright on an absent label; ensure first.
       const ensured = await ensureIssueLabels({
         owner,
         repo,
@@ -136,9 +119,6 @@ function liveIntakePorts({ provider, searchRepo, cwd, logger }) {
 }
 
 /**
- * Render the `friction` comment the Story carries so the blocker is legible
- * on the ticket itself, not only in the intake issue.
- *
  * @param {object} opts
  * @returns {string}
  */
@@ -171,16 +151,10 @@ export function renderFrictionComment({
   return lines.join('\n');
 }
 
-/** The graduation instruction every filing carries, verdict-independent. */
 const GRADUATE_LINE =
   'Graduate the intake issue with `/mandrel-plan <issue number>` to turn it into a Story.';
 
 /**
- * What this filing says about rerunning the failed job (Story #5343). An
- * allowance is stated with its head SHA and its one-shot bound, because the
- * comment is where an operator reads whether the rerun they are about to do
- * is the sanctioned one.
- *
  * @param {{ headSha: string } | null} rerunAllowance
  * @returns {string}
  */
@@ -193,14 +167,8 @@ function renderRerunLine(rerunAllowance) {
 }
 
 /**
- * File the CI-gap intake issue for one Story, post the `friction` comment,
- * and optionally flip the Story to `agent::blocked`.
- *
- * Every port is injectable so the unit tests exercise the whole command with
- * no network and no live tracker.
- *
  * @param {object} opts
- * @returns {Promise<object>} the intake result, plus what the command did.
+ * @returns {Promise<object>}
  */
 export async function runFileCiGap({
   storyId,
@@ -224,9 +192,7 @@ export async function runFileCiGap({
     throw new Error('--story <id> is required (a positive issue number).');
   }
   const resolved = config ?? resolveConfig();
-  // The digest's temp root, resolved exactly as `pr-watch-with-update.js`
-  // resolves it when it WRITES the digest — the CLI never passed one, so the
-  // default read crashed on `undefined` before it could find the file.
+  // Must resolve exactly as `pr-watch-with-update.js` does when writing it.
   const digestRoot = tempRoot ?? resolved?.project?.paths?.tempRoot ?? 'temp';
   const ciDigest =
     digest ?? readCiDigest({ storyId: sid, tempRoot: digestRoot, cwd });
@@ -268,9 +234,7 @@ export async function runFileCiGap({
     now,
   });
 
-  // Story #5343 — a proven-environmental verdict earns the one same-SHA
-  // rerun the watcher's guard will admit. Recorded on the digest, keyed to
-  // the head SHA the red was observed on, and never on a dry run.
+  // A proven-environmental verdict earns one same-SHA rerun; never on dry run.
   const rerunAllowance = dryRun
     ? null
     : recordRerunAllowance({
@@ -310,8 +274,6 @@ export async function runFileCiGap({
 }
 
 /**
- * CLI entrypoint.
- *
  * @returns {Promise<void>}
  */
 async function main() {
@@ -338,8 +300,6 @@ async function main() {
     block: values.block,
   });
 
-  // Single-line JSON per the script-output contract — an orchestrator parses
-  // this, and a pretty dump is noise in a delivery transcript.
   process.stdout.write(`${JSON.stringify(result)}\n`);
   for (const err of result.errors) {
     Logger.error(`[file-ci-gap] ${err}`);

package/.agents/scripts/generate-config-docs.js

@@ -1,58 +1,10 @@
 #!/usr/bin/env node
 /**
- * .agents/scripts/generate-config-docs.js — the `.agentrc` config surface
- * generator (Story #5007).
- *
- * **One annotated source, three generated artifacts.** The runtime AJV schema
- * (`AGENTRC_SCHEMA`, composed from `lib/config-settings-schema*.js` and
- * `lib/config/gates/*`) is the single hand-authored enumeration of the
- * `.agentrc.json` surface. `description` and `default` annotations live on
- * those literals — AJV ignores both — and this generator emits everything
- * downstream of them:
- *
- *   1. `.agents/schemas/agentrc.schema.json` — the JSON-Schema mirror every
- *      consumer `.agentrc.json` points `$schema` at. Serialized 2020-12,
- *      fully inlined (no `$defs`): it IS the runtime schema, so the class of
- *      bug where a key exists in the mirror but not in the runtime AJV — and
- *      a consumer's whole config is therefore dead on arrival (Epic #4131) —
- *      cannot be expressed any more.
- *   2. `.agents/docs/agentrc-reference.json` — the defaults inventory
- *      `lib/config/defaults.js` reads for `mandrel explain` and the
- *      sync-agentrc redundancy advisory. Built from the `default`
- *      annotations: a node carrying one contributes its value verbatim and is
- *      not descended into; a node carrying none contributes nothing.
- *   3. The bounded key-table region inside `.agents/docs/configuration.md`,
- *      delimited by:
- *
- *          <!-- BEGIN GENERATED:agentrc -->
- *          ...generated tables...
- *          <!-- END GENERATED:agentrc -->
- *
- *      One Markdown section per top-level schema key, each table columned
- *      `| Key | Required | Type | Default | Description |`, with nested
- *      properties flattened into dot-paths (`paths.agentRoot`,
- *      `branchProtection.requiredChecks[]`).
- *
- * Until this Story the first two were hand-maintained alongside the runtime
- * schema and reconciled by two parity suites; those suites are now
- * generator-fidelity checks.
- *
- * Modes:
- *   (default)  — rewrite any artifact whose content is stale.
- *   --check    — exit 0 when all three are current, exit 1 naming the stale
- *                ones. Wired into `npm run docs:check`, hence `npm run lint`.
- *
- * **Whitespace is not content.** The two JSON artifacts are re-formatted by
- * Biome via lint-staged after they are written, so comparing raw bytes would
- * make the check fail on formatting alone. Both comparison and write go
- * through {@link canonicalJson}: parse, re-serialize, compare. That is
- * insensitive to whitespace and *sensitive* to key order, which is what
- * actually matters — key order drives the doc-table order and the ordering a
- * consumer's editor offers completions in.
- *
- * Per `.agents/rules/orchestration-error-handling.md`, unrecoverable
- * failures surface via `throw new Error(...)` so `runAsCli` can map the
- * throw to `process.exit(1)` deterministically (no `Logger.fatal`).
+ * Generates the `.agentrc` config surface from the annotated runtime AJV
+ * schema (the single source): the JSON-Schema mirror (fully inlined, so it
+ * cannot disagree with runtime), the defaults inventory, and the key-table
+ * region of `configuration.md`. JSON artifacts compare canonically — Biome
+ * reformats them after write, so whitespace is ignored but key order counts.
  */
 
 import fs from 'node:fs';
@@ -82,7 +34,6 @@ const DOC_PATH = path.join(PROJECT_ROOT, '.agents', 'docs', 'configuration.md');
 const REGION_BEGIN = '<!-- BEGIN GENERATED:agentrc -->';
 const REGION_END = '<!-- END GENERATED:agentrc -->';
 
-/** Envelope keys prepended to the serialized runtime schema. */
 const MIRROR_ENVELOPE = {
   $schema: 'https://json-schema.org/draft/2020-12/schema',
   $id: 'https://github.com/dsj1984/mandrel/blob/main/.agents/schemas/agentrc.schema.json',
@@ -91,16 +42,12 @@ const MIRROR_ENVELOPE = {
     'GENERATED — do not edit. Emitted by `node .agents/scripts/generate-config-docs.js` from the runtime AJV schema in `.agents/scripts/lib/config-settings-schema.js` (plus its `-delivery` / `-quality` / `config/gates/*` modules), which is the single source of truth for the `.agentrc.json` surface. This file exists for editor tooling and human readers; because it is a serialization of the runtime schema rather than a hand-kept mirror, the two cannot disagree. Edit the annotated schema literals and re-run `npm run docs:gen`.',
 };
 
-/** `$schema` pointer written into the generated defaults inventory. */
 const REFERENCE_SCHEMA_POINTER = '../schemas/agentrc.schema.json';
 
-// Order matters — drives the per-section emission sequence.
+// Order drives section emission.
 const TOP_LEVEL_KEYS = ['project', 'github', 'planning', 'delivery', 'qa'];
 
 /**
- * Canonical JSON text for comparison and for writing. Key order is preserved
- * (and therefore compared); whitespace is normalized away.
- *
  * @param {unknown} value
  * @returns {string}
  */
@@ -109,10 +56,7 @@ function canonicalJson(value) {
 }
 
 /**
- * Read a JSON artifact and return its canonical text, or `null` when the file
- * is absent (first generation) or unparseable (a hand-mangled artifact is
- * treated as stale, not as a crash).
- *
+ * `null` when absent or unparseable — a mangled artifact is stale, not a crash.
  * @param {string} file
  * @returns {string | null}
  */
@@ -126,16 +70,7 @@ function readCanonicalJson(file) {
 }
 
 /**
- * Build the shipped JSON-Schema mirror: the 2020-12 envelope followed by the
- * runtime schema verbatim.
- *
- * The runtime schema is a plain, cycle-free object literal (no RegExp or
- * function values), so `structuredClone` is a faithful serialization. Shared
- * sub-schema objects — `TOLERANCE_SCHEMA` and friends, referenced by several
- * gates — are inlined at each use rather than hoisted into `$defs`. The
- * inlined document is smaller than the hand-maintained `$defs` mirror it
- * replaces, and it removes the naming heuristic a hoisting pass would need.
- *
+ * Shared sub-schemas are inlined at each use rather than hoisted to `$defs`.
  * @param {object} schema
  * @returns {object}
  */
@@ -144,17 +79,10 @@ function buildMirrorSchema(schema) {
 }
 
 /**
- * Collect the `default` annotations under `node` into a nested plain object.
- *
- * A node carrying `default` contributes that value verbatim and is NOT
- * descended into — that is what lets an object-shaped or array-shaped default
- * (`github.branchProtection.requiredChecks`, `qa.environments`) be declared in
- * one place. A properties-bearing node with no `default` contributes an object
- * built from whichever children contributed something, or nothing at all when
- * none did.
- *
+ * A node carrying `default` contributes it verbatim and is not descended
+ * into, so an object- or array-shaped default is declared in one place.
  * @param {object} node
- * @returns {unknown} The built value, or `undefined` for "contributes nothing".
+ * @returns {unknown} `undefined` when nothing is contributed.
  */
 function collectDefaults(node) {
   if (!node || typeof node !== 'object') return undefined;
@@ -169,8 +97,6 @@ function collectDefaults(node) {
 }
 
 /**
- * Build the defaults inventory shipped as `.agents/docs/agentrc-reference.json`.
- *
  * @param {object} schema
  * @returns {object}
  */
@@ -182,11 +108,9 @@ function buildReferenceInventory(schema) {
 }
 
 /**
- * Collapse an `allOf` envelope down onto its base node. The schema uses
- * `allOf` only to hang a conditional (`if`/`then`) constraint off a block, so
- * the merged view carries the base type for documentation purposes.
- *
- * @param {object} node The schema node to flatten.
+ * `allOf` only hangs `if`/`then` constraints off a block, so the base type is
+ * what the docs need.
+ * @param {object} node
  * @returns {object}
  */
 function flattenAllOf(node) {
@@ -203,11 +127,7 @@ function flattenAllOf(node) {
 }
 
 /**
- * Render the "Type" cell for an `array`-typed node by inspecting its `items`
- * schema: an enum item renders `array<enum>`, a typed item renders
- * `array<type>`, and anything else collapses to a bare `array`.
- *
- * @param {object} flat Flattened array node.
+ * @param {object} flat
  * @returns {string}
  */
 function renderArrayType(flat) {
@@ -224,11 +144,7 @@ function renderArrayType(flat) {
 }
 
 /**
- * Render the "Type" cell for an `object`-typed node — `object<map>` when it
- * carries an `additionalProperties` schema (the map form), `object`
- * otherwise.
- *
- * @param {object} flat Flattened object node.
+ * @param {object} flat
  * @returns {string}
  */
 function renderObjectType(flat) {
@@ -242,20 +158,12 @@ function renderObjectType(flat) {
 }
 
 /**
- * Ordered dispatch table for the "Type" cell. Each rule pairs a `when(flat)`
- * predicate with a `render(flat)` producer; {@link renderType} walks the
- * table once and returns the first match, so a new schema shape becomes a new
- * row here rather than another nested branch.
- *
- * Order is load-bearing — `oneOf` and `enum` are matched before the plain
- * `type` rules.
- *
+ * First match wins; `oneOf` and `enum` must precede the plain `type` rules.
  * @type {Array<{ when: (flat: object) => boolean, render: (flat: object) => string }>}
  */
 const TYPE_RULES = [
   {
-    // The list-or-extender union: a plain `string[]` (replace) or an
-    // `{ append?, prepend? }` object that deep-merges with the framework list.
+    // List-or-extender union: replace, or deep-merge with the framework list.
     when: (flat) =>
       Array.isArray(flat.oneOf) &&
       flat.oneOf.some((m) => m?.properties?.append || m?.properties?.prepend),
@@ -290,10 +198,7 @@ const TYPE_RULES = [
 ];
 
 /**
- * Render the "Type" cell for a schema node. Anything the table does not match
- * falls through to a `?` so missing coverage is visible rather than silently
- * wrong.
- *
+ * An unmatched shape renders `?` so the gap is visible.
  * @param {object} node
  * @returns {string}
  */
@@ -305,10 +210,6 @@ function renderType(node) {
 }
 
 /**
- * Render the "Default" cell. Nodes without an explicit `default` annotation
- * get an em dash — see the annotation contract in `config-settings-schema.js`
- * for why a key can have a runtime default and no annotation.
- *
  * @param {object} node
  * @returns {string}
  */
@@ -328,8 +229,6 @@ function renderDefault(node) {
 }
 
 /**
- * Escape pipe characters so they survive Markdown table cell parsing.
- *
  * @param {string} text
  * @returns {string}
  */
@@ -338,11 +237,7 @@ function escapeCell(text) {
 }
 
 /**
- * Emit the rows for a nested-object property: a header row carrying the
- * parent's description followed by the recursively-flattened child rows.
- * Returns `null` when `flat` is not a properties-bearing object, so the
- * caller can fall through to the next row shape.
- *
+ * `null` when not a properties-bearing object, so the next builder runs.
  * @param {{flat: object, keyPath: string, pathParts: string[], propName: string, isRequired: boolean, description: string}} ctx
  * @returns {Array<object> | null}
  */
@@ -365,10 +260,7 @@ function nestedObjectRows(ctx) {
 }
 
 /**
- * Emit the single `[]`-suffixed row for an array-of-objects property,
- * describing the item shape in the Description cell. Returns `null` when the
- * property is not an array whose items are a properties-bearing object.
- *
+ * One `[]`-suffixed row per array of objects, item keys in the Description.
  * @param {{flat: object, keyPath: string, isRequired: boolean, description: string}} ctx
  * @returns {Array<object> | null}
  */
@@ -393,10 +285,6 @@ function arrayOfObjectsRows(ctx) {
 }
 
 /**
- * Emit the leaf (scalar / non-recursed) row for a property. Always matches —
- * it is the fallthrough shape when neither the nested-object nor the
- * array-of-objects builder applied.
- *
  * @param {{flat: object, keyPath: string, isRequired: boolean, description: string}} ctx
  * @returns {Array<object>}
  */
@@ -413,24 +301,13 @@ function leafRow(ctx) {
   ];
 }
 
-// Ordered row-shape builders for one property. The loop in flattenObject
-// returns the first builder that yields rows (non-null): nested-object first,
-// array-of-objects next, scalar leaf as the always-matching fallthrough.
+// First builder returning non-null wins; leafRow always matches.
 const ROW_BUILDERS = [nestedObjectRows, arrayOfObjectsRows, leafRow];
 
 /**
- * Flatten one object-typed schema node into table rows. Recurses into nested
- * `object` properties so dot-paths like `paths.agentRoot` and
- * `branchProtection.requiredChecks` show up as individual rows.
- *
- * Arrays of objects (`requiredChecks[]`, `routes[]`, `bundles[]`) are emitted
- * as a single row whose Key column carries a `[]` suffix; the item shape is
- * captured in the Description cell. This keeps the output legible without
- * exploding into per-item-property rows.
- *
- * @param {object} node       Schema node to flatten.
- * @param {string[]} pathParts Dot-path accumulator.
- * @param {Set<string>} required Required-property names on the parent.
+ * @param {object} node
+ * @param {string[]} pathParts
+ * @param {Set<string>} required
  * @returns {Array<{key:string, required:string, type:string, def:string, description:string}>}
  */
 function flattenObject(node, pathParts, required) {
@@ -463,8 +340,6 @@ function flattenObject(node, pathParts, required) {
 }
 
 /**
- * Render the Markdown body for one top-level section.
- *
  * @param {object} schema
  * @param {string} topKey
  * @returns {string}
@@ -508,8 +383,6 @@ function renderSection(schema, topKey) {
 }
 
 /**
- * Render the full bounded-region body (excluding the markers themselves).
- *
  * @param {object} schema
  * @returns {string}
  */
@@ -533,14 +406,10 @@ function renderRegion(schema) {
 }
 
 /**
- * Substitute the bounded region inside `original`. If the markers are
- * absent, inject them just after the "## Top-level shape" section's
- * trailing horizontal rule (the first `---` after that heading) so the
- * generated reference lands before the hand-authored per-section docs.
- * If no anchor is found, prepend the markers above the first `## ` heading.
- *
+ * Absent markers are inserted after the "## Top-level shape" block's `---`,
+ * else above the first `## ` heading, else appended.
  * @param {string} original
- * @param {string} body Region body including leading/trailing blank lines.
+ * @param {string} body
  * @returns {string}
  */
 function spliceRegion(original, body) {
@@ -564,11 +433,9 @@ function spliceRegion(original, body) {
     );
   }
 
-  // Markers absent — insert them after the "## Top-level shape" block.
   const anchor = '## Top-level shape';
   const anchorIdx = original.indexOf(anchor);
   if (anchorIdx !== -1) {
-    // Find the next `---` separator after the anchor.
     const ruleIdx = original.indexOf('\n---\n', anchorIdx);
     if (ruleIdx !== -1) {
       const insertAt = ruleIdx + '\n---\n'.length;
@@ -579,7 +446,6 @@ function spliceRegion(original, body) {
     }
   }
 
-  // Fallback: insert above the first `## ` heading.
   const headingMatch = original.match(/^## /m);
   if (headingMatch && headingMatch.index !== undefined) {
     const before = original.slice(0, headingMatch.index);
@@ -588,18 +454,12 @@ function spliceRegion(original, body) {
     return `${before}${block}${after}`;
   }
 
-  // Last-ditch: append.
   return `${original}\n${REGION_BEGIN}\n${body}\n${REGION_END}\n`;
 }
 
 /**
- * Build every generated artifact from `schema` and pair each with what is on
- * disk today.
- *
- * The JSON artifacts compare canonically (see the module header); the
- * Markdown artifact compares raw, because its region is spliced into
- * hand-authored prose that must survive byte-for-byte.
- *
+ * The Markdown artifact compares raw: its hand-authored prose must survive
+ * byte-for-byte.
  * @param {{ schema?: object, schemaPath?: string, referencePath?: string,
  *   docPath?: string }} [opts]
  * @returns {Array<{ name: string, file: string, generated: string,