@rungs/cli 0.1.2 → 0.2.0

package/src/explain.ts

@@ -0,0 +1,189 @@
+import { ENGINES, type Finding } from './engines.ts';
+import { loadTable, tableKey } from './check.ts';
+import type { DetectResult, Manifest } from './types.ts';
+
+/**
+ * `doctor` answers a *presence* question — which of our modules does this repo
+ * already have an equivalent of. The question a repo actually arrives with is a
+ * *defect* question: which of my agent rules say MUST and have nothing checking
+ * them, how many near-identical CI workflows do I have, which topics have two
+ * documents claiming authority.
+ *
+ * Those detectors were already written. They ship as gates inside modules and
+ * ran only after installation, over rungs-managed content — so the analysis was
+ * gated behind installing the thing the analysis exists to justify, which is
+ * backwards for a tool whose primary case is retrofit (WI-038).
+ *
+ * Nothing here is new detection. It is the same `ENGINES` table the runner
+ * uses, over a registry synthesized in memory from the module manifests rather
+ * than read from `.ai/gates.toml`, which an unmanaged repo does not have.
+ */
+
+export interface DetectorFinding {
+  module: string;
+  gate: string;
+  /** The extracted incident behind the gate, from the manifest. */
+  why?: string;
+  findings: Finding[];
+  examined: number;
+}
+
+export interface ExplainResult {
+  reported: DetectorFinding[];
+  /** Gates skipped, by reason — printed, because a silent skip reads as a pass. */
+  skipped: { command: number; unimplemented: string[]; undeclared: string[]; errored: { gate: string; message: string }[] };
+  /** Modules whose detectors ran at all. */
+  scope: string[];
+}
+
+type EngineTable = Record<string, (t: any, root: string, files: string[]) => { findings: Finding[]; examined: number }>;
+
+/**
+ * A `command` gate runs a shell command the *repo* owns. On a repo that never
+ * installed rungs there is no registry to own one, but a module can still
+ * declare one — and executing an arbitrary command against somebody else's
+ * checkout because they typed a read-only-sounding flag is not a thing this
+ * tool gets to do. Skipped, and counted, never run.
+ */
+const isRunnable = (g: Manifest['gates'][number]) => g.kind !== 'command' && !g.trigger && !!g.engine;
+
+/**
+ * Which modules' detectors are allowed to run.
+ *
+ * **Only what the repo already has.** ADR-0004 biased detection signatures
+ * toward false negatives; the same bias applies here for a stronger reason —
+ * these engines read rungs-shaped inputs, so on a foreign repo a
+ * technically-correct finding can still be framed against a convention the repo
+ * never adopted. A module the repo has no equivalent of has nothing to check,
+ * and running it anyway produces exactly the confident noise that loses an
+ * adoption wedge.
+ *
+ * `paradigm` is excluded too: the repo solves that problem a different way, and
+ * measuring their solution against our shape is the same error with a nastier
+ * tone.
+ */
+export const IN_SCOPE: ReadonlySet<string> = new Set(['theirs', 'ours-current', 'ours-diverged']);
+
+/**
+ * Which declared applicability may run against a repo that is not ours.
+ *
+ * This was two hard-coded sets of **engine names** in this file, and the
+ * knowledge lived nowhere near the gates it governed: adding a gate on
+ * `file-population` silently made it foreign-safe, and adding one on a new
+ * engine silently made it not, with nothing at either declaration saying so.
+ * It is now a required field on each gate — see `Applicability` in `types.ts`
+ * for what the three cases mean and which measurement produced them.
+ */
+const FOREIGN_SAFE: ReadonlySet<string> = new Set(['repo-content']);
+
+export function explain(
+  mods: Manifest[],
+  results: DetectResult[],
+  repoRoot: string,
+  files: string[],
+): ExplainResult {
+  return explainWith(ENGINES, mods, results, repoRoot, files);
+}
+
+/**
+ * `explain` with the engine table injected, so the scope rules above can be
+ * tested without a repo on disk. Those rules are the whole safety argument of
+ * this pass; testing them through fifteen real manifests would test the
+ * manifests instead.
+ */
+export function explainWith(
+  engines: EngineTable,
+  mods: Manifest[],
+  results: DetectResult[],
+  repoRoot: string,
+  files: string[],
+): ExplainResult {
+  const inScope = results.filter((r) => IN_SCOPE.has(r.state));
+  const scope = inScope.map((r) => r.module);
+  const stateOf = new Map(inScope.map((r) => [r.module, r.state]));
+  const reported: DetectorFinding[] = [];
+  const skipped: ExplainResult['skipped'] = { command: 0, unimplemented: [], undeclared: [], errored: [] };
+
+  for (const name of scope) {
+    const mod = mods.find((m) => m.name === name);
+    if (!mod) continue;
+    const isOurs = stateOf.get(name) !== 'theirs';
+
+    for (const g of mod.gates) {
+      if (!isRunnable(g)) {
+        if (g.kind === 'command') skipped.command++;
+        continue;
+      }
+      // No default. A gate that has not said whether it can read a foreign repo
+      // does not read one, and is named — silence resolving to "safe" is how the
+      // 71 mis-framed findings of WI-038's first version happened.
+      if (!isOurs) {
+        if (!g.applicability) {
+          skipped.undeclared.push(g.id);
+          continue;
+        }
+        if (!FOREIGN_SAFE.has(g.applicability)) continue;
+      }
+      if (!(g.engine! in engines)) {
+        // Same rule as the runner: an engine named and missing is an unknown,
+        // and an unknown is never reported as clean.
+        skipped.unimplemented.push(g.id);
+        continue;
+      }
+
+      const table = loadTable(g.table ? `${mod.name}/${g.table.replace(/^gates\//, '')}` : undefined, repoRoot);
+      if (!table) {
+        skipped.errored.push({ gate: g.id, message: `table '${g.table ?? '(none)'}' not found` });
+        continue;
+      }
+
+      try {
+        const key = tableKey(g.engine!);
+        let section = table[key] ?? table;
+        if (Array.isArray(section) && section.some((s: any) => s?.id)) {
+          const mine = section.filter((s: any) => !s.id || g.id.includes(s.id));
+          if (mine.length) section = mine;
+        }
+        const r = engines[g.engine!](section, repoRoot, files);
+        if (r.findings.length) {
+          reported.push({ module: mod.name, gate: g.id, why: g.why, findings: r.findings, examined: r.examined });
+        }
+      } catch (e: any) {
+        // An engine that throws on a foreign repo's shapes is a fact about this
+        // pass, not about the repo. Reported as ours, not as their finding.
+        skipped.errored.push({ gate: g.id, message: e.message });
+      }
+    }
+  }
+
+  return { reported: collapseDuplicates(reported), skipped, scope };
+}
+
+/**
+ * Two gate ids that produce the identical finding set are one check reported
+ * twice, and on a repo with 112 broken links that is 224 lines of the same
+ * thing. `gates-links-resolve` and `gates-paths-exist` currently run the same
+ * markdown-link scan — F-007 in `docs/backlog/FINDINGS.md`, open before this
+ * pass existed and unchanged by it.
+ *
+ * Collapsed here rather than fixed there on purpose: the duplication is a defect
+ * in the gate set, this is a defect in *reading* the gate set, and a reporting
+ * layer that hides a registry problem is how the registry problem survives. The
+ * merged row names both ids, so the duplication stays visible to anyone who
+ * looks at the output — which is the point.
+ */
+export function collapseDuplicates(reported: DetectorFinding[]): DetectorFinding[] {
+  const out: DetectorFinding[] = [];
+  const seen = new Map<string, DetectorFinding>();
+  for (const r of reported) {
+    const key = `${r.module} ${r.findings.map((f) => `${f.file ?? ''}|${f.message}`).join('')}`;
+    const prior = seen.get(key);
+    if (prior) {
+      prior.gate = `${prior.gate} + ${r.gate}`;
+      continue;
+    }
+    seen.set(key, r);
+    out.push(r);
+  }
+  return out;
+}

