@mrciphersmith/keryx 0.2.77 → 0.2.79

package/dist/cli.js

@@ -589,6 +589,38 @@ description: Use FIRST for conceptual questions - how something works, why, arch
 
 # gdwiki Skill
 
+## Before you trust a page: check whether it is current
+
+A wiki page is a claim about code that may have moved since anyone checked.
+Reading a stale page and generating against it is the failure this whole
+mechanism exists to prevent, so consult freshness BEFORE treating a page as
+context, not after being wrong.
+
+- MCP: \`wiki_freshness\` (read-only; pass \`page\` to ask about one).
+- CLI: \`keryx wiki freshness\` \u2014 or read
+  \`.metaproject/data/wiki/freshness/latest.json\` directly, which is one file
+  and costs nothing.
+
+How to read the answer:
+
+- A page listed \`stale-reference\` has a Reference block that no longer matches
+  the graph. Its **prose may still be sound**; its API list is not. Say so
+  rather than quoting the list as current.
+- A page listed \`stale-prose\` may describe behaviour that changed. Quote it
+  with the caveat, and prefer reading the code it names.
+- A page listed \`unknown\` has never been verified. That is NOT the same as
+  stale, and NOT the same as fresh \u2014 nobody has checked.
+- **An empty finding list with a non-empty \`limitations\` does not mean the
+  wiki is fresh.** It means the check could not run: the graph was not built,
+  the symbol layer was unavailable, or there is no git history. Read
+  \`limitations\` first, every time.
+
+Repairing is a separate act from reading, and it belongs to a person:
+\`keryx wiki refresh\` regenerates Reference blocks deterministically without a
+model, and \`keryx wiki verify --page <p>\` records that someone reviewed a
+page. Do not stamp provenance on a human's behalf \u2014 the field means a person
+looked.
+
 Use this skill for project knowledge that is not a literal code detail:
 architecture, domain models, business rules, user scenarios, service/component
 responsibilities, integrations, and known decisions. The user does not need to
@@ -35431,6 +35463,7 @@ function renderProjectMetaprojectReferenceBlock({
     "Do not dispatch subagents until the Metaproject hard gate is complete. Every subagent prompt must include the exact project/worktree root and require reading `<project-root>/.metaproject/index.md` before searching or reading code.",
     "If MCP tools/resources are available for this project, prefer them for Metaproject capabilities because they provide structured tool calls. If MCP is unavailable or lacks a needed capability, fall back to the corresponding project-local skill and CLI command.",
     "For project navigation, file discovery, and code-related tasks, use the Metaproject gdgraph skill by default before raw file search.",
+    "The graph answers from the last `keryx gdgraph build`, not from the working tree. Rebuild before relying on a graph answer when you added, renamed, deleted or moved files in this session, or when `keryx gdgraph context` reports uncommitted code files \u2014 not once per question. If you cannot rebuild, say the graph predates those changes instead of quoting it as current. Contract: .metaproject/modules/gdgraph.md (Freshness & Refresh).",
     "Any text, symbol, or pattern search over project code goes through `keryx ctx rg`, never a bare `rg`/`grep` \u2014 even a single targeted search, and even when gdgraph/gdwiki are skipped. Raw `rg`/`grep` is a last resort only, with a stated reason recorded in the routing audit.",
     "`keryx ctx rg` and the agent's `search_code` tool require ripgrep (`rg`) on PATH \u2014 install it with `brew install ripgrep` (macOS) or `apt install ripgrep` (Debian/Ubuntu). Without it, code search is unavailable; fall back to reading files directly.",
     "For architecture, domain models, business rules, user scenarios, auth and other flows, integrations, and known decisions, consult the Metaproject gdwiki skill and read the wiki index before deep code reads; use gdgraph to move from a wiki concept to code.",
@@ -35632,6 +35665,7 @@ function renderIndexMarkdown({
     enableGdskills ? "| Any repository task / unclear request | `metaproject-router` | `skills/gdskills/core/metaproject-router/SKILL.md` | Classify the intent first, then route to the narrowest capability. |" : "",
     enableGdskills ? "| Need context / where to start | `context-router` | `skills/gdskills/core/context-router/SKILL.md` | Choose graph, wiki, memory, health, testing, or project-skills before raw reads. |" : "",
     enableGdgraph ? "| Find related files, dependencies, blast radius, cycles, or orphans | `gdgraph` | `skills/gdgraph/SKILL.md`; MCP `gdgraph.*` if available | Start with graph/affected context before broad search. |" : "",
+    enableGdgraph ? "| Files were added, renamed, deleted or moved; graph answers look stale | `gdgraph` | `modules/gdgraph.md` (Freshness & Refresh) | Run `keryx gdgraph build`, then answer from the rebuilt graph. |" : "",
     enableGdwiki ? "| Understand architecture, domain behavior, business rules, scenarios, integrations, or decisions | `gdwiki` | `skills/gdwiki/SKILL.md`; `wiki/index.md`; MCP `wiki.*` if available | Use knowledge pages first, then jump from wiki concepts to code. |" : "",
     enableMemory ? "| Recall past decisions, lessons, constraints, repeated mistakes, or project history | `memory` | `skills/memory/SKILL.md`; MCP `memory.search` if available | Search accepted memory before broad docs or assumptions. |" : "",
     enableTesting ? "| Create/change/debug tests or decide what tests to run | `testing` | `skills/testing/SKILL.md`; `data/testing/context.md` | Use test context and related-test intelligence before raw logs. |" : "",
@@ -35652,6 +35686,9 @@ function renderIndexMarkdown({
     "Any text, symbol, or pattern search over project code goes through `keryx ctx rg`, never a bare `rg`/`grep` \u2014 even a single targeted search, and even when gdgraph/gdwiki are skipped. Raw `rg`/`grep` is a last resort only, with a stated reason.",
     "`keryx ctx rg` and the agent's `search_code` tool require ripgrep (`rg`) on PATH \u2014 install it with `brew install ripgrep` (macOS) or `apt install ripgrep` (Debian/Ubuntu). Without it, code search is unavailable; fall back to reading files directly.",
     enableGdgraph ? "For structural questions (where is X, what files are related, what breaks if I change Y, usages, cycles, orphans) use `skills/gdgraph/SKILL.md` first, before any raw file search. The user does not need to request graph usage explicitly." : "Use relevant skills from `skills/` before raw file search.",
+    ...enableGdgraph ? [
+      "The graph answers from the last `keryx gdgraph build`, not from the working tree. Rebuild before relying on a graph answer when you added, renamed, deleted or moved files in this session, or when `keryx gdgraph context` reports uncommitted code files \u2014 not once per question. If you cannot rebuild, say the graph predates those changes instead of quoting it as current. Contract: `modules/gdgraph.md` (Freshness & Refresh)."
+    ] : [],
     ...enableGdwiki ? [
       "For conceptual questions (how does X work, why, architecture, domain models, business rules, user scenarios, auth and other flows, integrations, known decisions) read `wiki/index.md` first via `skills/gdwiki/SKILL.md`, then use gdgraph to jump from the wiki page to code."
     ] : [],
@@ -37057,13 +37094,23 @@ project-owned hook lines are preserved.
 
 ## git post-commit gdgraph hook
 
-When enabled during \`keryx init\`, the Git \`post-commit\` hook detects commits that touched files relevant to the graph and prints the explicit refresh command.
+When enabled during \`keryx init\`, the Git \`post-commit\` hook detects commits that touched files relevant to the graph and rebuilds the graph by running \`keryx gdgraph build\`.
 
 Purpose:
 
-- prevent stale graph usage by surfacing the refresh command close to the commit;
-- avoid broad raw file search when graph context is stale;
-- avoid mutating versioned \`.metaproject\` artifacts after the commit is already written.
+- keep the graph in step with the committed file set, so the next agent question is not answered from the previous one;
+- avoid broad raw file search caused by a graph that silently predates the commit.
+
+Behaviour:
+
+- runs only inside a work tree, and only when the commit touched a graph-relevant path;
+- resolves \`keryx\` from PATH, then \`$HOME/.local/bin/keryx\`; if neither exists it prints the manual command and returns;
+- never blocks the commit: a failed or unsupported build prints a warning and still exits 0;
+- \`KERYX_GDGRAPH_HOOK_REBUILD=0\` turns the hook back into a printed reminder.
+
+This hook mutates \`.metaproject\` after the commit is written. In a project that versions
+\`data/gdgraph/artifacts/\`, expect \`summary.md\` and \`module-map.json\` to be modified in the
+working tree after a graph-relevant commit \u2014 commit them separately, or opt out.
 
 ## git post-commit gdskills hook
 
@@ -37130,7 +37177,12 @@ Rules:
 }
 function renderGdgraphPostCommitHook() {
   return `keryx_gdgraph_post_commit() {
-  # Non-mutating: report graph staleness after graph-relevant commits.
+  # Rebuild the code graph after a graph-relevant commit, so the next agent
+  # question is answered from the committed file set instead of the previous one.
+  # Mutating by design: it rewrites graph storage and artifacts, which in a
+  # project that versions data/gdgraph/artifacts leaves them modified after the
+  # commit. Set KERYX_GDGRAPH_HOOK_REBUILD=0 for the old reminder-only behaviour.
+  # Never blocks: every path returns 0, including a failed build.
 
   if ! git rev-parse --is-inside-work-tree >/dev/null 2>&1; then
     return 0
@@ -37145,7 +37197,28 @@ function renderGdgraphPostCommitHook() {
     return 0
   fi
 
-  echo "keryx post-commit: gdgraph may be stale; run 'keryx gdgraph build' when you want to refresh graph artifacts"
+  if [ "\${KERYX_GDGRAPH_HOOK_REBUILD:-1}" = "0" ]; then
+    echo "keryx post-commit: gdgraph rebuild disabled (KERYX_GDGRAPH_HOOK_REBUILD=0); graph may be stale, run 'keryx gdgraph build'"
+    return 0
+  fi
+
+  gdm=""
+  if command -v keryx >/dev/null 2>&1; then
+    gdm="keryx"
+  elif [ -x "$HOME/.local/bin/keryx" ]; then
+    gdm="$HOME/.local/bin/keryx"
+  else
+    echo "keryx post-commit: keryx command not found; graph may be stale, run 'keryx gdgraph build'" >&2
+    return 0
+  fi
+
+  echo "keryx post-commit: rebuilding gdgraph after a graph-relevant commit"
+  if "$gdm" gdgraph build >/dev/null 2>&1; then
+    echo "keryx post-commit: gdgraph rebuilt; versioned graph artifacts may now differ from the commit"
+  else
+    echo "keryx post-commit: gdgraph build failed; graph may be stale, run 'keryx gdgraph build'" >&2
+  fi
+
   return 0
 }
 
@@ -37598,6 +37671,45 @@ frontend/static outputs are skipped by default.
 - \`keryx gdgraph query cycles | orphans\`
 - \`keryx gdgraph symbols <enable|disable|status>\` \u2014 opt-in tree-sitter symbol layer
 
+## Freshness & Refresh
+
+The graph is a snapshot of the last \`keryx gdgraph build\`, not a live view of the working tree. A
+graph answer computed after the file set moved is wrong, and nothing in the answer says so.
+
+What invalidates it:
+
+- a source file added, deleted, renamed or moved \u2014 the node set is stale, and \`find\`/\`orphans\`/
+  \`affected\` silently answer from the old one;
+- an import added or removed \u2014 the edge set is stale, so blast radius under-reports;
+- an edit inside a file with unchanged imports \u2014 file-level graph unaffected; the opt-in symbol
+  layer (\`symbol\`, \`path\` def/call data) IS stale, because signatures and call sites moved.
+
+How staleness is observed:
+
+\`\`\`bash
+keryx gdgraph context   # last line: "freshness: working tree clean"
+                        # or "freshness: N uncommitted code file(s) may not be reflected"
+\`\`\`
+
+That line counts uncommitted code files against \`HEAD\`; it is a heuristic, not a build ledger. It
+cannot see committed-but-not-rebuilt changes, so the post-commit hook covers that half.
+
+How it is repaired:
+
+\`\`\`bash
+keryx gdgraph build
+\`\`\`
+
+Agent rule: do not rebuild per question \u2014 the graph is meant to be read many times per build. Do
+rebuild before relying on a graph answer when you added, renamed, deleted or moved files in this
+session, when the freshness line reports uncommitted code files, or when graph storage is missing.
+When you cannot rebuild, say the graph predates your changes instead of quoting it as current.
+
+Automatic refresh: the optional Git \`post-commit\` hook rebuilds the graph after a commit that
+touched graph-relevant paths (see \`hooks/README.md\`). It never blocks the commit, and
+\`KERYX_GDGRAPH_HOOK_REBUILD=0\` turns it back into a printed reminder. In a project that versions
+\`data/gdgraph/artifacts/\`, a rebuild leaves those files modified after the commit.
+
 ## Data
 
 - \`data/gdgraph/artifacts/summary.md\`
@@ -37676,7 +37788,7 @@ Skip gdgraph only when the request is clearly unrelated to project files, asks f
 1. Check whether \`.metaproject/modules/gdgraph.md\` exists.
 2. If the task requires finding relevant project files or understanding relationships, use graph context before any \`rg\` or reading many files. When you do need a text/symbol search, run it as \`keryx ctx rg\`, not raw \`rg\`.
 3. Do not rebuild the graph on every user question. Prefer existing graph storage and curated artifacts.
-4. Run build only when graph storage is missing, obviously stale, or the user explicitly asks to refresh it:
+4. Run build when graph storage is missing, when the file set changed since the last build (you added, renamed, deleted or moved files; \`keryx gdgraph context\` reports uncommitted code files), or when the user asks to refresh it. The freshness contract is \`modules/gdgraph.md\` (Freshness & Refresh):
 
 \`\`\`bash
 keryx gdgraph build
@@ -37728,12 +37840,25 @@ degrades to file-level otherwise).
 
 ## Refresh Policy
 
-Graph refresh should happen through one of these paths:
-
-- user or agent explicitly runs \`keryx gdgraph build\`;
-- Git \`post-commit\` hook refreshes graph after relevant file changes;
+The graph answers from the last \`keryx gdgraph build\`, never from the working
+tree, and a stale answer looks exactly like a fresh one. Refresh happens through
+one of these paths:
+
+- you or the user run \`keryx gdgraph build\` \u2014 required before you rely on a graph
+  answer after adding, renaming, deleting or moving files in this session, or when
+  \`keryx gdgraph context\` ends with \`freshness: N uncommitted code file(s) may not
+  be reflected\`;
+- the optional Git \`post-commit\` hook rebuilds the graph after a commit that
+  touched graph-relevant paths. It resolves \`keryx\` from PATH then
+  \`$HOME/.local/bin/keryx\`, never blocks the commit (a failed build only warns),
+  and is turned back into a printed reminder by \`KERYX_GDGRAPH_HOOK_REBUILD=0\`.
+  In a project that versions \`data/gdgraph/artifacts/\`, the rebuild leaves those
+  files modified after the commit;
 - graph storage is missing and the task needs graph context.
 
+If you cannot rebuild, say the graph predates your changes rather than quoting it
+as current. The full contract is \`modules/gdgraph.md\` (Freshness & Refresh).
+
 ## Always-on orientation (optional)
 
 Graph usage is advisory by default. Unlike a raw \`rg\` (which the gdctx guard can
@@ -57480,7 +57605,7 @@ function buildToolRegistry() {
     {
       name: "gdgraph.affected",
       module: "gdgraph",
-      description: "List the dependencies and dependents of a file from the code graph (blast radius).",
+      description: "List the dependencies and dependents of a file from the code graph (blast radius). " + "Reads the built graph, so results are as old as the last `keryx gdgraph build` and " + "reflect no file added, renamed, deleted or re-imported since it \u2014 a blast radius " + "computed after such a change under-reports. With no graph built at all the result is " + "empty rather than an error, so an empty result means either no dependents or no graph.",
       inputSchema: OBJECT_SCHEMA({
         file: { type: "string", description: "Project-relative file path." },
         depth: { type: "number", description: "Reserved; traversal depth." }
@@ -57972,6 +58097,18 @@ async function serveMcp(options) {
   await startStdioTransport(server);
 }
 
+// src/commands/mcp-serve-root.ts
+function resolveServeRoot(explicitCwd, processCwd, env) {
+  if (explicitCwd !== undefined && explicitCwd.trim().length > 0) {
+    return explicitCwd;
+  }
+  const fromRuntime = env.CLAUDE_PROJECT_DIR;
+  if (fromRuntime !== undefined && fromRuntime.trim().length > 0) {
+    return fromRuntime;
+  }
+  return processCwd;
+}
+
 // src/commands/mcp.ts
 async function mcpCommand(args = [], cwd = process.cwd()) {
   const subcommand = args[0];
@@ -57989,7 +58126,7 @@ async function mcpCommand(args = [], cwd = process.cwd()) {
   }
   if (!subcommand || subcommand === "serve") {
     const http = args.includes("--http");
-    const projectRoot = path154.resolve(optionValue(args, "--cwd") ?? cwd);
+    const projectRoot = path154.resolve(resolveServeRoot(optionValue(args, "--cwd"), cwd, process.env));
     try {
       await serveMcp({ cwd: projectRoot, http });
     } catch (error) {
@@ -65964,7 +66101,7 @@ import { spawnSync as spawnSync2 } from "child_process";
 // package.json
 var package_default = {
   name: "@mrciphersmith/keryx",
-  version: "0.2.77",
+  version: "0.2.79",
   description: "Version-controlled project context for AI coding agents: code graph, architecture wiki, project memory, relevant tests, quality signals, and task flows.",
   private: false,
   publishConfig: {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mrciphersmith/keryx",
-  "version": "0.2.77",
+  "version": "0.2.79",
   "description": "Version-controlled project context for AI coding agents: code graph, architecture wiki, project memory, relevant tests, quality signals, and task flows.",
   "private": false,
   "publishConfig": {