@inharness-ai/claude4spec 1.0.20 → 1.0.22

package/dist/server/core/plugin-host/registry.js

@@ -3,24 +3,129 @@
  * singleton — the registry is immutable after `registerAllPlugins(registry)`
  * runs at process start, and `consolidate(config.entities)` is a pure factory
  * producing one ProjectPluginHost per project context.
+ *
+ * M33: the base layer is no longer process-immutable — the hot-reload
+ * pipeline mutates it via `registerPlugin` / `unregisterPlugin` and then
+ * invalidates dependent `ProjectContext`s (axis B). The registry additionally
+ * retains a per-plugin {@link RegisteredPluginRecord} so the host can surface
+ * non-entity capabilities (settings/commands) and the reload pipeline can call
+ * the old version's `onUnregister` before re-registering.
  */
 import { ProjectPluginHostImpl } from './project-host.js';
+import { PluginManifestError, lowerEntityContribution, validateWritingStyle, } from './manifest-adapter.js';
 export class PluginRegistryImpl {
     modules = new Map();
+    // M33: base-layer plugins by name, in registration order. The source
+    // of truth for `listWritingStyles` / `listPluginRecords` so a hot-reload that
+    // calls `unregisterPlugin` cleanly drops the old version's styles too.
+    plugins = new Map();
     registerEntityModule(module) {
         if (!module.type) {
             throw new Error('plugin-registry: module.type is required');
         }
         this.modules.set(module.type, module);
     }
+    /**
+     * Validate a manifest's shape and lower every contribution WITHOUT mutating
+     * the registry. Throws `PluginManifestError` on any structural problem (the
+     * loader/reload pipeline catches it). The hot-reload pipeline calls this
+     * BEFORE tearing the old version down, so a structurally-broken new version
+     * never leaves the pool missing a type ("old stays").
+     */
+    validateAndLower(manifest) {
+        if (!manifest || typeof manifest !== 'object') {
+            throw new PluginManifestError('plugin manifest must be an object');
+        }
+        if (typeof manifest.name !== 'string' || typeof manifest.version !== 'string') {
+            throw new PluginManifestError('plugin manifest requires string name + version');
+        }
+        if (manifest.contributes == null || typeof manifest.contributes !== 'object') {
+            throw new PluginManifestError(`plugin "${manifest.name}" — contributes must be an object`);
+        }
+        // Two-pass for atomicity: lower (validate) every contribution first, so a
+        // throw on a later entity/style never leaves earlier ones registered.
+        const entityModules = (manifest.contributes.entities ?? []).map(lowerEntityContribution);
+        const styles = (manifest.contributes.writingStyles ?? []).map(validateWritingStyle);
+        // `onUnregister` is a required slot from the HOST_API 1.0.0 baseline. A
+        // runtime manifest missing it is not crashed over — warn (parity with L8
+        // slot validation) and substitute a no-op so the reload pipeline still works.
+        let onUnregister;
+        if (typeof manifest.onUnregister === 'function') {
+            onUnregister = () => manifest.onUnregister();
+        }
+        else {
+            console.warn(`[plugin-registry] plugin "${manifest.name}" — required slot onUnregister is missing; using a no-op teardown`);
+            onUnregister = () => { };
+        }
+        const settings = manifest.contributes.settings ?? [];
+        const commands = manifest.contributes.commands ?? [];
+        return {
+            record: {
+                name: manifest.name,
+                version: manifest.version,
+                contributedTypes: entityModules.map((m) => m.type),
+                settings,
+                commands,
+                styles,
+                entityModules,
+                onUnregister,
+            },
+        };
+    }
+    validatePlugin(manifest) {
+        this.validateAndLower(manifest);
+    }
+    registerPlugin(manifest) {
+        const { record } = this.validateAndLower(manifest);
+        for (const module of record.entityModules) {
+            this.registerEntityModule(module);
+        }
+        // Re-registration (hot-reload) overwrites the prior record; Map keeps the
+        // first-seen insertion order, which is what we want for stable section order.
+        this.plugins.set(record.name, record);
+    }
+    unregisterPlugin(name) {
+        const record = this.plugins.get(name);
+        if (!record)
+            return;
+        try {
+            record.onUnregister();
+        }
+        catch (err) {
+            // Idempotent + non-throwing by contract — a throw is a warning, never a block.
+            console.warn(`[plugin-registry] onUnregister of "${name}" threw: ${err.message}`);
+        }
+        for (const module of record.entityModules) {
+            // Only drop the module if it is STILL the one this plugin contributed — a
+            // later same-typed registration (another base plugin contributing the same
+            // type) would have overwritten the slot, and must not be clobbered here.
+            if (this.modules.get(module.type) === module) {
+                this.modules.delete(module.type);
+            }
+        }
+        this.plugins.delete(name);
+    }
+    listPluginRecords() {
+        return Array.from(this.plugins.values()).map((r) => ({
+            name: r.name,
+            version: r.version,
+            contributedTypes: [...r.contributedTypes],
+            settings: r.settings,
+            commands: r.commands,
+            onUnregister: r.onUnregister,
+        }));
+    }
+    listWritingStyles() {
+        return Array.from(this.plugins.values()).flatMap((r) => r.styles);
+    }
     listAvailable() {
         return Array.from(this.modules.values()).sort((a, b) => a.displayOrder - b.displayOrder);
     }
     getAvailable(type) {
         return this.modules.get(type) ?? null;
     }
-    consolidate(activeWhitelist) {
-        return new ProjectPluginHostImpl(this, activeWhitelist);
+    consolidate(config, overlay) {
+        return new ProjectPluginHostImpl(this, config?.entities, overlay);
     }
 }
 //# sourceMappingURL=registry.js.map

package/dist/server/core/plugin-host/registry.js.map

@@ -1 +1 @@
-{"version":3,"file":"registry.js","sourceRoot":"","sources":["../../../../src/server/core/plugin-host/registry.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAGH,OAAO,EAAE,qBAAqB,EAAE,MAAM,mBAAmB,CAAC;AAE1D,MAAM,OAAO,kBAAkB;IACrB,OAAO,GAAG,IAAI,GAAG,EAAyB,CAAC;IAEnD,oBAAoB,CAAC,MAAqB;QACxC,IAAI,CAAC,MAAM,CAAC,IAAI,EAAE,CAAC;YACjB,MAAM,IAAI,KAAK,CAAC,0CAA0C,CAAC,CAAC;QAC9D,CAAC;QACD,IAAI,CAAC,OAAO,CAAC,GAAG,CAAC,MAAM,CAAC,IAAI,EAAE,MAAM,CAAC,CAAC;IACxC,CAAC;IAED,aAAa;QACX,OAAO,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,OAAO,CAAC,MAAM,EAAE,CAAC,CAAC,IAAI,CAC3C,CAAC,CAAC,EAAE,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,YAAY,GAAG,CAAC,CAAC,YAAY,CAC1C,CAAC;IACJ,CAAC;IAED,YAAY,CAAC,IAAY;QACvB,OAAO,IAAI,CAAC,OAAO,CAAC,GAAG,CAAC,IAAI,CAAC,IAAI,IAAI,CAAC;IACxC,CAAC;IAED,WAAW,CAAC,eAA4C;QACtD,OAAO,IAAI,qBAAqB,CAAC,IAAI,EAAE,eAAe,CAAC,CAAC;IAC1D,CAAC;CACF"}
+{"version":3,"file":"registry.js","sourceRoot":"","sources":["../../../../src/server/core/plugin-host/registry.ts"],"names":[],"mappings":"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"}

package/dist/server/core/plugin-host/runtime-shims.d.ts

@@ -0,0 +1,26 @@
+/**
+ * M33 "Option B" shared-singleton shims.
+ *
+ * The host publishes its OWN already-imported module namespaces onto
+ * `window.__c4s_shared` (see client `shared-runtime.ts`). The import map points
+ * each bare peer specifier at one of these tiny server-served ESM modules, which
+ * re-export from that global. A plugin's `import "react"` therefore resolves to
+ * the host's live React reconciler — not a second copy.
+ *
+ * The named-export list per peer is enumerated from the actually-installed
+ * package at runtime (cached), so the shim never drifts from the host's exports
+ * — avoiding a brittle hand-maintained list. `@c4s/plugin-runtime` is our own
+ * fixed surface (and a browser module the server can't import), so it is listed
+ * explicitly.
+ */
+import type { SharedPeerSpecifier } from '../../../shared/plugin-host/frontend-manifest.js';
+/** Bare specifier → URL slug used in `/api/plugins/runtime/<slug>.js`. */
+export declare const PEER_SLUG: Record<SharedPeerSpecifier, string>;
+/** Build the import map injected into the page. Bare specifier → shim URL. */
+export declare function buildImportMap(): Record<string, string>;
+/**
+ * Render (and cache) the ESM shim for one runtime slug. Returns `null` for an
+ * unknown slug. Never throws — a peer whose package can't be introspected
+ * server-side falls back to a default-only shim.
+ */
+export declare function getRuntimeShim(slug: string): Promise<string | null>;

package/dist/server/core/plugin-host/runtime-shims.js

@@ -0,0 +1,96 @@
+/**
+ * M33 "Option B" shared-singleton shims.
+ *
+ * The host publishes its OWN already-imported module namespaces onto
+ * `window.__c4s_shared` (see client `shared-runtime.ts`). The import map points
+ * each bare peer specifier at one of these tiny server-served ESM modules, which
+ * re-export from that global. A plugin's `import "react"` therefore resolves to
+ * the host's live React reconciler — not a second copy.
+ *
+ * The named-export list per peer is enumerated from the actually-installed
+ * package at runtime (cached), so the shim never drifts from the host's exports
+ * — avoiding a brittle hand-maintained list. `@c4s/plugin-runtime` is our own
+ * fixed surface (and a browser module the server can't import), so it is listed
+ * explicitly.
+ */
+import { SHARED_PEER_SPECIFIERS, PLUGIN_RUNTIME_EXPORT_NAMES, PLUGIN_RUNTIME_UI_EXPORT_NAMES, } from '../../../shared/plugin-host/frontend-manifest.js';
+/** Bare specifier → URL slug used in `/api/plugins/runtime/<slug>.js`. */
+export const PEER_SLUG = {
+    react: 'react',
+    'react/jsx-runtime': 'react-jsx-runtime',
+    'react/jsx-dev-runtime': 'react-jsx-dev-runtime',
+    'react-dom': 'react-dom',
+    'react-dom/client': 'react-dom-client',
+    '@tiptap/core': 'tiptap-core',
+    '@tanstack/react-query': 'react-query',
+    '@tanstack/react-router': 'react-router',
+    '@c4s/plugin-runtime': 'plugin-runtime',
+    '@c4s/plugin-runtime/ui': 'plugin-runtime-ui',
+};
+const SLUG_PEER = Object.fromEntries(SHARED_PEER_SPECIFIERS.map((spec) => [PEER_SLUG[spec], spec]));
+/**
+ * The named exports of our own client surfaces — browser modules the server
+ * can't introspect. Single source of truth lives in shared; parity tests
+ * (plugin-runtime.test.ts, plugin-runtime-ui.test.ts) guard them against drift.
+ */
+const PLUGIN_RUNTIME_EXPORTS = PLUGIN_RUNTIME_EXPORT_NAMES;
+const PLUGIN_RUNTIME_UI_EXPORTS = PLUGIN_RUNTIME_UI_EXPORT_NAMES;
+/** Build the import map injected into the page. Bare specifier → shim URL. */
+export function buildImportMap() {
+    const map = {};
+    for (const spec of SHARED_PEER_SPECIFIERS) {
+        map[spec] = `/api/plugins/runtime/${PEER_SLUG[spec]}.js`;
+    }
+    return map;
+}
+const ID_RE = /^[A-Za-z_$][A-Za-z0-9_$]*$/;
+function renderShimSource(specifier, names) {
+    const accessor = `globalThis.__c4s_shared[${JSON.stringify(specifier)}]`;
+    const lines = [
+        `// Auto-generated host singleton shim for "${specifier}".`,
+        `const __m = ${accessor};`,
+        `if (!__m) throw new Error('c4s plugin-runtime: missing shared singleton "${specifier}" — host did not publish window.__c4s_shared');`,
+        `export default (__m && __m.default !== undefined ? __m.default : __m);`,
+    ];
+    for (const name of names) {
+        if (name === 'default' || name === '__esModule' || !ID_RE.test(name))
+            continue;
+        lines.push(`export const ${name} = __m[${JSON.stringify(name)}];`);
+    }
+    return lines.join('\n') + '\n';
+}
+const shimCache = new Map();
+/**
+ * Render (and cache) the ESM shim for one runtime slug. Returns `null` for an
+ * unknown slug. Never throws — a peer whose package can't be introspected
+ * server-side falls back to a default-only shim.
+ */
+export async function getRuntimeShim(slug) {
+    const cached = shimCache.get(slug);
+    if (cached)
+        return cached;
+    const specifier = SLUG_PEER[slug];
+    if (!specifier)
+        return null;
+    let names;
+    if (specifier === '@c4s/plugin-runtime') {
+        names = [...PLUGIN_RUNTIME_EXPORTS];
+    }
+    else if (specifier === '@c4s/plugin-runtime/ui') {
+        names = [...PLUGIN_RUNTIME_UI_EXPORTS];
+    }
+    else {
+        try {
+            const ns = (await import(specifier));
+            names = Object.keys(ns);
+        }
+        catch (err) {
+            console.warn(`[plugin-runtime] could not introspect "${specifier}" for shim exports: ${err.message}`);
+            names = [];
+        }
+    }
+    const source = renderShimSource(specifier, names);
+    shimCache.set(slug, source);
+    return source;
+}
+//# sourceMappingURL=runtime-shims.js.map

package/dist/server/core/plugin-host/runtime-shims.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"runtime-shims.js","sourceRoot":"","sources":["../../../../src/server/core/plugin-host/runtime-shims.ts"],"names":[],"mappings":"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"}

package/dist/server/core/plugin-host/types.d.ts

@@ -10,6 +10,7 @@ import type { Database } from 'better-sqlite3';
 import type { Router } from 'express';
 import type { McpServerInstance } from '@inharness-ai/agent-adapters';
 import type { EntityModuleManifest, PluginActivationState, SystemPromptContribution } from '../../../shared/plugin-host/types.js';
+import type { PluginCommandContribution, PluginManifest, PluginSettingsSection, WritingStyleContribution } from '../../../shared/plugin-host/manifest.js';
 import type { EntityDiff, EntitySerializer, RestoreContext, RestoreResult, SerializeContext, SnapshotData } from '../../serialization/types.js';
 import type { TagsService } from '../../services/tags.js';
 import type { VersionService } from '../../services/versions.js';
@@ -89,6 +90,49 @@ export interface BackendModule extends EntityModuleManifest {
         mount?: PluginMountFn;
     };
 }
