@cairnkeep/cli 1.0.2

package/claude/agents/wiki-query-analyst.md

@@ -0,0 +1,84 @@
+---
+name: wiki-query-analyst
+description: Answers repository questions from the compiled wiki first, then canonical raw sources, and optionally writes back a reusable derived answer. Spawned by /wiki-query.
+tools: Read, Write, Edit, Grep, Glob, Bash
+model: inherit
+---
+
+<role>
+You are the query analyst for the governed project wiki.
+
+Your job is to answer one repository question by using the wiki as a navigation aid first and canonical raw sources second. If writeback is requested, store a reusable derived answer without presenting it as canonical truth.
+
+If the prompt contains a `<required_reading>` block, read every listed file before doing anything else.
+</role>
+
+<project_context>
+Before answering:
+
+1. Read `./AGENTS.md` if it exists.
+2. Read the supplied policy and index.
+3. Use the index to shortlist relevant wiki pages before reading them.
+4. Read canonical raw docs, tests, interfaces, config, or code whenever the wiki is missing, stale, contradictory, or insufficient.
+</project_context>
+
+<input_contract>
+You will receive a `<wiki_assignment>` block containing:
+- `project_root`
+- `question`
+- `writeback`
+- `index_path`
+- `log_path`
+- `policy_path`
+- `output_path`
+- `timestamp`
+- `branch`
+- `project_name`
+
+Treat `project_root` as the working directory. If the runtime spawned you elsewhere, change into `project_root` before reading or writing any relative paths.
+</input_contract>
+
+<retrieval_order>
+Use this order:
+
+1. `.planning/wiki/index.md`
+2. relevant wiki pages under `sources/`, `topics/`, `entities/`, `queries/`, and recent lint reports when they clarify trust issues
+3. cited canonical raw sources and any directly relevant repo files
+
+Truth rules:
+- raw repository docs, tests, interfaces, config, and code outrank derived wiki pages
+- prior query writebacks are reusable hints, not proof by themselves
+- when the wiki and raw sources disagree, preserve the contradiction and trust the raw sources
+</retrieval_order>
+
+<answer_rules>
+In the final answer:
+- lead with the best grounded conclusion
+- preserve source references for the claims you rely on
+- call out contradiction, ambiguity, or freshness risk explicitly
+- avoid pretending the wiki settled something the raw sources do not support
+</answer_rules>
+
+<writeback_rules>
+If `writeback` is true:
+- write markdown to `output_path`
+- start with `# Query: {short title}`
+- include bullets for `Asked at`, `Question`, `Answer status`, and `Last reviewed`
+- include sections named `Answer`, `Wiki Pages Consulted`, `Canonical Sources`, `Contradictions And Freshness Notes`, and `Suggested Follow-up`
+- keep the artifact concise and citation-heavy
+- update `.planning/wiki/index.md` once inside the `<!-- wiki:queries:start -->` and `<!-- wiki:queries:end -->` block when those markers exist
+- if `- None yet.` is present inside the queries block and you are adding a real entry, replace it
+- append one `wiki-query --writeback` entry to `.planning/wiki/log.md`, inside the `<!-- wiki:entries:start -->` and `<!-- wiki:entries:end -->` block when those markers exist
+
+If `writeback` is false:
+- do not modify files
+</writeback_rules>
+
+<critical_rules>
+1. The wiki is derived, not canonical.
+2. Index first, wiki pages second, raw sources third.
+3. Preserve provenance in both the chat answer and any written artifact.
+4. Do not smooth over contradictions.
+5. Resolve all relative paths from `project_root`, not from the process cwd.
+6. Return a concise grounded answer after finishing any requested writeback.
+</critical_rules>

package/claude/commands/context-explore.md

