unspaghettit 0.3.0 → 0.4.0

package/cli/commands/ci.ts

@@ -0,0 +1,71 @@
+import { existsSync, mkdirSync, writeFileSync } from 'node:fs';
+import { dirname, isAbsolute, join, resolve } from 'node:path';
+import pc from 'picocolors';
+import { log } from '../util/log';
+
+export type CiOptions = {
+  readonly cwd?: string;
+  /** Output path. Defaults to .github/workflows/unspaghettit.yml. */
+  readonly out?: string;
+  /** Run bounded model checking in the generated workflow (slower, deeper). */
+  readonly modelCheck?: boolean;
+  readonly dryRun?: boolean;
+  readonly force?: boolean;
+};
+
+const workflowYaml = (modelCheck: boolean): string => {
+  const checkCmd = modelCheck ? 'unspa check --model-check' : 'unspa check';
+  return `# Generated by \`unspa ci\`. Verifies the Unspaghettit spec on every push / PR:
+# scenarios as executable tests, maturity, surface reachability, spec→code drift,
+# cross-feature event coherence${modelCheck ? ', and bounded model checking (invariant + liveness counterexamples)' : ''}.
+# Requires the behavior model to travel with the repo — run \`unspa init --local\`
+# so \`unspa/\` is committed. Tighten the gate with flags, e.g.
+# \`unspa check --min-maturity 80 --fail-on-drift\`.
+name: unspaghettit
+on:
+  push:
+    branches: [main]
+  pull_request:
+jobs:
+  verify:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-node@v4
+        with:
+          node-version: '20'
+      - run: npm install -g unspaghettit
+      - run: ${checkCmd}
+`;
+};
+
+export const runCiCommand = async (options: CiOptions = {}): Promise<number> => {
+  const cwd = options.cwd ?? process.cwd();
+  const yaml = workflowYaml(options.modelCheck === true);
+
+  if (options.dryRun) {
+    process.stdout.write(`${yaml}`);
+    return 0;
+  }
+
+  const outPath = options.out
+    ? isAbsolute(options.out)
+      ? options.out
+      : resolve(cwd, options.out)
+    : resolve(cwd, join('.github', 'workflows', 'unspaghettit.yml'));
+
+  if (existsSync(outPath) && options.force !== true) {
+    log.err(`Refusing to overwrite existing file: ${outPath}`);
+    log.dim('Re-run with --force to overwrite, or pass --out <path> to write elsewhere.');
+    return 1;
+  }
+
+  const outDir = dirname(outPath);
+  if (!existsSync(outDir)) mkdirSync(outDir, { recursive: true });
+  writeFileSync(outPath, yaml, 'utf8');
+
+  log.ok(`Wrote ${pc.cyan(outPath)}`);
+  log.dim('Commit it (and the unspa/ folder) so CI verifies the spec on every push / PR.');
+  log.dim('The model must travel with the repo: `unspa init --local` if you haven\'t already.');
+  return 0;
+};

package/cli/commands/coverage-ingest.ts

@@ -0,0 +1,112 @@
+import { existsSync, readFileSync } from 'node:fs';
+import pc from 'picocolors';
+import { parseScenarioResults, summarizeByAction } from '../scenarios/results';
+import { linkPath } from '../util/link';
+import { readJson, writeJson } from '../util/json';
+import { log } from '../util/log';
+
+export type CoverageIngestOptions = {
+  readonly file: string;
+  readonly cwd?: string;
+  /** ISO timestamp to stamp (injected for tests; defaults to now). */
+  readonly now?: string;
+  readonly dryRun?: boolean;
+};
+
+type IndexEntry = Record<string, unknown>;
+type Link = { index?: Record<string, IndexEntry> } & Record<string, unknown>;
+
+/**
+ * Promote indexed actions from "claimed implemented" to "proven against the
+ * spec" by reading a Vitest JSON report of the generated scenario spec
+ * (`vitest run --reporter=json --outputFile=<file>`). An action whose every
+ * scenario passed gets `verifiedAt` stamped on its `.unspa.json` entry; one
+ * that now fails has a stale `verifiedAt` cleared. Recording only — the gate
+ * is `unspa check --min-verified`.
+ */
+export const runCoverageIngestCommand = async (
+  options: CoverageIngestOptions
+): Promise<number> => {
+  const cwd = options.cwd ?? process.cwd();
+
+  if (!existsSync(options.file)) {
+    log.err(`Results file not found: ${options.file}`);
+    log.dim('Run: vitest run <spec> --reporter=json --outputFile=<file>, then ingest that file.');
+    return 1;
+  }
+
+  let report: unknown;
+  try {
+    report = JSON.parse(readFileSync(options.file, 'utf8'));
+  } catch (e) {
+    log.err(`Could not parse ${options.file} as JSON: ${(e as Error).message}`);
+    return 1;
+  }
+
+  const perAction = summarizeByAction(parseScenarioResults(report));
+  if (perAction.length === 0) {
+    log.warn('No unspa-tagged scenario tests found in the report.');
+    log.dim('Generate the spec with `unspa scenarios export <featureId>`, then run vitest with --reporter=json.');
+    return 0;
+  }
+
+  const path = linkPath(cwd);
+  const link = readJson<Link>(path);
+  if (!link) {
+    log.err(`No .unspa.json found at ${cwd}.`);
+    log.dim('Link the repo (`unspa link`) and record implementations before ingesting verification.');
+    return 1;
+  }
+  const index = link.index ?? {};
+  const stampedAt = options.now ?? new Date().toISOString();
+
+  let stamped = 0;
+  let cleared = 0;
+  const unindexed: string[] = [];
+
+  for (const action of perAction) {
+    const key = `action:${action.actionId}`;
+    const entry = index[key];
+    if (action.verified) {
+      if (!entry) {
+        unindexed.push(action.actionId);
+        continue;
+      }
+      index[key] = { ...entry, verifiedAt: stampedAt, verifiedScenarios: action.passed };
+      stamped += 1;
+    } else if (entry && entry.verifiedAt !== undefined) {
+      // Was verified, now a scenario fails — the proof is stale, drop it.
+      const next = { ...entry };
+      delete next.verifiedAt;
+      delete next.verifiedScenarios;
+      index[key] = next;
+      cleared += 1;
+    }
+  }
+
+  const verifiedCount = perAction.filter((a) => a.verified).length;
+  log.step(`Verified coverage from ${pc.cyan(options.file)}`);
+  log.dim(
+    `${perAction.length} action(s) tested · ${verifiedCount} fully passing · ${perAction.length - verifiedCount} with failures`
+  );
+  if (unindexed.length > 0) {
+    log.warn(
+      `${unindexed.length} passing action(s) aren't in .unspa.json yet — record them (implementation status), then re-ingest to mark them verified.`
+    );
+  }
+
+  if (options.dryRun) {
+    log.dim('(dry-run; .unspa.json not written)');
+    return 0;
+  }
+  if (stamped === 0 && cleared === 0) {
+    log.dim('No indexed actions to update.');
+    return 0;
+  }
+
+  await writeJson(path, { ...link, index });
+  log.ok(
+    `Stamped ${stamped} action(s) verified${cleared > 0 ? `, cleared ${cleared} stale` : ''} in .unspa.json`
+  );
+  return 0;
+};

package/cli/commands/scenarios-adapter.ts

