mandrel 2.25.0 → 2.26.0

package/.agents/scripts/lib/observability/source-classifier.js

@@ -17,6 +17,9 @@
  *       - `.agentrc.json`
  *       - `.claude/`
  *       - `node .agents/scripts/`
+ *     …or (Story #4916) names one of the CLI entry points shipped at the
+ *     top level of `.agents/scripts/` by **bare basename**, so recognition
+ *     does not depend on how the caller spelled the reference.
  *   - Anything else (or empty input) defaults to `"consumer"`. The default
  *     is intentional — most friction comes from consumer code touching
  *     framework tooling, and we'd rather under-tag than mis-route a
@@ -47,6 +50,133 @@ const FRAMEWORK_PREFIXES = Object.freeze([
   'node .agents/scripts/',
 ]);
 
+/**
+ * Basenames of the CLI entry points shipped at the top level of
+ * `.agents/scripts/` (Story #4916).
+ *
+ * The prefix scan above recognises a framework script only when the caller
+ * spelled a path — `node .agents/scripts/acceptance-eval.js` classifies
+ * `framework`, while the same script named bare (`acceptance-eval.js --story
+ * 4901`) matched no prefix and fell through to `consumer`, so a real framework
+ * defect was routed as consumer-actionable and discarded. Recognition must not
+ * depend on how the caller spelled the reference.
+ *
+ * Kept as **static data**, not a directory read: `classifySignalSource` is
+ * called once per signal and MUST stay pure — no filesystem I/O at classify
+ * time. The sync test in
+ * `tests/lib/observability/source-classifier.test.js` reads the real directory
+ * and fails when a script is added, renamed, or removed without this list
+ * being updated, so the set cannot go stale and silently restore the blind
+ * spot.
+ *
+ * Scoped to the top level deliberately: those are the entry points a command
+ * line names. Library modules under `.agents/scripts/lib/` carry generic
+ * basenames (`index.js`, `config.js`) that a consumer command could plausibly
+ * name, and widening to them would trade one mis-route for another.
+ *
+ * @type {readonly string[]}
+ */
+const FRAMEWORK_SCRIPT_BASENAMES = Object.freeze([
+  'acceptance-eval.js',
+  'agents-bootstrap-github.js',
+  'apply-quality-bootstrap.js',
+  'audit-baselines.js',
+  'audit-labels-bootstrap.js',
+  'audit-to-stories.js',
+  'boot-sweep.js',
+  'bootstrap.js',
+  'check-action-pinning.js',
+  'check-arch-cycles.js',
+  'check-baseline-drift.js',
+  'check-baselines.js',
+  'check-context-budget.js',
+  'check-cyclomatic.js',
+  'check-dead-exports.js',
+  'check-doc-links.js',
+  'check-gherkin-placeholders.js',
+  'check-lifecycle-doc-drift.js',
+  'check-lifecycle-lint.js',
+  'check-schema-references.js',
+  'check-test-temp-hygiene.js',
+  'check-windows-git-perf.js',
+  'check-workflow-citations.js',
+  'check-workflow-cli-lint.js',
+  'check-workflow-timeouts.js',
+  'cleanup-repo-test-temp.js',
+  'coverage-capture.js',
+  'deliver-light.js',
+  'deliver-recover.js',
+  'diagnose-friction.js',
+  'diagnose.js',
+  'drain-pending-cleanup.js',
+  'evidence-gate.js',
+  'generate-config-docs.js',
+  'generate-lens-checklists.js',
+  'generate-lifecycle-docs.js',
+  'generate-skills-index.js',
+  'generate-workflows-doc.js',
+  'git-cleanup.js',
+  'install-matrix-assert.js',
+  'lint-baseline.js',
+  'lint-issue-body.js',
+  'lint-label-vocabulary.js',
+  'mandrel-update-preflight.js',
+  'nav-registry-diff.js',
+  'notify.js',
+  'plan-context.js',
+  'plan-critics.js',
+  'plan-persist.js',
+  'plan-run-epilogue.js',
+  'post-structured-comment.js',
+  'pr-watch-with-update.js',
+  'provision-git-hooks.js',
+  'quality-preview.js',
+  'quality-watch.js',
+  'resolve-doc-tiers.js',
+  'resolve-stories.js',
+  'resync-status-column.js',
+  'run-coverage.js',
+  'run-lint.js',
+  'run-test-profile.js',
+  'run-tests.js',
+  'run-verify.js',
+  'signals-view.js',
+  'single-story-close.js',
+  'single-story-confirm-merge.js',
+  'single-story-init.js',
+  'stories-wave-tick.js',
+  'story-plan.js',
+  'sync-agentrc.js',
+  'sync-branch-from-base.js',
+  'sync-claude-agents.js',
+  'sync-claude-commands.js',
+  'test-isolate.js',
+  'test-wrapper.js',
+  'update-coverage-baseline.js',
+  'update-crap-baseline.js',
+  'update-duplication-baseline.js',
+  'update-maintainability-baseline.js',
+  'update-ticket-state.js',
+  'validate-docs-freshness.js',
+  'validate-skills.js',
+]);
+
+/**
+ * Membership index over {@link FRAMEWORK_SCRIPT_BASENAMES}, built once at
+ * module load so the per-signal scan is a hash lookup.
+ *
+ * @type {ReadonlySet<string>}
+ */
+const FRAMEWORK_SCRIPT_BASENAME_SET = new Set(FRAMEWORK_SCRIPT_BASENAMES);
+
+/**
+ * Characters a shell-ish command line can wrap a token in. Stripped from both
+ * ends before the membership test so `"acceptance-eval.js",` still resolves.
+ *
+ * @type {RegExp}
+ */
+const TOKEN_TRIM = /^[\s'"`(,;:]+|[\s'"`),;:]+$/g;
+
 /**
  * Normalise a value to a string for prefix scanning. Anything that is not
  * a string (undefined, null, numbers, objects) becomes the empty string,
@@ -78,6 +208,44 @@ function containsFrameworkPrefix(haystack) {
   return false;
 }
 
+/**
+ * Return true when `haystack` names a top-level framework script by **bare
+ * basename** — no path segment at all (Story #4916).
+ *
+ * Whitespace-tokenised and matched whole: only a token that *equals* a known
+ * basename counts. A token carrying any path segment is deliberately left to
+ * {@link containsFrameworkPrefix} — `./tools/notify.js` is the consumer's own
+ * script and must stay `consumer`, while `.agents/scripts/notify.js` already
+ * matches a prefix. Likewise `my-notify.js` is not `notify.js`.
+ *
+ * @param {string} haystack
+ * @returns {boolean}
+ */
+function containsFrameworkScriptBasename(haystack) {
+  if (haystack.length === 0) return false;
+  for (const rawToken of haystack.split(/\s+/)) {
+    const token = rawToken.replace(TOKEN_TRIM, '');
+    if (FRAMEWORK_SCRIPT_BASENAME_SET.has(token)) return true;
+  }
+  return false;
+}
+
+/**
+ * True when `haystack` names the framework's own surface, by either
+ * recognition route: a path prefix, or a bare framework-script basename.
+ *
+ * Purely additive over {@link containsFrameworkPrefix} — every string that
+ * matched a prefix still matches here, so widening can only ever move a
+ * classification from `consumer` to `framework`, never the reverse.
+ *
+ * @param {string} haystack
+ * @returns {boolean}
+ */
+function namesFrameworkSurface(haystack) {
+  if (containsFrameworkPrefix(haystack)) return true;
+  return containsFrameworkScriptBasename(haystack);
+}
+
 /**
  * Classify a friction signal as `"framework"` or `"consumer"`.
  *
@@ -92,6 +260,10 @@ function containsFrameworkPrefix(haystack) {
  * `node .agents/scripts/single-story-init.js` — that's framework friction even
  * though the failing test path lives under the consumer.
  *
+ * Either input matches on a framework path prefix **or** on a bare framework
+ * script basename (Story #4916), so `single-story-close.js --story 4906` is
+ * recognised exactly like its fully-pathed spelling.
+ *
  * @param {unknown} failingPath  The path of the file or directory the
  *                               signal blames (e.g. `"tests/foo.test.js"`).
  * @param {unknown} command       The command line the signal blames
@@ -101,8 +273,8 @@ function containsFrameworkPrefix(haystack) {
 export function classifyPathSource(failingPath, command) {
   const path = toScanString(failingPath);
   const cmd = toScanString(command);
-  if (containsFrameworkPrefix(path)) return 'framework';
-  if (containsFrameworkPrefix(cmd)) return 'framework';
+  if (namesFrameworkSurface(path)) return 'framework';
+  if (namesFrameworkSurface(cmd)) return 'framework';
   return 'consumer';
 }
 
@@ -229,5 +401,6 @@ export function classifySignalSource(record) {
 
 export const __testing = Object.freeze({
   FRAMEWORK_PREFIXES,
+  FRAMEWORK_SCRIPT_BASENAMES,
   TOOL_DEGRADED_CATEGORY,
 });

package/.agents/scripts/lib/orchestration/ceremony-routing.js

@@ -78,7 +78,7 @@
  * @typedef {'fresh'|'inline'} CeremonyMode
  * @typedef {'fresh-critic'|'inline-self-eval'} VerdictOwner
  * @typedef {import('./review-depth.js').ChangeLevel} ChangeLevel
- * @typedef {'minimal'|'standard'|'strict'} CeremonyProfile
+ * @typedef {(typeof CEREMONY_PROFILES)[number]} CeremonyProfile
  */
 
 /**
@@ -93,12 +93,18 @@ export function verdictOwnerForMode(mode) {
   return mode === 'fresh' ? 'fresh-critic' : 'inline-self-eval';
 }
 
-/** @type {readonly CeremonyProfile[]} */
-export const CEREMONY_PROFILES = Object.freeze([
-  'minimal',
-  'standard',
-  'strict',
-]);
+/**
+ * The ceremony-profile vocabulary — the **single** place the three profile
+ * names are written. `normalizeCeremonyProfile` is its reader and the
+ * `CeremonyProfile` typedef is derived from it, so adding a profile is a
+ * one-line change here (Story #4926).
+ *
+ * @type {readonly ['minimal', 'standard', 'strict']}
+ */
+const CEREMONY_PROFILES = Object.freeze(['minimal', 'standard', 'strict']);
+
+/** The profile an absent or unrecognized value degrades to. */
+const DEFAULT_CEREMONY_PROFILE = 'standard';
 
 /**
  * Normalize an operator/config ceremony profile. Unknown values degrade to
@@ -107,11 +113,10 @@ export const CEREMONY_PROFILES = Object.freeze([
  * @param {unknown} value
  * @returns {CeremonyProfile}
  */
-export function normalizeCeremonyProfile(value) {
-  if (value === 'minimal' || value === 'standard' || value === 'strict') {
-    return value;
-  }
-  return 'standard';
+function normalizeCeremonyProfile(value) {
+  return CEREMONY_PROFILES.includes(/** @type {CeremonyProfile} */ (value))
+    ? /** @type {CeremonyProfile} */ (value)
+    : DEFAULT_CEREMONY_PROFILE;
 }
 
 /**

package/.agents/scripts/lib/orchestration/check-baselines/phases/compare.js

@@ -9,6 +9,7 @@
  * @module lib/orchestration/check-baselines/phases/compare
  */
 
+import { EXIT_CONFIG } from '../../../baselines/exit-codes.js';
 import { readBaseFromGit } from '../../../baselines/git-base.js';
 import { getKindModule } from '../../../baselines/kernel.js';
 import { resolveScope } from '../../../baselines/scope.js';
@@ -30,10 +31,8 @@ export function resolveDispatchScope({ kind, quality, env }) {
     kind,
     configScope: cfg.scope,
     configRef: cfg.diffRef,
-    cliFlags: {
-      envScope: env?.BASELINE_SCOPE,
-      envRef: env?.BASELINE_REF,
-    },
+    envScope: env?.BASELINE_SCOPE,
+    envRef: env?.BASELINE_REF,
   });
 }
 
@@ -41,13 +40,44 @@ function emptyCompareResult(baseRef) {
   return { baseRef, baseRead: false };
 }
 
+/**
+ * Story #4914 — a base read that FAILS is not a base that is ABSENT.
+ *
+ * `readBaseFromGit` already draws that line itself: it returns `null` only
+ * for git exit 128 ("path does not exist in this revision") and throws on
+ * everything else. Swallowing the throw conflated the two, so a broken read
+ * silently emptied the whole head-vs-base arm — regressions AND additions —
+ * while the floors arm kept the run at exit 0. A gate that fails open is
+ * worse than no gate, because it is trusted.
+ *
+ * So the read failure fails CLOSED as `EXIT_CONFIG` (3) — "the gate could
+ * not even start", the same code `assertFloorAxesExist` uses for a
+ * misconfigured floor axis. `check-baselines.js#main` maps any throw out of
+ * the pipeline onto that code.
+ */
+function buildBaseReadError({ kind, ref, file, cause }) {
+  const detail = cause?.message ?? String(cause);
+  const err = new Error(
+    `[check-baselines:${kind}] could not read the base baseline at ` +
+      `${ref}:${file} — the head-vs-base compare arm cannot run, so the gate ` +
+      `fails closed rather than reporting zero regressions: ${detail}`,
+  );
+  err.code = 'EXIT_CONFIG';
+  err.exitCode = EXIT_CONFIG;
+  err.kind = kind;
+  err.baseRef = ref;
+  err.baselinePath = file;
+  err.cause = cause;
+  return err;
+}
+
 function readBaseBaselinePayload(scope, kind, gateBlock, cwd) {
   const rel = baselineRelativePath(kind, gateBlock);
   let raw;
   try {
     raw = readBaseFromGit(scope.ref, rel, { cwd });
-  } catch {
-    return null;
+  } catch (cause) {
+    throw buildBaseReadError({ kind, ref: scope.ref, file: rel, cause });
   }
   if (raw === null) return null;
   try {

package/.agents/scripts/lib/orchestration/check-baselines/phases/evaluate.js

@@ -206,6 +206,11 @@ function buildGateReport({
     additions: compareOutput.additions ?? [],
     regressionCount: compareOutput.regressions.length,
     baseRef: cmp.baseRef ?? null,
+    // Story #4914 — the compare arm's read status was internal to compare.js,
+    // which is why a dead compare arm looked byte-identical to a clean run.
+    // Surfacing it makes "the head-vs-base arm did not run" diagnosable from
+    // the JSON report alone.
+    baseRead: cmp.baseRead === true,
     generatedAt: baseline.generatedAt,
     acknowledged,
   };

package/.agents/scripts/lib/orchestration/check-baselines/phases/floors.js

@@ -10,7 +10,18 @@
 
 import { EXIT_CONFIG } from '../../../baselines/exit-codes.js';
 
-function axisDirection(kind, axis) {
+/**
+ * Which way a floor axis is compared: `gte` means the measured value must be
+ * at or above the floor, `lte` at or below it. Exported (Story #4902) so the
+ * baseline hotspot engine reports floor headroom with the same polarity the
+ * gate enforces — a second copy of this table would let the two disagree
+ * about which direction is "better" for a given axis.
+ *
+ * @param {string} kind
+ * @param {string} axis
+ * @returns {'gte' | 'lte'}
+ */
+export function axisDirection(kind, axis) {
   if (kind === 'lint') return 'lte';
   if (kind === 'crap') return 'lte';
   if (kind === 'bundle-size') return 'lte';

package/.agents/scripts/lib/orchestration/check-baselines/phases/report.js

@@ -27,8 +27,15 @@ function formatGateLine(g) {
     ? ''
     : ` [kernel drift ${g.kernelBaseline} → ${g.kernelCurrent}]`;
   const baseRef = g.baseRef ? ` [baseRef=${g.baseRef}]` : '';
+  // Story #4914 — a compare arm that never read its base reports zero
+  // regressions and zero additions, which is indistinguishable from a clean
+  // run unless the text report says so out loud.
+  const baseRead =
+    g.baseRef && g.baseRead === false
+      ? ' [baseRead=false — compare skipped]'
+      : '';
   const ack = g.acknowledged ? ' [ACKNOWLEDGED — this run only]' : '';
-  return `  - ${g.kind}: ${status}${drift}${baseRef}${ack}`;
+  return `  - ${g.kind}: ${status}${drift}${baseRef}${baseRead}${ack}`;
 }
 
 function formatViolationLine(component, v) {

package/.agents/scripts/lib/orchestration/git-cleanup/phases/phase-drivers.js

@@ -26,8 +26,8 @@ import { buildGlobFilter } from './filters.js';
 import { promptStashDecision, promptYesNo } from './prompts.js';
 import { executePrune } from './prune.js';
 import {
+  renderCandidateList,
   renderDeferredLine,
-  renderDryRun,
   renderExecutionLine,
   renderExecutionSummary,
   renderPruneLine,
@@ -41,8 +41,9 @@ import {
 const TAG = '[git-cleanup]';
 
 /* node:coverage ignore next */
-function emitDryRunHuman(plan, baseBranch) {
-  for (const line of renderDryRun(plan, { baseBranch })) Logger.info(line);
+function emitCandidateList(plan, opts, baseBranch) {
+  for (const l of renderCandidateList({ plan, opts, baseBranch }))
+    Logger.info(l);
 }
 
 /* node:coverage ignore next */
@@ -291,7 +292,7 @@ export async function runBranchPhase(opts, cwd, baseBranch) {
     filter,
     includeRemoteOnly: true,
   });
-  emitDryRunHuman(plan, baseBranch);
+  emitCandidateList(plan, opts, baseBranch);
   const action = decideBranchPhase({ plan, opts, cwd });
   if (action.kind === 'prompt-then-execute') {
     const go = await promptYesNo(action.promptMessage);
@@ -375,7 +376,11 @@ export async function executeStashPhase(action) {
   );
 }
 
-/* node:coverage ignore next */
+// Story #4922 — the `node:coverage ignore next` directive that used to sit
+// here is gone. It was never justified: `runStashPhase` is drivable end to
+// end (planStashes degrades to an empty list outside a repo, and the
+// decide/execute pair below is pure given an allowlist), so the directive
+// only hid a sequencer nothing exercised.
 export async function runStashPhase(opts, cwd) {
   Logger.info(`${TAG} ── phase: stashes ──`);
   const { stashes } = planStashes({ cwd });

package/.agents/scripts/lib/orchestration/git-cleanup/phases/render.js

@@ -61,11 +61,28 @@ function contentMergedNote(candidate) {
     : '';
 }
 
-/** Pure: render the dry-run plan as the operator-facing text block. */
+/**
+ * Pure: render the branch-phase candidate list as the operator-facing text
+ * block.
+ *
+ * The header states the run mode: `execute` opts into the reap wording and
+ * defaults to `false`, so a caller that forgets it still gets the harmless
+ * preview line. Prefer {@link renderCandidateList}, which derives the mode
+ * from the phase's own CLI options rather than making the caller restate
+ * it — the header used to be hardcoded to the preview wording, so an
+ * `--execute` run announced "nothing deleted" and then reaped.
+ *
+ * @param {{ candidates: Array, skipped?: Array, ghDegraded?: boolean }} plan
+ * @param {{ baseBranch?: string|null, now?: number, execute?: boolean }} [opts]
+ * @returns {string[]}
+ */
 export function renderDryRun(plan, opts = {}) {
-  const { baseBranch = null, now } = opts;
+  const { baseBranch = null, now, execute = false } = opts;
+  const count = plan.candidates.length;
   const lines = [
-    `${TAG} DRY RUN (nothing deleted) — ${plan.candidates.length} candidate(s)`,
+    execute
+      ? `${TAG} EXECUTE — ${count} candidate(s) to reap`
+      : `${TAG} DRY RUN (nothing deleted) — ${count} candidate(s)`,
   ];
   if (plan.candidates.length === 0) {
     lines.push('  (no merged branches to clean up)');
@@ -105,6 +122,25 @@ export function renderDryRun(plan, opts = {}) {
   return lines;
 }
 
+/**
+ * Pure: the branch phase's candidate-list block, with the header's run
+ * mode derived from the phase's own CLI options — the same `opts.dryRun`
+ * the reap path reads. Taking the whole bag (rather than a restated
+ * boolean) is the point: the driver cannot get the wording wrong because
+ * it never names the flag, so a destructive `--execute` run can no longer
+ * announce itself as a `DRY RUN (nothing deleted)` preview and then
+ * delete every candidate.
+ *
+ * @param {object} args
+ * @param {{ candidates: Array, skipped?: Array }} args.plan
+ * @param {{ dryRun?: boolean }} args.opts   Parsed CLI options.
+ * @param {string|null} [args.baseBranch]
+ * @returns {string[]}
+ */
+export function renderCandidateList({ plan, opts = {}, baseBranch = null }) {
+  return renderDryRun(plan, { baseBranch, execute: !opts.dryRun });
+}
+
 /**
  * Pure: render a single latest-PR-state skip line. Returns null when the
  * skip reason is not one of the latest-PR family — `renderDryRun` filters