@infinitedusky/indusk-mcp 1.9.4 → 1.10.1

package/dist/bin/commands/extensions.js

@@ -3,7 +3,7 @@ import { cpSync, existsSync, mkdirSync, readdirSync, readFileSync, rmSync, write
 import { dirname, join } from "node:path";
 import { fileURLToPath } from "node:url";
 import { globSync } from "glob";
-import { disableExtension, disabledDir, enableExtension, ensureExtensionsDirs, extensionConfigDir, extensionsDir, getEnabledExtensions, isEnabled, loadExtension, loadExtensions, resolveManifestPath, } from "../../lib/extension-loader.js";
+import { disabledDir, disableExtension, enableExtension, ensureExtensionsDirs, extensionConfigDir, extensionsDir, getEnabledExtensions, isEnabled, loadExtension, loadExtensions, resolveManifestPath, } from "../../lib/extension-loader.js";
 const __dirname = dirname(fileURLToPath(import.meta.url));
 const packageRoot = join(__dirname, "../../..");
 const builtinDir = join(packageRoot, "extensions");
@@ -635,20 +635,31 @@ function printMcpInstructions(name, manifest) {
             }
             if (allResolved) {
                 const args = [
-                    "mcp", "add", "-t", "http",
-                    ...headerArgs.flatMap(h => {
+                    "mcp",
+                    "add",
+                    "-t",
+                    "http",
+                    ...headerArgs.flatMap((h) => {
                         const match = h.match(/--header "(.+): (.+)"/);
                         if (match)
                             return ["--header", `${match[1]}: ${match[2]}`];
                         return [];
                     }),
-                    "-s", "project", "--", name, url,
+                    "-s",
+                    "project",
+                    "--",
+                    name,
+                    url,
                 ];
-                const cmd = `claude ${args.map(a => a.includes(" ") ? `"${a}"` : a).join(" ")}`;
+                const cmd = `claude ${args.map((a) => (a.includes(" ") ? `"${a}"` : a)).join(" ")}`;
                 console.info(`\n  ${name}: adding MCP server with credentials from .env...`);
                 // Remove existing entry first so we always write fresh credentials
                 try {
-                    execSync(`claude mcp remove -s project ${name}`, { cwd: process.cwd(), timeout: 10000, stdio: ["ignore", "pipe", "pipe"] });
+                    execSync(`claude mcp remove -s project ${name}`, {
+                        cwd: process.cwd(),
+                        timeout: 10000,
+                        stdio: ["ignore", "pipe", "pipe"],
+                    });
                 }
                 catch {
                     // Ignore — may not exist

package/dist/bin/commands/init.js

@@ -299,6 +299,21 @@ export async function init(projectRoot, options = {}) {
     else {
         console.info("  skip: codegraphcontext MCP server (already exists)");
     }
+    // Add graphiti MCP server (Phase 5.5 — Streamable HTTP, runs in indusk-infra container)
+    const graphitiAddCommand = "claude mcp add -t http -s project graphiti http://localhost:8100/mcp";
+    if (!existingServers.has("graphiti") || force) {
+        try {
+            execSync(graphitiAddCommand, { cwd: projectRoot, stdio: "pipe", timeout: 10000 });
+            console.info("  added: graphiti MCP server (http://localhost:8100/mcp)");
+        }
+        catch {
+            console.info("  failed: could not add graphiti MCP server — run manually:");
+            console.info(`    ${graphitiAddCommand}`);
+        }
+    }
+    else {
+        console.info("  skip: graphiti MCP server (already exists)");
+    }
     // 4b. Check infrastructure container
     console.info("\n[Infrastructure]");
     try {

package/dist/bin/commands/update.js

@@ -274,7 +274,38 @@ export async function update(projectRoot) {
                     console.info(`  ${name}: update hook failed`);
                 }
             }
-            if (manifest?.mcp_server?.setup_instructions) {
+            // Phase 5.5: ensure declared MCP server is registered in .mcp.json.
+            // If the manifest's top-level mcp_server.add_command is set and the server
+            // is missing from .mcp.json, run the command. Idempotent — skips if present.
+            // The MCP server's name in .mcp.json is the extension name (matches init's
+            // `claude mcp add ... <extName> ...` convention).
+            const mcpServer = manifest?.mcp_server;
+            if (mcpServer?.add_command) {
+                const mcpJsonPath = join(projectRoot, ".mcp.json");
+                let alreadyRegistered = false;
+                if (existsSync(mcpJsonPath)) {
+                    try {
+                        const mcpJson = JSON.parse(readFileSync(mcpJsonPath, "utf-8"));
+                        alreadyRegistered = !!mcpJson.mcpServers?.[name];
+                    }
+                    catch { }
+                }
+                if (!alreadyRegistered) {
+                    try {
+                        execSync(mcpServer.add_command, {
+                            cwd: projectRoot,
+                            stdio: "pipe",
+                            timeout: 10000,
+                        });
+                        console.info(`  ${name}: registered MCP server`);
+                    }
+                    catch {
+                        console.info(`  ${name}: failed to register MCP server — run manually:`);
+                        console.info(`    ${mcpServer.add_command}`);
+                    }
+                }
+            }
+            else if (mcpServer?.setup_instructions) {
                 console.info(`  ${name}: MCP server setup — see .claude/skills/${name}/SKILL.md`);
             }
         }

package/dist/lib/config.d.ts

@@ -14,8 +14,59 @@ export interface InduskConfig {
         testRunner?: string;
         linter?: string;
     };
+    graphiti?: {
+        /**
+         * Group id used for project-specific Graphiti episodes. Defaults to the
+         * project directory basename. Override here if the directory name differs
+         * from the desired group id (e.g. shared monorepo, renamed project).
+         */
+        groupId?: string;
+    };
+    otel?: {
+        /**
+         * Project's relationship to OpenTelemetry. Controls whether the OTel gate
+         * fires when the planner writes impl phases and when the validate-impl-structure
+         * / check-gates hooks evaluate them.
+         *
+         * - `service`: produces telemetry I want to collect (default behavior; gate fires)
+         * - `library`: ships to other people, never produces telemetry (gate silent)
+         * - `tool`: short-lived script, telemetry overhead exceeds value (gate silent)
+         * - `none`: explicit opt-out for legacy/prototype/internal experiments (gate silent)
+         *
+         * **If unset, behaves as `service`** (gate fires). This preserves backwards
+         * compatibility — existing projects without the field continue to get the OTel
+         * gate enforced. Opt-out is explicit; opt-in is implicit.
+         */
+        role?: "service" | "library" | "tool" | "none";
+    };
 }
 export declare function getConfigPath(projectRoot: string): string;
 export declare function readConfig(projectRoot: string): InduskConfig | null;
 export declare function writeConfig(projectRoot: string, config: InduskConfig): void;
 export declare function getPlanningDir(projectRoot: string): string;
+/**
+ * Get the Graphiti group id for project-specific episodes.
+ *
+ * Resolution order:
+ *   1. .indusk/config.json `graphiti.groupId` if set
+ *   2. Project directory basename
+ *
+ * Use `[getProjectGroupId(root), "shared"]` as the default group_ids list when
+ * searching Graphiti — this gives both project-scoped and cross-project knowledge.
+ */
+export declare function getProjectGroupId(projectRoot: string): string;
+/**
+ * Whether the OTel gate should fire for this project.
+ *
+ * Returns `true` if `.indusk/config.json` is missing, missing `otel.role`, or
+ * has `otel.role: "service"`. Returns `false` only when the project explicitly
+ * opts out via `otel.role: "library" | "tool" | "none"`.
+ *
+ * Used by:
+ *   - planner skill (whether to write `#### Phase N OTel` sections into impl.md)
+ *   - validate-impl-structure hook (whether to require an OTel section at write time)
+ *   - check-gates hook (whether to block phase advancement on missing OTel)
+ *
+ * Backwards compatible: projects without the new field behave exactly as before.
+ */
+export declare function shouldEmitOtelGate(projectRoot: string): boolean;

package/dist/lib/config.js

@@ -1,5 +1,5 @@
 import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
-import { dirname, join } from "node:path";
+import { basename, dirname, join } from "node:path";
 const CONFIG_PATH = ".indusk/config.json";
 export function getConfigPath(projectRoot) {
     return join(projectRoot, CONFIG_PATH);
@@ -26,3 +26,38 @@ export function getPlanningDir(projectRoot) {
     // Default to new path (will be created by init)
     return newPath;
 }
+/**
+ * Get the Graphiti group id for project-specific episodes.
+ *
+ * Resolution order:
+ *   1. .indusk/config.json `graphiti.groupId` if set
+ *   2. Project directory basename
+ *
+ * Use `[getProjectGroupId(root), "shared"]` as the default group_ids list when
+ * searching Graphiti — this gives both project-scoped and cross-project knowledge.
+ */
+export function getProjectGroupId(projectRoot) {
+    const config = readConfig(projectRoot);
+    if (config?.graphiti?.groupId)
+        return config.graphiti.groupId;
+    return basename(projectRoot);
+}
+/**
+ * Whether the OTel gate should fire for this project.
+ *
+ * Returns `true` if `.indusk/config.json` is missing, missing `otel.role`, or
+ * has `otel.role: "service"`. Returns `false` only when the project explicitly
+ * opts out via `otel.role: "library" | "tool" | "none"`.
+ *
+ * Used by:
+ *   - planner skill (whether to write `#### Phase N OTel` sections into impl.md)
+ *   - validate-impl-structure hook (whether to require an OTel section at write time)
+ *   - check-gates hook (whether to block phase advancement on missing OTel)
+ *
+ * Backwards compatible: projects without the new field behave exactly as before.
+ */
+export function shouldEmitOtelGate(projectRoot) {
+    const config = readConfig(projectRoot);
+    const role = config?.otel?.role;
+    return role === undefined || role === "service";
+}

package/dist/lib/extension-loader.d.ts

@@ -53,6 +53,7 @@ export interface ExtensionManifest {
         headers?: Record<string, string>;
         env?: Record<string, string>;
         env_from_shell?: string[];
+        add_command?: string;
         setup_instructions?: string[];
     };
 }

package/dist/lib/extension-loader.js

@@ -100,10 +100,7 @@ function loadFromDir(baseDir, enabled) {
 export function loadExtensions(projectRoot) {
     const dir = extensionsDir(projectRoot);
     const disDir = disabledDir(projectRoot);
-    return [
-        ...loadFromDir(dir, true),
-        ...loadFromDir(disDir, false),
-    ];
+    return [...loadFromDir(dir, true), ...loadFromDir(disDir, false)];
 }
 export function getEnabledExtensions(projectRoot) {
     return loadExtensions(projectRoot).filter((e) => e.enabled);

package/extensions/excalidraw/manifest.json

@@ -7,8 +7,6 @@
 	"mcp_server": {
 		"type": "http",
 		"url": "https://mcp.excalidraw.com",
-		"setup_instructions": [
-			"claude mcp add -t http -- excalidraw https://mcp.excalidraw.com"
-		]
+		"setup_instructions": ["claude mcp add -t http -- excalidraw https://mcp.excalidraw.com"]
 	}
 }

package/extensions/graphiti/manifest.json

@@ -18,6 +18,16 @@
 			}
 		]
 	},
+	"mcp_server": {
+		"type": "http",
+		"url": "http://localhost:8100/mcp",
+		"add_command": "claude mcp add -t http -s project graphiti http://localhost:8100/mcp",
+		"setup_instructions": [
+			"Registered automatically by `indusk init` and re-added by `indusk update` if missing.",
+			"The Graphiti MCP server runs inside the `indusk-infra` container on port 8100.",
+			"Exposes 9 tools: add_memory, search_nodes, search_memory_facts, get_episodes, get_entity_edge, delete_episode, delete_entity_edge, clear_graph, get_status."
+		]
+	},
 	"detect": {
 		"command": "docker inspect --format='{{.State.Running}}' indusk-infra 2>/dev/null | grep true"
 	}

package/extensions/graphiti/skill.md

@@ -2,16 +2,32 @@
 
 Graphiti is an episodic memory system backed by FalkorDB. It extracts entities and facts from text, detects contradictions, and supports semantic search across project-specific and shared knowledge.
 
+The Graphiti MCP server runs inside the `indusk-infra` container on `http://localhost:8100/mcp` and is registered automatically by `indusk init`. The agent has direct access via `mcp__graphiti__*` tools — there is no wrapping layer.
+
 ## When to Use
 
-- **Episode capture**: After a decision, retro finding, or correction — anything worth remembering across sessions
+- **Capture**: After a decision, retro finding, or correction — anything worth remembering across sessions
 - **Search**: Before making assumptions — check what's already known about a topic
-- **Context retrieval**: At session start or when working in an unfamiliar area
+- **Recall**: At session start (`/catchup` does this automatically) or when working in an unfamiliar area
+
+## Tools
+
+The agent has nine `mcp__graphiti__*` tools. The five you'll use most:
+
+| Tool | Purpose |
+|------|---------|
+| `add_memory` | Capture an episode (text/JSON/message) — entities and facts are extracted asynchronously |
+| `search_nodes` | Find entities by natural-language query |
+| `search_memory_facts` | Find facts (relationships between entities) by query |
+| `get_episodes` | List recent episodes by group |
+| `get_status` | Check that Graphiti is reachable and the database is healthy |
+
+The other four (`delete_episode`, `delete_entity_edge`, `get_entity_edge`, `clear_graph`) are for cleanup — use sparingly, never in normal flow.
 
 ## Core Concepts
 
 ### Episodes
-An episode is a chunk of text that Graphiti processes into entities and facts. Think of it as "something that happened" — a decision was made, a bug was found, a convention was established.
+An episode is a chunk of text that Graphiti processes into entities and facts. Think of it as "something that happened" — a decision was made, a bug was found, a convention was established. Episodes are processed in the background; entities appear in search results once extraction completes (a few seconds).
 
 ### Group IDs
 Every episode belongs to a group. Groups isolate knowledge:
@@ -21,54 +37,123 @@ Every episode belongs to a group. Groups isolate knowledge:
 | `{project-name}` | Project-specific knowledge | `infinitedusky`, `numero` |
 | `shared` | Cross-project conventions | Developer preferences, universal patterns |
 
-When searching, always include both the project group and `shared` to get the full picture. The `GraphitiClient` does this automatically.
+When searching, always include both the project group and `shared` to get the full picture. Use `getProjectGroupId(projectRoot)` (from `apps/indusk-mcp/src/lib/config.ts`) to get the project group consistently — it reads `.indusk/config.json` `graphiti.groupId` if set, otherwise falls back to the project directory basename.
 
 ### Entities and Facts
 Graphiti extracts:
 - **Entities**: Named things (tools, patterns, files, concepts)
 - **Facts**: Relationships between entities with temporal validity
 
-Facts can be contradicted — if you add "the parser handles three gate types" and later "the parser handles four gate types", Graphiti invalidates the old fact.
+Facts can be contradicted — if you add "the parser handles three gate types" and later "the parser handles four gate types", Graphiti invalidates the old fact. The contradicted fact gets `invalid_at` set; the new one gets `valid_at` set. Search results respect this — invalid facts are excluded by default.
 
 ## Patterns
 
 ### Capturing a Decision
-After an ADR is accepted or a significant choice is made:
+
+After an ADR is accepted or a significant choice is made, the planner skill calls this automatically. To do it manually:
+
 ```
-addEpisode("auth-approach-decision", 
-  "We chose JWT with refresh tokens over session cookies because the API serves both web and mobile clients. Session cookies don't work well with React Native.",
-  { groupId: "myproject" })
+mcp__graphiti__add_memory({
+  name: "auth-approach-decision",
+  episode_body: "We chose JWT with refresh tokens over session cookies because the API serves both web and mobile clients. Session cookies don't work well with React Native.",
+  group_id: "myproject",
+  source: "text",
+  source_description: "ADR"
+})
 ```
 
+The `name` should be short and topical — the agent uses it as a handle when re-discussing the decision. The `episode_body` should be detailed enough that someone reading it cold understands the decision and the reasoning.
+
 ### Capturing a Correction
-When someone corrects the agent or a mistake is found:
+
+When the user corrects the agent, the work skill prompts `context learn` AND captures the correction as an episode:
+
 ```
-addEpisode("correction-test-database",
-  "Integration tests must use a real database, not mocks. We got burned when mocked tests passed but the production migration failed.",
-  { groupId: "shared" })
+mcp__graphiti__add_memory({
+  name: "correction-pnpm-ce",
+  episode_body: "Always use `pnpm ce`, never `npx ce`. The composable.env skill specifies pnpm and the project's package.json maps `ce` to the binary. npx invokes a different code path.",
+  group_id: "shared",
+  source: "text",
+  source_description: "user correction"
+})
 ```
 
+Choosing `shared` vs project group:
+- **`shared`**: tools, conventions, patterns that apply across projects ("always use pnpm ce", "never mock the database in integration tests")
+- **`{project-name}`**: facts specific to one project's code, data, or domain ("the impl-parser handles four gate types per phase", "the bet matching engine is order-book based")
+
+When in doubt, ask: "Would this correction make sense to a different project?" Yes → `shared`. No → project group.
+
 ### Searching Before Acting
+
 Before making assumptions about how something works:
+
 ```
-searchNodes("authentication middleware")
-searchFacts("how does auth work in this project")
+mcp__graphiti__search_nodes({
+  query: "authentication middleware",
+  group_ids: ["myproject", "shared"],
+  max_nodes: 10
+})
+
+mcp__graphiti__search_memory_facts({
+  query: "how does auth work in this project",
+  group_ids: ["myproject", "shared"],
+  max_facts: 10
+})
 ```
 
+Always search both the project group and `shared` — knowledge is split across them. The wrapper class `GraphitiClient` in `apps/indusk-mcp/src/lib/graphiti-client.ts` does this automatically when called internally; agents calling `mcp__graphiti__*` tools directly need to pass both group ids in the request.
+
 ### Capturing a Retrospective Finding
-After a plan retrospective surfaces a useful insight:
+
+After a plan retrospective surfaces a useful insight, the retrospective skill captures it as an episode:
+
+```
+mcp__graphiti__add_memory({
+  name: "retro-gate-enforcement-1",
+  episode_body: "Plan gates need hook-based enforcement, not just instructions. The agent skipped gates when they were advisory only. PreToolUse hooks that block phase transitions are the fix.",
+  group_id: "infinitedusky",
+  source: "text",
+  source_description: "retrospective insight"
+})
+```
+
+One episode per insight, named `retro-{plan}-{n}`. If the retro surfaces a contradiction (we thought X, found Y), capture both framings as separate episodes — Graphiti's contradiction detection invalidates the older one.
+
+### Recall at Session Start
+
+The `/catchup` skill calls this automatically after reading project context, but you can also trigger it manually:
+
 ```
-addEpisode("retro-gate-enforcement",
-  "Plan gates need hook-based enforcement, not just instructions. The agent skipped gates when they were advisory only. PreToolUse hooks that block phase transitions are the fix.",
-  { groupId: "myproject" })
+mcp__graphiti__search_nodes({
+  query: "recent decisions",
+  group_ids: ["myproject", "shared"],
+  max_nodes: 5
+})
 ```
 
+Surface anything notable to the user. Pay extra attention to facts where `invalid_at` is recent — those are areas where prior decisions changed and active plans may be working from stale assumptions.
+
+## Capture Triggers (Where Episodes Come From)
+
+In normal workflow, episodes are written automatically by other skills. The agent rarely calls `add_memory` directly:
+
+| Trigger | Skill | Episode |
+|---------|-------|---------|
+| Brief accepted | `planner` | `brief-accepted-{plan}` — Problem + Proposed Direction in project group |
+| ADR accepted | `planner` | `adr-{plan}` — Y-statement in project group |
+| User correction (`context learn`) | `work` | `correction-{slug}` — lesson body in `shared` or project group |
+| Retrospective lesson | `retrospective` | `retro-{plan}-{n}` — one per insight in project group |
+| Retrospective "would do differently" | `retrospective` | `retro-{plan}-wdid-{n}` — one per item in project group |
+
+The agent should call `add_memory` directly **only** when something worth remembering happens outside these trigger points. Most of the time, just trust the skills to capture and let `/catchup` recall.
+
 ## What NOT to Capture
 
-- Code structure (CGC handles this)
-- Git history (git log handles this)
-- Ephemeral state (current task, in-progress work)
-- Things already in CLAUDE.md or lessons
+- **Code structure** — CGC handles this. `function X calls function Y` is a graph relationship, not an episode.
+- **Git history** — `git log` is authoritative.
+- **Ephemeral state** — current task, in-progress work, todo lists. Use the TodoWrite tool, not Graphiti.
+- **Things already in CLAUDE.md or lessons** — those layers exist for stable, project-wide truths. Graphiti is for things that have temporal context and might be contradicted.
 
 Graphiti is for knowledge that has temporal context — decisions that might change, facts that might be contradicted, insights that accumulate over time.
 
@@ -86,6 +171,13 @@ Global config (API keys, OTel): `~/.indusk/config.env`
 
 ### Graceful Degradation
 If the `indusk-infra` container is down:
-- CGC graph tools still check FalkorDB directly
-- Graphiti client methods return null/empty (never throw)
-- The agent continues working with flat-file context (CLAUDE.md, lessons, skills)
+- `mcp__graphiti__*` tools will report a clean error (the MCP transport fails to connect)
+- The agent should fall back to flat-file context (CLAUDE.md, lessons, skills) and continue working
+- The `GraphitiClient` wrapper class (used internally by indusk-mcp) returns null/empty instead of throwing
+- Don't pretend the call succeeded — if Graphiti is down, capture is lost. Tell the user to `indusk infra start`.
+
+### Health Check
+```
+mcp__graphiti__get_status({})
+```
+Returns `{ status: "healthy", message: "..." }` when Graphiti is reachable and the database is connected.

package/hooks/check-gates.js

@@ -2,11 +2,16 @@
 /**
  * PreToolUse hook: blocks phase transitions in impl.md when gates are incomplete.
  *
+ * The OTel gate is conditional on the project's `otel.role` in .indusk/config.json:
+ *   - unset or "service": OTel gate is enforced (default)
+ *   - "library" / "tool" / "none": OTel gate is silenced (mirrors validate-impl-structure)
+ *
  * Exit 0 = allow the edit
  * Exit 2 = block the edit (stderr sent to agent as feedback)
  */
 
-import { readFileSync } from "node:fs";
+import { existsSync, readFileSync } from "node:fs";
+import { resolve } from "node:path";
 
 // Read hook input from stdin
 let input = "";
@@ -115,14 +120,57 @@ function detectWorkflow(content) {
 	return m ? m[1] : "feature";
 }
 
-// Which gate types are required per workflow
-const WORKFLOW_GATES = {
+/**
+ * Find the project root by walking up from a starting directory looking for
+ * a .indusk/ or .claude/ directory. Falls back to startDir if none found.
+ */
+function findProjectRoot(startDir) {
+	let dir = startDir;
+	for (let i = 0; i < 10; i++) {
+		if (existsSync(`${dir}/.indusk`) || existsSync(`${dir}/.claude`)) return dir;
+		const parent = resolve(dir, "..");
+		if (parent === dir) break;
+		dir = parent;
+	}
+	return startDir;
+}
+
+/**
+ * Whether the OTel gate should fire for this project. Reads .indusk/config.json
+ * and checks otel.role. Returns true if missing/unset/"service", false for
+ * library/tool/none. Mirrors shouldEmitOtelGate() in apps/indusk-mcp/src/lib/config.ts.
+ */
+function shouldEmitOtelGate(projectRoot) {
+	const configPath = `${projectRoot}/.indusk/config.json`;
+	if (!existsSync(configPath)) return true;
+	try {
+		const config = JSON.parse(readFileSync(configPath, "utf-8"));
+		const role = config?.otel?.role;
+		return role === undefined || role === "service";
+	} catch {
+		return true;
+	}
+}
+
+const projectRoot = findProjectRoot(event.cwd ?? process.cwd());
+const otelGateEnabled = shouldEmitOtelGate(projectRoot);
+
+// Which gate types are required per workflow.
+// OTel is filtered out below when the project opts out via otel.role.
+const WORKFLOW_GATES_BASE = {
 	feature: ["verification", "otel", "context", "document"],
 	refactor: ["verification", "otel", "context", "document"],
 	bugfix: ["verification", "document"],
 	spike: [],
 };
 
+const WORKFLOW_GATES = Object.fromEntries(
+	Object.entries(WORKFLOW_GATES_BASE).map(([wf, gates]) => [
+		wf,
+		otelGateEnabled ? gates : gates.filter((g) => g !== "otel"),
+	]),
+);
+
 // Parse phases from the NEW content (after edit) and OLD content (before edit)
 function parsePhases(content) {
 	// Strip frontmatter

package/hooks/validate-impl-structure.js

@@ -2,14 +2,20 @@
 /**
  * PreToolUse hook: validates that impl phases have all four gate sections.
  *
- * Every phase must have: implementation items, Verification, OTel, Context, Document.
+ * Every phase must have: implementation items, Verification, OTel*, Context, Document.
  * Sections can opt out with (none needed), (not applicable), or skip-reason: {why}.
  *
+ * *OTel section is conditional on the project's `otel.role` in .indusk/config.json:
+ *   - unset or "service": OTel section is required (default behavior)
+ *   - "library" / "tool" / "none": OTel section is NOT required (gate silenced)
+ * This mirrors `shouldEmitOtelGate()` in apps/indusk-mcp/src/lib/config.ts.
+ *
  * Exit 0 = allow the edit
  * Exit 2 = block the edit (stderr sent to agent as feedback)
  */
 
-import { readFileSync } from "node:fs";
+import { existsSync, readFileSync } from "node:fs";
+import { resolve } from "node:path";
 
 // Read hook input from stdin
 let input = "";
@@ -26,6 +32,43 @@ if (!filePath.endsWith("/impl.md") && !filePath.endsWith("\\impl.md")) {
 	process.exit(0);
 }
 
+/**
+ * Find the project root by walking up from a starting directory looking for
+ * a .indusk/ or .claude/ directory. Falls back to event.cwd if none found.
+ * Mirrors the pattern used in check-catchup.js.
+ */
+function findProjectRoot(startDir) {
+	let dir = startDir;
+	for (let i = 0; i < 10; i++) {
+		if (existsSync(`${dir}/.indusk`) || existsSync(`${dir}/.claude`)) return dir;
+		const parent = resolve(dir, "..");
+		if (parent === dir) break;
+		dir = parent;
+	}
+	return startDir;
+}
+
+/**
+ * Whether the OTel gate should fire for this project. Reads .indusk/config.json
+ * and checks otel.role. Returns true if the config is missing, if otel.role is
+ * unset, or if otel.role is "service" — matches shouldEmitOtelGate() in
+ * apps/indusk-mcp/src/lib/config.ts exactly.
+ */
+function shouldEmitOtelGate(projectRoot) {
+	const configPath = `${projectRoot}/.indusk/config.json`;
+	if (!existsSync(configPath)) return true;
+	try {
+		const config = JSON.parse(readFileSync(configPath, "utf-8"));
+		const role = config?.otel?.role;
+		return role === undefined || role === "service";
+	} catch {
+		return true; // on parse error, preserve default behavior
+	}
+}
+
+const projectRoot = findProjectRoot(event.cwd ?? process.cwd());
+const otelGateEnabled = shouldEmitOtelGate(projectRoot);
+
 // Check for skip-gates escape hatch
 const newContent = toolInput.new_string ?? toolInput.content ?? "";
 
@@ -100,10 +143,13 @@ const body = fmMatch ? newFullContent.slice(fmMatch[0].length) : newFullContent;
 const workflowMatch = frontmatter.match(/workflow:\s*(bugfix|refactor|feature|spike)/);
 const workflow = workflowMatch ? workflowMatch[1] : "feature";
 
-// Different workflows have different requirements
+// Different workflows have different requirements.
+// OTel is further gated on the project's `otel.role` in .indusk/config.json —
+// libraries/tools/none opt out of the OTel gate entirely. Workflows that normally
+// require OTel (feature, refactor) will only require it when otelGateEnabled is true.
 const requirements = {
-	feature: { verification: true, otel: true, context: true, document: true },
-	refactor: { verification: true, otel: true, context: true, document: true },
+	feature: { verification: true, otel: otelGateEnabled, context: true, document: true },
+	refactor: { verification: true, otel: otelGateEnabled, context: true, document: true },
 	bugfix: { verification: true, otel: false, context: false, document: true },
 	spike: { verification: false, otel: false, context: false, document: false },
 }[workflow];

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@infinitedusky/indusk-mcp",
-	"version": "1.9.4",
+	"version": "1.10.1",
 	"description": "InDusk development system — skills, MCP tools, and CLI for structured AI-assisted development",
 	"type": "module",
 	"files": [

package/skills/catchup.md

@@ -64,6 +64,29 @@ Read it fully. Don't skim.
 
 **After reading, edit the handoff to check off:** `- [x] context`
 
+### 4.5. Recall from Graphiti
+
+CLAUDE.md is the stable, slow-changing layer of project memory. Graphiti is the fast, temporal layer — it captures decisions, corrections, and retrospective insights as they happen. Catchup pulls both layers so the agent starts the session with full context.
+
+**Recall recent decisions and lessons:**
+```
+mcp__graphiti__search_nodes({
+  query: "recent decisions and lessons",
+  group_ids: ["{project-group}", "shared"],
+  max_nodes: 8
+})
+```
+
+The project group comes from the `getProjectGroupId(projectRoot)` helper (in `apps/indusk-mcp/src/lib/config.ts`). Always include both the project group and `shared` so cross-project conventions surface alongside project-specific knowledge.
+
+**Surface contradictions:** look at the returned nodes for any whose `attributes` reference recently invalidated facts (Graphiti marks superseded facts with `invalid_at`). If a recently invalidated fact relates to an active plan or current code area, flag it to the user — those are places where assumptions changed.
+
+**Output format:** include a "Graphiti recall" section in the catchup summary with the most relevant 3-5 nodes by name + summary. Don't dump everything — surface what's actionable.
+
+**Graceful degradation:** If `mcp__graphiti__search_nodes` is unavailable (Graphiti container down, transport error), skip this step silently and add a note to the catchup summary: `Graphiti: unavailable (run \`indusk infra start\` to recall episodic memory)`. Catchup should not fail if Graphiti is down — the rest of the layers are still valid.
+
+**After completing recall, edit the handoff to check off:** `- [x] graphiti` (added to the catchup status box section)
+
 ### 5. Check Active Plans
 Call `list_plans`. This shows every plan and its status. Pay attention to:
 - Plans with status `in-progress` — these are actively being worked on
@@ -104,6 +127,7 @@ After completing all steps, present a brief summary to the user:
 - Extensions: N enabled [list names]
 - Active plans: [list with current phase]
 - Codebase: [N files indexed]
+- Graphiti recall: [3-5 most relevant nodes by name + summary, or "unavailable" if Graphiti is down]
 
 Ready to pick up. What would you like to do?
 ```

package/skills/planner.md

@@ -74,8 +74,32 @@ Workflow templates are in `templates/workflows/` in the package. They describe w
 
 4. **If research is done**, write the brief. This is where a direction emerges from the research. The brief proposes what we're building and why, informed by what the research uncovered. **Consider creating a visual sketch** of the proposed architecture with Excalidraw (if the extension is enabled) — a hand-drawn diagram makes the proposal concrete and easier to discuss. **Present the brief and have a conversation about it.** Don't just ask "does this look good?" — walk the user through it: "Here's what I'm proposing we build. Does this match what you had in mind? Is there anything missing, or anything here you don't want?" Iterate until the user is genuinely happy with the direction, then mark it as `accepted`.
 
+   **When the brief moves from `draft` to `accepted`**, capture the decision in Graphiti:
+   ```
+   mcp__graphiti__add_memory({
+     name: "brief-accepted-{plan-name}",
+     episode_body: "{Problem}\n\n{Proposed Direction}\n\n{Scope summary if helpful}",
+     group_id: "{project-group}",
+     source: "text",
+     source_description: "brief acceptance"
+   })
+   ```
+   The `group_id` is the project group (use `getProjectGroupId(projectRoot)` from `apps/indusk-mcp/src/lib/config.ts` — defaults to project directory basename, override via `.indusk/config.json` `graphiti.groupId`). Skip silently if `mcp__graphiti__add_memory` is unavailable (Graphiti may be down — degrade gracefully, do not fail the brief acceptance).
+
 5. **If brief is accepted** and the workflow includes an ADR (feature only), write the ADR. The ADR formalizes the decisions that were discussed during research and led to the brief. It records what was chosen, what was rejected, and why. **After the ADR is accepted**, add a one-liner to CLAUDE.md's Key Decisions section per the context skill: `- {decision summary} — see .indusk/planning/{plan}/adr.md`
 
+   **When the ADR moves from `proposed` to `accepted`**, capture the Y-statement in Graphiti:
+   ```
+   mcp__graphiti__add_memory({
+     name: "adr-{plan-name}",
+     episode_body: "In the context of {use case}, facing {constraint}, we decided for {chosen option} and against {rejected alternatives}, to achieve {desired outcome}, accepting {tradeoff}, because {rationale}.",
+     group_id: "{project-group}",
+     source: "text",
+     source_description: "ADR acceptance"
+   })
+   ```
+   The Y-statement is rich enough that Graphiti will extract entities for the chosen option, rejected alternatives, constraint, and rationale — and will detect contradictions if a later ADR overrides this one. Skip silently on Graphiti unavailability.
+
 6. **If ADR is accepted** (or brief is accepted for bugfix/refactor), write the impl. Break into phased checklists with concrete tasks. For refactor workflows, include a `## Boundary Map` section. For multi-phase impls of any type, consider adding a boundary map.
 
    **Gate policy applies when writing impls.** Set `gate_policy` in the impl frontmatter (`strict`, `ask`, or `auto`). The `validate-impl-structure` hook enforces this at write time:
@@ -84,6 +108,8 @@ Workflow templates are in `templates/workflows/` in the package. They describe w
 
    Default is `ask`. See the work skill "Gate Override Policy" for full details on what each mode enforces at execution time.
 
+   **OTel gate is conditional on `otel.role`.** Read `.indusk/config.json` for the project's `otel.role` field (or use the `shouldEmitOtelGate(projectRoot)` helper from `apps/indusk-mcp/src/lib/config.ts`). The OTel gate fires for projects whose `otel.role` is unset or `"service"` — these are user-facing apps that produce telemetry you want to collect. **Do NOT write `#### Phase N OTel` sections** for projects whose `otel.role` is `"library"`, `"tool"`, or `"none"` — these are libraries, CLIs, or scripts that should never emit telemetry and writing OTel gates for them is friction without value. The `validate-impl-structure` and `check-gates` hooks apply the same rule. The other gates (verify, context, document) always apply regardless of `otel.role`.
+
 7. **If impl is completed** (all items checked off by `/work`), invoke the retrospective skill (`/retrospective {plan-name}`). This handles the structured audit (docs, tests, quality, context), knowledge handoff to the docs site, and archival. Do not write a freeform retrospective — use the skill. (Bugfix and refactor workflows may skip retrospective for small changes — user's call.)
 
 8. **Always present each document for review** before moving to the next stage. The user signs off on each step.
@@ -256,6 +282,8 @@ For multi-phase impls, include a boundary map showing what each phase produces a
   function withdrawFor(wallet: address, player: address, amount: uint256, historyHash: bytes32)
   ```
 
+{OPTIONAL: #### Phase 1 OTel — include ONLY if the project's `otel.role` in `.indusk/config.json` is unset or `"service"`. Skip the entire OTel block for projects with `otel.role: "library" | "tool" | "none"`. Use `shouldEmitOtelGate(projectRoot)` from `apps/indusk-mcp/src/lib/config.ts` to decide.}
+
 #### Phase 1 OTel
 - [ ] {Instrumentation check — are new code paths observable? See the OTel skill for patterns. Example items: "New endpoints have manual spans with `otel.category` and domain attributes", "Errors recorded with `recordException` + `setStatus(ERROR)` + trace-correlated log". Ask: "did this phase add endpoints, business logic, state transitions, or error paths?" If not, this section can be opted out per gate policy.}
 

package/skills/retrospective.md

@@ -91,6 +91,36 @@ If yes, call `add_lesson` for each one. These become personal lessons in `.claud
 
 If no lessons emerged, that's fine — not every plan produces new knowledge. Move on.
 
+**Also capture each retrospective insight in Graphiti** so it becomes part of the temporal knowledge graph and can surface in future searches and contradictions.
+
+For each item in the retrospective's **What We Learned** section:
+```
+mcp__graphiti__add_memory({
+  name: "retro-{plan-name}-{n}",
+  episode_body: "{the full insight, including context — not just a one-line summary}",
+  group_id: "{project-group}",
+  source: "text",
+  source_description: "retrospective lesson"
+})
+```
+
+For each item in the retrospective's **What We'd Do Differently** section:
+```
+mcp__graphiti__add_memory({
+  name: "retro-{plan-name}-wdid-{n}",
+  episode_body: "{the hindsight item, with reasoning}",
+  group_id: "{project-group}",
+  source: "text",
+  source_description: "retrospective hindsight"
+})
+```
+
+Use the project group (from `getProjectGroupId(projectRoot)`) — most retrospective insights are project-specific. Promote to `shared` only if the insight is clearly cross-project (those should also become a personal lesson via `add_lesson`).
+
+**Contradictions:** If the retrospective surfaces a moment where "we thought X but found Y", capture both as separate episodes. Graphiti's contradiction detection will invalidate the older fact when it sees the conflicting one. This is one of Graphiti's most useful features — it remembers that a previous assumption was overturned, so the agent doesn't accidentally re-introduce it later.
+
+Skip silently if `mcp__graphiti__add_memory` is unavailable — Graphiti capture is best-effort, and lesson recording via `add_lesson` is the canonical path. Graphiti capture is supplementary.
+
 ### Step 7: Context Audit
 
 Re-read CLAUDE.md in full. After the entire impl is done, verify:

package/skills/work.md

@@ -202,6 +202,27 @@ When you are corrected mid-work — the user says "no, not that way" or "don't d
 
 Don't wait to be told. Corrections are the most valuable source of project knowledge.
 
+**When the user confirms `context learn`, ALSO capture the correction in Graphiti:**
+```
+mcp__graphiti__add_memory({
+  name: "correction-{slug}",
+  episode_body: "{lesson text}",
+  group_id: "{shared OR project-group}",
+  source: "text",
+  source_description: "user correction"
+})
+```
+
+Where `{slug}` is a short kebab-case label for the topic (e.g. `correction-pnpm-ce`, `correction-graphiti-error-handling`).
+
+**Choosing `shared` vs project group:**
+- **`shared`**: tools, conventions, patterns that apply across projects. Examples: "always use pnpm ce", "never mock the database in integration tests", "use jj describe-then-do for commits". The lesson is generally true and a different project would benefit from it.
+- **`{project-group}`**: facts specific to this project's code, data, or domain. Examples: "the impl-parser handles four gate types per phase", "graph_ensure auto-repairs the indusk-infra container". The lesson only makes sense in the context of this project.
+
+When in doubt, ask: "Would this correction make sense to a different project?" Yes → `shared`. No → project group.
+
+Use `getProjectGroupId(projectRoot)` from `apps/indusk-mcp/src/lib/config.ts` to get the project group consistently. Skip silently if `mcp__graphiti__add_memory` is unavailable — Graphiti capture is best-effort, do not fail the work item.
+
 ## Commits (jj)
 
 Use the **describe-then-do** workflow from the jj skill: