unspaghettit 0.2.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/dashboard.ts

@@ -3,7 +3,9 @@ import { existsSync } from 'node:fs';
 import { dirname, resolve } from 'node:path';
 import { fileURLToPath } from 'node:url';
 import { discoverSnapshotDirectory } from '../../src/features/behavior-model/infrastructure/persistence/snapshot-discovery';
+import { parseThemeId } from '../../src/lib/theme/registry';
 import { readEnabledViews } from '../util/views';
+import { readSelectedTheme } from '../util/theme';
 import { log } from '../util/log';
 
 const __filename = fileURLToPath(import.meta.url);
@@ -45,6 +47,7 @@ export const runDashboardCommand = async (
     readonly host?: string;
     readonly snapshots?: string;
     readonly views?: string;
+    readonly theme?: string;
   }
 ): Promise<number> => {
   const repoRoot = resolve(__dirname, '..', '..');
@@ -126,6 +129,17 @@ export const runDashboardCommand = async (
     log.dim(`Views: expert + ${views.join(', ')}`);
   }
 
+  // Colour theme (cosmetic). A `--theme` flag overrides the persisted choice
+  // (`unspa theme set`) for this run; both feed the app as PUBLIC_UNSPA_THEME,
+  // which seeds the no-flash server-rendered <html data-theme>. The in-app
+  // switcher can still change it live in the browser. Unknown ids fall back to
+  // the default, so a typo never blanks the UI.
+  const theme = parseThemeId(args.theme ?? readSelectedTheme(directory));
+  if (theme !== 'default') {
+    env.PUBLIC_UNSPA_THEME = theme;
+    log.dim(`Theme: ${theme}`);
+  }
+
   return await new Promise<number>((resolvePromise) => {
     const child = spawn(process.execPath, [serverShim], {
       stdio: 'inherit',

package/cli/commands/init.ts

@@ -7,12 +7,14 @@ import { ALL_CLIENTS, clientById, SERVER_NAME, type ClientAdapter } from '../cli
 import { buildUnspaMcpEntry } from '../clients/claude-code';
 import type { ApplyResult, ConfigScope, McpServerEntry } from '../clients/types';
 import { isOptionalViewId, optionalViews } from '../../src/lib/views/registry';
+import { isThemeId, parseThemeId } from '../../src/lib/theme/registry';
 import { ask } from '../util/ask';
 import { writeUnspaContextBlocks } from '../util/context-files';
 import { upsertGitignoreBlock } from '../util/gitignore';
 import { log } from '../util/log';
 import { installUnspaSkills } from '../util/skills';
 import { readEnabledViews, writeEnabledViews } from '../util/views';
+import { writeSelectedTheme } from '../util/theme';
 
 /**
  * Expand a user-supplied hub path: tilde-expansion, relative→absolute (resolved
@@ -119,6 +121,13 @@ export type InitOptions = {
    * always on regardless.
    */
   readonly withViews?: string;
+  /**
+   * Dashboard colour theme to persist at setup (e.g. "lyriks"). Cosmetic only;
+   * written to `<snapshots>/theme.json`, same as `unspa theme set`, so
+   * `unspa dashboard` boots with it. The in-app header switcher can change it
+   * live later. Unknown ids fall back to the default with a warning.
+   */
+  readonly theme?: string;
 };
 
 const resolveClientsArg = async (
@@ -338,6 +347,23 @@ export const runInitCommand = async (options: InitOptions = {}): Promise<number>
     log.dim('Shows as a view switcher in `unspa dashboard`. Turn off later with `unspa view remove <id>`.');
   }
 
+  // 1c. Optional colour theme. Cosmetic only — persists the chosen skin into
+  //     `<snapshots>/theme.json` so `unspa dashboard` boots with it. An unknown
+  //     id is a no-op (keeps the default) with a warning rather than a hard
+  //     fail. Switchable later via `unspa theme set` or the in-app switcher.
+  if (options.theme !== undefined) {
+    const raw = options.theme.trim().toLowerCase();
+    if (raw && raw !== 'default' && !isThemeId(raw)) {
+      log.warn(`Unknown theme "${raw}" — keeping the default theme.`);
+    }
+    const id = parseThemeId(options.theme);
+    writeSelectedTheme(target.dir, id);
+    if (id !== 'default') {
+      log.ok(`Dashboard theme set to ${pc.cyan(id)}.`);
+      log.dim('Cosmetic skin. Change it with `unspa theme set <id>` or the dashboard header switcher.');
+    }
+  }
+
   // 2. Pick clients, write MCP server entry. `mergeMcpServerEntry` compares
   //    before writing so re-runs are a no-op when nothing changed. Detection
   //    is scoped to this cwd/home so the pre-selection (interactive) and the

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/commands/theme.ts

@@ -0,0 +1,62 @@
+import pc from 'picocolors';
+import { discoverSnapshotDirectory } from '../../src/features/behavior-model/infrastructure/persistence/snapshot-discovery';
+import { ALL_THEMES, isThemeId, parseThemeId } from '../../src/lib/theme/registry';
+import { readSelectedTheme, writeSelectedTheme } from '../util/theme';
+import { log } from '../util/log';
+
+export type ThemeCommandOptions = {
+  readonly action: 'list' | 'set' | 'reset';
+  readonly id?: string;
+  readonly cwd?: string;
+  readonly snapshots?: string;
+};
+
+const known = (): string => ALL_THEMES.map((t) => t.id).join(', ');
+
+/**
+ * Pick the dashboard's colour theme. Purely cosmetic: it only changes which
+ * skin the design system renders with, never a feature. The selection persists
+ * in `<snapshots>/theme.json` so `unspa dashboard` boots with it; the in-app
+ * header switcher can flip it live in the browser without touching this file.
+ */
+export const runThemeCommand = async (options: ThemeCommandOptions): Promise<number> => {
+  const cwd = options.cwd ?? process.cwd();
+  const { directory, source } = discoverSnapshotDirectory({ cwd, override: options.snapshots });
+  const active = parseThemeId(readSelectedTheme(directory));
+
+  if (options.action === 'list') {
+    log.step(`Themes for ${pc.cyan(directory)} (${source})`);
+    log.dim(`Active default: ${pc.cyan(active)}`);
+    for (const theme of ALL_THEMES) {
+      const on = active === theme.id;
+      const marker = on ? pc.green('● active') : pc.dim('○      ');
+      process.stdout.write(`${marker}  ${pc.cyan(theme.label)} ${pc.dim(`(${theme.id})`)} — ${theme.description}\n`);
+    }
+    log.blank();
+    log.dim('Set with `unspa theme set <id>`, revert with `unspa theme reset`.');
+    log.dim('Or flip it live from the dashboard header (the palette button).');
+    return 0;
+  }
+
+  if (options.action === 'reset') {
+    writeSelectedTheme(directory, 'default');
+    log.ok('Theme reset to default.');
+    log.dim('Restart `unspa dashboard` to apply (or use the in-app switcher).');
+    return 0;
+  }
+
+  // set
+  const id = (options.id ?? '').trim().toLowerCase();
+  if (!id) {
+    log.err(`Missing theme id. Known themes: ${known()}.`);
+    return 1;
+  }
+  if (!isThemeId(id)) {
+    log.err(`Unknown theme "${id}". Known themes: ${known()}.`);
+    return 1;
+  }
+  const next = writeSelectedTheme(directory, id);
+  log.ok(`Theme set to ${pc.cyan(next)}.`);
+  log.dim('Restart `unspa dashboard` to apply, or switch live via the dashboard header.');
+  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