mandrel 2.59.0 → 2.61.0

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

@@ -1,70 +1,11 @@
-// .agents/scripts/lib/baselines/scope.js
-//
-// Story #1962 / Task #1970 — the ScopeResolution helper behind the
-// `check-baselines.js` dispatcher: `resolveDispatchScope` in
-// `lib/orchestration/check-baselines/phases/compare.js` is its one
-// caller. Routing the read side's scope decision through a single pure
-// function keeps the precedence rules from being re-implemented per gate.
-//
-// It is NOT the writers' resolver. `lib/baselines/refresh-service.js`
-// defines its own private `resolveScope` (Story #3658) over a different
-// input set, and the header here used to claim otherwise — a claim that
-// made the read/write pair look coupled when it is not. Corrected in
-// Story #4922.
-//
-// The resolver is intentionally pure — it takes already-extracted
-// inputs and returns a frozen ScopeResolution. Env reading and config
-// loading happen in the caller; that keeps this module trivially
-// testable.
-//
-// Precedence (highest → lowest):
-//
-//   1. Environment — `BASELINE_SCOPE` ('full' | 'diff') and
-//      `BASELINE_REF` (any git ref). The dispatcher reads these from
-//      `process.env` and forwards via `envScope` / `envRef` so the
-//      resolver itself never touches process state. CI sets these.
-//   2. Config — `configScope` ('full' | 'diff') and `configRef` (any
-//      git ref) from `delivery.quality.gateScoping` in `.agentrc.json`.
-//   3. Default — `mode='diff'` against `ref='main'`. This is the
-//      framework-wide fallback when nothing else is configured.
-//
-// Story #4922 removed a fourth, highest-precedence layer: a
-// `cliFlags.fullScope` / `cliFlags.changedSinceRef` operator override,
-// plus the `cliFlags.changedFiles` → `files` plumbing that fed it. No
-// production caller ever populated any of the three — only this module's
-// own unit tests did — so the layer's only effect was to advertise a
-// `--full-scope` / `--changed-since` contract that `check-baselines.js`
-// does not implement, and a `files` set that no consumer read. Operators
-// who need full scope set `BASELINE_SCOPE=full`, which is what CI does.
-// (`mergeRowsByScope` below still takes a `files`-bearing scope — that
-// one comes from the refresh service's own resolver, not from here.)
-//
-// Missing-ref fallback: when the resolved mode is `'diff'` but no ref
-// is supplied at any layer, the resolver falls back to `'main'` rather
-// than producing a half-resolved scope with `ref=null`. The dispatcher
-// would have to invent a default anyway; centralising it here keeps
-// every gate aligned.
-//
-// `kind` (e.g. `'lint'`, `'coverage'`, `'crap'`) is currently echoed
-// through to the resolution unchanged. The argument exists so future
-// per-kind overrides (e.g. "lint always runs full") have a place to
-// land without breaking call signatures. Today: pass it; ignore it.
-//
-// Returned shape:
-//
-//   {
-//     kind: string,        // echoed back for caller convenience
-//     mode: 'full' | 'diff',
-//     ref:  string | null, // null in full mode; ref string in diff mode
-//     source: string,      // which layer won (debug / friction signal)
-//   }
+// Read-side scope resolution for the `check-baselines` dispatcher (the
+// refresh service has its own resolver). Pure: the caller extracts
+// `BASELINE_SCOPE` / `BASELINE_REF`; env wins, else diff against `main`.
 
 const VALID_MODES = new Set(['full', 'diff']);
 const DEFAULT_DIFF_REF = 'main';
 
 /**
- * Coerce a candidate value to a non-empty string, or `null`.
- *
  * @param {unknown} v
  * @returns {string | null}
  */
