mandrel 2.0.0 → 2.1.0

package/.agents/scripts/lib/orchestration/plan-metrics.js

@@ -5,7 +5,7 @@
  * phase is removed, every plan CLI invocation stamps an entry/exit record so
  * the current 12-phase baseline is captured on disk. Each record is one
  * newline-terminated JSON line appended to
- * `temp/epic-<id>/plan-metrics.json` (per-Epic plan CLIs) or
+ * `temp/run-<id>/plan-metrics.json` (per-Epic plan CLIs) or
  * `temp/standalone/plan-metrics.json` (the standalone `story-plan.js` path
  * and Epic-less healthcheck runs — same standalone routing the friction
  * ledger uses).
@@ -61,7 +61,7 @@ import path from 'node:path';
 
 import {
   anchorTempRoot,
-  epicArtifactPath,
+  runArtifactPath,
   tempRootFrom,
 } from '../config/temp-paths.js';
 import { Logger } from '../Logger.js';
@@ -95,7 +95,7 @@ export function planMetricsPath(epicId, config) {
       PLAN_METRICS_BASENAME,
     );
   }
-  return epicArtifactPath(epicId, PLAN_METRICS_BASENAME, config);
+  return runArtifactPath(epicId, PLAN_METRICS_BASENAME, config);
 }
 
 /**
@@ -314,7 +314,8 @@ export async function readPlanMetrics(epicId, config) {
 
 /**
  * Roll a read ledger up into the compact summary surfaced by the persist
- * summary and `analyze-execution.js`. Returns `null` when there is nothing
+ * summary. (Story #4545 deleted its second consumer, `analyze-execution.js`,
+ * with the execution-analysis surface.) Returns `null` when there is nothing
  * to summarize (missing ledger or zero parseable entries).
  *
  * Critic-skip records (kind: 'critic-skip') are counted separately from
@@ -322,7 +323,15 @@ export async function readPlanMetrics(epicId, config) {
  * them down, so the skip-audit trail is visible in the persist summary
  * without inflating the turns-per-plan proxy.
  *
+ * Pass `opts.since` (an ISO-8601 instant) to scope the roll-up to one plan
+ * run (Story #4541). The Epic-less ledger at `temp/standalone/` is shared by
+ * every plan the repo has ever run, so an unfiltered summary reported
+ * lifetime totals under a line the reader takes to describe the invocation
+ * in front of them. Records are timestamped `startedAt` (invocations) or
+ * `at` (critic skips); either at-or-after `since` is in scope.
+ *
  * @param {{ entries: object[], malformedLines?: number }} ledger
+ * @param {{ since?: string|null }} [opts]
  * @returns {{
  *   invocations: number,
  *   failures: number,
@@ -337,8 +346,31 @@ export async function readPlanMetrics(epicId, config) {
  *   malformedLines: number,
  * }|null}
  */