@@ -0,0 +1,96 @@
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';
+import { dirname, isAbsolute, join, resolve } from 'node:path';
+import pc from 'picocolors';
+import { discoverSnapshotDirectory } from '../../src/features/behavior-model/infrastructure/persistence/snapshot-discovery';
+import { JsonFolderFeatureRepository } from '../../src/features/behavior-model/infrastructure/persistence/JsonFolderFeatureRepository';
+import type { FeatureId } from '../../src/features/behavior-model/domain/value-objects/ids';
+import { generateAdapterStub, type IndexHint } from '../scenarios/adapter-scaffold';
+import { log } from '../util/log';
+
+export type ScenariosAdapterOptions = {
+  readonly featureId: string;
+  readonly cwd?: string;
+  /** Output path. Defaults to ./unspa.adapter.ts so the export command's default import resolves. */
+  readonly out?: string;
+  readonly adapterExport?: string;
+  readonly dryRun?: boolean;
+  readonly force?: boolean;
+};
+
+const EXPERIMENTAL_BANNER = 'experimental — adapter contract may change between minor versions';
+
+/** Best-effort read of the behavioral index from `.unspa.json` for impl hints. */
+const readIndex = (cwd: string): Readonly<Record<string, IndexHint>> => {
+  try {
+    const raw = JSON.parse(readFileSync(join(cwd, '.unspa.json'), 'utf8')) as {
+      index?: Record<string, IndexHint>;
+    };
+    return raw.index ?? {};
+  } catch {
+    return {};
+  }
+};
+
+export const runScenariosAdapterCommand = async (
+  options: ScenariosAdapterOptions
+): Promise<number> => {
+  const cwd = options.cwd ?? process.cwd();
+  log.dim(`(${EXPERIMENTAL_BANNER})`);
+  const { directory } = discoverSnapshotDirectory({ cwd });
+
+  if (!existsSync(directory)) {
+    log.err(`No unspa/ folder found at or above ${cwd}.`);
+    log.dim('Run `unspa init` first, then add a feature with scenarios.');
+    return 1;
+  }
+
+  const repo = new JsonFolderFeatureRepository(directory);
+  const feature = await repo.get(options.featureId as FeatureId);
+  if (!feature) {
+    log.err(`No feature with id "${options.featureId}" in ${directory}.`);
+    log.dim('Use `unspa list` (then open a project) or the dashboard to find feature ids.');
+    return 1;
+  }
+
+  const { code, actionCount } = generateAdapterStub(feature, {
+    index: readIndex(cwd),
+    ...(options.adapterExport ? { adapterExportName: options.adapterExport } : {})
+  });
+
+  if (actionCount === 0) {
+    log.warn(
+      `Feature "${feature.name}" has no scenarios on any action, so the adapter would be empty.`
+    );
+    log.dim('Author scenarios first, then re-run; the stub mirrors the actions the export tests cover.');
+    return 0;
+  }
+
+  if (options.dryRun) {
+    process.stdout.write(`${code}\n`);
+    log.dim(`(dry-run; ${actionCount} action case${actionCount === 1 ? '' : 's'} would be written)`);
+    return 0;
+  }
+
+  const outPath = options.out
+    ? isAbsolute(options.out)
+      ? options.out
+      : resolve(cwd, options.out)
+    : resolve(cwd, 'unspa.adapter.ts');
+
+  if (existsSync(outPath) && options.force !== true) {
+    log.err(`Refusing to overwrite existing file: ${outPath}`);
+    log.dim('Re-run with --force to overwrite, or pass --out <path> to write elsewhere.');
+    return 1;
+  }
+
+  const outDir = dirname(outPath);
+  if (!existsSync(outDir)) mkdirSync(outDir, { recursive: true });
+  writeFileSync(outPath, code, 'utf8');
+
+  log.ok(`Wrote ${pc.cyan(outPath)}`);
+  log.dim(`${actionCount} action case${actionCount === 1 ? '' : 's'} to fill in.`);
+  log.dim(
+    `Next: implement the cases, then \`unspa scenarios export ${feature.id}\` and run vitest.`
+  );
+  return 0;
+};

package/cli/scenarios/adapter-scaffold.ts

