simt-dev 0.2.1 → 0.3.0

package/src/projection/surfaces.mjs

@@ -41,7 +41,11 @@
 //      #19377), and the documented examples are not valid YAML. Every rule
 //      shipped here is always-on, so the key would buy nothing and cost a
 //      silent-failure surface. Absence of frontmatter is documented to load
-//      eagerly, which is exactly what is wanted.
+//      eagerly, which is exactly what is wanted. (S50 ruled on this: a rule
+//      that carries a scope is emitted ONLY for surfaces whose scoping key is
+//      documented and parsed correctly, and Claude is not one of them, which
+//      is why `canScope` below excludes it rather than trusting `documentedKeys`
+//      to carry the reason.)
 //
 //   4. `verified` IS THE POINT OF THE TABLE. A row whose `verified` is null was
 //      not checked against a vendor document, and the row says so where a reader
@@ -57,6 +61,22 @@
  *   - `file`    a wholly generated file; hand-written body text is retired
  *   - `pointer` a symlink to the primary target; carries no content of its own
  *
+ * `readsAgentsMd` is a vendor fact, in three values rather than two:
+ *   - `all`   every reader this row names loads AGENTS.md
+ *   - `some`  some of them do, and `readsAgentsMdNote` says which
+ *   - `none`  none does, so the row is the only channel its readers have
+ *
+ * It is not `readsPrimary`, which asks a different question: that one is about
+ * whether a per-rule file would duplicate text the region already carries, and it is
+ * only meaningful while folding is on. This one is about the FILE, and it is what
+ * decides whether a new harness needs a row at all - a harness that reads AGENTS.md
+ * is supported by the standard surface, whatever else it reads.
+ *
+ * `configDirs` are the directories whose presence implies the harness is in use.
+ * Detection reads them and claims nothing else: a directory a harness may create for
+ * other reasons is a presence, not a proof, and the command says "present", never
+ * "installed".
+ *
  * `ruleFrontmatter` returns the keys that editor reads BEFORE any rule text. A
  * surface that needs none returns '' and the projected file starts at the body.
  */
@@ -71,17 +91,19 @@ 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,
     foldRules: true,
+    readsAgentsMd: 'all',
+    configDirs: ['.opencode'],
     skills: '.agents/skills',
     documentedSkillsPaths: ['.opencode/skills', '.claude/skills', '.agents/skills'],
     // Codex concatenates AGENTS.md from the root down and stops at
@@ -96,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.',
   },
