cfsa-antigravity 3.0.0 → 3.0.2

package/README.md

@@ -57,7 +57,33 @@ Every install now scaffolds a shared `.memory/` root at the project level. It is
 └── migrate/     # legacy memory import helpers
 ```
 
-The installer also creates `.mcp.json` so supported runtimes can talk to the shared project-local memory daemon through their own MCP clients, and it merges Claude hook entries into `.claude/settings.json` for automatic capture and daemon startup. 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 runtime state into `.memory/runtime/`, and the semantic index writes retrieval artifacts into `.memory/schema/semantic-index.json` plus `.memory/schema/semantic-manifest.json`.
+
+### MCP client setup and first graph compile
+
+The kit installs the **server/runtime** only. You must configure your tool's MCP client yourself.
+
+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"],
+      "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"
+      }
+    }
+  }
+}
+```
+
+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/`.
 
 This replaces fragmented runtime-local memory as the canonical project memory layer. Runtime-local memory files remain legacy inputs for migration.
 
@@ -101,8 +127,10 @@ A fresh `init` now installs:
 - your selected runtime directories (`.agent/`, `.claude/`, `.factory/`)
 - `docs/`
 - shared `.memory/`
-- `.mcp.json` with the `cfsa-memory` server registration
-- merged Claude hooks in `.claude/settings.json` when Claude is installed
+- the shared memory MCP server/runtime under `.memory/mcp-server/`
+- the rest of the `.memory` scaffold needed to compile graph/index artifacts locally
+
+Tool-specific MCP client config (such as `.mcp.json`) is user-managed and documented above.
 
 Use `--migrate-memory` when upgrading an older installation that still has runtime-local memory you want imported into `.memory/`.
 

package/bin/cli.mjs

@@ -403,7 +403,7 @@ function installMemoryScaffold(targetDir, opts) {
 
     if (opts.dryRun) {
         info(`Would copy ${c.bold}.memory/${c.reset} (${countFiles(srcMemoryDir)} files)`);
-        info(`Would merge ${c.bold}.mcp.json${c.reset} and ${c.bold}.claude/settings.json${c.reset}`);
+        info(`Would install the shared memory runtime only; MCP client config remains user-managed`);
         return;
     }
 
@@ -419,82 +419,8 @@ function installMemoryScaffold(targetDir, opts) {
         info(`Merged ${c.bold}.memory/${c.reset}`);
     }
 
-    const mcpPath = join(targetDir, ".mcp.json");
-    const currentMcp = readJsonFile(mcpPath, {});
-    const nextMcp = {
-        ...currentMcp,
-        mcpServers: {
-            ...(currentMcp.mcpServers || {}),
-            "cfsa-memory": {
-                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"
-                }
-            }
-        }
-    };
-    writeJsonFile(mcpPath, nextMcp);
-    info(`Updated ${c.bold}.mcp.json${c.reset}`);
-
-    const claudeSettingsPath = join(targetDir, ".claude", "settings.json");
-    const currentClaudeSettings = readJsonFile(claudeSettingsPath, {});
-    const memoryHooks = {
-        SessionStart: [
-            {
-                hooks: [
-                    {
-                        type: "command",
-                        command: "node .memory/hooks/session-start.mjs"
-                    }
-                ]
-            }
-        ],
-        PreCompact: [
-            {
-                matcher: "manual|auto",
-                hooks: [
-                    {
-                        type: "command",
-                        command: "node .memory/hooks/pre-compact.mjs"
-                    }
-                ]
-            }
-        ],
-        Stop: [
-            {
-                hooks: [
-                    {
-                        type: "command",
-                        command: "node .memory/hooks/session-end.mjs"
-                    }
-                ]
-            }
-        ]
-    };
-    const daemonHooks = {
-        SessionStart: [
-            {
-                hooks: [
-                    {
-                        type: "command",
-                        command: "node .memory/mcp-server/start.mjs"
-                    }
-                ]
-            }
-        ]
-    };
-
-    const nextClaudeSettings = {
-        ...currentClaudeSettings,
-        hooks: mergeHookConfig(mergeHookConfig(currentClaudeSettings.hooks || {}, daemonHooks), memoryHooks)
-    };
-    writeJsonFile(claudeSettingsPath, nextClaudeSettings);
-    info(`Updated ${c.bold}.claude/settings.json${c.reset}`);
+    info(`Installed ${c.bold}.memory/${c.reset} runtime scaffold`);
+    info(`MCP client configuration is user-managed; see the README for tool-specific setup and the initial graph compile step.`);
 }
 
 async function migrateMemory(targetDir) {
@@ -664,7 +590,7 @@ async function cmdInit(opts) {
         log("");
         log(`${c.bold}Next steps:${c.reset}`);
         log(`  1. Open your project in your agent of choice`);
-        log(`  2. Verify ${c.cyan}.memory/${c.reset}, ${c.cyan}.mcp.json${c.reset}, and ${c.cyan}.claude/settings.json${c.reset}`);
+        log(`  2. Verify ${c.cyan}.memory/${c.reset} and configure your tool-specific MCP client manually if needed (see README)`);
         log(`  3. Run ${c.cyan}/ideate${c.reset} to start the pipeline`);
         log("");
         log(`${c.dim}Documentation: https://github.com/RepairYourTech/cfsa-antigravity${c.reset}`);