+/**
+ * M33: per-`ProjectContext` overlay of project-local plugins loaded
+ * from `<cwd>/.claude4spec/plugins/` (behind the `trustProjectPlugins` gate).
+ * The overlay is relative to the project — two projects in one process carry
+ * different overlays. `listLocal()` returns already-validated, trust-gated
+ * modules; `origin(type)` maps a type back to its source path under
+ * `.claude4spec/plugins/` for diagnostics (shadow report).
+ */
+export interface ProjectPluginOverlay {
+    /** Project-local modules of THIS project (post validation + trust gate). */
+    listLocal(): BackendModule[];
+    /** Source path under `<cwd>/.claude4spec/plugins/` for the given type. */
+    origin(type: string): string;
+    /**
+     * M33 — Settings sections contributed by trusted project-local
+     * plugins (one per plugin with `contributes.settings`). Trust is implicit:
+     * the overlay is built only on the trusted path.
+     */
+    listSettings(): PluginSettingsSection[];
+    /** M33 — declarative editor commands from trusted project-local plugins. */
+    listCommands(): PluginCommandContribution[];
+}
+/**
+ * M33 — a registered base-layer plugin, retained by the registry so the
+ * host can surface its non-entity capabilities (settings/commands) and the
+ * hot-reload pipeline can tear it down via `onUnregister` before re-registering.
+ */
+export interface RegisteredPluginRecord {
+    name: string;
+    version: string;
+    /** Entity types this plugin contributed (for unregister + diagnostics). */
+    contributedTypes: string[];
+    settings: PluginSettingsSection['fields'];
+    commands: PluginCommandContribution[];
+    /** Required teardown hook (idempotent, non-throwing by contract). */
+    onUnregister: () => void;
+}
+/** One overlay type that shadows a same-named base type (cross-layer collision). */
+export interface ShadowedType {
+    type: string;
+    /** Source path of the overlay module that won. */
+    overlayOrigin: string;
+}
 /**
  * M31 split: process-immutable plugin catalog. Populated once at process
  * start via `registerAllPlugins(registry)`; `consolidate` is a PURE factory —
@@ -97,15 +141,52 @@ export interface BackendModule extends EntityModuleManifest {
 export interface PluginRegistry {
     /** Register a plugin manifest. Idempotent on `module.type`. */
     registerEntityModule(module: BackendModule): void;
