simt-dev 0.6.2 → 0.7.0

package/src/commands/upgrade.mjs

@@ -21,14 +21,20 @@
 //   4. A repo it could not upgrade is reported loudly and fails the run. A repo left
 //      silently behind is the failure `compare` exists to surface, and this command must
 //      not be the thing that creates it.
+//   5. With no root named, it upgrades THIS repository only. The workspace is a claim
+//      about scope, so it needs `--all` or an explicit root (review 0003 Q33): the old
+//      default resolved the workspace and a dry run inside one repo planned all sixteen.
 
-import { mkdir, writeFile } from 'node:fs/promises';
+import { mkdir } from 'node:fs/promises';
+import { commitJournal, journaledWriteFile } from '../journal.mjs';
+import { invalidateCheckCache } from '../status.mjs';
 
 import { basename, dirname, resolve } from 'node:path';
 
 import { EXIT, emit, emitJson, fail, isJson, note, writeMode } from '../output/index.mjs';
 import { provenanceDigest, plan } from '../projection/project.mjs';
-import { MANIFEST, MANIFEST_COMMENT, readManifest, writeManifest } from '../projection/manifest.mjs';
+import { MANIFEST, MANIFEST_COMMENT, manifestPath, manifestText, readManifest, writeManifest } from '../projection/manifest.mjs';
+import { diffField, emitDiffs, readBefore } from '../diff.mjs';
 import { FAULT_STATES, planUpgrade, summariseUpgrade } from '../upgrade/plan.mjs';
 import { discover } from '../compare/discover.mjs';
 import { resolveWorkspace, targetRoot, WORKSPACE_REMEDY } from '../workspace.mjs';
@@ -52,12 +58,41 @@ export async function upgradeCommand(positional, flags) {
     }
   }
 
-  const target = await targetRoot(flags, positional);
+  // `--root`, a positional, and `--workspace` are all explicit claims about scope.
+  // Anything else is the enclosing repository, below.
+  const target = explicit || flags.workspace
+    ? await targetRoot(flags, positional)
+    : await (
+        // No root named: the scope is THIS repository, not the workspace. The old
+        // default resolved the workspace and swept every sibling - 16 repos planned
+        // from a dry run inside one of them. A workspace is a claim about scope, so
+        // it now needs `--all` or an explicit root, the way `--all` always did.
+        //
+        // The note fires only when the old default would have planned a different
+        // directory: a configured workspace that is not this repo. No workspace, or
+        // one equal to the cwd, changes nothing - and a note about an unchanged
+        // behaviour is noise.
+        (async () => {
+          const ws = await resolveWorkspace(flags);
+          if (ws.root && resolve(ws.root) !== process.cwd()) {
+            note(`note     the default scope is this repository; the workspace at ${ws.root} is not upgraded. Pass --root ${ws.root} (or --all) to upgrade it`);
+          }
+          return { root: process.cwd(), source: 'default', detail: 'the enclosing repository', ws };
+        })()
+      );
   const root = resolve(target.root);
   const found = await discover(root);
   if (found.error) {
     return fail(`${root}: ${found.error}`, EXIT.CONFIG, 'pass --root <path>');
   }
