unspaghettit 0.2.0 → 0.4.0

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

package/cli/unspa.ts

@@ -1,11 +1,16 @@
 import { createRequire } from 'node:module';
 import { Command } from 'commander';
+import { runCheckCommand } from './commands/check';
+import { runCiCommand } from './commands/ci';
+import { runCoverageIngestCommand } from './commands/coverage-ingest';
 import { runDashboardCommand } from './commands/dashboard';
 import { runInitCommand } from './commands/init';
 import { runLinkCommand } from './commands/link';
 import { runListCommand } from './commands/list';
+import { runScenariosAdapterCommand } from './commands/scenarios-adapter';
 import { runScenariosExportCommand } from './commands/scenarios-export';
 import { runServeCommand } from './commands/serve';
+import { runThemeCommand } from './commands/theme';
 import { runUninstallCommand } from './commands/uninstall';
 import { runViewCommand } from './commands/view';
 import { log } from './util/log';
@@ -68,6 +73,7 @@ program
   .option('--no-skills', 'Skip installing the bundled unspa skills under .claude/skills/.')
   .option('--fun', 'Pre-check the opt-in narrative skills (worldbuild + worldplay) in the skill picker. Also implicitly on when the CLI is invoked as `unspaghettit`.')
   .option('--with <views>', 'Comma list of opt-in dashboard views to enable (e.g. "builder"). Expert is always on. Without it, interactive init offers the Builder view.')
+  .option('--theme <id>', 'Set the dashboard colour theme at install (e.g. "lyriks"). Cosmetic only; persists so `unspa dashboard` boots with it. Switchable later via `unspa theme set` or the in-app header switcher.')
   .option('-y, --yes', 'Accept defaults. Non-interactive (CI / scripts).')
   .action(async (opts) => {
     if (opts.scope !== 'project' && opts.scope !== 'global') {
@@ -87,7 +93,8 @@ program
       local: opts.local === true,
       custom: opts.custom === true,
       fun: opts.fun === true || FUN_MODE_BY_INVOCATION,
-      withViews: opts.with
+      withViews: opts.with,
+      theme: opts.theme
     });
     process.exit(code);
   });
@@ -108,8 +115,9 @@ program
   .option('-h, --host <host>', 'Host to bind (default: 127.0.0.1). Pass 0.0.0.0 to expose on the LAN; the dashboard has no auth, so do this only on trusted networks.')
   .option('-s, --snapshots <dir>', 'Point the dashboard at a specific snapshots folder (sets UNSPA_SNAPSHOTS for this run). Handy for a one-off look at a custom hub or another repo.')
   .option('--view <ids>', 'Comma list of optional views to enable beyond Expert (e.g. "builder"). Expert is always on and is the default; with no extra views the header shows no switcher.')
+  .option('--theme <id>', 'Colour theme to boot with (e.g. "lyriks"). Cosmetic only; overrides the persisted `unspa theme set` choice for this run. The in-app header switcher can still change it live.')
   .action(async (opts) => {
-    const code = await runDashboardCommand({ port: opts.port, host: opts.host, snapshots: opts.snapshots, views: opts.view });
+    const code = await runDashboardCommand({ port: opts.port, host: opts.host, snapshots: opts.snapshots, views: opts.view, theme: opts.theme });
     process.exit(code);
   });
 
@@ -126,6 +134,61 @@ program
     process.exit(code);
   });
 
