mandrel 1.58.0 → 1.59.0

package/.agents/scripts/check-arch-cycles.js

@@ -0,0 +1,360 @@
+/**
+ * CLI: ratchet-down architecture gate for import cycles (Story #3991).
+ *
+ * Walks every `.js` file under `.agents/scripts/` (excluding
+ * `node_modules`), parses relative static-import edges
+ * (`from './…/x.js'`), detects directed cycles via DFS, and compares
+ * them against the committed allowlist at `baselines/arch-cycles.json`.
+ *
+ * Ratchet semantics mirror `check-dead-exports.js`:
+ *   - Any detected cycle NOT in the allowlist → exit 1, cycle path printed.
+ *   - Allowlisted cycle no longer detected → printed as `-` (removal),
+ *     warning that the allowlist can shrink. Removals-only exits 0.
+ *   - Clean diff → exit 0.
+ *
+ * Cycles are normalized by rotating to the lexicographically-smallest
+ * member so the same cycle always serializes identically regardless of
+ * the DFS entry point.
+ *
+ * Flags:
+ *   --baseline <path>  override the allowlist path (default
+ *                      `baselines/arch-cycles.json`, resolved from cwd)
+ *   --root <path>      override the scanned root (default
+ *                      `.agents/scripts`, resolved from cwd)
+ *   --json             write the structured envelope to stdout
+ */
+
+import fs from 'node:fs';
+import path from 'node:path';
+import process from 'node:process';
+import { runAsCli } from './lib/cli-utils.js';
+
+/**
+ * Parse argv for `--baseline <path>`, `--root <path>`, and `--json`.
+ * Exported so unit tests can pin the parser.
+ *
+ * @param {string[]} argv
+ * @returns {{ baselinePath: string | null, rootPath: string | null, json: boolean }}
+ */
+export function parseArgv(argv = []) {
+  let baselinePath = null;
+  let rootPath = null;
+  let json = false;
+  for (let i = 0; i < argv.length; i += 1) {
+    const a = argv[i];
+    if (a === '--baseline') {
+      const next = argv[i + 1];
+      if (next && !next.startsWith('--')) {
+        baselinePath = next;
+        i += 1;
+      }
+    } else if (a === '--root') {
+      const next = argv[i + 1];
+      if (next && !next.startsWith('--')) {
+        rootPath = next;
+        i += 1;
+      }
+    } else if (a === '--json') {
+      json = true;
+    }
+  }
+  return { baselinePath, rootPath, json };
+}
+
+/**
+ * Recursively collect `.js` files under `rootDir`, skipping
+ * `node_modules`. Returns absolute paths, sorted for determinism.
+ *
+ * @param {string} rootDir
+ * @returns {string[]}
+ */
+export function collectJsFiles(rootDir) {
+  const out = [];
+  const walk = (dir) => {
+    let entries;
+    try {
+      entries = fs.readdirSync(dir, { withFileTypes: true });
+    } catch {
+      return;
+    }
+    for (const entry of entries) {
+      if (entry.name === 'node_modules') continue;
+      const full = path.join(dir, entry.name);
+      if (entry.isDirectory()) {
+        walk(full);
+      } else if (entry.isFile() && entry.name.endsWith('.js')) {
+        out.push(full);
+      }
+    }
+  };
+  walk(rootDir);
+  return out.sort();
+}
+
+const IMPORT_RE = /from\s+['"](\.\.?\/[^'"]+\.js)['"]/g;
+
+/**
+ * Pure helper: extract relative static-import specifiers from source text.
+ *
+ * @param {string} source
+ * @returns {string[]}
+ */
+export function parseRelativeImports(source) {
+  const specs = [];
+  for (const m of source.matchAll(IMPORT_RE)) {
+    specs.push(m[1]);
+  }
+  return specs;
+}
+
+/**
+ * Build a directed import graph over the given files. Node identity is the
+ * file path relative to `rootDir`, posix-separated, so the graph (and any
+ * cycles found in it) serializes identically across platforms. Edges that
+ * resolve outside the scanned file set are dropped.
+ *
+ * @param {string[]} files absolute paths
+ * @param {string} rootDir
+ * @param {{ readFile?: (p: string) => string }} [opts]
+ * @returns {Map<string, string[]>}
+ */
+export function buildGraph(files, rootDir, { readFile } = {}) {
+  const read = readFile ?? ((p) => fs.readFileSync(p, 'utf-8'));
+  const toId = (abs) => path.relative(rootDir, abs).split(path.sep).join('/');
+  const idSet = new Set(files.map(toId));
+  const graph = new Map();
+  for (const file of files) {
+    const id = toId(file);
+    let source;
+    try {
+      source = read(file);
+    } catch {
+      graph.set(id, []);
+      continue;
+    }
+    const edges = [];
+    for (const spec of parseRelativeImports(source)) {
+      const target = path
+        .relative(rootDir, path.resolve(path.dirname(file), spec))
+        .split(path.sep)
+        .join('/');
+      if (idSet.has(target) && target !== id) edges.push(target);
+    }
+    graph.set(id, [...new Set(edges)].sort());
+  }
+  return graph;
+}
+
+/**
+ * Pure helper: rotate a cycle (array of module ids, no repeated terminal
+ * element) so it starts at its lexicographically-smallest member. The same
+ * cycle therefore always serializes identically regardless of where the
+ * DFS entered it.
+ *
+ * @param {string[]} cycle
+ * @returns {string[]}
+ */
+export function normalizeCycle(cycle) {
+  if (cycle.length === 0) return [];
+  let minIdx = 0;
+  for (let i = 1; i < cycle.length; i += 1) {
+    if (cycle[i] < cycle[minIdx]) minIdx = i;
+  }
+  return [...cycle.slice(minIdx), ...cycle.slice(0, minIdx)];
+}
+
+/**
+ * Detect directed cycles in the graph via iterative-stack DFS (white /
+ * gray / black coloring). Each back edge to a gray node yields the cycle
+ * slice currently on the DFS path. Cycles are normalized and deduplicated
+ * by their serialized form, then sorted for stable output.
+ *
+ * @param {Map<string, string[]>} graph
+ * @returns {string[][]} normalized cycles
+ */
+export function findCycles(graph) {
+  const WHITE = 0;
+  const GRAY = 1;
+  const BLACK = 2;
+  const color = new Map();
+  for (const node of graph.keys()) color.set(node, WHITE);
+  const seen = new Map();
+
+  const pathStack = [];
+  const onPath = new Map(); // node -> index in pathStack
+
+  const visit = (start) => {
+    // Iterative DFS frame stack: [node, edge cursor].
+    const frames = [[start, 0]];
+    color.set(start, GRAY);
+    onPath.set(start, pathStack.length);
+    pathStack.push(start);
+    while (frames.length > 0) {
+      const frame = frames[frames.length - 1];
+      const [node] = frame;
+      const edges = graph.get(node) ?? [];
+      if (frame[1] < edges.length) {
+        const next = edges[frame[1]];
+        frame[1] += 1;
+        const c = color.get(next);
+        if (c === GRAY) {
+          const cycle = normalizeCycle(pathStack.slice(onPath.get(next)));
+          seen.set(cycle.join(' -> '), cycle);
+        } else if (c === WHITE) {
+          color.set(next, GRAY);
+          onPath.set(next, pathStack.length);
+          pathStack.push(next);
+          frames.push([next, 0]);
+        }
+      } else {
+        color.set(node, BLACK);
+        onPath.delete(node);
+        pathStack.pop();
+        frames.pop();
+      }
+    }
+  };
+
+  for (const node of [...graph.keys()].sort()) {
+    if (color.get(node) === WHITE) visit(node);
+  }
+  return [...seen.values()].sort((a, b) =>
+    a.join(' -> ').localeCompare(b.join(' -> ')),
+  );
+}
+
+/**
+ * Pure helper: read the allowlist envelope from disk. Returns the parsed
+ * object or `null` when the file is missing or unparseable.
+ *
+ * @param {string} baselinePath
+ * @returns {{ cycles?: string[][] } | null}
+ */
+export function loadBaseline(baselinePath) {
+  try {
+    if (!fs.existsSync(baselinePath)) return null;
+    const parsed = JSON.parse(fs.readFileSync(baselinePath, 'utf-8'));
+    if (!parsed || typeof parsed !== 'object') return null;
+    return parsed;
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Pure helper: diff detected cycles against the allowlist. Both sides are
+ * normalized before comparison so rotation differences never count as
+ * drift. Identity is the ` -> `-joined normalized cycle.
+ *
+ * @param {string[][]} allowlisted
+ * @param {string[][]} detected
+ * @returns {{ added: string[][], removed: string[][] }}
+ */
+export function diffCycles(allowlisted, detected) {
+  const key = (c) => normalizeCycle(c).join(' -> ');
+  const baseSet = new Set((allowlisted ?? []).map(key));
+  const currentSet = new Set((detected ?? []).map(key));
+  const added = (detected ?? []).filter((c) => !baseSet.has(key(c)));
+  const removed = (allowlisted ?? []).filter((c) => !currentSet.has(key(c)));
+  const sortFn = (a, b) => key(a).localeCompare(key(b));
+  return { added: added.sort(sortFn), removed: removed.sort(sortFn) };
+}
+
+/**
+ * Pure helper: render the human-readable diff. `+` lines are new cycles
+ * (gate fail), `-` lines are fixed cycles whose allowlist entry can be
+ * removed. A one-line summary always follows.
+ *
+ * @param {{ added: string[][], removed: string[][] }} diff
+ * @returns {string}
+ */
+export function renderDiff(diff) {
+  const lines = [];
+  const fmt = (c) => `${c.join(' -> ')} -> ${c[0]}`;
+  for (const c of diff.added) lines.push(`+ ${fmt(c)}`);
+  for (const c of diff.removed) lines.push(`- ${fmt(c)}`);
+  if (diff.removed.length > 0) {
+    lines.push(
+      `[arch-cycles] ⚠ ${diff.removed.length} allowlisted cycle(s) no longer detected — shrink baselines/arch-cycles.json`,
+    );
+  }
+  const tag = diff.added.length > 0 ? '(gate fail)' : '(ok)';
+  lines.push(
+    `[arch-cycles] added=${diff.added.length} removed=${diff.removed.length} ${tag}`,
+  );
+  return lines.join('\n');
+}
+
+/**
+ * Top-level CLI entry. Exported so tests can drive the full pipeline
+ * against a tmpdir fixture graph.
+ *
+ * @param {{
+ *   argv?: string[],
+ *   cwd?: string,
+ *   stdout?: { write: (s: string) => void },
+ *   stderr?: { write: (s: string) => void },
+ * }} [opts]
+ * @returns {Promise<number>} 0 = clean or removals-only; 1 = new cycle detected
+ */
+export async function runCli({
+  argv = process.argv.slice(2),
+  cwd = process.cwd(),
+  stdout = process.stdout,
+  stderr = process.stderr,
+} = {}) {
+  const { baselinePath, rootPath, json } = parseArgv(argv);
+  const resolvedRoot = path.resolve(
+    cwd,
+    rootPath ?? path.join('.agents', 'scripts'),
+  );
+  const resolvedBaselinePath = path.resolve(
+    cwd,
+    baselinePath ?? path.join('baselines', 'arch-cycles.json'),
+  );
+  if (!fs.existsSync(resolvedRoot)) {
+    throw new Error(`[arch-cycles] scan root not found: ${resolvedRoot}`);
+  }
+  const baseline = loadBaseline(resolvedBaselinePath);
+  const allowlisted = Array.isArray(baseline?.cycles) ? baseline.cycles : [];
+
+  const files = collectJsFiles(resolvedRoot);
+  const graph = buildGraph(files, resolvedRoot);
+  const detected = findCycles(graph);
+  const diff = diffCycles(allowlisted, detected);
+  const exitCode = diff.added.length > 0 ? 1 : 0;
+
+  if (json) {
+    const envelope = {
+      kind: 'arch-cycles-report',
+      root: resolvedRoot,
+      baselinePath: resolvedBaselinePath,
+      allowlisted: allowlisted.map(normalizeCycle),
+      detected,
+      added: diff.added,
+      removed: diff.removed,
+      exitCode,
+    };
+    stdout.write(`${JSON.stringify(envelope, null, 2)}\n`);
+  } else {
+    if (!baseline) {
+      stderr.write(
+        `[arch-cycles] ⚠ allowlist not found at ${resolvedBaselinePath} — treating as empty\n`,
+      );
+    }
+    stdout.write(`\n--- arch-cycles preview ---\n`);
+    stdout.write(`${renderDiff(diff)}\n`);
+  }
+
+  return exitCode;
+}
+
+async function main() {
+  return runCli();
+}
+
+runAsCli(import.meta.url, main, {
+  source: 'arch-cycles',
+  propagateExitCode: true,
+  errorPrefix: '[arch-cycles] ❌ Fatal error',
+});

package/.agents/scripts/coverage-capture.js

@@ -9,9 +9,11 @@
  *   2. With `--skip-when-no-crap-files`: read `git diff --name-only <ref>...HEAD`
  *      (default ref `main`) and exit 0 if no changed file lives under
  *      `crap.targetDirs`.
- *   3. Compare the coverage artifact mtime against the newest mtime in
- *      `crap.targetDirs`. Exit 0 when fresh.
- *   4. Otherwise spawn `npm run test:coverage` and propagate its exit code.
+ *   3. Test freshness: content digest of `crap.targetDirs` vs. the persisted
+ *      capture stamp (`coverage/.capture-stamp.json`), falling back to the
+ *      artifact-mtime heuristic when no stamp exists. Exit 0 when fresh.
+ *   4. Otherwise spawn `npm run test:coverage`, write a fresh capture stamp
+ *      on success, and propagate the exit code.
  *
  * Exit codes:
  *   0 — coverage is fresh (or capture skipped/succeeded).
@@ -24,8 +26,10 @@ import { getChangedFiles } from './lib/changed-files.js';
 import { getQuality, resolveConfig } from './lib/config-resolver.js';
 import {
   anyChangedUnderTargets,
+  computeContentDigest,
   isCoverageFresh,
   runCapture,
+  writeCaptureStamp,
 } from './lib/coverage-capture.js';
 
 import { Logger } from './lib/Logger.js';
@@ -99,6 +103,23 @@ function main() {
     Logger.error(
       `[coverage-capture] ✖ npm run test:coverage exited ${code}. Fix failing tests or coverage-threshold breaches before re-running the CRAP gate.`,
     );
+    return code;
+  }
+
+  // Persist the content digest next to the fresh artifact so subsequent
+  // freshness checks are content-aware (mtime churn from branch switches no
+  // longer invalidates). Best-effort — a missing stamp just means the next
+  // check falls back to the mtime heuristic.
+  const digest = computeContentDigest(args.cwd, crap.targetDirs);
+  if (
+    digest &&
+    writeCaptureStamp({
+      cwd: args.cwd,
+      coveragePath: crap.coveragePath,
+      digest,
+    })
+  ) {
+    Logger.info('[coverage-capture] Wrote content-digest capture stamp.');
   }
   return code;
 }

package/.agents/scripts/epic-deliver-preflight.js

@@ -297,9 +297,11 @@ export async function runPreflight({
   // Persist the snapshot/DAG envelope so `epic-deliver-prepare.js` can
   // reuse it instead of re-walking the hierarchy. The cache key is a
   // deterministic fingerprint of the Epic ticket returned by the same
-  // `getTicket(epicId)` call that drove `runSnapshotPhase`, so any drift
-  // (label, body, updatedAt) forces a cache miss in prepare.
-  const baseSha = computeBaseSha(state.epic);
+  // `getTicket(epicId)` call that drove `runSnapshotPhase` **plus** the
+  // Story snapshots that drove the wave DAG (Story #4019), so any drift —
+  // Epic label/body/updatedAt or a Story-dependency edit — forces a cache
+  // miss in prepare.
+  const baseSha = computeBaseSha(state.epic, state.stories);
   let cacheWritten = false;
   if (!dryRun) {
     await writePreflightCache({

package/.agents/scripts/epic-deliver-prepare.js

@@ -226,16 +226,24 @@ export async function runEpicDeliverPrepare({
 
   // Story #3027: try the preflight cache first so we don't re-walk Epic
   // → Feature → Story when `epic-deliver-preflight.js` already did. The
-  // cache key is a deterministic fingerprint of the Epic ticket; a
-  // single getTicket(epicId) round-trip confirms the cache is still
-  // valid. Cache miss or baseSha mismatch → fall back to a fresh pass.
+  // cache key is a deterministic fingerprint of the Epic ticket plus the
+  // cached Story snapshots (Story #4019): the Epic re-fetch plus one
+  // getTicket per cached Story is still far cheaper than the full
+  // hierarchy BFS, and a Story-dependency edit now invalidates the cache.
+  // Cache miss or baseSha mismatch → fall back to a fresh pass.
   const ctx = { epicId, provider };
   let state = {};
   let cacheStatus = 'miss';
   const cached = await readPreflightCache({ epicId, cwd });
   if (cached) {
     const freshEpic = await provider.getTicket(epicId);
-    const freshBaseSha = computeBaseSha(freshEpic);
+    const cachedStoryIds = cached.stories
+      .map((s) => Number(s?.id ?? s?.number))
+      .filter((id) => Number.isInteger(id) && id > 0);
+    const freshStories = await Promise.all(
+      cachedStoryIds.map((id) => provider.getTicket(id)),
+    );
+    const freshBaseSha = computeBaseSha(freshEpic, freshStories);
     if (freshBaseSha === cached.baseSha) {
       state = {
         epic: cached.epic,

package/.agents/scripts/epic-execute-record-wave.js

@@ -42,7 +42,7 @@ import { getRunners } from './lib/config/runners.js';
 import { resolveConfig } from './lib/config-resolver.js';
 import { Logger } from './lib/Logger.js';
 import * as epicRunStateStore from './lib/orchestration/epic-run-state-store.js';
-import { upsertEpicRunProgress } from './lib/orchestration/epic-runner/progress-reporter.js';
+import { upsertEpicRunProgress } from './lib/orchestration/epic-runner/progress-reporter/composition.js';
 import {
   emitStoryDispatchEnd,
   storyStatusToDispatchOutcome,

package/.agents/scripts/evidence-gate.js

@@ -47,9 +47,9 @@
 import { spawnSync } from 'node:child_process';
 import { parseArgs } from 'node:util';
 import { runAsCli } from './lib/cli-utils.js';
-import { PROJECT_ROOT } from './lib/config-resolver.js';
 import { gitSpawn } from './lib/git-utils.js';
 import { Logger } from './lib/Logger.js';
+import { PROJECT_ROOT } from './lib/project-root.js';
 import {
   hashCommandConfig,
   recordPass,

package/.agents/scripts/git-rebase-and-resolve.js

@@ -40,9 +40,9 @@
 
 import { parseArgs } from 'node:util';
 import { runAsCli } from './lib/cli-utils.js';
-import { PROJECT_ROOT } from './lib/config-resolver.js';
 import { gitSpawn } from './lib/git-utils.js';
 import { Logger } from './lib/Logger.js';
+import { PROJECT_ROOT } from './lib/project-root.js';
 
 function currentBranch(cwd) {
   const res = gitSpawn(cwd, 'rev-parse', '--abbrev-ref', 'HEAD');

package/.agents/scripts/hierarchy-gate.js

@@ -42,6 +42,13 @@ import { resolveConfig } from './lib/config-resolver.js';
 import { Logger } from './lib/Logger.js';
 import { CONTEXT_LABELS, TYPE_LABELS } from './lib/label-constants.js';
 import { createProvider } from './lib/provider-factory.js';
+import { concurrentMap } from './lib/util/concurrent-map.js';
+
+/**
+ * Bounded fan-out for per-level `getSubTickets` calls. Matches the
+ * wave-record-io.js precedent (Story #3024).
+ */
+const SUB_TICKET_FETCH_CONCURRENCY = 4;
 
 function classify(ticket) {
   const labels = ticket.labels ?? [];
@@ -70,22 +77,35 @@ function ticketIsComplete(ticket) {
  */
 async function collectDescendants(provider, epicId) {
   const visited = new Set([epicId]);
-  const queue = [epicId];
   const out = [];
-  while (queue.length > 0) {
-    const parentId = queue.shift();
-    let children;
-    try {
-      children = await provider.getSubTickets(parentId);
-    } catch (err) {
-      throw new Error(`getSubTickets(#${parentId}) failed: ${err.message}`);
-    }
-    for (const child of children) {
-      if (visited.has(child.id)) continue;
-      visited.add(child.id);
-      out.push(child);
-      queue.push(child.id);
+  // Level-order BFS: each round fetches the whole frontier's children with a
+  // bounded-parallel map instead of one awaited round-trip per node. Stories
+  // are 3-tier leaves (no sub-issues by contract), so they are never expanded
+  // — that skip alone removes the largest class of wasted GraphQL calls.
+  let frontier = [epicId];
+  while (frontier.length > 0) {
+    const levels = await concurrentMap(
+      frontier,
+      async (parentId) => {
+        try {
+          return await provider.getSubTickets(parentId);
+        } catch (err) {
+          throw new Error(`getSubTickets(#${parentId}) failed: ${err.message}`);
+        }
+      },
+      { concurrency: SUB_TICKET_FETCH_CONCURRENCY },
+    );
+    const next = [];
+    for (const children of levels) {
+      for (const child of children) {
+        if (visited.has(child.id)) continue;
+        visited.add(child.id);
+        out.push(child);
+        const labels = child.labels ?? [];
+        if (!labels.includes(TYPE_LABELS.STORY)) next.push(child.id);
+      }
     }
+    frontier = next;
   }
   return out;
 }