@@ -0,0 +1,99 @@
+import type { Feature } from '../../src/features/behavior-model/domain/entities/Feature';
+
+/**
+ * Scaffolds the user-authored adapter that `unspa scenarios export` calls. The
+ * export command generates the Vitest spec from a feature's scenarios; the only
+ * thing the human still had to write by hand was this adapter. This generates
+ * its skeleton — one `case` per scenario-bearing action, pre-seeded with the
+ * implementation location recorded in `.unspa.json` (when known) — so the loop
+ * from spec to a passing/failing code-vs-spec test is "fill the TODOs", not
+ * "write the bridge from scratch".
+ */
+
+export type IndexHint = {
+  readonly file?: string;
+  readonly line?: number;
+  readonly signature?: string;
+};
+
+export type AdapterScaffoldOptions = {
+  /** Named export for the adapter. Defaults to `adapter` (matches the export command's default). */
+  readonly adapterExportName?: string;
+  /** Behavioral index (`.unspa.json` `index`) for implementation-location hints, keyed `action:<id>`. */
+  readonly index?: Readonly<Record<string, IndexHint>>;
+};
+
+export type AdapterScaffoldResult = {
+  readonly code: string;
+  /** Number of actions that got a case (those carrying at least one scenario). */
+  readonly actionCount: number;
+};
+
+const BANNER = `/**
+ * GENERATED ADAPTER STUB — \`unspa scenarios adapter\`.
+ *
+ * EXPERIMENTAL: the adapter contract (UnspaAdapter / AdapterInvocation /
+ * AdapterResult) may change between minor versions.
+ *
+ * Fill each case: drive your real implementation from input.initialState +
+ * input.parameters and return its actual outcome { status, finalState }. Then
+ * run \`unspa scenarios export <featureId>\` and \`vitest\` — the generated tests
+ * assert your implementation against the same oracle the simulator uses, so
+ * spec↔code drift fails loudly.
+ */`;
+
+const hintComment = (hint: IndexHint | undefined): string => {
+  if (!hint?.file) return '      // impl: (not recorded in .unspa.json yet)';
+  const loc = `${hint.file}${hint.line ? `:${hint.line}` : ''}`;
+  return `      // impl: ${loc}${hint.signature ? ` — ${hint.signature}` : ''}`;
+};
+
+export const generateAdapterStub = (
+  feature: Feature,
+  options: AdapterScaffoldOptions = {}
+): AdapterScaffoldResult => {
+  const exportName = options.adapterExportName ?? 'adapter';
+  const index = options.index ?? {};
+
+  const cases: string[] = [];
+  for (const surface of feature.surfaces) {
+    for (const action of surface.actions) {
+      // The export command only emits tests for scenario-bearing actions, so
+      // those are exactly the cases the adapter needs.
+      if ((action.scenarios ?? []).length === 0) continue;
+      cases.push(
+        [
+          `      // ${surface.name} › ${action.name}`,
+          hintComment(index[`action:${action.id}`]),
+          `      case ${JSON.stringify(String(action.id))}: {`,
+          `        // TODO: call your implementation; return only the paths the scenario asserts.`,
+          `        throw new Error('Adapter not implemented: ${action.name.replace(/'/g, "\\'")} (' + input.actionId + ')');`,
+          `      }`
+        ].join('\n')
+      );
+    }
+  }
+
+  const body =
+    cases.length > 0 ? cases.join('\n\n') : '      // (no scenario-bearing actions yet)';
+
+  const code = `${BANNER}
+import type {
+  AdapterInvocation,
+  AdapterResult,
+  UnspaAdapter
+} from 'unspaghettit/cli/scenarios';
+
+export const ${exportName}: UnspaAdapter = {
+  async invoke(input: AdapterInvocation): Promise<AdapterResult> {
+    switch (input.actionId) {
+${body}
+      default:
+        throw new Error('No adapter case for action ' + input.actionName + ' (' + input.actionId + ')');
+    }
+  }
+};
+`;
+
+  return { code, actionCount: cases.length };
+};

package/cli/scenarios/codegen.ts

