cfsa-antigravity 3.0.2 → 3.1.0

package/template/.memory/README.md

@@ -4,6 +4,7 @@ Source files for the unified `.memory/` scaffold that `npm run build` copies int
 
 ## What lives here
 - `pipeline/` — raw/wiki/schema processing utilities
+- `pipeline/progress/` — canonical pipeline progress scaffold shared by all runtimes
 - `mcp-server/` — stdio MCP server exposing memory tools
 - `hooks/` — Claude Code hook entrypoints
 - `migrate/` — legacy memory migration

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/migrate/migrate-legacy.mjs

@@ -10,6 +10,7 @@ const LEGACY_MAP = [
   { source: ".claude/memory/decisions.md", target: "wiki/decisions.md" },
   { source: ".claude/memory/blockers.md", target: "wiki/blockers.md" },
   { source: ".claude/progress/memory", targetDir: "wiki/knowledge", runtime: "claude-progress" },
+  { source: ".codex/progress/memory", targetDir: "wiki/knowledge", runtime: "codex-progress" },
   { source: ".agent/progress/memory", targetDir: "wiki/knowledge", runtime: "agent-progress" },
   { source: ".factory/memory", targetDir: "wiki/knowledge", runtime: "factory-memory" },
   { source: ".factory/progress/memory", targetDir: "wiki/knowledge", runtime: "factory-progress" },

package/template/.memory/pipeline/README.md

@@ -10,6 +10,7 @@ Unified memory pipeline utilities.
 - `spec-graph.mjs` — extract typed spec graph nodes/edges and Obsidian relationship hubs
 - `query.mjs` — query the compiled schema/index
 - `lint.mjs` — validate the scaffold and compiled outputs
+- `progress/` — canonical phase, slice, session, and spec-pipeline state scaffold
 
 ## Extension pattern
 Add small focused modules and keep compile/query behavior reusable by both hooks and the MCP server.

package/template/CLAUDE.md

@@ -56,9 +56,9 @@ The pipeline enforces a **progressive decision lock** — each stage locks decis
 .factory/
 ├── skills/              # All pipeline skills (workflows + rules + utilities as SKILL.md)
 ├── skill-library/       # Factory-owned skill library
-├── instructions/        # Core directives (workflow, tech-stack, patterns)
-└── progress/            # Pipeline progress tracking
+└── instructions/        # Core directives (workflow, tech-stack, patterns)
 .memory/                 # Canonical shared project memory / Obsidian-friendly vault
+├── pipeline/progress/   # Shared pipeline progress tracking
 docs/
 ├── plans/               # User project specifications (output directory)
 │   ├── ideation/
@@ -183,7 +183,7 @@ The `template/` directory is what gets published to npm. It's built from:
 - `docs/` (full directory, but `.memory/wiki/specs/` and `.memory/wiki/specs/audits/` content is stripped)
 - Root config files (`GEMINI.md`, `AGENTS.md`, `CLAUDE.md`, `CODEX.md`)
 
-Session-specific data is excluded (`.agent/progress/*.md` except README, `.claude/progress/*.md` runtime session artifacts where applicable, and `.memory/raw/*` generated runtime captures).
+Session-specific data is excluded (`.memory/pipeline/progress/*.md` runtime session artifacts where applicable, and `.memory/raw/*` generated runtime captures).
 
 ## Key Documentation
 
@@ -217,7 +217,7 @@ If ideation-index.md doesn't exist, the pipeline hasn't started — tell user to
 
 This is enforced by:
 - **Session Continuity Protocols** (`.claude/skills/session-continuity/protocols/`)
-- **Progress Tracking** (`.claude/progress/spec-pipeline.md`)
+- **Progress Tracking** (`.memory/pipeline/progress/spec-pipeline.md`)
 - **Pattern Extraction** (`.claude/skills/session-continuity/protocols/04-pattern-extraction.md`)
 
 ## Common Tasks

package/template/CODEX.md

@@ -7,7 +7,7 @@ This file provides guidance to Codex when working with code in this repository.
 **CFSA Antigravity** is a Constraint-First Specification Architecture pipeline that transforms raw ideas into exhaustively specified, test-driven, production-quality code through progressive gates. This repository is the kit source, not a destination product.
 
 - **Entry Point**: `npx cfsa-antigravity init`
-- **Codex support model**: Codex uses `CODEX.md` for repo guidance and the shared `.agent/` runtime for workflows, rules, instructions, and skills
+- **Codex support model**: Codex uses `CODEX.md` for repo guidance and the standalone `.codex/` runtime for workflow skills, rules, instructions, and skill library content
 - **Core Philosophy**: production-grade from line one, no throwaway code, no deferred quality
 
 ## Essential Commands
@@ -20,11 +20,11 @@ npm run changeset
 
 ## Runtime Model
 
-Codex is a first-class supported agent target, but it does not use a standalone runtime tree in this repository.
+Codex is a first-class supported agent target with its own `.codex/` runtime tree.
 
 Instead:
 
-- `cfsa-antigravity init --agent codex` installs the shared `.agent/` runtime
+- `cfsa-antigravity init --agent codex` installs the standalone `.codex/` runtime
 - `CODEX.md` provides Codex-specific repository guidance
 - `AGENTS.md` remains the generic pipeline config shipped to installed projects
 - `.memory/` is the canonical shared memory root installed into the project for cross-runtime continuity
@@ -47,8 +47,8 @@ If the Codex runtime has its own MCP client configuration surface beyond `.mcp.j
 ## What To Read First
 
 1. `AGENTS.md`
-2. `.agent/instructions/workflow.md`
-3. `.agent/instructions/commands.md`
+2. `.codex/instructions/workflow.md`
+3. `.codex/instructions/commands.md`
 4. `docs/README.md`
 5. `docs/kit-architecture.md`
 
@@ -66,53 +66,6 @@ If you change Codex support, keep these aligned:
 - CLI help and argument parsing in `bin/cli.mjs`
 - Root documentation (`README.md`, `docs/README.md`, `docs/kit-architecture.md`)
 - Root config sync (`CODEX.md` copied into `template/`)
+- Runtime sync (`.codex/` copied into `template/.codex/`)
 - Template integrity checks in `scripts/check-template-integrity.sh`
 - shared MCP daemon/client contract in `.memory/mcp-server/`
-
-## What To Read First
-
-1. `AGENTS.md`
-2. `.agent/instructions/workflow.md`
-3. `.agent/instructions/commands.md`
-4. `docs/README.md`
-5. `docs/kit-architecture.md`
-
-## Contribution Notes
-
-- Do not edit `template/` directly
-- Update source files first, then run `npm run build`
-- Run `npm run check` before considering the task complete
-- Preserve `{{PLACEHOLDER}}` markers in kit source files
-
-## Codex Alignment
-
-If you change Codex support, keep these aligned:
-
-- CLI help and argument parsing in `bin/cli.mjs`
-- Root documentation (`README.md`, `docs/README.md`, `docs/kit-architecture.md`)
-- Root config sync (`CODEX.md` copied into `template/`)
-- Template integrity checks in `scripts/check-template-integrity.sh`
-
-## What To Read First
-
-1. `AGENTS.md`
-2. `.agent/instructions/workflow.md`
-3. `.agent/instructions/commands.md`
-4. `docs/README.md`
-5. `docs/kit-architecture.md`
-
-## Contribution Notes
-
-- Do not edit `template/` directly
-- Update source files first, then run `npm run build`
-- Run `npm run check` before considering the task complete
-- Preserve `{{PLACEHOLDER}}` markers in kit source files
-
-## Codex Alignment
-
-If you change Codex support, keep these aligned:
-
-- CLI help and argument parsing in `bin/cli.mjs`
-- Root documentation (`README.md`, `docs/README.md`, `docs/kit-architecture.md`)
-- Root config sync (`CODEX.md` copied into `template/`)
-- Template integrity checks in `scripts/check-template-integrity.sh`

package/template/GEMINI.md

@@ -164,8 +164,8 @@ Before acting on any task, detect the current pipeline phase from filesystem mar
 | Decomposition done | IA shards in `.memory/wiki/specs/ia/` | `/write-architecture-spec` |
 | Spec writing | BE/FE specs exist | `/write-be-spec`, `/write-fe-spec` |
 | Planning | Phase plan in `.memory/wiki/specs/phases/` | `/plan-phase` |
-| Workspace setup | Phase plan exists, no `.agent/progress/` content | `/setup-workspace` → `/verify-infrastructure` |
-| Implementation | `.agent/progress/` has content | `/implement-slice` |
+| Workspace setup | Phase plan exists, no `.memory/pipeline/progress/` content | `/setup-workspace` → `/verify-infrastructure` |
+| Implementation | `.memory/pipeline/progress/` has content | `/implement-slice` |
 
 **Use this table to gate every action.** If a user runs a command that doesn't match their current phase, explain what phase they're in and what to run instead.
 

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:
@@ -215,6 +217,7 @@ The current implementation uses a local semantic backend designed to be upgraded
 ```bash
 git clone https://github.com/RepairYourTech/cfsa-antigravity.git
 cp -r cfsa-antigravity/.agent /path/to/your-project/
+cp -r cfsa-antigravity/.codex /path/to/your-project/
 cp -r cfsa-antigravity/docs /path/to/your-project/
 cp cfsa-antigravity/GEMINI.md /path/to/your-project/
 cp cfsa-antigravity/AGENTS.md /path/to/your-project/
@@ -226,7 +229,7 @@ cp cfsa-antigravity/CODEX.md /path/to/your-project/
 | Agent | What to Do |
 |-------|------------|
 | **Antigravity** | Both `AGENTS.md` and `GEMINI.md` are present — bootstrap fills both during `/create-prd`. |
-| **Codex** | Use `CODEX.md` for repo guidance and the shared `.agent/` runtime installed via `cfsa-antigravity init --agent codex`. |
+| **Codex** | Use `CODEX.md` for repo guidance and the standalone `.codex/` runtime installed via `cfsa-antigravity init --agent codex`. |
 | **Gemini CLI** | `GEMINI.md` is your agent config. Bootstrap fills it during `/create-prd`. |
 | **Claude Code** | Use the standalone `.claude/` runtime installed via `cfsa-antigravity init --agent claude` |
 | **Factory Droid** | Use the standalone `.factory/` runtime installed via `cfsa-antigravity init --agent factory` |
@@ -240,7 +243,7 @@ cp cfsa-antigravity/CODEX.md /path/to/your-project/
 > Do not hide the runtime directory your agent/editor needs to index.
 >
 > - Antigravity-style installs use `.agent/`
-> - Codex installs also use `.agent/`
+> - Codex installs use `.codex/`
 > - Claude Code installs use `.claude/`
 > - Factory Droid installs use `.factory/`
 >

package/template/docs/kit-architecture.md

@@ -2,7 +2,7 @@
 
 **Purpose:** Provide a high-level map of the agentic machinery that powers CFSA Antigravity.
 
-This document serves as a guide to understanding how the CFSA kit is organized across its agent runtimes. The shared `.agent/` runtime serves Antigravity and Codex-style installs, while `.claude/` owns Claude-specific execution assets. A shared project-level `.memory/` root now provides the canonical cross-runtime memory layer.
+This document serves as a guide to understanding how the CFSA kit is organized across its agent runtimes. The `.agent/` runtime serves Antigravity-style installs, `.codex/` serves Codex installs, and `.claude/` owns Claude-specific execution assets. A shared project-level `.memory/` root now provides the canonical cross-runtime memory layer.
 
 ---
 
@@ -11,30 +11,35 @@ This document serves as a guide to understanding how the CFSA kit is organized a
 The kit ships multiple runtime trees in this repository:
 
 ```text
-.agent/                      # Shared Antigravity/Codex runtime
+.agent/                      # Antigravity runtime
 ├── instructions/
-├── progress/
 ├── rules/
 ├── skill-library/
 ├── skills/
 └── workflows/
 
+.codex/                      # Codex runtime
+├── instructions/
+├── rules/
+├── skill-library/
+└── skills/
+
 .claude/                     # Claude Code runtime
 ├── commands/
 ├── instructions/
-├── progress/
 ├── rules/
 ├── skill-library/
 └── skills/
 
 .factory/                    # Factory Droid runtime
 ├── instructions/
-├── progress/
 ├── skill-library/
 └── skills/
 
 .memory/                     # Canonical shared project memory / Obsidian vault
 ├── .obsidian/
+├── pipeline/
+│   └── progress/            # Canonical phase, slice, session, and spec-pipeline state
 ├── raw/
 ├── wiki/
 ├── schema/
@@ -44,29 +49,39 @@ The kit ships multiple runtime trees in this repository:
 └── migrate/
 ```
 
-`.agent/`, `.claude/`, and `.factory/` implement the same CFSA pipeline for different agent environments. Codex uses the shared `.agent/` runtime plus the root `CODEX.md` guidance file rather than a separate runtime tree. Each runtime owns its own execution assets and state.
+`.agent/`, `.codex/`, `.claude/`, and `.factory/` implement the same CFSA pipeline for different agent environments. Codex uses the `.codex/` runtime plus the root `CODEX.md` guidance file. Each runtime owns its own execution assets. Shared project state lives under `.memory/`.
 
 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
 .agent/
 ├── instructions/    # Core directives (the "brainstem")
-├── progress/        # State and memory (the "hippocampus")
 ├── rules/           # Non-negotiable constraints (the "laws")
 ├── skill-library/   # Installable skill packages (the "toolbox")
 ├── skills/          # Active capabilities (the "tools")
 └── workflows/       # Structured processes (the "playbooks")
 ```
 
+### Codex Runtime Components
+
+```text
+.codex/
+├── instructions/    # Core directives for Codex runtime
+├── rules/           # Always-on constraints
+├── skill-library/   # Codex-owned installable skill packages
+└── skills/          # Active Codex capabilities, including pipeline workflow skills
+```
+
 ### Claude Runtime Components
 
 ```text
 .claude/
 ├── commands/        # Slash command shims
 ├── instructions/    # Core directives for Claude runtime
-├── progress/        # Claude pipeline state
 ├── rules/           # Always-on constraints
 ├── skill-library/   # Claude-owned installable skill packages
 ├── skills/          # Active Claude capabilities
@@ -227,12 +242,12 @@ Each CX entry includes which nodes interact, confidence level, 5 synthesis quest
 
 Agents are inherently stateless across conversations. The kit uses the **Session Continuity** protocol to provide a persistent memory system.
 
-### Runtime progress directories
+### Canonical Progress Directory
 
-Antigravity uses `.agent/progress/`. Claude Code uses `.claude/progress/`. Both serve the same purpose: phase tracking, spec-pipeline tracking, and session resumption.
+All runtimes use `.memory/pipeline/progress/` for phase tracking, spec-pipeline tracking, and session resumption. Runtime-local progress folders are legacy migration inputs only; new workflow, skill, and rule instructions must not point agents at `.agent/progress/`, `.codex/progress/`, `.claude/progress/`, or `.factory/progress/`.
 
 ```text
-.agent/progress/ or .claude/progress/
+.memory/pipeline/progress/
 ├── index.md                      # Master checklist — phases + overall %
 ├── spec-pipeline.md              # Spec completion tracker (IA/BE/FE per shard)
 ├── phases/
@@ -249,7 +264,7 @@ Antigravity uses `.agent/progress/`. Claude Code uses `.claude/progress/`. Both
 
 > **Adaptive Granularity Rule**: A slice gets its own file in `slices/` only when it has ≥3 acceptance criteria. Slices with 1–2 criteria are tracked inline in the phase file. This prevents file explosion for simple specs while giving granular tracking for complex ones.
 
-> **Runtime vs. pre-shipped files**: The `phases/`, `slices/`, and `sessions/` directories and their contents are created at runtime by `/plan-phase` (Protocol 2: Progress Generation) and `/implement-slice` (Protocol 3: Progress Update). They do not ship pre-created. The only files that ship as part of the kit in `memory/` are the three empty seed files (`patterns.md`, `blockers.md`, `decisions.md`).
+> **Runtime vs. pre-shipped files**: The `phases/`, `slices/`, `sessions/`, and `memory/` directories ship as empty scaffolds under `.memory/pipeline/progress/`. Runtime-generated markdown inside them is created by `/plan-phase` (Protocol 2: Progress Generation), `/implement-slice` (Protocol 3: Progress Update), and session close.
 
 ### Flow
 
@@ -264,16 +279,16 @@ The only canonical memory system shipped by the kit is the project-level `.memor
 
 - `.claude/memory/` is bridge documentation only
 - `.factory/memory/` is bridge documentation only
-- `.agent/progress/memory/` and `.factory/progress/memory/` are legacy migration inputs, not primary memory stores
+- `.agent/progress/memory/`, `.codex/progress/memory/`, `.claude/progress/memory/`, and `.factory/progress/memory/` are legacy migration inputs, not primary memory stores
 
 All new shared memory behavior should target `.memory/`.
 
 ### Unified memory architecture
 
-The kit now separates runtime execution state from shared project memory:
+The kit now separates runtime execution assets from shared project state:
 
-- Runtime progress still lives under `.agent/progress/`, `.claude/progress/`, and `.factory/progress/`
-- Canonical cross-runtime memory lives under `.memory/`
+- Canonical progress state lives under `.memory/pipeline/progress/`
+- Canonical cross-runtime memory lives under `.memory/wiki/`
 - 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`
 
@@ -315,7 +330,7 @@ The power of the kit comes from how these modules interact:
 
 *   **Workflows call Skills:** A workflow like `/create-prd` will explicitly instruct the agent to use the `technical-writer` and `brainstorming` skills.
 *   **Rules constrain Workflows:** While a workflow dictates the *steps*, the rules dictate *how* those steps are performed (e.g., `/implement-slice` must obey `tdd-contract-first.md`).
-*   **State informs Execution:** Each runtime reads from its own progress directory (`.agent/progress/` or `.claude/progress/`) to contextualize execution based on past decisions and current active phases.
+*   **State informs Execution:** Each runtime reads from the shared progress directory (`.memory/pipeline/progress/`) to contextualize execution based on past decisions and current active phases.
 
 ### Frontmatter `skills:` Semantic
 
@@ -437,7 +452,7 @@ Workflows are designed to end with explicit NEXT STEPS. An agent shouldn't guess
 
 ## 6. Kit Maintenance Checklist
 
-**When a new workflow or shard is added to a runtime tree (`.agent/workflows/` or `.claude/skills/<workflow>/SKILL.md`):**
+**When a new workflow or shard is added to a runtime tree (`.agent/workflows/`, `.codex/skills/<workflow>/SKILL.md`, or `.claude/skills/<workflow>/SKILL.md`):**
 
 - [ ] Add a row to the `AGENTS.md` Pipeline Workflow Table
 - [ ] Add a matching row to the `GEMINI.md` Pipeline Workflow Table (must stay in sync with `AGENTS.md`)
@@ -445,7 +460,7 @@ Workflows are designed to end with explicit NEXT STEPS. An agent shouldn't guess
 - [ ] If the workflow uses new prd-template reference files, add them to `prd-templates/SKILL.md`
 - [ ] If the workflow introduces a new skill, add it to the matching runtime's `skill-library/MANIFEST.md`
 
-**When a new rule is added to a runtime tree (`.agent/rules/` or `.claude/rules/`):**
+**When a new rule is added to a runtime tree (`.agent/rules/`, `.codex/rules/`, or `.claude/rules/`):**
 
 - [ ] Add a row to the `GEMINI.md` Agent Rules table
 - [ ] If the rule uses `{{PLACEHOLDER}}` values, follow the placeholder checklist below
@@ -475,6 +490,8 @@ Examples:
 ```bash
 echo '.agent/' >> .git/info/exclude
 # or
+echo '.codex/' >> .git/info/exclude
+# or
 echo '.claude/' >> .git/info/exclude
 ```