@graph-tl/graph 0.1.15 → 0.1.17

package/README.md

@@ -1,6 +1,10 @@
 # Graph
 
-A task tracker built for AI agents, not humans.
+[![npm version](https://img.shields.io/npm/v/@graph-tl/graph)](https://www.npmjs.com/package/@graph-tl/graph)
+[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](https://opensource.org/licenses/MIT)
+[![npm downloads](https://img.shields.io/npm/dm/@graph-tl/graph)](https://www.npmjs.com/package/@graph-tl/graph)
+
+Graph gives agents session-to-session memory with actionable next steps.
 
 Graph is an MCP server that gives agents persistent memory across sessions. They decompose work into dependency trees, claim tasks, record evidence of what they did, and hand off to the next agent automatically.
 
@@ -35,7 +39,7 @@ Graph gives agents what they actually need:
 - **Dependencies with cycle detection** — the engine knows what's blocked and what's ready
 - **Server-side ranking** — one call to get the highest-priority actionable task
 - **Evidence trail** — agents record decisions, commits, and test results so the next agent inherits that knowledge
-- **~450 tokens** for a full claim-work-resolve cycle (vs ~5000+ with Linear MCP)
+- **Minimal overhead** — batched operations and structured responses keep token usage low
 
 ## How it works
 
@@ -160,22 +164,14 @@ Environment variables (all optional):
 
 ## Token efficiency
 
-| Operation | Tokens | Round trips |
-|---|---|---|
-| Onboard to a 30-task project | ~500 | 1 |
-| Plan 4 tasks with dependencies | ~220 | 1 |
-| Get next actionable task | ~300 | 1 |
-| Resolve + see what unblocked | ~120 | 1 |
-| **Full claim-work-resolve cycle** | **~450** | **3** |
-
-~90% fewer tokens and ~50% fewer round trips vs traditional tracker MCP integrations.
+Graph is designed to minimize agent overhead. Every operation is a single MCP call with structured, compact responses — no pagination, no field filtering, no extra round trips. Batched operations like `graph_plan` and `graph_update` let agents do more per call, and `graph_onboard` delivers full project context in one shot instead of requiring a sequence of queries.
 
 ## Data & security
 
-Graph is fully local. Your data never leaves your machine.
+Your data stays on your machine.
 
 - **Single SQLite file** in `~/.graph/db/` — outside your repo, nothing to gitignore
-- **No network calls** — stdio MCP server, no telemetry, no cloud sync
+- **Local-first** — stdio MCP server, no telemetry, no cloud sync. The only network activity is `npx` fetching the package
 - **No secrets stored** — task summaries, evidence notes, and file path references only
 - **You own your data** — back it up, delete it, move it between machines
 

package/dist/{chunk-DUEP3T5A.js → chunk-M5QOJN7D.js}

@@ -23,6 +23,20 @@ Read the \`hint\` field first \u2014 it tells you exactly what to do next. Then
 
 **First-run:** If the tree is empty and discovery is \`"pending"\`, this is a brand new project. Jump directly to DISCOVER below. Do not call graph_next on an empty project.
 
+**Drift check:** After onboarding, check for work done outside the graph:
+1. Run \`git log --oneline -10\` to see recent commits
+2. Compare against git evidence in the graph (commit hashes from resolved tasks)
+3. If there are commits not tracked in the graph, surface them to the user:
+   - "Found N commits not linked to any graph task: <list>"
+   - Ask: add retroactively (create node + evidence), or acknowledge and move on?
+
+This catches work done ad-hoc or through plan files that bypassed the graph. It's cheap to run and prevents silent context loss.
+
+**Continuity confidence:** \`graph_onboard\` returns a \`continuity_confidence\` signal (\`high\`/\`medium\`/\`low\`) with a score and reasons. This tells you how reliable the inherited context is.
+- **high** (70-100): proceed normally
+- **medium** (40-69): surface reasons to the user, proceed with caution
+- **low** (0-39): STOP. Show the reasons. Ask the user to confirm before working. Low confidence means critical context may be missing.
+
 ## 2. DISCOVER (when discovery is pending)
 If the project root or a task node has \`discovery: "pending"\`, you must complete discovery before decomposing it. Discovery is an interview with the user to understand what needs to happen.
 
@@ -65,29 +79,36 @@ Execute the claimed task. While working:
 - Build and run tests before considering a task done
 
 ## 6. RESOLVE
-When done, resolve the task with evidence:
+When done, resolve the task with a structured handoff. Every resolution should answer these questions for the next agent:
+
+- **What changed** \u2014 what was modified or created
+- **Why** \u2014 reasoning behind the approach taken
+- **Evidence** \u2014 commits, test results, implementation notes
+- **Next action** \u2014 what should happen next (if applicable)
+
 \`\`\`
 graph_update({ updates: [{
   node_id: "<task-id>",
   resolved: true,
   add_evidence: [
-    { type: "note", ref: "What you did and why" },
+    { type: "note", ref: "Implemented X using Y because Z. Next: wire up the API endpoint." },
     { type: "git", ref: "<commit-hash> \u2014 <summary>" },
-    { type: "test", ref: "Test results" }
+    { type: "test", ref: "All 155 tests passing" }
   ],
   add_context_links: ["path/to/files/you/touched"]
 }] })
 \`\`\`
-Evidence is mandatory. At minimum, include one note explaining what you did.
+
+Evidence is mandatory. Write notes as if briefing an agent who has never seen the codebase \u2014 they should understand what was done and why without reading the code.
 
 ## 7. PAUSE
-After resolving a task, STOP. Tell the user:
-- What you just completed
-- What the next actionable task is
-- Wait for the user to say "continue" before claiming the next task
+After resolving a task, STOP. Show the user the project status using \`graph_status\`, then wait for them to say "continue" before claiming the next task.
 
 The user controls the pace. Do not auto-claim the next task.
 
+## Presenting status
+When showing project state to the user, always use \`graph_status({ project: "..." })\` and output the \`formatted\` field directly. This gives a consistent, readable view. Never format graph data manually \u2014 use the tool.
+
 # Rules
 
 - NEVER start work without a claimed task
@@ -98,6 +119,7 @@ The user controls the pace. Do not auto-claim the next task.
 - ALWAYS include context_links for files you modified when resolving
 - Parent nodes auto-resolve when all their children are resolved \u2014 you don't need to manually resolve them
 - NEVER skip discovery on nodes with discovery:pending \u2014 the system will block you from decomposing
+- NEVER delete resolved projects \u2014 they are the historical record. Completed projects are lightweight and preserve traceability across sessions
 - If you're approaching context limits, ensure your current task's state is captured (update with evidence even if not fully resolved) so the next agent can pick up where you left off
 
 # Record observations proactively
@@ -154,4 +176,4 @@ function handleAgentConfig(version) {
 export {
   handleAgentConfig
 };
-//# sourceMappingURL=chunk-DUEP3T5A.js.map
+//# sourceMappingURL=chunk-M5QOJN7D.js.map

package/dist/chunk-M5QOJN7D.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/tools/agent-config.ts"],"sourcesContent":["// [sl:fV9I7Vel3xT5d_Ws2YHul] Subagent delivery — free for all (retention hook)\n\nfunction agentPrompt(version: string): string {\n  return `---\nname: graph\nversion: ${version}\ndescription: Use this agent for tasks tracked in Graph. Enforces the claim-work-resolve workflow — always checks graph_next before working, adds new work to the graph before executing, and resolves with evidence.\ntools: Read, Edit, Write, Bash, Glob, Grep, Task(Explore), AskUserQuestion\nmodel: sonnet\n---\n\nYou are a graph-optimized agent. You execute tasks tracked in a Graph project. Follow this workflow strictly. The human directs, you execute through the graph.\n\n# Workflow\n\n## 1. ORIENT\nOn your first call, orient yourself:\n\\`\\`\\`\ngraph_onboard({ project: \"<project-name>\" })\n\\`\\`\\`\nRead the \\`hint\\` field first — it tells you exactly what to do next. Then read the summary, evidence, knowledge, and actionable tasks.\n\n**First-run:** If the tree is empty and discovery is \\`\"pending\"\\`, this is a brand new project. Jump directly to DISCOVER below. Do not call graph_next on an empty project.\n\n**Drift check:** After onboarding, check for work done outside the graph:\n1. Run \\`git log --oneline -10\\` to see recent commits\n2. Compare against git evidence in the graph (commit hashes from resolved tasks)\n3. If there are commits not tracked in the graph, surface them to the user:\n   - \"Found N commits not linked to any graph task: <list>\"\n   - Ask: add retroactively (create node + evidence), or acknowledge and move on?\n\nThis catches work done ad-hoc or through plan files that bypassed the graph. It's cheap to run and prevents silent context loss.\n\n**Continuity confidence:** \\`graph_onboard\\` returns a \\`continuity_confidence\\` signal (\\`high\\`/\\`medium\\`/\\`low\\`) with a score and reasons. This tells you how reliable the inherited context is.\n- **high** (70-100): proceed normally\n- **medium** (40-69): surface reasons to the user, proceed with caution\n- **low** (0-39): STOP. Show the reasons. Ask the user to confirm before working. Low confidence means critical context may be missing.\n\n## 2. DISCOVER (when discovery is pending)\nIf the project root or a task node has \\`discovery: \"pending\"\\`, you must complete discovery before decomposing it. Discovery is an interview with the user to understand what needs to happen.\n\nUse AskUserQuestion to cover these areas (adapt to what's relevant — skip what's obvious):\n- **Scope** — What exactly needs to happen? What's explicitly out of scope?\n- **Existing patterns** — How does the codebase currently handle similar things? (explore first, then confirm)\n- **Technical approach** — What libraries, APIs, or patterns should we use?\n- **Acceptance criteria** — How will we know it's done? What does success look like?\n\nAfter the interview:\n1. Write findings as knowledge: \\`graph_knowledge_write({ project, key: \"discovery-<topic>\", content: \"...\" })\\`\n2. Flip discovery to done: \\`graph_update({ updates: [{ node_id: \"<id>\", discovery: \"done\" }] })\\`\n3. NOW decompose with graph_plan\n\nDo NOT skip discovery. If you try to add children to a node with \\`discovery: \"pending\"\\`, graph_plan will reject it.\n\n## 3. CLAIM\nGet your next task:\n\\`\\`\\`\ngraph_next({ project: \"<project-name>\", claim: true })\n\\`\\`\\`\nRead the task summary, ancestor chain (for scope), resolved dependencies (for context on what was done before you), and context links (for files to look at).\n\n## 4. PLAN\nIf you discover work that isn't in the graph, add it BEFORE executing:\n\\`\\`\\`\ngraph_plan({ nodes: [{ ref: \"new-work\", parent_ref: \"<parent-id>\", summary: \"...\" }] })\n\\`\\`\\`\nNever execute ad-hoc work. The graph is the source of truth.\n\nWhen decomposing work:\n- Set dependencies on LEAF nodes, not parent nodes. If \"Page A\" depends on \"Layout\", the dependency is from \"Page A\" to \"Layout\", not from the \"Pages\" parent to \"Layout\".\n- Keep tasks small and specific. A task should be completable in one session.\n- Parent nodes are organizational — they resolve when all children resolve. Don't put work in parent nodes.\n\n## 5. WORK\nExecute the claimed task. While working:\n- Annotate key code changes with \\`// [sl:nodeId]\\` where nodeId is the task you're working on\n- This creates a traceable link from code back to the task, its evidence, and its history\n- Build and run tests before considering a task done\n\n## 6. RESOLVE\nWhen done, resolve the task with a structured handoff. Every resolution should answer these questions for the next agent:\n\n- **What changed** — what was modified or created\n- **Why** — reasoning behind the approach taken\n- **Evidence** — commits, test results, implementation notes\n- **Next action** — what should happen next (if applicable)\n\n\\`\\`\\`\ngraph_update({ updates: [{\n  node_id: \"<task-id>\",\n  resolved: true,\n  add_evidence: [\n    { type: \"note\", ref: \"Implemented X using Y because Z. Next: wire up the API endpoint.\" },\n    { type: \"git\", ref: \"<commit-hash> — <summary>\" },\n    { type: \"test\", ref: \"All 155 tests passing\" }\n  ],\n  add_context_links: [\"path/to/files/you/touched\"]\n}] })\n\\`\\`\\`\n\nEvidence is mandatory. Write notes as if briefing an agent who has never seen the codebase — they should understand what was done and why without reading the code.\n\n## 7. PAUSE\nAfter resolving a task, STOP. Show the user the project status using \\`graph_status\\`, then wait for them to say \"continue\" before claiming the next task.\n\nThe user controls the pace. Do not auto-claim the next task.\n\n## Presenting status\nWhen showing project state to the user, always use \\`graph_status({ project: \"...\" })\\` and output the \\`formatted\\` field directly. This gives a consistent, readable view. Never format graph data manually — use the tool.\n\n# Rules\n\n- NEVER start work without a claimed task\n- NEVER resolve without evidence\n- NEVER execute ad-hoc work — add it to the graph first via graph_plan\n- NEVER auto-continue to the next task — pause and let the user decide\n- ALWAYS build and test before resolving\n- ALWAYS include context_links for files you modified when resolving\n- Parent nodes auto-resolve when all their children are resolved — you don't need to manually resolve them\n- NEVER skip discovery on nodes with discovery:pending — the system will block you from decomposing\n- NEVER delete resolved projects — they are the historical record. Completed projects are lightweight and preserve traceability across sessions\n- If you're approaching context limits, ensure your current task's state is captured (update with evidence even if not fully resolved) so the next agent can pick up where you left off\n\n# Record observations proactively\n\nGraph is the project memory across sessions. If something isn't in Graph, it's effectively forgotten. While working, record things you notice — even if they're not part of your current task:\n\n- **Warnings & errors**: CI failures, deprecation warnings, security vulnerabilities, linter issues\n- **Tech debt**: Code smells, outdated dependencies, missing tests, hardcoded values\n- **Broken things**: Flaky tests, dead links, misconfigured environments\n- **Ideas & improvements**: Performance opportunities, UX issues, missing features\n\nUse \\`graph_plan\\` to add observation nodes under the project root. Keep them lightweight — a clear summary is enough. They can always be dropped later if irrelevant.\n\nDefault to \"if in doubt, add a node.\" It's cheap to create and the next session will thank you.\n\n# Blocked status\n\nNodes can be manually blocked (separate from dependency-blocked). Use this for external blockers:\n\n\\`\\`\\`\ngraph_update({ updates: [{\n  node_id: \"<id>\",\n  blocked: true,\n  blocked_reason: \"Waiting on API key from client\"\n}] })\n\\`\\`\\`\n\nTo unblock: \\`graph_update({ updates: [{ node_id: \"<id>\", blocked: false }] })\\`\n\n- \\`blocked_reason\\` is required when setting \\`blocked: true\\`\n- Blocked nodes won't appear in \\`graph_next\\` results\n- Unblocking auto-clears the reason\n- Use this for things like: waiting on external input, upstream API down, needs design review\n\n# Common mistakes to avoid\n\n- Setting dependencies on parent nodes instead of leaf nodes\n- Running project scaffolding tools (create-next-app, etc.) before planning in the graph\n- Resolving tasks without running tests\n- Doing work that isn't tracked in the graph\n- Continuing to the next task without pausing for user review\n- Trying to decompose a node without completing discovery first\n- Not writing knowledge entries during discovery — future agents need this context\n`;\n}\n\nexport interface AgentConfigResult {\n  agent_file: string;\n  install_path: string;\n  instructions: string;\n}\n\nexport function handleAgentConfig(version: string): AgentConfigResult {\n  return {\n    agent_file: agentPrompt(version),\n    install_path: \".claude/agents/graph.md\",\n    instructions:\n      \"Save the agent_file content to .claude/agents/graph.md in your project root. \" +\n      \"Claude Code will automatically discover it and use it when tasks match the agent description.\",\n  };\n}\n"],"mappings":";;;AAEA,SAAS,YAAY,SAAyB;AAC5C,SAAO;AAAA;AAAA,WAEE,OAAO;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAgKlB;AAQO,SAAS,kBAAkB,SAAoC;AACpE,SAAO;AAAA,IACL,YAAY,YAAY,OAAO;AAAA,IAC/B,cAAc;AAAA,IACd,cACE;AAAA,EAEJ;AACF;","names":[]}

package/dist/index.js

@@ -6,10 +6,10 @@ if (args[0] === "activate") {
   const { activate } = await import("./activate-DSDTR2EJ.js");
   activate(args[1]);
 } else if (args[0] === "init") {
-  const { init } = await import("./init-YFC5JVM5.js");
+  const { init } = await import("./init-74TF4PX3.js");
   init();
 } else {
-  const { startServer } = await import("./server-SNA2JYGG.js");
+  const { startServer } = await import("./server-XSKUM3G5.js");
   startServer().catch((error) => {
     console.error("Failed to start graph:", error);
     process.exit(1);

package/dist/{init-YFC5JVM5.js → init-74TF4PX3.js}

@@ -1,10 +1,10 @@
 #!/usr/bin/env node
 import {
   handleAgentConfig
-} from "./chunk-DUEP3T5A.js";
+} from "./chunk-M5QOJN7D.js";
 
 // src/init.ts
-import { readFileSync, writeFileSync, existsSync, mkdirSync } from "fs";
+import { readFileSync, writeFileSync, existsSync, mkdirSync, appendFileSync } from "fs";
 import { join, dirname } from "path";
 import { fileURLToPath } from "url";
 var PKG_VERSION = "0.0.0";
@@ -63,6 +63,29 @@ function init() {
     console.log("\u2713 .claude/agents/graph.md \u2014 created graph workflow agent");
     wrote = true;
   }
+  const claudeMdPath = join(cwd, "CLAUDE.md");
+  const graphSection = `
+## Graph workflow
+
+This project uses Graph for task tracking across sessions. Start every session with \`graph_onboard\` to see project state, actionable tasks, and continuity confidence. Follow the claim-work-resolve loop: \`graph_next\` (claim) \u2192 do work \u2192 \`graph_update\` (resolve with evidence). Don't execute ad-hoc work \u2014 add it to the graph first via \`graph_plan\`.
+`;
+  if (existsSync(claudeMdPath)) {
+    const current = readFileSync(claudeMdPath, "utf8");
+    if (current.includes("graph_onboard")) {
+      console.log("\u2713 CLAUDE.md \u2014 graph workflow instructions already present");
+    } else {
+      appendFileSync(claudeMdPath, graphSection, "utf8");
+      console.log("\u2713 CLAUDE.md \u2014 appended graph workflow instructions");
+      wrote = true;
+    }
+  } else {
+    writeFileSync(claudeMdPath, `# CLAUDE.md
+
+This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
+${graphSection}`, "utf8");
+    console.log("\u2713 CLAUDE.md \u2014 created with graph workflow instructions");
+    wrote = true;
+  }
   console.log("");
   if (wrote) {
     console.log("Graph is ready. Restart Claude Code to load the MCP server.");
@@ -76,4 +99,4 @@ function init() {
 export {
   init
 };
-//# sourceMappingURL=init-YFC5JVM5.js.map
+//# sourceMappingURL=init-74TF4PX3.js.map

package/dist/init-74TF4PX3.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/init.ts"],"sourcesContent":["import { readFileSync, writeFileSync, existsSync, mkdirSync, appendFileSync } from \"fs\";\nimport { join, dirname } from \"path\";\nimport { fileURLToPath } from \"url\";\nimport { handleAgentConfig } from \"./tools/agent-config.js\";\n\n// [sl:hy8oXisWnrZN1BfkonUqd] npx @graph-tl/graph init — zero friction onboarding\n\nlet PKG_VERSION = \"0.0.0\";\ntry {\n  const __dirname = dirname(fileURLToPath(import.meta.url));\n  const pkg = JSON.parse(readFileSync(join(__dirname, \"..\", \"package.json\"), \"utf-8\"));\n  PKG_VERSION = pkg.version;\n} catch {}\n\nconst MCP_CONFIG = {\n  command: \"npx\",\n  args: [\"-y\", \"@graph-tl/graph\"],\n  env: {\n    GRAPH_AGENT: \"claude-code\",\n  },\n};\n\nexport function init(): void {\n  const cwd = process.cwd();\n  let wrote = false;\n\n  // 1. Write .mcp.json\n  const configPath = join(cwd, \".mcp.json\");\n  if (existsSync(configPath)) {\n    try {\n      const config = JSON.parse(readFileSync(configPath, \"utf8\"));\n      if (config.mcpServers?.graph) {\n        console.log(\"✓ .mcp.json — graph already configured\");\n      } else {\n        config.mcpServers = config.mcpServers ?? {};\n        config.mcpServers.graph = MCP_CONFIG;\n        writeFileSync(configPath, JSON.stringify(config, null, 2) + \"\\n\", \"utf8\");\n        console.log(\"✓ .mcp.json — added graph server\");\n        wrote = true;\n      }\n    } catch {\n      console.error(`✗ .mcp.json exists but is not valid JSON — skipping`);\n    }\n  } else {\n    const config = { mcpServers: { graph: MCP_CONFIG } };\n    writeFileSync(configPath, JSON.stringify(config, null, 2) + \"\\n\", \"utf8\");\n    console.log(\"✓ .mcp.json — created with graph server\");\n    wrote = true;\n  }\n\n  // 2. Write .claude/agents/graph.md\n  const agentPath = join(cwd, \".claude\", \"agents\", \"graph.md\");\n  const { agent_file } = handleAgentConfig(PKG_VERSION);\n  if (existsSync(agentPath)) {\n    const current = readFileSync(agentPath, \"utf8\");\n    if (current === agent_file) {\n      console.log(\"✓ .claude/agents/graph.md — already up to date\");\n    } else {\n      writeFileSync(agentPath, agent_file, \"utf8\");\n      console.log(\"✓ .claude/agents/graph.md — updated\");\n      wrote = true;\n    }\n  } else {\n    mkdirSync(dirname(agentPath), { recursive: true });\n    writeFileSync(agentPath, agent_file, \"utf8\");\n    console.log(\"✓ .claude/agents/graph.md — created graph workflow agent\");\n    wrote = true;\n  }\n\n  // 3. Append graph workflow instructions to CLAUDE.md\n  // [sl:qPxNQTKru6q3nPzsNWlfe] Ensure default agent follows graph workflow\n  const claudeMdPath = join(cwd, \"CLAUDE.md\");\n  const graphSection = `\n## Graph workflow\n\nThis project uses Graph for task tracking across sessions. Start every session with \\`graph_onboard\\` to see project state, actionable tasks, and continuity confidence. Follow the claim-work-resolve loop: \\`graph_next\\` (claim) → do work → \\`graph_update\\` (resolve with evidence). Don't execute ad-hoc work — add it to the graph first via \\`graph_plan\\`.\n`;\n\n  if (existsSync(claudeMdPath)) {\n    const current = readFileSync(claudeMdPath, \"utf8\");\n    if (current.includes(\"graph_onboard\")) {\n      console.log(\"✓ CLAUDE.md — graph workflow instructions already present\");\n    } else {\n      appendFileSync(claudeMdPath, graphSection, \"utf8\");\n      console.log(\"✓ CLAUDE.md — appended graph workflow instructions\");\n      wrote = true;\n    }\n  } else {\n    writeFileSync(claudeMdPath, `# CLAUDE.md\\n\\nThis file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.\\n${graphSection}`, \"utf8\");\n    console.log(\"✓ CLAUDE.md — created with graph workflow instructions\");\n    wrote = true;\n  }\n\n  // 4. Summary\n  console.log(\"\");\n  if (wrote) {\n    console.log(\"Graph is ready. Restart Claude Code to load the MCP server.\");\n    console.log(\"\");\n    console.log(\"Then try:\");\n    console.log('  \"Use graph to plan building a REST API with auth and tests.\"');\n  } else {\n    console.log(\"Graph is already set up — nothing to do.\");\n  }\n}\n"],"mappings":";;;;;;AAAA,SAAS,cAAc,eAAe,YAAY,WAAW,sBAAsB;AACnF,SAAS,MAAM,eAAe;AAC9B,SAAS,qBAAqB;AAK9B,IAAI,cAAc;AAClB,IAAI;AACF,QAAM,YAAY,QAAQ,cAAc,YAAY,GAAG,CAAC;AACxD,QAAM,MAAM,KAAK,MAAM,aAAa,KAAK,WAAW,MAAM,cAAc,GAAG,OAAO,CAAC;AACnF,gBAAc,IAAI;AACpB,QAAQ;AAAC;AAET,IAAM,aAAa;AAAA,EACjB,SAAS;AAAA,EACT,MAAM,CAAC,MAAM,iBAAiB;AAAA,EAC9B,KAAK;AAAA,IACH,aAAa;AAAA,EACf;AACF;AAEO,SAAS,OAAa;AAC3B,QAAM,MAAM,QAAQ,IAAI;AACxB,MAAI,QAAQ;AAGZ,QAAM,aAAa,KAAK,KAAK,WAAW;AACxC,MAAI,WAAW,UAAU,GAAG;AAC1B,QAAI;AACF,YAAM,SAAS,KAAK,MAAM,aAAa,YAAY,MAAM,CAAC;AAC1D,UAAI,OAAO,YAAY,OAAO;AAC5B,gBAAQ,IAAI,kDAAwC;AAAA,MACtD,OAAO;AACL,eAAO,aAAa,OAAO,cAAc,CAAC;AAC1C,eAAO,WAAW,QAAQ;AAC1B,sBAAc,YAAY,KAAK,UAAU,QAAQ,MAAM,CAAC,IAAI,MAAM,MAAM;AACxE,gBAAQ,IAAI,4CAAkC;AAC9C,gBAAQ;AAAA,MACV;AAAA,IACF,QAAQ;AACN,cAAQ,MAAM,+DAAqD;AAAA,IACrE;AAAA,EACF,OAAO;AACL,UAAM,SAAS,EAAE,YAAY,EAAE,OAAO,WAAW,EAAE;AACnD,kBAAc,YAAY,KAAK,UAAU,QAAQ,MAAM,CAAC,IAAI,MAAM,MAAM;AACxE,YAAQ,IAAI,mDAAyC;AACrD,YAAQ;AAAA,EACV;AAGA,QAAM,YAAY,KAAK,KAAK,WAAW,UAAU,UAAU;AAC3D,QAAM,EAAE,WAAW,IAAI,kBAAkB,WAAW;AACpD,MAAI,WAAW,SAAS,GAAG;AACzB,UAAM,UAAU,aAAa,WAAW,MAAM;AAC9C,QAAI,YAAY,YAAY;AAC1B,cAAQ,IAAI,0DAAgD;AAAA,IAC9D,OAAO;AACL,oBAAc,WAAW,YAAY,MAAM;AAC3C,cAAQ,IAAI,+CAAqC;AACjD,cAAQ;AAAA,IACV;AAAA,EACF,OAAO;AACL,cAAU,QAAQ,SAAS,GAAG,EAAE,WAAW,KAAK,CAAC;AACjD,kBAAc,WAAW,YAAY,MAAM;AAC3C,YAAQ,IAAI,oEAA0D;AACtE,YAAQ;AAAA,EACV;AAIA,QAAM,eAAe,KAAK,KAAK,WAAW;AAC1C,QAAM,eAAe;AAAA;AAAA;AAAA;AAAA;AAMrB,MAAI,WAAW,YAAY,GAAG;AAC5B,UAAM,UAAU,aAAa,cAAc,MAAM;AACjD,QAAI,QAAQ,SAAS,eAAe,GAAG;AACrC,cAAQ,IAAI,qEAA2D;AAAA,IACzE,OAAO;AACL,qBAAe,cAAc,cAAc,MAAM;AACjD,cAAQ,IAAI,8DAAoD;AAChE,cAAQ;AAAA,IACV;AAAA,EACF,OAAO;AACL,kBAAc,cAAc;AAAA;AAAA;AAAA,EAA0H,YAAY,IAAI,MAAM;AAC5K,YAAQ,IAAI,kEAAwD;AACpE,YAAQ;AAAA,EACV;AAGA,UAAQ,IAAI,EAAE;AACd,MAAI,OAAO;AACT,YAAQ,IAAI,6DAA6D;AACzE,YAAQ,IAAI,EAAE;AACd,YAAQ,IAAI,WAAW;AACvB,YAAQ,IAAI,gEAAgE;AAAA,EAC9E,OAAO;AACL,YAAQ,IAAI,+CAA0C;AAAA,EACxD;AACF;","names":[]}

package/dist/{server-SNA2JYGG.js → server-XSKUM3G5.js}

@@ -4,7 +4,7 @@ import {
 } from "./chunk-WKOEKYTF.js";
 import {
   handleAgentConfig
-} from "./chunk-DUEP3T5A.js";
+} from "./chunk-M5QOJN7D.js";
 import {
   EngineError,
   ValidationError,
@@ -899,7 +899,19 @@ function handleDrop(op, agent) {
 }
 function handleDelete(op, agent) {
   const db = getDb();
-  getNodeOrThrow(op.node_id);
+  const node = getNodeOrThrow(op.node_id);
+  if (node.parent === null) {
+    const evidenceCount = db.prepare(
+      `SELECT COUNT(*) as cnt FROM nodes
+       WHERE project = ? AND evidence != '[]'`
+    ).get(node.project);
+    if (evidenceCount.cnt > 0) {
+      throw new EngineError(
+        "delete_protected",
+        `Cannot delete project "${node.project}" \u2014 it contains ${evidenceCount.cnt} node(s) with evidence. Resolved projects preserve traceability across sessions. Use "drop" to mark as resolved instead.`
+      );
+    }
+  }
   const descendants = getAllDescendants(op.node_id);
   const allIds = [op.node_id, ...descendants];
   const placeholders = allIds.map(() => "?").join(",");
@@ -994,6 +1006,93 @@ function handleHistory(input) {
   return result;
 }
 
+// src/continuity.ts
+function getProjectStats(project) {
+  const db = getDb();
+  const resolved = db.prepare(
+    "SELECT COUNT(*) as cnt FROM nodes WHERE project = ? AND parent IS NOT NULL AND resolved = 1"
+  ).get(project);
+  const withEvidence = db.prepare(
+    "SELECT COUNT(*) as cnt FROM nodes WHERE project = ? AND parent IS NOT NULL AND resolved = 1 AND evidence != '[]'"
+  ).get(project);
+  const lastAct = db.prepare(
+    "SELECT MAX(updated_at) as last FROM nodes WHERE project = ?"
+  ).get(project);
+  const knowledge = db.prepare(
+    "SELECT COUNT(*) as cnt FROM knowledge WHERE project = ?"
+  ).get(project);
+  const sevenDaysAgo = new Date(Date.now() - 7 * 24 * 60 * 60 * 1e3).toISOString();
+  const staleBlocked = db.prepare(
+    "SELECT COUNT(*) as cnt FROM nodes WHERE project = ? AND blocked = 1 AND updated_at < ?"
+  ).get(project, sevenDaysAgo);
+  const total = db.prepare(
+    "SELECT COUNT(*) as cnt FROM nodes WHERE project = ? AND parent IS NOT NULL"
+  ).get(project);
+  return {
+    resolvedCount: resolved.cnt,
+    resolvedWithEvidence: withEvidence.cnt,
+    lastActivity: lastAct.last,
+    knowledgeCount: knowledge.cnt,
+    staleBlockedCount: staleBlocked.cnt,
+    totalNonRoot: total.cnt
+  };
+}
+function computeContinuityConfidence(project) {
+  const stats = getProjectStats(project);
+  const reasons = [];
+  let score = 100;
+  if (stats.resolvedCount > 0) {
+    const coverage = stats.resolvedWithEvidence / stats.resolvedCount;
+    const missing = stats.resolvedCount - stats.resolvedWithEvidence;
+    if (coverage < 0.5) {
+      score -= 40;
+      reasons.push(`${missing} of ${stats.resolvedCount} resolved tasks have no evidence`);
+    } else if (coverage < 0.8) {
+      score -= 20;
+      reasons.push(`${missing} of ${stats.resolvedCount} resolved tasks have no evidence`);
+    } else if (coverage < 1) {
+      score -= 10;
+      reasons.push(`${missing} resolved task(s) missing evidence`);
+    }
+  }
+  if (stats.lastActivity) {
+    const ageMs = Date.now() - new Date(stats.lastActivity).getTime();
+    const ageDays = ageMs / (24 * 60 * 60 * 1e3);
+    if (ageDays > 14) {
+      score -= 25;
+      reasons.push(`No activity for ${Math.floor(ageDays)} days`);
+    } else if (ageDays > 7) {
+      score -= 15;
+      reasons.push(`No activity for ${Math.floor(ageDays)} days`);
+    } else if (ageDays > 3) {
+      score -= 5;
+      reasons.push(`Last activity ${Math.floor(ageDays)} days ago`);
+    }
+  }
+  if (stats.resolvedCount >= 5 && stats.knowledgeCount === 0) {
+    score -= 15;
+    reasons.push("No knowledge entries on a project with 5+ resolved tasks");
+  }
+  if (stats.staleBlockedCount > 0) {
+    score -= 10;
+    reasons.push(`${stats.staleBlockedCount} blocked item(s) not updated in 7+ days`);
+  }
+  if (stats.totalNonRoot === 0) {
+    score -= 10;
+    reasons.push("Project has no tasks yet");
+  }
+  score = Math.max(0, Math.min(100, score));
+  let confidence;
+  if (score >= 70) {
+    confidence = "high";
+  } else if (score >= 40) {
+    confidence = "medium";
+  } else {
+    confidence = "low";
+  }
+  return { confidence, score, reasons };
+}
+
 // src/tools/onboard.ts
 function handleOnboard(input) {
   const evidenceLimit = optionalNumber(input?.evidence_limit, "evidence_limit", 1, 50) ?? 20;
@@ -1122,6 +1221,7 @@ function handleOnboard(input) {
   } else if (summary.total <= 1 && root.discovery !== "pending") {
     hint = `Project is empty \u2014 use graph_plan to decompose the goal into tasks.`;
   }
+  const continuity_confidence = computeContinuityConfidence(project);
   return {
     project,
     goal: root.summary,
@@ -1134,6 +1234,7 @@ function handleOnboard(input) {
     knowledge: knowledgeRows,
     recently_resolved,
     last_activity,
+    continuity_confidence,
     actionable
   };
 }
@@ -1189,6 +1290,173 @@ function handleTree(input) {
   };
 }
 
+// src/tools/status.ts
+function statusIcon(entry) {
+  if (entry.resolved) return "x";
+  if (entry.blocked) return "!";
+  if (entry.dep_blocked) return "~";
+  return " ";
+}
+function progressBar(resolved, total, width = 20) {
+  if (total === 0) return "";
+  const clamped = Math.min(resolved, total);
+  const filled = Math.round(clamped / total * width);
+  const empty = width - filled;
+  const bar = "\u2588".repeat(filled) + "\u2591".repeat(empty);
+  const pct = Math.round(resolved / total * 100);
+  return `${bar} ${resolved}/${total} (${pct}%)`;
+}
+function timeAgo(isoDate) {
+  const diff = Date.now() - new Date(isoDate).getTime();
+  const mins = Math.floor(diff / 6e4);
+  if (mins < 1) return "just now";
+  if (mins < 60) return `${mins}m ago`;
+  const hours = Math.floor(mins / 60);
+  if (hours < 24) return `${hours}h ago`;
+  const days = Math.floor(hours / 24);
+  if (days === 1) return "yesterday";
+  return `${days}d ago`;
+}
+function handleStatus(input) {
+  const db = getDb();
+  let project = optionalString(input?.project, "project");
+  if (!project) {
+    const projects = listProjects();
+    if (projects.length === 0) {
+      return {
+        projects: [],
+        hint: 'No projects yet. Create one with graph_open({ project: "my-project", goal: "..." }).'
+      };
+    }
+    if (projects.length === 1) {
+      project = projects[0].project;
+    } else {
+      const lines2 = ["# All Projects", ""];
+      for (const p of projects) {
+        const taskCount2 = p.total > 0 ? p.total - 1 : 0;
+        const resolvedTasks2 = Math.min(p.resolved, taskCount2);
+        const bar = taskCount2 > 0 ? progressBar(resolvedTasks2, taskCount2) : "empty";
+        lines2.push(`**${p.project}** ${bar}`);
+        lines2.push(`  ${p.summary}`);
+        lines2.push("");
+      }
+      lines2.push("_Specify a project name for details._");
+      return { projects, hint: lines2.join("\n") };
+    }
+  }
+  const root = getProjectRoot(project);
+  if (!root) {
+    throw new EngineError("project_not_found", `Project not found: ${project}`);
+  }
+  const summary = getProjectSummary(project);
+  const rows = db.prepare(
+    `SELECT n.id, n.parent, n.summary, n.resolved, n.blocked, n.blocked_reason, n.depth,
+       (SELECT COUNT(*) FROM nodes c WHERE c.parent = n.id) as child_count,
+       (SELECT COUNT(*) FROM nodes c WHERE c.parent = n.id AND c.resolved = 1) as resolved_children,
+       (SELECT COUNT(*) FROM edges e
+        JOIN nodes dep ON dep.id = e.to_node AND dep.resolved = 0
+        WHERE e.from_node = n.id AND e.type = 'depends_on') as unresolved_deps
+     FROM nodes n
+     WHERE n.project = ? AND n.parent IS NOT NULL
+     ORDER BY n.depth ASC, n.created_at ASC`
+  ).all(project);
+  const entries = rows.map((r) => ({
+    id: r.id,
+    parent: r.parent,
+    summary: r.summary,
+    resolved: r.resolved === 1,
+    blocked: r.blocked === 1,
+    blocked_reason: r.blocked_reason,
+    depth: r.depth - 1,
+    // relative to root
+    child_count: r.child_count,
+    dep_blocked: r.unresolved_deps > 0,
+    resolved_children: r.resolved_children,
+    total_children: r.child_count
+  }));
+  const lines = [];
+  const taskCount = summary.total - 1;
+  lines.push(`# ${project}`);
+  lines.push("");
+  lines.push(root.summary);
+  lines.push("");
+  const resolvedTasks = Math.min(summary.resolved, taskCount);
+  if (taskCount > 0) {
+    lines.push(progressBar(resolvedTasks, taskCount));
+    const cc = computeContinuityConfidence(project);
+    const ccBars = Math.ceil(cc.score / 20);
+    const ccDisplay = "\u25A0".repeat(ccBars) + "\u25A1".repeat(5 - ccBars);
+    lines.push(`${summary.actionable} actionable | ${summary.blocked} blocked | ${summary.unresolved - summary.blocked - summary.actionable} waiting | continuity confidence: ${cc.confidence} ${ccDisplay}`);
+    if (cc.reasons.length > 0 && cc.confidence !== "high") {
+      for (const reason of cc.reasons) {
+        lines.push(`  - ${reason}`);
+      }
+    }
+  } else {
+    lines.push("No tasks yet");
+  }
+  lines.push("");
+  if (entries.length > 0) {
+    lines.push("## Tasks");
+    lines.push("");
+    for (const entry of entries) {
+      const icon = statusIcon(entry);
+      const prefix = "  ".repeat(entry.depth);
+      let line = `${prefix}[${icon}] ${entry.summary}`;
+      if (entry.child_count > 0) {
+        const pct = Math.round(entry.resolved_children / entry.total_children * 100);
+        line += ` (${entry.resolved_children}/${entry.total_children} \u2014 ${pct}%)`;
+      }
+      if (entry.blocked && entry.blocked_reason) {
+        line += `
+${prefix}    ^ ${entry.blocked_reason}`;
+      }
+      lines.push(line);
+    }
+    lines.push("");
+  }
+  const recentEvents = db.prepare(
+    `SELECT e.node_id, e.agent, e.action, e.timestamp, n.summary as node_summary
+     FROM events e
+     JOIN nodes n ON n.id = e.node_id
+     WHERE n.project = ?
+     ORDER BY e.timestamp DESC
+     LIMIT 5`
+  ).all(project);
+  if (recentEvents.length > 0) {
+    lines.push("## Recent Activity");
+    lines.push("");
+    for (const ev of recentEvents) {
+      lines.push(`- ${ev.action} **${ev.node_summary}** (${ev.agent}, ${timeAgo(ev.timestamp)})`);
+    }
+    lines.push("");
+  }
+  const blocked = entries.filter((e) => e.blocked && e.blocked_reason);
+  if (blocked.length > 0) {
+    lines.push("## Blocked");
+    lines.push("");
+    for (const b of blocked) {
+      lines.push(`- **${b.summary}** \u2014 ${b.blocked_reason}`);
+    }
+    lines.push("");
+  }
+  const knowledge = db.prepare(
+    "SELECT key, updated_at FROM knowledge WHERE project = ? ORDER BY updated_at DESC"
+  ).all(project);
+  if (knowledge.length > 0) {
+    lines.push("## Knowledge");
+    lines.push("");
+    for (const k of knowledge) {
+      lines.push(`- ${k.key} (${timeAgo(k.updated_at)})`);
+    }
+    lines.push("");
+  }
+  return {
+    formatted: lines.join("\n").trimEnd(),
+    project
+  };
+}
+
 // src/tools/knowledge.ts
 import { nanoid as nanoid2 } from "nanoid";
 function handleKnowledgeWrite(input, agent) {
@@ -1663,6 +1931,19 @@ var TOOLS = [
       required: ["project"]
     }
   },
+  {
+    name: "graph_status",
+    description: "Returns a pre-formatted markdown summary of a project's current state. Use this to present project status to the user \u2014 output the `formatted` field directly. Shows task tree with status tags, actionable items, blocked items, and knowledge entries. Omit project to auto-select or get multi-project overview.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        project: {
+          type: "string",
+          description: "Project name. Omit to auto-select (works when there's exactly one project)."
+        }
+      }
+    }
+  },
   {
     name: "graph_agent_config",
     description: "Returns the graph-optimized agent configuration file for Claude Code. Save the returned content to .claude/agents/graph.md to enable the graph workflow agent.",
@@ -1800,6 +2081,9 @@ async function startServer() {
         case "graph_tree":
           result = handleTree(args);
           break;
+        case "graph_status":
+          result = handleStatus(args);
+          break;
         case "graph_agent_config":
           result = handleAgentConfig(PKG_VERSION);
           break;
@@ -1949,4 +2233,4 @@ async function startServer() {
 export {
   startServer
 };
-//# sourceMappingURL=server-SNA2JYGG.js.map
+//# sourceMappingURL=server-XSKUM3G5.js.map