cfsa-antigravity 3.0.1 → 3.0.3

package/README.md

@@ -57,7 +57,11 @@ Every install now scaffolds a shared `.memory/` root at the project level. It is
 └── migrate/     # legacy memory import helpers
 ```
 
-The installer ships the shared memory runtime into `.memory/`, including the project-local MCP server under `.memory/mcp-server/`. Tool-specific MCP client config is intentionally **not** managed by the kit — users wire their own `.mcp.json` / editor settings for the tools they actually use. The daemon writes runtime state into `.memory/runtime/`, and the semantic index writes retrieval artifacts into `.memory/schema/semantic-index.json` plus `.memory/schema/semantic-manifest.json`.
+The installer ships the shared memory runtime into `.memory/`, including the project-local MCP server under `.memory/mcp-server/`. Tool-specific MCP client config is intentionally **not** managed by the kit — users wire their own `.mcp.json` / editor settings for the tools they actually use. The daemon writes workspace-local runtime state into `.memory/runtime/`, and clients resolve that state before proxying requests so one workspace does not silently talk to another workspace's daemon. The semantic index writes retrieval artifacts into `.memory/schema/semantic-index.json` plus `.memory/schema/semantic-manifest.json`.
+
+The practical contract is: point your tool at `.memory/mcp-server/client.mjs`, start the daemon for that workspace, and let the client discover the correct local daemon from `.memory/runtime/cfsa-memory-daemon.json`.
+
+If the daemon health payload reports a different `projectRoot` than the client expects, the client now fails loudly instead of proxying requests to the wrong workspace.
 
 ### MCP client setup and first graph compile
 
@@ -65,6 +69,21 @@ The kit installs the **server/runtime** only. You must configure your tool's MCP
 
 For tools that use a workspace `.mcp.json`, point the tool at the shared server entrypoint:
 
+```json
+{
+  "mcpServers": {
+    "cfsa-memory": {
+      "command": "node",
+      "args": [".memory/mcp-server/client.mjs"]
+    }
+  }
+}
+```
+
+This is the preferred default because the client resolves the correct workspace-local daemon from `.memory/runtime/cfsa-memory-daemon.json`.
+
+If you need a custom host/port, use env overrides:
+
 ```json
 {
   "mcpServers": {
@@ -72,18 +91,15 @@ For tools that use a workspace `.mcp.json`, point the tool at the shared server
       "command": "node",
       "args": [".memory/mcp-server/client.mjs"],
       "env": {
-        "MEMORY_ROOT": ".memory",
         "CFSA_MEMORY_HOST": "127.0.0.1",
-        "CFSA_MEMORY_PORT": "4317",
-        "CFSA_MEMORY_URL": "http://127.0.0.1:4317/mcp",
-        "CFSA_MEMORY_HEALTH_URL": "http://127.0.0.1:4317/health"
+        "CFSA_MEMORY_PORT": "4317"
       }
     }
   }
 }
 ```
 
-For an existing project, after wiring your MCP client, trigger the initial graph/index build by running the memory compile path (`memory_compile` via MCP, or the direct compile script fallback) before opening Obsidian. Verify files like `.memory/schema/spec-graph.json` and `.memory/wiki/hubs/spec-graph.md` exist, then open Obsidian at `.memory/`.
+For an existing project, after wiring your MCP client, start the workspace-local daemon so it writes `.memory/runtime/cfsa-memory-daemon.json`, then trigger the initial graph/index build by running the memory compile path (`memory_compile` via MCP, or the direct compile script fallback) before opening Obsidian. Verify files like `.memory/schema/spec-graph.json` and `.memory/wiki/hubs/spec-graph.md` exist, then open Obsidian at `.memory/`.
 
 This replaces fragmented runtime-local memory as the canonical project memory layer. Runtime-local memory files remain legacy inputs for migration.
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "cfsa-antigravity",
-  "version": "3.0.1",
+  "version": "3.0.3",
   "description": "CFSA Pipeline — Constraint-First Specification Architecture for AI agents. Production-grade from line one.",
   "scripts": {
     "changeset": "changeset",

package/template/.agent/kit-sync.md

@@ -1,6 +1,6 @@
 # Kit Sync State
 
 upstream: https://github.com/RepairYourTech/cfsa-antigravity
-last_synced_commit: a2ac251f783e2da4afa0c7f3b10d3d98fac585b7
-last_synced_at: 2026-04-15T05:09:13Z
-kit_version: 3.0.1
+last_synced_commit: 719622791838f3cc3da429ab87ff4bc303c81961
+last_synced_at: 2026-04-15T20:06:45Z
+kit_version: 3.0.3

package/template/.claude/README.md

@@ -37,6 +37,8 @@ A Claude install also gets the shared `.memory/` runtime scaffold, including:
 
 Tool-specific MCP client config and Claude hook wiring are user-managed. If you want Claude to talk to the shared memory daemon, add the appropriate MCP client config yourself and then run the initial compile before opening Obsidian at `.memory/`.
 
+Claude should point at `.memory/mcp-server/client.mjs`. That client now resolves the daemon from the current workspace's `.memory/runtime/cfsa-memory-daemon.json` and validates the daemon's `projectRoot` from `/health`, so a Claude session in one repo will not silently proxy into another repo's daemon.
+
 All runtimes should read and write shared project memory through `.memory/` and the MCP bridge.
 
 ```text

