mandrel 2.60.0 → 2.62.0

package/.agents/scripts/lib/bdd-scenario-budget.js

@@ -1,46 +1,21 @@
 /**
- * bdd-scenario-budget.js — envelope byte budget for the `bddScenarios`
- * `/mandrel-plan` context-envelope field (Story #4977).
- *
- * `bdd-scenario-scanner.js`'s `scanBddScenarios` stays a faithful, uncapped
- * index of the project's `.feature` corpus — that scan is also used
- * directly by `lib/qa/resolve-selection.js`, which needs the full set. The
- * cap belongs at the envelope boundary instead, in its own module: on a
- * consumer with a mature Gherkin corpus, `bddScenarios` grew to 118 KB —
- * larger than `docsContext` and `systemPrompts` combined — consuming
- * nearly the entire `PLAN_CONTEXT_ENVELOPE_BYTE_CEILING` headroom on its
- * own and blocking `/audit-to-stories`' single-plan path entirely.
- *
- * Deliberately a fixed framework constant rather than an `.agentrc.json`
- * knob: Story #4541 retired the one operator-tunable planner-context budget
- * (`planning.context.maxBytes`) because a cap the operator can raise past
- * what the model can read fails silently again, and the same reasoning
- * applies here.
+ * Byte cap for the `bddScenarios` plan-envelope field. The scanner stays
+ * uncapped (other callers need the full set); the cap lives at the envelope
+ * boundary, since a mature corpus can crowd out the whole envelope. A fixed
+ * constant, not a config knob: a cap an operator can raise past what the
+ * model reads fails silently.
  */
 
 /**
- * Byte budget for the capped `bddScenarios` envelope field. Sized well
- * under `PLAN_CONTEXT_ENVELOPE_BYTE_CEILING` (256 KB) — this is one of
- * several envelope fields, not the whole budget. At the measured ~337
- * bytes/scenario average (Story #4977 evidence, a mature Gherkin corpus),
- * 24 KB holds roughly 70 scenarios before truncating.
- *
- * Deliberately module-private: the only production consumer is
- * {@link capBddScenarios} below via the `opts.byteBudget` default. Tests
- * assert the resulting behavior (truncation, order, fit) rather than
- * importing this value directly, so it carries no public export the
- * `--production` dead-exports ratchet would otherwise flag as test-only.
+ * One field's share of the 256 KB envelope ceiling: about 70 scenarios.
+ * Module-private so it is not a test-only export.
  */
 const BDD_SCENARIOS_BYTE_BUDGET = 24_000;
 
 /**
- * Truncate a scenario index to a byte budget, deterministically (scan
- * order — file walk order, then in-file order — never re-sorted), and
- * report what was dropped rather than truncating silently: `truncated` is
- * `null` when everything fit, else a note naming how many scenarios were
- * cut (Story #5312).
+ * Truncate in scan order (never re-sorted) and report what was dropped.
  *
- * @param {Array<object>} scenarios Full scan output (order preserved).
+ * @param {Array<object>} scenarios
  * @param {{ byteBudget?: number }} [opts]
  * @returns {{
  *   scenarios: Array<object>,
@@ -70,8 +45,6 @@ export function capBddScenarios(scenarios, opts = {}) {
 }
 
 /**
- * The `truncated` note: `null` when everything fit, else what was cut.
- *
  * @param {Array<object>} list
  * @param {number} cut
  * @param {number} byteBudget

package/.agents/scripts/lib/bdd-scenario-scanner.js

@@ -1,28 +1,7 @@
 /**
- * bdd-scenario-scanner.js — Gherkin scenario index for /mandrel-plan Phase 7.
- *
- * Story #2637 (sibling to #2636's file-assumption gate; the #2634 and #2635
- * planner-grounding siblings were retired in Story #4811). The Acceptance
- * Engineer step of
- * `epic-plan-spec-author` currently writes ACs from Epic/Tech Spec narrative
- * alone — it never inspects the consumer project's existing `.feature`
- * files. Planned ACs frequently duplicate scenarios that already exist or
- * re-specify behaviour the codebase already proves; the duplication is
- * only discovered (at best) during `/mandrel-deliver` or (at worst) after
- * a redundant PR ships.
- *
- * `scanBddScenarios` walks every configured feature root, parses each
- * `.feature` file with a Gherkin-aware regex pass (deliberately not a
- * full Gherkin AST — keep the scanner cheap and dependency-free), and
- * returns one entry per scenario with its file path, line number,
- * scenario title, tag list, and an extracted set of outcome keywords
- * (action verb + objects from the "Then" clauses). The keyword set is
- * the fuzzy-match surface the planner uses to spot ACs that already
- * have a matching scenario.
- *
- * Determinism is load-bearing: the matcher is keyword-based, not
- * embedding-based, so re-running `/mandrel-plan` against the same
- * acceptance spec produces the same disposition annotations.
+ * Gherkin scenario index for `/mandrel-plan`, so planned ACs can be matched
+ * against existing scenarios. A cheap regex pass, not a full AST; matching is
+ * keyword-based (not embeddings) so re-planning is deterministic.
  */
 
 import { readdirSync, readFileSync, statSync } from 'node:fs';