+  if (found.repos.length === 0 && found.worktrees.length === 1) {
+    // A worktree passed directly is not counted as a repo by discover (its files are
+    // its parent's HEAD checked out elsewhere, so drift reporting would double-count
+    // it). Upgrading is different: the worktree carries the same rule content as its
+    // parent, so it is a valid single target. This is the shape the pre-push gate
+    // materializes - a detached worktree at HEAD that the suite runs inside.
+    found.repos = [found.worktrees[0].path];
+  }
   if (found.repos.length === 0) {
     return fail(
       `${root} contains no git repositories`,
@@ -69,13 +104,57 @@ export async function upgradeCommand(positional, flags) {
   const sha = await provenanceDigest();
   const mode = writeMode(flags);
   const plans = [];
+  // The plan inputs, kept because the diff is built from them: `planUpgrade`
+  // keeps the verdict, not the bytes, and the apply path below re-plans per
+  // repo rather than reusing this loop's targets.
+  const inputs = new Map();
   for (const repo of found.repos) {
     const { manifest, exists, error } = await readManifest(repo);
     const result = await plan(repo);
+    inputs.set(repo, { targets: result.targets, manifest });
     plans.push(planUpgrade({ name: basename(repo), path: repo, manifest, manifestExists: exists, manifestError: error, targets: result.targets, sha }));
   }
   const summary = summariseUpgrade(plans);
 
+  // The `--diff` pairs, read before anything is written so the before side is
+  // true in preview and in apply alike (R50). Labels carry the repo name: one
+  // run diffs N repositories, and a bare filename would not say which. The
+  // manifest after-bytes are built the same way the apply path builds them —
+  // chosen keys kept, `$comment` refreshed, pin moved — so the diff shows the
+  // write rather than a second opinion about it.
+  const diffs =
+    flags.diff === true
+      ? (
+          await Promise.all(
+            plans
+              .filter((p) => p.action === 'updated')
+              .map(async (p) => {
+                const input = inputs.get(p.path) ?? { targets: [], manifest: null };
+                const pairs = await Promise.all(
+                  input.targets
+                    .filter((t) => t.action !== 'unchanged' && t.action !== 'malformed')
+                    .map(async (t) => ({
+                      path: `${p.name}/${t.file}`,
+                      before: await readBefore(t.path),
+                      after: t.text,
+                    })),
+                );
+                const { $comment, ...chosen } = input.manifest ?? {};
+                pairs.push({
+                  path: `${p.name}/${MANIFEST_FILE}`,
+                  before: await readBefore(await manifestPath(p.path)),
+                  after: manifestText({
+                    ...MANIFEST_COMMENT,
+                    ...chosen,
+                    projection: { ...(input.manifest?.projection ?? {}), simtDevSha: sha },
+                  }),
+                });
+                return pairs;
+              }),
+          )
+        ).flat()
+      : [];
+
   // Writes happen BEFORE the report, in every output mode. An earlier version emitted
   // the JSON payload and returned, which meant `--yes --json` reported a plan and
   // changed nothing - the exact combination a script uses for automation.
@@ -96,11 +175,14 @@ export async function upgradeCommand(positional, flags) {
         // Every planned target, not just AGENTS.md: a repo can have a current AGENTS.md
         // and three stale `.mdc` rules, and restamping only the first leaves `check` red
         // straight after a successful upgrade.
+        // One journal set per repo: a set belongs to one repository, and an
+        // `undo` in one consumer must never reach into another (R49).
+        const journal = [];
         const { targets } = await plan(p.path);
         for (const t of targets) {
           if (t.action === 'unchanged' || t.action === 'malformed') continue;
           await mkdir(dirname(t.path), { recursive: true });
-          await writeFile(t.path, t.text);
+          await journaledWriteFile(p.path, journal, t.path, t.text);
           writtenFiles.add(t.file);
         }
         const { manifest } = await readManifest(p.path);
@@ -110,11 +192,20 @@ export async function upgradeCommand(positional, flags) {
         // forever, because `sync` does not own the manifest and nothing else rewrites
         // it. An adopted repo would never have corrected it.
         const { $comment, ...chosen } = manifest ?? {};
-        await writeManifest(p.path, {
-          ...MANIFEST_COMMENT,
-          ...chosen,
-          projection: { ...(manifest?.projection ?? {}), simtDevSha: sha },
-        });
+        await writeManifest(
+          p.path,
+          {
+            ...MANIFEST_COMMENT,
+            ...chosen,
+            projection: { ...(manifest?.projection ?? {}), simtDevSha: sha },
+          },
+          journal,
+        );
+        await commitJournal(p.path, 'upgrade', journal);
+        // The pin and regions moved: the last `check` of this repo no longer
+        // describes it (R48). Gated on the journal: an untouched repo keeps
+        // its record.
+        if (journal.length > 0) await invalidateCheckCache(p.path);
         applied.push(p.name);
       } catch (error) {
         // Reported per repo rather than thrown: one unwritable repo must not hide the
@@ -133,6 +224,7 @@ export async function upgradeCommand(positional, flags) {
     source: target.source,
     sha,
     dryRun: !mode.apply,
+    ...diffField(diffs, flags),
     written: applied.length > 0,
     summary: { ...summary, applied, failed },
     plans,
@@ -144,6 +236,8 @@ export async function upgradeCommand(positional, flags) {
   }
 
   emit(render(plans, summary, { root, shape: found.shape, source: target.source, sha, applied, failed }));
+  // After the report: the report says what, the diff shows it (R50).
+  emitDiffs(diffs, flags);
 
   for (const w of found.worktrees) {
     // The same reasoning as `compare`: a worktree is its parent's HEAD elsewhere, so

package/src/commands/why.mjs

@@ -13,6 +13,7 @@ import { promisify } from 'node:util';
 import { EXIT, emit, emitJson, fail, isJson } from '../output/index.mjs';
 import { CLI, MANIFEST_FILE } from '../name.mjs';
 import { FORMATTABLE, GATES } from '../hooks/gates.mjs';
+import { decisionsDir } from '../decisions/dir.mjs';
 import {
   decisionHits,
   scopeHits,
@@ -67,8 +68,10 @@ function reportUnresolved(root, flags, unresolved) {
 // the critic's brief resolves governance the same way without a second copy.
 export async function tracked(root) {
   try {
-    const { stdout } = await exec('git', ['ls-files'], { cwd: root, maxBuffer: 16 << 20 });
-    return { files: stdout.split('\n').filter(Boolean) };
+    // `-z`: without it git C-quotes a non-ASCII path and the reader's real
+    // filename never matches it (review 0003 Q39).
+    const { stdout } = await exec('git', ['ls-files', '-z'], { cwd: root, maxBuffer: 16 << 20 });
+    return { files: stdout.split('\0').filter(Boolean) };
   } catch (error) {
     return {
       error: fail(
@@ -81,10 +84,13 @@ export async function tracked(root) {
 }
 
 export async function decisionRecords(root) {
-  const dir = join(root, 'docs', 'decisions');
+  // Q55: the repository's own records, wherever it keeps them — not a hard-coded path.
+  const dir = join(root, await decisionsDir(root));
   let names = [];
   try {
-    names = (await readdir(dir)).filter((name) => /^ADR-\d{3,}-.*\.md$/i.test(name)).sort();
+    names = (await readdir(dir))
+      .filter((name) => /^ADR-\d{3,}-.*\.md$/i.test(name))
+      .sort((a, b) => Number(/^ADR-(\d{3,})/i.exec(a)[1]) - Number(/^ADR-(\d{3,})/i.exec(b)[1]));
   } catch {
     return [];
   }

package/src/compare/hooksstate.mjs

@@ -14,6 +14,25 @@ import { promisify } from 'node:util';
 import { CHAIN_MARKER, EVENTS, HOOKS_DIR, HOOKS_PATH_KEY, SHIM_MARKER, fileFor, renderChainedShim, renderShim } from '../hooks/shim.mjs';
 import { foreignHooks, resolveHooksDir } from '../hooks/where.mjs';
 import { packageVersion, hasNpm } from '../package-version.mjs';
+import { resolveNodeRunner } from '../ecosystem/node-runner.mjs';
+import { fingerprint } from '../resolve/fingerprint.mjs';
+
+/**
+ * The Node manager id for this repository, or null without a package.json.
+ * Lockfile first, `packageManager` next — the one resolver (review 0003 Q31).
+ */
+async function nodeManagerFor(root) {
+  if (!(await hasNpm(root))) return null;
+  const detected = await fingerprint(root);
+  let packageManager = null;
+  try {
+    const pkg = JSON.parse(await readFile(join(root, 'package.json'), 'utf8'));
+    if (typeof pkg.packageManager === 'string') packageManager = pkg.packageManager;
+  } catch {
+    // Unreadable here leaves the npm default; the manifest path reports it.
+  }
+  return resolveNodeRunner({ facts: detected.facts, packageManager }).id;
+}
 
 const exec = promisify(execFile);
 
@@ -149,7 +168,10 @@ async function describeShim(path, root) {
       const chain = await readChainedShim(path);
       stale = chain === null || content !== renderChainedShim(chain.event, chain.target);
     } else {
-      stale = content !== renderShim(basename(path), { npm: await hasNpm(root), version: packageVersion() });
+      // Q31: the comparison renders with the repo's own manager, or a pnpm repo
+      // reads as stale the moment this tool ships — the same one-answer rule as
+      // the install path above.
+      stale = content !== renderShim(basename(path), { npm: await hasNpm(root), manager: await nodeManagerFor(root), version: packageVersion() });
     }
   } catch {
     stale = true;

package/src/compare/learn.mjs

@@ -13,17 +13,24 @@
 // every ADR draft are byte-identical (no wall-clock timestamps, fixed sorting and
 // rounding).
 
-import { readFile } from 'node:fs/promises';
+import { createHash } from 'node:crypto';
 import { basename, join } from 'node:path';
+import { mapCapped, DEFAULT_CONCURRENCY } from './parallel.mjs';
 
 import { policiesFor } from '../agenthooks/policy.mjs';
+import { DEL_R_TOLERANCE, parseAblationArmName } from '../bench/ablate.mjs';
 import { compareArms, evaluateRunRecord, loadPrices, loadRunRecords } from '../bench/report.mjs';
 import { GATES } from '../hooks/gates.mjs';
 import { readLedger } from '../ledger/index.mjs';
 import { readLessonCandidates } from '../memory/lessons.mjs';
+import { STATE_DIR } from '../name.mjs';
 import { readManifest } from '../projection/manifest.mjs';
+import { localRel, readStateFile } from '../state.mjs';
 
-const DEL_R_TOLERANCE = 0.01;
+const ABLATION_REL = localRel('bench', 'ablation.json');
+// Where pre-Q19 checkouts keep the file: the writer's path before the move to
+// machine-local state (review 0003 Q50).
+const ABLATION_REL_LEGACY = join(STATE_DIR, 'bench', 'ablation.json');
 
 const POLICY_BY_ID = new Map(policiesFor('pre-tool-use').map((p) => [p.id, p]));
 const POLICY_BY_ADR = new Map(policiesFor('pre-tool-use').map((p) => [p.adr, p]));
@@ -78,7 +85,7 @@ export function classifyGateCommand(cmd, manifest = null) {
   for (const gate of GATE_ENTRIES) {
     if (gate.kind === 'script' && gate.script) {
       const scriptRe = new RegExp(`(?:^|\\s)npm\\s+run(?:\\s+--silent)?\\s+${gate.script}(?:\\s|$)`);
-      if (scriptRe.test(raw) || (gate.script === 'test' && /\b(?:npm\s+test|node\s+--test|pytest|go\s+test)\b/.test(raw))) {
+      if (scriptRe.test(raw) || (gate.script === 'test' && /\b(?:npm\s+test|node\s+--test|pytest|go\s+test|cargo\s+test)\b/.test(raw))) {
         return { gate: gate.name, adr: gate.adr };
       }
     }
@@ -162,21 +169,17 @@ export function classifyRuleViolations(candidate) {
   return [...found.values()];
 }
 
-function parseAblatedSectionArm(arm) {
-  const raw = String(arm ?? '');
-  if (raw.startsWith('no-core-')) {
-    const slug = raw.slice('no-core-'.length);
-    return { sectionId: `core:${slug}`, arm: raw, kind: 'core', targetId: slug, affects: ['rules/core.md'] };
-  }
-  if (raw.startsWith('no-profile-')) {
-    const id = raw.slice('no-profile-'.length);
-    return { sectionId: `profile:${id}`, arm: raw, kind: 'profile', targetId: id, affects: [`rules/stacks/${id}.md`] };
-  }
-  if (raw.startsWith('no-process-')) {
-    const id = raw.slice('no-process-'.length);
-    return { sectionId: `process:${id}`, arm: raw, kind: 'process', targetId: id, affects: [`rules/mdc/${id}.mdc`] };
+async function readExplicitNoValueSections(repoPath) {
+  const { text } = await readStateFile(repoPath, ABLATION_REL, [ABLATION_REL_LEGACY]).catch(() => ({
+    text: null,
+  }));
+  if (text === null) return [];
+  try {
+    const raw = JSON.parse(text);
+    return Array.isArray(raw?.sections) ? raw.sections : Array.isArray(raw) ? raw : [];
+  } catch {
+    return [];
   }
-  return null;
 }
 
 async function collectRepoAblationRecords(repoPath) {
@@ -188,17 +191,6 @@ async function collectRepoAblationRecords(repoPath) {
   return records.map((rec) => evaluateRunRecord(rec, prices));
 }
 
-async function readExplicitNoValueSections(repoPath) {
-  const file = join(repoPath, '.simt', 'ablation.json');
-  try {
-    const raw = JSON.parse(await readFile(file, 'utf8'));
-    const list = Array.isArray(raw?.sections) ? raw.sections : Array.isArray(raw) ? raw : [];
-    return list;
-  } catch {
-    return [];
-  }
-}
-
 function formatAffectsList(affects) {
   const sorted = [...new Set(affects.map(String).filter(Boolean))].sort();
   return sorted.length > 0 ? `[${sorted.map((a) => JSON.stringify(a)).join(', ')}]` : '[]';
@@ -270,9 +262,55 @@ export function renderAdrDraft({
  *   adrDrafts: Array<{id: string, category: string, target: string, title: string, affects: string[], supersedes: Array<{adr: string, ruling: number|null}>, markdown: string}>
  * }>}
  */
+/**
+ * Digest-keyed memo of estate learning (review 0003 Q38).
+ *
+ * The bootstrap comparisons below are pure over the records on disk, so a
+ * second `compare` with unchanged inputs recomputes nothing. Keyed by digest,
+ * not by time, so a changed record can never read a stale answer. In-process
+ * only: the MCP server is long-lived and repeats the call per session, while a
+ * CLI run pays one computation anyway. Bounded, because estates differ.
+ */
+const learningCache = new Map();
+const LEARNING_CACHE_MAX = 8;
+
+export function clearLearningCache() {
+  learningCache.clear();
+}
+
 export async function learnAcrossEstate(repos) {
   const sortedRepos = [...(repos ?? [])].sort();
 
+  // Collection first, capped and parallel: one repo's five reads overlap the
+  // next repo's, and the aggregation below stays sequential over sorted input
+  // so the output cannot depend on completion order.
+  const collected = await mapCapped(
+    sortedRepos,
+    async (repoPath) => {
+      const [manifestRes, ledgerRes, lessonsRes, benchEvaluated, explicitAblation] = await Promise.all([
+        readManifest(repoPath).catch(() => ({ manifest: null })),
+        readLedger(repoPath).catch(() => ({ entries: [] })),
+        readLessonCandidates(repoPath).catch(() => ({ candidates: [] })),
+        collectRepoAblationRecords(repoPath),
+        readExplicitNoValueSections(repoPath),
+      ]);
+      return {
+        repoPath,
+        repoName: basename(repoPath),
+        manifest: manifestRes?.manifest ?? null,
+        ledgerEntries: ledgerRes?.entries ?? [],
+        candidates: lessonsRes?.candidates ?? [],
+        benchEvaluated,
+        explicitAblation,
+      };
+    },
+    { concurrency: DEFAULT_CONCURRENCY },
+  );
+
+  const digest = createHash('sha1').update(JSON.stringify(collected)).digest('hex');
+  const cached = learningCache.get(digest);
+  if (cached) return cached;
+
   const ruleViolations = new Map();
   const gateStats = new Map();
   const ablationByArm = new Map();
@@ -284,19 +322,7 @@ export async function learnAcrossEstate(repos) {
   let totalLedgerRuns = 0;
   let totalHookDenials = 0;
 
-  for (const repoPath of sortedRepos) {
-    const repoName = basename(repoPath);
-    const [manifestRes, ledgerRes, lessonsRes, benchEvaluated, explicitAblation] = await Promise.all([
-      readManifest(repoPath).catch(() => ({ manifest: null })),
-      readLedger(repoPath).catch(() => ({ entries: [] })),
-      readLessonCandidates(repoPath).catch(() => ({ candidates: [] })),
-      collectRepoAblationRecords(repoPath),
-      readExplicitNoValueSections(repoPath),
-    ]);
-
-    const manifest = manifestRes?.manifest ?? null;
-    const ledgerEntries = ledgerRes?.entries ?? [];
-    const candidates = lessonsRes?.candidates ?? [];
+  for (const { repoName, manifest, ledgerEntries, candidates, benchEvaluated, explicitAblation } of collected) {
 
     if (ledgerEntries.length > 0) reposWithLedgers += 1;
     totalLedgerRuns += ledgerEntries.length;
@@ -357,7 +383,7 @@ export async function learnAcrossEstate(repos) {
       const tagged = { ...row, task: `${repoName}:${row.task}` };
       if (row.arm === 'current') {
         currentRunsAll.push(tagged);
-      } else if (parseAblatedSectionArm(row.arm)) {
+      } else if (parseAblationArmName(row.arm)) {
         const list = ablationByArm.get(row.arm) ?? [];
         list.push({ row: tagged, repoName });
         ablationByArm.set(row.arm, list);
@@ -415,7 +441,7 @@ export async function learnAcrossEstate(repos) {
   const noValueMap = new Map();
 
   for (const [arm, entries] of [...ablationByArm.entries()].sort((a, b) => a[0].localeCompare(b[0]))) {
-    const parsed = parseAblatedSectionArm(arm);
+    const parsed = parseAblationArmName(arm);
     if (!parsed || currentRunsAll.length === 0) continue;
     const ablatedRuns = entries.map((e) => e.row);
     const cmp = compareArms(arm, ablatedRuns, 'current', currentRunsAll);
@@ -423,11 +449,11 @@ export async function learnAcrossEstate(repos) {
     const dR = round4(cmp.deltas.R);
     const dC = round4(cmp.deltas.C);
     if (dR <= DEL_R_TOLERANCE && dC > 0) {
-      noValueMap.set(parsed.sectionId, {
-        sectionId: parsed.sectionId,
-        kind: parsed.kind,
-        targetId: parsed.targetId,
-        affects: parsed.affects,
+      noValueMap.set(parsed.ablate.sectionId, {
+        sectionId: parsed.ablate.sectionId,
+        kind: parsed.ablate.kind,
+        targetId: parsed.ablate.targetId,
+        affects: [parsed.ablate.sectionId],
         dR,
         dC,
         tasks: cmp.pairedTasks,
@@ -444,12 +470,6 @@ export async function learnAcrossEstate(repos) {
     const isCandidate = sec.deletionCandidate === true || (sec.measured !== false && dR <= DEL_R_TOLERANCE && dC > 0);
     if (!isCandidate) continue;
     const [kind = 'core', targetId = sectionId] = sectionId.split(':');
-    const affects =
-      kind === 'profile'
-        ? [`rules/stacks/${targetId}.md`]
-        : kind === 'process'
-          ? [`rules/mdc/${targetId}.mdc`]
-          : ['rules/core.md'];
     const existing = noValueMap.get(sectionId);
     if (existing) {
       existing.repos = [...new Set([...existing.repos, repoName])].sort();
@@ -458,7 +478,7 @@ export async function learnAcrossEstate(repos) {
         sectionId,
         kind,
         targetId,
-        affects,
+        affects: [sectionId],
         dR,
         dC,
         tasks: Number(sec.tasks ?? 1),
@@ -584,7 +604,7 @@ export async function learnAcrossEstate(repos) {
 
   for (const s of noValueRules) {
     const rawEntry = noValueMap.get(s.sectionId);
-    const affects = rawEntry?.affects ?? ['rules/core.md'];
+    const affects = rawEntry?.affects ?? [s.sectionId];
     const draftId = nextDraftId();
     const title = `Prune or demote zero-value section "${s.sectionId}" (dR=${s.dR}, dC=+$${s.dC})`;
     const context =
@@ -616,7 +636,7 @@ export async function learnAcrossEstate(repos) {
     });
   }
 
-  return {
+  const result = {
     reposWithLedgers,
     reposWithDenials,
     totalLedgerRuns,
@@ -627,6 +647,11 @@ export async function learnAcrossEstate(repos) {
     noValueRules,
     adrDrafts,
   };
+  if (learningCache.size >= LEARNING_CACHE_MAX) {
+    learningCache.delete(learningCache.keys().next().value);
+  }
+  learningCache.set(digest, result);
+  return result;
 }
 
 /**

package/src/compare/parallel.mjs

@@ -0,0 +1,50 @@
+// Capped parallelism for estate-wide work (review 0003 Q38).
+//
+// Two callers need it - row building and estate learning - and a third copy of
+// the same worker pool would be the defect ADR-002 names, so it lives here.
+// Order-preserving: results land at their input index, because both callers
+// diff their output between runs and completion order would scramble it.
+
+/**
+ * How many estate items to work on at once.
+ *
+ * The work is process-spawn bound (git, file reads), so unbounded parallelism
+ * is a burst of subprocesses with no speedup, and sequential work is what took
+ * `compare` 48 s over MCP for 17 repos. Four overlaps the wait while keeping
+ * the burst bounded.
+ */
+export const DEFAULT_CONCURRENCY = 4;
+
+export function resolveConcurrency(flags = {}) {
+  const raw = flags?.concurrency ?? process.env.SIMT_CONCURRENCY ?? DEFAULT_CONCURRENCY;
+  const n = typeof raw === 'number' ? raw : parseInt(String(raw), 10);
+  return Number.isFinite(n) && n >= 1 ? Math.floor(n) : DEFAULT_CONCURRENCY;
+}
+
+/**
+ * Map `items` through async `fn` with at most `concurrency` in flight.
+ *
+ * @param {unknown[]} items
+ * @param {(item: unknown, index: number) => Promise<unknown>} fn
+ * @param {{concurrency?: number, signal?: AbortSignal|null, onItem?: ((done: number, total: number) => void)|null}} options
+ * @returns {Promise<unknown[]>} results in input order
+ * @throws the first worker failure, or a CANCELLED error when `signal` aborts
+ */
+export async function mapCapped(items, fn, { concurrency = DEFAULT_CONCURRENCY, signal = null, onItem = null } = {}) {
+  const list = [...(items ?? [])];
+  const out = new Array(list.length);
+  const cap = Number.isFinite(concurrency) && concurrency >= 1 ? Math.floor(concurrency) : DEFAULT_CONCURRENCY;
+  let next = 0;
+  let done = 0;
+  async function worker() {
+    while (next < list.length) {
+      if (signal?.aborted) throw Object.assign(new Error('cancelled by client'), { code: 'CANCELLED' });
+      const i = next++;
+      out[i] = await fn(list[i], i);
+      done += 1;
+      if (onItem) onItem(done, list.length);
+    }
+  }
+  await Promise.all(Array.from({ length: Math.min(cap, list.length) }, () => worker()));
+  return out;
+}

package/src/compare/row.mjs

@@ -16,6 +16,7 @@
 // fact per line in a stable field order so two runs diff cleanly; a row that
 // reordered its columns would make every comparison between two runs unreadable.
 
+import { mapCapped, DEFAULT_CONCURRENCY, resolveConcurrency } from './parallel.mjs';
 import { checkTargets, PRIMARY_TARGET } from '../projection/project.mjs';
 import { manifestDrift, readManifest } from '../projection/manifest.mjs';
 import { loadRules, select } from '../projection/rules.mjs';
@@ -74,7 +75,8 @@ function packageEntry(f) {
   return { path: f.file, profiles: f.profiles ?? [], status: f.status, detail: f.detail ?? null };
 }
 
-export async function buildRow(path, context) {  const name = path.split('/').filter(Boolean).pop() ?? path;
+export async function buildRow(path, context) {
+  const name = path.split('/').filter(Boolean).pop() ?? path;
   const problems = [];
   const notes = [];
 
@@ -354,6 +356,29 @@ export async function buildRow(path, context) {  const name = path.split('/').fi
   return row;
 }
 
+export { DEFAULT_CONCURRENCY, resolveConcurrency } from './parallel.mjs';
+
+/**
+ * Every row, in input order, built with at most `concurrency` in flight.
+ *
+ * A thrown row is impossible - `buildRow` never rejects - so the first error
+ * aborts, because a pool that swallows the one failure mode its worker cannot
+ * produce is decoration. `onBatch(done, total)` fires after each row for MCP
+ * `notifications/progress`; `signal` aborts between rows for
+ * `notifications/cancelled`.
+ */
+export async function buildRows(
+  paths,
+  context,
+  { concurrency = DEFAULT_CONCURRENCY, signal = null, onBatch = null } = {},
+) {
+  return mapCapped(paths, (p) => buildRow(p, context), {
+    concurrency,
+    signal,
+    onItem: onBatch,
+  });
+}
+
 function declaredGates(manifest) {
   if (!manifest) return [];
   return [...(manifest.gates?.preCommit ?? []), ...(manifest.gates?.prePush ?? [])];