npm - unspaghettit - Versions diffs - 0.2.0 → 0.4.0 - Mend

unspaghettit 0.2.0 → 0.4.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (772) hide show

package/src/app.css CHANGED Viewed

@@ -39,6 +39,199 @@ body {
   color: #0f172a;
 }
+/*
+ * ============================================================================
+ * Lyriks theme — opt-in cosmetic skin (gated by data-theme="lyriks" on <html>)
+ * ============================================================================
+ *
+ * Purely a re-colour of the design system: it overrides the `@theme` token
+ * *values* (the brand ramp + canvas/hairline), so every token-driven utility
+ * (bg-brand-*, text-brand-*, ring-brand-*, the avatar gradient, progress bars,
+ * focus rings, chips, ...) adopts the Lyriks violet identity without touching a
+ * single component. The header/shell *chrome* (the signature gradient bar) is
+ * applied in +layout.svelte via the same theme flag. Inert unless the attribute
+ * is present, so the default install is unaffected.
+ *
+ * `:root[data-theme='lyriks']` (specificity 0,2,0) wins over Tailwind's
+ * `@theme`-emitted `:root` (0,1,0), and custom properties inherit, so the
+ * overridden values cascade to every element.
+ *
+ * Tailwind v4 exposes the WHOLE default palette as CSS vars too (every utility
+ * compiles to `var(--color-<family>-<shade>)`). So re-skinning the families the
+ * app is built on — the neutral ramps (slate + neutral) and the cool accents it
+ * uses as the default teal/cyan brand (cyan/sky/teal) — restyles every surface,
+ * border, input, chip, table, and accent across the whole dashboard from this
+ * one block, with no component edits. The semantic status colours (amber,
+ * emerald, rose, red) are deliberately left alone so warnings/success/danger
+ * keep their meaning — matching the reference's amber/teal status rings.
+ */
+:root[data-theme='lyriks'] {
+  /* Brand ramp → violet. */
+  --color-brand-50: #f5f3ff;
+  --color-brand-100: #ede9fe;
+  --color-brand-200: #ddd6fe;
+  --color-brand-300: #c4b5fd;
+  --color-brand-400: #a78bfa;
+  --color-brand-500: #8b5cf6;
+  --color-brand-600: #7c3aed;
+  --color-brand-700: #6d28d9;
+  --color-brand-800: #5b21b6;
+  --color-brand-900: #4c1d95;
+  /* Brand wordmark switches to Space Grotesk (the reference's clean grotesk)
+   * instead of the default Dancing Script. `font-brand` resolves through this
+   * token, so the header wordmark restyles with no markup change. */
+  --font-brand: 'Space Grotesk', ui-sans-serif, system-ui, sans-serif;
+  /* App semantic surfaces. A clearly lavender canvas so the body — not just the
+   * header — reads as themed; white cards float on top of it. */
+  --color-canvas: #eeeafb;
+  --color-surface-soft: #e6dff7;
+  --color-surface-strong: #ddd4f1;
+  --color-hairline: #e0d8f1;
+  /* Neutral ramps (slate + neutral) → a cool lavender-tinted gray. The light
+   * end is pushed visibly violet so panels/rows/borders read as Lyriks; the
+   * mid tones keep enough darkness for text contrast; the dark shades become a
+   * deep violet-navy (matches the reference's chrome). Lightness tracks the
+   * originals so contrast holds. */
+  --color-slate-50: #f2eefc;
+  --color-slate-100: #e9e3f7;
+  --color-slate-200: #ddd4ee;
+  --color-slate-300: #c7bce0;
+  --color-slate-400: #948ab0;
+  --color-slate-500: #645c7e;
+  --color-slate-600: #4d4669;
+  --color-slate-700: #393353;
+  --color-slate-800: #261e3b;
+  --color-slate-900: #18122f;
+  --color-slate-950: #0d0822;
+  --color-neutral-50: #f2eefc;
+  --color-neutral-100: #e9e3f7;
+  --color-neutral-200: #ddd4ee;
+  --color-neutral-300: #c7bce0;
+  --color-neutral-400: #948ab0;
+  --color-neutral-500: #645c7e;
+  --color-neutral-600: #4d4669;
+  --color-neutral-700: #393353;
+  --color-neutral-800: #261e3b;
+  --color-neutral-900: #18122f;
+  --color-neutral-950: #0d0822;
+  /* Cool accents the app uses as its default brand (cyan/sky/teal) → violet,
+   * so no teal/blue pockets survive next to the new violet primary. */
+  --color-cyan-50: #f5f3ff;
+  --color-cyan-100: #ede9fe;
+  --color-cyan-200: #ddd6fe;
+  --color-cyan-300: #c4b5fd;
+  --color-cyan-400: #a78bfa;
+  --color-cyan-500: #8b5cf6;
+  --color-cyan-600: #7c3aed;
+  --color-cyan-700: #6d28d9;
+  --color-cyan-800: #5b21b6;
+  --color-cyan-900: #4c1d95;
+  --color-cyan-950: #2e1065;
+  --color-sky-50: #f5f3ff;
+  --color-sky-100: #ede9fe;
+  --color-sky-200: #ddd6fe;
+  --color-sky-300: #c4b5fd;
+  --color-sky-400: #a78bfa;
+  --color-sky-500: #8b5cf6;
+  --color-sky-600: #7c3aed;
+  --color-sky-700: #6d28d9;
+  --color-sky-800: #5b21b6;
+  --color-sky-900: #4c1d95;
+  --color-sky-950: #2e1065;
+  --color-teal-50: #f5f3ff;
+  --color-teal-100: #ede9fe;
+  --color-teal-200: #ddd6fe;
+  --color-teal-300: #c4b5fd;
+  --color-teal-400: #a78bfa;
+  --color-teal-500: #8b5cf6;
+  --color-teal-600: #7c3aed;
+  --color-teal-700: #6d28d9;
+  --color-teal-800: #5b21b6;
+  --color-teal-900: #4c1d95;
+  --color-teal-950: #2e1065;
+}
+/* Cover the bare <html>/<body> backdrop (set outside the theme system above
+ * and via the body's `bg-neutral-50` utility) so edges match the cool canvas. */
+:root[data-theme='lyriks'],
+:root[data-theme='lyriks'] body {
+  background: var(--color-canvas);
+}
+/* Re-tint the navigateTo focus pulse to the violet brand so it matches. */
+@keyframes focus-flash-lyriks {
+  0% {
+    box-shadow: 0 0 0 0 rgba(124, 58, 237, 0.55);
+    background-color: rgba(237, 233, 254, 0.65);
+  }
+  8% {
+    box-shadow: 0 0 0 6px rgba(124, 58, 237, 0.3);
+    background-color: rgba(237, 233, 254, 0.55);
+  }
+  /* Hold a visible ring + tint through most of the animation so the target
+     stays obvious after the scroll lands, then fade out at the end. */
+  75% {
+    box-shadow: 0 0 0 4px rgba(124, 58, 237, 0.22);
+    background-color: rgba(237, 233, 254, 0.4);
+  }
+  100% {
+    box-shadow: 0 0 0 0 rgba(124, 58, 237, 0);
+    background-color: transparent;
+  }
+}
+:root[data-theme='lyriks'] .focus-flash {
+  animation-name: focus-flash-lyriks;
+}
+/*
+ * Emphasis colour. Primary buttons and active toggles across the app use a
+ * near-black `slate-900` surface (with a `slate-800` hover) as the "emphasis"
+ * colour — separate from the brand. Under Lyriks the brand IS the emphasis
+ * colour, so remap the SOLID dark button/active/border surfaces (and their
+ * hovers) to violet; otherwise primary CTAs read as leftover black buttons.
+ *
+ * We target the utility CLASSES, not the `--color-slate-*` variables, on
+ * purpose: the same slate-900 token is the body-text colour (`text-slate-900`),
+ * which must stay dark. Translucent scrims (`bg-slate-900/40`, …) and the
+ * builder's dark canvas gradients keep their own class names and are
+ * intentionally left as deep violet-navy.
+ */
+:root[data-theme='lyriks'] .bg-slate-900,
+:root[data-theme='lyriks'] .bg-slate-950,
+:root[data-theme='lyriks'] .bg-neutral-900,
+:root[data-theme='lyriks'] .bg-neutral-950 {
+  background-color: var(--color-brand-600);
+}
+:root[data-theme='lyriks'] .bg-slate-800 {
+  background-color: var(--color-brand-700);
+}
+:root[data-theme='lyriks'] .border-slate-900 {
+  border-color: var(--color-brand-600);
+}
+:root[data-theme='lyriks'] .hover\:bg-slate-900:hover,
+:root[data-theme='lyriks'] .hover\:bg-slate-800:hover {
+  background-color: var(--color-brand-700);
+}
+:root[data-theme='lyriks'] .hover\:bg-slate-700:hover {
+  background-color: var(--color-brand-600);
+}
+/*
+ * Card top-accent flourish. Project + feature cards paint a thin
+ * `from-brand-500 via-brand-mint to-violet-400` bar across the top; the mint
+ * (teal) middle stop is a fixed accent token we leave alone elsewhere (tags use
+ * that palette), so it survives the remap and clashes with Lyriks. Re-skin just
+ * this flourish to echo the header's violet→fuchsia→pink sweep. `.via-brand-mint`
+ * is unique to these accent bars, so the override is precise.
+ */
+:root[data-theme='lyriks'] .via-brand-mint {
+  background-image: linear-gradient(to right, #6d28d9, #a21caf, #db2777);
+}
 /*
  * Restore `cursor: pointer` on interactive elements.
  *
@@ -75,25 +268,31 @@ body {
 }
 /*
- * Pulses a brief project-accent ring + soft fill on whatever element is being
- * focused via editorStore.navigateTo. Triggered by adding the
- * `.focus-flash` class for ~1.6s.
+ * Pulses a project-accent ring + soft fill on whatever element is being
+ * focused via editorStore.navigateTo or a global-search result. Triggered by
+ * adding the `.focus-flash` class; holds for ~3s (kept in sync with
+ * FOCUS_FLASH_MS in FeatureEditor) so the searched item stays obvious.
  */
 @keyframes focus-flash {
   0% {
-    box-shadow: 0 0 0 0 rgba(8, 145, 178, 0.5);
+    box-shadow: 0 0 0 0 rgba(8, 145, 178, 0.55);
+    background-color: rgba(207, 250, 254, 0.6);
+  }
+  8% {
+    box-shadow: 0 0 0 6px rgba(8, 145, 178, 0.3);
     background-color: rgba(207, 250, 254, 0.55);
   }
-  60% {
-    box-shadow: 0 0 0 8px rgba(8, 145, 178, 0);
-    background-color: rgba(207, 250, 254, 0.25);
+  /* Hold the ring + tint through most of the animation, then fade at the end. */
+  75% {
+    box-shadow: 0 0 0 4px rgba(8, 145, 178, 0.22);
+    background-color: rgba(207, 250, 254, 0.4);
   }
   100% {
-    box-shadow: 0 0 0 0 rgba(124, 58, 237, 0);
+    box-shadow: 0 0 0 0 rgba(8, 145, 178, 0);
     background-color: transparent;
   }
 }
 .focus-flash {
-  animation: focus-flash 1.6s ease-out;
+  animation: focus-flash 3s ease-out;
   border-radius: 0.5rem;
 }

package/src/app.html CHANGED Viewed

@@ -1,8 +1,22 @@
 <!doctype html>
-<html lang="en" class="h-full">
+<html lang="en" class="h-full" data-theme="%unspa.theme%">
   <head>
     <meta charset="utf-8" />
     <meta name="viewport" content="width=device-width, initial-scale=1" />
+    <!--
+      Theme bootstrap. The server fills the data-theme placeholder above from
+      PUBLIC_UNSPA_THEME (the CLI default) in hooks.server.ts. This runs before
+      first paint and lets a saved in-app switcher choice (localStorage) win
+      over that default, so the page never flashes the wrong colour skin. Kept
+      tiny + guarded so a blocked storage API (private browsing) just leaves
+      the server default.
+    -->
+    <script>
+      try {
+        var t = localStorage.getItem('unspa.theme');
+        if (t) document.documentElement.dataset.theme = t;
+      } catch (e) {}
+    </script>
     <link rel="icon" href="%sveltekit.assets%/unspaghettit_logo.png" type="image/png" />
     <meta name="description" content="Executable specifications for AI-assisted software development. Local-first and MCP-native by Lyriks.io." />
     <meta property="og:title" content="Unspaghettit" />

package/src/features/behavior-model/application/ports/FeatureRepository.ts CHANGED Viewed

@@ -1,21 +1,21 @@
 import type { Feature } from '$features/behavior-model/domain/entities/Feature';
 import type { Tag } from '$shared/domain/Tags';
-import type { FeatureId } from '$features/behavior-model/domain/value-objects/ids';
-export type FeatureSummary = {
-  readonly id: FeatureId;
+import type { FeatureId } from '$features/behavior-model/domain/value-objects/ids';
+export type FeatureSummary = {
+  readonly id: FeatureId;
   readonly name: string;
   readonly description?: string;
   readonly tags?: readonly Tag[];
-  readonly surfaceCount: number;
-  readonly actionCount: number;
-  readonly createdAt: string;
-  readonly updatedAt: string;
-};
-export interface FeatureRepository {
-  list(): Promise<readonly FeatureSummary[]>;
-  get(id: FeatureId): Promise<Feature | null>;
-  save(feature: Feature): Promise<void>;
-  delete(id: FeatureId): Promise<void>;
-}
+  readonly surfaceCount: number;
+  readonly actionCount: number;
+  readonly createdAt: string;
+  readonly updatedAt: string;
+};
+export interface FeatureRepository {
+  list(): Promise<readonly FeatureSummary[]>;
+  get(id: FeatureId): Promise<Feature | null>;
+  save(feature: Feature): Promise<void>;
+  delete(id: FeatureId): Promise<void>;
+}

package/src/features/behavior-model/application/use-cases/CreateFeature.ts CHANGED Viewed

@@ -1,24 +1,24 @@
-import type { Clock } from '$shared/domain/Clock';
-import type { IdGenerator } from '$shared/domain/IdGenerator';
+import type { Clock } from '$shared/domain/Clock';
+import type { IdGenerator } from '$shared/domain/IdGenerator';
 import type { Feature } from '$features/behavior-model/domain/entities/Feature';
 import { asFeatureId } from '$features/behavior-model/domain/value-objects/ids';
 import type { Tag } from '$shared/domain/Tags';
 import { normalizeTags } from '$shared/domain/Tags';
 import type { FeatureRepository } from '../ports/FeatureRepository';
-export type CreateFeatureInput = {
+export type CreateFeatureInput = {
   readonly name: string;
   readonly description?: string;
   readonly tags?: readonly Tag[];
-};
-export const createFeatureUseCase = (deps: {
-  repository: FeatureRepository;
-  ids: IdGenerator;
-  clock: Clock;
-}) => {
-  return async (input: CreateFeatureInput): Promise<Feature> => {
-    const trimmedName = input.name.trim();
+};
+export const createFeatureUseCase = (deps: {
+  repository: FeatureRepository;
+  ids: IdGenerator;
+  clock: Clock;
+}) => {
+  return async (input: CreateFeatureInput): Promise<Feature> => {
+    const trimmedName = input.name.trim();
     if (trimmedName.length === 0) {
       throw new Error('Feature name is required');
     }
@@ -33,14 +33,14 @@ export const createFeatureUseCase = (deps: {
       description: trimmedDescription,
       ...(normalizeTags(input.tags) ? { tags: normalizeTags(input.tags) } : {}),
       surfaces: [],
-      personas: [],
-      resources: [],
-      entities: [],
-      events: [],
-      createdAt: now,
-      updatedAt: now
-    };
-    await deps.repository.save(feature);
-    return feature;
-  };
-};
+      personas: [],
+      resources: [],
+      entities: [],
+      events: [],
+      createdAt: now,
+      updatedAt: now
+    };
+    await deps.repository.save(feature);
+    return feature;
+  };
+};

package/src/features/behavior-model/application/use-cases/DeleteFeature.ts CHANGED Viewed

@@ -1,8 +1,8 @@
-import type { FeatureId } from '$features/behavior-model/domain/value-objects/ids';
-import type { FeatureRepository } from '../ports/FeatureRepository';
-export const deleteFeatureUseCase = (deps: { repository: FeatureRepository }) => {
-  return async (id: FeatureId): Promise<void> => {
-    await deps.repository.delete(id);
-  };
-};
+import type { FeatureId } from '$features/behavior-model/domain/value-objects/ids';
+import type { FeatureRepository } from '../ports/FeatureRepository';
+export const deleteFeatureUseCase = (deps: { repository: FeatureRepository }) => {
+  return async (id: FeatureId): Promise<void> => {
+    await deps.repository.delete(id);
+  };
+};

package/src/features/behavior-model/application/use-cases/GetFeature.ts CHANGED Viewed

@@ -1,9 +1,9 @@
-import type { Feature } from '$features/behavior-model/domain/entities/Feature';
-import type { FeatureId } from '$features/behavior-model/domain/value-objects/ids';
-import type { FeatureRepository } from '../ports/FeatureRepository';
-export const getFeatureUseCase = (deps: { repository: FeatureRepository }) => {
-  return async (id: FeatureId): Promise<Feature | null> => {
-    return deps.repository.get(id);
-  };
-};
+import type { Feature } from '$features/behavior-model/domain/entities/Feature';
+import type { FeatureId } from '$features/behavior-model/domain/value-objects/ids';
+import type { FeatureRepository } from '../ports/FeatureRepository';
+export const getFeatureUseCase = (deps: { repository: FeatureRepository }) => {
+  return async (id: FeatureId): Promise<Feature | null> => {
+    return deps.repository.get(id);
+  };
+};

package/src/features/behavior-model/application/use-cases/ListFeatures.ts CHANGED Viewed

@@ -1,10 +1,10 @@
-import type {
-  FeatureRepository,
-  FeatureSummary
-} from '../ports/FeatureRepository';
-export const listFeaturesUseCase = (deps: { repository: FeatureRepository }) => {
-  return async (): Promise<readonly FeatureSummary[]> => {
-    return deps.repository.list();
-  };
-};
+import type {
+  FeatureRepository,
+  FeatureSummary
+} from '../ports/FeatureRepository';
+export const listFeaturesUseCase = (deps: { repository: FeatureRepository }) => {
+  return async (): Promise<readonly FeatureSummary[]> => {
+    return deps.repository.list();
+  };
+};

package/src/features/behavior-model/application/use-cases/MutateFeature.ts CHANGED Viewed

@@ -1,90 +1,90 @@
-import type { Clock } from '$shared/domain/Clock';
-import type { Feature } from '$features/behavior-model/domain/entities/Feature';
-import type { FeatureId } from '$features/behavior-model/domain/value-objects/ids';
-import { normalizeFeatureEmittedEvents } from '$features/behavior-model/domain/services/FeatureEmittedEventsNormalizer';
-import { normalizeFeatureExpressions } from '$features/behavior-model/domain/services/FeatureExpressionNormalizer';
-import { normalizeFeatureSharedState } from '$features/behavior-model/domain/services/FeatureSharedStateNormalizer';
-import { introducedValidationErrors } from '$features/behavior-model/domain/services/FeatureValidator';
-import type { FeatureRepository } from '../ports/FeatureRepository';
-/** The shared normalization pipeline applied before validation + save. */
-const normalizeForSave = (feature: Feature): Feature =>
-  normalizeFeatureSharedState(
-    normalizeFeatureEmittedEvents(normalizeFeatureExpressions(feature))
-  );
-export type FeatureTransform = (feature: Feature) => Feature;
-export class FeatureValidationError extends Error {
-  constructor(
-    message: string,
-    public readonly errors: readonly string[]
-  ) {
-    super(message);
-    this.name = 'FeatureValidationError';
-  }
-}
-export class FeatureNotFoundError extends Error {
-  constructor(featureId: string) {
-    super(`Feature ${featureId} not found`);
-    this.name = 'FeatureNotFoundError';
-  }
-}
-/**
- * Generic mutate-then-save use case. Loads an feature by id, applies a
- * pure transform, validates the result for structural integrity, then
- * persists it. Used by every granular MCP write tool so they share one
- * load/validate/save loop.
- *
- * Throws `FeatureNotFoundError` if no feature matches the id, or
- * `FeatureValidationError` if the transformed feature fails
- * structural validation. Either error must be surfaced to the caller; the
- * snapshot is left untouched in both cases.
- */
-export const mutateFeatureUseCase = (deps: {
-  repository: FeatureRepository;
-  clock: Clock;
-}) => {
-  return async (input: {
-    featureId: FeatureId;
-    transform: FeatureTransform;
-  }): Promise<Feature> => {
-    const current = await deps.repository.get(input.featureId);
-    if (!current) throw new FeatureNotFoundError(input.featureId);
-    // Normalize Expression trees before validation so downstream consumers
-    // (validators, scorer, evaluator) can assume well-formed children. JSON
-    // authoring lets raw scalars land inside Expression bodies where the type
-    // demands an Expression node; this rewrites them as {kind:"literal",value}.
-    // Then mirror every emit_event effect into action.emittedEvents so the
-    // scorer's "event declarations" check passes without forcing an extra
-    // update_action op from the caller.
-    // Rule-category normalization runs ONLY at import (FeatureJson) and on
-    // save_feature, not on writes. That way `category: "permission"` from
-    // the LLM hits the strict validator and gets a "did you mean..." error
-    // instead of being silently remapped, fresh authoring learns the
-    // canonical vocabulary on the next call. Legacy snapshots still load.
-    const transformed = normalizeForSave(input.transform(current));
-    // Diff-aware gate (both structural AND reference-integrity): block the
-    // write only when it INTRODUCES a new error. Pre-existing problems on a
-    // partially-built feature — most commonly descriptions not yet filled in —
-    // stay editable, so you can set a description (or any field) without the
-    // whole feature already being valid. The baseline is normalized the same
-    // way as `transformed` so normalization artifacts on untouched elements
-    // don't read as introduced. See introducedValidationErrors for the why.
-    const introduced = introducedValidationErrors(normalizeForSave(current), transformed);
-    if (introduced.length > 0) {
-      throw new FeatureValidationError(
-        'The requested change would introduce new validation errors. (Pre-existing issues elsewhere in the feature are not blocking — fix them whenever; they show up in get_spec_gaps / score_feature.)',
-        introduced
-      );
-    }
-    const next: Feature = { ...transformed, updatedAt: deps.clock() };
-    await deps.repository.save(next);
-    return next;
-  };
-};
+import type { Clock } from '$shared/domain/Clock';
+import type { Feature } from '$features/behavior-model/domain/entities/Feature';
+import type { FeatureId } from '$features/behavior-model/domain/value-objects/ids';
+import { normalizeFeatureEmittedEvents } from '$features/behavior-model/domain/services/FeatureEmittedEventsNormalizer';
+import { normalizeFeatureExpressions } from '$features/behavior-model/domain/services/FeatureExpressionNormalizer';
+import { normalizeFeatureSharedState } from '$features/behavior-model/domain/services/FeatureSharedStateNormalizer';
+import { introducedValidationErrors } from '$features/behavior-model/domain/services/FeatureValidator';
+import type { FeatureRepository } from '../ports/FeatureRepository';
+/** The shared normalization pipeline applied before validation + save. */
+const normalizeForSave = (feature: Feature): Feature =>
+  normalizeFeatureSharedState(
+    normalizeFeatureEmittedEvents(normalizeFeatureExpressions(feature))
+  );
+export type FeatureTransform = (feature: Feature) => Feature;
+export class FeatureValidationError extends Error {
+  constructor(
+    message: string,
+    public readonly errors: readonly string[]
+  ) {
+    super(message);
+    this.name = 'FeatureValidationError';
+  }
+}
+export class FeatureNotFoundError extends Error {
+  constructor(featureId: string) {
+    super(`Feature ${featureId} not found`);
+    this.name = 'FeatureNotFoundError';
+  }
+}
+/**
+ * Generic mutate-then-save use case. Loads an feature by id, applies a
+ * pure transform, validates the result for structural integrity, then
+ * persists it. Used by every granular MCP write tool so they share one
+ * load/validate/save loop.
+ *
+ * Throws `FeatureNotFoundError` if no feature matches the id, or
+ * `FeatureValidationError` if the transformed feature fails
+ * structural validation. Either error must be surfaced to the caller; the
+ * snapshot is left untouched in both cases.
+ */
+export const mutateFeatureUseCase = (deps: {
+  repository: FeatureRepository;
+  clock: Clock;
+}) => {
+  return async (input: {
+    featureId: FeatureId;
+    transform: FeatureTransform;
+  }): Promise<Feature> => {
+    const current = await deps.repository.get(input.featureId);
+    if (!current) throw new FeatureNotFoundError(input.featureId);
+    // Normalize Expression trees before validation so downstream consumers
+    // (validators, scorer, evaluator) can assume well-formed children. JSON
+    // authoring lets raw scalars land inside Expression bodies where the type
+    // demands an Expression node; this rewrites them as {kind:"literal",value}.
+    // Then mirror every emit_event effect into action.emittedEvents so the
+    // scorer's "event declarations" check passes without forcing an extra
+    // update_action op from the caller.
+    // Rule-category normalization runs ONLY at import (FeatureJson) and on
+    // save_feature, not on writes. That way `category: "permission"` from
+    // the LLM hits the strict validator and gets a "did you mean..." error
+    // instead of being silently remapped, fresh authoring learns the
+    // canonical vocabulary on the next call. Legacy snapshots still load.
+    const transformed = normalizeForSave(input.transform(current));
+    // Diff-aware gate (both structural AND reference-integrity): block the
+    // write only when it INTRODUCES a new error. Pre-existing problems on a
+    // partially-built feature — most commonly descriptions not yet filled in —
+    // stay editable, so you can set a description (or any field) without the
+    // whole feature already being valid. The baseline is normalized the same
+    // way as `transformed` so normalization artifacts on untouched elements
+    // don't read as introduced. See introducedValidationErrors for the why.
+    const introduced = introducedValidationErrors(normalizeForSave(current), transformed);
+    if (introduced.length > 0) {
+      throw new FeatureValidationError(
+        'The requested change would introduce new validation errors. (Pre-existing issues elsewhere in the feature are not blocking — fix them whenever; they show up in get_spec_gaps / score_feature.)',
+        introduced
+      );
+    }
+    const next: Feature = { ...transformed, updatedAt: deps.clock() };
+    await deps.repository.save(next);
+    return next;
+  };
+};