mandrel 2.31.0 → 2.33.0

package/.agents/scripts/lib/baselines/scope-inventory.js

@@ -0,0 +1,314 @@
+// .agents/scripts/lib/baselines/scope-inventory.js
+//
+// Story #5012 — the ONE in-scope file inventory the honesty surface reads.
+//
+// A ratchet gate can be green while measuring almost nothing: nothing checks
+// that a committed baseline's row set still describes the tree it claims to
+// describe. Both instruments that now do — `check-baseline-scope.js` (assert)
+// and `prune-baseline-orphans.js` (remedy) — resolve "which files is this kind
+// supposed to have rows for?" through this module, so the gate and the pruner
+// cannot disagree about scope and start fighting each other.
+//
+// ## Recompute from the gate's own config, never from a second walker
+//
+// The inventory is derived from **the same configuration the kind's refresh
+// scorer reads**, through the same helpers:
+//
+//   - `coverage` — `.c8rc.cjs` `include` / `exclude`, applied with
+//     `coverage-baseline.js#buildScopePredicate`, exactly as
+//     `refresh-service.js#buildDefaultCoverageScorer` does.
+//   - every other file-keyed kind — `delivery.quality.gates.<kind>.targetDirs`
+//     / `.ignoreGlobs`, walked with `maintainability-utils.js#scanDirectory`,
+//     exactly as `refresh-service.js#buildDefaultMaintainabilityScorer` does.
+//
+// A second walker written here would report the two implementations
+// disagreeing as divergence — the same failure mode
+// `check-baseline-drift.js` avoids by re-scoring through
+// `resolveDefaultScorer` rather than a private scorer.
+//
+// ## Measurement-free by contract
+//
+// Nothing in this module runs a scorer, reads `coverage/coverage-final.json`,
+// or needs a test run to have happened. It walks directories and matches
+// globs. That is what makes the gate runnable on any checkout, which is in
+// turn what makes hard-failing on a stale row defensible.
+
+import { createRequire } from 'node:module';
+import path from 'node:path';
+
+import { buildScopePredicate } from '../coverage-baseline.js';
+import { scanDirectory } from '../maintainability-utils.js';
+
+/**
+ * Per-kind classification of which divergence directions may be asserted.
+ *
+ * **Only a kind whose producer emits one row per in-scope file may assert the
+ * MISSING direction.** This is not a conservatism knob — it is arithmetic.
+ * Measured against this repository on 2026-08-05, asserting MISSING densely
+ * yields 128 phantom rows for `crap` (rows are per-method and coverage-gated,
+ * so a file with no scorable method legitimately has none) and 510 for
+ * `duplication` (a row exists only where a clone was found). A gate that
+ * reports 638 phantom findings on a healthy tree is a gate nobody reads.
+ *
+ * `lint` and `mutation` are sparse for the same reason — a clean file has no
+ * lint row, an untested file has no mutation row. `lighthouse` (keyed on
+ * `route`) and `bundle-size` (keyed on `bundle`) are not file-keyed at all, so
+ * neither direction is meaningful: their keys name artefacts, not paths on
+ * disk, and a directory walk can say nothing about them.
+ *
+ * @type {Readonly<Record<string, { keyField: string, directions: readonly string[] }>>}
+ */
+export const KIND_SCOPE_POLICY = Object.freeze({
+  coverage: Object.freeze({
+    keyField: 'path',
+    directions: Object.freeze(['missing', 'extra']),
+  }),
+  maintainability: Object.freeze({
+    keyField: 'path',
+    directions: Object.freeze(['missing', 'extra']),
+  }),
+  crap: Object.freeze({
+    keyField: 'path',
+    directions: Object.freeze(['extra']),
+  }),
+  duplication: Object.freeze({
+    keyField: 'path',
+    directions: Object.freeze(['extra']),
+  }),
+  lint: Object.freeze({
+    keyField: 'path',
+    directions: Object.freeze(['extra']),
+  }),
+  mutation: Object.freeze({
+    keyField: 'path',
+    directions: Object.freeze(['extra']),
+  }),
+  lighthouse: Object.freeze({
+    keyField: 'route',
+    directions: Object.freeze([]),
+  }),
+  'bundle-size': Object.freeze({
+    keyField: 'bundle',
+    directions: Object.freeze([]),
+  }),
+});
+
+/** Every kind the honesty surface knows about, in report order. */
+export const SCOPE_KINDS = Object.freeze(Object.keys(KIND_SCOPE_POLICY));
+
+/**
+ * The directions `kind` may assert. Unknown kinds assert nothing — a kind this
+ * module has never heard of has no scope model, and inventing one would be the
+ * phantom-row failure above with extra steps.
+ *
+ * @param {string} kind
+ * @returns {readonly string[]}
+ */
+export function directionsFor(kind) {
+  return KIND_SCOPE_POLICY[kind]?.directions ?? [];
+}
+
+/**
+ * The row field `kind` keys on — `path` for the file-keyed kinds, `route` for
+ * lighthouse, `bundle` for bundle-size. Mirrors `kinds/<kind>.js#keyField`;
+ * kept here so a caller can classify without importing the kernel.
+ *
+ * @param {string} kind
+ * @returns {string}
+ */
+export function keyFieldFor(kind) {
+  return KIND_SCOPE_POLICY[kind]?.keyField ?? 'path';
+}
+
+/**
+ * True when `kind` keys its rows on a repo-relative file path, so a directory
+ * walk can be compared against its row set at all.
+ *
+ * @param {string} kind
+ * @returns {boolean}
+ */
+export function isFileKeyed(kind) {
+  return keyFieldFor(kind) === 'path' && Object.hasOwn(KIND_SCOPE_POLICY, kind);
+}
+
+/** Glob metacharacters that end a pattern's literal prefix. */
+const GLOB_META = /[*?[\]{}!+@()]/;
+
+/**
+ * Derive directory roots to walk from a list of include globs, by taking each
+ * pattern's literal leading path segments.
+ *
+ * The coverage gate's schema is closed and declares no `targetDirs` — its
+ * scope lives entirely in `.c8rc.cjs`. Without this derivation the coverage
+ * walk has no root to start from, so there is nothing to compare the row set
+ * against and the whole MISSING direction goes silently inert for the one kind
+ * whose producer is densest.
+ *
+ * `'.agents/scripts/**'` yields `.agents/scripts`; a pattern that is glob from
+ * its first segment (`'**​/*.js'`) yields `.`, the repo root.
+ *
+ * @param {string[]} globs
+ * @returns {string[]} De-duplicated roots, repo-relative POSIX.
+ */
+export function deriveWalkRoots(globs) {
+  const roots = new Set();
+  for (const glob of Array.isArray(globs) ? globs : []) {
+    if (typeof glob !== 'string' || glob.length === 0) continue;
+    const literal = [];
+    for (const segment of glob.split('/')) {
+      if (GLOB_META.test(segment)) break;
+      literal.push(segment);
+    }
+    roots.add(literal.join('/') || '.');
+  }
+  return [...roots];
+}
+
+/**
+ * Walk `roots` under `cwd` and return canonical repo-relative POSIX paths.
+ *
+ * Delegates to `scanDirectory`, which already owns the supported-extension set
+ * and the ignored-directory set (`node_modules`, `.git`, `temp`, `.worktrees`,
+ * …) that every scorer walks with. Passing `ignoreGlobs` straight through
+ * means an ignored file is dropped by the identical matcher the scorer uses.
+ *
+ * @param {{ cwd: string, roots: string[], ignoreGlobs?: string[] }} params
+ * @returns {string[]}
+ */
+function walkRoots({ cwd, roots, ignoreGlobs = [] }) {
+  const absolute = [];
+  for (const root of roots) {
+    const abs = path.isAbsolute(root) ? root : path.resolve(cwd, root);
+    scanDirectory(abs, absolute, { cwd, ignoreGlobs });
+  }
+  return absolute.map((abs) =>
+    path.relative(cwd, abs).split(path.sep).join('/'),
+  );
+}
+
+/**
+ * Build the coverage inventory from `.c8rc.cjs`.
+ *
+ * Roots come from the literal prefixes of `include`; the walked set is then
+ * filtered through the same `buildScopePredicate` the coverage scorer applies,
+ * so `exclude` is honoured by one implementation rather than two.
+ *
+ * @param {{ cwd: string, requireFn?: (id: string) => object }} params
+ * @returns {{ files: string[] | null, roots: string[], degraded: boolean, reason: string | null }}
+ */
+function coverageInventory({ cwd, requireFn }) {
+  const load = requireFn ?? createRequire(path.join(cwd, 'noop.cjs'));
+  let config;
+  try {
+    config = load(path.resolve(cwd, '.c8rc.cjs'));
+  } catch (err) {
+    return {
+      files: null,
+      roots: [],
+      degraded: true,
+      reason: `.c8rc.cjs unreadable: ${err?.message ?? err}`,
+    };
+  }
+  const include = Array.isArray(config?.include) ? config.include : [];
+  const exclude = Array.isArray(config?.exclude) ? config.exclude : [];
+  if (include.length === 0) {
+    return {
+      files: null,
+      roots: [],
+      degraded: true,
+      reason: '.c8rc.cjs declares no include globs',
+    };
+  }
+  const roots = deriveWalkRoots(include);
+  const inScope = buildScopePredicate({ include, exclude });
+  return {
+    files: walkRoots({ cwd, roots }).filter(inScope),
+    roots,
+    degraded: false,
+    reason: null,
+  };
+}
+
+/**
+ * Build the inventory for a `targetDirs`-configured kind (everything except
+ * coverage). Reads the gate's own `targetDirs` / `ignoreGlobs` off the
+ * normalized quality block — the same two keys its refresh scorer reads.
+ *
+ * @param {{ kind: string, cwd: string, gate: object }} params
+ * @returns {{ files: string[] | null, roots: string[], degraded: boolean, reason: string | null }}
+ */
+function targetDirsInventory({ kind, cwd, gate }) {
+  const roots = Array.isArray(gate?.targetDirs) ? gate.targetDirs : [];
+  const ignoreGlobs = Array.isArray(gate?.ignoreGlobs) ? gate.ignoreGlobs : [];
+  if (roots.length === 0) {
+    return {
+      files: null,
+      roots: [],
+      degraded: true,
+      reason: `delivery.quality.gates.${kind}.targetDirs is empty or unset`,
+    };
+  }
+  return {
+    files: walkRoots({ cwd, roots, ignoreGlobs }),
+    roots,
+    degraded: false,
+    reason: null,
+  };
+}
+
+/**
+ * Resolve the set of files `kind` is configured to have rows for.
+ *
+ * Never throws: an unreadable or absent scope config degrades to
+ * `{ files: null, degraded: true, reason }`. Callers treat a degraded
+ * inventory as "scope unknown" — the gate reports it and skips that kind's
+ * scope directions, the pruner falls back to orphan-only pruning. Neither may
+ * infer emptiness from it: a `files: []` inventory would make every committed
+ * row look out-of-scope and hand the pruner a licence to delete the baseline.
+ *
+ * @param {{
+ *   kind: string,
+ *   cwd?: string,
+ *   quality?: object,
+ *   requireFn?: (id: string) => object,
+ * }} params
+ * @returns {{
+ *   kind: string,
+ *   keyField: string,
+ *   directions: readonly string[],
+ *   files: string[] | null,
+ *   roots: string[],
+ *   degraded: boolean,
+ *   reason: string | null,
+ * }}
+ */
+export function buildScopeInventory({
+  kind,
+  cwd = process.cwd(),
+  quality,
+  requireFn,
+} = {}) {
+  const base = {
+    kind,
+    keyField: keyFieldFor(kind),
+    directions: directionsFor(kind),
+  };
+  if (!isFileKeyed(kind)) {
+    return {
+      ...base,
+      files: null,
+      roots: [],
+      degraded: false,
+      reason: `${kind} is not file-keyed (rows key on "${base.keyField}")`,
+    };
+  }
+  const resolved =
+    kind === 'coverage'
+      ? coverageInventory({ cwd, requireFn })
+      : targetDirsInventory({
+          kind,
+          cwd,
+          gate: quality?.gates?.[kind] ?? {},
+        });
+  return { ...base, ...resolved };
+}