+program
+  .command('check [featureId]')
+  .description('Verify the spec headlessly and exit non-zero on failure (CI gate). Runs every scenario as an executable spec test, scores maturity, analyses surface reachability, optionally model-checks the reachable state space, and reports spec→code drift. Scopes to the repo\'s linked project by default; pass a featureId or --project to narrow.')
+  .option('-s, --snapshots <dir>', 'Verify a specific snapshots folder (defaults to walk-up, then the shared hub).')
+  .option('--project <id>', 'Verify a specific project\'s features (overrides the .unspa.json link).')
+  .option('--model-check', 'Also run bounded model checking (exhaustive state-space exploration). Off by default; it is the costly part.')
+  .option('--max-depth <n>', 'Model-check action-depth bound (default 6).', (v) => Number.parseInt(v, 10))
+  .option('--max-states <n>', 'Model-check state cap (default 2000).', (v) => Number.parseInt(v, 10))
+  .option('--min-maturity <n>', 'Fail any feature scoring below this maturity percentage.', (v) => Number.parseInt(v, 10))
+  .option('--min-verified <n>', 'Fail any feature where fewer than N% of actions are proven against code (via `unspa coverage ingest`).', (v) => Number.parseInt(v, 10))
+  .option('--max-scenario-failures <n>', 'Tolerate up to N failing scenarios before failing (default 0).', (v) => Number.parseInt(v, 10))
+  .option('--require-scenarios', 'Fail a feature that has no scenarios authored.')
+  .option('--fail-on-drift', 'Fail when an implementation was audited against an older spec (default: warn only).')
+  .option('--fail-on-dead-actions', 'Fail when an action never fires within the model-check bound (default: warn only).')
+  .option('--fail-on-unmet-goals', 'Fail when a reachability/liveness goal is unmet (default: warn only). Requires --model-check.')
+  .option('--allow-invariant-violations', 'Downgrade reachable invariant violations from failure to warning.')
+  .option('--json', 'Emit the full verification report as JSON instead of the human view.')
+  .action(async (featureId, opts) => {
+    const code = await runCheckCommand({
+      featureId,
+      snapshots: opts.snapshots,
+      project: opts.project,
+      json: opts.json === true,
+      modelCheck: opts.modelCheck === true,
+      maxDepth: opts.maxDepth,
+      maxStates: opts.maxStates,
+      minMaturity: opts.minMaturity,
+      minVerified: opts.minVerified,
+      maxScenarioFailures: opts.maxScenarioFailures,
+      requireScenarios: opts.requireScenarios === true,
+      failOnDrift: opts.failOnDrift === true,
+      failOnDeadActions: opts.failOnDeadActions === true,
+      failOnUnmetGoals: opts.failOnUnmetGoals === true,
+      allowInvariantViolations: opts.allowInvariantViolations === true
+    });
+    process.exit(code);
+  });
+
+program
+  .command('ci')
+  .description('Scaffold a GitHub Actions workflow (.github/workflows/unspaghettit.yml) that runs `unspa check` on every push / PR, so the spec gates CI. Requires the model to travel with the repo (`unspa init --local`). Refuses to clobber without --force.')
+  .option('-o, --out <path>', 'Output path (default: .github/workflows/unspaghettit.yml).')
+  .option('--model-check', 'Run bounded model checking in the workflow (deeper: invariant + liveness counterexamples).')
+  .option('--dry-run', 'Print the workflow to stdout instead of writing it.')
+  .option('-f, --force', 'Overwrite an existing workflow file.')
+  .action(async (opts) => {
+    const code = await runCiCommand({
+      out: opts.out,
+      modelCheck: opts.modelCheck === true,
+      dryRun: opts.dryRun === true,
+      force: opts.force === true
+    });
+    process.exit(code);
+  });
+
 program
   .command('link')
   .description('Bind this repo to a single project via .unspa.json so the MCP scopes its queries to that project (and the LLM picks the right feature from the project\'s members for the task at hand). Pass --unlink to remove the binding.')
@@ -192,6 +255,38 @@ view
     process.exit(await runViewCommand({ action: 'remove', id, snapshots: opts.snapshots }));
   });
 
