simt-dev 0.2.2 → 0.3.0

package/src/projection/manifest.mjs

@@ -67,8 +67,12 @@ export async function manifestPath(root) {
  * real is the recorded SHA under `projection`.
  */
 export const MANIFEST_COMMENT = {
-  $comment:
-    `Written and maintained by simt-dev. Edit by hand only if you intend to take ownership of this file: \`${CLI} sync --yes\` regenerates the projected rules, and re-running \`${CLI} init\` refreshes the SHA without weakening a value you set here.`,
+  $comment: [
+    `Written and maintained by simt-dev. \`${CLI} sync --yes\` regenerates the projected rules.`,
+    `\`${CLI} init\` refreshes the SHA and keeps every key it does not write, so a value you add here survives a re-init.`,
+    `\`plans\` is such a key: it selects the tracker template and the directories \`${CLI} plan\` reads.`,
+    'Omit it and the tracker template applies, which reads docs/plans and docs/reviews.',
+  ].join(' '),
 };
 
 /**
@@ -418,7 +422,7 @@ export function buildManifest({ root, stack = [], sha, version, existing = null,
       ? { ...planned.gates, commands: planned.commands }
       : planned.gates;
 
-  return {
+  const owned = {
     ...MANIFEST_COMMENT,
     id: existing?.id ?? defaultId(root),
     stack: existing?.stack?.length ? existing.stack : stack,
@@ -473,6 +477,25 @@ export function buildManifest({ root, stack = [], sha, version, existing = null,
     // adopted. See src/package-version.mjs.
     projection: { simtDevSha: sha ?? null, version: version ?? null },
   };
+  return withRepoKeys(existing, owned);
+}
+
+/**
+ * Keys this writer does not recognise belong to the repository.
+ *
+ * A re-init used to return only the object above, so anything else in the file
+ * disappeared. `plans` is the tracker overlay, and it is not the only key a
+ * repository might have added. Owned keys stay in the order the writer emits
+ * them; an unknown key is copied after them, in the order the file had it.
+ */
+function withRepoKeys(existing, owned) {
+  if (!existing || typeof existing !== 'object' || Array.isArray(existing)) return owned;
+  const kept = {};
+  for (const key of Object.keys(existing)) {
+    if (Object.hasOwn(owned, key)) continue;
+    kept[key] = existing[key];
+  }
+  return { ...owned, ...kept };
 }
 
 /**

package/src/projection/rules.mjs

@@ -30,6 +30,8 @@ import { loadMdcRules, renderMdc } from './mdc.mjs';
 import { foldsRules, frontmatterBlock, resolveSurfaces, rulePath, canScope } from './surfaces.mjs';
 import { ruleTargets } from './targets.mjs';
 import { manifestPath, readManifest } from './manifest.mjs';
+import { commandCard, CARD_LIMIT_BYTES } from '../kernel/card.mjs';
+import { filterInferable, inferableDefect, inferableProofs } from '../kernel/inferability.mjs';
 import { BASELINES } from './baselines.mjs';
 import { CLI } from '../name.mjs';
 import { PACK_DIR, resolvePacks } from '../packs.mjs';
@@ -408,6 +410,19 @@ async function ruleBodies(root, manifest, flags) {
   return { resolved, bodies, problems, notes, skipped };
 }
 
+/**
+ * The command card for a repository and the evidence its markers may be proved by.
+ *
+ * Both the region and the package regions need the proofs, and they must be the same set:
+ * a rule dropped at the root and kept in a package would be one rule treated as two. The
+ * card comes back alongside because the caller that needs the proofs also needs the card's
+ * bytes, and building it twice would read the manifest twice for no second answer.
+ */
+async function inferableEvidence(root, { stack, facts, manifest }) {
+  const card = await commandCard({ root, manifest, stack, facts });
+  return { card, proofs: inferableProofs({ facts, stack, card, manifest }) };
+}
+
 /**
  * The one place the desired region is computed. `plan` (which writes) and
  * `checkTarget` (which gates) both go through this, so they cannot disagree
@@ -469,8 +484,50 @@ export async function desiredRegion(root, flags) {
     if (mode === 'kernel' && (r.error !== null || !KERNEL_CLASSES.has(r.priority))) deferred.push(r);
     else packed.push(r);
   }
-  let body = render(packed);
-  let sources = packed.map((r) => r.source);
+  // The command card leads the region. The exact commands for this repository are the
+  // bytes a reader cannot infer from rules that are identical everywhere (plan 0003 R10),
+  // so they go first — above even the core rules. It is derived from committed evidence
+  // only, in one place, so `plan` and `checkTarget` cannot disagree about it and two
+  // machines render it byte-identically.
+  const { card, proofs } = await inferableEvidence(root, { stack, facts, manifest });
+  if (card.dropped.length > 0) {
+    // Reported where every other projection note is reported. A card that lost a command
+    // in silence is a card a reader cannot tell is incomplete.
+    notes.push(
+      `command card: dropped ${card.dropped.join(', ')} to stay within ${CARD_LIMIT_BYTES} bytes`,
+    );
+  }
+  // Inferability (R09). A marked line leaves when the repository proves the evidence it
+  // names. `shipped` is a separate list from `packed` because they are separate decisions:
+  // the kernel is about which classes cost a reader nothing to skip, and this is about
+  // which lines the reader already knows.
+  const inferable = [];
+  const shipped = [];
+  for (const r of packed) {
+    const filtered = filterInferable(r.body, proofs);
+    if (!filtered.changed) {
+      shipped.push(r);
+      continue;
+    }
+    for (const x of filtered.removed) inferable.push({ rule: r.id, text: x.text, expr: x.expr });
+    shipped.push({ ...r, body: filtered.body });
+  }
+  let body = card.text ? `${card.text}\n\n${render(shipped)}` : render(shipped);
+  let sources = shipped.map((r) => r.source);
+  if (inferable.length > 0) {
+    // Never silent, and never a heading. A line that left with no trace repeats the
+    // mistake ADR-073 rejected for deferred rules, and a `## Dropped` section spends region
+    // bytes on lines the reader is being told not to read. A count they can act on, plus —
+    // with `--explain` — the evidence behind each one, is the third option.
+    notes.push(
+      `inferability: dropped ${inferable.length} line(s) this repository already proves; ${CLI} sync --explain names each one and the evidence behind it`,
+    );
+    if (flags?.explain === true) {
+      for (const x of inferable) {
+        notes.push(`inferable: ${x.rule} dropped "${x.text}" — proved by ${x.expr}`);
+      }
+    }
+  }
   const folded = [];
 
   // The pointer. A reader who opens AGENTS.md and does not find a profile they know is
@@ -523,6 +580,10 @@ export async function desiredRegion(root, flags) {
     folded,
     mode,
     deferred: deferred.map((r) => r.id),
+    // The marked lines that left, each with the evidence that dropped it. The region is
+    // written without them; `--explain` is what reads this list, so a removal is reportable
+    // without spending region bytes and without a second computation to find it.
+    inferable,
     // The profiles that left the region, and the surfaces that accepted them as files.
     // `plan` writes them and `checkTarget` gates them through this list, so a projected
     // file and a drifted one are decided by the same computation.
@@ -643,6 +704,7 @@ export async function loadRules(root = null) {
   for (const item of collected) {
     const text = await readFile(join(item.dir, item.file), 'utf8');
     const meta = parseFrontmatter(text);
+    const body = stripFrontmatter(text);
     out.push({
       file: item.file,
       origin: item.origin,
@@ -654,8 +716,12 @@ export async function loadRules(root = null) {
       scope: Array.isArray(meta['simt-scope']) ? meta['simt-scope'] : null,
       priority: meta['simt-priority'] ?? null,
       bytes: Buffer.byteLength(text),
-      body: stripFrontmatter(text),
-      error: describeDefect(meta),
+      body,
+      // A marker naming evidence the tool cannot check is a broken rule like any other, so
+      // it travels the field that already reaches `check` and `rules list`. The
+      // frontmatter defect wins, because a rule that cannot say what it applies to cannot
+      // be reasoned about at all.
+      error: describeDefect(meta) ?? inferableDefect(body),
     });
   }
   return out;
@@ -691,12 +757,21 @@ export async function packageRegions(root, flags, rootProfiles = null) {
 
   const rules = await loadRules(root);
   const sha = await provenanceDigest();
+  // The ROOT's proofs, not the package's. The rule set is the root's, so which lines it
+  // already proves is a fact about the repository rather than about the directory a file
+  // lands in — filtering a package by the package's own facts would keep a rule here and
+  // drop it one directory up, which is the same rule treated as two.
+  const { proofs } = await inferableEvidence(root, await fingerprint(root));
   const regions = [];
   for (const pkg of packages) {
     const fp = await fingerprint(join(root, pkg.path));
     const { selected } = select(rules, fp.stack ?? [], fp.facts ?? []);
     const delta = selected.filter((r) => !shared.includes(r.id));
     if (delta.length === 0) continue;
+    const shipped = delta.map((r) => {
+      const filtered = filterInferable(r.body, proofs);
+      return filtered.changed ? { ...r, body: filtered.body } : r;
+    });
     regions.push({
       path: pkg.path,
       ecosystem: pkg.ecosystem,
@@ -706,7 +781,7 @@ export async function packageRegions(root, flags, rootProfiles = null) {
       // One sentence, because the file's whole purpose is to be found by a reader
       // who does not know it exists: without it, a nested region reads as a
       // complete set of rules and the shared half looks forgotten.
-      body: `The rules this package selects on its own. Everything the repository shares with its other packages is in the region at the root.\n\n${render(delta)}`,
+      body: `The rules this package selects on its own. Everything the repository shares with its other packages is in the region at the root.\n\n${render(shipped)}`,
       meta: { sha, sources: delta.map((r) => r.source) },
     });
   }

package/src/projection/surfaces.mjs

@@ -91,13 +91,13 @@ export const SURFACES = [
     id: 'opencode',
     label: 'opencode (AGENTS.md + .agents/skills)',
     readers:
-      'opencode, and AGENTS.md is also read natively by Codex, Cursor, Windsurf, Zed, Amp, Jules, Copilot CLI and the DeepSeek harness; Claude Code falls back to it, Antigravity and Gemini CLI accept GEMINI.md as an equal name',
+      'OpenCode v2, and AGENTS.md is also read natively by Codex, Cursor, Windsurf, Zed, Amp, Jules, Copilot CLI and the DeepSeek harness; Claude Code falls back to it, Antigravity and Gemini CLI accept GEMINI.md as an equal name',
     primary: 'AGENTS.md',
     kind: 'region',
-    // opencode documents NO per-rule directory: it reads AGENTS.md (walking up to the
-    // git worktree), CLAUDE.md only as a fallback, and .opencode/AGENTS.md in
-    // addition. So `foldRules` — this surface carries every rule inside the one
-    // generated region, and the other rows are how a rule reaches an editor that
+    // OpenCode v2 documents no per-rule directory. It reads AGENTS.md only — every
+    // file from the workspace up to the project root, combined — and it does not fall
+    // back to CLAUDE.md. So `foldRules`: this surface carries every rule inside the
+    // one generated region, and the other rows are how a rule reaches an editor that
     // cannot read AGENTS.md. Writing .opencode/rules/*.md would be a guess, and a
     // guessed path is the failure this table exists to prevent.
     rule: null,
@@ -118,7 +118,7 @@ export const SURFACES = [
       },
     ],
     verified:
-      'opencode docs, "Rules" and "Agent Skills" (read 2026-10-07) — AGENTS.md walked up from cwd to the git worktree; CLAUDE.md used only if no AGENTS.md exists; .opencode/AGENTS.md additionally; skills at .opencode/skills/, .claude/skills/ and .agents/skills/<name>/SKILL.md; skill frontmatter recognises only name, description, license, compatibility, metadata',
+      'OpenCode v2 instructions and skills docs (opencode.ai/v2/docs, read 2026-10-14) — AGENTS.md only, combined from the workspace up to the project root; CLAUDE.md is not a fallback; skills at .opencode/skills/, .claude/skills/ and .agents/skills/<name>/SKILL.md, with the model shown name and description',
     note:
       '.agents/skills is one of the three skill locations opencode documents, so the same directory serves the standard surface without a symlink.',
   },
@@ -286,8 +286,12 @@ export const POINTERS = [
     to: 'AGENTS.md',
     readers: 'Gemini CLI, Antigravity',
     verified:
-      'Google Antigravity docs, "Rules": workspace rules are AGENTS.md or GEMINI.md in the root or any subdirectory; Copilot CLI also discovers GEMINI.md',
-    note: 'Covers Gemini CLI and gives Antigravity a second, equally-native name for the same file.',
+      'Google Antigravity docs, "Rules": workspace rules are AGENTS.md or GEMINI.md in the root or any subdirectory; Copilot CLI also discovers GEMINI.md. ' +
+      'Gemini CLI, read today: its own docs (core memory index, and the configuration reference) say the memory service loads GEMINI.md hierarchically from the working directory up to the project root and the home directory and also into subdirectories, and that `context.fileName` in settings.json "accepts either a single string or an array of strings" naming the context file(s) to load, default undefined',
+    note:
+      'Covers Gemini CLI and gives Antigravity a second, equally-native name for the same file. ' +
+      'A repository can also point Gemini CLI at AGENTS.md itself with `context.fileName: ["AGENTS.md"]` and need no pointer at all, ' +
+      'which is the reason there is no separate Gemini CLI row here: this pointer and a native row would be two ways to hand one reader the same rule.',
   },
 ];
 
@@ -399,6 +403,16 @@ export const CANDIDATE_DIRS = [
   { dir: '.continue', harness: 'Continue' },
   { dir: '.amp', harness: 'Amp' },
   { dir: '.goose', harness: 'Goose' },
+  // Home directory, seen only with `harness detect --user`. DeepSeek keeps user data
+  // under ~/.dsh and reads the repository's AGENTS.md; it has no project config
+  // directory and no per-rule file to project (ADR-067).
+  {
+    dir: '.dsh',
+    harness: 'DeepSeek harness',
+    readsAgentsMd: 'all',
+    verified:
+      'DeepSeek harness agent-instructions docs (read 2026-10-14): user data lives at $DSH_HOME or ~/.dsh, and the project chain is AGENTS.md',
+  },
 ];
 
 /**

package/src/toolwords.mjs

@@ -0,0 +1,69 @@
+// The `simt-` names this tool owns, and the records that argue about the prefix itself.
+//
+// Two readers need to tell this tool's own vocabulary from a repository in the estate
+// these records were written about: the decision reader, which redacts the second kind
+// and names it, and the guard on shipped text, which refuses to ship it. Both answered
+// the question with a shape — `simt-` followed by anything but `dev` — and the shape is
+// false about the tool's own names, which the corpus prints. `rules why ADR-073` reported
+// that the ruling surveyed `simt-priority` as a repository, and printed the same word as
+// `a repository: hard | command | convention | style` where the record says
+// `simt-priority: hard | command | convention | style`: a reader with the tool and not
+// the estate got a sentence with no subject, from the command whose whole job is to
+// explain a citation.
+//
+// The words are derived from the modules that own them (ADR-022) rather than listed
+// here, because a second list is a list that drifts and then forgives. Both readers read
+// this one, and a name added to a frontmatter vocabulary reaches both without an edit.
+import { KNOWN_KEYS } from './projection/mdc.mjs';
+import { PROFILE_KEYS } from './projection/rules.mjs';
+import { INFERABLE_MARKER } from './kernel/inferability.mjs';
+
+/**
+ * `simt-` names that belong to this tool and never to a repository.
+ *
+ * The last three are not frontmatter: they are names this tool writes into files it
+ * adopts a repository into — the package, the gate file it puts in `.github`, and the
+ * hooks directory it points `core.hooksPath` at. `simt-dev` itself is here for the same
+ * reason the estate pattern exempts it, and stating it once here is what stops the two
+ * readers from disagreeing about the tool's own name.
+ */
+export const TOOL_WORDS = new Set([
+  ...KNOWN_KEYS,
+  ...PROFILE_KEYS,
+  INFERABLE_MARKER,
+  'simt-dev',
+  'simt-dev-check',
+  'simt-hooks',
+]);
+
+/**
+ * Records whose subject is the prefix itself, so the prefixed names in them are the
+ * argument rather than a citation.
+ *
+ * Each entry is a file and a reason, never a repository. That distinction is the whole
+ * point: an exemption says "this document discusses the namespace", which is a fact
+ * about this tool and carries nothing about whoever uses it. A vocabulary cannot settle
+ * these two — a hypothetical key in an argument and a repository name are the same shape
+ * — so the file is exempted where the word cannot be.
+ *
+ * The guard fails on a stale entry: each one must still be tripping the rule, so an
+ * exemption that stops being needed is removed rather than kept as a precedent.
+ */
+export const PREFIX_ARGUING = new Map([
+  [
+    'ADR-022-a-key-simt-dev-reads-is-prefixed.md',
+    'is the record arguing for the prefix, using hypothetical keys as examples',
+  ],
+  [
+    'ADR-026-a-config-without-a-region-is-a-file-the-repo-owns.md',
+    'names one prefixed key to record Dependabot rejecting it',
+  ],
+  [
+    'ADR-080-the-tools-own-names-are-not-repositories-and-neither-reader-decides-by-shape.md',
+    'quotes the prefixed names it measured, which are its evidence rather than a citation',
+  ],
+  [
+    'ADR-081-a-tracker-is-read-through-the-repositorys-template.md',
+    'names the plan overlay file the next record withdraws, and that filename has the shape of a repository',
+  ],
+]);

package/templates/plan/tracker.json

@@ -0,0 +1,36 @@
+{
+  "$comment": "Tracker format delivered with the tool. A repository replaces any section with the plans key in simt.json; a section it omits stays as written here. directories are the only places read, and each word is what a dependency uses to name that place (\"review 0002 S41\"). Headers are tried in the order written. Only a state marked satisfies unblocks a slice that depends on it. ready is the state plan next returns. dependency.group matches a wave of rows; wave names that table's columns.",
+  "name": "tracker",
+  "directories": [
+    { "kind": "plans", "word": "plan", "path": "docs/plans" },
+    { "kind": "reviews", "word": "review", "path": "docs/reviews" }
+  ],
+  "id": {
+    "pattern": "^[A-Za-z]{0,4}[- ]?[0-9]{1,4}$",
+    "headers": ["id", "#", "step", "item", "slice", "task"]
+  },
+  "columns": {
+    "state": ["state", "status", "done when"],
+    "depends": ["depends on", "depends", "dependency", "dependencies", "deps", "needs"],
+    "title": ["slice", "deliverable", "title", "summary", "description", "content"],
+    "evidence": ["sha / evidence", "sha/evidence", "evidence", "sha", "notes", "note"]
+  },
+  "states": [
+    { "id": "queued", "write": "Queued", "read": ["queued"] },
+    { "id": "in-progress", "write": "In progress", "read": ["in progress", "in-progress"] },
+    { "id": "complete", "write": "Complete", "read": ["complete", "completed", "done"], "satisfies": true },
+    { "id": "accepted", "write": "Accepted", "read": ["accepted"] }
+  ],
+  "ready": "queued",
+  "dependency": {
+    "empty": ["none", "null", "n/a", "n.a.", "na", "—", "-", "–"],
+    "separators": ",;",
+    "notes": true,
+    "group": "^waves?\\s+(.+)$"
+  },
+  "wave": {
+    "label": ["wave"],
+    "members": ["slices"]
+  },
+  "section": { "depth": 3 }
+}