simt-dev 0.6.3 → 0.7.0

package/src/commands/tests.mjs

@@ -13,7 +13,7 @@ import { promisify } from 'node:util';
 import { EXIT, emit, emitJson, fail, isJson } from '../output/index.mjs';
 import { CLI } from '../name.mjs';
 import { isTestPath } from '../bench/mine.mjs';
-import { blobTexts, langOf, readEdges, readFiles, reindex } from '../index/store.mjs';
+import { blobTexts, isIndexStale, langOf, readEdges, readFiles, reindex } from '../index/store.mjs';
 import { HISTORY, importsOf, parseCoverage, testEdges, testsFor } from '../index/tests.mjs';
 
 const exec = promisify(execFile);
@@ -84,7 +84,10 @@ function summarise(root, flags, edges) {
 
 async function loadFiles(root) {
   let files = await readFiles(root);
-  if (files.length === 0) {
+  // An empty index has nothing to answer from; a stale one has yesterday's
+  // tree (review 0003 Q42). Either way the refresh is incremental, so a
+  // current repository pays for one `git ls-files -s`, not a rebuild.
+  if (files.length === 0 || (await isIndexStale(root))) {
     try {
       await reindex(root);
     } catch (error) {

package/src/commands/undo.mjs

@@ -1,9 +1,10 @@
 // `simt undo [--yes] [--json]`
 //
 // Restore the last journaled set of writes (plan 0003 R49): every file the last
-// writing run changed goes back to its pre-run bytes, and files the run created
-// are deleted. A run that wrote nothing leaves no set, so there is nothing to
-// restore and the command says so.
+// writing run changed goes back to its pre-run bytes, files the run created
+// are deleted, and git config keys the run set go back to their pre-run
+// values (review 0003 Q22). A run that wrote nothing leaves no set, so there
+// is nothing to restore and the command says so.
 //
 // The safety is the journal's, not the flag's: when any file in the set no
 // longer matches the bytes the run left, the whole undo is refused — restoring
@@ -12,7 +13,7 @@
 
 import { EXIT, emit, emitJson, isJson, writeMode } from '../output/index.mjs';
 import { CLI } from '../name.mjs';
-import { listJournalSets, readJournalSet, undoLastJournalSet } from '../journal.mjs';
+import { beforeText, entryLabel, listJournalSets, readGitValue, readJournalSet, undoLastJournalSet } from '../journal.mjs';
 import { diffField, emitDiffs, readBefore } from '../diff.mjs';
 import { join } from 'node:path';
 import { invalidateCheckCache } from '../status.mjs';
@@ -32,30 +33,37 @@ export async function undoCommand(positional, flags) {
   }
 
   const set = await readJournalSet(root, id);
-  const paths = set.entries.map((e) => e.path);
+  const labels = set.entries.map(entryLabel);
   // The `--diff` pairs: what the tree holds now against what the restore
-  // would put back. A null beforeBytes is a file the run created, so the
-  // restore deletes it — the after side is empty (R50).
+  // would put back. A null before is a file the run created (or a key it
+  // set from unset), so the restore deletes it — the after side is empty
+  // (R50).
   const diffs =
     flags.diff === true
       ? await Promise.all(
-        set.entries.map(async (e) => ({
-          path: e.path,
-          before: await readBefore(join(root, e.path)),
-          after: e.beforeBytes ?? null,
-        })),
+        set.entries.map(async (e) => {
+          if (e.kind === 'git-config') {
+            return { path: entryLabel(e), before: await readGitValue(root, e.key), after: e.before ?? null };
+          }
+          return { path: e.path, before: await readBefore(join(root, e.path)), after: beforeText(e) };
+        }),
       )
       : [];
 
   if (!mode.apply) {
     if (isJson(flags)) {
-      emitJson({ ok: true, command: 'undo', root, set: id, restores: paths, dryRun: true, ...diffField(diffs, flags) });
+      emitJson({ ok: true, command: 'undo', root, set: id, restores: labels, dryRun: true, ...diffField(diffs, flags) });
       return EXIT.OK;
     }
+    const files = set.entries.filter((e) => e.kind !== 'git-config').length;
+    const keys = set.entries.length - files;
     emit(
-      [`last write  ${set.command} (${id})`, ...paths.map((p) => `restore   ${p}`), '', `would restore ${paths.length} file(s); apply with: ${CLI} undo --yes`].join(
-        '\n',
-      ),
+      [
+        `last write  ${set.command} (${id})`,
+        ...labels.map((p) => `restore   ${p}`),
+        '',
+        `would restore ${files} file(s)${keys > 0 ? ` and ${keys} git config key(s)` : ''}; apply with: ${CLI} undo --yes`,
+      ].join('\n'),
       { maxBytes: flags.maxBytes ?? 0 },
     );
     // After the report: the report says what, the diff shows it (R50).

package/src/commands/upgrade.mjs

@@ -21,6 +21,9 @@
 //   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 } from 'node:fs/promises';
 import { commitJournal, journaledWriteFile } from '../journal.mjs';
@@ -55,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`,

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 ?? [])];

package/src/completions.mjs

@@ -125,6 +125,11 @@ function renderZsh({ top, groups }) {
     '# source this after compinit: `source <(simt completions zsh)`.',
     '_simt() {',
     '  local cur prev',
+    // compsys sets `words` and `CURRENT` before the function runs; without the
+    // assignment `cur` and `prev` stay empty, so the flag and value-flag cases
+    // below never match and zsh completes only positionals (review 0003 Q51).
+    '  cur=${words[CURRENT]}',
+    '  prev=${words[CURRENT-1]}',
     '  local -a top flags subs',
     `  top=( ${top.join(' ')} )`,
     `  flags=( ${FLAGS.join(' ')} )`,

package/src/decisions/dir.mjs

@@ -0,0 +1,84 @@
+// The one answer to "where are this repository's decision records" (review 0003 Q55).
+//
+// Before this, every reader hard-coded `docs/decisions` while detection already
+// knew four spellings (`docs/decisions`, `docs/adr`, `docs/adrs`, `adr`), so a
+// repository that kept its records under `docs/adr/` was fingerprinted correctly
+// and then unread by every command. One resolution, every reader.
+//
+// Precedence is declaration first. A manifest `decisions.dir` names the directory
+// relative to the repository root; without one, the first existing candidate
+// wins; without any, the default is `docs/decisions`. The cutoff below answers
+// the companion question — which records predate structured frontmatter — and it
+// lives in the same config (`decisions.historicalCutoff`), never in code.
+
+import { stat } from 'node:fs/promises';
+import { join } from 'node:path';
+
+import { readManifest } from '../projection/manifest.mjs';
+
+/** Directory spellings a repository's decision records live under, in priority order. */
+const DECISION_DIR_CANDIDATES = ['docs/decisions', 'docs/adr', 'docs/adrs', 'adr'];
+
+/** The default when nothing is declared and nothing exists yet. */
+const DEFAULT_DECISIONS_DIR = 'docs/decisions';
+
+/**
+ * The repository's own `decisions` manifest key, or null.
+ *
+ * Read with the manifest loader (so the legacy name resolves the same way for
+ * this as for every other reader) and returned as-is: validation belongs to
+ * the caller that knows what it needs.
+ */
+async function manifestDecisions(root) {
+  try {
+    const { manifest } = await readManifest(root);
+    const decisions = manifest?.decisions;
+    return decisions !== null && typeof decisions === 'object' && !Array.isArray(decisions) ? decisions : null;
+  } catch {
+    // An unreadable manifest is not evidence either way; detection decides.
+    return null;
+  }
+}
+
+async function isDir(path) {
+  try {
+    return (await stat(path)).isDirectory();
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * The relative decisions directory for this repository.
+ *
+ * @param {string} root repository root
+ * @returns {Promise<string>} e.g. `docs/decisions`
+ */
+export async function decisionsDir(root) {
+  const declared = await manifestDecisions(root);
+  if (typeof declared?.dir === 'string' && declared.dir.trim() !== '') {
+    return declared.dir.trim().replace(/\\/g, '/').replace(/\/+$/, '');
+  }
+  for (const candidate of DECISION_DIR_CANDIDATES) {
+    if (await isDir(join(root, candidate))) return candidate;
+  }
+  return DEFAULT_DECISIONS_DIR;
+}
+
+/**
+ * How many leading records predate structured frontmatter and are exempt from it.
+ *
+ * The package's own history is the only corpus with such records, and even it
+ * declares the number in its own manifest rather than in code: a number in code
+ * is a second answer the next record silently moves. Any other repository gets
+ * zero unless it declares otherwise.
+ *
+ * @param {string} root repository root
+ * @returns {Promise<number>}
+ */
+export async function decisionsCutoff(root) {
+  const declared = await manifestDecisions(root);
+  const value = declared?.historicalCutoff;
+  if (typeof value === 'number' && Number.isFinite(value) && value >= 0) return Math.floor(value);
+  return 0;
+}