package/template/.claude/kit-sync.md

@@ -1,6 +1,6 @@
 # Kit Sync State
 
 upstream: https://github.com/RepairYourTech/cfsa-antigravity
-last_synced_commit: a2ac251f783e2da4afa0c7f3b10d3d98fac585b7
-last_synced_at: 2026-04-15T05:09:13Z
-kit_version: 3.0.1
+last_synced_commit: 719622791838f3cc3da429ab87ff4bc303c81961
+last_synced_at: 2026-04-15T20:06:45Z
+kit_version: 3.0.3

package/template/.factory/kit-sync.md

@@ -1,6 +1,6 @@
 # Kit Sync State
 
 upstream: https://github.com/RepairYourTech/cfsa-antigravity
-last_synced_commit: a2ac251f783e2da4afa0c7f3b10d3d98fac585b7
-last_synced_at: 2026-04-15T05:09:13Z
-kit_version: 3.0.1
+last_synced_commit: 719622791838f3cc3da429ab87ff4bc303c81961
+last_synced_at: 2026-04-15T20:06:45Z
+kit_version: 3.0.3

package/template/.memory/mcp-server/README.md

@@ -12,8 +12,16 @@ The kit installs the MCP **server/runtime** into the workspace. Tool-specific MC
 ## Initial bootstrap
 For an existing project:
 1. wire your tool's MCP client to this server entrypoint
-2. run the initial memory compile (`memory_compile` or the direct compile fallback)
-3. verify graph/index artifacts exist under `.memory/schema/` and `.memory/wiki/`
+2. start the workspace-local daemon so it writes `.memory/runtime/cfsa-memory-daemon.json`
+3. run the initial memory compile (`memory_compile` or the direct compile fallback)
+4. verify graph/index artifacts exist under `.memory/schema/` and `.memory/wiki/`
+
+## Workspace-local routing contract
+- preferred client config is just `command: node` plus `args: [".memory/mcp-server/client.mjs"]`
+- `daemon.mjs` publishes `projectRoot`, `memoryRoot`, `endpoint`, and `healthUrl` into `.memory/runtime/cfsa-memory-daemon.json`
+- `client.mjs` reads that runtime state for the current workspace before proxying MCP requests
+- `client.mjs` validates `/health` and rejects mismatched `projectRoot` values instead of silently talking to another workspace's daemon
+- host/port env can still be used when you intentionally need custom daemon startup behavior
 
 ## Extension pattern
 Expose new memory capabilities by adding a tool file under `tools/` and wiring it into `index.mjs`.

package/template/.memory/mcp-server/client.mjs