@@ -17,6 +17,7 @@ import {
 import { mergeSnapshotWithDefaults } from '../../src/features/behavior-model/domain/services/StateSnapshot';
 import { isExpression } from '../../src/features/behavior-model/domain/value-objects/Expression';
 import { simulate } from '../../src/features/simulator/domain/SimulatorEngine';
+import { scenarioTitleToken } from './results';
 
 export type CodegenOptions = {
   /**
@@ -206,8 +207,13 @@ const renderScenarioBlock = (
     }
   }
 
+  const titleToken = scenarioTitleToken(
+    String(surface.id),
+    String(action.id),
+    String(scenario.id)
+  );
   const code = [
-    `  it(${tsString(scenario.name)}, async () => {`,
+    `  it(${tsString(`${titleToken} ${scenario.name}`)}, async () => {`,
     driftBanner.trimEnd(),
     `    const initialState = ${jsonLiteral(initialState)};`,
     `    const parameters = ${jsonLiteral(parameters)};`,

package/cli/scenarios/results.ts

@@ -0,0 +1,85 @@
+/**
+ * The bridge that turns a real `vitest run` into verified spec coverage.
+ *
+ * The generated scenario spec prefixes each `it(...)` title with a machine
+ * token — `[unspa:<surfaceId>:<actionId>:<scenarioId>]` — so a standard Vitest
+ * JSON report (`vitest run --reporter=json --outputFile=...`) can be parsed
+ * back into "which scenarios the IMPLEMENTATION actually passed", with no
+ * custom reporter or config. `unspa coverage ingest` reads that report and
+ * stamps `verifiedAt` on the matching `.unspa.json` entries — promoting an
+ * entity from "claimed implemented" to "proven against the spec".
+ *
+ * Pure + framework-agnostic: the token format lives here once, used by the
+ * codegen (to emit) and the ingester (to parse), so the two can't drift.
+ */
+
+/** Build the title token the codegen prepends to each generated `it(...)`. */
+export const scenarioTitleToken = (
+  surfaceId: string,
+  actionId: string,
+  scenarioId: string
+): string => `[unspa:${surfaceId}:${actionId}:${scenarioId}]`;
+
+const TOKEN = /\[unspa:([^:\]]+):([^:\]]+):([^:\]]+)\]/;
+
+export type ScenarioResult = {
+  readonly surfaceId: string;
+  readonly actionId: string;
+  readonly scenarioId: string;
+  readonly passed: boolean;
+};
+
+/**
+ * Parse a Vitest JSON report (Jest-compatible shape) into per-scenario
+ * pass/fail. Ignores tests with no unspa token (the user's own tests in the
+ * same run). Tolerant of partial shapes — a malformed report yields [].
+ */
+export const parseScenarioResults = (raw: unknown): ScenarioResult[] => {
+  const root = raw as {
+    testResults?: ReadonlyArray<{
+      assertionResults?: ReadonlyArray<{
+        title?: string;
+        fullName?: string;
+        status?: string;
+      }>;
+    }>;
+  };
+  const out: ScenarioResult[] = [];
+  for (const file of root?.testResults ?? []) {
+    for (const a of file?.assertionResults ?? []) {
+      const match = TOKEN.exec(a.title ?? a.fullName ?? '');
+      if (!match) continue;
+      const [, surfaceId, actionId, scenarioId] = match;
+      if (!surfaceId || !actionId || !scenarioId) continue;
+      out.push({ surfaceId, actionId, scenarioId, passed: a.status === 'passed' });
+    }
+  }
+  return out;
+};
+
+export type ActionVerification = {
+  readonly actionId: string;
+  readonly total: number;
+  readonly passed: number;
+  /** True when the action has at least one scenario result and every one passed. */
+  readonly verified: boolean;
+};
+
+/** Roll per-scenario results up to per-action: an action is verified iff all its scenarios passed. */
+export const summarizeByAction = (
+  results: readonly ScenarioResult[]
+): readonly ActionVerification[] => {
+  const byAction = new Map<string, { total: number; passed: number }>();
+  for (const r of results) {
+    const acc = byAction.get(r.actionId) ?? { total: 0, passed: 0 };
+    acc.total += 1;
+    if (r.passed) acc.passed += 1;
+    byAction.set(r.actionId, acc);
+  }
+  return [...byAction.entries()].map(([actionId, { total, passed }]) => ({
+    actionId,
+    total,
+    passed,
+    verified: total > 0 && passed === total
+  }));
+};

package/cli/skills/unspa-audit/SKILL.md

