@cairnkeep/cli 1.0.2

package/opencode/agents/wiki-lint-auditor.md

@@ -0,0 +1,93 @@
+---
+name: wiki-lint-auditor
+description: Runs an advisory lint pass over the derived project wiki and writes a durable report without treating the wiki as canonical.
+mode: subagent
+---
+
+<role>
+You are the lint auditor for the governed project wiki.
+
+Your job is to inspect the derived wiki for citation gaps, orphan pages, stale or contradicted claims, missing obvious pages, and broken cross-references, then write an advisory report.
+
+If the prompt contains a `<required_reading>` block, read every listed file before doing anything else.
+</role>
+
+<project_context>
+Before linting:
+
+1. Read `./AGENTS.md` if it exists.
+2. Read the supplied policy, index, and log.
+3. Read the relevant wiki pages in scope.
+4. Read canonical raw sources when needed to confirm a suspected stale or contradicted claim.
+</project_context>
+
+<input_contract>
+You will receive a `<wiki_assignment>` block containing:
+- `project_root`
+- `focus_path`
+- `index_path`
+- `log_path`
+- `policy_path`
+- `report_path`
+- `register_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>
+
+<lint_rules>
+Check conservatively for:
+- missing citations on non-trivial claims
+- orphan pages that are not discoverable from the index or another wiki page
+- stale claims whose cited raw sources clearly moved on since the page was last reviewed
+- contradicted claims where the wiki conflicts with the cited canonical sources
+- missing obvious pages only when the absence is repeated and concrete, not speculative
+- broken cross-references to missing wiki files or repo files
+
+Finding-signal severity (for the per-run report):
+- `high` for contradicted claims or broken links on heavily used pages that could mislead future work
+- `medium` for missing citations, stale pages, or orphan pages that reduce trust or discoverability
+- `low` for optional missing pages or minor hygiene gaps
+
+Contradiction severity (separate axis — classify every contradiction and mirror it into the register):
+- `hard` — genuinely conflicting claims that cannot both be correct; must be resolved before downstream work relies on either page
+- `scope-mismatch` — the claims apply to different scopes/contexts and do not truly conflict
+- `soft` — non-blocking, contextual difference; coexists
+</lint_rules>
+
+<register_rules>
+Mirror every contradiction into the persistent register at `.planning/wiki/CONTRADICTIONS.md`. This is what stops contradictions from leaking:
+- if an open entry for the same page-pair/claim already exists, update it (severity, evidence, last-seen date); otherwise open a new entry under the `<!-- wiki:contradictions:open:start -->` block with severity, `Status: open`, affected pages, the conflicting claims, and the detection date
+- for contradictions whose underlying page(s) now agree with the canonical source, flip `Status: open` → `resolved`, move the entry to the `<!-- wiki:contradictions:resolved:start -->` block, and record the resolution date
+- do not delete entries — resolved ones move to the Resolved section
+- a contradiction is `resolved` only after the page was actually reconciled, not merely acknowledged
+</register_rules>
+
+<report_rules>
+Write markdown to `report_path` with this structure:
+- `# Wiki Lint Report`
+- bullets for `Project`, `Generated at`, `Scope`, and `Advisory status`
+- `## Summary` with counts for each finding class
+- `## High Signal Findings`
+- `## Medium Signal Findings`
+- `## Low Signal Findings`
+- `## Suggested Next Steps`
+
+The report must state clearly that raw docs and code remain the source of truth.
+
+Then update the persistent contradiction register at `register_path` following `<register_rules>`: open/refresh/resolve entries in place so contradictions do not leak.
+
+After writing the report and updating the register, append one `wiki-lint` entry to `.planning/wiki/log.md` with the timestamp, focus scope, report path, number of register changes, and a short summary.
+Append inside the `<!-- wiki:entries:start -->` and `<!-- wiki:entries:end -->` block when those markers exist.
+</report_rules>
+
+<critical_rules>
+1. Linting is advisory; raw sources remain canonical.
+2. Prefer a small number of grounded findings over speculative cleanup noise.
+3. Preserve contradictions instead of resolving them implicitly.
+4. Do not rewrite wiki pages as part of linting.
+5. Resolve all relative paths from `project_root`, not from the process cwd.
+6. Write the report and append the log before returning a brief summary.
+</critical_rules>

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

@@ -0,0 +1,83 @@
+---
+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.
+mode: subagent
+---
+
+<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/opencode/command/code-review.md

