simt-dev 0.2.2 → 0.3.0

package/src/kernel/card.mjs

@@ -0,0 +1,254 @@
+// The command card: the exact commands for THIS repository, at the top of the
+// projected region (plan 0003 R10).
+//
+// The card holds the bytes a reader cannot infer. "Run the tests" is useless advice in a
+// repository whose test command is `./gradlew :app:testDebugUnitTest`; the runner, the
+// wrapper and the task name are facts about this repository, and none of them are in the
+// rules, which are the same in every repository. So the card is derived rather than
+// written: from the manifest's declared gates, the repository's own `package.json`
+// scripts, and the marker files that name its ecosystem.
+//
+// It reads committed evidence ONLY. It must never consult PATH or `node_modules`, because
+// the projected region is required to be byte-identical on two machines (plan 0003 P4,
+// R13) and a card that named whichever linter happened to be installed would differ
+// between a laptop and CI for no reason a diff could explain. Runnability is a property
+// of the machine; a command is a property of the repository.
+//
+// The focused-test entries are TEMPLATES. `{file}`, `{pkg}`, `{Test}` and `{class}` are
+// placeholders the reader fills from the file they are editing, and the label names the
+// path kind so a template is never mistaken for a command that can be pasted as-is.
+// Refining which test a given `{file}` maps to is R24's job, not R10's.
+
+import { readFile } from 'node:fs/promises';
+import { join } from 'node:path';
+
+import { ECOSYSTEMS } from '../projection/manifest.mjs';
+
+/**
+ * The card's ceiling in bytes (plan 0003 R10). Over it, the least valuable lines are
+ * dropped rather than the ceiling raised: the point of the card is the bytes a reader
+ * most needs, and an unbounded card is a second copy of the rules.
+ */
+export const CARD_LIMIT_BYTES = 600;
+
+/**
+ * The verbs the card carries, in the order a reader meets them. The plan names exactly
+ * these five. A `build` command exists only where a repository declares one, so the order
+ * is a priority as well as a sequence: the most universally true verb comes first.
+ *
+ * Exported because a second reader has to agree with it: a rule may declare `card:<verb>`
+ * as the evidence that makes its line redundant (R09), and a copy of this list living in
+ * the filter would let the card name a verb the filter called unknown.
+ */
+export const CARD_VERBS = ['build', 'test', 'lint', 'format', 'typecheck'];
+
+const VERBS = CARD_VERBS;
+
+/**
+ * The order verbs are dropped in when the card is over its ceiling: the verb whose loss a
+ * reader misses least goes first. `test` is absent on purpose — a card that dropped the
+ * test command would have dropped the one command it exists to carry.
+ */
+const DROP_ORDER = ['format', 'typecheck', 'lint', 'build'];
+
+/**
+ * Build commands for ecosystems whose build entrypoint is not a package script. Keyed by
+ * a marker fact or stack tag, whichever the ecosystem is identified by. `npm` is handled
+ * before this table, because a Node repository states its own build script and stating it
+ * again here would be a second answer to the same question.
+ */
+const BUILDS = [
+  { fact: 'has-cargo-toml', command: 'cargo build' },
+  { fact: 'has-go-mod', command: 'go build ./...' },
+  { fact: 'has-nuget', command: 'dotnet build' },
+  { fact: 'has-swift-package', command: 'swift build' },
+  { fact: 'has-mix', command: 'mix compile' },
+  { stack: 'gradle', command: './gradlew build' },
+];
+
+/**
+ * One focused-test template per path kind. Entries are ordered, and the FIRST match wins,
+ * so a repository that carries more than one marker gets the more specific template:
+ * `has-uv-lock` before `has-pyproject`, `has-android-manifest` before the plain `gradle`
+ * tag, `has-deno-config` before the Node fallback. A duplicate template for the same path
+ * kind would be two answers, and the second is the wrong one.
+ */
+const FOCUSED = [
+  { kind: 'Android', when: (s, f) => f.has('has-android-manifest'), template: () => './gradlew :{module}:testDebugUnitTest --tests {class}' },
+  { kind: 'JVM', when: (s) => s.has('gradle'), template: () => './gradlew test --tests {class}' },
+  { kind: 'Maven', when: (s, f) => f.has('has-maven-pom'), template: () => './mvnw test -Dtest={class}' },
+  { kind: 'Go package', when: (s, f) => f.has('has-go-mod'), template: () => 'go test ./{pkg} -run {Test}' },
+  { kind: 'Rust', when: (s, f) => f.has('has-cargo-toml'), template: () => 'cargo test {name}' },
+  { kind: 'Python', when: (s, f) => f.has('has-uv-lock'), template: () => 'uv run -m pytest {file}::{test}' },
+  { kind: 'Python', when: (s, f) => f.has('has-pyproject') || f.has('has-requirements'), template: () => 'pytest {file}::{test}' },
+  { kind: '.NET', when: (s, f) => f.has('has-nuget'), template: () => 'dotnet test --filter {test}' },
+  { kind: 'Swift', when: (s, f) => f.has('has-swift-package'), template: () => 'swift test --filter {test}' },
+  { kind: 'Deno', when: (s, f) => f.has('has-deno-config'), template: () => 'deno test {file}' },
+  { kind: 'Ruby', when: (s, f) => f.has('has-gemfile'), template: () => 'bundle exec rspec {file}' },
+  { kind: 'Dart', when: (s, f) => f.has('has-pubspec'), template: () => 'dart test {file}' },
+  { kind: 'Elixir', when: (s, f) => f.has('has-mix'), template: () => 'mix test {file}' },
+  {
+    kind: 'Node',
+    when: (s) => s.has('node'),
+    // The repo's own runner decides the shape. A repository whose test script is vitest
+    // or jest takes a file argument through the script; one with no such script gets the
+    // built-in runner, which is the only answer that needs nothing installed to already
+    // be true. `npm test -- <file>` is the ADR-010 shape (never `npx`).
+    template: (s, f, scripts) => {
+      const test = scripts?.test ?? '';
+      return /vitest|jest/.test(test) ? 'npm test -- {file}' : 'node --test {file}';
+    },
+  },
+];
+
+/**
+ * Verbs for ecosystems the gate table does not seed, used by the card alone.
+ *
+ * Python is the case, and it is not an oversight that the tool seeds no Python gate: the
+ * runner genuinely varies (uv, poetry, tox, nox, a project wrapper), so a seeded gate would
+ * be wrong in the repositories it guessed about. The card can still name the one command a
+ * repository has proved: a committed `uv.lock` means uv, and the uv profile is explicit
+ * that `uv run -m pytest` is correct and `uv run pytest` is not — the console entrypoint
+ * can miss the `uv` import path and run a different copy of the package than the one under
+ * test. Without a lockfile the card names the plain runner, which is what the python
+ * profile assumes when it says "no `pytest.skip`".
+ */
+const CARD_FALLBACKS = [
+  { when: (s, f) => f.has('has-uv-lock'), commands: { test: 'uv run -m pytest' } },
+  { when: (s, f) => f.has('has-pyproject') || f.has('has-requirements'), commands: { test: 'pytest' } },
+];
+
+/** A non-empty string, or null. Guards JSON that is present but not a command. */
+function text(value) {
+  return typeof value === 'string' && value.trim() !== '' ? value.trim() : null;
+}
+
+/** The repository's own `package.json` scripts, or an empty map. */
+async function readScripts(root) {
+  try {
+    const pkg = JSON.parse(await readFile(join(root, 'package.json'), 'utf8'));
+    return pkg && typeof pkg.scripts === 'object' && pkg.scripts ? pkg.scripts : {};
+  } catch {
+    // No package.json is a normal shape (a Python or Go repository), and an unreadable one
+    // is reported by the manifest path. Either way the card has no scripts to draw on.
+    return {};
+  }
+}
+
+/**
+ * The command for one verb, or null when this repository proves none.
+ *
+ * Precedence is deliberate and mirrors the manifest's own. A declared `gates.commands`
+ * entry is the repository naming its own program and wins over anything inferred; a
+ * `package.json` script is the repository's declared entrypoint (`npm run <verb>`); and
+ * the ecosystem table is the canonical command for a marker that is present but whose
+ * repository has declared nothing. The last is the same table the tool seeds gates from,
+ * so the card and the gate list cannot name two different commands for one repository.
+ */
+function resolveVerb(verb, { manifest, facts, stack, scripts }) {
+  const declared = text(manifest?.gates?.commands?.[verb]);
+  if (declared) return declared;
+
+  // The script a verb maps to. `format` is a staged gate rather than a script gate, so its
+  // two conventional script names are tried directly — `format:check` first, because that
+  // is the one a hook and CI run, which is what the card is reporting.
+  const scriptNames = verb === 'format' ? ['format:check', 'format'] : [verb];
+  for (const name of scriptNames) {
+    if (text(scripts?.[name])) return `npm run ${name}`;
+  }
+
+  if (verb === 'build') {
+    if (text(scripts?.build)) return 'npm run build';
+    for (const row of BUILDS) {
+      if (row.fact && facts.has(row.fact)) return row.command;
+      if (row.stack && stack.has(row.stack)) return row.command;
+    }
+    return null;
+  }
+
+  for (const eco of ECOSYSTEMS) {
+    if (!facts.has(eco.fact)) continue;
+    const command = text(eco.commands?.[verb]);
+    if (command) return command;
+  }
+  for (const row of CARD_FALLBACKS) {
+    if (!row.when(stack, facts, scripts)) continue;
+    const command = text(row.commands?.[verb]);
+    if (command) return command;
+  }
+  return null;
+}
+
+/** The text a set of lines renders to. Kept beside `commandCard` so both agree. */
+function renderCard(lines) {
+  const body = lines.map((l) => `- ${l.label}: \`${l.command}\``).join('\n');
+  return `Commands for this repository:\n\n${body}`;
+}
+
+function renderBytes(lines) {
+  return lines.length === 0 ? 0 : Buffer.byteLength(renderCard(lines));
+}
+
+/**
+ * The index of the next line to drop, or -1 when nothing may be dropped.
+ *
+ * Verbs drop in `DROP_ORDER`. Focused templates drop only after every verb, from the last
+ * first, because a focused template is the plan's headline content and a repository with
+ * several is the one case where dropping one still leaves the reader a template.
+ */
+function pickDroppable(lines) {
+  for (const verb of DROP_ORDER) {
+    const at = lines.findIndex((l) => l.verb === verb);
+    if (at !== -1) return at;
+  }
+  for (let i = lines.length - 1; i >= 0; i -= 1) {
+    if (lines[i].verb === 'focused') return i;
+  }
+  return -1;
+}
+
+/**
+ * Build the card for one repository.
+ *
+ * @param {{root: string, manifest?: object, stack?: string[], facts?: string[]}} input
+ * @returns {Promise<{text: string, bytes: number, lines: {label: string, command: string,
+ *   verb: string}[], dropped: string[]}>}
+ */
+export async function commandCard({ root, manifest = null, stack = [], facts = [] }) {
+  const factSet = new Set(facts);
+  const stackSet = new Set(stack);
+  const scripts = await readScripts(root);
+
+  const lines = [];
+  for (const verb of VERBS) {
+    const command = resolveVerb(verb, { manifest, facts: factSet, stack: stackSet, scripts });
+    if (command) lines.push({ label: verb, command, verb });
+  }
+  for (const entry of FOCUSED) {
+    if (!entry.when(stackSet, factSet, scripts)) continue;
+    // One template per path kind: `has-uv-lock` and `has-pyproject` both match a uv repo,
+    // and two Python lines would be two answers with the second one wrong.
+    if (lines.some((l) => l.kind === entry.kind)) continue;
+    lines.push({
+      label: `focused test (${entry.kind})`,
+      command: entry.template(stackSet, factSet, scripts),
+      kind: entry.kind,
+      verb: 'focused',
+    });
+  }
+
+  // Fit under the ceiling by dropping whole lines, least valuable first. Nothing is cut
+  // silently: `dropped` names every line removed so the caller can say so, because a card
+  // that quietly lost a command is a card a reader cannot tell is incomplete.
+  const dropped = [];
+  let kept = lines.slice();
+  while (renderBytes(kept) > CARD_LIMIT_BYTES) {
+    const victim = pickDroppable(kept);
+    if (victim === -1) break;
+    dropped.push(kept[victim].label);
+    kept = kept.filter((_, i) => i !== victim);
+  }
+
+  const text = kept.length > 0 ? renderCard(kept) : '';
+  return { text, bytes: Buffer.byteLength(text), lines: kept, dropped };
+}

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/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: {},
   };
 }