simt-dev 0.2.1 → 0.2.2

package/src/projection/rules.mjs

@@ -27,10 +27,13 @@ import { dirname, join, resolve } from 'node:path';
 
 import { fingerprint, KNOWN_TAGS } from '../resolve/fingerprint.mjs';
 import { loadMdcRules, renderMdc } from './mdc.mjs';
-import { foldsRules, frontmatterBlock, resolveSurfaces } from './surfaces.mjs';
+import { foldsRules, frontmatterBlock, resolveSurfaces, rulePath, canScope } from './surfaces.mjs';
 import { ruleTargets } from './targets.mjs';
-import { manifestPath } from './manifest.mjs';
+import { manifestPath, readManifest } from './manifest.mjs';
 import { BASELINES } from './baselines.mjs';
+import { CLI } from '../name.mjs';
+import { PACK_DIR, resolvePacks } from '../packs.mjs';
+import { discoverPackages } from '../monorepo.mjs';
 
 const HERE = dirname(fileURLToPath(import.meta.url));
 export const ROOT = resolve(HERE, '..', '..');
@@ -123,12 +126,37 @@ async function walk(dir, prefix = '') {
 /** Repo-local profile directory, relative to a repo root (ADR-013 section 2). */
 export const LOCAL_PROFILE_DIR = '.simt-dev/profiles';
 
+/**
+ * Which origin outranks which when two profiles claim one `simt-id`.
+ *
+ * A pack is the repository's shared policy and the built-in set is the tool's
+ * opinion, so a repository can replace either and a pack can replace what the
+ * tool ships. Read in one place because the answer to "whose rule is this?" is
+ * asked on every rule of every projection, and a precedence that lives in two
+ * places is a precedence that will disagree with itself.
+ */
+const ORIGIN_RANK = { central: 0, pack: 1, local: 2 };
+
 /** Every key a stack profile or core rule may declare is this tool's own, so every
  *  one carries the `simt-` prefix (ADR-022). A profile carrying a bare key would read
  *  as an editor's instruction — Cursor, Copilot and Antigravity all parse a
  *  frontmatter block the same way — and would be silently inert. */
 /** Frontmatter keys a rule profile declares. See {@link KNOWN_KEYS} on why exported. */
-export const PROFILE_KEYS = new Set(['simt-id', 'simt-title', 'simt-applies', 'simt-fallback']);
+export const PROFILE_KEYS = new Set(['simt-id', 'simt-title', 'simt-applies', 'simt-fallback', 'simt-scope', 'simt-priority']);
+
+/**
+ * Priority classes, packed in this order (plan 0003 R07).
+ *
+ * A class is not a severity, it is a promise about what a reader loses by not having
+ * the line. A hard constraint is one whose absence produces a defect; a command is one
+ * the reader cannot guess; a convention is right to follow and harmless to miss; a style
+ * is a preference. Anything after `command` is the first thing a kernel drops, and that
+ * ordering is the whole content of the mode — everything else about it is bookkeeping.
+ */
+export const PRIORITY_CLASSES = ['hard', 'command', 'convention', 'style'];
+
+/** The classes a kernel keeps. `full` mode keeps all four and is the default. */
+export const KERNEL_CLASSES = new Set(['hard', 'command']);
 
 /** Report the first thing wrong with a profile's frontmatter, in the order a reader
  *  fixes it: no id to select it by, then a key that will not be read, then a tag the
@@ -147,14 +175,33 @@ function describeDefect(meta) {
     const prefixed = `simt-${unknown.replace(/[A-Z]/g, (c) => `-${c.toLowerCase()}`)}`;
     return PROFILE_KEYS.has(prefixed)
       ? `key "${unknown}" is this tool's own, not the editor's; it is spelled "${prefixed}"`
-      : `unrecognised frontmatter key "${unknown}"; simt-dev's own keys are simt-id, simt-title, simt-applies, simt-fallback`;
+      : `unrecognised frontmatter key "${unknown}"; simt-dev's own keys are simt-id, simt-title, simt-applies, simt-fallback, simt-scope`;
   }
   const applies = meta['simt-applies'];
   if (!Array.isArray(applies)) return null;
   const undeclared = applies.find((tag) => !KNOWN_TAGS.has(tag));
-  return undeclared === undefined
-    ? null
-    : `simt-applies names "${undeclared}", which fingerprint() never emits, so this profile could never be selected`;
+  if (undeclared !== undefined) {
+    return `simt-applies names "${undeclared}", which fingerprint() never emits, so this profile could never be selected`;
+  }
+  const priority = meta['simt-priority'];
+  if (priority !== undefined && !PRIORITY_CLASSES.includes(priority)) {
+    return `simt-priority is "${priority}"; the classes are ${PRIORITY_CLASSES.join(', ')}, in the order a kernel packs them`;
+  }
+  const scope = meta['simt-scope'];
+  if (scope === undefined) return null;
+  // A scope that matches the whole repository is the eager profile wearing a costume:
+  // the reader is told the rule narrows, and the rule loads on every file. `**` and
+  // `**/*` are the two spellings of that, and both are the default a surface applies
+  // when it is given no pattern at all.
+  const CATCH_ALL = new Set(['**', '**/*', '*']);
+  if (scope.length === 0) {
+    return 'simt-scope is empty; a profile with no pattern would load as eagerly as one with no simt-scope at all';
+  }
+  const bad = scope.find((glob) => typeof glob !== 'string' || glob === '' || CATCH_ALL.has(glob));
+  if (bad !== undefined) {
+    return `simt-scope needs at least one pattern that narrows; "${bad}" matches every file, so the profile would load exactly as eagerly as one with no simt-scope`;
+  }
+  return null;
 }
 
 /**
@@ -371,21 +418,88 @@ export async function desiredRegion(root, flags) {
   const { stack, facts, manifest } = await fingerprint(root);
   const all = await loadRules(root);
   const { selected, fallback, notes } = select(all, stack, facts);
-
-  let body = render(selected);
-  let sources = selected.map((r) => r.source);
-  const folded = [];
-
-  // When every selected surface carries its rules inside the primary document, the
-  // per-rule bodies belong in the region too — otherwise a repo on the standard
-  // surface receives AGENTS.md and none of the always-on process rules, because
-  // those had nowhere else to live. One file, one region, one place a reader opens.
   const { resolved, bodies, problems, notes: ruleNotes } = await ruleBodies(
     root,
     manifest,
     flags ?? {},
   );
   notes.push(...ruleNotes);
+
+  // A profile that declares a scope leaves the region only when every selected surface
+  // can load it narrowly. The alternative is a profile written only as a scoped file for
+  // a reader whose surface cannot scope — a rule nobody loads, which is worse than one
+  // that loads eagerly (ADR-071). A surface that cannot scope it therefore keeps the
+  // profile in the region and says so, rather than letting the region quietly shrink.
+  const narrowing = resolved.surfaces.every((s) => canScope(s));
+  const scoped = [];
+  const inRegion = [];
+  for (const r of selected) {
+    const declares = Array.isArray(r.scope) && r.scope.length > 0 && r.error === null;
+    if (!declares) {
+      inRegion.push(r);
+      continue;
+    }
+    // A profile only leaves the region when a narrowed file can replace it. When any
+    // selected surface cannot narrow, the file would be the only home for a rule that
+    // reader cannot reach — so it stays, and says why.
+    if (narrowing) {
+      scoped.push(r);
+      continue;
+    }
+    inRegion.push(r);
+    notes.push(
+      `${r.id} declares simt-scope, but ${resolved.source} selects a surface that cannot narrow a rule, so it stays in the region`,
+    );
+  }
+
+// The kernel. In `kernel` mode only the hard and command classes are packed into the
+  // region and every other rule is deferred to `rules show <id>`, which is what makes
+  // R08's accept criterion reachable at all: a budget cannot be met by a projection that
+  // never tries. `full` is the default and stays it until R02 has measured that a
+  // kernel does not lose compliance, because nobody has measured it yet.
+  //
+  // A rule with no stated class is deferred, not packed. The two mistakes are not
+  // symmetric: packing a line that should have been deferred spends the budget the mode
+  // exists to save, while deferring a line that should have been packed costs a reader
+  // one `rules show`. The mode is a promise about bytes, so it is the bytes that win.
+  const mode = await projectionMode(root);
+  const packed = [];
+  const deferred = [];
+  for (const r of inRegion) {
+    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);
+  const folded = [];
+
+  // The pointer. A reader who opens AGENTS.md and does not find a profile they know is
+  // there will look for it, and the honest answer is where it moved: the file a scoping
+  // surface loads it from, and the files it now matches. Without the line the region's
+  // source list is quietly short one entry, which reads as a rule that was deleted.
+  if (scoped.length > 0 && narrowing) {
+    const lines = scoped.map(
+      (r) =>
+        `- ${sourceTitle(r, 'profile')} — loads only when a matching file is in play (${r.scope.join(', ')}): ${scopedPaths(r, resolved).join(', ')}`,
+    );
+    body += `\n\n## Scoped rules\n\n${lines.join('\n')}`;
+    for (const r of scoped) sources.push(r.source);
+  }
+
+  if (deferred.length > 0) {
+    // The pointer is the same shape as the scoped one above, and for the same reason:
+    // a reader who opens AGENTS.md and does not find a rule they know is there will
+    // look for it. What it costs to find it has to be one command, named per rule.
+    const lines = [...deferred]
+      .sort(byPriorityThenId)
+      .map(
+        (r) =>
+          `- ${sourceTitle(r, 'profile')} — ${r.priority ?? 'unclassified'}, deferred in kernel mode. Show it with: ${CLI} rules show ${r.id}`,
+      );
+    body += `\n\n## Deferred rules\n\n${lines.join('\n')}`;
+    for (const r of deferred) sources.push(r.source);
+  }
+
   if (foldsRules(resolved)) {
     for (const { rule, body: ruleBody } of bodies) {
       // `## Process:`, not `### id`. The body already uses `##`, and a third-level
@@ -407,6 +521,13 @@ export async function desiredRegion(root, flags) {
     all,
     profiles: selected.map((r) => r.id),
     folded,
+    mode,
+    deferred: deferred.map((r) => r.id),
+    // 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.
+    scoped,
+    narrowing,
     surfaces: resolved.ids,
     surfaceSource: resolved.source,
     problems,
@@ -417,6 +538,27 @@ export async function desiredRegion(root, flags) {
   };
 }
 
+/**
+ * Every per-rule file a scoped profile is written to, as paths a reader can open.
+ *
+ * Only the surfaces that can scope get one: a Cursor `.mdc` with `globs` and
+ * `alwaysApply: false`, an Antigravity file with `trigger: glob`, a Copilot
+ * `.instructions.md` with `applyTo`. A surface that reads the region already (opencode)
+ * has no file channel at all, and Claude's scoping key is the documented-defect one,
+ * so neither appears here.
+ */
+function scopedPaths(rule, resolved) {
+  const out = [];
+  for (const s of resolved.surfaces) {
+    if (!canScope(s) || !s.rule) continue;
+    // A folded surface already carries the whole region; it is the reason this profile
+    // is only a file when folding is off, which is the caller's question to answer.
+    if (s.foldRules === true && s.readsPrimary === true && foldsRules(resolved)) continue;
+    out.push(rulePath(s.id, rule.id));
+  }
+  return out;
+}
+
 /**
  * Read every rule file once, with its frontmatter parsed, plus any repo-local
  * profile under `.simt-dev/profiles/`.
@@ -444,7 +586,42 @@ export async function loadRules(root = null) {
     collected.push({ file, dir: RULES_DIR, origin: 'central', source: `rules/${file}` });
   }
 
+  // Packs go in before the repo's own profiles and after the built-ins, because
+  // that is the order they lose to. The collection order is the tie-break `select`
+  // reads for two profiles of equal rank, so "collected central, then pack, then
+  // local" is the precedence stated once rather than restated in the comparator.
   if (root !== null) {
+    const { packs } = await resolvePacks(root);
+    for (const pack of packs) {
+      // `present`, not `ok`. A pack whose bytes disagree with its pin still projects:
+      // dropping it would let the next `sync` delete the rules it carries, so the
+      // remedy the finding names would cause the damage it exists to report.
+      if (!pack.present) continue;
+      const packRules = join(pack.dir, 'rules');
+      let names = [];
+      try {
+        names = (await readdir(packRules)).filter((n) => n.endsWith('.md')).sort();
+      } catch {
+        names = [];
+      }
+      let stackNames = [];
+      try {
+        stackNames = (await readdir(join(packRules, 'stacks')))
+          .filter((n) => n.endsWith('.md'))
+          .map((n) => `stacks/${n}`);
+      } catch {
+        stackNames.length = 0;
+      }
+      for (const file of [...names, ...stackNames].sort()) {
+        collected.push({
+          file,
+          dir: packRules,
+          origin: 'pack',
+          source: `${PACK_DIR}/${pack.name}/rules/${file}`,
+        });
+      }
+    }
+
     const localDir = join(root, LOCAL_PROFILE_DIR);
     let localNames = [];
     try {
@@ -474,6 +651,8 @@ export async function loadRules(root = null) {
       title: meta['simt-title'] ?? null,
       applies: meta['simt-applies'] ?? [],
       fallback: meta['simt-fallback'] === true,
+      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),
@@ -482,6 +661,58 @@ export async function loadRules(root = null) {
   return out;
 }
 
+/**
+ * The regions a monorepo's packages each need, as bodies ready to be written.
+ *
+ * A repository with packages in it is projected twice over: the root carries the
+ * rules every package shares, and each package carries the profiles IT selects and
+ * the root does not. A reader working in `apps/web` opens two files by walking up,
+ * and gets the union; a reader who only reads the root still gets everything that
+ * is not package-specific. Nothing is repeated, so nothing goes stale twice
+ * (ADR-066).
+ *
+ * A package whose delta is empty gets no file. Writing an empty region into every
+ * directory of a large monorepo would be noise the reader has to learn to skip,
+ * and a file with nothing in it is not a projection, it is an absence with a
+ * generated header on it.
+ *
+ * The rule set is the ROOT's - local profiles and packs are the repository's, and
+ * a package that re-read them from its own directory would resolve a different
+ * set in a directory that has no manifest.
+ *
+ * @returns {Promise<{regions: {path: string, ecosystem: string, stack: string[],
+ *   facts: string[], profiles: string[], body: string, meta: {sha: string, sources: string[]}}[],
+ *   notes: string[]}>}
+ */
+export async function packageRegions(root, flags, rootProfiles = null) {
+  const shared = rootProfiles ?? (await desiredRegion(root, flags)).profiles;
+  const { packages, notes } = await discoverPackages(root);
+  if (packages.length === 0) return { regions: [], notes };
+
+  const rules = await loadRules(root);
+  const sha = await provenanceDigest();
+  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;
+    regions.push({
+      path: pkg.path,
+      ecosystem: pkg.ecosystem,
+      stack: fp.stack ?? [],
+      facts: fp.facts ?? [],
+      profiles: delta.map((r) => r.id),
+      // 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)}`,
+      meta: { sha, sources: delta.map((r) => r.source) },
+    });
+  }
+  return { regions, notes };
+}
+
 /**
  * Selection is pure set intersection: core always, then every profile whose
  * `simt-applies` intersects the repo's signals. `node` is the fallback, so it is only
@@ -492,7 +723,7 @@ export async function loadRules(root = null) {
  * fact is the more durable choice because it survives the framework being
  * replaced.
  *
- * `shadowed` lists local profiles that replaced a central one, so a caller can
+ * `shadowed` lists profiles that replaced one they outrank, so a caller can
  * report it rather than silently changing what a repo receives.
  */
 export function select(rules, stack, facts = []) {
@@ -506,9 +737,14 @@ export function select(rules, stack, facts = []) {
       ids.set(rule.id, rule);
       continue;
     }
-    // A local profile is allowed to replace a central one; two of the same
-    // origin are a defect the caller must be able to see.
-    const localWins = rule.origin === 'local' && prior.origin !== 'local';
+    // A profile may replace one it outranks; two of the same origin are a defect
+    // the caller must be able to see.
+    //
+    // Ranked rather than `=== 'local'` because there is now a third origin. The
+    // ordering it encodes - the repository's own profile, then a pack it declares,
+    // then what the tool ships - is the whole precedence rule, in one comparison
+    // that cannot drift from the order the files were collected in.
+    const localWins = ORIGIN_RANK[rule.origin] > ORIGIN_RANK[prior.origin];
     if (localWins) {
       ids.set(rule.id, rule);
       shadowed.push({
@@ -580,6 +816,32 @@ export function render(selected) {
     .join('\n\n');
 }
 
+/**
+ * The projection mode this repository declared, or `full`.
+ *
+ * Absent means `full`, and `full` is the default rather than a fallback: no measurement
+ * yet says a kernel does not lose compliance (plan 0003 R02), so the mode that changes
+ * what a reader gets cannot be the one nobody chose.
+ */
+async function projectionMode(root) {
+  const { manifest } = await readManifest(root);
+  return manifest?.mode === 'kernel' ? 'kernel' : 'full';
+}
+
+/**
+ * Deterministic kernel order: the class a rule declares, then its id.
+ *
+ * The tie-break is not decoration. Two rules of the same class packed in file order
+ * would move when a file is added to the directory, and a projection that reorders
+ * itself on an unrelated commit is a projection nobody can diff (ADR-013).
+ */
+function byPriorityThenId(a, b) {
+  const classA = PRIORITY_CLASSES.indexOf(a.priority ?? 'style');
+  const classB = PRIORITY_CLASSES.indexOf(b.priority ?? 'style');
+  if (classA !== classB) return classA - classB;
+  return String(a.id).localeCompare(String(b.id));
+}
+
 /**
  * One source, one `##` heading, then its body with every heading demoted.
  *
@@ -634,6 +896,12 @@ function parseFrontmatter(text) {
         .slice(1, raw.lastIndexOf(']'))
         .split(',')
         .map((s) => s.trim())
+        // A quoted item is a quoted item: the glob inside is the value, not the quotes
+        // around it. A profile author quoting `\"src/**/*.ts\"` because their editor
+        // colouring complains about a bare `*` would otherwise project a pattern the
+        // surface matches nothing against.
+        .map((s) => (s.length >= 2 && s.startsWith('"') && s.endsWith('"') ? s.slice(1, -1) : s))
+        .map((s) => (s.length >= 2 && s.startsWith("'") && s.endsWith("'") ? s.slice(1, -1) : s))
         .filter(Boolean);
     } else out[key] = raw.trim();
   }

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.
  */
@@ -82,6 +102,8 @@ export const SURFACES = [
     // 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
@@ -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
@@ -277,6 +331,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 +370,37 @@ 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' },
+];
+
 /**
  * Frontmatter keys a surface emits that its own vendor does not document.
  *
@@ -313,10 +419,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)'}`,
+        );
       }
     }
   }