@@ -1,15 +1,51 @@
-const endpoint = process.env.CFSA_MEMORY_URL || `http://${process.env.CFSA_MEMORY_HOST || "127.0.0.1"}:${process.env.CFSA_MEMORY_PORT || "4317"}/mcp`;
-const healthUrl = process.env.CFSA_MEMORY_HEALTH_URL || endpoint.replace(/\/mcp$/, "/health");
+import { buildDaemonEndpoints, fetchHealth, readDaemonState, resolveProjectRoot } from "./runtime.mjs";
+
+const projectRoot = resolveProjectRoot();
+const state = readDaemonState(projectRoot);
+const envEndpoint = process.env.CFSA_MEMORY_URL || null;
+const envHealthUrl = process.env.CFSA_MEMORY_HEALTH_URL || null;
+const fallbackEndpoint = `http://${process.env.CFSA_MEMORY_HOST || "127.0.0.1"}:${process.env.CFSA_MEMORY_PORT || "4317"}/mcp`;
+const fallbackHealthUrl = envHealthUrl || fallbackEndpoint.replace(/\/mcp$/, "/health");
+
+function resolveConnectionTarget() {
+  if (state) {
+    return { source: "runtime-state", ...buildDaemonEndpoints(state) };
+  }
+  if (envEndpoint || envHealthUrl) {
+    return {
+      source: "environment",
+      endpoint: envEndpoint || fallbackEndpoint,
+      healthUrl: envHealthUrl || (envEndpoint || fallbackEndpoint).replace(/\/mcp$/, "/health"),
+    };
+  }
+  return {
+    source: "fallback",
+    endpoint: fallbackEndpoint,
+    healthUrl: fallbackHealthUrl,
+  };
+}
+
+const connection = resolveConnectionTarget();
 
 async function ensureReady() {
   for (let attempt = 0; attempt < 20; attempt += 1) {
     try {
-      const response = await fetch(healthUrl);
-      if (response.ok) {
-        return true;
+      const health = await fetchHealth(connection.healthUrl);
+      const daemonProjectRoot = health?.projectRoot;
+      if (daemonProjectRoot && daemonProjectRoot !== projectRoot) {
+        throw new Error(`Workspace mismatch: client for ${projectRoot} is pointing at daemon for ${daemonProjectRoot}`);
+      }
+      if (!daemonProjectRoot && state?.projectRoot) {
+        throw new Error(`Workspace identity missing from daemon health response at ${connection.healthUrl}`);
+      }
+      return true;
+    } catch (error) {
+      if (error instanceof Error && error.message.startsWith("Workspace ")) {
+        throw error;
+      }
+      if (error instanceof Error && error.message.startsWith("Workspace identity missing")) {
+        throw error;
       }
-    } catch {
-      // retry
     }
     await new Promise((resolve) => setTimeout(resolve, 150));
   }
@@ -25,17 +61,24 @@ process.stdin.on("data", async (chunk) => {
   for (const line of lines) {
     const trimmed = line.trim();
     if (!trimmed) continue;
-    const ready = await ensureReady();
-    if (!ready) {
-      process.stdout.write(`${JSON.stringify({ jsonrpc: "2.0", id: null, error: { code: -32000, message: "cfsa-memory-daemon is not ready" } })}\n`);
-      continue;
+    let requestId = null;
+    try {
+      const parsed = JSON.parse(trimmed);
+      requestId = parsed?.id ?? null;
+      const ready = await ensureReady();
+      if (!ready) {
+        process.stdout.write(`${JSON.stringify({ jsonrpc: "2.0", id: requestId, error: { code: -32000, message: "cfsa-memory-daemon is not ready" } })}\n`);
+        continue;
+      }
+      const response = await fetch(connection.endpoint, {
+        method: "POST",
+        headers: { "content-type": "application/json" },
+        body: trimmed,
+      });
+      const text = await response.text();
+      process.stdout.write(`${text}\n`);
+    } catch (error) {
+      process.stdout.write(`${JSON.stringify({ jsonrpc: "2.0", id: requestId, error: { code: -32000, message: error instanceof Error ? error.message : String(error) } })}\n`);
     }
-    const response = await fetch(endpoint, {
-      method: "POST",
-      headers: { "content-type": "application/json" },
-      body: trimmed,
-    });
-    const text = await response.text();
-    process.stdout.write(`${text}\n`);
   }
 });

package/template/.memory/mcp-server/daemon.mjs

@@ -5,12 +5,14 @@ import { memoryGraphQuery } from "./tools/graph.mjs";
 import { memoryIngest, memoryLogDaily, memoryGetActiveBlockers } from "./tools/ingest.mjs";
 import { memoryLint } from "./tools/lint.mjs";
 import { memoryContext, memoryQuery, memorySemanticStatus } from "./tools/query.mjs";
-import { clearDaemonState, writeDaemonState } from "./runtime.mjs";
+import { clearDaemonState, resolveProjectRoot, workspaceMemoryRoot, writeDaemonState } from "./runtime.mjs";
 
 const host = process.env.CFSA_MEMORY_HOST || "127.0.0.1";
 const preferredPort = Number(process.env.CFSA_MEMORY_PORT || 4317);
-const projectRoot = process.cwd();
+const projectRoot = resolveProjectRoot();
+const memoryRoot = workspaceMemoryRoot(projectRoot);
 let actualPort = preferredPort;
+const startedAt = new Date().toISOString();
 
 const tools = {
   memory_flush: memoryFlush,
@@ -44,8 +46,11 @@ function statePayload(extra = {}) {
     host,
     port: actualPort,
     requestedPort: preferredPort,
+    endpoint: `http://${host}:${actualPort}/mcp`,
     healthUrl: `http://${host}:${actualPort}/health`,
-    startedAt: new Date().toISOString(),
+    projectRoot,
+    memoryRoot,
+    startedAt,
     ...extra,
   };
 }

package/template/.memory/mcp-server/runtime.mjs

@@ -1,11 +1,15 @@
 import { existsSync, mkdirSync, readFileSync, rmSync, writeFileSync } from "node:fs";
-import { dirname, join } from "node:path";
+import { join, resolve } from "node:path";
 
-export function getRuntimeDir(root = process.cwd()) {
+export function resolveProjectRoot(root = process.env.CFSA_MEMORY_PROJECT_ROOT || process.cwd()) {
+  return resolve(root);
+}
+
+export function getRuntimeDir(root = resolveProjectRoot()) {
   return join(root, ".memory", "runtime");
 }
 
-export function ensureRuntimeDir(root = process.cwd()) {
+export function ensureRuntimeDir(root = resolveProjectRoot()) {
   const runtimeDir = getRuntimeDir(root);
   if (!existsSync(runtimeDir)) {
     mkdirSync(runtimeDir, { recursive: true });
@@ -13,28 +17,55 @@ export function ensureRuntimeDir(root = process.cwd()) {
   return runtimeDir;
 }
 
-export function pidFile(root = process.cwd()) {
+export function pidFile(root = resolveProjectRoot()) {
   return join(getRuntimeDir(root), "cfsa-memory-daemon.pid");
 }
 
-export function stateFile(root = process.cwd()) {
+export function stateFile(root = resolveProjectRoot()) {
   return join(getRuntimeDir(root), "cfsa-memory-daemon.json");
 }
 
+export function workspaceMemoryRoot(root = resolveProjectRoot()) {
+  return join(root, ".memory");
+}
+
+export function buildDaemonEndpoints(state) {
+  const host = state.host || "127.0.0.1";
+  const port = state.port;
+  const healthUrl = state.healthUrl || `http://${host}:${port}/health`;
+  const endpoint = state.endpoint || `http://${host}:${port}/mcp`;
+  return { endpoint, healthUrl };
+}
+
+export function normalizeDaemonState(root, state = {}) {
+  const projectRoot = resolveProjectRoot(root);
+  const memoryRoot = state.memoryRoot ? resolve(state.memoryRoot) : workspaceMemoryRoot(projectRoot);
+  const normalized = {
+    ...state,
+    projectRoot,
+    memoryRoot,
+  };
+  const { endpoint, healthUrl } = buildDaemonEndpoints(normalized);
+  normalized.endpoint = endpoint;
+  normalized.healthUrl = healthUrl;
+  return normalized;
+}
+
 export function writeDaemonState(root, state) {
   ensureRuntimeDir(root);
-  writeFileSync(stateFile(root), `${JSON.stringify(state, null, 2)}\n`, "utf8");
-  writeFileSync(pidFile(root), `${state.pid}\n`, "utf8");
+  const normalized = normalizeDaemonState(root, state);
+  writeFileSync(stateFile(root), `${JSON.stringify(normalized, null, 2)}\n`, "utf8");
+  writeFileSync(pidFile(root), `${normalized.pid}\n`, "utf8");
 }
 
-export function readDaemonState(root = process.cwd()) {
+export function readDaemonState(root = resolveProjectRoot()) {
   if (!existsSync(stateFile(root))) {
     return null;
   }
-  return JSON.parse(readFileSync(stateFile(root), "utf8"));
+  return normalizeDaemonState(root, JSON.parse(readFileSync(stateFile(root), "utf8")));
 }
 
-export function clearDaemonState(root = process.cwd()) {
+export function clearDaemonState(root = resolveProjectRoot()) {
   if (existsSync(pidFile(root))) rmSync(pidFile(root), { force: true });
   if (existsSync(stateFile(root))) rmSync(stateFile(root), { force: true });
 }
@@ -48,13 +79,19 @@ export function processExists(pid) {
   }
 }
 
+export async function fetchHealth(url) {
+  const response = await fetch(url);
+  if (!response.ok) {
+    throw new Error(`Health check failed with status ${response.status}`);
+  }
+  return response.json();
+}
+
 export async function waitForHealth(url, retries = 20, delayMs = 150) {
   for (let attempt = 0; attempt < retries; attempt += 1) {
     try {
-      const response = await fetch(url);
-      if (response.ok) {
-        return true;
-      }
+      await fetchHealth(url);
+      return true;
     } catch {
       // keep retrying
     }

package/template/.memory/mcp-server/start.mjs

@@ -1,9 +1,9 @@
 import { spawn } from "node:child_process";
 import { existsSync } from "node:fs";
 import { join } from "node:path";
-import { clearDaemonState, processExists, readDaemonState, waitForHealth } from "./runtime.mjs";
+import { clearDaemonState, processExists, readDaemonState, resolveProjectRoot, waitForHealth } from "./runtime.mjs";
 
-const root = process.cwd();
+const root = resolveProjectRoot();
 const daemonPath = join(root, ".memory", "mcp-server", "daemon.mjs");
 if (!existsSync(daemonPath)) {
   console.error(`Missing daemon at ${daemonPath}`);
@@ -25,10 +25,12 @@ if (current?.pid && processExists(current.pid)) {
 }
 
 const child = spawn("node", [daemonPath], {
+  cwd: root,
   detached: true,
   stdio: "ignore",
   env: {
     ...process.env,
+    CFSA_MEMORY_PROJECT_ROOT: root,
     CFSA_MEMORY_HOST: host,
     CFSA_MEMORY_PORT: String(port),
   },

package/template/.memory/pipeline/compile.mjs

@@ -2,6 +2,7 @@ import { join } from "node:path";
 import {
   chunkText,
   ensureMemoryScaffold,
+  getFileText,
   getMemoryRoot,
   listFilesRecursively,
   readJsonl,
@@ -84,8 +85,64 @@ export function compileMemory(options = {}) {
   const knowledge = records.filter((record) => !["pattern", "decision", "blocker"].includes(record.type));
 
   const knowledgeDir = join(memoryRoot, "wiki", "knowledge");
+  const specsRoot = join(memoryRoot, "wiki", "specs");
   const indexEntries = [];
   const chunkEntries = [];
+  const specFiles = listFilesRecursively(specsRoot)
+    .filter((filePath) => filePath.endsWith(".md"))
+    .filter((filePath) => !filePath.endsWith("README.md"))
+    .filter((filePath) => !filePath.endsWith(".gitkeep"));
+
+  const specTypeForPath = (relativePath) => {
+    if (relativePath.includes('/specs/ia/')) return 'ia-spec';
+    if (relativePath.includes('/specs/be/')) return 'be-spec';
+    if (relativePath.includes('/specs/fe/')) return 'fe-spec';
+    if (relativePath.includes('/specs/phases/')) return 'phase-plan';
+    if (relativePath.includes('/specs/ideation/')) return 'ideation';
+    if (relativePath.includes('/specs/audits/')) return 'audit';
+    if (relativePath.includes('/specs/architecture/')) return 'architecture';
+    return 'spec';
+  };
+
+  const specTitleForText = (relativePath, text) => {
+    const heading = text.split("\n").find((line) => line.startsWith("# "));
+    if (heading) {
+      return heading.replace(/^#\s+/, '').trim();
+    }
+    return relativePath.split('/').at(-1)?.replace(/\.md$/, '') ?? relativePath;
+  };
+
+  for (const filePath of specFiles) {
+    const text = getFileText(filePath, '');
+    if (!text.trim()) {
+      continue;
+    }
+    const relativePath = toRelativePath(projectRoot, filePath);
+    const type = specTypeForPath(relativePath);
+    const title = specTitleForText(relativePath, text);
+    indexEntries.push({
+      id: `spec:${relativePath.replace(/^\.memory\/wiki\/specs\//, '').replace(/\.md$/, '')}`,
+      type,
+      title,
+      path: relativePath,
+      source: relativePath,
+      agent: 'spec-vault',
+      timestamp: 'spec-vault',
+      excerpt: text.slice(0, 240),
+    });
+
+    for (const [index, chunk] of chunkText(text).entries()) {
+      chunkEntries.push({
+        id: `spec:${relativePath}:${index + 1}`,
+        parentId: `spec:${relativePath.replace(/^\.memory\/wiki\/specs\//, '').replace(/\.md$/, '')}`,
+        path: relativePath,
+        text: chunk,
+      });
+    }
+  }
+
+  const seenIndexEntryIds = new Set(indexEntries.map((entry) => entry.id));
+  const seenChunkEntryIds = new Set(chunkEntries.map((entry) => entry.id));
 
   const getRecordPath = (record) => {
     if (record.type === "pattern") {
@@ -111,24 +168,32 @@ export function compileMemory(options = {}) {
 
   for (const record of records) {
     const absolutePath = getRecordPath(record);
-    indexEntries.push({
-      id: record.id,
-      type: record.type,
-      title: record.title ?? record.id,
-      path: toRelativePath(projectRoot, absolutePath),
-      source: record.source,
-      agent: record.agent,
-      timestamp: record.timestamp,
-      excerpt: record.text.slice(0, 240),
-    });
+    if (!seenIndexEntryIds.has(record.id)) {
+      indexEntries.push({
+        id: record.id,
+        type: record.type,
+        title: record.title ?? record.id,
+        path: toRelativePath(projectRoot, absolutePath),
+        source: record.source,
+        agent: record.agent,
+        timestamp: record.timestamp,
+        excerpt: record.text.slice(0, 240),
+      });
+      seenIndexEntryIds.add(record.id);
+    }
 
     for (const [index, chunk] of chunkText(record.text).entries()) {
+      const chunkId = `${record.id}:${index + 1}`;
+      if (seenChunkEntryIds.has(chunkId)) {
+        continue;
+      }
       chunkEntries.push({
-        id: `${record.id}:${index + 1}`,
+        id: chunkId,
         parentId: record.id,
         path: toRelativePath(projectRoot, absolutePath),
         text: chunk,
       });
+      seenChunkEntryIds.add(chunkId);
     }
   }
 

package/template/docs/README.md

@@ -176,6 +176,8 @@ npx cfsa-antigravity init
 
 The kit installs the memory **server/runtime** only. `.mcp.json` and other tool-specific MCP client settings are user-managed.
 
+The MCP routing contract is workspace-local: the daemon writes `.memory/runtime/cfsa-memory-daemon.json`, the client reads that file for the current workspace, then validates the daemon's `projectRoot` from `/health` before proxying requests. This prevents cross-workspace collisions when multiple projects have daemons running.
+
 ### Initial graph compile for existing projects
 
 After installing or updating the `.memory` runtime in an existing project:

package/template/docs/kit-architecture.md

@@ -48,6 +48,8 @@ The kit ships multiple runtime trees in this repository:
 
 The `.memory/` directory is not just an internal store; it is intended to be an Obsidian-friendly vault within the project space so humans and agents can browse the same memory corpus directly. It also mirrors durable `.memory/wiki/specs/` artifacts into graph-friendly vault notes so IA/BE/FE specs, phase plans, and related knowledge become traversable Obsidian graph nodes. Runtime clients should connect to one shared project-local memory daemon rather than each spawning their own isolated server process.
 
+That routing is now workspace-safe: the daemon publishes `projectRoot`, `memoryRoot`, and endpoint metadata into `.memory/runtime/cfsa-memory-daemon.json` and its `/health` payload; the client resolves the local workspace daemon from that runtime state and rejects mismatched workspace identity instead of trusting a shared default port.
+
 ### Antigravity Runtime Components
 
 ```text