simt-dev 0.6.3 → 0.7.1

package/src/mcp/tools.mjs

@@ -22,7 +22,7 @@
 import { loadRegistry } from '../graph/load.mjs';
 import { provenanceDigest } from '../projection/project.mjs';
 import { discover } from '../compare/discover.mjs';
-import { buildRow, summarise } from '../compare/row.mjs';
+import { buildRows, resolveConcurrency, summarise } from '../compare/row.mjs';
 import { GATES } from '../hooks/gates.mjs';
 import { checkRepo } from '../commands/sync.mjs';
 import { diagnose, serialisedFindings } from '../commands/doctor.mjs';
@@ -248,9 +248,10 @@ const output = {
       workspace: { type: 'string' },
       body: { type: ['string', 'null'] },
       bodyFrom: { type: 'string' },
-      bodyText: { type: 'string' },
+      bodyText: { type: ['string', 'null'] },
+      reason: { type: ['string', 'null'], description: 'why there is no body, when there is none' },
     },
-    required: ['name', 'bytes', 'bodyFrom', 'requires', 'variants'],
+    required: ['name', 'bytes', 'body', 'bodyFrom', 'bodyText', 'reason', 'requires', 'variants'],
   },
   skills_find: {
     type: 'object',
@@ -381,6 +382,9 @@ const output = {
       repos: { type: 'array', items: { type: 'object' } },
       worktrees: { type: 'array', items: { type: 'object' } },
       directories: { type: 'array', items: { type: 'string' } },
+      partial: { type: 'boolean' },
+      cursor: { type: ['string', 'null'] },
+      total: { type: 'number' },
     },
     required: ['root', 'shape', 'expectedSha', 'summary', 'repos'],
   },
@@ -423,6 +427,7 @@ const output = {
       cut: { type: 'array', items: { type: 'string' } },
       sections: { type: 'object', additionalProperties: { type: 'array', items: { type: 'string' } } },
       text: { type: 'string' },
+      note: { type: ['string', 'null'] },
     },
     required: ['root', 'kind', 'basis', 'task', 'scope', 'budget', 'bytes', 'before', 'floorHeld', 'cut', 'sections', 'text'],
   },