package/.agents/scripts/lib/bdd-step-index.js

@@ -0,0 +1,326 @@
+/**
+ * bdd-step-index.js — scoped discovery and matching for BDD step definitions.
+ *
+ * `check-gherkin-corpus.js` answers one question per Gherkin step: does a step
+ * definition **under this step's own scope** claim it? That question has two
+ * halves, and this module owns both so the corpus gate never re-implements
+ * either inline:
+ *
+ *   1. **Discovery** — which files under a scope's `stepRoots` hold step
+ *      definitions, and which `.feature` files sit under its `featureRoots`.
+ *      Feature discovery is delegated to `listFeatureFiles` in
+ *      `bdd-scenario-scanner.js` rather than copied: /plan's scenario index and
+ *      this gate must agree on what counts as a feature file, and two walkers
+ *      would eventually disagree.
+ *   2. **Matching** — turn each definition's Cucumber expression or regular
+ *      expression into one `RegExp`, and test a step's text against the index.
+ *
+ * ## Heuristic index, exact parser
+ *
+ * The parser half of the gate is exact: `@cucumber/gherkin` decides what
+ * compiles. This half is deliberately **not**. Reading step definitions
+ * without executing them means a regex scan over source text, and a scan
+ * cannot see a definition assembled at runtime, registered through a wrapper,
+ * or parameterised by a custom `defineParameterType`. That asymmetry is why
+ * the gate ships a step-waiver list: a false "unbound" must always have an
+ * escape that does not require switching the whole gate off.
+ *
+ * Supported Cucumber-expression constructs are the ones the built-in parameter
+ * types and the optional/alternation syntax cover — `{int}`, `{float}`,
+ * `{word}`, `{string}`, an anonymous `{}`, `text(s)` optionals, and `a/an`
+ * word alternation. An unrecognised `{custom}` degrades to `(.*)` rather than
+ * failing to match, because over-matching produces a missed finding while
+ * under-matching produces a false one, and a false one blocks a delivery.
+ *
+ * Nothing here reads configuration or exits a process; the CLI owns both.
+ */
+
+import { readdirSync, readFileSync, statSync } from 'node:fs';
+import path from 'node:path';
+
+import { listFeatureFiles } from './bdd-scenario-scanner.js';
+
+export { listFeatureFiles };
+
+/** Extensions a step-definition module may carry. */
+const STEP_FILE_EXTENSIONS = Object.freeze([
+  '.js',
+  '.mjs',
+  '.cjs',
+  '.ts',
+  '.mts',
+  '.cts',
+  '.tsx',
+]);
+
+/** Directory names never walked when looking for step definitions. */
+const SKIPPED_DIRECTORIES = Object.freeze(
+  new Set(['node_modules', '.git', 'dist', 'build', '.next', 'coverage']),
+);
+
+/**
+ * Regular expressions for the built-in Cucumber parameter types, keyed by the
+ * name inside the braces. The empty key is the anonymous `{}` parameter and
+ * doubles as the fallback for a custom type this scan cannot resolve.
+ *
+ * @type {Readonly<Record<string, string>>}
+ */
+const PARAMETER_PATTERNS = Object.freeze({
+  '': '(.*)',
+  int: '(-?\\d+)',
+  float: '(-?\\d*\\.?\\d+)',
+  word: '([^\\s]+)',
+  string: '("[^"]*"|\'[^\']*\')',
+});
+
+/**
+ * Step-registration call sites this scan recognises. `Step` and `defineStep`
+ * cover the generic registrars playwright-bdd and cucumber-js both expose.
+ *
+ * Group 2/3 capture a quoted expression, group 4/5 a regular-expression
+ * literal with its flags.
+ */
+const STEP_CALL_PATTERN =
+  /\b(Given|When|Then|And|But|Step|defineStep)\s*\(\s*(?:(['"`])((?:\\.|(?!\2)[^\\])*)\2|\/((?:\\.|\[(?:\\.|[^\]\\])*\]|[^/\\[])+)\/([dgimsuvy]*))/g;
+
+/** Escape one character for literal use inside a regular expression. */
+function escapeRegExp(text) {
+  return text.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+}
+
+/**
+ * Render one alternation-free segment of a Cucumber expression: parameter
+ * placeholders become capture groups, `(optional)` runs become optional
+ * groups, and everything else is escaped literal text.
+ *
+ * @param {string} segment
+ * @returns {string}
+ */
+function renderSegment(segment) {
+  let out = '';
+  let i = 0;
+  while (i < segment.length) {
+    const ch = segment[i];
+    if (ch === '\\' && i + 1 < segment.length) {
+      out += escapeRegExp(segment[i + 1]);
+      i += 2;
+      continue;
+    }
+    if (ch === '{') {
+      const end = segment.indexOf('}', i);
+      if (end !== -1) {
+        const name = segment.slice(i + 1, end);
+        out += PARAMETER_PATTERNS[name] ?? PARAMETER_PATTERNS[''];
+        i = end + 1;
+        continue;
+      }
+    }
+    if (ch === '(') {
+      const end = segment.indexOf(')', i);
+      if (end !== -1) {
+        out += `(?:${renderSegment(segment.slice(i + 1, end))})?`;
+        i = end + 1;
+        continue;
+      }
+    }
+    out += escapeRegExp(ch);
+    i += 1;
+  }
+  return out;
+}
+
+/**
+ * Split a word on unescaped `/` so `a/an` becomes two alternatives. Escaped
+ * `\/` stays literal.
+ *
+ * @param {string} word
+ * @returns {string[]}
+ */
+function splitAlternation(word) {
+  const parts = [];
+  let current = '';
+  for (let i = 0; i < word.length; i += 1) {
+    const ch = word[i];
+    if (ch === '\\' && i + 1 < word.length) {
+      current += ch + word[i + 1];
+      i += 1;
+      continue;
+    }
+    if (ch === '/') {
+      parts.push(current);
+      current = '';
+      continue;
+    }
+    current += ch;
+  }
+  parts.push(current);
+  return parts;
+}
+
+/**
+ * Compile a Cucumber expression into an anchored `RegExp`.
+ *
+ * Alternation is resolved per whitespace-separated word, which is what the
+ * real expression grammar does. Resolving it across the whole string instead
+ * would turn `I have a/an apple` into `^I have a|an apple$` — two anchored
+ * alternatives, neither of them the intended step.
+ *
+ * @param {string} expression
+ * @returns {RegExp}
+ */
+function expressionToRegExp(expression) {
+  const tokens = String(expression).split(/(\s+)/);
+  const body = tokens
+    .map((token) => {
+      if (token.length === 0) return '';
+      if (/^\s+$/.test(token)) return escapeRegExp(token);
+      const alternatives = splitAlternation(token);
+      const rendered = alternatives.map(renderSegment);
+      return rendered.length > 1 ? `(?:${rendered.join('|')})` : rendered[0];
+    })
+    .join('');
+  return new RegExp(`^${body}$`);
+}
+
+/**
+ * Recursively list step-definition source files under the given roots.
+ *
+ * Deliberately not `walkFilesByExtension` from `fs-walk.js`, which is the
+ * shared walker for the lint surfaces. That one matches a single extension and
+ * walks everything below the root, so reusing it here would mean seven passes
+ * — one per accepted extension — each of them descending into a `node_modules`
+ * a consumer's step root may well contain. It also rethrows every non-ENOENT
+ * `readdir` failure, where this walker must skip an unreadable directory: an
+ * unreadable *scope* has to surface as "zero step definitions", the gate's
+ * fail-closed path, which names the scope and its step roots.
+ *
+ * @param {string[]} roots absolute or cwd-relative directories
+ * @returns {string[]} absolute paths, sorted
+ */
+export function listStepFiles(roots) {
+  const found = [];
+  for (const root of roots ?? []) {
+    walkStepDir(path.resolve(root), found);
+  }
+  return found.sort();
+}
+
+function walkStepDir(dir, acc) {
+  let entries;
+  try {
+    entries = readdirSync(dir, { withFileTypes: true });
+  } catch {
+    return;
+  }
+  for (const entry of entries) {
+    const full = path.join(dir, entry.name);
+    // `withFileTypes` reports a symlink as neither file nor directory, so
+    // fall back to a stat for those rather than dropping them silently.
+    const isDir =
+      entry.isDirectory() || (entry.isSymbolicLink() && isDirAt(full));
+    if (isDir) {
+      if (!SKIPPED_DIRECTORIES.has(entry.name)) walkStepDir(full, acc);
+      continue;
+    }
+    if (STEP_FILE_EXTENSIONS.includes(path.extname(entry.name))) acc.push(full);
+  }
+}
+
+function isDirAt(target) {
+  try {
+    return statSync(target).isDirectory();
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * Extract every step registration in one source file.
+ *
+ * @param {string} source file contents
+ * @param {string} file absolute path, recorded on each entry
+ * @returns {Array<{ file: string, line: number, source: string, regex: RegExp }>}
+ */
+function parseStepDefinitions(source, file) {
+  const entries = [];
+  STEP_CALL_PATTERN.lastIndex = 0;
+  let match = STEP_CALL_PATTERN.exec(source);
+  while (match !== null) {
+    const [, , , quoted, pattern, flags] = match;
+    const line = source.slice(0, match.index).split('\n').length;
+    const regex = compileMatcher({ quoted, pattern, flags });
+    if (regex) entries.push({ file, line, source: quoted ?? pattern, regex });
+    match = STEP_CALL_PATTERN.exec(source);
+  }
+  return entries;
+}
+
+/**
+ * Build one matcher from a captured registration. A malformed regular
+ * expression yields `null` — the definition is skipped rather than crashing
+ * the scan, and the steps it would have claimed surface as unbound, which is
+ * the safe direction.
+ */
+function compileMatcher({ quoted, pattern, flags }) {
+  if (typeof quoted === 'string') {
+    try {
+      return expressionToRegExp(quoted);
+    } catch {
+      return null;
+    }
+  }
+  try {
+    // `g` and `y` are stateful across `.test()` calls; strip them so the index
+    // cannot depend on how many times it has been consulted.
+    return new RegExp(pattern, (flags ?? '').replace(/[gy]/g, ''));
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Build the step index for one scope.
+ *
+ * @param {{ files: string[], readFile?: (p: string) => string }} params
+ * @returns {{ entries: Array<{ file: string, line: number, source: string, regex: RegExp }>, files: string[] }}
+ */
+export function buildStepIndex({ files, readFile }) {
+  const read = readFile ?? ((p) => readFileSync(p, 'utf8'));
+  const entries = [];
+  for (const file of files ?? []) {
+    let source;
+    try {
+      source = read(file);
+    } catch {
+      continue;
+    }
+    entries.push(...parseStepDefinitions(source, file));
+  }
+  return { entries, files: [...(files ?? [])] };
+}
+
+/**
+ * Find the first definition in the index claiming `text`.
+ *
+ * @param {{ entries: Array<{ regex: RegExp }> }} index
+ * @param {string} text the step text, keyword already stripped by the parser
+ * @returns {object | null} the matching entry, or `null` when nothing claims it
+ */
+export function matchStep(index, text) {
+  for (const entry of index?.entries ?? []) {
+    if (entry.regex.test(text)) return entry;
+  }
+  return null;
+}
+
+/**
+ * Module-private helpers the suite drives directly. Bundled rather than
+ * exported individually — the same seam `knip-entry-sync.js` and
+ * `source-classifier.js` use — so test-only symbols cost one production
+ * dead-export row instead of one each, and so private helpers do not read as
+ * API.
+ */
+export const __testing = Object.freeze({
+  expressionToRegExp,
+  parseStepDefinitions,
+});

package/.agents/scripts/lib/bootstrap/install-ledger.js

@@ -105,9 +105,11 @@ export function ledgerPath(projectRoot) {
  *
  * @param {object} args
  * @param {import('./manifest.js').MutationManifestEntry[]} args.entries
- *   — the APPROVED subset of the mutation manifest that was applied.
- * @param {string[]} args.approvedGroups — the phase groups the operator
- *   approved (sorted for stable output).
+ *   — the subset of the mutation manifest that was applied.
+ * @param {string[]} args.approvedGroups — the phase groups whose mutations
+ *   landed (sorted for stable output). Field name predates Story #5007's
+ *   removal of the phased-approval gate; the ledger record shape is a
+ *   consumer contract read back by `mandrel uninstall`, so it is unchanged.
  * @param {{ owner?: string, repo?: string }} [args.answers]
  * @param {string} [args.appliedAt] — ISO-8601 timestamp (default: now).
  * @param {Record<string, { action?: string }>} [args.report] — the live

package/.agents/scripts/lib/bootstrap/issue-forms-template.js

@@ -15,8 +15,7 @@
  * `HUMAN_INTENT_FIELDS` table here, and each field's heading is the exact
  * section name the parser maps (`goal` → `## Goal`, etc.). The CI
  * conformance lint (`lint-issue-body.js`) runs the real `parse()` against
- * human-opened issues so the form and the parser cannot silently drift —
- * the same model `ci-workflow-template.js` follows for `ci.yml`.
+ * human-opened issues so the form and the parser cannot silently drift.
  *
  * ## Form fields ⊆ body schema
  *
@@ -70,9 +69,8 @@ export const STORY_FORM_RELATIVE_PATH = `${ISSUE_TEMPLATE_RELATIVE_DIR}/story.ym
  * generated YAML uses it verbatim as the field `label` so GitHub's
  * `### {label}` render produces a heading the parser recognises.
  *
- * Machine-managed body fields (`wide`, `reason_to_exist`,
- * `estimated_test_files`, `depends_on` meta) are intentionally absent —
- * the runtime fills those. `depends_on` is exposed as a free-text input
+ * Machine-managed body fields (`wide`, `reason_to_exist`, `depends_on`
+ * meta) are intentionally absent — the runtime fills those. `depends_on` is exposed as a free-text input
  * that serializes to the `blocked by #N` footer `parse()` already reads.
  *
  * @type {Array<{
@@ -367,7 +365,7 @@ jobs:
 
 /**
  * Write (or refresh) the Story issue form into a project checkout. Idempotent at
- * the byte level — mirrors {@link ensureCiWorkflow}'s contract:
+ * the byte level:
  *
  * - file absent → `created`
  * - byte-identical → `unchanged`