simt-dev 0.4.0 → 0.6.0

package/src/mcp/resources.mjs

@@ -1,13 +1,14 @@
-// Rules and decisions as MCP resources.
+// Rules, decisions, the kernel region and the next plan slice 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 -
+// The tools answer questions and the answers are arguments to the next call. These
+// answer a different request: "what is the rule you would apply, in full", "what does an
+// agent actually read here", "what does the plan say to do next". 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
+// All 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.
@@ -16,9 +17,9 @@ 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 { planNext } from '../plan/index.mjs';
 import { loadMdcRules } from '../projection/mdc.mjs';
-import { loadRules } from '../projection/rules.mjs';
+import { desiredRegion, loadRules } from '../projection/rules.mjs';
 
 const RULES_SCHEME = 'simt://rules/';
 const DECISIONS_SCHEME = 'simt://decisions/';
@@ -27,7 +28,9 @@ 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.
+ * finding names an ADR, so the template's variable names match what those print. The two
+ * fixed resources (`simt://kernel`, `simt://plan/next`) have no handle to substitute and
+ * so are listed directly, not templated.
  */
 export const RESOURCE_TEMPLATES = [
   {
@@ -57,12 +60,21 @@ export const RESOURCE_TEMPLATES = [
  */
 function parseResourceUri(uri) {
   if (typeof uri !== 'string') return null;
+  // `simt://kernel` is one resource and not a collection: there is no handle to split,
+  // so it is matched whole, and anything that only looks like it (`simt://kernel/`)
+  // falls through to the refusals below.
+  if (uri === 'simt://kernel') return { collection: 'kernel' };
   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;
+  // `plan` holds one resource per working plan, and the handle says which: `next` is the
+  // plan's own vocabulary for the next ready slice. Any other handle names a resource
+  // that does not exist, so it is refused here rather than resolved against a reader's
+  // guess.
+  if (name === 'plan') return id === 'next' ? { collection: 'plan', id: 'next' } : null;
   if (name !== 'rules' && name !== 'decisions') return null;
   return { collection: name, id };
 }
@@ -79,20 +91,67 @@ function resource(collection, id, title, bytes) {
 }
 
 /**
- * Every rule and every decision record, one entry each.
+ * The kernel region for a root, rendered on demand.
+ *
+ * `simt://kernel` promises the kernel's bytes by its name, whatever the repository
+ * declared: the declared mode governs what `sync` writes to disk, not what a read path
+ * may look at, and a read that re-consulted the manifest would answer a different
+ * question than the URI asked (ADR-002). `mode` is threaded through `desiredRegion` for
+ * exactly this caller.
+ */
+function kernelRegion(root) {
+  return desiredRegion(root, { mode: 'kernel' });
+}
+
+/**
+ * Every rule, every decision record, the kernel and - when one is ready - the next
+ * plan slice, 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.
+ *
+ * The slice is listed only when one is ready. A listing that promises a read the server
+ * then answers with "not found" is a listing that lies, and the plan's "no ready slice"
+ * cases are information about the plan, which the `plan_next` tool reports, not about a
+ * resource's text.
  */
-export async function listResources() {
-  const [rules, mdc, { decisions }] = await Promise.all([loadRules(null), loadMdcRules(), loadDecisions({ all: true })]);
+export async function listResources(root = process.cwd()) {
+  const [rules, mdc, { decisions }, region, plan] = await Promise.all([
+    loadRules(null),
+    loadMdcRules(),
+    loadDecisions({ all: true }),
+    kernelRegion(root),
+    planNext(root, null),
+  ]);
   // `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.
+  // a size that disagrees with the payload is worse than a size that rounds. The kernel
+  // and the slice have no such gap - both serve exactly what they list - so their sizes
+  // are the served ones.
   return [
+    {
+      uri: 'simt://kernel',
+      name: 'kernel',
+      title: 'The kernel region',
+      description: 'The rules this repository packs in kernel mode, with the deferrals named by their fetch command',
+      mimeType: 'text/markdown',
+      size: Buffer.byteLength(region.body),
+    },
+    ...(plan.error || !plan.next
+      ? []
+      : [
+          {
+            uri: 'simt://plan/next',
+            name: 'plan/next',
+            title: 'Next plan slice',
+            description: plan.next.title ?? 'the next slice whose dependencies are complete',
+            mimeType: 'text/markdown',
+            size: plan.next.sectionBytes,
+          },
+        ]),
     ...[...rules, ...mdc]
       .filter((rule) => rule.id !== null)
       .map((rule) => resource('rules', rule.id, rule.title ?? rule.id, rule.bytes)),
@@ -107,10 +166,33 @@ export async function listResources() {
  * 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) {
+export async function readResource(uri, root = process.cwd()) {
   const parsed = parseResourceUri(uri);
   if (parsed === null) return null;
 
+  if (parsed.collection === 'kernel') {
+    const region = await kernelRegion(root);
+    return {
+      uri,
+      mimeType: 'text/markdown',
+      text: region.body,
+      // Listed size is read size here on purpose: the body is served exactly as it is
+      // rendered, so a client that budgets on the listing gets what it budgeted for.
+      bytes: Buffer.byteLength(region.body),
+    };
+  }
+
+  if (parsed.collection === 'plan') {
+    const plan = await planNext(root, null);
+    if (plan.error || !plan.next) return null;
+    return {
+      uri,
+      mimeType: 'text/markdown',
+      text: plan.next.section,
+      bytes: plan.next.sectionBytes,
+    };
+  }
+
   if (parsed.collection === 'rules') {
     const [rules, mdc] = await Promise.all([loadRules(null), loadMdcRules()]);
     const rule = [...rules, ...mdc].find((candidate) => candidate.id === parsed.id);
@@ -147,11 +229,3 @@ function frontmatterOf(rule) {
 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

@@ -1,8 +1,9 @@
 // The MCP transport: newline-delimited JSON-RPC 2.0 on stdio.
 //
 // This file is the PROTOCOL and nothing else. It knows about `initialize`,
-// `tools/list`, `tools/call` and `ping`; it knows nothing about skills, rules or repos.
-// The tools themselves live in `src/mcp/tools.mjs`.
+// `tools/list`, `tools/call`, `resources/*`, `prompts/*` and what remains of `ping`; it
+// knows nothing about skills, rules or repos. The tools live in `src/mcp/tools.mjs`, the
+// resources in `src/mcp/resources.mjs`, the prompts in `src/mcp/prompts.mjs`.
 //
 // Three decisions, each of which is a place where the obvious implementation is wrong:
 //
@@ -21,6 +22,7 @@
 
 import { createInterface } from 'node:readline';
 import { CLI } from '../name.mjs';
+import { getPrompt, PROMPTS } from './prompts.mjs';
 import { RESOURCE_TEMPLATES, listResources, readResource } from './resources.mjs';
 
 /**
@@ -96,12 +98,17 @@ const LIST_CACHE = { ttlMs: 3600000, cacheScope: 'private' };
  * revision would hand it fields it did not ask for. So the version is read from the
  * request when there is one and remembered only for the clients that need it.
  *
+ * `root` is the repository the read surface answers for. The resources carry no argument
+ * channel in the specification - `resources/read` takes a URI and nothing else - so the
+ * caller names the root and the default is the process's cwd, which is what an editor's
+ * stdio server sits in.
+ *
  * @param {object|null} request a parsed JSON-RPC message
  * @param {object[]} tools
- * @param {{packageVersion?: string, state?: {version: string|null}}} options
+ * @param {{packageVersion?: string, state?: {version: string|null}, root?: string}} options
  * @returns {Promise<object|null>}
  */
-export async function handle(request, tools, { packageVersion, state } = {}) {
+export async function handle(request, tools, { packageVersion, state, root } = {}) {
   if (request === null || typeof request !== 'object' || Array.isArray(request)) {
     return error(null, RPC.REQUEST, 'request must be a JSON object');
   }
@@ -210,7 +217,7 @@ export async function handle(request, tools, { packageVersion, state } = {}) {
 
     case 'resources/list':
       return reply(
-        cacheable(v) ? { resources: await listResources(), ...LIST_CACHE } : { resources: await listResources() },
+        cacheable(v) ? { resources: await listResources(root), ...LIST_CACHE } : { resources: await listResources(root) },
       );
     case 'resources/templates/list':
       return reply(
@@ -225,12 +232,28 @@ export async function handle(request, tools, { packageVersion, state } = {}) {
       // 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);
+      const found = await readResource(uri, root);
       if (found === null) return error(id, code, `no such resource: ${String(uri)}`);
       return reply(
         cacheable(v) ? { contents: [found], ...LIST_CACHE } : { contents: [found] },
       );
     }
+    case 'prompts/list':
+      return reply(
+        cacheable(v) ? { prompts: PROMPTS, ...LIST_CACHE } : { prompts: PROMPTS },
+      );
+    case 'prompts/get': {
+      const name = params?.name;
+      // `getPrompt` returns null only for a prompt this server does not have: its
+      // argument failures degrade into the template text itself, because an unfilled
+      // variable is still readable and the agent it reaches can ask the user. A named
+      // prompt that does not exist is the client's mistake, so it is a protocol error -
+      // the same rule as tools/call, and for the same reason: there is no result shape
+      // that means absence.
+      const found = await getPrompt(name, params?.arguments ?? {});
+      if (found === null) return error(id, RPC.METHOD, `no prompt named "${String(name)}"; call prompts/list first`);
+      return reply(found);
+    }
     default:
       return isNotification ? null : error(id, RPC.METHOD, `unknown method "${method}"`);
   }
@@ -256,6 +279,10 @@ function capabilities() {
     // ever set: a capability gated on a flag nobody flips is the same promise a client
     // waits on forever, only quieter.
     resources: {},
+    // Two fixed templates, listed statically: there is nothing to subscribe to and
+    // nothing that changes without a release, so the same empty object makes the same
+    // promise here as above the resources.
+    prompts: {},
   };
 }
 

package/src/mcp/tools.mjs

@@ -407,7 +407,7 @@ export const TOOLS = [
     outputSchema: output.doctor,
     name: 'doctor',
     description:
-      'Classify a repository: its stack tags, the emitted facts with the file that proved each, and whether a simt-dev manifest is present. Call this first when you do not yet know what a repo is.',
+      'Classify a repository: stack tags, emitted facts with the file that proved each, and manifest presence. Call this first when the repo is unknown.',
     inputSchema: rootArg,
     async run(args) {
       const root = rootOf(args);
@@ -430,7 +430,7 @@ export const TOOLS = [
     outputSchema: output.skills_index,
     name: 'skills_index',
     description:
-      'The full skill catalogue: every skill with its summary, size, stack tags and whether it is deferred. Cheap enough to always afford, and the fallback when brief returns nothing useful.',
+      'Full skill catalogue: every skill with summary, size, stack tags and deferred flag. The fallback when brief returns nothing useful.',
     inputSchema: noArgs,
     async run(args) {
       const { registry: reg, verified, workspace } = await registry(args);
@@ -451,7 +451,7 @@ export const TOOLS = [
     outputSchema: output.skills_brief,
     name: 'skills_brief',
     description:
-      'THE entry point. Resolve the skill set for a task in a repository. Returns what was selected, why each was selected, what was deferred, and what was NOT selected with the reason - the last part matters, because it is what lets 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 reason - the reasons let you override the resolver instead of guessing at it.',
     inputSchema: {
       type: 'object',
       properties: {
@@ -517,7 +517,7 @@ export const TOOLS = [
   {
     outputSchema: output.skills_show,
     name: 'skills_show',
-    description: 'One skill body, with the metadata needed to decide whether to trust it: source path, which of the two locations it was read from, and its cited decisions.',
+    description: 'One skill body and the metadata needed to judge it: source path, the location it was read from, and its cited decisions.',
     inputSchema: {
       type: 'object',
       properties: {
@@ -585,7 +585,7 @@ export const TOOLS = [
     outputSchema: output.skills_why,
     name: 'skills_why',
     description:
-      'The signal chain for one skill in one repository: its score, the reasons behind it, whether the stack gate admits it at all, and what it would take to make it selected.',
+      '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' } },
@@ -619,7 +619,7 @@ export const TOOLS = [
     outputSchema: output.rules_list,
     name: 'rules_list',
     description:
-      'The rule catalogue, and which rules a given repository actually receives. Pass `root` to get the selection rather than just the catalogue.',
+      'The rule catalogue, and which rules a repository actually receives. Pass root for the selection, not just the catalogue.',
     inputSchema: {
       type: 'object',
       properties: { root: { type: 'string' } },
@@ -657,7 +657,7 @@ export const TOOLS = [
     outputSchema: output.rules_why,
     name: 'rules_why',
     description:
-      'Why a rule exists. Give a rule id for the decisions that settled it and whether each is still in force, or an ADR id for the rules that decision repeats. A rule citing no decision reports that - it is a finding, not an empty answer.',
+      'Why a rule exists: a rule id for the decisions that settled it, or an ADR id for the rules that repeat it. An uncited rule is a finding, reported so.',
     inputSchema: {
       type: 'object',
       properties: { what: { type: 'string', description: 'a rule id or ADR-NNN' } },
@@ -713,7 +713,7 @@ export const TOOLS = [
     outputSchema: output.check,
     name: 'check',
     description:
-      'The gate for one repository: is its generated region current, unmanaged, drifted or malformed, and does any rule file lack an id. Read-only - it never repairs.',
+      'The gate for one repository: region current, unmanaged, drifted or malformed, and rule files lacking an id. Read-only - it never repairs.',
     inputSchema: rootArg,
     async run(args) {
       const root = rootOf(args);
@@ -730,7 +730,7 @@ export const TOOLS = [
     outputSchema: output.compare,
     name: 'compare',
     description:
-      'The organisation-wide matrix: every repository under the root, its adoption, region state, pinned simt-dev SHA, hook routing and declared gates, plus the problems found. This is the command that replaces reconstructing the estate by hand.',
+      'The workspace matrix: every repository with its adoption, region state, pinned SHA, hook routing and gates, plus the problems found.',
     inputSchema: {
       type: 'object',
       properties: {
@@ -761,7 +761,7 @@ 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.',
+    description: "The next queued slice whose dependencies are complete; its design section only. Pass id for one slice whether or not it is ready.",
     inputSchema: {
       type: 'object',
       properties: {
@@ -821,7 +821,7 @@ export const TOOLS = [
     outputSchema: output.brief,
     name: 'brief',
     description:
-      'The packet for one task, in the bytes a prompt can carry: the kind of task it is, the commands that kind needs, the files the index ranks highest, the tests that cover them, the decisions that govern them, the skills that apply and the lessons that name those paths. Every argument is optional - with no task it describes the repository itself.',
+      'The packet for one task in prompt-sized bytes: task kind, needed commands, ranked files, covering tests, governing decisions, applicable skills. With no task it describes the repository.',
     inputSchema: {
       type: 'object',
       properties: {
@@ -868,7 +868,7 @@ export const TOOLS = [
     outputSchema: output.federation_query,
     name: 'federation_query',
     description:
-      'Ask a code-graph server this repository declared one structural question, and return its answer with the name of the server that gave it. Read-only: it reads the "federation" block from simt.json and starts only the servers the manifest itself names, and a repository that declared none is told so rather than queried.',
+      'Ask a declared code-graph server one structural question; the answer names the server that gave it. Starts only servers simt.json names; a repository declaring none is told so.',
     inputSchema: {
       type: 'object',
       properties: {

package/src/measure/session.mjs

@@ -11,7 +11,7 @@ import { resolve } from 'node:path';
 import { tokens } from './context.mjs';
 
 const RULE_PATH_RE =
-  /(?:^|\/)(?:AGENTS(?:\.override)?\.md|CLAUDE(?:\.local)?\.md|GEMINI\.md|SKILL\.md|\.cursor\/rules\/|\.claude\/rules\/|\.agents\/rules\/|\.github\/(?:copilot-instructions\.md|instructions\/)|\.simt-dev\/profiles\/)/;
+  /(?:^|\/)(?:AGENTS(?:\.override)?\.md|CLAUDE(?:\.local)?\.md|GEMINI\.md|SKILL\.md|\.cursor\/rules\/|\.claude\/rules\/|\.agents\/rules\/|\.github\/(?:copilot-instructions\.md|instructions\/)|\.simt\/profiles\/)/;
 
 const FILE_READ_TOOLS = new Set(['Read', 'read_file', 'NotebookRead', 'view_file', 'read']);
 

package/src/memory/decide.mjs

@@ -244,7 +244,7 @@ export async function diffAffectedPaths(root) {
   const addLines = (stdout) => {
     for (const line of String(stdout ?? '').split(/\r?\n/)) {
       const trimmed = line.trim();
-      if (trimmed && !trimmed.startsWith('.simt-dev/')) paths.add(trimmed);
+      if (trimmed && !trimmed.startsWith('.simt/')) paths.add(trimmed);
     }
   };
   for (const args of [

package/src/memory/lessons.mjs

@@ -1,6 +1,6 @@
 // Deterministic lesson candidate ledger and promotion to `docs/lessons/NNNN-<slug>.md` (plan 0003 R32).
 //
-// Four deterministic candidate sources write to `.simt-dev/lessons.jsonl`:
+// Four deterministic candidate sources write to `.simt/lessons.jsonl`:
 //   1. `fail-then-fix`: a gate or test that fails and then passes in one session,
 //      recorded as `error signature -> fix diff` (where the signature is the sha256
 //      hash of the normalised first error line);
@@ -23,7 +23,7 @@ import { splitFrontmatter } from './decide.mjs';
 
 const exec = promisify(execFile);
 
-export const LESSONS_FILE = '.simt-dev/lessons.jsonl';
+export const LESSONS_FILE = '.simt/lessons.jsonl';
 export const LESSONS_DIR = 'docs/lessons';
 export const LESSON_KEYS = new Set(['simt-trigger', 'simt-evidence', 'simt-expires']);
 const DEFAULT_EXPIRES = '2027-04-01';
@@ -137,7 +137,7 @@ function slugify(text) {
 }
 
 /**
- * Read all candidate records from `.simt-dev/lessons.jsonl`.
+ * Read all candidate records from `.simt/lessons.jsonl`.
  *
  * @param {string} root
  * @returns {Promise<{candidates: Array<object>, errors: string[]}>}
@@ -181,7 +181,7 @@ function sameEvidence(a = [], b = []) {
 }
 
 /**
- * Append one deterministic candidate to `.simt-dev/lessons.jsonl`, deduplicating by
+ * Append one deterministic candidate to `.simt/lessons.jsonl`, deduplicating by
  * `(kind, signature, evidence)`.
  *
  * @param {string} root
@@ -239,11 +239,11 @@ async function diffBetweenTrees(root, fromRef, toRef) {
   }
   try {
     const [namesOut, diffOut] = await Promise.all([
-      exec('git', ['diff', '--name-only', fromRef, toRef, '--', '.', ':(exclude).simt-dev'], {
+      exec('git', ['diff', '--name-only', fromRef, toRef, '--', '.', ':(exclude).simt'], {
         cwd: root,
         maxBuffer: 8 << 20,
       }),
-      exec('git', ['diff', '--unified=3', fromRef, toRef, '--', '.', ':(exclude).simt-dev'], {
+      exec('git', ['diff', '--unified=3', fromRef, toRef, '--', '.', ':(exclude).simt'], {
         cwd: root,
         maxBuffer: 8 << 20,
       }),
@@ -295,8 +295,8 @@ export async function recordFailThenFix(root, { failEntry, passEntry, failOutput
 }
 
 /**
- * Scan `.simt-dev/ledger.jsonl` for any fail-then-fix sequences in the session and
- * ensure each is recorded in `.simt-dev/lessons.jsonl`.
+ * Scan `.simt/ledger.jsonl` for any fail-then-fix sequences in the session and
+ * ensure each is recorded in `.simt/lessons.jsonl`.
  *
  * @param {string} root
  * @param {Array<object>} [entries]
@@ -306,7 +306,7 @@ export async function captureFromLedger(root, entries = null) {
   let list = entries;
   if (!Array.isArray(list)) {
     try {
-      const raw = await readFile(join(root, '.simt-dev', 'ledger.jsonl'), 'utf8');
+      const raw = await readFile(join(root, '.simt', 'ledger.jsonl'), 'utf8');
       list = raw
         .split('\n')
         .map((s) => s.trim())
@@ -339,7 +339,7 @@ export async function captureFromLedger(root, entries = null) {
 }
 
 /**
- * Capture reverted commits from git history into `.simt-dev/lessons.jsonl`.
+ * Capture reverted commits from git history into `.simt/lessons.jsonl`.
  *
  * @param {string} root
  * @param {{limit?: number}} [options]
@@ -408,7 +408,7 @@ export async function captureRevertedCommits(root, options = {}) {
 }
 
 /**
- * Record an ADR-008 `BLOCK` review finding in `.simt-dev/lessons.jsonl`.
+ * Record an ADR-008 `BLOCK` review finding in `.simt/lessons.jsonl`.
  *
  * @param {string} root
  * @param {{summary: string, paths?: string[], evidence?: string[], fixDiff?: string, keywords?: string[]}} finding
@@ -437,7 +437,7 @@ export async function recordReviewBlock(root, finding) {
 }
 
 /**
- * Record an agent-time hook denial (R15) in `.simt-dev/lessons.jsonl`.
+ * Record an agent-time hook denial (R15) in `.simt/lessons.jsonl`.
  *
  * @param {string} root
  * @param {{harness?: string, event?: string, policies?: string[], messages?: string[], command?: string, writes?: string[]}} denial
@@ -612,7 +612,7 @@ async function nextLessonNumber(root) {
 }
 
 /**
- * Promote a lesson candidate from `.simt-dev/lessons.jsonl` to `docs/lessons/NNNN-<slug>.md`.
+ * Promote a lesson candidate from `.simt/lessons.jsonl` to `docs/lessons/NNNN-<slug>.md`.
  *
  * @param {string} root
  * @param {{id?: string, apply?: boolean, paths?: string[], expires?: string, title?: string}} [options]
@@ -622,7 +622,7 @@ export async function promoteLesson(root, options = {}) {
   await captureFromLedger(root);
   const { candidates } = await readLessonCandidates(root);
   if (candidates.length === 0) {
-    return { ok: false, error: 'no lesson candidates in .simt-dev/lessons.jsonl' };
+    return { ok: false, error: 'no lesson candidates in .simt/lessons.jsonl' };
   }
 
   let target = null;

package/src/name.mjs

@@ -45,6 +45,16 @@ export const MARKER_PREFIX_LEGACY = 'simt-dev';
 /** The config directory on the adopting engineer's machine. LOCKED, same argument. */
 export const CONFIG_DIR = PROJECT;
 
+/**
+ * The per-repository state directory: the index, ledger, benchmark runs and local-model
+ * proposals a repository writes for itself. Renamed from `.simt-dev` to `.simt`; the
+ * rename is unreleased, so no repository carries the old spelling as a name this tool
+ * cannot rewrite. Deliberately not derived from CONFIG_DIR: that is the user-level
+ * config directory, and a derivation would let two different on-disk names agree by
+ * accident rather than by decision.
+ */
+export const STATE_DIR = '.simt';
+
 /**
  * The gate this tool writes into a repository. LOCKED: it is a path in `.github`, and
  * a repo that renames the file silently stops running the gate it was adopted with.
@@ -92,4 +102,4 @@ export const CLI = 'simt';
 export const PACKAGE_NAME = PROJECT;
 
 /** The entry point, relative to the package root. LOCKED: `bin` in package.json. */
-export const BIN_REL = 'bin/simt-dev.mjs';
+export const BIN_REL = 'bin/simt.mjs';

package/src/package-version.mjs

@@ -3,14 +3,16 @@
 // Three distinct things that must not be confused:
 //   - packageVersion() is the version of the binary that is RUNNING. It is read from
 //     the package this code lives in, so it is correct whether the binary was resolved
-//     from node_modules, a global install, or a source checkout.
+//     from node_modules, the release binary in `.simt/bin`, a global install, or a
+//     source checkout.
 //   - hasNpm(root) is the KIND of repository: does it have a package.json? That decides
-//     how it obtains simt-dev at all — pinned as a devDependency where one exists, a
-//     pinned global install where there is no node_modules to pin in.
+//     how it obtains simt-dev at all — pinned as a devDependency where one exists, the
+//     release binary into the repository where there is no node_modules to pin in
+//     (ADR-098).
 //   - the pin is the version a repository recorded when it adopted simt-dev, stored in
-//     the manifest's projection.version. It is what a global install must match: npm
-//     pins the node_modules copy for us, but nothing pins a global binary, so the gate
-//     compares the running version against the pin and refuses on a mismatch.
+//     the manifest's projection.version. It is what an install outside node_modules
+//     must match: npm pins the node_modules copy for us, but nothing pins a binary, so
+//     the gate compares the running version against the pin and refuses on a mismatch.
 
 import { readFileSync } from 'node:fs';
 import { stat } from 'node:fs/promises';
@@ -38,7 +40,7 @@ export function packageVersion() {
 
 /**
  * Whether a repository has a package.json, i.e. whether it pins simt-dev as a
- * devDependency (npm) or must fall back to a global install. Async because the render
+ * devDependency (npm) or must download the release binary (ADR-098). Async because the render
  * call sites that feed it (init, hooks install, the compare stale check) are all async,
  * and a missing file is an answer (false), not an error.
  */
@@ -56,9 +58,9 @@ export async function hasNpm(root) {
  * simt-dev. Returns null when there is nothing to refuse, otherwise a message that
  * names both versions and the one command that fixes it.
  *
- * This is the gate's fail-closed guard against a stale global binary: for a repository
- * without npm, simt-dev is a global install and the only thing that knows which version
- * it should be is the pin. A node_modules copy is pinned by npm itself, so its mismatch
+ * This is the gate's fail-closed guard against a stale binary: for a repository
+ * without npm, the copy is the release binary in `.simt/bin` (ADR-098) and the only
+ * thing that knows which version it should be is the pin. A node_modules copy is pinned by npm itself, so its mismatch
  * is a stale manifest, which `upgrade` refreshes — the remedy is the same either way.
  *
  * A manifest with no recorded pin (adopted before the field existed) is skipped, not