@@ -0,0 +1,40 @@
+---
+description: On-demand token-efficient repo exploration via context_explore, returning compact citations
+argument-hint: "<query> [repo path]"
+allowed-tools: Bash, mcp__cairn-memory__context_explore
+---
+
+<objective>
+Answer a repo-exploration question with compact `path:line-range` citations from `context_explore`, without reading or summarizing the cited ranges yourself — that expansion is the caller's decision, not this command's.
+</objective>
+
+<context>
+Arguments: $ARGUMENTS
+
+The first token (or the full string if no path is given) is the query. An optional trailing path argument overrides the resolved repo root.
+</context>
+
+<process>
+## 0. Resolve repo root
+
+```bash
+ROOT=$(git rev-parse --show-toplevel 2>/dev/null || true)
+if [ -z "$ROOT" ]; then
+  echo "Not inside a git repository. /context-explore must run from a project repo."
+  exit 1
+fi
+cd "$ROOT"
+```
+
+If `$ARGUMENTS` carries an optional trailing path token that is a valid path, use it to override `$ROOT`. The winning value becomes the explicit `repo_root` argument in step 1.
+
+## 1. Call the tool
+
+Call `context_explore` with `query` set to the question text from `$ARGUMENTS` (path override stripped) and `repo_root` set to the resolved path from step 0. `repo_root` MUST be passed explicitly — the MCP server's own working directory is not the target repo, so cwd and any environment default cannot be relied on.
+
+## 2. Report
+
+On success, relay the tool's `content[0].text` citation list verbatim, including its zero-citation note if that is what was returned. Do not read or summarize the cited ranges.
+
+On failure, relay a one-line pass-through of the tool's error message (the thrown message, or `structuredContent.error`) — never a raw JSON dump, never a re-diagnosis of the cause.
+</process>

package/claude/commands/graphify.md

@@ -0,0 +1,150 @@
+---
+description: "Build, rebuild, query, and inspect the project knowledge graph in .planning/graphs/"
+argument-hint: "[build [--force]|query <term>|status|diff]"
+allowed-tools: Read, Bash
+---
+
+**STOP -- DO NOT READ THIS FILE. You are already reading it. This prompt was injected into your context by Claude Code's command system. Using the Read tool on this file wastes tokens. Begin executing Step 0 immediately.**
+
+**graphify CLI:** the `graphify` subcommand is exposed by `gsd-tools` (on PATH). Invoke as `gsd-tools graphify …` as documented in this command and in `docs/CLI-TOOLS.md`. Other GSD queries use `gsd-tools <subcmd>` where a handler exists.
+
+## Step 0 -- Banner
+
+**Before ANY tool calls**, display this banner:
+
+```
+GRAPHIFY
+```
+
+Then proceed to Step 1.
+
+## Step 1 -- Config Gate
+
+Check if graphify is enabled by reading `.planning/config.json` directly using the Read tool.
+
+**DO NOT use the gsd-tools config get-value command** -- it hard-exits on missing keys.
+
+1. Read `.planning/config.json` using the Read tool
+2. If the file does not exist: display the disabled message below and **STOP**
+3. Parse the JSON content. Check if `config.graphify && config.graphify.enabled === true`
+4. If `graphify.enabled` is NOT explicitly `true`: display the disabled message below and **STOP**
+5. If `graphify.enabled` is `true`: proceed to Step 2
+
+**Disabled message:**
+
+```
+GRAPHIFY
+
+Knowledge graph is disabled. To activate:
+
+  gsd-tools config-set graphify.enabled true
+
+Then run /graphify build to create the initial graph.
+```
+
+---
+
+## Step 2 -- Parse Argument
+
+Parse `$ARGUMENTS` to determine the operation mode:
+
+| Argument | Action |
+|----------|--------|
+| `build` or `build --force` | Run inline build (Step 3) |
+| `query <term>` | Run inline query (Step 2a) |
+| `status` | Run inline status check (Step 2b) |
+| `diff` | Run inline diff check (Step 2c) |
+| No argument or unknown | Show usage message |
+
+**Usage message** (shown when no argument or unrecognized argument):
+
+```
+GRAPHIFY
+
+Usage: /graphify <mode>
+
+Modes:
+  build [--force] Build or rebuild the knowledge graph
+  query <term>    Search the graph for a term
+  status          Show graph freshness and statistics
+  diff            Show changes since last build
+```
+
+### Step 2a -- Query
+
+Run:
+
+```bash
+gsd-tools graphify query <term>
+```
+
+Parse the JSON output and display results:
+- If the output contains `"disabled": true`, display the disabled message from Step 1 and **STOP**
+- If the output contains `"error"` field, display the error message and **STOP**
+- If no nodes found, display: `No graph matches for '<term>'. Try /graphify build to create or rebuild the graph.`
+- Otherwise, display matched nodes grouped by type, with edge relationships and confidence tiers (EXTRACTED/INFERRED/AMBIGUOUS)
+
+**STOP** after displaying results. Do not spawn an agent.
+
+### Step 2b -- Status
+
+Run:
+
+```bash
+gsd-tools graphify status
+```
+
+Parse the JSON output and display:
+- If `exists: false`, display the message field
+- Otherwise show last build time, node/edge/hyperedge counts, and STALE or FRESH indicator
+
+**STOP** after displaying status. Do not spawn an agent.
+
+### Step 2c -- Diff
+
+Run:
+
+```bash
+gsd-tools graphify diff
+```
+
+Parse the JSON output and display:
+- If `no_baseline: true`, display the message field
+- Otherwise show node and edge change counts (added/removed/changed)
+
+If no snapshot exists, suggest running `build` twice (first to create, second to generate a diff baseline).
+
+**STOP** after displaying diff. Do not spawn an agent.
+
+---
+
+## Step 3 -- Build (Inline)
+
+Run:
+
+```bash
+gsd-tools graphify build [--force]
+```
+
+Parse the JSON output and display:
+- If the output contains `"disabled": true`, display the disabled message from Step 1 and **STOP**
+- If the output contains an `"error"` field, display the error and the `stage` field when present, then **STOP**
+- Otherwise display the build summary using `status.last_build`, `status.node_count`, `status.edge_count`, `status.hyperedge_count`, whether the snapshot was saved, and whether a forced clean rebuild was used
+
+This command now performs the full pipeline directly:
+- runs `graphify update .` with legacy fallback to `graphify . --update`
+- when `--force` is present, clears `graphify-out/`, published graph artifacts, and `.planning/graphs/.last-build-snapshot.json` first
+- validates `graphify-out/graph.json`
+- copies `graph.json`, `graph.html`, and `GRAPH_REPORT.md` into `.planning/graphs/`
+- writes `.planning/graphs/.last-build-snapshot.json`
+
+**STOP** after displaying the build result. Do not spawn an agent.
+
+---
+
+## Anti-Patterns
+
+1. DO NOT spawn an agent for graphify operations -- build/query/status/diff are handled directly
+2. DO NOT modify graph files directly outside the graphify CLI path
+3. DO NOT skip the config gate check
+4. DO NOT use gsd-tools config get-value for the config gate -- it exits on missing keys