@@ -24,6 +24,8 @@ source code is not annotated.
 | `get_implementation_gaps` | Authoritative "what is missing/partial/implemented" report. Read this before deciding where to point the user. |
 | `get_implementation_status` | Detailed sidecar for one feature (or filtered to one action/surface). Shows captured fields, locations, staleness flags. |
 | `get_spec_gaps` | Spec-depth diagnostics. Critical + recommended to-do list grounded in entities. Catches shallow specs (effect-less actions, stateless surfaces, untested destructive paths, etc.), orthogonal to "is code indexed?". |
+| `get_drift` | Spec→code drift: implementations audited against an OLDER spec than the one now on disk — the `entry.specVersion` vs `feature.updatedAt` comparison, done for you. Returns `stale` (re-audit these), `unversioned` (audited but never stamped), and `orphans` (keys that no longer resolve). The fastest "what silently went stale" read. |
+| `verify` | One gated `pass`/`warn`/`fail` verdict per feature — scenarios + maturity + reachability + bounded model check + drift + cross-feature event coherence. The in-chat form of the `unspa check` CLI. Use to confirm the spec itself is sound before declaring an audit clean. |
 | `sync_from_index` | After you rewrite `.unspa.json`, the MCP re-reads it, resolves UUIDs, and posts one report per action and per surface. Use this instead of the lower-level `report_implementation_status_batch` unless you need per-entity granularity. |
 | `report_implementation_status` | Fine-grained: sync ONE action or surface plus its children. Use when you intentionally do not want to push the whole index. |
 
@@ -66,6 +68,23 @@ source code is not annotated.
    Resolve every critical gap before declaring the audit clean.
    Recommended gaps are a defensible backlog.
 
+6. **Check for drift, then verify.** Call `get_drift` to find code audited
+   against an older spec than the one on disk (a rule changed under an
+   implementation you previously mapped) — re-audit the `stale` entries. Then
+   `verify` for the one-call verdict: it runs the whole spine (scenarios +
+   maturity + reachability + model check + drift + cross-feature event
+   coherence + verified coverage) and reports `pass` / `warn` / `fail` per
+   check. A clean `verify` (plus zero critical spec gaps) is what "the audit is
+   clean" means. The same gate runs headlessly in CI as `unspa check`.
+
+7. **Distinguish claimed from proven.** A `.unspa.json` `{file,line}` entry
+   says an entity is *implemented*, not *correct*. To prove it, run the
+   feature's scenarios against the real code: `unspa scenarios export` →
+   `vitest run --reporter=json` → `unspa coverage ingest <report>`, which
+   stamps `verifiedAt` on actions whose scenarios all passed. `verify` reports
+   the proven share; `unspa check --min-verified <pct>` gates on it. An honest
+   audit reports both: indexed coverage **and** verified coverage.
+
 ## Reading the index correctly
 
 `.unspa.json` is keyed `"<entityType>:<id-name-or-path>"` where the

package/cli/skills/unspa-edit/SKILL.md

@@ -29,7 +29,9 @@ many Features. Use `add_feature_to_project` to attach.
 ## The domain in 60 seconds
 
 A **Feature** holds `surfaces[]`, `personas[]`, `resources[]`, `entities[]`,
-`events[]`, and optional `devContext`, `expectedActions[]`, `nonGoals[]`.
+`events[]`, `featureInvariants[]` (cross-surface safety), `reachabilityGoals[]`
+(liveness: `reachable` / `always_reachable` target states), and optional
+`devContext`, `expectedActions[]`, `nonGoals[]`.
 
 A **Surface** is one context (screen, terminal, workflow, canvas, ...) with
 `stateDefinitions[]`, `actions[]`, `rules[]`, `invariants[]`,
@@ -117,7 +119,10 @@ Atomic state-from-state-and-param write:
 `remove_surface_rule`, `add_action_invariant`,
 `update_action_invariant`, `remove_action_invariant`,
 `add_surface_invariant`, `update_surface_invariant`,