+    /**
+     * M33: register a runtime plugin manifest. Validates the manifest shape and
+     * fans `contributes.entities[]` out to `registerEntityModule(...)` (each
+     * lowered from its authoring shape). Throws `PluginManifestError` on a
+     * structurally invalid manifest — the loader catches this per-package. Does
+     * NOT gate on hostApiVersion/engines (that is the loader's job).
+     */
+    registerPlugin(manifest: PluginManifest): void;
+    /**
+     * M33 — validate a manifest's shape + lower all its contributions
+     * WITHOUT mutating the registry; throws on a structural problem. The reload
+     * pipeline calls this before `unregisterPlugin` so a structurally-broken new
+     * version never leaves the pool missing a type (atomic "old stays").
+     */
+    validatePlugin(manifest: PluginManifest): void;
+    /**
+     * M33 — tear down a previously-registered base plugin by name: call
+     * its `onUnregister` (idempotent, non-throwing) and drop its entity modules +
+     * retained capability record. The hot-reload pipeline calls this on the OLD
+     * version before re-`registerPlugin`-ing the fresh module. No-op for an
+     * unknown name.
+     */
+    unregisterPlugin(name: string): void;
+    /** M33 — retained base-layer plugin records (for capabilities + reload). */
+    listPluginRecords(): RegisteredPluginRecord[];
     /** All registered modules, regardless of activation. */
     listAvailable(): BackendModule[];
     /** Lookup including inactive — used for broken-chip categorisation. */
     getAvailable(type: string): BackendModule | null;
     /**
-     * Derive a per-project host from config.entities. Pass undefined / null =
-     * all available are active (v1 backward compat). No side effects.
+     * M15: writing styles contributed by base-layer (workspace/npm)
+     * plugins, collected during `registerPlugin`. Pushed into each project's
+     * SkillRegistry as `source: "plugin"` at context build (project-local overlay
+     * styles are pushed separately, behind the trust gate).
+     */
+    listWritingStyles(): WritingStyleContribution[];
+    /**
+     * Derive a per-project host. The effective pool is `base ∪ overlay`
+     * (base ∪ overlay); the `config.entities` whitelist is applied to that merged
+     * pool, not to the base alone. `config.entities === undefined` ⇒ all available
+     * active (v1 backward compat). `overlay === undefined` ⇒ effective pool =
+     * base (parity with the base-only case). No side effects.
      */