-export function summarizePlanMetrics(ledger) {
-  const entries = ledger?.entries ?? [];
+/**
+ * Timestamp a ledger record is ordered by: `startedAt` for invocation
+ * records, `at` for critic-skip records.
+ *
+ * @param {object} entry
+ * @returns {string|null}
+ */
+function recordTimestamp(entry) {
+  const stamp =
+    entry?.kind === PLAN_METRICS_KIND_CRITIC_SKIP ? entry.at : entry.startedAt;
+  return typeof stamp === 'string' ? stamp : null;
+}
+
+export function summarizePlanMetrics(ledger, opts = {}) {
+  const all = ledger?.entries ?? [];
+  const since = typeof opts.since === 'string' ? opts.since : null;
+  // ISO-8601 UTC strings sort lexicographically in time order, so a string
+  // compare is a correct (and allocation-free) instant compare here.
+  const entries =
+    since === null
+      ? all
+      : all.filter((e) => {
+          const stamp = recordTimestamp(e);
+          return stamp !== null && stamp >= since;
+        });
   if (entries.length === 0) return null;
   const byCli = {};
   const byMode = {};

package/.agents/scripts/lib/orchestration/plan-persist/fan-out-gate.js

@@ -6,7 +6,11 @@
  */
 
 import { Logger } from '../../Logger.js';
-import { renderHardConflictError } from '../ticket-validator-conflicts.js';
+import {
+  renderFanOutEvidence,
+  renderFanOutRemedy,
+  renderHardConflictError,
+} from '../ticket-validator-conflicts.js';
 
 /**
  * @param {object[]} findings
@@ -24,8 +28,9 @@ export function enforceFanOutGate(
     for (const f of fanOut) {
       Logger.warn(
         `[${tag}] Persisting a large-fan-out deletion: ` +
-          `Task "${f.taskSlug}" deletes "${f.path}" with ${f.callSiteCount} ` +
-          `call site(s) (threshold ${f.threshold}). Operator override --allow-large-fan-out.`,
+          `Story "${f.storySlug}" deletes "${f.path}" with ${f.callSiteCount} ` +
+          `importer(s) (threshold ${f.threshold}). Operator override --allow-large-fan-out.` +
+          renderFanOutEvidence(f),
       );
     }
     return;
@@ -33,13 +38,18 @@ export function enforceFanOutGate(
   const lines = fanOut
     .map(
       (f) =>
-        `  - Task "${f.taskSlug}" (Story "${f.storySlug}") deletes "${f.path}" — ${f.callSiteCount} call site(s) (threshold ${f.threshold})`,
+        `  - Story "${f.storySlug}" deletes "${f.path}" — ` +
+        `${f.callSiteCount} importer(s) (threshold ${f.threshold})` +
+        renderFanOutEvidence(f),
     )
     .join('\n');
+  // Each finding carries its own remedy — a rename-shaped deletion has no
+  // subsystems to split across, so a blanket "split it up" footer would be
+  // wrong advice for it (Story #4547).
+  const remedies = [...new Set(fanOut.map((f) => renderFanOutRemedy(f)))];
   throw new Error(
     `[${tag}] ${fanOut.length} Task(s) declare large-fan-out deletions:\n${lines}\n\n` +
-      `Split each deletion into a subsystem-by-subsystem migration across multiple Stories, ` +
-      `or rerun --allow-large-fan-out after confirming the deletion is intentional.`,
+      remedies.join('\n\n'),
   );
 }
 

package/.agents/scripts/lib/orchestration/plan-persist/persist-helpers.js

@@ -2,16 +2,19 @@
  * persist-helpers.js — pure helper surface for the flat Story `/plan` persist.
  *
  * Exports:
+ *   - `resolveBaseBranchRef(config)` — the one place the persist gates learn
+ *     which ref to probe.
  *   - `validateTickets(tickets, config)` — runs the cross-link, model-capacity,
  *     freshness, and task-body validators in one pass. Capacity settings are
  *     explicit inputs so the validator and decomposer share one live delivery
  *     envelope instead of silently falling back to framework defaults.
- *   - `makeDefaultFanOutCounter({ baseBranchRef, cwd })` — production
+ *   - `makeDefaultFanOutCounter({ baseBranchRef, cwd, git })` — production
  *     fan-out probe used by the conflict policy.
  *
  * @module lib/orchestration/plan-persist/persist-helpers
  */
 
+import posix from 'node:path/posix';
 import { resolveListValue } from '../../config/shared.js';
 import { gitSpawn } from '../../git-utils.js';
 import { validateTaskBodies } from '../task-body-validator.js';
@@ -19,32 +22,156 @@ import { validateAndNormalizeTickets } from '../ticket-validator.js';
 import { DEFAULT_REGISTRY_PATTERNS } from '../ticket-validator-conflicts.js';
 
 /**
- * Default fan-out counter — counts distinct files at `baseBranchRef` that
- * reference the basename (without extension) of the deleted path. Uses
- * `git grep -l` for a streaming-friendly probe; an empty grep returns
- * exit code 1 which we map to a count of 0.
+ * Extensions an import specifier may elide. Probed longest-path-first when
+ * resolving an extensionless specifier back onto a concrete repo path.
+ */
+const RESOLVABLE_EXTENSIONS = ['', '.js', '.mjs', '.cjs', '.jsx', '.json'];
+
+/** Every quoted string on a candidate line — the specifier lives in one. */
+const QUOTED_RE = /['"]([^'"\n]+)['"]/g;
+
+function escapeRegExp(value) {
+  return value.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+}
+
+/**
+ * The specifier tails an importer of `path` could plausibly write as the
+ * final segment of its quoted specifier: the basename, the basename minus
+ * its extension, and — for a directory-index module — the directory name
+ * (`./foo` resolving to `foo/index.js`).
+ *
+ * This is a *candidate* net only. It is deliberately generous because the
+ * resolution pass below re-checks every hit against the real path; a tail
+ * that over-matches costs one extra resolve, a tail that under-matches
+ * loses a genuine importer.
+ */
+function specifierTails(path) {
+  const base = posix.basename(path);
+  const ext = posix.extname(base);
+  const stem = ext ? base.slice(0, -ext.length) : base;
+  const tails = new Set([base, stem]);
+  if (stem === 'index') {
+    const dir = posix.basename(posix.dirname(path));
+    if (dir && dir !== '.') tails.add(dir);
+  }
+  return [...tails].filter((t) => t.length > 0);
+}
+
+/**
+ * ERE matching a line that carries an `import` / `export … from` /
+ * `require(` / dynamic `import(` whose quoted specifier *ends* at one of
+ * `tails`. The `(^|/)`-equivalent guard (`([^'"]*\/)?`) is what keeps
+ * `notification.js` from matching `push-notification.js`.
+ */
+function buildProbePattern(tails) {
+  const alt = tails.map(escapeRegExp).join('|');
+  return `(from|require|import)[[:space:]]*\\(?[[:space:]]*['"]([^'"]*/)?(${alt})['"]`;
+}
+
+/**
+ * Resolve a relative specifier written in `importerPath` back onto a repo
+ * path and report whether it names `deletedPath`.
+ *
+ * **Known boundary:** only relative (`./`, `../`) specifiers resolve. A
+ * consumer repo that imports its own modules through bare specifiers or a
+ * path alias (`#lib/x`, `@app/x`, a `tsconfig` `paths` entry) would
+ * under-count, because resolving those needs the resolver config this probe
+ * deliberately does not read. Mandrel's own internal imports are all
+ * relative. Under-counting is the *quiet* failure direction — it argues for
+ * a deletion rather than against one — so if alias-importing consumers
+ * appear, this is the place to teach the probe their resolver.
+ */
+function specifierResolvesTo(importerPath, specifier, deletedPath) {
+  if (!specifier.startsWith('./') && !specifier.startsWith('../')) return false;
+  const resolved = posix.normalize(
+    posix.join(posix.dirname(importerPath), specifier),
+  );
+  for (const ext of RESOLVABLE_EXTENSIONS) {
+    if (`${resolved}${ext}` === deletedPath) return true;
+    if (ext && `${resolved}/index${ext}` === deletedPath) return true;
+  }
+  return false;
+}
+
+/**
+ * Quote one argv entry so the reported probe is **runnable as emitted**.
  *
- * Story #2962. Injected via opts in tests; this default runs in production.
+ * The probe is the operator's route to checking the number, so it has to
+ * survive a paste into a shell. Unquoted, the ERE's `(`, `|`, `[[:space:]]`
+ * and `?` are glob/grouping metacharacters: zsh fails the paste with
+ * `no matches found` *and exits 0*, which reads as "zero importers" — the
+ * gate's own audit trail would then argue for the deletion it is meant to
+ * question (Story #4547).
  */
-export function makeDefaultFanOutCounter({ baseBranchRef, cwd }) {
+function shellQuote(value) {
+  if (/^[A-Za-z0-9_./-]+$/.test(value)) return value;
+  return `'${value.replaceAll("'", "'\\''")}'`;
+}
+
+/**
+ * Parse one `git grep -n` output line of the form `<ref>:<path>:<lineno>:<text>`.
+ */
+function parseGrepLine(line, baseBranchRef) {
+  const prefix = `${baseBranchRef}:`;
+  if (!line.startsWith(prefix)) return null;
+  const rest = line.slice(prefix.length);
+  const pathEnd = rest.indexOf(':');
+  if (pathEnd === -1) return null;
+  const path = rest.slice(0, pathEnd);
+  const afterPath = rest.slice(pathEnd + 1);
+  const lineEnd = afterPath.indexOf(':');
+  if (lineEnd === -1) return null;
+  return { path, text: afterPath.slice(lineEnd + 1) };
+}
+
+/**
+ * Default fan-out probe — resolves the *importers* of the deleted module at
+ * `baseBranchRef`, and reports the referencing files alongside the exact
+ * probe that produced them.
+ *
+ * Two-stage, because accuracy and cost pull in opposite directions:
+ *
+ *   1. `git grep -n -E` narrows the tree to lines whose quoted import /
+ *      require specifier could name the module (final-segment match).
+ *   2. Each candidate specifier is resolved against its own importer's
+ *      directory and compared to the deleted path. Only a real resolution
+ *      counts.
+ *
+ * The predecessor (Story #2962) grepped the basename stem as a bare word
+ * across the whole tree, so a module named `notification` or `options`
+ * reported dozens of call sites drawn from prose, schemas, and unrelated
+ * modules — and the gate that fired on that number told the operator to
+ * split a migration that did not exist. It also returned 0 without probing
+ * for any stem under three characters, under-reporting in silence. Both are
+ * gone: coupling is measured by resolution, not vocabulary (Story #4547).
+ *
+ * @returns {(arg: { path: string }) => { count: number, files: string[], probe: string }}
+ */
+export function makeDefaultFanOutCounter({ baseBranchRef, cwd, git } = {}) {
+  const spawn = git?.gitSpawn ?? gitSpawn;
   return ({ path }) => {
-    const lastSlash = path.lastIndexOf('/');
-    const base = lastSlash === -1 ? path : path.slice(lastSlash + 1);
-    const dotIdx = base.lastIndexOf('.');
-    const stem = dotIdx > 0 ? base.slice(0, dotIdx) : base;
-    if (stem.length < 3) return 0;
-    const result = gitSpawn(
-      cwd ?? process.cwd(),
-      'grep',
-      '-l',
-      '--fixed-strings',
-      stem,
-      baseBranchRef,
-    );
-    if (result.status !== 0) return 0;
-    const lines = result.stdout.split('\n').filter((l) => l.trim().length > 0);
-    // Exclude the deleted file itself from the call-site count.
-    return lines.filter((l) => !l.endsWith(`:${path}`)).length;
+    const tails = specifierTails(path);
+    const pattern = buildProbePattern(tails);
+    const args = ['grep', '-n', '-E', '--full-name', pattern, baseBranchRef];
+    const probe = `git ${args.map(shellQuote).join(' ')}`;
+    const result = spawn(cwd ?? process.cwd(), ...args);
+    // git grep exits 1 on "no matches" — an empty result, not a failure.
+    if (result.status !== 0) return { count: 0, files: [], probe };
+    const files = new Set();
+    for (const line of result.stdout.split('\n')) {
+      if (line.trim().length === 0) continue;
+      const hit = parseGrepLine(line, baseBranchRef);
+      // The deleted module's own self-references are not call sites.
+      if (!hit || hit.path === path) continue;
+      for (const match of hit.text.matchAll(QUOTED_RE)) {
+        if (specifierResolvesTo(hit.path, match[1], path)) {
+          files.add(hit.path);
+          break;
+        }
+      }
+    }
+    const sorted = [...files].sort();
+    return { count: sorted.length, files: sorted, probe };
   };
 }
 
@@ -72,8 +199,29 @@ function resolveConflictPolicy(cfg) {
   return policy;
 }
 
+/**
+ * Resolve the ref the persist gates probe against.
+ *
+ * The canonical resolved config carries the base branch at
+ * `project.baseBranch` (`lib/config-resolver.js` defaults it to `main`).
+ * This helper used to read `config.baseBranch` — a key the resolver never
+ * produces — so every freshness / file-assumption / fan-out probe silently
+ * targeted the literal `main` regardless of configuration. Benign in a repo
+ * whose base branch *is* `main`; wrong for any consumer that configured
+ * something else (Story #4541).
+ *
+ * The flat `config.baseBranch` fallback is retained for the legacy
+ * `settings`-bag callers that pass `{ baseBranch, paths, planning }`.
+ *
+ * @param {object} [config] Resolved config, or a legacy settings bag.
+ * @returns {string}
+ */
+export function resolveBaseBranchRef(config) {
+  return config?.project?.baseBranch ?? config?.baseBranch ?? 'main';
+}
+
 export function validateTickets(tickets, config, opts = {}) {
-  const baseBranchRef = config?.baseBranch ?? 'main';
+  const baseBranchRef = resolveBaseBranchRef(config);
   const conflictPolicy = resolveConflictPolicy(config);
   if (typeof opts.fanOutCounter === 'function') {
     conflictPolicy.fanOutCounter = opts.fanOutCounter;

package/.agents/scripts/lib/orchestration/plan-persist/plan-context-source.js

@@ -0,0 +1,116 @@
+/**
+ * plan-context-source.js — locate and read the `plan-context.js` envelope so
+ * persist can derive the `/plan --tickets` source ids from the run that
+ * actually fetched them (Story #4554).
+ *
+ * This lives beside the persist ops rather than inside `plan-persist.js` so
+ * the discovery + failure policy is directly testable: the CLI is a thin
+ * `parseArgs` shell, and the interesting behaviour here is exactly the part
+ * that decides whether a `--tickets` run can quietly lose its source set.
+ *
+ * @module lib/orchestration/plan-persist/plan-context-source
+ */
+
+import { readFile } from 'node:fs/promises';
+import path from 'node:path';
+
+import { Logger } from '../../Logger.js';
+
+/**
+ * Filename the `/plan` interrogate step writes its envelope to inside
+ * `--plan-dir` (`plan-context.js --out <plan-dir>/plan-context.json`).
+ */
+export const PLAN_CONTEXT_FILENAME = 'plan-context.json';
+
+/**
+ * Decide where to look for the envelope.
+ *
+ * An explicit `--plan-context` path wins; otherwise the conventional file
+ * inside `--plan-dir`. With neither, there is nothing to read — the caller
+ * gets `null` and must warn (see `loadPlanContextEnvelope`).
+ *
+ * @param {string|null|undefined} explicitPath `--plan-context`.
+ * @param {string|null|undefined} planDir `--plan-dir`.
+ * @returns {{ path: string, explicit: boolean }|null}
+ */
+export function resolvePlanContextPath(explicitPath, planDir) {
+  if (explicitPath) {
+    return { path: path.resolve(explicitPath), explicit: true };
+  }
+  if (planDir) {
+    return {
+      path: path.join(path.resolve(planDir), PLAN_CONTEXT_FILENAME),
+      explicit: false,
+    };
+  }
+  return null;
+}
+
+/**
+ * The advice printed whenever persist has no envelope to derive ids from.
+ * Single-homed so the two no-envelope paths cannot drift apart.
+ */
+const CAPTURE_HINT =
+  'Re-run step 1 with `node .agents/scripts/plan-context.js … --out ' +
+  '<plan-dir>/plan-context.json` and pass --plan-dir, or pass ' +
+  '--source-tickets explicitly.';
+
+/**
+ * Read the `plan-context.js` envelope.
+ *
+ * Failure policy — the point is that a `--tickets` run can never *quietly*
+ * lose its source set, so every no-envelope path is audible:
+ *
+ * - **No path at all** (neither `--plan-dir` nor `--plan-context`): warn.
+ *   Persist cannot tell a legitimate `--seed` run from a `--tickets` run
+ *   whose envelope was never captured, so it says so rather than returning a
+ *   silent `null`.
+ * - **Explicit `--plan-context` missing**: throw. The operator named a file
+ *   and meant it.
+ * - **Auto-discovered file simply absent**: warn and degrade to
+ *   `--source-tickets`. A `--seed` run legitimately has no envelope, so
+ *   absence alone is not fatal.
+ * - **Present but unparseable**: throw either way. A corrupt envelope is not
+ *   the same as no envelope, and reading it as "no source tickets" is exactly
+ *   the vacuous pass this module exists to prevent.
+ *
+ * @param {{ path: string, explicit: boolean }|null} planContext
+ * @returns {Promise<object|null>} Parsed envelope, or null when absent.
+ */
+export async function loadPlanContextEnvelope(planContext) {
+  if (!planContext) {
+    Logger.warn(
+      '[plan-persist] no --plan-dir or --plan-context given, so no ' +
+        'plan-context envelope was read. If this was a `/plan --tickets` ' +
+        'run, its source tickets can only come from --source-tickets and ' +
+        `will NOT be closed otherwise. ${CAPTURE_HINT}`,
+    );
+    return null;
+  }
+
+  let raw;
+  try {
+    raw = await readFile(planContext.path, 'utf8');
+  } catch (err) {
+    if (err?.code === 'ENOENT' && !planContext.explicit) {
+      Logger.warn(
+        `[plan-persist] no plan-context envelope at ${planContext.path} — ` +
+          'source tickets can only come from --source-tickets. ' +
+          CAPTURE_HINT,
+      );
+      return null;
+    }
+    throw new Error(
+      `Cannot read plan-context envelope ${planContext.path}: ${err.message}`,
+    );
+  }
+
+  try {
+    return JSON.parse(raw);
+  } catch (err) {
+    throw new Error(
+      `Failed to parse plan-context envelope "${planContext.path}" as JSON: ` +
+        `${err.message}. ${CAPTURE_HINT}`,
+    );
+  }
+}