simt-dev 0.6.2 → 0.7.0

package/src/projection/manifest.mjs

@@ -18,11 +18,15 @@
 import { readFile, rename, writeFile } from 'node:fs/promises';
 import { existsSync } from 'node:fs';
 import { basename, join, resolve } from 'node:path';
+import { journaledWriteFile } from '../journal.mjs';
 // gates.mjs imports nothing, so this direction cannot cycle. It is the gate table
 // this file already selects from; duplicating the runnability rules here would be two
 // answers to "can this repo run that gate", which is precisely the kind of drift this
 // file exists to prevent elsewhere.
 import { getGate } from '../hooks/gates.mjs';
+// Q31: the one Node runner table. This module and the card, capability,
+// dispatcher and CI workflow all spell `<manager> run <script>` from it.
+import { runScript } from '../ecosystem/node-runner.mjs';
 
 // Imported as well as re-exported: a bare `export { X as Y } from` binds nothing here,
 // and the manifest name is used a dozen times below in remedy strings that name this
@@ -200,7 +204,7 @@ export const ECOSYSTEMS = [
  * fail closed — the defect is declaring a gate this repo has no way to run.
  *
  * The check mirrors what the dispatcher actually attempts:
- *   - `script` gates  run `npm run <script>`, so the script must exist
+ *   - `script` gates  run `<manager> run <script>`, so the script must exist
  *   - `staged` gates  look for each named tool in `node_modules/.bin`, so it must be
  *     installed, not merely declared as a dependency
  *   - `command` gates run whatever the manifest's `gates.commands` declares, so a
@@ -225,18 +229,27 @@ export function gateRunnable(gate, capability = {}) {
       : { runnable: true, why: `runs: ${declared}` };
   }
 
+  if (gate.kind === 'builtin') {
+    // The one kind with no external requirement: the implementation ships inside
+    // the binary that is reading this manifest (ADR-100). Saying otherwise would
+    // make `check` report a gate as unrunnable that runs on every commit.
+    return { runnable: true, why: 'runs inside the tool itself; nothing to install' };
+  }
   if (gate.kind === 'command') {
     return { runnable: false, why: `no command is declared for it in gates.commands` };
   }
   if (gate.kind === 'script') {
     const script = gate.script ?? gate.name;
-    if (capability.scripts?.[script]) return { runnable: true, why: `runs: npm run ${script}` };
+    // Q31: the runnable sentence names the repo's own runner, never a bare npm
+    // assumption — the card, the dispatcher and this check read one resolver.
+    const spell = runScript(capability.runner ?? 'npm', script);
+    if (capability.scripts?.[script]) return { runnable: true, why: `runs: ${spell}` };
     // Saying "no script in package.json" about a repo with no package.json states a
     // fact about a file that does not exist and implies a fix that cannot be taken.
     return {
       runnable: false,
       why: foreign
-        ? `this repo runs ${runnerName(capability.runner)}, not npm, so "npm run ${script}" cannot run here`
+        ? `this repo runs ${runnerName(capability.runner)}, not npm, so "${spell}" cannot run here`
         : `no "${script}" script in package.json`,
     };
   }
@@ -270,11 +283,17 @@ function gateRemedy(gate, { existing = false, runner = null } = {}) {
   const name = gate?.name ?? 'the gate';
   const npmShaped = gate?.kind === 'staged' || gate?.kind === 'script';
   const foreign = isForeignRunner(runner);
+  // Q31: a missing tool in a Node repo names the repo's own installer —
+  // `pnpm add -D`, not `npm i -D` — and anything elsewhere keeps the honest
+  // undo: name the program under `gates.commands`.
+  const addDev = { npm: 'npm i -D', pnpm: 'pnpm add -D', yarn: 'yarn add -D', bun: 'bun add -d' }[runner] ?? null;
   const fix =
     npmShaped && foreign
       ? `this repo runs ${runnerName(runner)}, not npm; name the program under "gates.commands" in ${MANIFEST_FILE} instead of the npm equivalent`
       : gate?.kind === 'staged'
-        ? `install ${gate.tools.join(', ')} as a dev dependency`
+        ? addDev
+          ? `install ${gate.tools.join(', ')} as a dev dependency: ${addDev} ${gate.tools.join(' ')}   (the gate runs from the pinned dependency)`
+          : `install ${gate.tools.join(', ')} as a dev dependency`
         : gate?.kind === 'script'
           ? `add a "${gate.script ?? name}" script to package.json`
           : gate?.kind === 'command'
@@ -295,11 +314,14 @@ function gateRemedy(gate, { existing = false, runner = null } = {}) {
 /**
  * Is this runner one where `npm run` is not how a gate is spelled?
  *
- * `undefined` means "the caller did not report a runner", and `npm` means the npm
- * remedy applies. Only a positively identified other ecosystem changes the wording.
+ * `undefined` means "the caller did not report a runner", and every Node manager
+ * (`npm`, `pnpm`, `yarn`, `bun`) spells gates as `<manager> run <script>` with
+ * scripts living in the same `package.json`. Only a positively identified
+ * non-Node runner changes the wording. (Q31: pnpm is Node-shaped, not foreign.)
  */
 function isForeignRunner(runner) {
-  return runner != null && runner !== 'npm';
+  if (runner == null) return false;
+  return !['npm', 'pnpm', 'yarn', 'bun'].includes(runner);
 }
 
 /** How a reader would name the runner in a sentence. */
@@ -309,6 +331,9 @@ function runnerName(runner) {
       none: 'no recognised runner',
       gradle: 'Gradle',
       python: 'Python',
+      npm: 'npm',
+      pnpm: 'pnpm',
+      yarn: 'yarn',
       bun: 'bun',
       cargo: 'Cargo',
       go: 'Go',
@@ -376,14 +401,15 @@ export function planGates(stack = [], capability = null, facts = []) {
  */
 function ecosystemCommands(facts = [], capability = null) {
   if (!capability?.tools?.length) return {};
-  // An npm runner already answers "how do I test and format" with its own package.json
-  // scripts, and a seed only wins over those scripts when the repo has not declared a
-  // command of its own — which is exactly the mixed repos (package.json AND Cargo.toml)
-  // where the script is the deliberate answer. Seeding there would replace a choice with
-  // a default; the reader's escape hatch is declaring gates.commands by hand, which a
-  // seed would lose to anyway. Pure ecosystem repos have runner 'cargo'/'go'/... and
-  // seed normally.
-  if (capability.runner === 'npm') return {};
+  // A Node runner (npm/pnpm/yarn/bun) already answers "how do I test and format"
+  // with its own package.json scripts, and a seed only wins over those scripts when
+  // the repo has not declared a command of its own — which is exactly the mixed
+  // repos (package.json AND Cargo.toml) where the script is the deliberate answer.
+  // Seeding there would replace a choice with a default; the reader's escape hatch
+  // is declaring gates.commands by hand, which a seed would lose to anyway. Pure
+  // ecosystem repos have runner 'cargo'/'go'/... and seed normally.
+  // Q31: every Node manager skips seeding — pnpm is not "foreign", it is Node.
+  if (['npm', 'pnpm', 'yarn', 'bun'].includes(capability.runner)) return {};
   const present = new Set(facts);
   const commands = {};
   for (const eco of ECOSYSTEMS) {
@@ -721,6 +747,23 @@ export function declaredShared(manifest) {
 
 export const GENERATED_KEYS = new Set(['$comment', 'projection']);
 
+// The sub-keys of `projection` this tool writes. `projection` is a generated key, but
+// not wholesale: the repository owns sub-keys this writer does not emit (`place` is the
+// one that shipped), and a repair that replaces the object deletes them (review 0003 Q26).
+const PROJECTION_KEYS = new Set(['simtDevSha', 'version']);
+
+/** The `projection` object a manifest carries; anything that is not an object is nothing. */
+function projectionOf(value) {
+  return value !== null && typeof value === 'object' && !Array.isArray(value) ? value : {};
+}
+
+/** Only the generated sub-keys of a `projection` object, in the order this writer emits them. */
+function generatedProjection(value) {
+  const out = {};
+  for (const key of PROJECTION_KEYS) if (key in projectionOf(value)) out[key] = value[key];
+  return out;
+}
+
 /**
  * A manifest with this tool's own fields replaced by what this build writes, and
  * nothing else touched.
@@ -731,13 +774,22 @@ export const GENERATED_KEYS = new Set(['$comment', 'projection']);
  * repo chose is never compared" is a promise about the repair too, not only about
  * the report, and a repair is exactly where it would be broken.
  *
+ * `projection` merges the same way, one level down: the object the repository has
+ * keeps every sub-key it chose, and the generated sub-keys take this build's values.
+ *
  * @param {object} manifest the repository's manifest, as parsed
  * @param {object} expected `buildManifest`'s output, from the call `manifestDrift` made
  * @returns {object} a new manifest; the argument is not mutated
  */
 export function withGenerated(manifest, expected) {
   const patched = { ...manifest };
-  for (const key of GENERATED_KEYS) if (key in expected) patched[key] = expected[key];
+  for (const key of GENERATED_KEYS) {
+    if (!(key in expected)) continue;
+    patched[key] =
+      key === 'projection'
+        ? { ...projectionOf(manifest?.projection), ...expected.projection }
+        : expected[key];
+  }
   return patched;
 }
 
@@ -780,9 +832,14 @@ export async function manifestDrift(root, stack, sha) {
   // `[...GENERATED_KEYS]`, and not `Object.keys(expected)`: the question is which
   // fields are ours, and the answer is the set above. Iterating the expected object
   // asks the same question of a different list and can only agree by coincidence.
-  const stale = [...GENERATED_KEYS].filter(
-    (key) => key in expected && JSON.stringify(manifest[key]) !== JSON.stringify(expected[key]),
-  );
+  const stale = [...GENERATED_KEYS].filter((key) => {
+    if (!(key in expected)) return false;
+    // `projection` compares on the sub-keys this tool writes: a sub-key the repo
+    // chose (`place`) is not a stale field, and reporting it is what made `sync`
+    // delete the one setting that was not stale (review 0003 Q26).
+    const actual = key === 'projection' ? generatedProjection(manifest[key]) : manifest[key];
+    return JSON.stringify(actual) !== JSON.stringify(expected[key]);
+  });
   if (stale.length > 0) {
     return {
       file: MANIFEST,
@@ -851,13 +908,17 @@ export async function readManifest(root) {
   }
 }
 
-export async function writeManifest(root, manifest) {
+export async function writeManifest(root, manifest, journal = null) {
   // A repository still holding the old name gets it moved, not shadowed. Two manifests
   // in one repo is a manifest nobody can reason about, and the second would be the one
   // that is never read - so the window closes by moving the file, not by leaving both.
   const previous = join(root, MANIFEST_LEGACY);
   const fresh = join(root, MANIFEST);
   if (existsSync(previous) && !existsSync(fresh)) await rename(previous, fresh);
-  await writeFile(fresh, manifestText(manifest));
+  // A journaled manifest is one `undo` can restore, like every other repo file a
+  // command writes (R49). Callers that span repos or the repo boundary (shared,
+  // bench) pass nothing and keep the old behaviour exactly.
+  if (journal) await journaledWriteFile(root, journal, fresh, manifestText(manifest));
+  else await writeFile(fresh, manifestText(manifest));
   return fresh;
 }

package/src/projection/markers.mjs

@@ -165,6 +165,43 @@ export function parse(text, style) {
   };
 }
 
+/**
+ * The line spans of every generated region in `text`, across both marker styles.
+ *
+ * `parse` is the single reader: a malformed region is still a region (an edit
+ * anywhere in the file stays denied), so malformed counts as a span covering the
+ * whole file rather than as absent. Line numbers are 1-based and inclusive.
+ *
+ * @returns {{malformed: boolean, spans: Array<{start: number, end: number}>}}
+ */
+export function regionSpans(text) {
+  const spans = [];
+  let malformed = false;
+  for (const style of ['html', 'hash']) {
+    const state = parse(text, style);
+    if (state.status === 'malformed') {
+      malformed = true;
+      continue;
+    }
+    if (state.status !== 'ok') continue;
+    const start = state.before === '' ? 1 : state.before.split('\n').length + 1;
+    const bodyLines = state.body === '' ? 0 : state.body.split('\n').length;
+    spans.push({ start, end: start + bodyLines + 1 });
+  }
+  if (malformed) {
+    const total = text.split('\n').length;
+    return { malformed: true, spans: [{ start: 1, end: total }] };
+  }
+  return { malformed: false, spans };
+}
+
+/** Line range of `text.slice(index, index + length)`, 1-based and inclusive. */
+export function lineRangeOf(text, index, length) {
+  const start = text.slice(0, index).split('\n').length;
+  const end = text.slice(0, index + length).split('\n').length;
+  return { start, end };
+}
+
 function malformed(lines, from, at, reason) {
   return {
     status: 'malformed',
@@ -359,9 +396,12 @@ export function inject(text, body, meta, opts = {}) {
   // too. A body that matches with a seam that does not is red on `format:check`, and
   // reporting `unchanged` there means `check` finds no drift and `sync` never repairs
   // it - the repository stays red with no remedy the tool offers. Top placement is
-  // excluded because there the splice is a repair that legitimately moves bytes
-  // outside the markers, so the two files differ for a reason unrelated to the seam.
-  const settled = unchanged && (where === 'top' || spliced === text);
+  // excluded from the seam test because there the splice is a repair that
+  // legitimately moves bytes outside the markers, so the two files differ for a
+  // reason unrelated to the seam. Position is the test there instead: a region below
+  // the file's own settings has been moved, and the move is what `where: 'top'`
+  // exists to repair (review 0003 Q26).
+  const settled = unchanged && (where === 'top' ? state.before.trim() === '' : spliced === text);
   if (settled) return { ...seen, text, action: 'unchanged' };
 
   return { ...seen, text: spliced, action: 'updated' };

package/src/projection/mdc.mjs

@@ -28,6 +28,7 @@ import { dirname, join, resolve } from 'node:path';
 import { fileURLToPath } from 'node:url';
 
 import { parse } from './markers.mjs';
+import { MANIFEST_FILE } from '../name.mjs';
 
 // ROOT is computed here rather than imported: project.mjs is the caller of every
 // function below, so importing it back would create a cycle for the sake of one
@@ -148,9 +149,18 @@ function parseSubstitutions(text) {
     const scope = next ? tail.slice(0, next.index + 1) : tail;
     const def = /^\s*default:\s*(.*)$/m.exec(scope);
     const desc = /^\s*describe:\s*(.*)$/m.exec(scope);
+    // A per-signal default: `default-<signal>:` picks the value when the repository
+    // carries that signal (a stack tag or a detection fact). `default:` is the
+    // fallback. The two cannot collide: `default:` requires the colon immediately
+    // after the word, and a signal line has a `-` there.
+    const perSignal = {};
+    for (const pm of scope.matchAll(/^\s*default-([a-z0-9][a-z0-9-]*):\s*(.*)$/gm)) {
+      perSignal[pm[1]] = unquote(pm[2].trim());
+    }
     out.push({
       key: hit[1],
       default: def ? unquote(def[1].trim()) : '',
+      perSignal,
       describe: desc ? unquote(desc[1].trim()) : '',
     });
   }
@@ -197,6 +207,19 @@ function stripFrontmatter(text) {
     .trim();
 }
 
+/**
+ * The default a signal set selects: the first per-signal default whose signal is
+ * present, else the plain default. Signals carry detection facts as well as stack
+ * tags, because a Go repository is selected on a fact, not a stack (review 0003 Q32).
+ */
+function pickDefault(sub, signals) {
+  const perSignal = sub.perSignal ?? {};
+  for (const s of signals) {
+    if (Object.prototype.hasOwnProperty.call(perSignal, s)) return perSignal[s];
+  }
+  return sub.default;
+}
+
 /**
  * Substitute declared placeholders.
  *
@@ -209,9 +232,11 @@ function stripFrontmatter(text) {
  * rendered rule would ship a literal `{{key}}`, which reads as a finished rule
  * and is not one.
  */
-export function renderMdc(rule, declared = {}) {
+export function renderMdc(rule, declared = {}, signals = []) {
   const problems = [];
-  let body = rule.body;
+  // The rule text names the manifest with a token and the render substitutes it,
+  // so a rename of the file is a change in one place (MANIFEST_FILE).
+  let body = rule.body.replaceAll('{manifest}', MANIFEST_FILE);
 
   for (const sub of rule.substitutions) {
     const has = Object.prototype.hasOwnProperty.call(declared, sub.key);
@@ -226,17 +251,19 @@ export function renderMdc(rule, declared = {}) {
     }
 
     if (provided === undefined || provided === null || provided === '') {
-      // Fall back to the default. An empty DEFAULT is also a drop instruction,
-      // which is how the same file serves a repo that has nothing to add.
-      if (sub.default === '') {
+      // Fall back to the default the signals select. An empty chosen default is
+      // also a drop instruction, which is how the same file serves a repo that
+      // has nothing to add.
+      const chosen = pickDefault(sub, signals);
+      if (chosen === '') {
         body = dropOrReplace(body, sub.key, '');
         continue;
       }
-      if (sub.default === undefined) {
+      if (chosen === undefined) {
         problems.push(`substitution ${sub.key} has no default and none declared`);
         continue;
       }
-      body = dropOrReplace(body, sub.key, sub.default);
+      body = dropOrReplace(body, sub.key, chosen);
       continue;
     }
 

package/src/projection/project.mjs

@@ -16,7 +16,8 @@
 // same matcher, so supporting an ecosystem nobody here has heard of requires no
 // code change and no release.
 
-import { readFile, readdir } from 'node:fs/promises';
+import { constants as fsConstants } from 'node:fs';
+import { access, readFile, readdir, stat } from 'node:fs/promises';
 import { join } from 'node:path';
 
 import { baselineTargets, misplaced } from './baselines.mjs';
@@ -31,8 +32,75 @@ import { measureRoot } from '../measure/context.mjs';
 import { loadMdcRules, renderMdc } from './mdc.mjs';
 import { foldsRules, resolveSurfaces, SURFACES, SURFACE_IDS } from './surfaces.mjs';
 import { pointerState, pointerTargets, ruleTargets, scopedTargets } from './targets.mjs';
-import { CLI } from '../name.mjs';
-import { MANIFEST_FILE } from '../name.mjs';
+import { CLI, LOCK_FILE, LOCK_LEGACY, PACKAGE_NAME } from '../name.mjs';
+import { MANIFEST_FILE, WORKFLOW_FILE_NAME } from '../name.mjs';
+import { resolveNodeRunner } from '../ecosystem/node-runner.mjs';
+import { LOCAL_BIN } from '../distribute/release.mjs';
+
+/**
+ * A checked-in gate workflow the locator cannot resolve (review 0003 Q31).
+ *
+ * Returns a finding, or null when some resolution path can still succeed. Only
+ * committed evidence counts: the pinned devDependency, the release binary, and
+ * `simt` on this machine's PATH (a global install CI may share — its presence
+ * here is a reason to stay silent, its absence is not proof CI lacks it, so the
+ * finding also requires the first two to be missing).
+ */
+async function workflowResolvable(root) {
+  let pkg = null;
+  try {
+    pkg = JSON.parse(await readFile(join(root, 'package.json'), 'utf8'));
+  } catch {
+    pkg = null;
+  }
+  if (pkg !== null) {
+    const deps = { ...(pkg.dependencies ?? {}), ...(pkg.devDependencies ?? {}) };
+    if (Object.hasOwn(deps, PACKAGE_NAME)) return null;
+  }
+  try {
+    await stat(join(root, LOCAL_BIN));
+    return null;
+  } catch {
+    // No release binary: keep checking the last path.
+  }
+  for (const dir of (process.env.PATH ?? '').split(':').filter(Boolean)) {
+    try {
+      await access(join(dir, 'simt'), fsConstants.X_OK);
+      return null;
+    } catch {
+      // Not here; keep looking.
+    }
+  }
+  const file = `.github/workflows/${WORKFLOW_FILE_NAME}`;
+  if (pkg !== null) {
+    const lockfiles = [];
+    for (const name of ['pnpm-lock.yaml', 'yarn.lock', 'bun.lock', 'bun.lockb', 'package-lock.json']) {
+      try {
+        await stat(join(root, name));
+        lockfiles.push(name);
+      } catch {
+        // Absent is the normal case.
+      }
+    }
+    const runner = resolveNodeRunner({
+      lockfiles,
+      packageManager: typeof pkg.packageManager === 'string' ? pkg.packageManager : null,
+    });
+    return {
+      file,
+      status: 'unresolvable',
+      detail: `the checked-in gate workflow looks for ${PACKAGE_NAME} in node_modules, but nothing it tries can succeed: no pinned devDependency, no ${LOCAL_BIN}, no simt on PATH`,
+      remedy: `run: ${runner.addDev} ${PACKAGE_NAME}   (the gate runs from the pinned dependency)`,
+    };
+  }
+  return {
+    file,
+    status: 'unresolvable',
+    detail: `the checked-in gate workflow cannot resolve ${PACKAGE_NAME}: no package.json to pin it in, no ${LOCAL_BIN}, no simt on PATH`,
+    remedy: `install the pinned gate binary into the repository, then re-run: simt init --yes`,
+  };
+}
+import { computeLock } from './lock.mjs';
 import {
   desiredRegion,
   provenanceDigest,
@@ -53,6 +121,16 @@ import {
  *  most agents, including ones that ignore .cursor/ entirely. */
 export const PRIMARY_TARGET = 'AGENTS.md';
 
+/** The gate's verdict on a region `sync` has already written. `current` rows carry
+ *  `detail: null`, not `undefined`: a key whose value is `undefined` survives into the
+ *  structured MCP surface but is dropped by `JSON.stringify`, so the two surfaces of one
+ *  answer no longer deep-equal. */
+function regionVerdict(action) {
+  return action === 'unchanged'
+    ? { status: 'current', detail: null }
+    : { status: 'drift', detail: `region is ${action}; run: ${CLI} sync --yes` };
+}
+
 
 /**
  * @param {string} root repo root
@@ -62,7 +140,7 @@ export const PRIMARY_TARGET = 'AGENTS.md';
 export async function plan(root, flags = {}) {
   const desired = await desiredRegion(root, flags);
   const { stack, facts, profiles, fallback, notes, body, meta, all, manifest } = desired;
-  const target = await targetFor(root, body, meta);
+  const target = await targetFor(root, root, body, meta);
 
   // Per-rule content projects to every editor the repo selected, not only Cursor. The
   // body is identical on each; only the frontmatter the editor reads before any rule
@@ -94,9 +172,39 @@ export async function plan(root, flags = {}) {
   // root's would read as though the packages were the repository.
   const packages = await packageRegions(root, flags, profiles);
   const nested = await Promise.all(
-    packages.regions.map((r) => targetFor(join(root, r.path), r.body, r.meta, `${r.path}/${PRIMARY_TARGET}`)),
+    packages.regions.map((r) => targetFor(root, join(root, r.path), r.body, r.meta, `${r.path}/${PRIMARY_TARGET}`)),
   );
 
+  // The lock records the two digests a frozen check compares (ADR-086). It is a target
+  // like every other: `plan` produces it, so preview, `--diff`, the journal, the idle
+  // test and `init` all inherit it. Computing it here rather than in `sync` is what makes
+  // a deleted lock show up in the plan as a write instead of vanishing from it — the
+  // `sync` that printed "wrote simt-dev.lock.json" and then "nothing written" (Q29).
+  const lock = await computeLock(root, flags);
+  const lockText = `${JSON.stringify(lock, null, 2)}\n`;
+  let previousLockText = '';
+  let lockExists = false;
+  for (const name of [LOCK_FILE, LOCK_LEGACY]) {
+    try {
+      previousLockText = await readFile(join(root, name), 'utf8');
+      lockExists = true;
+      break;
+    } catch (error) {
+      if (error.code !== 'ENOENT') throw error;
+    }
+  }
+  const lockTarget = {
+    file: LOCK_FILE,
+    path: join(root, LOCK_FILE),
+    kind: 'lock',
+    surface: null,
+    exists: lockExists,
+    action: !lockExists ? 'create' : previousLockText === lockText ? 'unchanged' : 'update',
+    bytes: Buffer.byteLength(lockText),
+    previousBytes: Buffer.byteLength(previousLockText),
+    text: lockText,
+  };
+
   return {
     root,
     stack,
@@ -107,15 +215,25 @@ export async function plan(root, flags = {}) {
     surfaceSource: surfaces.source,
     surfaceProblems: surfaces.problems,
     rules: all,
-    targets: [target, ...nested, ...mdc.targets, ...scoped.targets, ...baselines.targets],
+    targets: [target, ...nested, ...mdc.targets, ...scoped.targets, ...baselines.targets, lockTarget],
     packages: packages.regions.map((r) => ({ path: r.path, profiles: r.profiles })),
     mdcProblems: mdc.problems,
+    crossRefs: desired.crossRefs,
     notes: [...notes, ...mdc.notes, ...packages.notes],
   };
 }
 
-async function targetFor(root, body, meta, label = PRIMARY_TARGET) {
-  const path = join(root, PRIMARY_TARGET);
+/**
+ * Build the write target for one AGENTS.md. `root` is the repository: `regionOpts`
+ * reads its manifest, because placement is a repository-level decision that holds for
+ * every package's region too. `dir` is where the file lives, which differs from
+ * `root` only for a nested monorepo package (review 0003 Q26).
+ *
+ * @param {string} root repo root
+ * @param {string} dir directory the target file lives in
+ */
+async function targetFor(root, dir, body, meta, label = PRIMARY_TARGET) {
+  const path = join(dir, PRIMARY_TARGET);
   let existing = '';
   let exists = true;
   try {
@@ -186,8 +304,24 @@ export async function checkTargets(root, flags = {}) {
   // Two `.github` files, one ownership rule, so one loop over both. The gate and the
   // dependency-updates config fail for the same reason and are fixed the same way,
   // and listing them separately is how the second copy of this rule gets written.
+  const workflowPlan = await planWorkflow(root);
+  // Q31: a workflow that exists but cannot resolve simt-dev by any path the
+  // locator tries is a green tick on a gate that never runs. The locator tries
+  // `$SIMT_DEV_BIN`, the pinned devDependency, the release binary and `simt`
+  // on PATH, in that order; only the middle two are committed evidence this
+  // check can see. When the repo pins nothing and carries no binary, the check
+  // can still see `simt` on its own PATH — a global install CI may share — so
+  // it stays silent then rather than crying wolf about a resolution it cannot
+  // disprove. The remedy names the repo's own manager, never a bare npm guess.
+  // simt-dev's own copy is exempt: it runs this checkout directly and never asks the
+  // locator to find a binary, so a machine without `simt` on PATH is not evidence that
+  // the gate cannot start. The consumer copy is not exempt, because its locator does.
+  if (!workflowPlan.own && workflowPlan.action !== 'create' && workflowPlan.action !== 'skip') {
+    const unresolvable = await workflowResolvable(root);
+    if (unresolvable) findings.push(unresolvable);
+  }
   for (const [plan, what] of [
-    [await planWorkflow(root), 'nothing gates it'],
+    [workflowPlan, 'nothing gates it'],
     [await planDependabot(root), 'nothing watches its dependencies'],
   ]) {
     if (plan.action === 'create') {
@@ -258,7 +392,20 @@ export async function checkTargets(root, flags = {}) {
   for (const p of resolved.problems) {
     findings.push({ file: `${MANIFEST_FILE}`, status: 'invalid', detail: p, remedy: `known surfaces: ${SURFACE_IDS.join(', ')}` });
   }
-  const rules = all.filter((r) => isEligible(r, new Set([...stack, ...facts]), declared.optIn));
+  const signals = new Set([...stack, ...facts]);
+  const rules = all.filter((r) => isEligible(r, signals, declared.optIn));
+
+  // A dangling cross-reference is a rule-text defect: the region renders, but it points
+  // the reader at a profile they cannot reach. A gate failure, like any other rule defect.
+  for (const p of desired.crossRefs ?? []) {
+    const idx = p.indexOf(': ');
+    findings.push({
+      file: p.slice(0, idx),
+      status: 'invalid',
+      detail: p.slice(idx + 2),
+      remedy: `co-select the profile, or name it with ${CLI} rules show <id>`,
+    });
+  }
 
   const sha = await provenanceDigest();
   const notes = [];
@@ -286,8 +433,7 @@ export async function checkTargets(root, flags = {}) {
       findings.push({
         file: target.file,
         surface: target.surface,
-        status: action === 'unchanged' ? 'current' : 'drift',
-        detail: action === 'unchanged' ? undefined : `region is ${action}; run: ${CLI} sync --yes`,
+        ...regionVerdict(action),
         recordedSha: parse(target.previous).sha ?? null,
       });
     }
@@ -308,6 +454,7 @@ export async function checkTargets(root, flags = {}) {
     const { body, problems } = renderMdc(
       rule,
       ruleValues(rule, declared.values[rule.id] ?? {}, resolved.surfaces),
+      signals,
     );
     if (problems.length > 0) {
       findings.push({
@@ -359,8 +506,7 @@ export async function checkTargets(root, flags = {}) {
       findings.push({
         file: rel,
         surface: target.surface,
-        status: action === 'unchanged' ? 'current' : 'drift',
-        detail: action === 'unchanged' ? undefined : `region is ${action}; run: ${CLI} sync --yes`,
+        ...regionVerdict(action),
         recordedSha: state.sha ?? null,
       });
     }
@@ -395,8 +541,7 @@ export async function checkTargets(root, flags = {}) {
     }
     findings.push({
       file: t.file,
-      status: t.action === 'unchanged' ? 'current' : 'drift',
-      detail: t.action === 'unchanged' ? undefined : `region is ${t.action}; run: ${CLI} sync --yes`,
+      ...regionVerdict(t.action),
       recordedSha: state.sha ?? null,
     });
     const off = misplaced(state, t.style);
@@ -566,8 +711,7 @@ async function checkRegion(root, dir, body, meta) {
   const d = diff(existing, body, meta, await regionOpts(root));
   return {
     file: PRIMARY_TARGET,
-    status: d.action === 'unchanged' ? 'current' : 'drift',
-    detail: d.action === 'unchanged' ? undefined : `region is ${d.action}; run: ${CLI} sync --yes`,
+    ...regionVerdict(d.action),
     recordedSha: state.sha ?? null,
     expectedSha: meta.sha,
   };