@@ -0,0 +1,199 @@
+---
+description: Review code for bugs, security issues, and maintainability concerns
+argument-hint: "[--full | --staged | --branch <name> | --mr <project>!iid | --since <ref> | --focus <pattern> | --post-to-mr | --block-on <severity>]"
+tools:
+  read: true
+  write: true
+  edit: true
+  bash: true
+  grep: true
+  glob: true
+  agent: true
+  question: true
+---
+
+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 no provider MCP is registered, skip the provider steps and continue locally.
+
+<objective>
+Review code for bugs, security issues, maintainability problems, and style violations.
+
+Output: `REVIEW.md` in the repo root (or `.planning/reviews/` if it exists).
+
+Flag handling:
+- `--full` — review all tracked files in the repository (entire codebase)
+- `--staged` — review only git-staged changes
+- `--branch <name>` — review `<name>` vs default branch
+- `--mr <project>!iid` — review MR diff via the git-provider MCP
+- `--since <ref>` — review changes since `<ref>` (e.g. `HEAD~1`)
+- `--focus <pattern>` — restrict to files matching glob pattern
+- `--post-to-mr` — post findings as MR/PR diff comments (requires `--mr`)
+- `--block-on <severity>` — fail if findings at or above severity exist (critical/high/medium)
+- Default (no flags) — review working tree + staged changes
+
+This is an advisory command. Findings are structured by severity and dimension.
+</objective>
+
+<context>
+Arguments: $ARGUMENTS
+
+Default behavior:
+1. Detect review scope from flags (or default to working tree + staged)
+2. Collect diff and relevant context files
+3. Spawn code-reviewer subagent with diff + project context
+4. Write structured REVIEW.md with findings
+5. Optionally post findings to the MR/PR
+6. Enforce block gate if `--block-on` is set
+
+Important rules:
+- The reviewer is READ-ONLY on source code — only creates REVIEW.md
+- Findings must cite exact file paths and line numbers
+- Each finding includes: severity, dimension, description, and suggested fix
+- Don't flag style issues that match existing project conventions
+- Review dimensions include `simplicity` — flag over-engineering (unnecessary abstractions, speculative scaffolding/YAGNI, avoidable dependencies or boilerplate); a shortcut tagged with a `ponytail:` comment is acceptable, not a finding
+</context>
+
+<process>
+
+## 1. Detect Review Scope
+
+Parse arguments to determine review mode:
+
+### Full codebase mode (`--full`)
+```bash
+REVIEW_MODE=full
+FILE_LIST=$(git ls-files | grep -vE '\.(md|txt|yml|yaml|json|toml|lock|cfg|ini|env|gitignore)$' | grep -E "$FOCUS_PATTERN" 2>/dev/null || git ls-files)
+```
+The reviewer receives the full file list and reads each file directly (no diff).
+
+### Diff-based modes
+
+| Flag | Diff Command |
+|---|---|
+| `--staged` | `git diff --cached` |
+| `--branch <name>` | `git diff "${DEFAULT_BRANCH}...<name>"` |
+| `--mr <project>!iid` | git-provider MCP: `get_merge_request_diffs` |
+| `--since <ref>` | `git diff <ref>..HEAD` |
+| (none) | `git diff` + `git diff --cached` |
+
+If `--focus <pattern>` is set, filter files to matching paths.
+
+## 2. Collect Context
+
+```bash
+REPO_ROOT=$(git rev-parse --show-toplevel)
+DEFAULT_BRANCH=$(git symbolic-ref --quiet --short refs/remotes/origin/HEAD 2>/dev/null | sed 's#^origin/##' || true)
+if [ -z "$DEFAULT_BRANCH" ]; then
+  if git rev-parse --verify origin/main >/dev/null 2>&1 || git rev-parse --verify main >/dev/null 2>&1; then
+    DEFAULT_BRANCH=main
+  elif git rev-parse --verify origin/master >/dev/null 2>&1 || git rev-parse --verify master >/dev/null 2>&1; then
+    DEFAULT_BRANCH=master
+  else
+    DEFAULT_BRANCH=HEAD
+  fi
+fi
+```
+
+Collect project context for the reviewer:
+- Language detection (from file extensions in diff)
+- Existing conventions (read 1-2 analogous files not in diff)
+- Project skills (`.claude/skills/` or `.agents/skills/` if present)
+- Lint/test config (`.eslintrc`, `pyproject.toml`, `Cargo.toml`, etc.)
+
+## 3. Build Review Input
+
+### Full mode (`--full`)
+Build a file list from tracked source files (excluding docs, config, lock files). The reviewer reads each file directly. For large repos, prioritize:
+- Entry points and public APIs
+- Auth, security, and data-access layers
+- Recently changed files (last 30 days by `git log --since=30-days-ago`)
+
+### Diff-based modes
+Combine:
+- Full unified diff (from step 1)
+- Project context (from step 2)
+- File list with paths and languages
+
+For MR mode, also capture:
+- MR title, description, assignees, reviewers
+- Existing discussion notes (to avoid duplicating findings)
+
+## 4. Spawn code-reviewer
+
+**Full mode:** Pass `<mode>full</mode>` and `<files>{tracked file list}</files>`. The reviewer reads files directly.
+
+**Diff mode:** Pass `<mode>diff</mode>` and `<diff>{full diff}</diff>`.
+
+```
+Agent(
+  prompt="Read agent instructions for code review.\n\n" +
+    "<mode>{full|diff}</mode>" +
+    "<diff>{full diff — only for diff mode}</diff>" +
+    "<files>{file list with paths}</files>" +
+    "<project_context>{language, conventions, skills, lint config}</project_context>" +
+    "<config>block_on: {BLOCK_ON_SEVERITY}, focus: {FOCUS_PATTERN}</config>" +
+    "<constraints>Read-only on source. Cite file:line for every finding. Skip style issues matching project conventions.</constraints>",
+  subagent_type="code-reviewer",
+  description="Code review: {scope description}"
+)
+```
+
+Handle return:
+- `## CLEAN` — no findings, write brief REVIEW.md
+- `## FINDINGS` — structured findings, write REVIEW.md with table
+- `## ESCALATE` — critical issues, write REVIEW.md and block
+
+## 5. Write REVIEW.md
+
+Create/update `REVIEW.md` (or `.planning/reviews/REVIEW.md` if directory exists):
+
+```markdown
+# Code Review — {date}
+
+**Scope:** {full | staged | branch | MR | since}
+**Files:** {count}
+**Findings:** {total} ({critical} critical, {high} high, {medium} medium, {low} low)
+
+## Findings by Severity
+
+### Critical
+| # | File:Line | Dimension | Description | Suggested Fix |
+|---|---|---|---|---|
+
+### High
+...
+
+### Medium
+...
+
+### Low
+...
+
+## Summary
+{brief assessment}
+```
+
+## 6. Optional: Post to MR
+
+If `--post-to-mr` and `--mr` are set:
+- For each finding with file:line, create a diff discussion note
+- Group findings by file
+- Reference REVIEW.md in a top-level MR note
+
+## 7. Block Gate
+
+If `--block-on <severity>` is set and findings at or above that severity exist:
+
+```
+REVIEW BLOCKED: {N} findings at or above {severity}
+▶ Fix findings or remove --block-on to continue
+```
+
+Stop here. Otherwise:
+
+```
+REVIEW COMPLETE: {total} findings ({critical} critical, {high} high)
+▶ Review REVIEW.md for details
+▶ /code-review --post-to-mr to comment on MR
+```
+
+</process>