-    consolidate(activeWhitelist: string[] | null | undefined): ProjectPluginHost;
+    consolidate(config: {
+        entities?: string[];
+    } | null | undefined, overlay?: ProjectPluginOverlay): ProjectPluginHost;
 }
 /** Plugin self-registration hook — exported by each entities/*\/plugin.ts. */
 export type PluginOnRegister = (registry: PluginRegistry) => void;
@@ -114,6 +195,21 @@ export interface ProjectPluginHost {
     listAvailable(): BackendModule[];
     /** Active modules only (filtered by the consolidated whitelist). */
     listEntities(): BackendModule[];
+    /**
+     * M33 — Settings sections of ALL loaded + trusted plugins in the
+     * effective pool (base ∪ trusted overlay), one per plugin with
+     * `contributes.settings`. Deliberately does NOT filter by `config.entities`
+     * (contrast with `listEntities()`): a plugin's settings survive deactivation
+     * of its entity types — the user needs the panel to re-enable them. This is
+     * axis B (pool + trust), not axis A (entity whitelist).
+     */
+    listSettings(): PluginSettingsSection[];
+    /**
+     * M33 — declarative editor slash-commands of ALL loaded + trusted
+     * plugins, independent of `config.entities` (same two-axis rationale as
+     * `listSettings()`). Routed into the editor via `registerEditorExtension`.
+     */
+    listCommands(): PluginCommandContribution[];
     /** Lookup by type — returns null for inactive or unknown. */
     getEntity(type: string): BackendModule | null;
     /** Lookup including inactive — used for broken-chip categorisation. */
@@ -121,6 +217,12 @@ export interface ProjectPluginHost {
     isActive(type: string): boolean;
     /** Activation snapshot — input for GET /_meta/entities. (Rename of `state()`.) */
     partition(): PluginActivationState;
+    /**
+     * M33: overlay types that shadow a same-named base type. Empty when
+     * there is no overlay or no cross-layer collision. Feeds the per-project
+     * `/_meta/plugins` shadow report and the M19 consistency check.
+     */
+    shadowReport(): ShadowedType[];
     /**
      * Mount every active backend module into the supplied Express app + the
      * host-internal MCP registry. Iterates `listEntities()` and invokes each

package/dist/server/db/migrations/041_chat_thread_transagent.sql

@@ -0,0 +1,22 @@
+-- 0.1.69 Transagents ("bańki") — a chat/patch thread can delegate a unit of
+-- work to a hidden CHILD thread of the same spec. The child runs a full turn,
+-- streams live into the parent's panel, and returns only a `summary` to the
+-- parent LLM's context.
+--
+-- chat_thread gains a self-referential parent pointer (NULL = top-level thread,
+-- NOT NULL = child banka) plus the parent tool_use id that spawned it (used for
+-- F5 reconstruction: resolve childThreadId from the stored tool_use row via
+-- (parent_thread_id, spawned_by_tool_use_id)).
+--
+-- Migration 029 rebuilt chat_thread without a context_type CHECK; here we only
+-- ADD COLUMN, so no table rebuild is needed. The self-FK on parent_thread_id is
+-- safe under ALTER TABLE ADD COLUMN — the migration runner disables foreign_keys
+-- around the batch (see migrate.ts), so this neither rebuilds nor cascade-checks
+-- existing rows.
+-- Spec: 0.1.69 brief — Transagents.
+
+ALTER TABLE chat_thread ADD COLUMN parent_thread_id TEXT
+  REFERENCES chat_thread(id) ON DELETE CASCADE;   -- NULL = top-level; NOT NULL = child banka
+ALTER TABLE chat_thread ADD COLUMN spawned_by_tool_use_id TEXT;
+
+CREATE INDEX idx_chat_thread_parent_thread_id ON chat_thread(parent_thread_id);

package/dist/server/db/migrations/042_chat_thread_drop_context_type_check.sql

@@ -0,0 +1,61 @@
+-- M05/0.1.79 'ask' context_type — older published versions rebuilt chat_thread
+-- in migration 029 WITH `CHECK (context_type IN ('chat','brief','patch'))`.
+-- SQLite cannot ALTER/DROP a CHECK and 029 is already recorded as applied, so
+-- DBs created by those versions still reject 'ask'. Rebuild the table once more
+-- with NO context_type CHECK (validation lives in CONTEXT_TYPE_REGISTRY,
+-- chat-context.ts). Idempotent: a rebuild is harmless for DBs already lacking
+-- the constraint. FK-safe — migrate.ts disables foreign_keys around the batch,
+-- so the DROP does not cascade-delete chat_message / chat_subagent_task /
+-- chat_queued_message rows, and the self-FK parent_thread_id re-resolves once
+-- the new table is renamed in.
+-- Full column set as of migrations 005/009/010/011/013/021/024/022/029/033/041.
+
+CREATE TABLE chat_thread_new (
+  id                               TEXT PRIMARY KEY NOT NULL,
+  title                            TEXT,
+  last_session_id                  TEXT,
+  created_at                       TEXT NOT NULL DEFAULT (datetime('now')),
+  updated_at                       TEXT NOT NULL DEFAULT (datetime('now')),
+  current_todo_items               TEXT,
+  plan_mode                        INTEGER NOT NULL DEFAULT 0,
+  initial_system_prompt            TEXT,
+  last_usage_json                  TEXT,
+  plan_id                          INTEGER REFERENCES plan(id) ON DELETE SET NULL,
+  last_seen_plan_version           INTEGER,
+  last_context_size                INTEGER,
+  context_type                     TEXT NOT NULL DEFAULT 'chat',
+  brief_path                       TEXT,
+  patch_path                       TEXT,
+  initial_architecture_config_json TEXT,
+  parent_thread_id                 TEXT REFERENCES chat_thread(id) ON DELETE CASCADE,
+  spawned_by_tool_use_id           TEXT
+);
+
+INSERT INTO chat_thread_new (
+  id, title, last_session_id, created_at, updated_at, current_todo_items,
+  plan_mode, initial_system_prompt, last_usage_json, plan_id,
+  last_seen_plan_version, last_context_size, context_type, brief_path,
+  patch_path, initial_architecture_config_json, parent_thread_id,
+  spawned_by_tool_use_id
+)
+SELECT
+  id, title, last_session_id, created_at, updated_at, current_todo_items,
+  plan_mode, initial_system_prompt, last_usage_json, plan_id,
+  last_seen_plan_version, last_context_size, context_type, brief_path,
+  patch_path, initial_architecture_config_json, parent_thread_id,
+  spawned_by_tool_use_id
+FROM chat_thread;
+
+DROP TABLE chat_thread;
+
+ALTER TABLE chat_thread_new RENAME TO chat_thread;
+
+CREATE INDEX idx_chat_thread_plan ON chat_thread(plan_id);
+
+CREATE INDEX IF NOT EXISTS idx_chat_thread_brief_path
+  ON chat_thread(brief_path) WHERE brief_path IS NOT NULL;
+
+CREATE INDEX IF NOT EXISTS idx_chat_thread_patch_path
+  ON chat_thread(patch_path) WHERE patch_path IS NOT NULL;
+
+CREATE INDEX idx_chat_thread_parent_thread_id ON chat_thread(parent_thread_id);

package/dist/server/external-skills/brief-implementer-template.d.ts

@@ -1,2 +1,2 @@
 export declare const BRIEF_IMPLEMENTER_FRONTMATTER = "---\nname: c4s-brief-implementer\ndescription: Implement features described in claude4spec briefs (markdown files in .claude4spec/briefs/). Briefs are self-contained \u2014 they include all context needed for implementation (entity snapshots, section diffs, narrative). After implementation, if you discover drift between the brief and reality (missing details, incorrect assumptions, edge cases not covered), generate a patch file in .claude4spec/patches/ as feedback for the specification author. Use when implementing changes in a code repository that has a .claude4spec/briefs/ directory.\n---\n";
-export declare const BRIEF_IMPLEMENTER_BODY = "# c4s-brief-implementer\n\nThis skill describes how to implement a release brief in **your code repository**\n(not the spec repo). A brief is a self-contained markdown file under\n`.claude4spec/briefs/` that captures everything you need to ship the change:\nentity snapshots, section diffs, narrative, acceptance criteria.\n\n**This skill does NOT assume the `c4s` CLI is installed.** Briefs are designed\nto be self-contained \u2014 you do not need to read the main specification or query\nthe entity database. If the brief references something you cannot find in its\nbody, treat that as drift and file a patch (step 4 below).\n\n## Workflow\n\n### 1. Discover\n\n```sh\nls .claude4spec/briefs/        # list available briefs\ncat .claude4spec/briefs/<slug>.md\n```\n\nIf `.claude4spec/` is not in your current directory, walk up the directory tree\nuntil you find it (similar to how git finds `.git/`).\n\n### 2. Read the brief as self-contained input\n\nEvery brief has YAML frontmatter:\n\n```yaml\n---\ntype: brief\nfrom_release: v0.1.16\nto_release: v0.1.17\ngenerator_version: brief-author@0.1\nimplemented: false\n---\n```\n\nThe body contains everything you need \u2014 entity snapshots, section diffs, the\nnarrative of what changes, and acceptance criteria. **Do not read the main\nspecification.**\n\nIf the brief is unclear \u2014 a missing detail, an ambiguous wording, a decision\nyou'd otherwise have to guess \u2014 you have two paths:\n\n**Synchronous (preferred when available).** Ask the specification agent in the\nsame terminal and continue once you have an answer:\n\n```bash\nc4s ask \"Brief nie precyzuje X \u2014 czy chodzi o A czy B?\" --ct brief --brief <brief-slug>.md\n```\n\nContinue the same thread with `c4s ask \"...\" --thread <threadId>` (the\n`threadId` is printed with the answer). This path requires `c4s` installed\n*and* a running `npx @inharness-ai/claude4spec` server. When either is unavailable, skip it.\n\nIf `c4s ask` returns `PROJECT_NOT_FOUND` despite a running server, your cwd is\nprobably reached through a **symlink** (common for `.claude/skills/<name>`\nprojects): `c4s` resolves `process.cwd()` to the real path, which is NOT the one\nregistered in `~/.claude4spec/workspaces.json`. Pass the registered (symlink) path\nexplicitly \u2014 `--project` is run through `path.resolve`, which does NOT canonicalize\nsymlinks, so it matches the registry:\n\n```bash\nc4s ask \"Brief nie precyzuje X \u2014 ...\" --ct brief --brief <brief-slug>.md --project /abs/path/to/registered/skill-dir\n```\n\n**Asynchronous (always available).** If you cannot ask synchronously, proceed\nwith your best judgement and file a patch afterwards (step 4) so the\nspec-author can fold the clarification into the next brief.\n\n### 3. Implement\n\nStandard code flow in your target repository: read existing code, plan, edit,\ntest. Stay focused on what the brief specifies.\n\n### 4. Feedback loop (patches)\n\nWhen you discover that the brief diverges from reality \u2014 a missing detail, an\nincorrect assumption, an edge case not covered, or anything else the\nspec-author should know \u2014 write a patch file:\n\n```sh\nmkdir -p .claude4spec/patches\n```\n\nCreate `.claude4spec/patches/<brief-slug>-<short-desc>.md` with this format:\n\n```markdown\n---\ntype: patch\nbrief: v0-1-16-to-v0-1-17.md      # path relative to briefs/\npatch_kind: drift                  # drift | missing | incorrect | clarification\ncreated_at: 2026-05-11T17:32:00Z\ncreated_by: claude-code            # or \"cursor\", \"aider\", ...\n---\n\n# Patch \u2014 short title\n\n## What I found\n\n\u2026description of the drift / missing detail / incorrect assumption\u2026\n\n## Suggestion\n\n\u2026what the spec-author should consider in a follow-up brief or entity edits\u2026\n```\n\nPatch-kind values:\n\n- `drift` \u2014 the brief described behavior X, but the codebase already does Y.\n- `missing` \u2014 the brief is silent on a detail you had to decide yourself.\n- `incorrect` \u2014 the brief is factually wrong about existing code.\n- `clarification` \u2014 the brief is ambiguous; you guessed but it should be made\n  explicit for next time.\n\nThe `.claude4spec/patches/` directory is created **lazily** \u2014 only when you\nfile your first patch. The claude4spec server does NOT create it.\n\n### 5. Mark brief as implemented\n\nWhen the implementation is genuinely finished \u2014 code committed, tests green,\nmerged to main / accepted by the user \u2014 flip the brief's frontmatter to\n`implemented: true`:\n\n```bash\n# Option A \u2014 Edit tool: change the line `implemented: false` \u2192 `implemented: true`.\n# Option B \u2014 yq (idempotent; adds the field to legacy briefs that never had it):\nyq -i '.implemented = true' .claude4spec/briefs/<brief-slug>.md\n```\n\n`implemented: true` is a **declaration**, not a computed fact derived from git.\nA revert on main does NOT roll the flag back. Set it ONLY when implementation\nis realistically done \u2014 never proactively or \"just in case\".\n\n### 6. Hand-off\n\nThe spec-author reads patches manually (`ls .claude4spec/patches/`, `cat`)\nand folds them into the next brief or entity edits. There is no UI listing in\nthis release \u2014 patches are raw markdown.\n\n## Notes\n\nThis file is **fully managed** by claude4spec \u2014 it is overwritten on every\nserver start when its rendered content changes. Do not edit it by hand.\n";
+export declare const BRIEF_IMPLEMENTER_BODY = "# c4s-brief-implementer\n\nThis skill describes how to implement a release brief in **your code repository**\n(not the spec repo). A brief is a self-contained markdown file under\n`.claude4spec/briefs/` that captures everything you need to ship the change:\nentity snapshots, section diffs, narrative, acceptance criteria.\n\n**This skill does NOT assume the `c4s` CLI is installed.** Briefs are designed\nto be self-contained \u2014 you do not need to read the main specification or query\nthe entity database. If the brief references something you cannot find in its\nbody, treat that as drift and file a patch (step 4 below).\n\n## Workflow\n\n### 1. Discover\n\n```sh\nls .claude4spec/briefs/        # list available briefs\ncat .claude4spec/briefs/<slug>.md\n```\n\nIf `.claude4spec/` is not in your current directory, walk up the directory tree\nuntil you find it (similar to how git finds `.git/`).\n\n### 2. Read the brief as self-contained input\n\nEvery brief has YAML frontmatter:\n\n```yaml\n---\ntype: brief\nfrom_release: v0.1.16\nto_release: v0.1.17\ngenerator_version: brief-author@0.1\nimplemented: false\n---\n```\n\nThe body contains everything you need \u2014 entity snapshots, section diffs, the\nnarrative of what changes, and acceptance criteria. **Do not read the main\nspecification.**\n\nIf the brief is unclear \u2014 a missing detail, an ambiguous wording, a decision\nyou'd otherwise have to guess \u2014 you have two paths:\n\n**Synchronous (preferred when available).** Ask the specification agent in the\nsame terminal and continue once you have an answer:\n\n```bash\nc4s ask \"Brief nie precyzuje X \u2014 czy chodzi o A czy B?\" --ct brief --brief <brief-slug>.md\n```\n\nContinue the same thread with `c4s ask \"...\" --thread <threadId>` (the\n`threadId` is printed with the answer). This path requires `c4s` installed\n*and* a running `npx @inharness-ai/claude4spec` server. When either is unavailable, skip it.\n\nIf `c4s ask` returns `PROJECT_NOT_FOUND` despite a running server, your cwd is\nprobably reached through a **symlink** (common for `.claude/skills/<name>`\nprojects): `c4s` resolves `process.cwd()` to the real path, which is NOT the one\nregistered in `~/.claude4spec/workspaces.json`. Pass the registered (symlink) path\nexplicitly \u2014 `--project` is run through `path.resolve`, which does NOT canonicalize\nsymlinks, so it matches the registry:\n\n```bash\nc4s ask \"Brief nie precyzuje X \u2014 ...\" --ct brief --brief <brief-slug>.md --project /abs/path/to/registered/skill-dir\n```\n\n**Asynchronous (always available).** If you cannot ask synchronously, proceed\nwith your best judgement and file a patch afterwards (step 4) so the\nspec-author can fold the clarification into the next brief.\n\n### 3. Implement\n\nStandard code flow in your target repository: read existing code, plan, edit,\ntest. Stay focused on what the brief specifies.\n\n### 4. Feedback loop (patches)\n\nWhen you discover that the brief diverges from reality \u2014 a missing detail, an\nincorrect assumption, an edge case not covered, or anything else the\nspec-author should know \u2014 write a patch file:\n\n```sh\nmkdir -p .claude4spec/patches\n```\n\nCreate `.claude4spec/patches/<brief-slug>-<short-desc>.md` with this format:\n\n```markdown\n---\ntype: patch\nbrief: v0-1-16-to-v0-1-17.md      # path relative to briefs/\npatch_kind: drift                  # drift | missing | incorrect | clarification\ncreated_at: 2026-05-11T17:32:00Z\ncreated_by: claude-code            # or \"cursor\", \"aider\", ...\n---\n\n# Patch \u2014 short title\n\n## What I found\n\n\u2026description of the drift / missing detail / incorrect assumption\u2026\n\n## Suggestion\n\n\u2026what the spec-author should consider in a follow-up brief or entity edits\u2026\n```\n\nPatch-kind values:\n\n- `drift` \u2014 the brief described behavior X, but the codebase already does Y.\n- `missing` \u2014 the brief is silent on a detail you had to decide yourself.\n- `incorrect` \u2014 the brief is factually wrong about existing code.\n- `clarification` \u2014 the brief is ambiguous; you guessed but it should be made\n  explicit for next time.\n\nThe `.claude4spec/patches/` directory is created **lazily** \u2014 only when you\nfile your first patch. The claude4spec server does NOT create it.\n\n### 5. Mark brief as implemented\n\nWhen the implementation is genuinely finished \u2014 code committed, tests green,\nmerged to main / accepted by the user \u2014 flip the brief's frontmatter to\n`implemented: true`:\n\n```bash\n# Option A \u2014 Edit tool: change the line `implemented: false` \u2192 `implemented: true`.\n# Option B \u2014 yq (idempotent; adds the field to legacy briefs that never had it):\nyq -i '.implemented = true' .claude4spec/briefs/<brief-slug>.md\n```\n\n`implemented: true` is a **declaration**, not a computed fact derived from git.\nA revert on main does NOT roll the flag back. Set it ONLY when implementation\nis realistically done \u2014 never proactively or \"just in case\".\n\n### 6. Hand-off\n\nThe spec-author reads patches manually (`ls .claude4spec/patches/`, `cat`)\nand folds them into the next brief or entity edits. There is no UI listing in\nthis release \u2014 patches are raw markdown.\n\n## Notes\n\nThis is a **base skill** generated by claude4spec. It already covers what you\nneed to read briefs and ask the c4s agent questions. Feel free to **adapt it to\nyour own workflow** (e.g. add a git/PR flow) or use it as-is \u2014 this base copy\nunder `.claude4spec/skills/` is refreshed on server start, so copy it into your\nproject's `.claude/skills/` if you want edits that stick.\n";

package/dist/server/external-skills/brief-implementer-template.js

@@ -146,7 +146,10 @@ this release — patches are raw markdown.
 
 ## Notes
 
-This file is **fully managed** by claude4spec — it is overwritten on every
-server start when its rendered content changes. Do not edit it by hand.
+This is a **base skill** generated by claude4spec. It already covers what you
+need to read briefs and ask the c4s agent questions. Feel free to **adapt it to
+your own workflow** (e.g. add a git/PR flow) or use it as-is — this base copy
+under \`.claude4spec/skills/\` is refreshed on server start, so copy it into your
+project's \`.claude/skills/\` if you want edits that stick.
 `;
 //# sourceMappingURL=brief-implementer-template.js.map

package/dist/server/external-skills/brief-implementer-template.js.map

@@ -1 +1 @@
-{"version":3,"file":"brief-implementer-template.js","sourceRoot":"","sources":["../../../src/server/external-skills/brief-implementer-template.ts"],"names":[],"mappings":"AAAA,MAAM,CAAC,MAAM,6BAA6B,GAAG;;;;CAI5C,CAAC;AAEF,MAAM,CAAC,MAAM,sBAAsB,GAAG;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CAiJrC,CAAC"}
+{"version":3,"file":"brief-implementer-template.js","sourceRoot":"","sources":["../../../src/server/external-skills/brief-implementer-template.ts"],"names":[],"mappings":"AAAA,MAAM,CAAC,MAAM,6BAA6B,GAAG;;;;CAI5C,CAAC;AAEF,MAAM,CAAC,MAAM,sBAAsB,GAAG;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CAoJrC,CAAC"}

package/dist/server/external-skills/spec-reader-template.d.ts

@@ -1,2 +1,2 @@
 export declare const SPEC_READER_FRONTMATTER = "---\nname: c4s-spec-reader\ndescription: Read claude4spec specification entities (endpoints, DTOs, tables, AC, UI views) referenced from markdown pages through XML tags like <inline_mention/>, <single_element/>, <tagged_list/>. Use when working in a repository whose pages/ contain these tags or whose .claude4spec/ directory exists. Resolves entity slugs to full data via c4s CLI or c4s-reader MCP server.\n---\n";
-export declare const SPEC_READER_BODY = "# c4s-spec-reader\n\nThis repository contains a claude4spec specification. Pages (`*.md`) reference\nentities stored in `.claude4spec/db.sqlite` through XML tags. This skill teaches\nyou how to resolve them.\n\nAll commands below walk up from the agent's cwd to the nearest `.claude4spec/` \u2014\nno absolute paths are required.\n\n## Resolving a tag\n\nInstall `claude4spec` (Node 20+) and use the `c4s` CLI. Subcommand names match\nXML tag names 1:1.\n\n| XML tag | CLI equivalent |\n|---------|----------------|\n| `<inline_mention type=\"endpoint\" slug=\"X\"/>` | `c4s inline_mention --type endpoint --slug X` |\n| `<single_element type=\"dto\" slug=\"X\"/>` | `c4s single_element --type dto --slug X` |\n| `<element_list type=\"endpoint\" slugs=\"a,b,c\"/>` | `c4s element_list --type endpoint --slugs a,b,c` |\n| `<tagged_list type=\"dto\" tags=\"auth\" filter=\"and\"/>` | `c4s tagged_list --type dto --tags auth --filter and` |\n| `<tagged_list_mixed tags=\"public\"/>` | `c4s tagged_list_mixed --tags public` |\n\n## Expanding a whole page\n\n```sh\nc4s resolve some-page.md              # writes markdown with tags expanded inline\nc4s resolve some-page.md --format json   # writes { content, resolved: [...] }\n```\n\n## Discovery\n\n- `c4s catalog` \u2014 active entity types with counts + version + description + roleNoun + mcpToolsLine per type (smoke test).\n- `c4s describe --type <t> [--view <v>]` \u2014 JSON Schema per view for one type (on-demand).\n- `c4s list-tags` \u2014 all tags with per-type counts.\n- `c4s list-slugs --type endpoint` \u2014 all slugs for a given type.\n\nAll output is JSON (pretty) by default. Use `--compact` for pipelines and\n`--format text` for terminal-friendly output. Errors go to stderr as JSON with\nan exit code > 0.\n\nThe database is opened **read-only** \u2014 `c4s` never mutates the project.\n\n## Asking the spec agent\n\nWhen a question goes beyond resolving entities or pages, `c4s ask` runs a\nsynchronous agent turn against the specification:\n\n```sh\nc4s ask \"<question>\" --ct chat\n```\n\nUnlike the read-only commands above, `c4s ask` requires a running\n`npx @inharness-ai/claude4spec` server (it delegates the turn to the server's agent).\n\n### `PROJECT_NOT_FOUND` when the project dir is a symlink\n\nIf `c4s ask` (or any `c4s` command) returns `PROJECT_NOT_FOUND` even though a\nserver is running, your cwd is most likely reached through a **symlink** (common\nfor `.claude/skills/<name>` that points elsewhere). `c4s` resolves `process.cwd()`\nthrough the symlink to the real path, which is NOT the path registered in\n`~/.claude4spec/workspaces.json`. Pass the registered (symlink) path explicitly \u2014\n`--project` is run through `path.resolve`, which does NOT canonicalize symlinks, so\nit matches the registry exactly:\n\n```sh\nc4s ask \"<question>\" --ct chat --project /abs/path/to/registered/project-dir\n```\n";
+export declare const SPEC_READER_BODY = "# c4s-spec-reader\n\nThis repository contains a claude4spec specification. Pages (`*.md`) reference\nentities stored in `.claude4spec/db.sqlite` through XML tags. This skill teaches\nyou how to resolve them.\n\nAll commands below walk up from the agent's cwd to the nearest `.claude4spec/` \u2014\nno absolute paths are required.\n\n## Resolving a tag\n\nInstall `claude4spec` (Node 20+) and use the `c4s` CLI. Subcommand names match\nXML tag names 1:1.\n\n| XML tag | CLI equivalent |\n|---------|----------------|\n| `<inline_mention type=\"endpoint\" slug=\"X\"/>` | `c4s inline_mention --type endpoint --slug X` |\n| `<single_element type=\"dto\" slug=\"X\"/>` | `c4s single_element --type dto --slug X` |\n| `<element_list type=\"endpoint\" slugs=\"a,b,c\"/>` | `c4s element_list --type endpoint --slugs a,b,c` |\n| `<tagged_list type=\"dto\" tags=\"auth\" filter=\"and\"/>` | `c4s tagged_list --type dto --tags auth --filter and` |\n| `<tagged_list_mixed tags=\"public\"/>` | `c4s tagged_list_mixed --tags public` |\n\n## Expanding a whole page\n\n```sh\nc4s resolve some-page.md              # writes markdown with tags expanded inline\nc4s resolve some-page.md --format json   # writes { content, resolved: [...] }\n```\n\n## Discovery\n\n- `c4s catalog` \u2014 active entity types with counts + version + description + roleNoun + mcpToolsLine per type (smoke test).\n- `c4s describe --type <t> [--view <v>]` \u2014 JSON Schema per view for one type (on-demand).\n- `c4s list-tags` \u2014 all tags with per-type counts.\n- `c4s list-slugs --type endpoint` \u2014 all slugs for a given type.\n\nAll output is JSON (pretty) by default. Use `--compact` for pipelines and\n`--format text` for terminal-friendly output. Errors go to stderr as JSON with\nan exit code > 0.\n\nThe database is opened **read-only** \u2014 `c4s` never mutates the project.\n\n## Asking the spec agent\n\nWhen a question goes beyond resolving entities or pages, `c4s ask` runs a\nsynchronous agent turn against the specification:\n\n```sh\nc4s ask \"<question>\" --ct chat\n```\n\nUnlike the read-only commands above, `c4s ask` requires a running\n`npx @inharness-ai/claude4spec` server (it delegates the turn to the server's agent).\n\n### `PROJECT_NOT_FOUND` when the project dir is a symlink\n\nIf `c4s ask` (or any `c4s` command) returns `PROJECT_NOT_FOUND` even though a\nserver is running, your cwd is most likely reached through a **symlink** (common\nfor `.claude/skills/<name>` that points elsewhere). `c4s` resolves `process.cwd()`\nthrough the symlink to the real path, which is NOT the path registered in\n`~/.claude4spec/workspaces.json`. Pass the registered (symlink) path explicitly \u2014\n`--project` is run through `path.resolve`, which does NOT canonicalize symlinks, so\nit matches the registry exactly:\n\n```sh\nc4s ask \"<question>\" --ct chat --project /abs/path/to/registered/project-dir\n```\n\n### `SERVER_NOT_RECOGNIZED` / `PROJECT_BUILD_FAILED` \u2014 the project failed to build\n\nIf `c4s ask` reports the server is \"not a claude4spec server\", or\n`GET /api/projects/<id>/config` returns `PROJECT_BUILD_FAILED`, the server IS\nrunning but **that project failed to build**. A common cause is the configured\n`writingStyle` skill failing to load: a skill under `.claude/skills/` whose\nfrontmatter `version` exceeds the supported version is skipped at scan time, so\nthe style is \"not a selectable writing-style skill\".\n\n`c4s ask` surfaces the real `PROJECT_BUILD_FAILED` message, which names the cause\n(e.g. `writingStyle \"X\" was found on disk but skipped: version 2 > supported 1`).\nFix the skill's frontmatter (`version` is a format-compat gate \u2014 keep it `1`, don't\nuse it as a content counter) and restart the server.\n";

package/dist/server/external-skills/spec-reader-template.js

@@ -70,5 +70,19 @@ it matches the registry exactly:
 \`\`\`sh
 c4s ask "<question>" --ct chat --project /abs/path/to/registered/project-dir
 \`\`\`
+
+### \`SERVER_NOT_RECOGNIZED\` / \`PROJECT_BUILD_FAILED\` — the project failed to build
+
+If \`c4s ask\` reports the server is "not a claude4spec server", or
+\`GET /api/projects/<id>/config\` returns \`PROJECT_BUILD_FAILED\`, the server IS
+running but **that project failed to build**. A common cause is the configured
+\`writingStyle\` skill failing to load: a skill under \`.claude/skills/\` whose
+frontmatter \`version\` exceeds the supported version is skipped at scan time, so
+the style is "not a selectable writing-style skill".
+
+\`c4s ask\` surfaces the real \`PROJECT_BUILD_FAILED\` message, which names the cause
+(e.g. \`writingStyle "X" was found on disk but skipped: version 2 > supported 1\`).
+Fix the skill's frontmatter (\`version\` is a format-compat gate — keep it \`1\`, don't
+use it as a content counter) and restart the server.
 `;
 //# sourceMappingURL=spec-reader-template.js.map

package/dist/server/external-skills/spec-reader-template.js.map

@@ -1 +1 @@
-{"version":3,"file":"spec-reader-template.js","sourceRoot":"","sources":["../../../src/server/external-skills/spec-reader-template.ts"],"names":[],"mappings":"AAAA,MAAM,CAAC,MAAM,uBAAuB,GAAG;;;;CAItC,CAAC;AAEF,MAAM,CAAC,MAAM,gBAAgB,GAAG;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CAmE/B,CAAC"}
+{"version":3,"file":"spec-reader-template.js","sourceRoot":"","sources":["../../../src/server/external-skills/spec-reader-template.ts"],"names":[],"mappings":"AAAA,MAAM,CAAC,MAAM,uBAAuB,GAAG;;;;CAItC,CAAC;AAEF,MAAM,CAAC,MAAM,gBAAgB,GAAG;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CAiF/B,CAAC"}