package/claude/commands/memory-review.md

@@ -0,0 +1,85 @@
+---
+description: Review staged memory candidates extracted from prior sessions and accept (write to AgentFS) or discard them
+argument-hint: "[--all]"
+allowed-tools: Read, Write, Edit, Bash, Grep, Glob, mcp__cairn-memory__memory_read, mcp__cairn-memory__memory_search, mcp__cairn-memory__memory_write, mcp__cairn-memory__memory_supersede
+---
+
+<objective>
+Review memory candidates that the SessionEnd hook (memory-capture.sh) extracted
+automatically from prior sessions and staged under `.planning/memory-staging/`.
+This is the accept gate between autonomous extraction and durable AgentFS writes:
+no candidate becomes a memory fact until you accept it here.
+
+Accepted candidates are written via the cairn-memory MCP (`memory_write`).
+Discarded ones are deleted from staging. This keeps writes agent-gated (no
+premature or auto writes) while making extraction fully automatic.
+
+Argument handling:
+- no args: review candidates from the most recent staged session
+- `--all`: review candidates across all staged sessions
+</objective>
+
+<context>
+Arguments: $ARGUMENTS
+</context>
+
+<process>
+
+## 0. Initialize repo context
+
+```bash
+ROOT=$(git rev-parse --show-toplevel 2>/dev/null || pwd)
+cd "$ROOT"
+```
+
+Resolve the staging dir: `$ROOT/.planning/memory-staging/`. If it does not exist or contains no `*.json`, report "No staged memory candidates to review" and stop.
+
+## 1. Load staged candidates
+
+- default: read the newest `*.json` file only
+- `--all`: read every `*.json` file, oldest first
+
+Each staged file is the JSON emitted by `mcp-memory-server extract`:
+```json
+{ "model": "...", "count": N, "candidates": [ { "key": "...", "value": "...", "category": "...", "importance": N, "rationale": "..." }, ... ] }
+```
+
+Parse every candidate's `key`, `value`, `category`, `importance`, and `rationale`.
+
+## 2. Review each candidate (judgment gate)
+
+For each candidate, apply these acceptance rules:
+- **Accept** when the claim is a durable, branch-safe, short fact/decision/pitfall/convention that future sessions would benefit from and that is not already in AgentFS. Check for duplicates by reading the existing project memory (use `memory_search` with the candidate's key/terms).
+- **Skip/discard** when it is: branch-local or speculative, a restatement of code/config already canonical in the repo, trivial/transient, or already present in AgentFS.
+
+For accepted candidates, classify the AgentFS scope:
+- `project` for repo-specific facts (the default)
+- `domain-engineering` for reusable engineering patterns/conventions
+- `identity` only for user/identity facts
+
+## 3. Write accepted candidates
+
+For each accepted candidate, call the cairn-memory MCP:
+```
+memory_write(scope="<scope>", key="<candidate.key>", value="<candidate.value>", promote_to="<category if applicable>")
+```
+If a candidate supersedes an existing entry (same key, updated value), use `memory_supersede` instead of `memory_write`, with a `reason`.
+
+## 4. Clear staging
+
+- delete the staged files whose candidates have been fully reviewed (accepted or discarded)
+- if `--all` was passed, clear the entire staging dir once review is complete
+
+## 5. Report
+
+Display a summary: N reviewed, N accepted (→ AgentFS), N discarded, N superseded. Note that accepted facts are now durable across both harnesses.
+
+</process>
+
+<success_criteria>
+- [ ] Staging dir read; candidates parsed
+- [ ] Each candidate judged against the acceptance rules (durable, branch-safe, non-duplicate)
+- [ ] Accepted candidates written via memory_write / memory_supersede
+- [ ] Reviewed staging files cleared
+- [ ] No speculative, branch-local, or trivial claims written to AgentFS
+</success_criteria>

package/claude/commands/memory-sync.md

@@ -0,0 +1,71 @@
+---
+description: Sync project memory (AgentFS via cairn-memory MCP, AnythingLLM) with current MR/PR state from your git provider
+argument-hint: "[--dry-run] [--force]"
+allowed-tools: Read, Grep, Glob, Bash, mcp__cairn-memory__memory_read, mcp__cairn-memory__memory_write, mcp__cairn-memory__memory_list, mcp__cairn-memory__domain_knowledge_sync
+---
+
+Git provider: these steps use the git host set by `CAIRN_GIT_PROVIDER` (`github`/`gitlab`/`codeberg`/`forgejo`/`none`); resolve the operation-to-tool mapping from `docs/git-providers.md`. If it is `none` or unset, or no provider MCP is registered, skip the provider steps and continue locally.
+
+<objective>
+Sync durable memory with the current state of tracked MRs and PRs.
+
+Output artifacts:
+- Updated AgentFS keys (project scope): `internal-mrs-status`, `upstream-prs-status`
+- Optional AnythingLLM sync if new docs were created
+
+Flag handling:
+- `--dry-run` — show what would change without writing
+- `--force` — sync even if nothing appears changed (useful after manual edits)
+
+This is an operational command. It reads live API state and writes to the memory store.
+</objective>
+
+<context>
+Arguments: $ARGUMENTS
+
+Default behavior:
+1. Read the project memory config (`.agent/memory.json`, `.opencode/memory.json`, or `.claude/memory.json`) to determine scope and workspaces
+2. Read AgentFS key `internal-mrs-status` (project scope) via the cairn-memory `memory_read` tool to get the tracked MR list
+3. For each tracked MR, query the git-provider MCP for current state
+4. Read AgentFS key `upstream-prs-status` via `memory_read` to get the tracked PR list
+5. For each tracked PR, query the git-provider MCP for current state
+6. Compare live state against stored state
+7. If changed (or --force):
+   - Update AgentFS keys with current state via `memory_write`
+   - If `anythingllm_workspaces` is configured and new docs exist, offer `domain_knowledge_sync`
+8. Print a summary of changes
+
+Important rules:
+- Never delete memory entries — only update them
+- Preserve historical context (merged dates, close reasons) in updated entries
+- If an API call fails, skip that item and continue with others
+- Log the sync timestamp in updated entries
+</context>
+
+<process>
+## 1. Read memory configuration
+Read the project memory config to get scopes and `anythingllm_workspaces`. If no config file exists, default to scope `project` with no workspaces.
+
+## 2. Extract tracked MRs and PRs from AgentFS
+Use `memory_read` with scope `project` for keys `internal-mrs-status` and `upstream-prs-status`.
+Parse the markdown to extract tracked items:
+- MRs: `project_id` and `iid` (format: `!IID` in project `ID` or `PATH`)
+- PRs: `owner/repo#NUMBER`
+
+## 3. Query live state
+For each tracked MR, use the git-provider MCP tools to capture: state, draft, assignees, merge_status, updated_at, latest discussion notes (last 3).
+For each tracked PR, call the provider's "get change state" tool from the operation map (e.g. `get_pull_request`) and capture: state, merged, updated_at, comments count.
+
+## 4. Compare and diff
+Compare each item's live state against the stored AgentFS state: state changes (open→merged, open→closed), assignee changes, new discussion notes/comments, draft status changes, merge status changes.
+
+## 5. Write updates
+If `--dry-run`, print the diff and stop.
+
+Otherwise:
+- Update AgentFS `internal-mrs-status` and `upstream-prs-status` via `memory_write` (preserve historical notes)
+- If `anythingllm_workspaces` is configured and new `.md` files exist in the repo that are not yet synced, offer `domain_knowledge_sync` (do not auto-sync)
+
+## 6. Print summary
+Output a compact table: each tracked item, current state, changed (yes/no), notable change.
+</process>

package/claude/commands/recall.md

@@ -0,0 +1,32 @@
+---
+description: Recall known info across memory layers (AgentFS project scope, wiki index, optional AnythingLLM)
+argument-hint: "<question or topic>"
+allowed-tools: Read, Grep, Glob, mcp__cairn-memory__memory_read, mcp__cairn-memory__memory_search, mcp__cairn-memory__domain_knowledge_query
+---
+
+<objective>
+Cross-layer read companion to the automatic SessionStart wakeup. Use mid-session when the task shifts and you need stored context the wakeup did not surface.
+</objective>
+
+<context>
+Question or topic: $ARGUMENTS
+
+Read order (canonical sources still win over derived layers):
+1. AgentFS project scope (short accepted facts)
+2. Wiki index and derived pages (.planning/wiki/)
+3. AnythingLLM workspaces (only if repo docs and memory are insufficient)
+</context>
+
+<process>
+## 1. AgentFS
+`memory_search` scope `project` with $ARGUMENTS. If nothing relevant, retry scope `all`.
+
+## 2. Wiki
+Read `.planning/wiki/index.md` if present and follow links relevant to $ARGUMENTS.
+
+## 3. AnythingLLM (optional)
+Only if 1 and 2 are insufficient and the answer likely lives in long-form docs: `domain_knowledge_query` against the project workspace from the memory config.
+
+## 4. Report
+Summarize what each layer returned in a few lines. If layers disagree, prefer the canonical raw source and note the staleness.
+</process>

package/claude/commands/remember.md

@@ -0,0 +1,43 @@
+---
+description: Persist a durable finding across memory layers (AgentFS + file memory), flagging wiki/AnythingLLM candidates
+argument-hint: "<the fact to remember>"
+allowed-tools: Read, Write, Edit, Grep, Glob, mcp__cairn-memory__memory_read, mcp__cairn-memory__memory_search, mcp__cairn-memory__memory_write, mcp__cairn-memory__memory_supersede
+---
+
+<objective>
+Persist one durable, accepted finding so future sessions recall it without being asked.
+
+This is the write half of the memory loop. It writes the fact to the layers that hold short structured facts (AgentFS project scope + the Claude file-memory), and it only flags the document layers (wiki, AnythingLLM) as candidates rather than writing to them blindly, because those are compiled or embedded from canonical sources.
+</objective>
+
+<context>
+Fact to remember: $ARGUMENTS
+
+Layer shapes (do not treat as four copies of the same thing):
+- AgentFS project scope: short key/value facts, accepted and branch-safe. Direct write.
+- File-memory (`~/.claude/projects/<encoded-cwd>/memory/`): markdown, auto-loaded each session. Direct write.
+- Wiki (`.planning/wiki/`): derived synthesis, compiled via /wiki-ingest. Not a raw-fact store.
+- AnythingLLM: document embeddings, refreshed via domain_knowledge_sync. Not a raw-fact store.
+</context>
+
+<process>
+## 1. Guard
+If $ARGUMENTS is empty, ask what to remember and stop. Do not invent a fact.
+
+## 2. Dedupe before writing
+Run `memory_search` (scope `project`) on the key terms of the fact. If a near-duplicate key exists, update that entry instead of creating a new one.
+
+## 3. Write AgentFS (project scope)
+If step 2 found a near-duplicate key that should keep its prior value for audit/debugging, use `memory_supersede` on that key. Otherwise use `memory_write` scope `project` with a short kebab-case key and the fact as value. Convert relative dates to absolute. No em dashes or double-hyphen dashes (use commas or full stops).
+
+## 4. Write file-memory
+Append or update a one-file-one-fact note under the project memory directory and add a one-line pointer to its `MEMORY.md` index. Skip if the fact is already covered there.
+
+## 5. Flag document layers (do not auto-run)
+- If the fact is stable, doc-worthy synthesis of a canonical source, suggest `/wiki-ingest <path>`.
+- If a repo document changed and retrieval should reflect it, suggest `domain_knowledge_sync`.
+State the suggestion in one line each; do not execute them here.
+
+## 6. Confirm
+Print: the AgentFS key written, the file-memory file touched, and any flagged candidates.
+</process>