simt-dev 0.2.2 → 0.3.1

package/src/kernel/inferability.mjs

@@ -0,0 +1,188 @@
+// The inferability filter: a rule line the repository already proves does not ship
+// (plan 0003 R09).
+//
+// The costliest byte in a projection is the one the reader already knows. A Go repository
+// with one runner does not need to be told to use it; a repository whose manifest declares
+// a format gate does not need to be told how it indents. The evidence is committed — the
+// marker files, the declared gates, the command card — so the same repository filters the
+// same way on every machine (plan 0003 P4, R13).
+//
+// Nothing is dropped by guesswork. A rule author marks the line with
+// `<!-- simt-inferable-when: <expression> -->`, naming the evidence that makes it
+// redundant, and the line leaves only when the repository proves every term. A line nobody
+// marked is a line nobody claimed was inferable, and stays.
+//
+// The unit dropped is the blank-line-delimited block, so a wrapped bullet is marked once
+// and leaves whole rather than leaving half a sentence behind. The marker is stripped from
+// the region either way: `simt-` vocabulary is for the rule's author, not its reader.
+
+import { gateNames } from '../hooks/gates.mjs';
+import { KNOWN_TAGS } from '../resolve/fingerprint.mjs';
+
+import { CARD_VERBS } from './card.mjs';
+
+/**
+ * The marker a rule line carries. Named here rather than at its use, because the defect
+ * message has to spell the thing the author must type.
+ */
+export const INFERABLE_MARKER = 'simt-inferable-when';
+
+const MARKER = /<!--\s*simt-inferable-when:\s*([^>]*?)\s*-->/g;
+
+/**
+ * Marks the trailing position of a marker on a line, so the text a reader keeps is the
+ * line without the comment and not the line with a hole in it.
+ */
+const MARKER_AT = /\s*<!--\s*simt-inferable-when:\s*[^>]*?-->/g;
+
+/** A non-global probe, because a global regex carries `lastIndex` between calls. */
+const HAS_MARKER = /<!--\s*simt-inferable-when:/;
+
+/**
+ * Split a body into the units a marker drops. Blank lines separate blocks, except inside a
+ * fenced code block, where a blank line is part of the sample and splitting there would
+ * cut a fence in half.
+ */
+function blocks(text) {
+  const out = [];
+  let current = [];
+  let fenced = false;
+  for (const line of String(text ?? '').split('\n')) {
+    if (/^\s*(```|~~~)/.test(line)) {
+      if (current.length > 0 || fenced) current.push(line);
+      fenced = !fenced;
+      continue;
+    }
+    if (!fenced && line.trim() === '') {
+      if (current.length > 0) out.push(current.join('\n'));
+      current = [];
+      continue;
+    }
+    current.push(line);
+  }
+  if (current.length > 0) out.push(current.join('\n'));
+  return out;
+}
+
+/** Every marker in one block, as `{line, expr}`. More than one is a defect. */
+function markers(block) {
+  const found = [];
+  for (const line of block.split('\n')) {
+    for (const match of line.matchAll(MARKER)) found.push({ line, expr: match[1] });
+  }
+  return found;
+}
+
+/**
+ * An expression is a conjunction of terms: `term + term`, and nothing else. There is no
+ * negation, because every reason a line is redundant is a positive proof the repository
+ * offers, and a grammar for a case nobody has is a grammar nobody can be taught.
+ */
+export function parseInferable(expression) {
+  return String(expression ?? '')
+    .split('+')
+    .map((term) => term.trim())
+    .filter((term) => term !== '');
+}
+
+/**
+ * Whether a term is evidence this tool can check: a fact or stack tag the repository
+ * proves by its files, a verb its command card names, or a gate it declares. Anything else
+ * is a typo the author has to see, not a term that happens to be unproven — a marker
+ * naming evidence the tool never gathered would drop the line on a claim nothing verified.
+ */
+function knownTerm(term) {
+  if (term.startsWith('card:')) return CARD_VERBS.includes(term.slice('card:'.length));
+  if (term.startsWith('gate:')) return gateNames().includes(term.slice('gate:'.length));
+  return KNOWN_TAGS.has(term);
+}
+
+/**
+ * The defect in a body's markers, or null. Reported through the same field as a
+ * frontmatter defect, so `check` and `rules list` need no second path to a broken rule.
+ */
+export function inferableDefect(body) {
+  for (const block of blocks(body)) {
+    const found = markers(block);
+    if (found.length === 0) continue;
+    if (found.length > 1) {
+      return `carries more than one ${INFERABLE_MARKER} marker; a block is dropped whole, so one marker is one claim`;
+    }
+    const terms = parseInferable(found[0].expr);
+    if (terms.length === 0) {
+      return `${INFERABLE_MARKER} names no evidence, so nothing can decide whether the line is redundant`;
+    }
+    for (const term of terms) {
+      if (!knownTerm(term)) {
+        return `${INFERABLE_MARKER} names "${term}", which is not evidence this repository can prove; use a marker-file fact, card:${CARD_VERBS.join('|card:')} or gate:<name>`;
+      }
+    }
+  }
+  return null;
+}
+
+/**
+ * The evidence a projection may treat as already known. Built from committed bytes only —
+ * never PATH or `node_modules` — because a proof read off the machine would make the
+ * region differ between a laptop and CI for no reason a diff could explain.
+ */
+export function inferableProofs({ facts = [], stack = [], card = null, manifest = null } = {}) {
+  const proofs = new Set([...facts, ...stack]);
+  for (const line of card?.lines ?? []) {
+    if (line.verb) proofs.add(`card:${line.verb}`);
+  }
+  const gates = manifest?.gates ?? {};
+  for (const name of [...(gates.preCommit ?? []), ...(gates.prePush ?? [])]) {
+    proofs.add(`gate:${name}`);
+  }
+  return proofs;
+}
+
+/** The line a reader would have read, collapsed and clipped for a one-line note. */
+function excerpt(text) {
+  const one = text.replace(/\s+/g, ' ').trim();
+  return one.length > 80 ? `${one.slice(0, 79)}…` : one;
+}
+
+/** The block without its markers, and without the line a marker stood on alone. */
+function stripMarkers(block) {
+  const kept = [];
+  for (const line of block.split('\n')) {
+    const stripped = line.replace(MARKER_AT, '').replace(/\s+$/, '');
+    if (stripped === '' && HAS_MARKER.test(line)) continue;
+    kept.push(stripped);
+  }
+  return kept.join('\n');
+}
+
+/**
+ * Drop every marked block whose expression the repository proves, and strip the markers
+ * from the rest.
+ *
+ * `changed` is false when the body carries no marker, and then `body` is the input by
+ * identity: a projection of a rule nobody marked must not move a byte, or every
+ * repository in the estate would diff on a change none of them made.
+ *
+ * @returns {{body: string, removed: {text: string, expr: string}[], changed: boolean}}
+ */
+export function filterInferable(body, proofs) {
+  const parts = blocks(body);
+  if (!parts.some((block) => markers(block).length > 0)) {
+    return { body, removed: [], changed: false };
+  }
+  const kept = [];
+  const removed = [];
+  for (const block of parts) {
+    const found = markers(block);
+    if (found.length > 0) {
+      const terms = parseInferable(found[0].expr);
+      if (terms.length > 0 && terms.every((term) => proofs.has(term))) {
+        removed.push({ text: excerpt(stripMarkers(block)), expr: found[0].expr.trim() });
+        continue;
+      }
+    }
+    const clean = stripMarkers(block).replace(/\s+$/, '');
+    if (clean.trim() !== '') kept.push(clean);
+  }
+  return { body: kept.join('\n\n'), removed, changed: true };
+}

package/src/ledger/index.mjs

@@ -0,0 +1,112 @@
+// The evidence ledger (ADR-087).
+//
+// A passing command is evidence about one tree and no other. The tree is taken with a
+// private index, because `git add -A` on the real index would stage work the author had
+// left unstaged. Editing any file afterwards produces a different tree, so the old line
+// no longer proves anything about what is on disk now.
+
+import { createHash } from 'node:crypto';
+import { execFile } from 'node:child_process';
+import { appendFile, mkdir, mkdtemp, readFile, rm } from 'node:fs/promises';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { promisify } from 'node:util';
+
+const exec = promisify(execFile);
+
+const LEDGER_FILE = '.simt-dev/ledger.jsonl';
+
+/** Phrases that claim a run happened. `unverified` and `not verified` are removed
+ *  first, because both contain the word and neither is a claim. */
+const CLAIM = /\btests?\s+pass(?:ed)?\b|\bverified\b/i;
+
+/**
+ * The tree of everything in the worktree, without staging any of it.
+ *
+ * @param {string} root
+ * @returns {Promise<string>} the write-tree id
+ */
+export async function treeId(root) {
+  const dir = await mkdtemp(join(tmpdir(), 'tree-index-'));
+  const index = join(dir, 'index');
+  const env = { ...process.env, GIT_INDEX_FILE: index };
+  try {
+    // The ledger is a record of the tree, so it cannot be part of the tree it names.
+    // `git add -A` would take it once the file exists, and the line would prove a
+    // tree that stopped existing when the line was written.
+    await exec('git', ['add', '-A', '--', '.', ':(exclude).simt-dev/ledger.jsonl'], { cwd: root, env });
+    const { stdout } = await exec('git', ['write-tree'], { cwd: root, env });
+    return stdout.trim();
+  } finally {
+    await rm(dir, { recursive: true, force: true });
+  }
+}
+
+/**
+ * Append one run. The output itself is not stored: the digest is enough to notice a
+ * change, and a ledger that kept logs would keep whatever the command printed.
+ */
+export async function recordRun(root, { cmd, exit, ms, output }) {
+  const line = {
+    v: 1,
+    ts: new Date().toISOString().replace(/\.\d{3}Z$/, 'Z'),
+    tree: await treeId(root),
+    cmd,
+    exit,
+    ms,
+    outputDigest: `sha256-${createHash('sha256').update(output).digest('hex')}`,
+    summary: summarise(output, exit),
+  };
+  await mkdir(join(root, '.simt-dev'), { recursive: true });
+  await appendFile(join(root, LEDGER_FILE), `${JSON.stringify(line)}\n`);
+  return line;
+}
+
+/** Every well-formed line. A line that does not parse is returned as an error so a
+ *  damaged ledger cannot look empty. */
+export async function readLedger(root) {
+  let text;
+  try {
+    text = await readFile(join(root, LEDGER_FILE), 'utf8');
+  } catch (error) {
+    if (error.code === 'ENOENT') return { entries: [], errors: [] };
+    throw error;
+  }
+  const entries = [];
+  const errors = [];
+  for (const [i, raw] of text.split('\n').entries()) {
+    if (raw.trim() === '') continue;
+    try {
+      const line = JSON.parse(raw);
+      if (typeof line.tree !== 'string' || typeof line.exit !== 'number') {
+        errors.push(`line ${i + 1} has no tree or exit`);
+        continue;
+      }
+      entries.push(line);
+    } catch (error) {
+      errors.push(`line ${i + 1} does not parse (${error.message})`);
+    }
+  }
+  return { entries, errors };
+}
+
+export function claimsVerification(message) {
+  const text = String(message).replace(/\bunverified\b/gi, ' ').replace(/\bnot\s+verified\b/gi, ' ');
+  return CLAIM.test(text);
+}
+
+/** `block` fails the commit. Anything unset is a warning. A third spelling is an
+ *  error, because a typo for `block` must not quietly warn. */
+export function evidenceMode(manifest) {
+  const value = manifest?.gates?.evidence;
+  if (value === undefined || value === 'warn') return 'warn';
+  if (value === 'block') return 'block';
+  return null;
+}
+
+function summarise(output, exit) {
+  const pass = /(\d+)\s+pass\b/.exec(output) ?? /\bpass\s+(\d+)/.exec(output);
+  const fail = /(\d+)\s+fail\b/.exec(output) ?? /\bfail\s+(\d+)/.exec(output);
+  if (pass || fail) return `${pass?.[1] ?? 0} pass, ${fail?.[1] ?? 0} fail`;
+  return `exit ${exit}`;
+}

package/src/mcp/resources.mjs

@@ -0,0 +1,157 @@
+// Rules and decisions as MCP resources.
+//
+// The tools answer questions and the answers are arguments to the next call. These two
+// answer a different request: "what is the rule you would apply, in full". A client that
+// reads them can hold the text rather than reconstructing it from a tool's summary, and
+// a reader outside this estate gets the same bytes an adopting repository's agent reads -
+// redacted, because a decision record cites its own rulings and not this repository's
+// layout (ADR-055, ADR-061).
+//
+// Both revisions agree on the shape here. They disagree about what a missing resource
+// returns, and that difference is handled in the server, not here: this module answers
+// with a resource or with nothing at all, and never with an empty `contents` array,
+// which the newest revision forbids because it is indistinguishable from an empty rule.
+
+import { readFile } from 'node:fs/promises';
+import { join } from 'node:path';
+
+import { DECISIONS_DIR, loadDecisions, redactEstate, redactInternalPaths } from '../decisions/index.mjs';
+import { CLI } from '../name.mjs';
+import { loadMdcRules } from '../projection/mdc.mjs';
+import { loadRules } from '../projection/rules.mjs';
+
+const RULES_SCHEME = 'simt://rules/';
+const DECISIONS_SCHEME = 'simt://decisions/';
+
+/**
+ * RFC 6570 templates, so a client can discover the shape without a hard-coded string.
+ *
+ * `id` and `adr` are the handles a reader already has: a gate names a rule id and a
+ * finding names an ADR, so the template's variable names match what those print.
+ */
+export const RESOURCE_TEMPLATES = [
+  {
+    uriTemplate: `${RULES_SCHEME}{id}`,
+    name: 'rules',
+    title: 'Projected rules',
+    description: 'One rule as this tool projects it: its frontmatter, its body and its decision citations.',
+    mimeType: 'text/markdown',
+  },
+  {
+    uriTemplate: `${DECISIONS_SCHEME}{adr}`,
+    name: 'decisions',
+    title: 'Decision records',
+    description: 'One decision record, including the rulings and the reasons they were given.',
+    mimeType: 'text/markdown',
+  },
+];
+
+/**
+ * Split a resource URI into its collection and its handle.
+ *
+ * String handling rather than `new URL`, because a custom scheme is parsed by the WHATWG
+ * URL machinery according to rules written for http, and the one thing this has to get
+ * right is which character separates `simt://rules` from the id. A handle that carries a
+ * slash or a dot segment is refused rather than resolved: a resource URI is not a file
+ * path, and the specification requires a server to reject one that tries to be.
+ */
+function parseResourceUri(uri) {
+  if (typeof uri !== 'string') return null;
+  const [collection, ...rest] = uri.split('://');
+  if (collection !== 'simt') return null;
+  const [name, ...handle] = rest.join('://').split('/');
+  const id = handle.join('/');
+  if (!id || id === '.' || id === '..' || id.includes('..')) return null;
+  if (name === 'rules' && id.includes('/')) return null;
+  if (name !== 'rules' && name !== 'decisions') return null;
+  return { collection: name, id };
+}
+
+function resource(collection, id, title, bytes) {
+  return {
+    uri: `simt://${collection}/${id}`,
+    name: id,
+    title,
+    description: `${title}, as this tool projects it`,
+    mimeType: 'text/markdown',
+    size: bytes,
+  };
+}
+
+/**
+ * Every rule and every decision record, one entry each.
+ *
+ * The list is built from what is on disk rather than from a hand-kept index, so it cannot
+ * describe a rule that was renamed or a record that was never written. Order is sorted:
+ * the newest revision forbids a set that varies per connection or as a side effect of
+ * another request, and a list built from a directory read is the only shape that satisfies
+ * that without a cache to invalidate.
+ */
+export async function listResources() {
+  const [rules, mdc, { decisions }] = await Promise.all([loadRules(null), loadMdcRules(), loadDecisions({ all: true })]);
+  // `size` is the bytes on disk rather than the bytes served: `read` redacts a decision
+  // before sending it, so the served length is not knowable without reading the file, and
+  // a size that disagrees with the payload is worse than a size that rounds.
+  return [
+    ...[...rules, ...mdc]
+      .filter((rule) => rule.id !== null)
+      .map((rule) => resource('rules', rule.id, rule.title ?? rule.id, rule.bytes)),
+    ...decisions.map((decision) => resource('decisions', decision.id, decision.title ?? decision.id, decision.bytes)),
+  ].sort((a, b) => a.uri.localeCompare(b.uri));
+}
+
+/**
+ * One resource, or null when there is no such id.
+ *
+ * `null` is not a failure the caller swallows: the specification makes a missing resource
+ * a protocol error with a code that CHANGED between revisions, so the server decides the
+ * code and this module only declines to invent content.
+ */
+export async function readResource(uri) {
+  const parsed = parseResourceUri(uri);
+  if (parsed === null) return null;
+
+  if (parsed.collection === 'rules') {
+    const [rules, mdc] = await Promise.all([loadRules(null), loadMdcRules()]);
+    const rule = [...rules, ...mdc].find((candidate) => candidate.id === parsed.id);
+    if (rule === undefined) return null;
+    const text = `${frontmatterOf(rule)}\n${rule.body ?? ''}`.trim();
+    return {
+      uri,
+      mimeType: 'text/markdown',
+      text,
+      // The body a tool returns is redacted for the same reason: a reader outside this
+      // estate is told what the rule says and not which directory here it is filed in.
+      bytes: Buffer.byteLength(text),
+    };
+  }
+
+  // `loadDecisions` reads the index, not the records: it reports status, currency and
+  // byte count, and keeps no body. Reading the file the index named is one read of a
+  // record the reader has already asked for by id.
+  const { decisions } = await loadDecisions({ all: true });
+  const decision = decisions.find((candidate) => candidate.id === parsed.id);
+  if (decision === undefined) return null;
+  const raw = await readFile(join(DECISIONS_DIR, decision.file), 'utf8');
+  const text = redactInternalPaths(redactEstate(raw)).trim();
+  return { uri, mimeType: 'text/markdown', text, bytes: Buffer.byteLength(text) };
+}
+
+function frontmatterOf(rule) {
+  const keys = ['id', 'title', 'applies', 'priority'];
+  const present = keys.filter((key) => rule[key] !== undefined && rule[key] !== null);
+  if (present.length === 0) return '';
+  return ['---', ...present.map((key) => `${key}: ${formatValue(rule[key])}`), '---'].join('\n');
+}
+
+function formatValue(value) {
+  return Array.isArray(value) ? `[${value.join(', ')}]` : String(value);
+}
+
+/**
+ * The remedy a client gets when it asks for something that is not here.
+ *
+ * A command, not a path, for the reason every remedy in this package is a command: the
+ * reader runs this tool, not this checkout.
+ */
+const MISSING_REMEDY = `run: ${CLI} rules list, or ${CLI} graph lint to see what this copy can read`;

package/src/mcp/server.mjs

@@ -21,6 +21,7 @@
 
 import { createInterface } from 'node:readline';
 import { CLI } from '../name.mjs';
+import { RESOURCE_TEMPLATES, listResources, readResource } from './resources.mjs';
 
 /**
  * Every protocol revision this server speaks, newest first.
@@ -141,7 +142,7 @@ export async function handle(request, tools, { packageVersion, state } = {}) {
     case 'initialize':
       return reply({
         protocolVersion: v,
-        capabilities: capabilities(tools),
+        capabilities: capabilities(),
         // `serverInfo` stays in the body here even on 2026-07-28: a client that has just
         // called a method the newest revision removed is by definition an older client,
         // and the field is where it looks.
@@ -158,7 +159,7 @@ export async function handle(request, tools, { packageVersion, state } = {}) {
     case 'server/discover':
       return reply({
         supportedVersions: [...SUPPORTED_VERSIONS],
-        capabilities: capabilities(tools),
+        capabilities: capabilities(),
         instructions: INSTRUCTIONS,
         ...(cacheable(v) ? LIST_CACHE : {}),
       });
@@ -207,6 +208,29 @@ export async function handle(request, tools, { packageVersion, state } = {}) {
       }
     }
 
+    case 'resources/list':
+      return reply(
+        cacheable(v) ? { resources: await listResources(), ...LIST_CACHE } : { resources: await listResources() },
+      );
+    case 'resources/templates/list':
+      return reply(
+        cacheable(v)
+          ? { resourceTemplates: RESOURCE_TEMPLATES, ...LIST_CACHE }
+          : { resourceTemplates: RESOURCE_TEMPLATES },
+      );
+    case 'resources/read': {
+      // The code for a resource that is not there CHANGED, and a server that answers
+      // with one code to both revisions is a server that is wrong to whichever half of
+      // the client's world it is not. The newest revision forbids an empty `contents`
+      // array as the answer, so "absent" can only be an error.
+      const code = atLeast(v, '2026-07-28') ? RPC.RESOURCE_NOT_FOUND : RPC.RESOURCE_NOT_FOUND_LEGACY;
+      const uri = request.params?.uri;
+      const found = await readResource(uri);
+      if (found === null) return error(id, code, `no such resource: ${String(uri)}`);
+      return reply(
+        cacheable(v) ? { contents: [found], ...LIST_CACHE } : { contents: [found] },
+      );
+    }
     default:
       return isNotification ? null : error(id, RPC.METHOD, `unknown method "${method}"`);
   }
@@ -219,12 +243,19 @@ function serverInfo(packageVersion) {
   return { ...SERVER_INFO, version: packageVersion ?? '0.0.0' };
 }
 
-function capabilities(tools) {
+function capabilities() {
   return {
     tools: { listChanged: false },
-    // Declared only when there is something to read. A capability with no method behind
-    // it is a promise a client will keep waiting on.
-    ...(tools.resources ? { resources: { listChanged: false, subscribe: false } } : {}),
+    // Unconditional, and that is the point: every rule and every decision record ships
+    // with the package, so there is always something to read. The empty object is the
+    // documented way to say "resources, but no subscriptions and no change
+    // notifications" — both of which this server has no way to honour, and a client
+    // told otherwise would subscribe to a stream that never arrives.
+    //
+    // It used to be conditional on a property hung on the tools array, which nothing
+    // ever set: a capability gated on a flag nobody flips is the same promise a client
+    // waits on forever, only quieter.
+    resources: {},
   };
 }
 

package/src/mcp/tools.mjs

@@ -27,6 +27,7 @@ import { discover } from '../compare/discover.mjs';
 import { buildRow, summarise } from '../compare/row.mjs';
 import { GATES } from '../hooks/gates.mjs';
 import { dirtyPaths, parsePathList, readBody } from '../commands/skills.mjs';
+import { planNext, planDone } from '../plan/index.mjs';
 import { resolveWorkspace } from '../workspace.mjs';
 import { measureSkill } from '../graph/load.mjs';
 import { CLI } from '../name.mjs';
@@ -308,6 +309,30 @@ const output = {
     },
     required: ['root', 'shape', 'expectedSha', 'summary', 'repos'],
   },
+  plan_next: {
+    type: 'object',
+    properties: {
+      root: { type: 'string' },
+      next: { type: ['object', 'null'] },
+      reason: { type: ['string', 'null'] },
+    },
+    required: ['root', 'next', 'reason'],
+  },
+  plan_done: {
+    type: 'object',
+    properties: {
+      root: { type: 'string' },
+      id: { type: 'string' },
+      doc: { type: 'string' },
+      line: { type: 'number' },
+      from: { type: 'string' },
+      to: { type: 'string' },
+      wouldChange: { type: 'boolean' },
+      dryRun: { type: 'boolean' },
+      remedy: { type: ['string', 'null'] },
+    },
+    required: ['root', 'id', 'wouldChange', 'dryRun'],
+  },
   /** The shape of every tool failure, which is a result and not a protocol error. */
   error: ERROR_SHAPE,
 };
@@ -688,6 +713,65 @@ export const TOOLS = [
       };
     },
   },
+  {
+    outputSchema: output.plan_next,
+    name: 'plan_next',
+    description: 'The next queued slice whose dependencies are complete, and only that slice\'s section. Pass id to read one slice whether or not it is ready.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        root: { type: 'string', description: 'repository root; defaults to the editor cwd' },
+        id: { type: 'string', description: 'slice id; when given, return that slice' },
+      },
+      required: [],
+    },
+    async run(args) {
+      const root = rootOf(args);
+      const id = typeof args?.id === 'string' && args.id.length > 0 ? args.id : null;
+      const result = await planNext(root, id);
+      if (result.error) throw Object.assign(new Error(result.error), { remedy: result.remedy ?? null });
+      return { root: result.root, next: result.next, reason: result.reason };
+    },
+  },
+  {
+    outputSchema: output.plan_done,
+    name: 'plan_done',
+    // Same function as the command, and deliberately a preview. This surface does
+    // not write: the row change is a diff, and the command applies it behind --yes.
+    description: 'Preview the one-row rewrite for a slice. The write stays on the plan done command, behind --yes.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        root: { type: 'string', description: 'repository root; defaults to the editor cwd' },
+        id: { type: 'string', description: 'slice id' },
+        sha: { type: 'string', description: 'commit sha that closed the slice' },
+        test: { type: 'string', description: 'test command that closed it' },
+        state: { type: 'string', description: 'target state; omitted means the completed state of the repository template (Complete for tracker)' },
+      },
+      required: ['id'],
+    },
+    async run(args) {
+      const root = rootOf(args);
+      const result = await planDone(root, args?.id, {
+        sha: args?.sha ?? null,
+        test: args?.test ?? null,
+        state: args?.state ?? null,
+        dryRun: true,
+      });
+      if (result.error) throw Object.assign(new Error(result.error), { remedy: result.remedy ?? null });
+      return {
+        root: result.root,
+        id: result.id,
+        doc: result.doc,
+        line: result.line,
+        from: result.from,
+        to: result.to,
+        wouldChange: result.wouldChange,
+        dryRun: true,
+        remedy: result.remedy,
+      };
+    },
+  },
 ];
 
 export function toolNames() {