package/src/lifecycle.ts

@@ -4,7 +4,7 @@ import { fileURLToPath } from 'node:url';
 import { execSync } from 'node:child_process';
 import { parse } from 'smol-toml';
 import type { Manifest } from './types.ts';
-import { contentHash, emittedFiles } from './add.ts';
+import { contentHash, emittedFiles, registerGates } from './add.ts';
 import { resolveParams, substitute, type Params } from './substitute.ts';
 import { loadRegistry } from './check.ts';
 
@@ -89,18 +89,105 @@ export function applyUpgrade(repoRoot: string, mods: Manifest[], record: Install
   const params = resolveParams(mods, paramsFrom(record), repoRoot);
   const skillsDir = record.harnesses.includes('claude') ? '.claude/skills' : '.agents/skills';
   let written = 0;
+  // Only files this run rewrote. A diverged file is not in here, which is what
+  // keeps its recorded hash — and therefore its protection — intact (F-017).
+  const rewritten = new Map<string, Map<string, string>>();
   for (const item of plan) {
     const mod = mods.find((m) => m.name === item.module)!;
     const emitted = emittedFiles(mod, params, skillsDir);
     for (const f of item.files) {
       if (f.state !== 'stale' && f.state !== 'missing') continue;
       const full = join(repoRoot, f.rel);
+      const content = emitted.get(f.rel)!;
       mkdirSync(dirname(full), { recursive: true });
-      writeFileSync(full, emitted.get(f.rel)!);
+      writeFileSync(full, content);
+      if (!rewritten.has(mod.name)) rewritten.set(mod.name, new Map());
+      rewritten.get(mod.name)!.set(f.rel, contentHash(content));
       written++;
     }
   }
-  return written;
+
+  // F-016. Upgrading rewrote a module's **files** and never its **gates**, so a
+  // module version that added, removed or renamed one left the registry on the
+  // old block and told the user the upgrade succeeded. Reproduced 2026-08-16
+  // against a scratch consumer: `session` 1.1.0 → 1.2.0 with a new gate, and
+  // `.ai/gates.toml` kept `rungs:begin session@1.1.0` and 20 entries.
+  //
+  // Registration is by whole merge block, so this fixes removal too — a gate
+  // dropped from a manifest leaves the registry with the block that replaces it.
+  // Idempotent, and cheap enough to run for every module in the plan rather than
+  // only the ones whose files happened to be stale.
+  const upgraded = plan.map((p) => mods.find((m) => m.name === p.module)!).filter(Boolean);
+  const gateActions = upgraded.length ? registerGates(upgraded, repoRoot, false) : [];
+
+  const recorded = updateRecordAfterUpgrade(
+    repoRoot,
+    upgraded.map((m) => ({ module: m.name, version: m.version, hashes: rewritten.get(m.name) ?? new Map() })),
+  );
+
+  return { written, gates: gateActions.length, recorded };
+}
+
+/**
+ * Update `.ai/rungs.toml` in place after an upgrade: the version each module
+ * moved to, and a new hash for each file this run actually rewrote.
+ *
+ * **Surgical, and text-level, on purpose.** F-017: `upgrade` left the record
+ * naming the old version, so a repo on 1.2.0 described itself to its owner as
+ * 1.1.0 and `planUpgrade` offered the same move forever. The obvious fix —
+ * calling `writeInstallRecord` — is worse than the bug: it re-derives the whole
+ * record and hashes **every emitted file that exists**, which would stamp our
+ * hash onto a file the user had diverged. That file would then match its record
+ * and be silently reclassified from `diverged` to `current`, so the next upgrade
+ * would overwrite the edit rungs promises never to touch.
+ *
+ * So: only the lines that must change, and only for files we wrote. Everything
+ * else — the header comment, kept-file lists, and the hash of every file we did
+ * not touch — is left exactly as it was.
+ */
+export function updateRecordAfterUpgrade(
+  repoRoot: string,
+  updates: { module: string; version: string; hashes: Map<string, string> }[],
+): number {
+  const path = join(repoRoot, '.ai', 'rungs.toml');
+  if (!existsSync(path) || !updates.length) return 0;
+
+  const lines = readFileSync(path, 'utf8').split('\n');
+  const byModule = new Map(updates.map((u) => [u.module, u]));
+  let changed = 0;
+  let current: { module: string; hashes: boolean } | null = null;
+
+  const out: string[] = [];
+  for (const line of lines) {
+    const header = /^\[modules\.([^\].]+)(\.[^\]]+)?\]/.exec(line);
+    if (header) {
+      current = byModule.has(header[1]) ? { module: header[1], hashes: header[2] === '.hashes' } : null;
+      out.push(line);
+      continue;
+    }
+
+    if (current && !current.hashes && /^version\s*=/.test(line)) {
+      const next = `version = "${byModule.get(current.module)!.version}"`;
+      if (next !== line) changed++;
+      out.push(next);
+      continue;
+    }
+
+    if (current?.hashes) {
+      const entry = /^"([^"]+)"\s*=/.exec(line);
+      const replacement = entry && byModule.get(current.module)!.hashes.get(entry[1]);
+      if (replacement) {
+        out.push(`"${entry[1]}" = "${replacement}"`);
+        changed++;
+        continue;
+      }
+    }
+
+    out.push(line);
+  }
+
+  writeFileSync(path, out.join('\n'));
+  return changed;
 }
 
 function paramsFrom(record: InstallRecord): Params {

package/src/manifest.ts

@@ -21,6 +21,7 @@ export function loadManifest(dir: string): Manifest {
     params: (raw.params ?? {}) as Record<string, ParamSpec>,
     gates: raw.gates ?? [],
     detect: raw.detect ?? {},
+    skills: raw.skills ?? {},
     provenance: raw.provenance,
     threshold: raw.threshold,
     dir,
@@ -61,7 +62,7 @@ export function usedParams(dir: string): Set<string> {
 
 export interface ManifestIssue {
   module: string;
-  kind: 'dead-param' | 'undeclared-param' | 'dep-missing' | 'gate-no-table' | 'gate-no-why';
+  kind: 'dead-param' | 'undeclared-param' | 'dep-missing' | 'gate-no-table' | 'gate-no-why' | 'gate-no-applicability';
   detail: string;
 }
 
@@ -102,6 +103,17 @@ export function auditModules(mods: Manifest[]): ManifestIssue[] {
       if (!g.why?.trim()) {
         issues.push({ module: mod.name, kind: 'gate-no-why', detail: `gate '${g.id}' has no 'why'` });
       }
+      // WI-052. `doctor --explain` will not run an undeclared gate against a repo
+      // that is not ours, so an author who forgets this silently loses their gate
+      // on exactly the repos the analysis exists for. Caught here, where the
+      // module is written, rather than as a skip line nobody reads.
+      if (g.kind === 'declared' && !g.applicability) {
+        issues.push({
+          module: mod.name,
+          kind: 'gate-no-applicability',
+          detail: `gate '${g.id}' does not declare applicability (repo-content | our-artifacts | our-schema)`,
+        });
+      }
     }
   }
   return issues;

package/src/selftest.ts

@@ -0,0 +1,221 @@
+import { mkdirSync, mkdtempSync, rmSync, writeFileSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { dirname, join } from 'node:path';
+import { ENGINES, type Finding } from './engines.ts';
+
+/**
+ * Execute a gate's `[[self_test]]` fixtures instead of only checking they exist.
+ *
+ * F-006 / WI-045. `gateMeta` confirmed that a `pass` block and a `fail` block
+ * were declared and never ran either, so every fixture in the repo was
+ * documentation shaped like a test. `gates-links-resolve`'s
+ * `See [the plan](./does-not-exist.md).` had never been executed — and had it
+ * been, it would have caught F-005 months before a person found it by hand.
+ *
+ * That is `gate-self-test`'s own argument turned on itself: *a gate whose rules
+ * are all currently satisfied is indistinguishable from a gate that matches
+ * nothing*, and a self-test that never runs is indistinguishable from one that
+ * would fail.
+ *
+ * **What this does not do is as important as what it does.** A fixture whose
+ * shape has no builder is reported **unrun, by name**. It is never counted as a
+ * pass, because a suite that reports green while three quarters of it never
+ * executed is this finding again, one level up.
+ */
+
+export interface SelfTestResult {
+  gate: string;
+  expect: 'pass' | 'fail';
+  outcome: 'ok' | 'mismatch' | 'unrun';
+  detail?: string;
+}
+
+/**
+ * A concrete path the table's `scan` would match, for writing a fixture into.
+ *
+ * The table may be an **array** — `[[frontmatter_schema]]` declares several — in
+ * which case `t.file`/`t.scan` are undefined and the first "scan pattern" was
+ * an entire schema object. That silently produced a nonsense path, the engine
+ * saw no file, and the fixture was reported as a gate failure (F-018).
+ */
+function targetPath(table: any): string {
+  const t = Array.isArray(table) ? table[0] ?? {} : table ?? {};
+  const pattern: string = t.file ?? [t.scan ?? []].flat()[0] ?? '**/*.md';
+  if (!pattern.includes('*')) return pattern;
+  return pattern
+    .replace(/\*\*\//g, 'probe/')
+    .replace(/\/\*\*/g, '/probe')
+    .replace(/\*/g, 'probe')
+    .replace(/probe\.probe$/, 'probe.md');
+}
+
+/**
+ * Build the fixture's repo state, or return null when its shape has no builder.
+ *
+ * The declarative keys are deliberately handled generically — `frontmatter`,
+ * `sections`, `opening` and `body` are all "a markdown file with this in it",
+ * and writing one builder per key would be the same per-shape sprawl that left
+ * 85 of 114 fixtures unrunnable in the first place.
+ */
+function build(root: string, table: any, fx: any, input?: string): string[] | null {
+  const write = (rel: string, body: string) => {
+    const full = join(root, rel);
+    mkdirSync(dirname(full), { recursive: true });
+    writeFileSync(full, body);
+    return rel;
+  };
+
+  if (typeof input === 'string') return [write(targetPath(table), `${input}\n`)];
+  if (!fx || typeof fx !== 'object') return null;
+
+  // Named files in a parameterised directory, plus the version they are judged
+  // against — the changelog shapes. `dir` is stated by the fixture rather than
+  // assumed here, because the self-test sees the module's *raw* table and a
+  // `{{changelog_dir}}` glob cannot match anything on disk; see `deparam`.
+  if (Array.isArray(fx.fragments) && typeof fx.version === 'string') {
+    const dir = fx.dir ?? 'changelog.d';
+    // Forward slashes, not `join`: the returned paths are matched against the
+    // spec's globs, and on Windows `join` yields `changelog.d\0.1.1.md`, which
+    // `changelog.d/*.md` does not match. The gate then reports "did not fire"
+    // about the harness rather than the fixture.
+    const written = fx.fragments.map((n: string) => write(`${dir}/${n}`, `# ${n}\n`));
+    written.push(write('package.json', JSON.stringify({ version: fx.version })));
+    return written;
+  }
+
+  // N files matching the table's scan — the population shapes.
+  if (typeof fx.matching_files === 'number') {
+    const base = fx.location ?? dirname(targetPath(table));
+    const marker = fx.exempt ? `<!-- ${fx.exempt} -->\n` : '';
+    return Array.from({ length: fx.matching_files }, (_, i) =>
+      write(join(base === '.' ? '' : base, `probe-${i}.md`), `${marker}# probe ${i}\n`),
+    );
+  }
+
+  // A single markdown file described declaratively.
+  const contentKeys = ['frontmatter', 'sections', 'opening', 'body', 'row', 'table'];
+  if (contentKeys.some((k) => k in fx)) {
+    const parts: string[] = [];
+    // `table = "Closed"` names the heading the row belongs under. A register
+    // engine finds rows by section, so a row written without its heading is in
+    // no table at all — which read as "the gate did not fire" (F-018).
+    if (fx.table) parts.push(`## ${fx.table}`, '');
+    if (fx.frontmatter && typeof fx.frontmatter === 'object') {
+      parts.push('---');
+      for (const [k, v] of Object.entries(fx.frontmatter)) parts.push(`${k}: ${v}`);
+      parts.push('---', '');
+    }
+    if (fx.opening) parts.push(String(fx.opening), '');
+    for (const s of fx.sections ?? []) parts.push(`## ${s}`, '', 'text', '');
+    if (fx.row && typeof fx.row === 'object') {
+      const cols = Object.keys(fx.row);
+      parts.push(`| ${cols.join(' | ')} |`, `| ${cols.map(() => '---').join(' | ')} |`,
+        `| ${cols.map((c) => (fx.row as any)[c]).join(' | ')} |`, '');
+    }
+    if (fx.body) parts.push(String(fx.body), '');
+    return [write(fx.file ?? targetPath(table), `${parts.join('\n')}\n`)];
+  }
+
+  return null;
+}
+
+/**
+ * Engines whose verdict depends **only on the content of the file the fixture
+ * describes**, so a fixture can be executed faithfully in an empty directory.
+ *
+ * The rest need context the fixture does not carry, and running them anyway
+ * produces confident nonsense. `gates-links-resolve`'s `pass` fixture is
+ * `See [this table](./structural.toml).` — it asserts that a link *which
+ * resolves* passes, and in a temp directory it does not resolve, so the runner
+ * would report the gate broken. Creating the target to make it pass would be
+ * assuming the answer, and only for `expect = "pass"` blocks, which is worse.
+ *
+ * Measured 2026-08-16: without this restriction the runner reported 17
+ * "failures", and the ones inspected were all its own artifacts. A test harness
+ * that cries wolf gets deleted faster than the gate it was checking.
+ *
+ * This is the same shape as `applicability` in ADR-0007, one level down: ask
+ * whether the check can legitimately run before running it.
+ */
+const CONTEXT_FREE: ReadonlySet<string> = new Set([
+  'frontmatter-schema',
+  'sections',
+  'file-budget',
+  'register-schema',
+  'file-population',
+  'changelog-freshness',
+]);
+
+/**
+ * Replace `{{param}}` segments in a spec's globs with the literal the fixture
+ * stands in for.
+ *
+ * The runner reads the **module's** gate table, where paths are still written as
+ * parameters — `{{changelog_dir}}/*.md`. Nothing substitutes them here, because
+ * there is no installed repo to take values from. So a fixture that exercises a
+ * parameterised path has to say what it is standing in for, and the spec has to
+ * be told the same thing, or the glob matches a file the builder just wrote and
+ * the gate reports "did not fire" about its own harness.
+ */
+function deparam<T>(spec: T, dir: string): T {
+  const walk = (v: any): any =>
+    typeof v === 'string' ? v.replace(/\{\{[^}]+\}\}/g, dir)
+      : Array.isArray(v) ? v.map(walk)
+      : v && typeof v === 'object' ? Object.fromEntries(Object.entries(v).map(([k, x]) => [k, walk(x)]))
+      : v;
+  return walk(spec);
+}
+
+export function runSelfTests(
+  gateId: string,
+  engine: string,
+  table: any,
+  blocks: { expect: string; input?: string; fixture?: any }[],
+): SelfTestResult[] {
+  const out: SelfTestResult[] = [];
+  for (const b of blocks) {
+    const expect = b.expect === 'fail' ? 'fail' : 'pass';
+    if (!CONTEXT_FREE.has(engine)) {
+      out.push({ gate: gateId, expect, outcome: 'unrun', detail: `${engine} fixtures need context the fixture does not carry` });
+      continue;
+    }
+    if (!(engine in ENGINES)) {
+      out.push({ gate: gateId, expect, outcome: 'unrun', detail: `engine '${engine}' not implemented` });
+      continue;
+    }
+    const root = mkdtempSync(join(tmpdir(), 'rungs-selftest-'));
+    try {
+      const files = build(root, table, b.fixture, b.input);
+      // A fixture states an opt-in with `opted_in`; the engine reads it from the
+      // spec as `extensions_opted_in`. Without the bridge, the `pass` fixture for
+      // an opted-in extension fired `non-spec key` — the harness asserting the
+      // opposite of what the fixture said (F-018).
+      let spec = b.fixture?.opted_in
+        ? (Array.isArray(table) ? table.map((s: any) => ({ ...s, extensions_opted_in: b.fixture.opted_in })) : { ...table, extensions_opted_in: b.fixture.opted_in })
+        : table;
+      // Same bridge, for paths: a fixture that names a parameterised directory
+      // has to hand the spec the same literal it wrote the files into.
+      if (Array.isArray(b.fixture?.fragments)) spec = deparam(spec, b.fixture.dir ?? 'changelog.d');
+      if (!files) {
+        out.push({ gate: gateId, expect, outcome: 'unrun', detail: `no builder for fixture ${JSON.stringify(b.fixture).slice(0, 60)}` });
+        continue;
+      }
+      let findings: Finding[];
+      try {
+        findings = ENGINES[engine](spec, root, files).findings;
+      } catch (e: any) {
+        out.push({ gate: gateId, expect, outcome: 'unrun', detail: `engine threw: ${e.message}`.slice(0, 90) });
+        continue;
+      }
+      const fired = findings.length > 0;
+      out.push(
+        fired === (expect === 'fail')
+          ? { gate: gateId, expect, outcome: 'ok' }
+          : { gate: gateId, expect, outcome: 'mismatch', detail: `expected ${expect}, ${fired ? `fired: ${findings[0].message}`.slice(0, 80) : 'did not fire'}` },
+      );
+    } finally {
+      rmSync(root, { recursive: true, force: true });
+    }
+  }
+  return out;
+}

package/src/types.ts

@@ -15,10 +15,35 @@ export interface ParamSpec {
   consumed_by?: string;
 }
 
+/**
+ * Whether a detector can legitimately interpret a repo that did not adopt our
+ * conventions — asked *before* "did the condition fire" (WI-052).
+ *
+ * This lived as two hard-coded sets of engine names inside `explain.ts`, which
+ * meant a new gate inherited an applicability nobody chose for it and could not
+ * see. The three cases are the ones measurement produced, not a taxonomy:
+ *
+ * - `repo-content`  measures the repo's own content. A broken link is a broken
+ *   link in anybody's methodology, and so is a 1,358-line file.
+ * - `our-artifacts` checks something rungs wrote. On a repo that never installed
+ *   it the artifact cannot exist, so the finding is guaranteed by the repo's
+ *   *state* rather than its *content* — `adr-index-current` reporting a missing
+ *   `adr-index` block against hexguard's perfectly healthy decision index.
+ * - `our-schema`    reads their file against a shape we defined.
+ *   `specs-status-evidence` produced 70 findings on hexguard-templates whose
+ *   spec register is fine and simply has its own columns.
+ *
+ * Only `repo-content` runs on a repo that is not ours. There is deliberately no
+ * default: an undeclared gate is reported, never quietly assumed safe — the same
+ * rule `enforcement-declaration` applies to `gated` / `review-only`.
+ */
+export type Applicability = 'repo-content' | 'our-artifacts' | 'our-schema';
+
 export interface GateSpec {
   id: string;
   kind: 'declared' | 'command';
   engine?: string;
+  applicability?: Applicability;
   table?: string;
   command?: string;
   tier?: string;
@@ -79,6 +104,15 @@ export interface Manifest {
   params: Record<string, ParamSpec>;
   gates: GateSpec[];
   detect: DetectSpec;
+  /**
+   * Per skill, the harness extensions this module opted into — `[skills.<name>]`
+   * in `module.toml`.
+   *
+   * Was declared in manifests and documented in `modules/README.md` while being
+   * parsed by nothing (F-019), so the opt-in that is meant to attach a
+   * portability cost to a decision attached to nothing at all.
+   */
+  skills?: Record<string, { extensions?: Record<string, unknown>; extension_note?: string }>;
   provenance: Provenance;
   threshold?: { metric: string; minimum: number; confirm?: boolean };
   /** Absolute path to the module directory. */