unspaghettit 0.2.0 → 0.4.0

package/mcp-server/resources/guide.ts

@@ -47,15 +47,17 @@ Feature
   ├── resources[]       External dependencies (APIs, storage, …)
   ├── entities[]        Structured data namespaces with typed fields
   ├── events[]          First-class event registry { name, description, payloadSchema? }
-  └── valueSets[]       Named reusable enums { name, values } referenced by valueSetId
+  ├── valueSets[]       Named reusable enums { name, values } referenced by valueSetId
+  ├── featureInvariants[]  Cross-surface post-conditions (checked after every action)
+  └── reachabilityGoals[]  Liveness goals — reachable / always_reachable target states (the complement to invariants)
 
 State paths use dot notation: "cart.itemCount", "user.profile.name".
 StateDefinition: { path, type (string|number|boolean|enum|object|array), defaultValue, enumValues? | valueSetId?, sharedWith?: SurfaceId[] }
 
 Descriptions are mandatory for every authored element. That includes Feature,
 Project, Surface, StateDefinition, Parameter, Rule, Effect, Invariant,
-Transition, Persona, Resource, Entity, EntityField, Scenario, Scenario
-expectedAssertion, Event, and Event payload field. Action uses the mandatory
+Reachability goal, Transition, Persona, Resource, Entity, EntityField, Scenario,
+Scenario expectedAssertion, Event, and Event payload field. Action uses the mandatory
 \`intent\` field as its description. If the user has not provided a description,
 ask for it or write a concise one from the provided context before calling tools.
 
@@ -112,7 +114,25 @@ Before committing a large change:
   1. apply_batch dryRun:true  → catches type errors and structural issues
   2. dry_run_simulate          → runs the simulator on one action (pure, no persist)
   3. run_all_scenarios         → executes every scenario, applying personaId first when set
-  4. score_feature          → maturity report; use to catch regressions
+  4. model_check               → bounded exhaustive state-space exploration: invariant counterexamples
+                                 (with the shortest action path that reaches them), dead actions,
+                                 deadlocks, unreachable/terminal surfaces, and reachability-goal results
+  5. score_feature          → maturity report; use to catch regressions
+
+To gate the whole feature/project in one call (the CI shape), use verify — it folds scenarios +
+maturity + reachability + optional model_check + spec→code drift + cross-feature event coherence +
+verified coverage into one pass/warn/fail verdict (the in-chat form of the \`unspa check\` CLI).
+get_drift surfaces just the spec-drift part (code audited against an older spec than the one now on
+disk). With modelCheck on, verify also enforces project-level invariants (project.projectInvariants,
+authored via add_project_invariant / update_project — cross-FEATURE safety properties referencing
+state paths in different features, which a feature invariant can't) over the union of the project's
+state.
+
+Verified coverage closes the spec↔code loop: \`.unspa.json\` records WHERE each entity lives; running
+the generated scenario spec (\`unspa scenarios export\` → \`vitest --reporter=json\`) and
+\`unspa coverage ingest <report>\` stamps \`verifiedAt\` on the actions whose scenarios PASSED against
+the real code — "proven", not just "claimed". verify / \`unspa check --min-verified <pct>\` gate on
+that proven share.
 
 Run find_state_references before renaming or removing a state path. It shows every rule,
 effect, invariant, and requiredState that references that path.

package/mcp-server/resources/operations.ts

@@ -41,6 +41,8 @@ actionRef: a_new }\` works when only the action was minted in this batch.
   add_surface_invariant    { ref?, surfaceRef|surfaceId, invariant }
   add_feature_invariant    { ref?, invariant }
 . Feature-level invariants are checked after every action in the feature regardless of surface. Use for cross-surface properties (Σ balances = 0). Eliminates the workaround of duplicating one invariant onto every surface.
+  add_reachability_goal    { ref?, name, kind, condition, description, message? }
+. Feature-level LIVENESS goal, the complement to invariants (safety). \`kind:"reachable"\` = some reachable state satisfies \`condition\` (the target is achievable at all); \`kind:"always_reachable"\` = the target stays reachable from EVERY reachable state (no trap). \`condition\` is the target state, same shape as an invariant condition; no parameter scope. Evaluated by model_check / verify over the reachable state space (bounded), which return the shortest action path to a trap on an always_reachable failure.
   add_transition           { ref?, surfaceRef|surfaceId, target|targetRef, label?, description }
   add_persona              { ref?, name, description, stateOverrides?, parameterOverrides?, persistAcrossSurfaces? }
   add_value_set            { ref?, name, description, values }
@@ -66,6 +68,7 @@ actionRef: a_new }\` works when only the action was minted in this batch.
   update_action_invariant { ..., invariantId, patch }
   update_surface_invariant    { surfaceRef|surfaceId, invariantId, patch }
   update_feature_invariant    { invariantId, patch }
+  update_reachability_goal    { goalId, patch }
   update_transition           { surfaceRef|surfaceId, transitionId, target?, label?, description? }
   update_persona              { personaId, ...partial }
   update_value_set            { valueSetId, name?, description?, values? }

package/mcp-server/seed-snapshots.ts

@@ -1,22 +1,22 @@
-#!/usr/bin/env node
-import { JsonFolderFeatureRepository } from '../src/features/behavior-model/infrastructure/persistence/JsonFolderFeatureRepository';
-import { discoverSnapshotDirectory } from '../src/features/behavior-model/infrastructure/persistence/snapshot-discovery';
-import { seedFeatures } from '../src/features/behavior-model/infrastructure/seed/seedFeatures';
-
-const main = async (): Promise<void> => {
-  const override = process.env.UNSPA_SNAPSHOTS;
-  const { directory, source } = discoverSnapshotDirectory({ override: override ?? './unspa' });
-  process.stdout.write(`Writing seed snapshots → ${directory} (${source})\n`);
-
-  const repo = new JsonFolderFeatureRepository(directory);
-  for (const feature of seedFeatures) {
-    await repo.save(feature);
-    process.stdout.write(`  + ${feature.name}\n`);
-  }
-  process.stdout.write(`Done. ${seedFeatures.length} features written.\n`);
-};
-
-main().catch((err) => {
-  process.stderr.write(`seed:snapshots failed: ${(err as Error).message}\n`);
-  process.exit(1);
-});
+#!/usr/bin/env node
+import { JsonFolderFeatureRepository } from '../src/features/behavior-model/infrastructure/persistence/JsonFolderFeatureRepository';
+import { discoverSnapshotDirectory } from '../src/features/behavior-model/infrastructure/persistence/snapshot-discovery';
+import { seedFeatures } from '../src/features/behavior-model/infrastructure/seed/seedFeatures';
+
+const main = async (): Promise<void> => {
+  const override = process.env.UNSPA_SNAPSHOTS;
+  const { directory, source } = discoverSnapshotDirectory({ override: override ?? './unspa' });
+  process.stdout.write(`Writing seed snapshots → ${directory} (${source})\n`);
+
+  const repo = new JsonFolderFeatureRepository(directory);
+  for (const feature of seedFeatures) {
+    await repo.save(feature);
+    process.stdout.write(`  + ${feature.name}\n`);
+  }
+  process.stdout.write(`Done. ${seedFeatures.length} features written.\n`);
+};
+
+main().catch((err) => {
+  process.stderr.write(`seed:snapshots failed: ${(err as Error).message}\n`);
+  process.exit(1);
+});

package/mcp-server/server.ts

@@ -28,6 +28,7 @@ import { registerInvariantTools } from './tools/invariant';
 import { registerParameterTools } from './tools/parameter';
 import { registerPersonaTools } from './tools/persona';
 import { registerProjectTools } from './tools/project';
+import { registerReachabilityGoalTools } from './tools/reachabilityGoal';
 import { registerQueueTools } from './tools/queue';
 import { registerReadTools } from './tools/read';
 import { registerReorderTools } from './tools/reorder';
@@ -40,6 +41,7 @@ import { registerStateDefinitionTools } from './tools/state';
 import { registerSurfaceTools } from './tools/surface';
 import { registerTransitionTools } from './tools/transition';
 import { registerValueSetTools } from './tools/valueSet';
+import { registerVerificationTools } from './tools/verification';
 import { json, type ToolDeps } from './tools/_shared';
 import { metrics } from './metrics';
 import type { RepoLink } from './repo-link';
@@ -86,7 +88,7 @@ export type BuildServerDeps = {
 // byte is paid once per session, but it offsets per-tool description bloat.
 const SERVER_INSTRUCTIONS = `Unspaghettit models software as executable behavior. The unit is a Feature: ONE coherent slice of behavior inside a Project (a flow, a screen, a capability), sized so you can hold it all in head at once. Rule of thumb: 1-15 surfaces, 30-100 actions. A Feature is NOT a whole product. "Add filter to results" is one Feature; "Spotify clone" is a Project that needs many Features. If a Feature grows past 15 surfaces, split it. Hierarchy: Domain tag > Project > Feature > Surface > Action > State/Rule/Effect. A Domain is only a project tag/grouping for filtering Projects, not its own modeling page.
 