-`remove_surface_invariant`, `add_transition`, `update_transition`,
+`remove_surface_invariant`, `add_feature_invariant`,
+`update_feature_invariant`, `remove_feature_invariant`,
+`add_reachability_goal`, `update_reachability_goal`, `remove_reachability_goal`,
+`add_transition`, `update_transition`,
 `remove_transition`, `add_effect`, `update_effect`, `remove_effect`,
 `add_event`, `update_event`, `remove_event`, `add_scenario`,
 `update_scenario`, `remove_scenario`, `add_persona`, `update_persona`,
@@ -126,7 +131,16 @@ Atomic state-from-state-and-param write:
 `update_entity_field`, `remove_entity_field`,
 `create_project`, `update_project`, `replace_project`, `delete_project`,
 `add_feature_to_project`, `remove_feature_from_project`,
-`move_feature_in_project`.
+`move_feature_in_project`, `add_project_invariant`,
+`update_project_invariant`, `remove_project_invariant`.
+
+**Cross-feature invariants** live on the Project, not a feature:
+`project.projectInvariants` are safety properties spanning member features
+(referencing state paths in different features, which a feature invariant
+can't). Author with `add_project_invariant` / `update_project_invariant` /
+`remove_project_invariant`; the model checker enforces them across the
+project's state. Use a feature invariant when the property is within one
+feature, a project invariant when it spans two or more.
 
 Use the granular tools for one-off tweaks. For anything ≥ 2 ops, use
 `apply_batch`.
@@ -138,6 +152,9 @@ Use the granular tools for one-off tweaks. For anything ≥ 2 ops, use
 | `get_spec_gaps` | Spec-depth diagnostics. Prioritized critical + recommended gaps. |
 | `get_implementation_gaps` | Implementation coverage gaps (spec vs. `.unspa.json` index). |
 | `get_implementation_status` | Detailed per-action / per-surface coverage report. |
+| `model_check` | Bounded state-space exploration: invariant counterexamples (shortest action path), dead actions, deadlocks, unreachable surfaces, reachability-goal results. |
+| `verify` | One gated `pass`/`warn`/`fail` verdict per feature (scenarios + maturity + reachability + model check + drift + event coherence) — the in-chat form of `unspa check`. |
+| `get_drift` | Implementations audited against an older spec than the one now on disk (stale / unversioned / orphan). |
 
 ## Workflow
 

package/cli/skills/unspa-implement/SKILL.md

@@ -183,6 +183,34 @@ own key will be reported as missing even when the parent is `implemented`.
    `get_spec_gaps` to catch shallow specs that *look* covered but lack
    scenarios, blocking validation rules, etc.
 
+## Prove the code matches the spec (close the loop)
+
+Recording a `{file, line}` says "implemented", not "correct". To turn the
+feature's scenarios into a real code-vs-spec test:
+
+1. `unspa scenarios adapter <featureId>` — scaffolds `unspa.adapter.ts`, one
+   `case` per scenario-bearing action, pre-seeded with the `.unspa.json`
+   implementation locations. Fill each `case` so it drives the real code from
+   `input.initialState` + `input.parameters` and returns `{ status, finalState }`.
+2. `unspa scenarios export <featureId>` — generates a Vitest spec whose oracle
+   is the simulator's prediction for each scenario.
+3. Run vitest with the JSON reporter:
+   `vitest run <spec> --reporter=json --outputFile=unspa-results.json`. Green
+   means the implementation agrees with the spec on every authored scenario; a
+   failure is a real spec↔code divergence — fix the code (or the spec, if the
+   spec was wrong) and re-run.
+4. `unspa coverage ingest unspa-results.json` — stamps `verifiedAt` on every
+   action whose scenarios all passed (and clears it on a regression), promoting
+   those entities from "claimed implemented" to **proven against the spec**.
+5. CI: `unspa ci` drops a workflow running `unspa check`; add
+   `--min-verified <pct>` to require that share of actions be proven, and run
+   the generated scenario spec + ingest in the same job so the code is gated
+   against the spec on every push.
+
+This is the experimental wedge — the adapter contract may shift between minor
+versions. Recording presence in `.unspa.json` (step 5 above) is still the
+baseline; this proves the behavior on top of it.
+
 ## "Don't ask, just build" mode
 
 If the user's prompt signals one-shot autonomy ("one pass", "make