+// `theme list|set|reset` — pick the dashboard's colour skin. Purely cosmetic
+// (it never changes which features exist), persisted next to the model in
+// `<snapshots>/theme.json` so `unspa dashboard` boots with it. The in-app
+// header switcher flips it live in the browser without touching this file.
+const theme = program
+  .command('theme')
+  .description('Pick the dashboard colour theme (cosmetic). The in-app header switcher can also flip it live.');
+
+theme
+  .command('list')
+  .description('Show the available themes and which one is the persisted default.')
+  .option('-s, --snapshots <dir>', 'Target a specific snapshots folder (defaults to walk-up, then the shared hub).')
+  .action(async (opts) => {
+    process.exit(await runThemeCommand({ action: 'list', snapshots: opts.snapshots }));
+  });
+
+theme
+  .command('set <id>')
+  .description('Set the dashboard theme (e.g. "lyriks"). Persists so `unspa dashboard` uses it.')
+  .option('-s, --snapshots <dir>', 'Target a specific snapshots folder.')
+  .action(async (id, opts) => {
+    process.exit(await runThemeCommand({ action: 'set', id, snapshots: opts.snapshots }));
+  });
+
+theme
+  .command('reset')
+  .description('Revert to the default theme.')
+  .option('-s, --snapshots <dir>', 'Target a specific snapshots folder.')
+  .action(async (opts) => {
+    process.exit(await runThemeCommand({ action: 'reset', snapshots: opts.snapshots }));
+  });
+
 // `scenarios export <featureId>` — generates a Vitest spec from the feature's
 // scenarios, using the deterministic simulator as the assertion oracle. The
 // user writes a thin adapter that calls their real implementation; the
@@ -226,6 +321,45 @@ scenarios
     process.exit(code);
   });
 