-Feature shape: { id, name, surfaces[], personas[], resources[], entities[], events[], devContext? }. A Surface is one context (screen, terminal, workflow, canvas, ...) holding stateDefinitions[], actions[], rules[], invariants[], transitions[]. An Action is a user/AI-triggerable action with parameters[], rules[], effects[], invariants[], requiredStates[], emittedEvents[]. State lives at dotted paths ("cart.itemCount"); StateDefinition declares the schema (path, type, defaultValue, sharedWith?:other surfaces that also use it).
+Feature shape: { id, name, surfaces[], personas[], resources[], entities[], events[], featureInvariants[], reachabilityGoals[], devContext? }. A Surface is one context (screen, terminal, workflow, canvas, ...) holding stateDefinitions[], actions[], rules[], invariants[], transitions[]. An Action is a user/AI-triggerable action with parameters[], rules[], effects[], invariants[], requiredStates[], emittedEvents[]. State lives at dotted paths ("cart.itemCount"); StateDefinition declares the schema (path, type, defaultValue, sharedWith?:other surfaces that also use it).
 
 Naming convention: names are for humans first. Use short Title Case noun phrases for surfaces ("Checkout", "MCP Server") and verb phrases for actions ("Apply Batch", "Get Repo Context", "Manage Rules"). Let parent context carry repeated words: on the "MCP Server" surface, write "Create Feature" or "Manage Surfaces", not "Create Feature via MCP" or a repeated "MCP ..." prefix. Avoid boilerplate suffixes/prefixes across siblings; put technical identifiers, tool ids, file paths, HTTP verbs, or storage names in descriptions and implementation indexes unless the user-facing concept is literally that technical object.
 