@@ -814,7 +740,6 @@ function cmdStatus() {
         { path: ".memory/wiki/hubs/phases.md", label: "Phase graph hub" },
         { path: ".memory/wiki/hubs/operations.md", label: "Operations graph hub" },
         { path: ".memory/wiki/hubs/surfaces.md", label: "Surface graph hub" },
-        { path: ".mcp.json", label: "MCP config" },
     ];
 
     if (!args.json) {
@@ -869,24 +794,27 @@ function cmdStatus() {
             const mcpConfig = JSON.parse(readFileSync(mcpPath, "utf-8"));
             if (mcpConfig.mcpServers?.["cfsa-memory"]?.args?.includes(".memory/mcp-server/client.mjs")) {
                 if (!args.json) {
-                    info(`  MCP registration ${c.dim}(cfsa-memory configured)${c.reset}`);
+                    info(`  MCP client config ${c.dim}(cfsa-memory configured)${c.reset}`);
                 }
-                statusJson.memoryHealth.push({ label: "MCP registration", status: "present", detail: "cfsa-memory configured" });
+                statusJson.memoryHealth.push({ label: "MCP client config", status: "present", detail: "cfsa-memory configured" });
                 totalInstalled++;
             } else {
                 if (!args.json) {
-                    warn("  MCP registration — cfsa-memory missing or misconfigured");
+                    warn("  MCP client config — present but cfsa-memory is not configured");
                 }
-                statusJson.memoryHealth.push({ label: "MCP registration", status: "missing", detail: "cfsa-memory missing or misconfigured" });
-                totalMissing++;
+                statusJson.memoryHealth.push({ label: "MCP client config", status: "partial", detail: "present but cfsa-memory is not configured" });
             }
         } catch {
             if (!args.json) {
-                warn("  MCP config — invalid JSON");
+                warn("  MCP client config — invalid JSON");
             }
-            statusJson.memoryHealth.push({ label: "MCP config", status: "invalid" });
-            totalMissing++;
+            statusJson.memoryHealth.push({ label: "MCP client config", status: "invalid" });
+        }
+    } else {
+        if (!args.json) {
+            warn("  MCP client config — user-managed (not configured here)");
         }
+        statusJson.memoryHealth.push({ label: "MCP client config", status: "user-managed", detail: "configure your tool manually if needed" });
     }
 
     const claudeSettingsPath = join(targetDir, ".claude", "settings.json");
