mandrel 2.25.0 → 2.26.0

package/.agents/scripts/lib/orchestration/planning/memory-pool-advisory.js

@@ -0,0 +1,231 @@
+/**
+ * memory-pool-advisory.js — the `/plan` Phase 0 memory-hygiene advisory.
+ *
+ * Replaces the retired memory-freshness pre-flight (Story #2557 / #4414) in
+ * the same slot, fixing both of that design's defects:
+ *
+ *   1. **Correct pool resolution.** The retired `resolveMemoryDir` built
+ *      `~/.claude/projects/<github.repo>/memory/`, but harness project
+ *      directories are **cwd-slugs** — the absolute cwd with every `/` and `.`
+ *      replaced by `-` — so the old path never resolved in any consumer and
+ *      the scan was a silent no-op everywhere.
+ *   2. **A named consumer.** The retired scanner emitted a per-entry staleness
+ *      verdict nothing read. This emits one advisory the `/plan` spine
+ *      surfaces at Gate #1, recommending `/memory-consolidate`.
+ *
+ * It also drops the semantic that made the old scanner unfixable: it renders
+ * **no per-entry verdict at all**. A memory citing a closed issue is a
+ * delivery retrospective whose subject is that issue — not a stale entry — and
+ * only the attended `/memory-consolidate` pass, reading content, can tell the
+ * difference. This module counts and stats; it never judges an entry.
+ *
+ * Detection is filesystem-only — no child processes, no `gh` probes, no
+ * network. Every failure path fails soft to "no pool, no recommendation": the
+ * advisory can degrade the nudge, never a plan.
+ *
+ * Test seams: `cwd`, `env`, `fsImpl` (node:fs-compatible `statSync` /
+ * `readdirSync` / `readFileSync`), `now`, and the two thresholds.
+ *
+ * `buildMemoryPoolAdvisory` is the **only** export: the helpers below have no
+ * caller outside this module, and exporting one solely for a test would add a
+ * row to the `dead-exports-production` ratchet (the `buildUiSurfaceSignal`
+ * precedent). Tests reach every branch through the seams above — do not
+ * "fix" the missing exports.
+ */
+
+import * as defaultFs from 'node:fs';
+import * as os from 'node:os';
+import * as path from 'node:path';
+
+/** Recommend a consolidation pass once the stamp is this old. */
+const STALE_AFTER_DAYS = 30;
+
+/** Recommend a consolidation pass once the pool holds more entries than this. */
+const ENTRY_COUNT_CEILING = 100;
+
+/** Stamp file written by `/memory-consolidate` after its operator gate. */
+const STAMP_FILENAME = '.consolidation-stamp.json';
+
+/** The index file is not itself a memory entry. */
+const INDEX_FILENAME = 'MEMORY.md';
+
+const MS_PER_DAY = 86_400_000;
+
+/**
+ * Slugify an absolute path the way the harness names its per-project
+ * directories: every `/` and `.` becomes `-`. Verified against real
+ * directories in `~/.claude/projects/` — a plain checkout and a worktree both
+ * round-trip exactly.
+ *
+ * @param {string} absPath
+ * @returns {string}
+ */
+function slugifyProjectPath(absPath) {
+  return String(absPath ?? '').replace(/[/.]/g, '-');
+}
+
+/**
+ * Resolve the memory pool directory for a working directory.
+ *
+ * `MANDREL_MEMORY_DIR` wins outright (operator override and test seam);
+ * otherwise `~/.claude/projects/<cwd-slug>/memory/`.
+ *
+ * @param {{ cwd?: string, env?: Record<string,string|undefined>, homedir?: string }} [opts]
+ * @returns {string|null} absolute pool path, or `null` when unresolvable
+ */
+function resolveMemoryPoolDir({ cwd, env = process.env, homedir } = {}) {
+  const override = env?.MANDREL_MEMORY_DIR;
+  if (typeof override === 'string' && override.length > 0) return override;
+
+  const base = typeof cwd === 'string' && cwd.length > 0 ? cwd : null;
+  if (!base) return null;
+
+  const home =
+    typeof homedir === 'string' && homedir.length > 0 ? homedir : os.homedir();
+  if (!home) return null;
+
+  return path.join(
+    home,
+    '.claude',
+    'projects',
+    slugifyProjectPath(base),
+    'memory',
+  );
+}
+
+/**
+ * Read the consolidation stamp, returning its ISO timestamp or `null`.
+ * A missing, unreadable, unparseable, or malformed stamp is indistinguishable
+ * from "never consolidated" — all four mean the same thing to the advisory.
+ *
+ * @returns {string|null}
+ */
+function readStamp({ poolDir, fsImpl }) {
+  try {
+    const raw = fsImpl.readFileSync(path.join(poolDir, STAMP_FILENAME), 'utf8');
+    const parsed = JSON.parse(raw);
+    const value = parsed?.lastConsolidatedAt;
+    if (typeof value !== 'string' || value.length === 0) return null;
+    return Number.isNaN(Date.parse(value)) ? null : value;
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Count memory entries — `.md` files other than the index.
+ *
+ * @returns {number|null} `null` when the directory cannot be listed
+ */
+function countEntries({ poolDir, fsImpl }) {
+  try {
+    return fsImpl
+      .readdirSync(poolDir)
+      .filter((name) => name.endsWith('.md') && name !== INDEX_FILENAME).length;
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Build the `memoryPoolAdvisory` envelope field.
+ *
+ * Advisory only — it carries **no routing authority**, mirroring
+ * `deliverLightSuggestion`. The `/plan` spine surfaces `recommend` at Gate #1;
+ * nothing auto-runs, and nothing here mutates the operator's memory store.
+ *
+ * @param {object} [opts]
+ * @param {string} [opts.cwd] — defaults to `process.cwd()`
+ * @param {Record<string,string|undefined>} [opts.env]
+ * @param {object} [opts.fsImpl] — node:fs-compatible seam
+ * @param {string} [opts.homedir]
+ * @param {Date|string|number} [opts.now]
+ * @param {number} [opts.staleAfterDays]
+ * @param {number} [opts.entryCountCeiling]
+ * @returns {{ present: boolean, entryCount: number, lastConsolidatedAt: string|null,
+ *            recommend: boolean, reasons: string[] }}
+ */
+export function buildMemoryPoolAdvisory({
+  cwd = process.cwd(),
+  env = process.env,
+  fsImpl = defaultFs,
+  homedir,
+  now = new Date(),
+  staleAfterDays = STALE_AFTER_DAYS,
+  entryCountCeiling = ENTRY_COUNT_CEILING,
+} = {}) {
+  const absent = (reason) => ({
+    present: false,
+    entryCount: 0,
+    lastConsolidatedAt: null,
+    recommend: false,
+    reasons: [reason],
+  });
+
+  const poolDir = resolveMemoryPoolDir({ cwd, env, homedir });
+  if (!poolDir) {
+    return absent(
+      'no memory pool could be resolved for this working directory',
+    );
+  }
+
+  let isDir = false;
+  try {
+    isDir = fsImpl.statSync(poolDir).isDirectory();
+  } catch {
+    isDir = false;
+  }
+  if (!isDir) {
+    return absent(`no memory pool at ${poolDir} — nothing to consolidate`);
+  }
+
+  const entryCount = countEntries({ poolDir, fsImpl });
+  if (entryCount === null) {
+    return absent(`memory pool at ${poolDir} could not be listed`);
+  }
+
+  const lastConsolidatedAt = readStamp({ poolDir, fsImpl });
+  const reasons = [];
+
+  // An empty pool has nothing to consolidate, whatever the stamp says.
+  if (entryCount === 0) {
+    return {
+      present: true,
+      entryCount: 0,
+      lastConsolidatedAt,
+      recommend: false,
+      reasons: ['memory pool is empty — nothing to consolidate'],
+    };
+  }
+
+  if (lastConsolidatedAt === null) {
+    reasons.push(
+      'no consolidation stamp — this pool has never been consolidated',
+    );
+  } else {
+    const ageDays =
+      (new Date(now).getTime() - Date.parse(lastConsolidatedAt)) / MS_PER_DAY;
+    if (ageDays > staleAfterDays) {
+      reasons.push(
+        `last consolidated ${Math.floor(ageDays)} days ago (over the ${staleAfterDays}-day threshold)`,
+      );
+    }
+  }
+
+  if (entryCount > entryCountCeiling) {
+    reasons.push(
+      `${entryCount} entries (over the ${entryCountCeiling}-entry threshold)`,
+    );
+  }
+
+  return {
+    present: true,
+    entryCount,
+    lastConsolidatedAt,
+    recommend: reasons.length > 0,
+    reasons:
+      reasons.length > 0
+        ? reasons
+        : ['memory pool is within both freshness thresholds'],
+  };
+}

package/.agents/scripts/lib/orchestration/resolve-stories.js

@@ -34,6 +34,7 @@ import {
   extractChangePaths,
   parse as parseStoryBody,
 } from '../story-body/story-body.js';
+import { expandIdList } from '../util/parse-id-list.js';
 import { resolveStoryDispatchMode } from './complexity-gate.js';
 
 /** Labels/state that mean a blocker no longer gates its dependents. */
@@ -355,29 +356,29 @@ export function buildStoriesEnvelope({
 }
 
 /**
- * Parse and validate the `--ids` list.
+ * Parse and validate the `--ids` list, expanding any `A-B` dash range.
+ *
+ * A contiguous span is how an operator names a plan run — `/deliver 4922 -
+ * 4926` — so the range is expanded here rather than transcribed by the host.
+ * `stories-wave-tick.js --stories` reads through this same function, which is
+ * what keeps the sequencing set identical to the resolved one.
  *
  * @param {string|undefined} raw
+ * @param {string} [flag] Flag name, for the error message.
  * @returns {number[]}
  */
-export function parseIds(raw) {
-  const ids = String(raw ?? '')
-    .split(',')
-    .map((s) => s.trim())
-    .filter(Boolean)
-    .map((s) => {
-      const n = Number.parseInt(s, 10);
-      if (!Number.isInteger(n) || n <= 0 || String(n) !== s) {
-        throw new Error(
-          `[resolve-stories] --ids must be a comma-separated list of positive issue numbers (got "${s}").`,
-        );
-      }
-      return n;
-    });
+export function parseIds(raw, flag = '--ids') {
+  const { ids, error } = expandIdList(raw, {
+    flag,
+    prefix: '[resolve-stories] ',
+  });
+  if (error) {
+    throw new Error(error);
+  }
   if (ids.length === 0) {
     throw new Error(
-      '[resolve-stories] --ids is required: node resolve-stories.js --ids 101,102',
+      `[resolve-stories] ${flag} is required: node resolve-stories.js --ids 101,102 (or a range: --ids 101-104)`,
     );
   }
-  return [...new Set(ids)];
+  return ids;
 }

package/.agents/scripts/lib/orchestration/run-epilogue.js

@@ -494,6 +494,18 @@ async function executeAuditRoster({
       ? selectedAudits.map((lens) => `- \`${lens}\``)
       : ['- _(none — docs-only or no matching change-set lenses)_']),
     '',
+    // Story #4949 — the roster used to name the lenses and say nothing about
+    // how to dispatch them, which made a serial walk (and a nested
+    // coordinator) fully compliant with it. The lenses are read-only and share
+    // no write paths, so they are the textbook independent fan-out; naming the
+    // shape here is what turns that from an option into the instruction.
+    '**Dispatch shape (MUST): flat, parallel, one turn.** Spawn one ' +
+      '`auditor` sub-agent per lens listed above and issue every one of those ' +
+      'spawns in a SINGLE turn — no nested fan-out, no serial walk. A ' +
+      'coordinator sub-agent that re-dispatches the lenses is the failure ' +
+      'this line exists to prevent: a grandchild routes its findings to the ' +
+      'wrong parent or loses them outright.',
+    '',
     '```json',
     JSON.stringify(
       {

package/.agents/scripts/lib/orchestration/single-story-close/phases/confirm-merge.js

@@ -282,15 +282,33 @@ export async function readPrWaitProbe({
  * explicit `maxWaitSecondsOverride` still wins over the async cap — a headless
  * caller with no host ceiling opts back into single-block waiting.
  *
+ * `modeOverride` is the per-invocation `--merge-watch-mode` flag (Story #4949)
+ * and wins over `delivery.mergeWatch.mode` on exactly the precedence
+ * `maxWaitSecondsOverride` already uses. It exists because run topology is
+ * knowable only to the orchestrator: close sees one Story and cannot tell a
+ * solo delivery (where a foreground wait is the cheapest ending) from the Nth
+ * close of a wave (where each foreground wait is serialized dead time). The
+ * config default therefore stays `sync`, and the caller that knows better says
+ * so per invocation. The two flags remain composable — `--merge-watch-mode
+ * async --max-wait-seconds 900` selects the async posture and then overrides
+ * its probe cap, because the cap check below keys on the override's presence,
+ * not on where the mode came from.
+ *
  * @param {object} [config]
  * @param {number} [maxWaitSecondsOverride]
+ * @param {'sync'|'async'} [modeOverride]
  * @returns {{ mode: 'sync'|'async', intervalSeconds: number, maxWaitSeconds: number, maxBudgetSeconds: number, updateAttempts: number }}
  */
-export function resolveMergeWaitConfig(config, maxWaitSecondsOverride) {
+export function resolveMergeWaitConfig(
+  config,
+  maxWaitSecondsOverride,
+  modeOverride,
+) {
   const mergeWatch = config?.delivery?.mergeWatch ?? {};
   const int = (value, fallback, min = 1) =>
     Number.isInteger(value) && value >= min ? value : fallback;
-  const mode = mergeWatch.mode === 'async' ? 'async' : 'sync';
+  const requestedMode = modeOverride ?? mergeWatch.mode;
+  const mode = requestedMode === 'async' ? 'async' : 'sync';
   const configuredMaxWait = int(
     maxWaitSecondsOverride,
     int(mergeWatch.maxWaitSeconds, DEFAULT_MAX_WAIT_SECONDS),
@@ -759,6 +777,9 @@ async function onMergeObserved({
  * @param {string|null} args.autoMergeReason
  * @param {object} args.provider
  * @param {object} [args.config]
+ * @param {'sync'|'async'} [args.mergeWatchMode] Per-invocation
+ *   `--merge-watch-mode` override (Story #4949); wins over
+ *   `delivery.mergeWatch.mode`.
  * @param {(tag: string, msg: string) => void} [args.progress]
  * @param {object} [args.injectedGh]
  * @param {Function} [args.injectedNotify]
@@ -791,6 +812,7 @@ export async function runConfirmMergePhase({
   provider,
   config,
   maxWaitSeconds: maxWaitSecondsOverride,
+  mergeWatchMode: mergeWatchModeOverride,
   progress,
   injectedGh,
   injectedNotify,
@@ -833,7 +855,11 @@ export async function runConfirmMergePhase({
     maxWaitSeconds,
     maxBudgetSeconds,
     updateAttempts,
-  } = resolveMergeWaitConfig(config, maxWaitSecondsOverride);
+  } = resolveMergeWaitConfig(
+    config,
+    maxWaitSecondsOverride,
+    mergeWatchModeOverride,
+  );
   const intervalMs = intervalSeconds * 1000;
   const startedAtMs = nowMsFn();
   let anchorMs = startedAtMs;

package/.agents/scripts/lib/orchestration/single-story-close/phases/normalize-pr-title.js

@@ -38,7 +38,7 @@ import { gitSpawn as defaultGitSpawn } from '../../../git-utils.js';
 import { Logger as DefaultLogger } from '../../../Logger.js';
 
 /** Safe default Conventional-Commit type when none can be derived. */
-export const DEFAULT_CONVENTIONAL_TYPE = 'chore';
+const DEFAULT_CONVENTIONAL_TYPE = 'chore';
 
 /**
  * The Conventional-Commit types Mandrel accepts. Mirrors
@@ -46,7 +46,7 @@ export const DEFAULT_CONVENTIONAL_TYPE = 'chore';
  * `changelog-sections`. Kept in sync by hand (single hard-cutover, no
  * shim) — adding a type means touching all three.
  */
-export const CONVENTIONAL_TYPES = Object.freeze([
+const CONVENTIONAL_TYPES = Object.freeze([
   'feat',
   'fix',
   'perf',
@@ -99,7 +99,7 @@ const LEADING_TYPE_RE = new RegExp(
  * @param {string} subject
  * @returns {boolean}
  */
-export function isConventionalSubject(subject) {
+function isConventionalSubject(subject) {
   if (typeof subject !== 'string') return false;
   return CONVENTIONAL_HEADER_RE.test(subject.trim());
 }
@@ -111,7 +111,7 @@ export function isConventionalSubject(subject) {
  * @param {string} subject
  * @returns {string|null}
  */
-export function parseConventionalType(subject) {
+function parseConventionalType(subject) {
   if (typeof subject !== 'string') return null;
   const match = subject.trim().match(LEADING_TYPE_RE);
   return match ? match[1] : null;
@@ -125,7 +125,7 @@ export function parseConventionalType(subject) {
  * @param {string[]} types
  * @returns {string|null}
  */
-export function pickDominantType(types) {
+function pickDominantType(types) {
   const present = new Set(types.filter(Boolean));
   for (const candidate of TYPE_PRECEDENCE) {
     if (present.has(candidate)) return candidate;
@@ -148,7 +148,7 @@ export function pickDominantType(types) {
  * }} args
  * @returns {string}
  */
-export function deriveTypeFromBranchCommits({
+function deriveTypeFromBranchCommits({
   storyBranch,
   baseBranch,
   cwd = process.cwd(),

package/.agents/scripts/lib/orchestration/single-story-close/phases/options.js

@@ -9,23 +9,27 @@
  */
 
 import path from 'node:path';
-import { parseSprintArgs } from '../../../cli-args.js';
+import { parseMergeWatchMode, parseSprintArgs } from '../../../cli-args.js';
 import { getDeliveryRouting } from '../../../config/delivery-routing.js';
 import { PROJECT_ROOT } from '../../../project-root.js';
 import { isOperatorMergeReason } from './auto-merge.js';
 
 /**
- * Resolve a flag value from an explicit override, a parsed CLI arg, or a
- * hard default.
+ * Resolve a flag value from an explicit override or a parsed CLI arg.
+ *
+ * Returns `undefined` when neither is supplied — that absence is itself the
+ * answer here, letting each caller below apply its own default (a `!!` coerce,
+ * a config lookup, or a deliberate `undefined` passed further down). The
+ * former third `defaultValue` parameter was dropped in Story #4961: no call
+ * site passed it, so it documented a mode nobody used.
  *
  * @template T
  * @param {T|undefined} paramValue
  * @param {T|undefined} parsedValue
- * @param {T} defaultValue
- * @returns {T}
+ * @returns {T|undefined}
  */
-function resolveFlag(paramValue, parsedValue, defaultValue) {
-  return paramValue ?? parsedValue ?? defaultValue;
+function resolveFlag(paramValue, parsedValue) {
+  return paramValue ?? parsedValue;
 }
 
 /**
@@ -87,8 +91,8 @@ export function resolveWaitForMerge({
  * (`waitForMergeExplicit` / `noWaitForMerge`) for the runner to resolve once
  * the config and the arm outcome exist.
  *
- * @param {{ storyIdParam, cwdParam, skipValidationParam, skipSyncParam, noAutoMergeParam, waitForMergeParam, noWaitForMergeParam, maxWaitSecondsParam }} raw
- * @returns {{ storyId, cwd, skipValidation, skipSync, noAutoMerge, waitForMergeExplicit, noWaitForMerge, maxWaitSeconds }}
+ * @param {{ storyIdParam, cwdParam, skipValidationParam, skipSyncParam, noAutoMergeParam, waitForMergeParam, noWaitForMergeParam, maxWaitSecondsParam, mergeWatchModeParam }} raw
+ * @returns {{ storyId, cwd, skipValidation, skipSync, noAutoMerge, waitForMergeExplicit, noWaitForMerge, maxWaitSeconds, mergeWatchMode }}
  */
 export function parseCloseOptions({
   storyIdParam,
@@ -99,26 +103,27 @@ export function parseCloseOptions({
   waitForMergeParam,
   noWaitForMergeParam,
   maxWaitSecondsParam,
+  mergeWatchModeParam,
 }) {
-  const parsed =
-    storyIdParam !== undefined
-      ? {
-          storyId: storyIdParam,
-          cwd: cwdParam ?? null,
-          skipValidation: !!skipValidationParam,
-          skipSync: !!skipSyncParam,
-          noAutoMerge: !!noAutoMergeParam,
-          // Preserve undefined so resolveWaitForMerge can apply the
-          // closeAndLand config default when neither flag was injected.
-          waitForMerge: waitForMergeParam,
-          noWaitForMerge: !!noWaitForMergeParam,
-          maxWaitSeconds: maxWaitSecondsParam,
-        }
-      : parseSprintArgs();
-  const waitForMergeExplicit = waitForMergeParam ?? parsed.waitForMerge;
-  const maxWaitSeconds = maxWaitSecondsParam ?? parsed.maxWaitSeconds;
+  // An injecting caller (`storyIdParam` supplied) is not reading argv at all,
+  // so there is nothing to parse and `parsed` stays empty. This used to build a
+  // stand-in object that copied every `*Param` into the slot of the same name —
+  // which is precisely what `resolveFlag` already does below, preferring the
+  // param over the parsed slot. One expression per flag now serves both
+  // callers, so a new flag is added in one place instead of two that can drift.
+  const parsed = storyIdParam === undefined ? parseSprintArgs() : {};
+  // Preserve undefined so resolveWaitForMerge can apply the closeAndLand
+  // config default when neither flag was supplied.
+  const waitForMergeExplicit = resolveFlag(
+    waitForMergeParam,
+    parsed.waitForMerge,
+  );
+  const maxWaitSeconds = resolveFlag(
+    maxWaitSecondsParam,
+    parsed.maxWaitSeconds,
+  );
   return {
-    storyId: parsed.storyId,
+    storyId: resolveFlag(storyIdParam, parsed.storyId),
     cwd: path.resolve(cwdParam ?? parsed.cwd ?? PROJECT_ROOT),
     // `undefined` when unsupplied — the merge wait then reads
     // `delivery.mergeWatch.maxWaitSeconds`. A per-run override exists so a
@@ -128,21 +133,20 @@ export function parseCloseOptions({
       Number.isInteger(maxWaitSeconds) && maxWaitSeconds > 0
         ? maxWaitSeconds
         : undefined,
-    skipValidation: resolveFlag(
-      skipValidationParam,
-      parsed.skipValidation,
-      false,
+    // `undefined` when unsupplied — the merge wait then reads
+    // `delivery.mergeWatch.mode`. The two merge-watch flags stay composable and
+    // mode-agnostic: `--merge-watch-mode async` picks the posture, and an
+    // explicit `--max-wait-seconds` still wins over that posture's probe cap.
+    mergeWatchMode: parseMergeWatchMode(
+      resolveFlag(mergeWatchModeParam, parsed.mergeWatchMode),
     ),
-    skipSync: resolveFlag(skipSyncParam, parsed.skipSync, false),
-    noAutoMerge: resolveFlag(noAutoMergeParam, parsed.noAutoMerge, false),
+    skipValidation: !!resolveFlag(skipValidationParam, parsed.skipValidation),
+    skipSync: !!resolveFlag(skipSyncParam, parsed.skipSync),
+    noAutoMerge: !!resolveFlag(noAutoMergeParam, parsed.noAutoMerge),
     waitForMergeExplicit:
       typeof waitForMergeExplicit === 'boolean'
         ? waitForMergeExplicit
         : undefined,
-    noWaitForMerge: resolveFlag(
-      noWaitForMergeParam,
-      parsed.noWaitForMerge,
-      false,
-    ),
+    noWaitForMerge: !!resolveFlag(noWaitForMergeParam, parsed.noWaitForMerge),
   };
 }

package/.agents/scripts/lib/orchestration/single-story-close/phases/push.js

@@ -42,7 +42,12 @@ export function pushStoryBranch({
 }) {
   progress('GIT', `Pushing ${storyBranch} to origin...`);
   try {
-    gitSync(cwd, 'push', '--no-verify', '-u', 'origin', storyBranch);
+    // No hook-bypass flag here, deliberately. Close runs its own gate chain
+    // before this point, but `--skip-validation` skips that chain, and the
+    // bypass then left nothing running at all. `pre-push` is the backstop,
+    // and it only became reachable once hooks were materialized into
+    // worktrees — which is where every Story branch is built.
+    gitSync(cwd, 'push', '-u', 'origin', storyBranch);
     progress('GIT', `✅ Pushed ${storyBranch}.`);
   } catch (err) {
     throw new Error(