@@ -525,7 +530,7 @@ export const TOOLS = [
     outputSchema: output.doctor,
     name: 'doctor',
     description:
-      'Classify a repository: stack tags, emitted facts with the file that proved each, and manifest presence. Call this first when the repo is unknown.',
+      'Classify a repository: stack tags, the facts with the file that proved each, and manifest presence. Call this first when the repo is unknown. Read-only: `--fix` and `--diff` stay on the command.',
     inputSchema: rootArg,
     async run(args) {
       const root = rootOf(args);
@@ -548,7 +553,13 @@ export const TOOLS = [
     name: 'skills_index',
     description:
       'Full skill catalogue: every skill with summary, size, stack tags and deferred flag. The fallback when brief returns nothing useful.',
-    inputSchema: noArgs,
+    inputSchema: {
+      type: 'object',
+      properties: {
+        registry: { type: 'string', description: 'path to skills.graph.json; else --registry / SIMT_REGISTRY / default tiers' },
+      },
+      required: [],
+    },
     async run(args) {
       const { registry: reg, verified, workspace } = await registry(args);
       return {
@@ -568,7 +579,7 @@ export const TOOLS = [
     outputSchema: output.skills_brief,
     name: 'skills_brief',
     description:
-      'THE entry point. Resolve the skill set for a task: selected with why, deferred, and not selected with reason - the reasons let you override the resolver instead of guessing at it.',
+      'THE entry point. Resolve the skill set for a task: selected with why, deferred, and not selected with the reason to override.',
     inputSchema: {
       type: 'object',
       properties: {
@@ -578,6 +589,7 @@ export const TOOLS = [
         budget: { type: 'number', description: 'context budget in bytes (default 20480)' },
         skill: { type: 'string', description: 'force a skill in, comma-separated' },
         all: { type: 'boolean', description: 'ignore the budget' },
+        registry: { type: 'string', description: 'path to skills.graph.json; else --registry / SIMT_REGISTRY / default tiers' },
       },
       required: [],
     },
@@ -610,18 +622,25 @@ export const TOOLS = [
         name: { type: 'string' },
         root: { type: 'string' },
         maxBytes: { type: 'number', description: 'hard ceiling on the returned text' },
+        registry: { type: 'string', description: 'path to skills.graph.json; else --registry / SIMT_REGISTRY / default tiers' },
       },
       required: ['name'],
     },
     async run(args) {
       const root = rootOf(args);
       const facts = await skillsShowFacts(root, args?.name, args ?? {});
+      // The schema promises `body: null` when there is no body, and this used to hand the
+      // prose that says so to the field a client tests for null: a caller checking `body`
+      // for null read a paragraph as a body (Q56). The prose moves to `reason`, which is
+      // where a model looks for what to do about it.
+      const missing = typeof facts.bodyText === 'string' && facts.bodyText.startsWith('(body unavailable');
       return {
         ...facts.skill,
         workspace: facts.workspace,
-        body: facts.body,
+        body: missing ? null : facts.body,
         bodyFrom: facts.bodyFrom,
-        bodyText: facts.bodyText,
+        bodyText: missing ? null : facts.bodyText,
+        reason: missing ? facts.bodyText : null,
       };
     },
   },
@@ -632,11 +651,16 @@ export const TOOLS = [
     description: 'Raw search across capability, keyword and summary. Use when skills_brief has nothing and you suspect a skill exists.',
     inputSchema: {
       type: 'object',
-      properties: { query: { type: 'string' } },
+      properties: {
+        query: { type: 'string' },
+        root: { type: 'string' },
+        registry: { type: 'string', description: 'path to skills.graph.json; else --registry / SIMT_REGISTRY / default tiers' },
+      },
       required: ['query'],
     },
     async run(args) {
-      return skillsFindFacts(typeof args?.query === 'string' ? args.query : '', args ?? {});
+      const root = rootOf(args);
+      return skillsFindFacts(root, typeof args?.query === 'string' ? args.query : '', args ?? {});
     },
   },
 
@@ -647,7 +671,12 @@ export const TOOLS = [
       'The signal chain for one skill in one repository: its score, the reasons, whether the stack gate admits it, and what would select it.',
     inputSchema: {
       type: 'object',
-      properties: { name: { type: 'string' }, root: { type: 'string' }, task: { type: 'string' } },
+      properties: {
+        name: { type: 'string' },
+        root: { type: 'string' },
+        task: { type: 'string' },
+        registry: { type: 'string', description: 'path to skills.graph.json; else --registry / SIMT_REGISTRY / default tiers' },
+      },
       required: ['name'],
     },
     async run(args) {
@@ -710,23 +739,37 @@ export const TOOLS = [
     outputSchema: output.compare,
     name: 'compare',
     description:
-      'The workspace matrix: every repository with its adoption, region state, pinned SHA, hook routing and gates, plus the problems found.',
+      'The workspace matrix: adoption, region, SHA, hooks and gates per repo, plus problems. Pages with limit/cursor; honors progressToken and cancellation.',
     inputSchema: {
       type: 'object',
       properties: {
         root: { type: 'string', description: 'a workspace directory, or one repository' },
         workspace: { type: 'string', description: 'workspace root when root is not given' },
+        limit: { type: 'number', description: 'page size; without it every row is built' },
+        cursor: { type: 'string', description: 'opaque page start from a previous partial answer' },
+        concurrency: { type: 'number', description: 'rows built at once (default 4)' },
       },
       required: [],
     },
-    async run(args) {
+    async run(args, ctx = {}) {
       const root = args?.root ?? args?.workspace ?? (await resolveWorkspace(args ?? {})).root ?? process.cwd();
       const found = await discover(root);
       if (found.error) throw Object.assign(new Error(`${root}: ${found.error}`), { remedy: 'pass root' });
       const expectedSha = await provenanceDigest();
       const context = { expectedSha, gates: new Set(Object.keys(GATES)), gateKinds: GATE_KINDS };
-      const rows = [];
-      for (const repo of found.repos) rows.push(await buildRow(repo, context));
+      // A page names its start as an index into discovery order, which is
+      // stable between calls on an unchanged estate; garbage parses to 0
+      // rather than erroring, because a dashboard that refuses to run over a
+      // stale cursor is worse than one that restarts the listing.
+      const start = Math.max(0, parseInt(typeof args?.cursor === 'string' ? args.cursor : '0', 10) || 0);
+      const limit = typeof args?.limit === 'number' && args.limit >= 1 ? Math.floor(args.limit) : null;
+      const page = limit === null ? found.repos : found.repos.slice(start, start + limit);
+      const rows = await buildRows(page, context, {
+        concurrency: resolveConcurrency(args ?? {}),
+        signal: ctx?.signal ?? null,
+        onBatch: ctx?.onProgress ? (done, total) => ctx.onProgress(start + done, found.repos.length) : null,
+      });
+      const next = limit !== null && start + page.length < found.repos.length ? String(start + page.length) : null;
       return {
         root,
         shape: found.shape,
@@ -735,6 +778,7 @@ export const TOOLS = [
         repos: rows,
         worktrees: found.worktrees.map((w) => ({ name: w.name, owner: w.ownerName })),
         directories: found.directories,
+        ...(limit === null ? {} : { partial: next !== null, cursor: next, total: found.repos.length }),
       };
     },
   },
@@ -869,7 +913,37 @@ export const TOOLS = [
         build: false,
       });
       if (result.error) throw Object.assign(new Error('the index could not be read'), { remedy: `run: ${CLI} index` });
-      if (result.cold) throw Object.assign(new Error('this repository has no index to answer from'), { remedy: `run: ${CLI} index` });
+      // A repository with no index is not a failed call. Every surface points here first,
+      // so the one tool told to be the entry point must answer in a repository that has
+      // never been indexed - it falls back to the skill packet, which is read from the
+      // package rather than the tree, and names the command that unlocks the rest (Q56).
+      if (result.cold) {
+        const task = typeof args?.task === 'string' ? args.task : '';
+        const facts = await skillsBriefFacts(root, { ...(args ?? {}), task });
+        // Through JSON once, so the packet carries exactly what the text block shows: a
+        // property whose value is `undefined` survives `stringify` as nothing at all, and
+        // the two blocks would then describe different objects.
+        const text = JSON.stringify(facts, null, 2);
+        const packet = JSON.parse(text);
+        const size = Buffer.byteLength(text);
+        return {
+          root,
+          kind: 'skills',
+          basis: 'registry',
+          task,
+          scope: [],
+          budget,
+          bytes: size,
+          before: size,
+          // The skill packet is one document and is not cut to fit: saying the floor held
+          // when the answer is over it is the class of claim this review exists to remove.
+          floorHeld: size <= budget,
+          cut: size <= budget ? [] : ['text'],
+          sections: { skills: (packet.resolved ?? []).map((s) => s.name) },
+          text,
+          note: `no index here, so this is the skill packet; run: ${CLI} index for the repository packet`,
+        };
+      }
       return {
         root: result.root,
         kind: result.kind,

package/src/measure/session.mjs

@@ -8,6 +8,7 @@
 import { readFile } from 'node:fs/promises';
 import { resolve } from 'node:path';
 
+import { CLI } from '../name.mjs';
 import { tokens } from './context.mjs';
 
 const RULE_PATH_RE =
@@ -53,14 +54,14 @@ export async function measureSession(transcriptPath) {
     return {
       ok: false,
       error: '--session requires a local transcript path',
-      remedy: 'pass a local JSONL or JSON transcript path: simt tokens --session <path>',
+      remedy: `pass a local JSONL or JSON transcript path: ${CLI} tokens --session <path>`,
     };
   }
   if (/^[a-z][a-z0-9+.-]*:\/\//i.test(transcriptPath.trim())) {
     return {
       ok: false,
       error: `${transcriptPath}: remote URLs are refused; session transcripts are read locally only (ADR-075)`,
-      remedy: 'pass a local file path on this machine: simt tokens --session ./session.jsonl',
+      remedy: `pass a local file path on this machine: ${CLI} tokens --session ./session.jsonl`,
     };
   }
 

package/src/memory/decide.mjs

@@ -7,7 +7,8 @@ import { execFile } from 'node:child_process';
 import { mkdir, readFile, readdir, writeFile } from 'node:fs/promises';
 import { join } from 'node:path';
 import { promisify } from 'node:util';
-import { journaledWriteFile } from '../journal.mjs';
+import { recordCreatedFile } from '../journal.mjs';
+import { decisionsDir } from '../decisions/dir.mjs';
 
 const exec = promisify(execFile);
 
@@ -336,15 +337,19 @@ function renderDecisionScaffold({
   ].join('\n');
 }
 
-/** Scaffold a new ADR in `<root>/docs/decisions` with structured frontmatter. */
+/**
+ * Scaffold a new ADR in the repository's decisions directory with structured frontmatter.
+ *
+ * The number is claimed with `O_EXCL`: two concurrent scaffolds that both read
+ * the same maximum must not land on the same number, and a check-then-write
+ * would let the second silently overwrite the first. On collision the number is
+ * re-read and the next free one taken, so the retry always terminates.
+ */
 export async function scaffoldDecision(root, options = {}) {
-  const decisionsDir = options.decisionsDir ?? join(root, 'docs', 'decisions');
-  const { number, id } = await nextDecisionNumber(decisionsDir);
+  const relDir = options.decisionsDir ?? (await decisionsDir(root));
+  const absDir = join(root, relDir);
   const title = String(options.title ?? 'Untitled decision').trim() || 'Untitled decision';
   const slug = slugifyTitle(title);
-  const file = `${id}-${slug}.md`;
-  const relPath = ['docs', 'decisions', file].join('/');
-  const fullPath = join(decisionsDir, file);
   const affects = Array.isArray(options.affects)
     ? options.affects.map((p) => String(p).trim()).filter(Boolean)
     : await diffAffectedPaths(root);
@@ -352,38 +357,58 @@ export async function scaffoldDecision(root, options = {}) {
   const { entries: supersedes, errors } = parseSupersedesSpec(options.supersedes);
   if (errors.length > 0) return { ok: false, errors };
 
-  const text = renderDecisionScaffold({
-    id,
-    title,
-    date: options.date,
-    status: options.status,
-    affects,
-    supersedes,
-  });
-
-  // A caller-supplied journal records the scaffold so `undo` can restore it
-  // (R49). Callers without one (probes, tests staging fixtures) keep the old
-  // behaviour exactly.
-  if (options.write) {
-    await mkdir(decisionsDir, { recursive: true });
-    if (options.journal) await journaledWriteFile(root, options.journal, fullPath, text);
-    else await writeFile(fullPath, text, 'utf8');
+  // A dry run names the number without claiming it: the file must not exist
+  // afterwards, so no exclusive create happens here.
+  if (!options.write) {
+    const { number, id } = await nextDecisionNumber(absDir);
+    const file = `${id}-${slug}.md`;
+    return {
+      ok: true,
+      id,
+      number,
+      title,
+      slug,
+      file,
+      relPath: [relDir, file].join('/'),
+      path: join(absDir, file),
+      affects,
+      supersedes,
+      text: renderDecisionScaffold({ id, title, date: options.date, status: options.status, affects, supersedes }),
+      written: false,
+    };
   }
 
-  return {
-    ok: true,
-    id,
-    number,
-    title,
-    slug,
-    file,
-    relPath,
-    path: fullPath,
-    affects,
-    supersedes,
-    text,
-    written: Boolean(options.write),
-  };
+  await mkdir(absDir, { recursive: true });
+  for (let attempt = 0; attempt < 100; attempt += 1) {
+    const { number, id } = await nextDecisionNumber(absDir);
+    const file = `${id}-${slug}.md`;
+    const fullPath = join(absDir, file);
+    const text = renderDecisionScaffold({ id, title, date: options.date, status: options.status, affects, supersedes });
+    try {
+      await writeFile(fullPath, text, { flag: 'wx' });
+    } catch (error) {
+      if (error.code !== 'EEXIST') throw error;
+      continue;
+    }
+    // The exclusive create is the journal entry's `before: null`: the file did
+    // not exist a moment ago, by construction rather than by re-reading.
+    if (options.journal) recordCreatedFile(root, options.journal, fullPath, text);
+    return {
+      ok: true,
+      id,
+      number,
+      title,
+      slug,
+      file,
+      relPath: [relDir, file].join('/'),
+      path: fullPath,
+      affects,
+      supersedes,
+      text,
+      written: true,
+    };
+  }
+  return { ok: false, errors: ['could not claim a free ADR number after 100 attempts'] };
 }
 
 /** Extract partial supersession claims stated in prose (`Status:` and header paragraphs). */
@@ -415,8 +440,15 @@ function prosePartialSupersessions(body) {
   return claims;
 }
 
-/** Lint a single ADR document for structured supersession conformance (plan 0003 R34). */
-export function lintDecision(text, { file = 'ADR-000.md', allowHistorical = false } = {}) {
+/**
+ * Lint a single ADR document for structured supersession conformance (plan 0003 R34).
+ *
+ * `historicalCutoff` exempts the first N records from the frontmatter requirement:
+ * they predate it, and demanding it retroactively would fail a history nobody can
+ * rewrite without rewriting history. Q55: the number lives in the repository's
+ * config (`decisions.historicalCutoff`, resolved by the caller), never in code.
+ */
+export function lintDecision(text, { file = 'ADR-000.md', historicalCutoff = 0 } = {}) {
   const fileMatch = file !== 'ADR-000.md' ? /^(ADR-\d{3,})/i.exec(file) : null;
   const headMatch = /^#\s+(ADR-\d{3,})\b/m.exec(String(text ?? ''));
   const id = (fileMatch?.[1] ?? headMatch?.[1] ?? /^(ADR-\d{3,})/i.exec(file)?.[1] ?? '').toUpperCase() || null;
@@ -432,7 +464,7 @@ export function lintDecision(text, { file = 'ADR-000.md', allowHistorical = fals
     remedy: 'fix simt-supersedes frontmatter to use [{ adr: "ADR-NNN", ruling: N }]',
   }));
 
-  if (allowHistorical && !fm.hasFrontmatter && num !== null && num > 0 && num <= 96) {
+  if (!fm.hasFrontmatter && num !== null && num > 0 && num <= historicalCutoff) {
     return { ok: findings.length === 0, findings };
   }
 
@@ -455,13 +487,36 @@ export function lintDecision(text, { file = 'ADR-000.md', allowHistorical = fals
   return { ok: findings.length === 0, findings };
 }
 
-/** Lint all ADR records in a decisions directory. */
-export async function lintDecisions(decisionsDir, { allowHistorical = false } = {}) {
+/**
+ * Lint all ADR records in a decisions directory.
+ *
+ * Duplicate ids are a lint finding, not a silent keep-first: two files claiming
+ * one number means `byId` answers for only one of them, and the reader of the
+ * other gets a record the index cannot see. The kept record is the first in
+ * numeric filename order — the same one the loader keeps — so lint and load
+ * never name different winners.
+ */
+export async function lintDecisions(decisionsDir, { historicalCutoff = 0 } = {}) {
   const names = (await readdir(decisionsDir).catch(() => [])).filter((n) => /^ADR-\d{3,}-.*\.md$/i.test(n)).sort();
   const findings = [];
+  const seen = new Map();
   for (const file of names) {
+    const id = /^(ADR-\d{3,})/i.exec(file)?.[1]?.toUpperCase() ?? null;
+    if (id !== null) {
+      if (seen.has(id)) {
+        findings.push({
+          file,
+          id,
+          status: 'duplicate-decision-id',
+          detail: `decision id ${id} is claimed by ${seen.get(id)} and ${file}; the index only sees the first`,
+          remedy: 'renumber the newer record to a free number, then rerun the check',
+        });
+        continue;
+      }
+      seen.set(id, file);
+    }
     const text = await readFile(join(decisionsDir, file), 'utf8');
-    findings.push(...lintDecision(text, { file, allowHistorical }).findings);
+    findings.push(...lintDecision(text, { file, historicalCutoff }).findings);
   }
   return { ok: findings.length === 0, findings };
 }