+scenarios
+  .command('adapter <featureId>')
+  .description('[experimental] Scaffold the UnspaAdapter stub for a feature: one case per scenario-bearing action, pre-seeded with the implementation location from .unspa.json. Fill the TODOs, then `scenarios export` + vitest closes the spec↔code loop. Refuses to clobber without --force.')
+  .option('-o, --out <path>', 'Output file path. Defaults to ./unspa.adapter.ts (so the export command\'s default import resolves).')
+  .option('--adapter-export <name>', 'Named export for the adapter.', 'adapter')
+  .option('--dry-run', 'Print the generated adapter to stdout instead of writing it.')
+  .option('-f, --force', 'Overwrite the output file if it already exists.')
+  .action(async (featureId, opts) => {
+    const code = await runScenariosAdapterCommand({
+      featureId,
+      out: opts.out,
+      adapterExport: opts.adapterExport,
+      dryRun: opts.dryRun === true,
+      force: opts.force === true
+    });
+    process.exit(code);
+  });
+
+// `coverage ingest <file>` — close the spec↔code proof loop. Reads a Vitest
+// JSON report of the generated scenario spec and stamps `verifiedAt` on the
+// matching .unspa.json action entries, promoting them from "claimed
+// implemented" to "proven against the spec". Gate on it with
+// `unspa check --min-verified`.
+const coverage = program
+  .command('coverage')
+  .description('Work with implementation coverage recorded in .unspa.json.');
+
+coverage
+  .command('ingest <resultsFile>')
+  .description('[experimental] Read a Vitest JSON report (vitest run --reporter=json --outputFile=<file>) of the generated scenario spec and mark each action whose scenarios all passed as verified in .unspa.json (clears stale verifications that now fail). Recording only; gate with `unspa check --min-verified`.')
+  .option('--dry-run', 'Report what would change without writing .unspa.json.')
+  .action(async (resultsFile, opts) => {
+    const code = await runCoverageIngestCommand({
+      file: resultsFile,
+      dryRun: opts.dryRun === true
+    });
+    process.exit(code);
+  });
+
 program.parseAsync(process.argv).catch((err) => {
   log.err((err as Error).message);
   process.exit(1);

package/cli/util/context-files.ts

@@ -27,6 +27,11 @@ per-repo install (\`unspa init --local\`). Open the dashboard with
 \`unspa dashboard\` (http://localhost:3000) to see surfaces, actions, simulator,
 maturity, and implementation coverage.
 
+When using the CLI hub, treat \`~/.unspa-hub/unspa\` as the source of truth.
+Dashboard localhost ports are only views over that folder and may change per
+run. Do not inspect Docker containers, unrelated app integrations, or another
+product's embedded Unspa data unless the user explicitly asks for that source.
+
 ### Editing the model. Use the MCP, don't re-emit JSON
 
 The Unspaghettit **MCP server** is registered for this repo. Prefer its tools over
@@ -40,8 +45,13 @@ and produce smaller diffs. Workflow:
 3. For multi-step edits use \`apply_batch\`. N ops in one atomic load + validate +
    save. Add ops can capture their new id under \`op.ref\` so later ops in the same
    batch reference it via \`*Ref\` (e.g. \`surfaceRef:"shop"\`).
-4. Validate risky proposals with \`dry_run_simulate\` (pure, no persist) and
-   \`score_feature\` before committing.
+4. Validate before committing: \`dry_run_simulate\` (pure, no persist),
+   \`run_all_scenarios\`, \`model_check\` (bounded state-space exploration —
+   invariant counterexamples with the action path, dead actions, deadlocks,
+   reachability, reachability-goal results), and \`score_feature\` (maturity).
+   Gate the whole feature/project in one call with \`verify\` — the in-chat form
+   of the \`unspa check\` CI command. \`get_drift\` finds code audited against an
+   older spec than the one now on disk.
 5. Run \`find_state_references\` before renaming or removing a state path.
 
 ### \`.unspa.json\`. Record implementations in the index
@@ -69,6 +79,12 @@ in its \`orphans\` block with a fix hint.
 Each entry stores \`{ file, line, signature, ... }\`. After editing the index,
 call \`sync_from_index\` so the MCP refreshes the coverage report.
 
+To PROVE coverage (not just claim it), run the feature's scenarios against the
+real code: \`unspa scenarios export <featureId>\` → \`vitest run --reporter=json\`
+→ \`unspa coverage ingest <report>\`. That stamps \`verifiedAt\` on actions whose
+scenarios all passed; \`verify\` / \`unspa check --min-verified\` gate on the
+proven share.
+
 ### Don't
 
 - Don't regenerate an entire feature JSON from scratch; mutate via the MCP.

package/cli/util/theme.ts

@@ -0,0 +1,34 @@
+import { mkdirSync, readFileSync, writeFileSync } from 'node:fs';
+import { dirname, join } from 'node:path';
+
+/**
+ * Persisted dashboard-theme selection, stored next to the model the dashboard
+ * shows (`<snapshots>/theme.json`). Purely cosmetic — picks the colour skin the
+ * UI renders with. `unspa dashboard` reads it and exposes it to the app as
+ * `PUBLIC_UNSPA_THEME`; the in-app header switcher can still override it live
+ * in the browser. A missing/malformed file means the default theme.
+ */
+const FILE_NAME = 'theme.json';
+
+type ThemeConfig = { readonly theme?: unknown };
+
+export const themeConfigPath = (snapshotsDir: string): string => join(snapshotsDir, FILE_NAME);
+
+/** Read the selected theme id; tolerant of a missing/malformed file. */
+export const readSelectedTheme = (snapshotsDir: string): string => {
+  try {
+    const parsed = JSON.parse(readFileSync(themeConfigPath(snapshotsDir), 'utf8')) as ThemeConfig;
+    return typeof parsed.theme === 'string' ? parsed.theme.trim().toLowerCase() : 'default';
+  } catch {
+    return 'default';
+  }
+};
+
+/** Persist the selected theme id (normalized: trimmed, lowercased). */
+export const writeSelectedTheme = (snapshotsDir: string, theme: string): string => {
+  const next = theme.trim().toLowerCase() || 'default';
+  const path = themeConfigPath(snapshotsDir);
+  mkdirSync(dirname(path), { recursive: true });
+  writeFileSync(path, `${JSON.stringify({ theme: next }, null, 2)}\n`, 'utf8');
+  return next;
+};

package/mcp-server/bin.ts

@@ -1,104 +1,104 @@
-#!/usr/bin/env node
-import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
-import { JsonFolderFeatureRepository } from '../src/features/behavior-model/infrastructure/persistence/JsonFolderFeatureRepository';
-import { discoverSnapshotDirectory } from '../src/features/behavior-model/infrastructure/persistence/snapshot-discovery';
-import { JsonFolderImplementationStatusRepository } from '../src/features/implementation-status/infrastructure/persistence/JsonFolderImplementationStatusRepository';
-import { JsonFolderProjectRepository } from '../src/features/projects/infrastructure/persistence/JsonFolderProjectRepository';
-import { migrateFlatLayoutAndLog } from '../src/shared/infrastructure/persistence/snapshotLayout';
-import { discoverRepoLink } from './repo-link';
-import { buildServer } from './server';
-import {
-  SyncAwareFeatureRepository,
-  SyncAwareImplementationStatusRepository,
-  SyncAwareProjectRepository
-} from './sync-aware-repos';
-
-const parseArgs = (argv: readonly string[]): { override?: string; link?: string } => {
-  const out: { override?: string; link?: string } = {};
-  for (let i = 0; i < argv.length; i += 1) {
-    const arg = argv[i];
-    if (arg === '--snapshots' || arg === '-s') {
-      const next = argv[i + 1];
-      if (!next) throw new Error('--snapshots requires a directory path');
-      out.override = next;
-      i += 1;
-      continue;
-    }
-    if (arg && arg.startsWith('--snapshots=')) {
-      out.override = arg.slice('--snapshots='.length);
-      continue;
-    }
-    if (arg === '--link' || arg === '-l') {
-      const next = argv[i + 1];
-      if (!next) throw new Error('--link requires a path to .unspa.json or its parent folder');
-      out.link = next;
-      i += 1;
-      continue;
-    }
-    if (arg && arg.startsWith('--link=')) {
-      out.link = arg.slice('--link='.length);
-      continue;
-    }
-  }
-  return out;
-};
-
-const main = async (): Promise<void> => {
-  const args = parseArgs(process.argv.slice(2));
-  const override = args.override ?? process.env.UNSPA_SNAPSHOTS;
-  const { directory, source } = discoverSnapshotDirectory({ override });
-  const linkOverride = args.link ?? process.env.UNSPA_LINK;
-
-  // Snapshot the link state once for the startup banner; the live repoContext
-  // below re-resolves on every property access, so subsequent `unspa link` /
-  // file edits are picked up without restarting the MCP server.
-  const initialLink = discoverRepoLink(process.cwd(), linkOverride);
-
-  // Diagnostics go to stderr. Stdout is reserved for the JSON-RPC stream.
-  process.stderr.write(`[unspa-mcp] snapshots: ${directory} (${source})\n`);
-  migrateFlatLayoutAndLog(directory, 'unspa-mcp');
-  if (initialLink.link) {
-    process.stderr.write(
-      `[unspa-mcp] repo linked to project: ${initialLink.link.projectName ?? '(unknown)'} (${initialLink.link.projectId})\n`
-    );
-  }
-
-  const repo = new SyncAwareFeatureRepository(new JsonFolderFeatureRepository(directory));
-  const statusRepo = new SyncAwareImplementationStatusRepository(
-    new JsonFolderImplementationStatusRepository(directory)
-  );
-  const projectRepo = new SyncAwareProjectRepository(
-    new JsonFolderProjectRepository(directory)
-  );
-
-  // Live `.unspa.json` lookup. Tools read `repoContext.link` / `.linkPath`
-  // on every invocation, so if the developer runs `unspa link` while the AI
-  // client is connected the next tool call sees the new state — no restart
-  // required. Per-access stat walk is a few microseconds; cheap enough that
-  // we don't memoize.
-  const cwd = process.cwd();
-  const repoContext = {
-    get cwd() {
-      return cwd;
-    },
-    get link() {
-      return discoverRepoLink(cwd, linkOverride).link;
-    },
-    get linkPath() {
-      return discoverRepoLink(cwd, linkOverride).path;
-    }
-  };
-
-  const server = buildServer(repo, {
-    statusRepo,
-    projectRepo,
-    repoContext
-  });
-  const transport = new StdioServerTransport();
-  await server.connect(transport);
-};
-
-main().catch((err) => {
-  process.stderr.write(`[unspa-mcp] fatal: ${(err as Error).message}\n`);
-  process.exit(1);
-});
+#!/usr/bin/env node
+import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
+import { JsonFolderFeatureRepository } from '../src/features/behavior-model/infrastructure/persistence/JsonFolderFeatureRepository';
+import { discoverSnapshotDirectory } from '../src/features/behavior-model/infrastructure/persistence/snapshot-discovery';
+import { JsonFolderImplementationStatusRepository } from '../src/features/implementation-status/infrastructure/persistence/JsonFolderImplementationStatusRepository';
+import { JsonFolderProjectRepository } from '../src/features/projects/infrastructure/persistence/JsonFolderProjectRepository';
+import { migrateFlatLayoutAndLog } from '../src/shared/infrastructure/persistence/snapshotLayout';
+import { discoverRepoLink } from './repo-link';
+import { buildServer } from './server';
+import {
+  SyncAwareFeatureRepository,
+  SyncAwareImplementationStatusRepository,
+  SyncAwareProjectRepository
+} from './sync-aware-repos';
+
+const parseArgs = (argv: readonly string[]): { override?: string; link?: string } => {
+  const out: { override?: string; link?: string } = {};
+  for (let i = 0; i < argv.length; i += 1) {
+    const arg = argv[i];
+    if (arg === '--snapshots' || arg === '-s') {
+      const next = argv[i + 1];
+      if (!next) throw new Error('--snapshots requires a directory path');
+      out.override = next;
+      i += 1;
+      continue;
+    }
+    if (arg && arg.startsWith('--snapshots=')) {
+      out.override = arg.slice('--snapshots='.length);
+      continue;
+    }
+    if (arg === '--link' || arg === '-l') {
+      const next = argv[i + 1];
+      if (!next) throw new Error('--link requires a path to .unspa.json or its parent folder');
+      out.link = next;
+      i += 1;
+      continue;
+    }
+    if (arg && arg.startsWith('--link=')) {
+      out.link = arg.slice('--link='.length);
+      continue;
+    }
+  }
+  return out;
+};
+
+const main = async (): Promise<void> => {
+  const args = parseArgs(process.argv.slice(2));
+  const override = args.override ?? process.env.UNSPA_SNAPSHOTS;
+  const { directory, source } = discoverSnapshotDirectory({ override });
+  const linkOverride = args.link ?? process.env.UNSPA_LINK;
+
+  // Snapshot the link state once for the startup banner; the live repoContext
+  // below re-resolves on every property access, so subsequent `unspa link` /
+  // file edits are picked up without restarting the MCP server.
+  const initialLink = discoverRepoLink(process.cwd(), linkOverride);
+
+  // Diagnostics go to stderr. Stdout is reserved for the JSON-RPC stream.
+  process.stderr.write(`[unspa-mcp] snapshots: ${directory} (${source})\n`);
+  migrateFlatLayoutAndLog(directory, 'unspa-mcp');
+  if (initialLink.link) {
+    process.stderr.write(
+      `[unspa-mcp] repo linked to project: ${initialLink.link.projectName ?? '(unknown)'} (${initialLink.link.projectId})\n`
+    );
+  }
+
+  const repo = new SyncAwareFeatureRepository(new JsonFolderFeatureRepository(directory));
+  const statusRepo = new SyncAwareImplementationStatusRepository(
+    new JsonFolderImplementationStatusRepository(directory)
+  );
+  const projectRepo = new SyncAwareProjectRepository(
+    new JsonFolderProjectRepository(directory)
+  );
+
+  // Live `.unspa.json` lookup. Tools read `repoContext.link` / `.linkPath`
+  // on every invocation, so if the developer runs `unspa link` while the AI
+  // client is connected the next tool call sees the new state — no restart
+  // required. Per-access stat walk is a few microseconds; cheap enough that
+  // we don't memoize.
+  const cwd = process.cwd();
+  const repoContext = {
+    get cwd() {
+      return cwd;
+    },
+    get link() {
+      return discoverRepoLink(cwd, linkOverride).link;
+    },
+    get linkPath() {
+      return discoverRepoLink(cwd, linkOverride).path;
+    }
+  };
+
+  const server = buildServer(repo, {
+    statusRepo,
+    projectRepo,
+    repoContext
+  });
+  const transport = new StdioServerTransport();
+  await server.connect(transport);
+};
+
+main().catch((err) => {
+  process.stderr.write(`[unspa-mcp] fatal: ${(err as Error).message}\n`);
+  process.exit(1);
+});