@@ -107,6 +129,8 @@ export const SURFACES = [
     primary: null,
     kind: 'file',
     rule: '.cursor/rules/{name}.mdc',
+    readsAgentsMd: 'all',
+    configDirs: ['.cursor'],
     // `documentedKeys` is the set the vendor's own docs name for this surface, and
     // `ruleFrontmatter` must emit nothing outside it. A key invented here would be
     // inert at best; on Antigravity an unrecognised value silently discards the
@@ -129,12 +153,17 @@ export const SURFACES = [
     // value. One body is written for all of them, so a Cursor name must not land
     // in a file Claude Code also reads.
     substitutions: { askTool: 'Use the interactive `AskQuestion` tool' },
-    ruleFrontmatter: (rule) =>
-      [
-        `description: ${rule.description ?? `Canonical ${rule.id} rule managed by simt-dev`}`,
-        `alwaysApply: ${rule.alwaysApply ? 'true' : 'false'}`,
-      ],
-    verified: 'Cursor project rules (.cursor/rules/*.mdc, description + alwaysApply + globs)',
+    ruleFrontmatter: (rule) => [
+      `description: ${rule.description ?? `Canonical ${rule.id} rule managed by simt-dev`}`,
+      // `globs` only appears when the rule declares a scope. Cursor attaches a rule
+      // with no globs on the strength of `alwaysApply` alone, so emitting either
+      // unquoted patterns on an eager rule or no globs at all on a scoped one is
+      // asking for the wrong loading behaviour.
+      ...(rule.scope ? [`globs: ${rule.scope.map((g) => `"${g}"`).join(', ')}`] : []),
+      `alwaysApply: ${rule.alwaysApply ? 'true' : 'false'}`,
+    ],
+    verified:
+      'Cursor project rules (.cursor/rules/*.mdc, description + alwaysApply + globs); alwaysApply: false with globs is "auto-attached when a matching file is in context", and the docs warn that alwaysApply: false with no description is manual @-mention only',
     note: 'The only surface that reads `.mdc`. Every other row here is a plain `.md` or a symlink.',
   },
   {
@@ -144,6 +173,16 @@ export const SURFACES = [
     primary: null,
     kind: 'file',
     rule: '.claude/rules/{name}.md',
+    // `some`, not `none`. It reads AGENTS.md - the same docs say CLAUDE.md is used only
+    // when no AGENTS.md exists - but only on that condition, so a repository that has a
+    // hand-written CLAUDE.md is read by neither. That is why this row still needs its
+    // own channel and a pointer: the fallback is not a channel, it is the absence of
+    // one, and a reader who relied on it would be relying on the reader deleting a
+    // file they wrote.
+    readsAgentsMd: 'some',
+    readsAgentsMdNote:
+      'CLAUDE.md is read first; AGENTS.md is read only when there is no CLAUDE.md, which is why the pointer exists',
+    configDirs: ['.claude'],
     // Intentionally no `paths:`. See decision 3 in the header.
     documentedKeys: ['paths', 'description'],
     ruleFrontmatter: () => [],
@@ -163,6 +202,8 @@ export const SURFACES = [
     primary: null,
     kind: 'file',
     rule: '.agents/rules/{name}.md',
+    readsAgentsMd: 'all',
+    configDirs: ['.agents'],
     // `trigger` is REQUIRED here and an unrecognised value discards the rule with no
     // message, which is why the value is mapped rather than passed through.
     documentedKeys: ['trigger', 'description', 'globs', 'glob'],
@@ -173,10 +214,15 @@ export const SURFACES = [
     // what makes them duplicates rather than a fallback.
     readsPrimary: true,
     ruleFrontmatter: (rule) => [
-      `trigger: ${rule.alwaysApply ? 'always_on' : 'model_decision'}`,
+      // `trigger: glob` carries the patterns, and they are quoted because YAML reads a
+      // value starting with `*` as an alias anchor — the Antigravity docs require it, and
+      // an invalid frontmatter block is discarded with no message at all.
+      `trigger: ${rule.scope ? 'glob' : rule.alwaysApply ? 'always_on' : 'model_decision'}`,
+      ...(rule.scope ? [`globs: ${rule.scope.map((g) => `"${g}"`).join(', ')}`] : []),
       `description: ${rule.description ?? `Canonical ${rule.id} rule managed by simt-dev`}`,
     ],
-    verified: 'Google Antigravity docs, "Rules" — .agents/rules/*.md, YAML frontmatter with trigger: always_on | model_decision | glob | manual; missing or invalid frontmatter silently discards the rule',
+    verified:
+      'Google Antigravity docs, "Rules" — .agents/rules/*.md, YAML frontmatter with trigger: always_on | model_decision | glob | manual; missing or invalid frontmatter silently discards the rule; trigger: glob takes comma-separated globs, which the docs require to be quoted so YAML does not read a leading * as an alias anchor; a 24 KB per-file limit and a 20,000-token budget for always_on rules, with automatic demotion to pointers past it',
     note:
       'This is why frontmatter is mandatory here and why the trigger value is not guessed: an unrecognised trigger means the rule is dropped with no message.',
   },
@@ -187,10 +233,18 @@ export const SURFACES = [
     primary: null,
     kind: 'file',
     rule: '.github/instructions/{name}.instructions.md',
+    // Copilot is why the column is three values and not two. Its CLI reads AGENTS.md
+    // and its editor and code review do not, so the row both needs its own channel and
+    // cannot be described as "reads AGENTS.md" without a reader reading that claim as
+    // "this repo is covered for Copilot", which for two of its three readers it is not.
+    readsAgentsMd: 'some',
+    readsAgentsMdNote:
+      'Copilot CLI reads AGENTS.md; the editor, code review and the cloud agent do not',
+    configDirs: ['.github'],
     documentedKeys: ['applyTo', 'excludeAgent'],
-    ruleFrontmatter: () => ['applyTo: "**"'],
+    ruleFrontmatter: (rule) => [`applyTo: ${rule.scope ? `"${rule.scope.join(',')}"` : '"**"'}`],
     verified:
-      'GitHub docs, "Adding repository custom instructions" — .github/instructions/NAME.instructions.md with applyTo globs; `applyTo: "**"` is the documented example',
+      'GitHub docs, "Adding repository custom instructions" — .github/instructions/NAME.instructions.md with applyTo globs; `applyTo: "**"` is the documented example, and a comma-separated pattern list is how more than one is named',
     // NOT marked readsPrimary, and this row is the reason the flag is per-surface
     // rather than global. The reader is split: Copilot CLI reads AGENTS.md, the
     // editor and code review do not. A per-rule file here is not duplication for two
@@ -232,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.',
   },
 ];
 
@@ -277,6 +335,27 @@ export function foldsRules(resolved) {
   return resolved.surfaces.some((s) => s.foldRules === true);
 }
 
+/**
+ * Whether this surface can load a rule only when a matching file is in play.
+ *
+ * Three do, and each for its own documented key: Cursor patterns with `globs` under
+ * `alwaysApply: false`, Copilot with `applyTo`, and Antigravity with `trigger: glob`
+ * plus `globs`. Claude Code does not — its `paths:` key has a documented parser
+ * defect in which quoted values and YAML sequences silently fail to lazy-load — and
+ * opencode cannot, because it has no per-rule file channel at all.
+ *
+ * The question is asked per surface rather than per key because the answer decides
+ * whether a scoped profile may leave the region: a profile written only as a scoped
+ * file would be absent from a reader that cannot scope it, and a rule nobody loads is
+ * worse than a rule that loads eagerly (ADR-071).
+ */
+export function canScope(surface) {
+  return surface.rule !== null && surface.rule !== undefined && SCOPE_KEYS.has(surface.id);
+}
+
+/** Surface ids whose scoping key was read in the vendor's own documentation. */
+const SCOPE_KEYS = new Set(['cursor', 'antigravity', 'copilot']);
+
 /**
  * Surfaces whose reader already loads the primary document, so a per-rule file for
  * them repeats text the region already carries.
@@ -295,6 +374,47 @@ export function readsPrimary(resolved) {
 
 export const SURFACE_IDS = SURFACES.map((s) => s.id);
 
+/**
+ * Config directories whose presence implies a harness is in use, for the ones this
+ * tool has no surface row for.
+ *
+ * Deliberately a list of DIRECTORY NAMES and nothing else. It carries no claim about
+ * what any of these readers loads: the review that proposed the command listed these
+ * harnesses as candidates and explicitly did not re-verify each vendor's current
+ * documentation, and a row built from that list would ship a `verified` field citing
+ * nothing — decoration that misdescribes the artefact, which is the failure this whole
+ * repository exists to prevent. A directory here means "a reader may be configured in
+ * this repository", never "this harness is installed" and never "its rules are not
+ * being loaded".
+ *
+ * `.github` is absent even though the Copilot row carries it: `.github` holds workflows
+ * and issues, so its presence says nothing about whether Copilot is used, and the
+ * Copilot row's own detection is not something this command is for.
+ */
+export const CANDIDATE_DIRS = [
+  { dir: '.gemini', harness: 'Gemini CLI' },
+  { dir: '.windsurf', harness: 'Windsurf' },
+  { dir: '.zed', harness: 'Zed' },
+  { dir: '.kiro', harness: 'Kiro' },
+  { dir: '.cline', harness: 'Cline' },
+  { dir: '.roo', harness: 'Roo Code' },
+  { dir: '.junie', harness: 'Junie' },
+  { dir: '.aider', harness: 'Aider' },
+  { 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',
+  },
+];
+
 /**
  * Frontmatter keys a surface emits that its own vendor does not document.
  *
@@ -313,10 +433,22 @@ export function undocumentedKeys(surfaceRows = SURFACES) {
   for (const s of surfaceRows) {
     if (!s.ruleFrontmatter) continue;
     const documented = Array.isArray(s.documentedKeys) ? s.documentedKeys : [];
-    for (const line of s.ruleFrontmatter({ id: 'probe', description: 'probe', alwaysApply: true })) {
-      const key = String(line).split(':')[0].trim();
-      if (!documented.includes(key)) {
-        bad.push(`${s.id} emits frontmatter key "${key}"; its vendor documents ${documented.join(', ') || '(nothing)'}`);
+    // Both shapes, because a scoping key is emitted only on the scoped shape: probing
+    // the eager one alone would pass a row that drops `globs` on a scoped rule, and the
+    // rule would then load on nothing.
+    const probes = [
+      { id: 'probe', description: 'probe', alwaysApply: true },
+      { id: 'probe', description: 'probe', alwaysApply: false, scope: ['src/**'] },
+    ];
+    for (const rule of probes) {
+      for (const line of s.ruleFrontmatter(rule)) {
+        const key = String(line).split(':')[0].trim();
+        // One report per key, not per probe: the same invented key appears on both
+        // shapes, and a gate that prints it twice reads as two defects.
+        if (documented.includes(key) || bad.some((b) => b.includes(`key "${key}"`))) continue;
+        bad.push(
+          `${s.id} emits frontmatter key "${key}"; its vendor documents ${documented.join(', ') || '(nothing)'}`,
+        );
       }
     }
   }

package/src/projection/targets.mjs

@@ -136,6 +136,43 @@ export async function ruleTargets(root, rule, body, sha, resolved, notes) {
   return { targets };
 }
 
+/**
+ * Per-rule files for the profiles that left the region, for the surfaces that can
+ * narrow them.
+ *
+ * A scoped profile is an ordinary rule with a `scope` on it, and that is the whole
+ * reason this is a thin wrapper over {@link ruleTargets} rather than a second
+ * construction: the byte-level concerns — frontmatter re-derived per surface, the
+ * region injected between the markers, the retired-prose note — are already decided
+ * there and must not be decided twice. A second implementation would drift from the
+ * first and the gate would report drift on a clean tree, which is the failure this
+ * module exists to prevent.
+ *
+ * The one thing it adds is the skip: a surface that folds the region carries the whole
+ * region already, so a scoped file is the duplication S12 removed — UNLESS the profile
+ * actually left the region, which is `narrowing`, the caller's answer, and which means
+ * the reader would otherwise get nothing.
+ */
+export async function scopedTargets(root, rules, sha, resolved, notes) {
+  const targets = [];
+  for (const rule of rules) {
+    // `alwaysApply: false` is what asks the surface to attach the file on the patterns
+    // rather than always. Cursor's documented reading of no description plus no globs is
+    // a manual @-mention, so a scoped rule carries its scope and the description it
+    // already had.
+    // `target` is what `ruleName` reads, and a stack profile has none: it is a plain
+    // `python.md`, not an `.mdc` in the rules directory. Without it the file is named
+    // `null.mdc`, which is exactly what the first version of this did.
+    const scoped = {
+      ...rule,
+      target: rule.target ?? `${rule.id}.mdc`,
+      alwaysApply: false,
+      scope: rule.scope,
+    };
+    targets.push(...(await ruleTargets(root, scoped, rule.body, sha, resolved, notes)).targets);
+  }
+  return { targets };
+}
 
 /**
  * Pointer targets: `CLAUDE.md` and `GEMINI.md` as symlinks to `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 }
+}