@@ -31,9 +10,7 @@ import path from 'node:path';
 import { Logger } from './Logger.js';
 
 /**
- * Recursively list every file with a `.feature` extension under one of
- * the given roots. Returns absolute paths; never throws on permission
- * errors — unreadable directories are simply skipped.
+ * Unreadable directories are skipped, never thrown.
  *
  * @param {string[]} roots
  * @param {{ logger?: { debug: Function } }} [opts]
@@ -79,14 +56,7 @@ function walk(dir, acc, logger) {
   }
 }
 
-/**
- * English stop words that carry no outcome semantics. Stripped from
- * extracted keywords so "the invoice appears in the outbox" reduces to
- * `{invoice, appears, outbox}` rather than including `{the, in}`.
- *
- * Kept short on purpose — false-negative pruning here is preferable to
- * over-pruning a verb the matcher needs.
- */
+/** Kept short: under-pruning beats pruning a verb the matcher needs. */
 const STOP_WORDS = new Set([
   'a',
   'an',
@@ -121,13 +91,6 @@ const STOP_WORDS = new Set([
 ]);
 
 /**
- * Reduce a free-text outcome ("the invoice appears in the outbox") to a
- * deterministic, lower-case keyword set ("invoice", "appears", "outbox").
- * Words of length 1 are dropped; common stop words are filtered.
- *
- * Exported so the matcher and downstream tests can share the exact
- * tokenisation contract.
- *
  * @param {string} text
  * @returns {string[]}
  */
@@ -147,16 +110,8 @@ const THEN_LINE_RE = /^\s*(?:Then|And|But)\s+(.+?)\s*$/i;
 const STEP_KEYWORD_RE = /^\s*(?:Given|When|Then|And|But|\*)\s+/i;
 
 /**
- * Parse a single `.feature` file body into an array of scenario rows.
- * The parser is deliberately minimal:
- *
- *   - `@tag` lines preceding a `Scenario:` are attached to that scenario.
- *   - `Scenario:` and `Scenario Outline:` both produce a row.
- *   - `Then` / `And` / `But` lines following the scenario (until the
- *     next scenario or EOF) feed the `outcomeKeywords` set.
- *
- * The Background block is recognised but its steps are NOT folded into
- * outcomeKeywords — Background carries setup, not outcomes.
+ * Only `Then`/`And`/`But` lines feed `outcomeKeywords`; Background steps are
+ * setup, not outcomes, and are excluded.
  *
  * @param {string} body
  * @returns {Array<{ scenarioTitle: string, line: number, tags: string[], outcomeKeywords: string[] }>}
@@ -199,8 +154,7 @@ export function parseFeatureBody(body) {
       const thenMatch = raw.match(THEN_LINE_RE);
       if (thenMatch) current.thenLines.push(thenMatch[1]);
     }
-    // Reset pendingTags when a step keyword in the body appears with no
-    // scenario yet — stray tags before a Feature: header don't bind.
+    // Stray tags before any scenario don't bind.
     if (current === null && STEP_KEYWORD_RE.test(raw)) {
       pendingTags = [];
     }
@@ -223,14 +177,6 @@ function finalize(scenario) {
 }
 
 /**
- * Scan every `.feature` file under the configured feature roots and
- * return the full scenario index. Each row carries the absolute path,
- * the 1-based line number of the `Scenario:` keyword, the title, the
- * tag list, and the deterministic outcome-keyword set. Returns an
- * empty array when no roots exist or no scenarios are found — the
- * caller (the spec-author skill) uses emptiness to know the project
- * hasn't adopted BDD, no warning required.
- *
  * @param {{ featureRoots: string[] }} opts
  * @returns {Array<{ file: string, line: number, scenarioTitle: string, tags: string[], outcomeKeywords: string[] }>}
  */
@@ -264,11 +210,8 @@ export function scanBddScenarios(opts = {}) {
 }
 
 /**
- * Score the overlap between an acceptance criterion's outcome string
- * and a scenario's outcome-keyword set. The score is the count of
- * keywords the AC outcome shares with the scenario, normalised by the
- * smaller of the two sets so single-word ACs aren't penalised against
- * verbose scenarios (and vice versa).
+ * Shared keywords over the smaller set's size, so terse ACs are not
+ * penalised against verbose scenarios.
  *
  * @param {string} acOutcome
  * @param {{ outcomeKeywords: string[] }} scenario
@@ -286,12 +229,7 @@ export function scoreMatch(acOutcome, scenario) {
 }
 
 /**
- * Find the best matching scenario for one AC outcome string, if any.
- * Returns `null` when no scenario scores above `minScore` (default
- * `0.5`). The matcher is intentionally conservative — false positives
- * cost the planner more (rewriting the spec to "refine" a scenario
- * that doesn't actually exist) than false negatives (writing a new
- * scenario the operator can later dedupe).
+ * Conservative: a false match costs more than a duplicate scenario.
  *
  * @param {string} acOutcome
  * @param {Array<{ outcomeKeywords: string[] }>} scenarios

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

@@ -1,38 +1,12 @@
 /**
- * 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: /mandrel-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.
+ * Scoped discovery and matching of BDD step definitions for
+ * `check-gherkin-corpus.js`. Feature discovery reuses the scenario scanner's
+ * `listFeatureFiles` so both agree on what a feature file is.
+ *
+ * The index is a heuristic source scan (it cannot see runtime-built or
+ * wrapped definitions), hence the gate's step-waiver list. An unknown
+ * `{custom}` parameter degrades to `(.*)`: over-matching misses a finding,
+ * under-matching blocks a delivery with a false one.
  */
 
 import { readdirSync, readFileSync, statSync } from 'node:fs';
@@ -42,7 +16,6 @@ import { listFeatureFiles } from './bdd-scenario-scanner.js';
 
 export { listFeatureFiles };
 
-/** Extensions a step-definition module may carry. */
 const STEP_FILE_EXTENSIONS = Object.freeze([
   '.js',
   '.mjs',
@@ -53,15 +26,12 @@ const STEP_FILE_EXTENSIONS = Object.freeze([
   '.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.
+ * Built-in parameter types; `''` is `{}` and the fallback for custom types.
  *
  * @type {Readonly<Record<string, string>>}
  */
@@ -73,27 +43,16 @@ const PARAMETER_PATTERNS = Object.freeze({
   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.
- */
+/** Groups 2/3: quoted expression; 4/5: regex literal and 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
+ * @param {string} segment An alternation-free piece of an expression.
  * @returns {string}
  */
 function renderSegment(segment) {
@@ -130,10 +89,7 @@ function renderSegment(segment) {
 }
 
 /**
- * Split a word on unescaped `/` so `a/an` becomes two alternatives. Escaped
- * `\/` stays literal.
- *
- * @param {string} word
+ * @param {string} word Split on unescaped `/`.
  * @returns {string[]}
  */
 function splitAlternation(word) {
@@ -158,12 +114,8 @@ function splitAlternation(word) {
 }
 
 /**
- * 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.
+ * Alternation is per word, as in the real grammar; whole-string alternation
+ * would anchor the wrong alternatives.
  *
  * @param {string} expression
  * @returns {RegExp}
@@ -183,18 +135,11 @@ function expressionToRegExp(expression) {
 }
 
 /**
- * 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.
+ * Not `fs-walk.js`: that walker takes one extension, descends into
+ * `node_modules`, and rethrows readdir failures, whereas an unreadable scope
+ * here must surface as "zero step definitions" (the gate's fail-closed path).
  *
- * @param {string[]} roots absolute or cwd-relative directories
+ * @param {string[]} roots
  * @returns {string[]} absolute paths, sorted
  */
 export function listStepFiles(roots) {
@@ -214,8 +159,7 @@ function walkStepDir(dir, acc) {
   }
   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.
+    // A symlink is neither file nor directory to `withFileTypes`; stat it.
     const isDir =
       entry.isDirectory() || (entry.isSymbolicLink() && isDirAt(full));
     if (isDir) {
@@ -235,10 +179,8 @@ function isDirAt(target) {
 }
 
 /**
- * Extract every step registration in one source file.
- *
- * @param {string} source file contents
- * @param {string} file absolute path, recorded on each entry
+ * @param {string} source
+ * @param {string} file
  * @returns {Array<{ file: string, line: number, source: string, regex: RegExp }>}
  */
 function parseStepDefinitions(source, file) {
@@ -255,12 +197,7 @@ function parseStepDefinitions(source, file) {
   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.
- */
+/** A malformed pattern yields `null`: its steps surface as unbound, the safe direction. */
 function compileMatcher({ quoted, pattern, flags }) {
   if (typeof quoted === 'string') {
     try {
@@ -270,8 +207,7 @@ function compileMatcher({ quoted, pattern, flags }) {
     }
   }
   try {
-    // `g` and `y` are stateful across `.test()` calls; strip them so the index
-    // cannot depend on how many times it has been consulted.
+    // `g`/`y` make `.test()` stateful.
     return new RegExp(pattern, (flags ?? '').replace(/[gy]/g, ''));
   } catch {
     return null;
@@ -279,8 +215,6 @@ function compileMatcher({ quoted, pattern, flags }) {
 }
 
 /**
- * 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[] }}
  */
@@ -300,11 +234,9 @@ export function buildStepIndex({ files, readFile }) {
 }
 
 /**
- * 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
+ * @param {string} text Step text without its keyword.
+ * @returns {object | null}
  */
 export function matchStep(index, text) {
   for (const entry of index?.entries ?? []) {
@@ -313,13 +245,7 @@ export function matchStep(index, text) {
   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.
- */
+/** Test-only helpers, bundled so they cost one dead-export row. */
 export const __testing = Object.freeze({
   expressionToRegExp,
   parseStepDefinitions,

package/.agents/scripts/lib/bootstrap/baseline-merge-driver.js

@@ -1,24 +1,8 @@
 /**
- * bootstrap/baseline-merge-driver — register the `baselines/*.json` merge
- * driver on a consumer clone (Story #5215).
- *
- * Registration has two halves that live in different places, and conflating
- * them is why this needs a doctor check rather than just an installer:
- *
- *   1. **`.gitattributes`** says which files use the driver. It is a tracked
- *      file, so installing the line once ships it to everyone.
- *   2. **`git config merge.mandrel-baseline.driver`** says what the driver
- *      actually is. Git deliberately keeps this out of tracked config —
- *      otherwise a clone would execute a command chosen by whoever wrote the
- *      repo — so it is **per clone**, and a fresh clone silently falls back
- *      to git's text merge with no error at all.
- *
- * That silence is the whole reason `mandrel doctor` carries a check: an
- * unregistered clone is not broken in any way it can report on its own, it
- * just quietly goes back to conflicting (or worse, splicing) baselines.
- *
- * This module owns both halves plus the strings they share, so the installer
- * and the doctor check cannot drift apart on the exact command.
+ * Register the `baselines/*.json` merge driver. The `.gitattributes` line is
+ * tracked; the `git config` driver command is per clone, so a fresh clone
+ * silently falls back to text merge — hence the doctor check. Owning both
+ * halves here keeps installer and doctor agreeing on the command.
  *
  * @module lib/bootstrap/baseline-merge-driver
  */
@@ -27,38 +11,22 @@ import fs from 'node:fs';
 import path from 'node:path';
 import { spawnCapture } from '../child-exec.js';
 
-/** Driver name, as it appears on both sides of the registration. */
 const BASELINE_MERGE_DRIVER_NAME = 'mandrel-baseline';
 
-/** The `.gitattributes` line that routes baselines through the driver. */
 const BASELINE_MERGE_ATTRIBUTE = `baselines/*.json merge=${BASELINE_MERGE_DRIVER_NAME}`;
 
-/** Git config key holding the driver command. */
 export const BASELINE_MERGE_DRIVER_CONFIG_KEY = `merge.${BASELINE_MERGE_DRIVER_NAME}.driver`;
 
-/** Script path the driver command invokes, relative to the worktree root. */
+/** Relative: git runs the driver from the worktree root, in every worktree. */
 const DRIVER_SCRIPT = '.agents/scripts/merge-baseline.js';
 
-/** Git's merge-driver placeholders, in the order the driver's argv expects. */
+/** In the order the driver's argv expects. */
 const DRIVER_PLACEHOLDERS = '%O %A %B %P';
 
 /**
- * Build the driver command for a given node binary.
- *
- * The interpreter is the RESOLVED ABSOLUTE path (`process.execPath`), not the
- * bare word `node`, and it is quoted. Git runs a merge driver through the
- * shell, and that shell's `PATH` is whatever launched git — a GUI client, a
- * Finder-launched editor, a `launchd` job — none of which necessarily carry
- * the nvm/volta shim that puts `node` on an interactive shell's `PATH`. A
- * driver that cannot start is not a loud failure: git reports the driver
- * exited non-zero and falls back to leaving the file conflicted, which reads
- * as "baselines conflict again" — the exact symptom the driver exists to
- * remove. Quoting covers the installation whose node lives under a path with
- * a space (`/Users/a b/.nvm/...`).
- *
- * The script path stays RELATIVE: git runs the driver from the worktree root,
- * and that is also where `mandrel sync` materializes `.agents/`, so one
- * command is correct in the main checkout and in every linked worktree.
+ * The node path is absolute and quoted: git's shell may lack the nvm/volta
+ * `PATH` shim (GUI clients, launchd), and a driver that cannot start just
+ * leaves the file conflicted. Quoting covers paths with spaces.
  *
  * @param {string} [execPath] Absolute path to the node binary.
  * @returns {string}
@@ -67,31 +35,16 @@ function buildBaselineMergeDriverCommand(execPath = process.execPath) {
   return `"${execPath}" ${DRIVER_SCRIPT} ${DRIVER_PLACEHOLDERS}`;
 }
 
-/** The driver command this process would install. */
 const BASELINE_MERGE_DRIVER_COMMAND = buildBaselineMergeDriverCommand();
 
-/**
- * The exact command an operator runs to complete registration. Single-quoted
- * because the command itself carries the double quotes around the node path.
- */
+/** Single-quoted: the command carries double quotes around the node path. */
 export const BASELINE_MERGE_DRIVER_REMEDY = `git config ${BASELINE_MERGE_DRIVER_CONFIG_KEY} '${BASELINE_MERGE_DRIVER_COMMAND}'`;
 
 /**
- * Split a configured driver command into an executable + argv pair, dropping
- * git's `%O %A %B %P` placeholders.
- *
- * Used by the `mandrel doctor` check to actually RUN the configured command
- * (with `--help`) rather than only assert the config key is non-empty. A key
- * pointing at a node that no longer exists — the ordinary outcome of an nvm
- * version bump after the driver was installed — is set, non-empty, and
- * completely broken, and the pre-Story-#5277 check called that healthy.
- *
- * Tokenising here rather than handing the string to a shell is deliberate:
- * the value is per-clone git config, and executing it through `shell: true`
- * would turn any write to that key into arbitrary command execution
- * (`security-baseline.md` § Output & Rendering — never concatenate into a
- * shell command). Only double quotes are honoured, which is exactly the
- * quoting {@link buildBaselineMergeDriverCommand} emits.
+ * Split a driver command into file + argv, dropping git placeholders, so the
+ * doctor can actually run it (an nvm bump leaves a set-but-broken key).
+ * Tokenised rather than shelled: executing per-clone config through a shell
+ * would be arbitrary command execution. Only double quotes are honoured.
  *
  * @param {string|null|undefined} command
  * @returns {{ file: string, args: string[] }|null} null when there is no
@@ -112,8 +65,7 @@ export function parseBaselineMergeDriverCommand(command) {
 }
 
 /**
- * Does this `.gitattributes` content route baselines through the driver?
- * Comment lines do not count — a commented-out registration is not one.
+ * Comment lines do not count.
  *
  * @param {string|null|undefined} gitattributes
  * @returns {boolean}
@@ -129,23 +81,10 @@ function declaresBaselineMergeDriver(gitattributes) {
 }
 
 /**
- * Is the driver DECLARED by this project and REGISTERED in this clone?
- *
- * Two callers ask this exact question of two different clones — the
- * `mandrel doctor` check, and the pre-push base-sync guard — and both need
- * the same two-part answer, because the two halves fail differently:
- *
- *   - **Not declared** → the project never opted in. Both callers stay
- *     silent; telling a consumer to register a driver for files they do not
- *     route through it is noise. An unreadable `.gitattributes` reads the
- *     same way, deliberately.
- *   - **Declared, empty command** → the silent case. Git reports nothing at
- *     all: it falls back to its own line-based merge, which on a generated
- *     baseline either conflicts on the `generatedAt` stamp or splices both
- *     sides' rows into a set neither side scored.
- *
- * The `runGit` seam takes argv tokens and returns `{ status, stdout }`, which
- * is the shape both callers' own git surfaces already produce.
+ * Is the driver declared by the project and registered in this clone? Not
+ * declared (or unreadable `.gitattributes`) means the project never opted in
+ * and callers stay silent; declared with an empty command is the silent
+ * text-merge fallback callers must flag.
  *
  * @param {{
  *   projectRoot: string,
@@ -206,8 +145,6 @@ function ensureGitattributesLine(projectRoot, fsImpl = fs) {
 }
 
 /**
- * Point `merge.mandrel-baseline.driver` at the driver in THIS clone.
- *
  * @param {string} projectRoot
  * @param {typeof spawnCapture} [spawnImpl]
  * @returns {{ action: 'set'|'already-present'|'not-a-repo'|'failed' }}
@@ -258,9 +195,6 @@ function ensureDriverGitConfig(projectRoot, spawnImpl = spawnCapture) {
 }
 
 /**
- * Read `.gitattributes` without writing it — the `configOnly` half of
- * {@link ensureBaselineMergeDriver}.
- *
  * @param {string} projectRoot
  * @param {typeof fs} fsImpl
  * @returns {{ action: 'already-present'|'absent', path: string }}
@@ -282,24 +216,10 @@ function probeGitattributesLine(projectRoot, fsImpl) {
 }
 
 /**
- * Install the registration. Idempotent: a second run reports
- * `already-present` and changes no bytes.
- *
- * Two modes, because the two callers mean different things by "install":
- *
- * - **Full (default)** — `mandrel init --with-quality` and this repo's own
- *   `prepare`. Writes the `.gitattributes` line as well as the config key:
- *   the caller has opted the repository into the quality surface, so
- *   declaring the attribute is part of what it asked for.
- * - **`configOnly: true`** — consumer `mandrel sync`. Writes ONLY the
- *   per-clone config key, and only when `.gitattributes` already declares the
- *   attribute. `sync` materializes `.agents/`; it is not an opt-in to the
- *   quality surface, and creating a `.gitattributes` in a project that never
- *   asked for one would be `sync` changing git's behaviour on files it has no
- *   business touching. What it DOES fix is the real gap: the attribute is
- *   tracked and therefore ships with the repo, while the config key is
- *   per-clone and silently absent in every fresh clone — so the half that
- *   cannot travel is installed on the one command every consumer runs.
+ * Idempotent install. Full mode (init/prepare) writes the attribute and the
+ * config key. `configOnly` (consumer `sync`) writes only the per-clone key,
+ * and only when the project already declares the attribute — `sync` is not
+ * an opt-in to the quality surface.
  *
  * @param {object} ctx
  * @param {string} ctx.projectRoot

package/.agents/scripts/lib/bootstrap/branch-protection.js

@@ -141,11 +141,8 @@ export async function applyBranchProtection({
     return { status: 'skipped', reason: 'no-checks' };
   }
 
-  // Story #2018 (Bug 3): on a fresh-empty repo with no commits yet, the
-  // base branch hasn't been pushed and the protection PUT would 404 with
-  // a confusing transport error. Probe for existence first so operators
-  // get a clear "no-base-branch" skip rather than discovering the
-  // `enforce: false` opt-out by reading the failure message.
+  // On an empty repo the protection PUT 404s confusingly; probe first so the
+  // skip reads "no base branch".
   if (typeof provider.branchExists === 'function') {
     let exists = true;
     try {