@@ -896,9 +824,9 @@ function cmdStatus() {
             const hasHooks = Boolean(claudeSettings.hooks?.SessionStart?.length);
             if (hasHooks) {
                 if (!args.json) {
-                    info(`  Claude memory hooks ${c.dim}(configured)${c.reset}`);
+                    info(`  Claude settings ${c.dim}(hooks configured)${c.reset}`);
                 }
-                statusJson.memoryHealth.push({ label: "Claude memory hooks", status: "present", detail: "configured" });
+                statusJson.memoryHealth.push({ label: "Claude settings", status: "present", detail: "hooks configured" });
                 totalInstalled++;
             } else {
                 if (!args.json) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "cfsa-antigravity",
-  "version": "3.0.0",
+  "version": "3.0.2",
   "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: 5605aba29a84c4b3149b7115b73f77297aafd83b
-last_synced_at: 2026-04-14T15:34:01Z
-kit_version: 3.0.0
+last_synced_commit: 63c31d9113ccb3f828aeb5c8a4902483cbbc2e8a
+last_synced_at: 2026-04-15T09:10:27Z
+kit_version: 3.0.2

package/template/.claude/README.md

@@ -30,11 +30,12 @@ Project root canonical memory / Obsidian vault:
 
 The `.memory/` directory is the canonical project memory layer and is designed to function as an Obsidian-friendly vault inside the project. `.claude/memory/` exists only for Claude-native bridge guidance and session-specific conventions.
 
-A Claude install also gets:
-- `.mcp.json` with the `cfsa-memory` client registration
-- `.claude/settings.json` hook entries for SessionStart, PreCompact, and Stop
-- daemon startup through `.memory/mcp-server/start.mjs`
-- initial `.memory/schema/` compilation during `init`
+A Claude install also gets the shared `.memory/` runtime scaffold, including:
+- the `cfsa-memory` server under `.memory/mcp-server/`
+- daemon startup helpers under `.memory/mcp-server/start.mjs`
+- compile/runtime helpers under `.memory/pipeline/` and `.memory/hooks/`
+
+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/`.
 
 All runtimes should read and write shared project memory through `.memory/` and the MCP bridge.
 

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

@@ -1,6 +1,6 @@
 # Kit Sync State
 
 upstream: https://github.com/RepairYourTech/cfsa-antigravity
-last_synced_commit: 5605aba29a84c4b3149b7115b73f77297aafd83b
-last_synced_at: 2026-04-14T15:34:01Z
-kit_version: 3.0.0
+last_synced_commit: 63c31d9113ccb3f828aeb5c8a4902483cbbc2e8a
+last_synced_at: 2026-04-15T09:10:27Z
+kit_version: 3.0.2

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

@@ -1,6 +1,6 @@
 # Kit Sync State
 
 upstream: https://github.com/RepairYourTech/cfsa-antigravity
-last_synced_commit: 5605aba29a84c4b3149b7115b73f77297aafd83b
-last_synced_at: 2026-04-14T15:34:01Z
-kit_version: 3.0.0
+last_synced_commit: 63c31d9113ccb3f828aeb5c8a4902483cbbc2e8a
+last_synced_at: 2026-04-15T09:10:27Z
+kit_version: 3.0.2

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

@@ -6,5 +6,14 @@ Stdio MCP server for the unified `.memory/` system.
 - `index.mjs` — stdio JSON-RPC MCP entrypoint
 - `tools/` — individual tool adapters that call the pipeline
 
+## Ownership boundary
+The kit installs the MCP **server/runtime** into the workspace. Tool-specific MCP client configuration (for example `.mcp.json` or editor-specific MCP settings) is user-managed.
+
+## 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/`
+
 ## Extension pattern
 Expose new memory capabilities by adding a tool file under `tools/` and wiring it into `index.mjs`.

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

@@ -165,15 +165,25 @@ npx cfsa-antigravity init
 
 ### Unified memory scaffold
 
-`init` now also installs a shared `.memory/` directory plus `.mcp.json`. The `.memory/` directory is designed to function as an Obsidian vault inside the project.
+`init` now installs a shared `.memory/` directory. The `.memory/` directory is designed to function as an Obsidian vault inside the project.
 
 - `.memory/raw/` stores append-only session and event captures
 - `.memory/wiki/` stores compiled patterns, decisions, blockers, and knowledge pages
 - `.memory/schema/` stores machine-readable retrieval artifacts, including semantic index/manifests
-- `.memory/mcp-server/client.mjs` is the per-runtime MCP client entrypoint to the shared daemon
+- `.memory/mcp-server/client.mjs` is the MCP bridge entrypoint for the shared daemon
 - `.memory/mcp-server/daemon.mjs` is the shared project-local MCP daemon
 - `.memory/hooks/` contains Claude-oriented hook entrypoints
 
+The kit installs the memory **server/runtime** only. `.mcp.json` and other tool-specific MCP client settings are user-managed.
+
+### Initial graph compile for existing projects
+
+After installing or updating the `.memory` runtime in an existing project:
+1. Configure your tool's MCP client manually.
+2. Trigger the first memory compile (`memory_compile` via MCP, or the direct compile script fallback).
+3. Verify graph/index artifacts exist under `.memory/schema/` and `.memory/wiki/`.
+4. Open Obsidian at `.memory/`.
+
 If you are upgrading an older project with siloed runtime-local memory, run:
 
 ```bash

package/template/docs/kit-architecture.md

@@ -274,8 +274,10 @@ The kit now separates runtime execution state from shared project memory:
 
 - Runtime progress still lives under `.agent/progress/`, `.claude/progress/`, and `.factory/progress/`
 - Canonical cross-runtime memory lives under `.memory/`
-- Claude uses hooks in `.claude/settings.json` to flush and compile memory automatically
-- All runtimes can access the same memory through `.mcp.json` -> `cfsa-memory` -> `.memory/mcp-server/client.mjs` -> shared daemon `.memory/mcp-server/daemon.mjs`
+- Claude can use hooks in `.claude/settings.json` to flush and compile memory automatically when the user chooses to wire them
+- All runtimes can access the same memory through their own MCP client config -> `cfsa-memory` -> `.memory/mcp-server/client.mjs` -> shared daemon `.memory/mcp-server/daemon.mjs`
+
+The kit ships the server/runtime. Tool-specific MCP client configuration (for example `.mcp.json`) remains user-managed.
 
 This lets Claude, Antigravity, Factory, Codex, and future runtimes query the same project memory without each runtime owning a separate canonical store.