@@ -96,7 +98,7 @@ Rules guard behavior: { category, condition: { left: statePath, operator (equals
 
 Effects are discriminated by type: set_state{path,value} | show_message{message,tone?} | emit_event{event} | block_action{reason} | allow_action | transition_surface{target}. set_state.value also accepts an Expression. Value:{kind:"add", left:{kind:"state", path:"player.vx"}, right:{kind:"param", name:"ax"}} writes vx+ax atomically. In apply_batch the transition_surface effect accepts targetRef so it can wire to a surface created earlier in the same batch.
 
-Events are first-class entities in feature.events[] with { name, description, payloadSchema? }. emit_event effects and action.emittedEvents reference them by name. Register the event once via add_event so the dashboard knows the payload shape. Invariants are post-conditions; violations block the run.
+Events are first-class entities in feature.events[] with { name, description, payloadSchema? }. emit_event effects and action.emittedEvents reference them by name. Register the event once via add_event so the dashboard knows the payload shape. Invariants are post-conditions; violations block the run. Reachability goals (feature.reachabilityGoals, add_reachability_goal) are the liveness complement to invariants: kind "reachable" asserts a target state is achievable at all, "always_reachable" asserts it stays reachable from every reachable state; model_check / verify evaluate them over the state space and return the shortest action path to any trap.
 
 Value sets are named, reusable enums in feature.valueSets[] { name, values }. A state or parameter of type enum can reference one via valueSetId instead of inlining enumValues (add_value_set), so the allowed values live in one place. Inline enumValues still work; the two are mutually exclusive per field.
 
@@ -106,9 +108,9 @@ Workflow:
 0. Call get_repo_context once at session start. If linked:true, the developer has bound this repo to one project via .unspa.json. The response includes linkedProjectId, linkedProjectName, and the project's features[{id,name}]. Scope all subsequent calls to that project: pick the right featureId from features[] for the task at hand (use file paths being edited, action name in the user prompt, and the surrounding context). When ambiguous, ask the user which feature they mean.
 1. Discover with list_features then list_actions. get_feature returns an INDEX (ids+names+counts+devContext) by default. Drill into a single action with get_action. Only pass get_feature(verbose:true) when you genuinely need the full blob; it is ~10× larger.
 2. 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") instead of *Id; add_state_definition.sharedWith also accepts those refs. Pass dryRun:true to validate and get maturity feedback without saving. Strongly preferred over many granular calls.
-3. Validate risky proposals with apply_batch dryRun:true, dry_run_simulate (pure, no persist), run_all_scenarios (executes every scenario, including its persona baseline when set, through the simulator and checks expectedStatus + expectedAssertions), and score_feature (maturity report) before committing. Run find_state_references before renaming/removing a state path.
+3. Validate risky proposals with apply_batch dryRun:true, dry_run_simulate (pure, no persist), run_all_scenarios (executes every scenario, including its persona baseline when set, through the simulator and checks expectedStatus + expectedAssertions), model_check (bounded exhaustive exploration of the reachable state space — finds invariant counterexamples with the action path that reaches them, dead actions, deadlocks, and unreachable/terminal surfaces, beyond the example flows scenarios cover), and score_feature (maturity report) before committing. Run find_state_references before renaming/removing a state path. To gate a whole feature/project in one call (the CI shape), use verify: it folds scenarios + maturity + reachability + optional model_check + drift + cross-feature event coherence + verified coverage into a single pass/warn/fail verdict (the in-chat form of the \`unspa check\` CLI). Use get_drift to find code that was audited against an older spec than the one now on disk. Cross-FEATURE safety properties (referencing state in different features) live as project.projectInvariants — author via add_project_invariant; verify --modelCheck enforces them. Verified coverage: after implementing, run the generated scenario spec and \`unspa coverage ingest\` to stamp actions "proven against code" (not just claimed); gate with verify minVerified / \`unspa check --min-verified\`.
 
-Behavioral index: when a repo is linked (.unspa.json present), the implementation map lives in that file. A Record<"type:id-or-path", {status, file, line, signature, auditedAt?, gitCommit?, specVersion?, kind?, relatedFiles?, testFile?, knownGaps?}>. Call get_behavioral_index to read the current map; call get_implementation_gaps to see what is missing, partial, or implemented relative to the spec. To update the index: use your file tools to write .unspa.json directly (you write it, the MCP only reads). After updating .unspa.json, call sync_from_index. It reads the index, resolves all UUIDs from the spec automatically, and posts a full report in one call. Prefer sync_from_index over the lower-level report_implementation_status_batch unless you need per-entity granularity. Staleness detection: compare entry.gitCommit vs "git log --format=%H -1 <file>" for file changes; compare entry.specVersion vs feature.updatedAt for spec drift.
+Behavioral index: when a repo is linked (.unspa.json present), the implementation map lives in that file. A Record<"type:id-or-path", {status, file, line, signature, auditedAt?, gitCommit?, specVersion?, kind?, relatedFiles?, testFile?, knownGaps?}>. Call get_behavioral_index to read the current map; call get_implementation_gaps to see what is missing, partial, or implemented relative to the spec. To update the index: use your file tools to write .unspa.json directly (you write it, the MCP only reads). After updating .unspa.json, call sync_from_index. It reads the index, resolves all UUIDs from the spec automatically, and posts a full report in one call. Prefer sync_from_index over the lower-level report_implementation_status_batch unless you need per-entity granularity. Staleness detection: compare entry.gitCommit vs "git log --format=%H -1 <file>" for file changes; for spec drift call get_drift (it compares each entry.specVersion vs the owning feature.updatedAt and returns the stale/unversioned/orphan buckets) instead of doing it by hand.
 
 IDs are opaque server-minted strings. Never invent them. Get them from list_*/get_* responses or apply_batch refs. save_feature is an escape hatch for full-replace edits; prefer apply_batch. All write ops return slim acks ({ok, featureId, updatedAt, id?}); re-read with get_action only when you need the new shape.
 
@@ -168,6 +170,7 @@ export const buildServer = (
   registerEffectTools(toolDeps);
   registerEventTools(toolDeps);
   registerInvariantTools(toolDeps);
+  registerReachabilityGoalTools(toolDeps);
   registerTransitionTools(toolDeps);
   registerPersonaTools(toolDeps);
   registerValueSetTools(toolDeps);
@@ -181,6 +184,7 @@ export const buildServer = (
   registerProjectTools(toolDeps);
   registerQueueTools(toolDeps);
   registerSpecGapsTool(toolDeps);
+  registerVerificationTools(toolDeps);
 
   server.registerResource(
     'feature',

package/mcp-server/sync-aware-repos.ts

@@ -1,79 +1,79 @@
-import type {
-  FeatureRepository,
-  FeatureSummary
-} from '../src/features/behavior-model/application/ports/FeatureRepository';
-import type { Feature } from '../src/features/behavior-model/domain/entities/Feature';
-import type { FeatureId } from '../src/features/behavior-model/domain/value-objects/ids';
-import type {
-  ProjectRepository,
-  ProjectSummary
-} from '../src/features/projects/application/ports/ProjectRepository';
-import type { Project } from '../src/features/projects/domain/entities/Project';
-import type { ProjectId } from '../src/features/projects/domain/value-objects/ids';
-import type { ImplementationStatusRepository } from '../src/features/implementation-status/application/ports/ImplementationStatusRepository';
-import type { ImplementationStatus } from '../src/features/implementation-status/domain/ImplementationStatus';
-import { notifySyncReload } from './sync-notifier';
-
-export class SyncAwareFeatureRepository implements FeatureRepository {
-  constructor(private readonly inner: FeatureRepository) {}
-  list(): Promise<readonly FeatureSummary[]> {
-    return this.inner.list();
-  }
-  get(id: FeatureId): Promise<Feature | null> {
-    return this.inner.get(id);
-  }
-  async save(feature: Feature): Promise<void> {
-    await this.inner.save(feature);
-    void notifySyncReload('feature', feature.id, { name: feature.name, op: 'save' });
-  }
-  async delete(id: FeatureId): Promise<void> {
-    // Capture the name BEFORE deleting so the toast can say "deleted feature
-    // 'Smoke Test'" instead of a bare id. One extra disk read per delete is
-    // a cheap price for readable activity logs.
-    const existing = await this.inner.get(id);
-    await this.inner.delete(id);
-    void notifySyncReload('feature', id, {
-      op: 'delete',
-      ...(existing?.name ? { name: existing.name } : {})
-    });
-  }
-}
-
-export class SyncAwareProjectRepository implements ProjectRepository {
-  constructor(private readonly inner: ProjectRepository) {}
-  list(): Promise<readonly ProjectSummary[]> {
-    return this.inner.list();
-  }
-  get(id: ProjectId): Promise<Project | null> {
-    return this.inner.get(id);
-  }
-  async save(project: Project): Promise<void> {
-    await this.inner.save(project);
-    void notifySyncReload('project', project.id, { name: project.name, op: 'save' });
-  }
-  async delete(id: ProjectId): Promise<void> {
-    const existing = await this.inner.get(id);
-    await this.inner.delete(id);
-    void notifySyncReload('project', id, {
-      op: 'delete',
-      ...(existing?.name ? { name: existing.name } : {})
-    });
-  }
-}
-
-export class SyncAwareImplementationStatusRepository
-  implements ImplementationStatusRepository
-{
-  constructor(private readonly inner: ImplementationStatusRepository) {}
-  get(id: FeatureId): Promise<ImplementationStatus | null> {
-    return this.inner.get(id);
-  }
-  async save(status: ImplementationStatus): Promise<void> {
-    await this.inner.save(status);
-    void notifySyncReload('implementation-status', status.featureId);
-  }
-  async delete(id: FeatureId): Promise<void> {
-    await this.inner.delete(id);
-    void notifySyncReload('implementation-status', id);
-  }
-}
+import type {
+  FeatureRepository,
+  FeatureSummary
+} from '../src/features/behavior-model/application/ports/FeatureRepository';
+import type { Feature } from '../src/features/behavior-model/domain/entities/Feature';
+import type { FeatureId } from '../src/features/behavior-model/domain/value-objects/ids';
+import type {
+  ProjectRepository,
+  ProjectSummary
+} from '../src/features/projects/application/ports/ProjectRepository';
+import type { Project } from '../src/features/projects/domain/entities/Project';
+import type { ProjectId } from '../src/features/projects/domain/value-objects/ids';
+import type { ImplementationStatusRepository } from '../src/features/implementation-status/application/ports/ImplementationStatusRepository';
+import type { ImplementationStatus } from '../src/features/implementation-status/domain/ImplementationStatus';
+import { notifySyncReload } from './sync-notifier';
+
+export class SyncAwareFeatureRepository implements FeatureRepository {
+  constructor(private readonly inner: FeatureRepository) {}
+  list(): Promise<readonly FeatureSummary[]> {
+    return this.inner.list();
+  }
+  get(id: FeatureId): Promise<Feature | null> {
+    return this.inner.get(id);
+  }
+  async save(feature: Feature): Promise<void> {
+    await this.inner.save(feature);
+    void notifySyncReload('feature', feature.id, { name: feature.name, op: 'save' });
+  }
+  async delete(id: FeatureId): Promise<void> {
+    // Capture the name BEFORE deleting so the toast can say "deleted feature
+    // 'Smoke Test'" instead of a bare id. One extra disk read per delete is
+    // a cheap price for readable activity logs.
+    const existing = await this.inner.get(id);
+    await this.inner.delete(id);
+    void notifySyncReload('feature', id, {
+      op: 'delete',
+      ...(existing?.name ? { name: existing.name } : {})
+    });
+  }
+}
+
+export class SyncAwareProjectRepository implements ProjectRepository {
+  constructor(private readonly inner: ProjectRepository) {}
+  list(): Promise<readonly ProjectSummary[]> {
+    return this.inner.list();
+  }
+  get(id: ProjectId): Promise<Project | null> {
+    return this.inner.get(id);
+  }
+  async save(project: Project): Promise<void> {
+    await this.inner.save(project);
+    void notifySyncReload('project', project.id, { name: project.name, op: 'save' });
+  }
+  async delete(id: ProjectId): Promise<void> {
+    const existing = await this.inner.get(id);
+    await this.inner.delete(id);
+    void notifySyncReload('project', id, {
+      op: 'delete',
+      ...(existing?.name ? { name: existing.name } : {})
+    });
+  }
+}
+
+export class SyncAwareImplementationStatusRepository
+  implements ImplementationStatusRepository
+{
+  constructor(private readonly inner: ImplementationStatusRepository) {}
+  get(id: FeatureId): Promise<ImplementationStatus | null> {
+    return this.inner.get(id);
+  }
+  async save(status: ImplementationStatus): Promise<void> {
+    await this.inner.save(status);
+    void notifySyncReload('implementation-status', status.featureId);
+  }
+  async delete(id: FeatureId): Promise<void> {
+    await this.inner.delete(id);
+    void notifySyncReload('implementation-status', id);
+  }
+}