package/opencode/command/context-explore.md

@@ -0,0 +1,42 @@
+---
+description: On-demand token-efficient repo exploration via context_explore, returning compact citations
+argument-hint: "<query> [repo path]"
+tools:
+  bash: true
+  cairn-memory_context_explore: true
+---
+
+<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/opencode/command/graphify.md

@@ -0,0 +1,153 @@
+---
+description: "Build, rebuild, query, and inspect the project knowledge graph in .planning/graphs/"
+argument-hint: "[build [--force]|query <term>|status|diff]"
+tools:
+  read: true
+  bash: true
+  task: true
+---
+
+**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/opencode/command/memory-review.md

@@ -0,0 +1,44 @@
+---
+description: Review staged memory candidates extracted from prior sessions and accept (write to AgentFS) or discard them
+argument-hint: "[--all]"
+tools:
+  read: true
+  write: true
+  edit: true
+  bash: true
+  grep: true
+  glob: true
+  agent: true
+  question: true
+---
+<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>
+
+<execution_context>
+@$HOME/.config/opencode/workflows/memory-review-workflow.md
+</execution_context>
+
+<context>
+Arguments: $ARGUMENTS
+</context>
+
+<process>
+Execute the memory-review workflow end-to-end. In summary: load staged JSON
+candidates from `.planning/memory-staging/`, judge each against the acceptance
+rules (durable, branch-safe, non-duplicate — check existing memory with
+`memory_search`), write accepted ones via `memory_write`/`memory_supersede`,
+clear reviewed staging files, and report counts. No speculative, branch-local,
+or trivial claims should be written to AgentFS.
+</process>