@@ -73,10 +14,7 @@ function asNonEmptyString(v) {
 }
 
 /**
- * Coerce a candidate scope value to one of the canonical modes, or
- * `null` if it is not a recognised mode. Unknown strings are dropped
- * rather than coerced — the layer "did not specify" rather than
- * "specified an invalid value".
+ * An unknown string means "unspecified", not invalid.
  *
  * @param {unknown} v
  * @returns {'full' | 'diff' | null}
@@ -86,13 +24,10 @@ function asMode(v) {
 }
 
 /**
- * Resolve a scope against the layered precedence (env > config >
- * default). Pure; no I/O.
+ * `source` names the winning layer; `ref` is null in full mode.
  *
  * @param {object} input
- * @param {string} input.kind          - Baseline kind (e.g. `'lint'`).
- * @param {string} [input.configScope] - `'full'` | `'diff'` from agentrc.
- * @param {string} [input.configRef]   - Diff ref from agentrc.
+ * @param {string} input.kind          - Echoed back.
  * @param {string} [input.envScope]    - From `BASELINE_SCOPE`.
  * @param {string} [input.envRef]      - From `BASELINE_REF`.
  * @returns {{
@@ -108,7 +43,6 @@ export function resolveScope(input = {}) {
       ? input.kind
       : 'unknown';
 
-  // ---- Layer 1: Environment (extracted by the caller) ------------------
   const envMode = asMode(input.envScope);
   if (envMode === 'full') {
     return Object.freeze({
@@ -128,29 +62,6 @@ export function resolveScope(input = {}) {
     });
   }
 
-  // ---- Layer 2: Config (delivery.quality.gateScoping) ------------------
-  const cfgMode = asMode(input.configScope);
-  if (cfgMode === 'full') {
-    return Object.freeze({
-      kind,
-      mode: 'full',
-      ref: null,
-      source: 'config:gateScoping.scope=full',
-    });
-  }
-  const cfgRef = asNonEmptyString(input.configRef);
-  if (cfgMode === 'diff' || cfgRef) {
-    return Object.freeze({
-      kind,
-      mode: 'diff',
-      ref: cfgRef ?? DEFAULT_DIFF_REF,
-      source: cfgRef
-        ? 'config:gateScoping.diffRef'
-        : 'config:gateScoping.scope=diff',
-    });
-  }
-
-  // ---- Layer 3: Default ------------------------------------------------
   return Object.freeze({
     kind,
     mode: 'diff',
@@ -160,44 +71,17 @@ export function resolveScope(input = {}) {
 }
 
 /**
- * Generic scope-aware row merge for s-diff-scoped-writes (Story #1974).
- *
- * Each per-kind module re-exports a thin wrapper that pins `scopeKey` to
- * the field used to identify the file the row belongs to (path / route /
- * bundle). This helper does the actual merge:
- *
- *   - `scope.mode === 'full'` (or `scope` is null/undefined / `scope.files`
- *     is empty): regenerated wins everywhere — returned as-is. This keeps
- *     the legacy "always rewrite" behaviour intact when no scope filter is
- *     applied.
- *   - `scope.mode === 'diff'`: rows whose `scopeKey` value is OUTSIDE
- *     `scope.files` are preserved from `prior` verbatim. Rows whose
- *     `scopeKey` value is INSIDE `scope.files` are taken from
- *     `regenerated` (the regenerated values for in-scope files). Prior
- *     rows for in-scope files are dropped (regen replaces them); regen
- *     rows for out-of-scope files are dropped (the writer should not have
- *     computed them, but we filter defensively).
- *   - Missing `prior` (null / undefined / empty) — regenerated wins
- *     everywhere; behaves like full mode.
- *
- * Identity matching uses the per-kind `identity(row)` function — for
- * coverage / lint / maintainability / mutation / lighthouse / bundle-size
- * the identity is the keyField value; for crap it's a composite
- * `path::method@startLine`. The merge preserves row ordering by
- * concatenating in-scope regen rows then out-of-scope prior rows; the
- * downstream `sortRows` from the per-kind module re-sorts before write.
- *
- * Pure. No I/O.
+ * Scope-aware row merge. Full mode, no scope, or no prior: regenerated wins.
+ * Diff mode: in-scope rows come from `regenerated`, out-of-scope rows from
+ * `prior` verbatim (regen rows outside scope are dropped). Output is unsorted.
  *
  * @template TRow
  * @param {object} args
  * @param {Array<TRow>|null|undefined} args.prior
  * @param {Array<TRow>|null|undefined} args.regenerated
  * @param {{mode?: 'full'|'diff', files?: Set<string>|Iterable<string>}|null|undefined} args.scope
- * @param {(row: TRow) => string} args.scopeKey  Per-kind scope-key extractor — returns the
- *        file path / route / bundle name used to match against `scope.files`.
- * @param {(row: TRow) => string} [args.identity] Per-kind identity extractor — defaults to
- *        the same as `scopeKey`. CRAP overrides this with `path::method@startLine`.
+ * @param {(row: TRow) => string} args.scopeKey  The file key matched against `scope.files`.
+ * @param {(row: TRow) => string} [args.identity] Defaults to `scopeKey`.
  * @returns {Array<TRow>}
  */
 export function mergeRowsByScope({
@@ -214,23 +98,15 @@ export function mergeRowsByScope({
   }
   const idFn = typeof identity === 'function' ? identity : scopeKey;
 
-  // No scope filter / full mode / no prior → regen wins everywhere.
   const mode = scope?.mode;
   if (!scope || mode === 'full' || priorRows.length === 0) {
     return regenRows.slice();
   }
 
-  // Coerce scope.files to a Set for O(1) membership tests. An empty Set in
-  // diff mode means "no files in scope" — every prior row is preserved
-  // and every regen row is dropped (defensive: writer feeds in-scope rows).
   const filesSet =
     scope.files instanceof Set ? scope.files : new Set(scope.files ?? []);
 
-  // In-scope regen rows: keep regen.
   const regenInScope = regenRows.filter((row) => filesSet.has(scopeKey(row)));
-  // Out-of-scope prior rows: keep prior, but drop any whose identity
-  // collides with an in-scope regen row (defensive — should not happen
-  // since identity within a kind is keyField-derived).
   const inScopeIds = new Set(regenInScope.map((row) => idFn(row)));
   const priorOutOfScope = priorRows.filter(
     (row) => !filesSet.has(scopeKey(row)) && !inScopeIds.has(idFn(row)),

package/.agents/scripts/lib/baselines/writer.js

@@ -1,41 +1,7 @@
 /**
- * writer.js — shared baseline writer (Story #1891, Epic #1786).
- *
- * Every legacy baseline-refresh script (`update-crap-baseline.js`,
- * `update-maintainability-baseline.js`, `lib/coverage-baseline.js`,
- * the auto-refresh evaluator, now inside `auto-refresh-runner.js`) used to assemble its own envelope and
- * call `fs.writeFileSync`. That meant the path canonicalisation, rollup
- * math, kernel-version stamping, and JSON-serialisation conventions were
- * duplicated five-ish times, each with subtly different rules. The
- * worktree-prefix bug that prompted Story #1891 is the proof: each
- * refresh path had to remember to strip `.worktrees/<workspace>/` on its
- * own, and the maintainability path forgot.
- *
- * `write({ kind, rows, components, kernelVersion?, generatedAt? })` is
- * the single funnel:
- *
- *   1. Look up the per-kind module via the kernel registry. The module
- *      declares the `keyField`, `projectRow`, `sortRows`, `rollup`, and
- *      `kernelVersion()` functions.
- *   2. Run every row through `projectRow` — that's where the path is
- *      canonicalised via `path-canon.canonicalise()`. After projection,
- *      the writer asserts every key field is already canonical
- *      (`path-canon.assertCanonical()`), refusing to silently rewrite
- *      identity.
- *   3. Sort the rows for deterministic on-disk diffs.
- *   4. Compute the per-component rollup (always including `*`).
- *   5. Stamp the envelope via `buildEnvelope` — `$schema`, `kernelVersion`,
- *      `generatedAt`.
- *   6. Validate the envelope via `assertEnvelope` (AJV against the per-kind
- *      schema).
- *   7. Return the envelope object. Callers serialise via `writeFile()`
- *      (separate seam so tests can round-trip without touching disk).
- *
- * `writeFile(absPath, envelope)` is the serialise + flush seam. It
- * stringifies the envelope with two-space indent, appends a trailing
- * newline, creates the parent directory, and writes atomically (write to
- * `<path>.tmp` then `rename` — `rename` is atomic on every platform we
- * support).
+ * Shared baseline writer, the single funnel for envelope assembly
+ * (`write`: project, canonical-assert, merge, stabilise, sort, rollup, stamp,
+ * validate) and serialisation (`writeFile`: atomic tmp + rename).
  *
  * @module lib/baselines/writer
  */
@@ -48,42 +14,11 @@ import { currentKernelVersion, getKindModule } from './kernel.js';
 import { assertCanonical } from './path-canon.js';
 
 /**
- * Assemble + validate a baseline envelope. Returns the envelope object
- * (no disk I/O). Callers feed the result into `writeFile()` when they're
- * ready to persist.
- *
- * Story #1964 (s-stability-epsilon) added the optional `prior` and
- * `epsilon` parameters. When both are present, the writer calls the
- * per-kind `applyEpsilon(prior, regenerated, epsilon)` stabilizer
- * **after** projection but **before** sort/rollup/serialise. Sub-epsilon
- * row deltas resolve to the prior bytes, so env variance never rewrites
- * the on-disk envelope. When either is absent (`undefined`), behaviour is
- * unchanged from the pre-#1964 contract — this is regression-fail-safe by
- * design so existing call sites stay untouched.
- *
- * Story #1974 (s-diff-scoped-writes) added the optional `scope` parameter.
- * When `scope` is present *and* `prior` is supplied, the writer calls the
- * per-kind `mergeRows(prior, projected, scope)` filter **after** projection
- * but **before** `applyEpsilon`. The composition is intentional: scope-
- * filter first (preserve out-of-scope prior rows verbatim), then stabilise
- * the in-scope rows against the same prior under epsilon. The merged result
- * is sorted, rolled up, and serialised exactly as before. When `scope` is
- * absent (or `prior` is absent), behaviour is unchanged from the pre-#1974
- * contract — also regression-fail-safe.
- *
- * `prior` MUST be an array of rows already in canonical (per-kind
- * `projectRow`) shape — the on-disk baseline format is canonical
- * end-to-end, and the writer no longer re-projects prior rows on entry.
- *
- * Story #2135 (Task #2146) added the structural-equality short-circuit on
- * top of `prior`. When a `prior` envelope (or `priorEnvelope`) is supplied
- * and the projected `rows + rollup` deep-equal the prior's `rows + rollup`,
- * the writer returns the prior envelope unchanged — same `generatedAt`,
- * same kernelVersion, same byte payload. Without this guard every
- * auto-refresh that ran on a no-op Story would stamp a fresh
- * `generatedAt` and surface a spurious one-line diff. The short-circuit
- * is the semantic replacement for the legacy byte-equality compare that
- * lived in `baseline-snapshot.js`.
+ * Assemble and validate an envelope (no I/O). With `scope`, out-of-scope
+ * `prior` rows are preserved first; with `epsilon`, sub-epsilon deltas then
+ * resolve to prior bytes. `prior` rows must already be canonical. When rows
+ * and rollup deep-equal the prior envelope, the prior is returned unchanged
+ * so a no-op refresh leaves no `generatedAt` diff.
  *
  * @param {{
  *   kind: string,
@@ -127,11 +62,7 @@ export function write({
     }
   });
 
-  // Defensive: assert every key field on the projected rows is canonical.
-  // The per-kind `projectRow` already funnels paths through `canonicalise`,
-  // but the assertion catches a future per-kind module that forgets — and
-  // catches absolute paths in inputs that the canonicaliser would also
-  // throw on (we surface a writer-scoped error pointing at the row).
+  // Catches a kind module whose `projectRow` forgets to canonicalise.
   if (mod.keyField === 'path') {
     projected.forEach((row, idx) => {
       try {
@@ -150,30 +81,19 @@ export function write({
   const sortedRows = mod.sortRows(stabilised);
   const rollup = mod.rollup(sortedRows, components ?? []);
 
-  // The rollup() implementations always seed `*` from `aggregate()`, but
-  // the AC pins this explicitly: the envelope ALWAYS carries `*` even
-  // when `components` is undefined or empty. Belt-and-braces.
   if (!Object.hasOwn(rollup, '*')) {
     throw new Error(
       `writer.write: ${kind} rollup is missing the required "*" key`,
     );
   }
 
-  // Story #2135 / Task #2146 — structural-equality short-circuit. When the
-  // caller supplies a `priorEnvelope` (or, for backwards-compatibility, the
-  // bare `prior` array is itself a full envelope object), and the projected
-  // rows + rollup deep-equal what's on the prior, return the prior envelope
-  // unchanged. This is the semantic replacement for the byte-equality
-  // compare in `baseline-snapshot.js` and is what makes a no-op auto-refresh
-  // produce a zero-byte baseline diff.
   const priorEnv = resolvePriorEnvelope(priorEnvelope, prior);
   if (
     priorEnv &&
     deepEqual(sortedRows, priorEnv.rows) &&
     deepEqual(rollup, priorEnv.rollup)
   ) {
-    // Re-validate defensively before returning so a caller cannot smuggle
-    // an invalid envelope through the short-circuit.
+    // No smuggling an invalid envelope through the short-circuit.
     assertEnvelope(priorEnv);
     return priorEnv;
   }
@@ -191,14 +111,7 @@ export function write({
   return envelope;
 }
 
-/**
- * Resolve the prior envelope used by the structural-equality short-circuit.
- * Accepts either an explicit `priorEnvelope` (preferred) or, for backwards
- * compatibility, recognises when `prior` is itself a full envelope object
- * carrying `rows` + `rollup` rather than a bare rows array. Returns null
- * when neither yields a usable envelope — the short-circuit is opt-in by
- * design.
- */
+/** `priorEnvelope`, else `prior` when it is a whole envelope, else null. */
 function resolvePriorEnvelope(priorEnvelope, prior) {
   if (
     priorEnvelope &&
@@ -224,21 +137,8 @@ function resolvePriorEnvelope(priorEnvelope, prior) {
 }
 
 /**
- * Serialise an envelope to `absPath`. Deterministic: two-space indent,
- * trailing newline, sorted keys for the top-level envelope keys (rows are
- * already sorted by the per-kind module's `sortRows`). Atomic: writes to
- * `<absPath>.tmp` then `rename`s onto the destination so a crash mid-write
- * never leaves a half-flushed envelope on disk.
- *
- * Story #2135 / Task #2146 — the optional `fsImpl` seam lets tests inject
- * a virtual filesystem (or an in-memory recorder) the way the legacy
- * saver helpers allowed. Production callers omit it and fall through to
- * `node:fs`. The seam covers `mkdirSync`, `writeFileSync`, and
- * `renameSync` — the three calls this function actually makes — so a mock
- * that exposes a subset of `fs` works without leaking real disk I/O.
- *
- * Backwards-compatible: two-argument callers (`writeFile(abs, env)`)
- * continue to work unchanged.
+ * Serialise deterministically (fixed top-level key order, two-space indent,
+ * trailing newline) and atomically (tmp + rename).
  *
  * @param {string} absPath
  * @param {object} envelope
@@ -251,29 +151,13 @@ export function writeFile(absPath, envelope, opts = {}) {
       `writer.writeFile: absPath must be an absolute path (got ${JSON.stringify(absPath)})`,
     );
   }
-  // Re-validate at the seam — a caller might mutate the envelope between
-  // `write()` and `writeFile()`.
+  // The caller may have mutated the envelope since `write()`.
   assertEnvelope(envelope);
 
   const fsImpl = opts?.fsImpl ? opts.fsImpl : fs;
 
-  // Canonical key order on the top-level envelope keeps diffs stable
-  // across runs and platforms. Per-kind row keys retain their natural
-  // declaration order; the row sort is done by `sortRows()`.
-  //
-  // The projection is deliberately explicit (Story #4775): a per-kind envelope
-  // stamp reaches disk only if it is named here, so an unlisted one is present
-  // in memory, passes validation, and is absent from the file it exists to
-  // protect. That is not hypothetical — Story #4901 added `provenanceStamped`
-  // to `envelopeExtras()` and not to this list, and every baseline written
-  // between then and Story #4969 lost it at this boundary, leaving the
-  // `provenance-unstamped` axis reading an absence its own writer had
-  // manufactured.
-  //
-  // A stamp a kind does not set is simply `undefined`, and `JSON.stringify`
-  // omits an undefined-valued key — so naming all three unconditionally emits
-  // exactly what the per-key `undefined` guards used to, with nothing to
-  // half-apply when the next stamp is added.
+  // A kind's envelope stamp reaches disk only if named here — add every new
+  // `envelopeExtras()` key. Unset stamps are undefined and JSON omits them.
   const canonical = {
     $schema: envelope.$schema,
     kernelVersion: envelope.kernelVersion,
@@ -292,29 +176,12 @@ export function writeFile(absPath, envelope, opts = {}) {
   return absPath;
 }
 
-/**
- * Story #1974 — s-diff-scoped-writes scope-merge dispatch. When `scope` is
- * present, defer to the per-kind `mergeRows(prior, projected, scope)` to
- * preserve out-of-scope prior rows verbatim. Returns `projected` unchanged
- * when `scope` is omitted, when the kind doesn't ship the merger
- * (forward-compatible), or when `prior` is absent (nothing to preserve).
- */
 function scopeMergeRows(mod, projected, prior, scope) {
   if (scope === undefined || scope === null) return projected;
   if (typeof mod.mergeRows !== 'function') return projected;
-  // mergeRows treats null/undefined/empty prior as "no preservation needed"
-  // and returns projected verbatim — that branch is covered upstream and
-  // here for symmetry.
   return mod.mergeRows(prior ?? [], projected, scope);
 }
 
-/**
- * Story #1964 — s-stability-epsilon stabilizer dispatch. When both
- * `prior` and `epsilon` are present, fold sub-epsilon row deltas back to
- * the prior bytes via the per-kind `applyEpsilon`. Returns `projected`
- * unchanged when either is omitted, or when the kind doesn't ship the
- * stabilizer (forward-compatible).
- */
 function stabiliseRows(mod, projected, prior, epsilon) {
   if (prior === undefined || epsilon === undefined) return projected;
   if (!Array.isArray(prior)) {

package/.agents/scripts/lib/bdd-runner-detect.js

@@ -1,40 +1,10 @@
 /**
- * BDD runner detection + pending-tag verification (Epic #2001 Story #2094
- * Task #2103; workspace-aware extension from Story #2956).
- *
- * Used by `buildAuthoringContext` (the `plan-context.js` envelope) to decide whether the
- * acceptance-table section should plan **features-first** Story ordering (a real
- * pending-tag is available, so the features-first Story can ship `.feature`
- * files marked `@pending` / `@skip` ahead of the implementation Stories) or
- * fall back to **dependencies-first** ordering (no pending tag → cannot
- * suspend an unimplemented scenario without a permanent red, so Stories run
- * in dependency order and the AC reconciler defers).
- *
- * The verification is **static**: we inspect `package.json` for a known BDD
- * runner dependency, and consult a small lookup table of which runners
- * support which pending/skip tag. We do not boot the runner. This keeps
- * `/mandrel-plan` Phase 7 hermetic and offline.
- *
- * **Workspace awareness (Story #2956).** In a pnpm / npm / yarn monorepo the
- * BDD runner is rarely a root devDependency — it lives in the workspace
- * package that owns the e2e suite (e.g. `apps/web/package.json`). The
- * detector reads the root `package.json` first and then unions in
- * dependencies from every declared workspace package, so an `apps/*` shaped
- * monorepo no longer falls back to "no runner detected" when the runner
- * sits one level down. Workspace declarations are read from
- * `pnpm-workspace.yaml` (`packages:` field) or the root `package.json`
- * `workspaces` field (array or `{ packages: [] }` object form).
- * Preferred-first ordering is preserved by iterating
- * `BDD_RUNNER_TAG_TABLE` against the union of all collected deps — the
- * first runner present in *any* package wins.
- *
- * Output shape (returned to the planner-context envelope):
- *
- *   { runner: 'cucumber-js',         pendingTag: '@skip',     supported: true,  fallback: false }
- *   { runner: 'playwright-bdd',      pendingTag: '@skip',     supported: true,  fallback: false }
- *   { runner: '@cucumber/cucumber',  pendingTag: '@skip',     supported: true,  fallback: false }
- *   { runner: null,                  pendingTag: null,        supported: false, fallback: true,
- *     reason: 'no-bdd-runner-detected' }
+ * Static BDD runner detection: does the project ship a runner with a
+ * pending/skip tag? If so the planner can order features-first (scenarios
+ * land `@skip` ahead of the implementation); if not, dependencies-first,
+ * since an unimplemented scenario would be a permanent red. Reads the root
+ * `package.json` plus every workspace package (runners usually live in one),
+ * never boots the runner.
  */
 
 import { existsSync, readdirSync, readFileSync, statSync } from 'node:fs';
@@ -45,13 +15,7 @@ import picomatch from 'picomatch';
 
 import { Logger } from './Logger.js';
 
-/**
- * Known BDD runner package names → pending-tag string the runner honours.
- *
- * Keys MUST match the literal npm package name as it appears in
- * `dependencies` or `devDependencies`. Order is preferred-first: if multiple
- * runners are present (rare), the first match wins.
- */
+/** npm package name → pending tag. Preferred-first: the first match wins. */
 export const BDD_RUNNER_TAG_TABLE = Object.freeze({
   'playwright-bdd': '@skip',
   '@cucumber/cucumber': '@skip',
@@ -60,21 +24,8 @@ export const BDD_RUNNER_TAG_TABLE = Object.freeze({
 });
 
 /**
- * Shared set of tag tokens that mean "this scenario does not yet satisfy
- * its AC — treat coverage as pending, not satisfied." Sourced from every
- * pending-tag value in `BDD_RUNNER_TAG_TABLE` (today `@skip` / `skip`).
- *
- * Both the prefixed (`@skip`) and the unprefixed (`skip`) form of each
- * tag are included so consumers can look up either the raw tag string
- * (as it appears in a `.feature` file) or the normalized token form
- * produced by tag-block parsers that strip the leading `@`.
- *
- * Consumers:
- *   - `acceptance-spec-reconciler.classifyCoverage` — membership check
- *     against parsed scenario tag sets.
- *   - Contract tests that walk `BDD_RUNNER_TAG_TABLE` and assert each
- *     pending tag is registered here, guarding against drift when a
- *     new runner is added.
+ * Tags meaning "coverage pending, not satisfied", in both `@skip` and
+ * `skip` forms (parsers may strip the `@`).
  */
 export const PENDING_TAGS = Object.freeze(
   new Set(
@@ -85,11 +36,6 @@ export const PENDING_TAGS = Object.freeze(
   ),
 );
 
-/**
- * Result returned when no supported BDD runner is detected. The acceptance
- * spec body will print "Fallback: dependencies-first ordering" and Phase 8
- * decomposer ordering reverts to topological dependency order.
- */
 const FALLBACK = Object.freeze({
   runner: null,
   pendingTag: null,
@@ -99,19 +45,11 @@ const FALLBACK = Object.freeze({
 });
 
 /**
- * Verify which BDD runner (if any) the project ships and whether it
- * supports a pending/skip tag. Reads the root `package.json` and (when
- * declared) every workspace `package.json` so monorepos that house the
- * runner in `apps/<name>` or `packages/<name>` resolve correctly.
- *
  * @param {object} [opts]
- * @param {string} [opts.cwd] - Project root holding `package.json`.
- * @param {(p: string) => Promise<string>} [opts.readPkg] - Override for
- *   tests; receives the resolved absolute path to a `package.json`.
+ * @param {string} [opts.cwd]
+ * @param {(p: string) => Promise<string>} [opts.readPkg] Test seam.
  * @param {(ctx: { cwd: string, rootPkg: object, readPkg: Function }) => Promise<string[]>} [opts.listWorkspacePkgPaths]
- *   Override for tests; returns absolute paths to workspace `package.json`
- *   files. Defaults to scanning `pnpm-workspace.yaml` then the root
- *   `package.json` `workspaces` field and expanding their glob patterns.
+ *   Test seam.
  * @returns {Promise<{ runner: string|null, pendingTag: string|null, supported: boolean, fallback: boolean, reason?: string }>}
  */
 export async function verifyBddRunnerPendingTag(opts = {}) {
@@ -153,7 +91,6 @@ export async function verifyBddRunnerPendingTag(opts = {}) {
       logger,
     });
   } catch (err) {
-    // Workspace discovery failure is non-fatal: degrade to root-only scan.
     logger.debug(
       `[bdd-runner-detect] workspace discovery failed for ${cwd}: ${err?.message ?? err}`,
     );
@@ -201,18 +138,8 @@ export async function verifyBddRunnerPendingTag(opts = {}) {
 }
 
 /**
- * Default workspace discovery: read `pnpm-workspace.yaml` (`packages:`
- * field) then the root `package.json` `workspaces` field, expand the
- * glob patterns against `cwd`, and return the resulting workspace
- * `package.json` absolute paths.
- *
- * Returns `[]` (silent) on any of:
- *   - no `pnpm-workspace.yaml` and no `workspaces` field
- *   - YAML parse failure
- *   - patterns matching no on-disk directories
- *
- * Failures here are non-fatal so a malformed workspace file can never
- * block planner-context emission.
+ * Workspace `package.json` paths from `pnpm-workspace.yaml`, else the root
+ * `workspaces` field. Non-fatal: `[]` on any failure.
  *
  * @returns {Promise<string[]>}
  */
@@ -233,7 +160,6 @@ function readWorkspacePatterns(cwd, rootPkg, logger) {
         return parsed.packages.filter((p) => typeof p === 'string');
       }
     } catch (err) {
-      // unparseable yaml → fall through to package.json workspaces
       logger.debug(
         `[bdd-runner-detect] pnpm-workspace.yaml parse failed for ${yamlPath}: ${err?.message ?? err}`,
       );
@@ -253,14 +179,7 @@ function readWorkspacePatterns(cwd, rootPkg, logger) {
   return [];
 }
 
-/**
- * Expand a list of workspace glob patterns into absolute paths to each
- * matching `package.json`. Handles:
- *   - literal directory entries (no glob chars): `apps/web`
- *   - single-segment globs: `apps/*`, `packages/*`
- *   - recursive globs: `packages/**`
- *   - exclusion patterns prefixed with `!` (pnpm/npm convention)
- */
+/** Handles literal dirs, `*` and `**` globs, and `!` exclusions. */
 function expandWorkspacePatterns(cwd, patterns, logger) {
   const includes = patterns.filter((p) => !p.startsWith('!'));
   const excludes = patterns
@@ -366,13 +285,7 @@ function existsSyncDir(p, logger) {
   }
 }
 
-/**
- * Canonical directories a project might use to house `.feature` files.
- * Probed in order; the first existing directory wins. The list is
- * deliberately short — projects that house features elsewhere will need
- * to land an explicit config surface for it, which Story #2637 leaves
- * out of scope.
- */
+/** Canonical `.feature` directories; there is no config key for others. */
 const CANONICAL_FEATURE_ROOTS = Object.freeze([
   'tests/features',
   'features',
@@ -380,17 +293,10 @@ const CANONICAL_FEATURE_ROOTS = Object.freeze([
 ]);
 
 /**
- * Resolve the project's BDD feature roots — absolute paths to every
- * canonical directory that exists under `cwd`. Returns an empty array
- * when no feature directory is present (the project has not adopted
- * BDD), so downstream scanners can degrade silently to "no scenarios".
- *
- * Story #2637 — the Phase 7 BDD-scenario scanner consumes this so the
- * planner can cross-reference acceptance criteria against existing
- * scenarios without introducing a new config key.
+ * Existing canonical feature roots; `[]` when the project has not adopted BDD.
  *
  * @param {{ cwd?: string }} [opts]
- * @returns {string[]} Absolute paths to existing feature roots.
+ * @returns {string[]}
  */
 export function resolveFeatureRoots(opts = {}) {
   const cwd = opts.cwd ?? process.cwd();
@@ -403,7 +309,6 @@ export function resolveFeatureRoots(opts = {}) {
         roots.push(abs);
       }
     } catch (err) {
-      // Unreadable path → treat as absent. Non-blocking by design.
       logger.debug(
         `[bdd-runner-detect] feature-root probe failed for ${abs}: ${err?.message ?? err}`,
       );