@cairnkeep/cli 1.0.2

package/claude/commands/repo-review.md

@@ -0,0 +1,191 @@
+---
+description: Review code for bugs, security issues, and maintainability concerns (workflow code-review; distinct name to avoid shadowing the built-in /code-review)
+argument-hint: "[--full | --staged | --branch <name> | --mr <project>!iid | --since <ref> | --focus <pattern> | --post-to-mr | --block-on <severity>]"
+allowed-tools: Read, Write, Edit, Bash, Grep, Glob, Task
+---
+
+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
+
+Spawn the `code-reviewer` subagent via the Task tool with `subagent_type: "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>`.
+
+Prompt structure:
+```text
+Read agent instructions for code review.
+
+<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>
+```
+
+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
+▶ /repo-review --post-to-mr to comment on MR
+```
+
+</process>

package/claude/commands/security-audit.md

@@ -0,0 +1,174 @@
+---
+description: Run a governed local security audit against one scoped attack surface and write repo-local artifacts
+argument-hint: "[--full] [--focus <path>] [--threat-model <name>] [--verify-only] [--create-confidential-issue] [--issue-project <group/project>]"
+allowed-tools: Read, Write, Edit, Bash, Grep, Glob, Task
+---
+
+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>
+Run one governed local security assessment against the current repository: select one narrow target, investigate it, validate at most one candidate finding, and preserve the outcome under `.planning/security/`.
+
+Output artifacts:
+- `.planning/security/REPORTS/<timestamp>.md`
+- `.planning/security/CANDIDATES/<timestamp>-candidate.md`
+- `.planning/security/VALIDATED/SEC-xxxx-<slug>.md` for accepted findings
+- optional `.planning/security/ISSUES/<timestamp>-confidential-issue.md`
+- optional update to `.planning/security/FINDINGS.yaml`
+
+Flag handling:
+- `--full` — inspect the broader repository instead of the changed surface only
+- `--focus <path>` — bias target selection toward one file or subtree
+- `--threat-model <name>` — label and bias the run; defaults to `changed-surface`
+- `--verify-only` — write the audit artifacts without mutating `.planning/security/FINDINGS.yaml`
+- `--create-confidential-issue` — create a repo-local confidential issue draft when an accepted finding exists
+- `--issue-project <group/project>` — record the intended git-provider destination for that issue draft
+
+This is a governed local-only workflow. It must stay inside the current repository, repo-owned local processes, local files, and localhost services launched from this repo.
+
+Recommended `--threat-model` values: `changed-surface` (default), `authenticated-http-request`, `privilege-escalation`, `session-upgrade`, `deserialization`, `archive-extraction`, `path-traversal`, `subprocess-injection`, `config-file-injection`, `localhost-service-abuse`, `native-crash`, `memory-corruption`. Use a short concrete phrase that helps the selector and investigator reason about attacker capability or failure mode.
+</objective>
+
+<context>
+Arguments: $ARGUMENTS
+
+Scaffold templates live at `$HOME/.claude/templates/security-*.template` (installed by `scripts/sync-claude-assets.sh`). The bootstrap also seeds `.planning/security/POLICY.md` and `.planning/security/FINDINGS.yaml` into each project.
+
+Operating model:
+- one scoped target per run
+- one candidate finding per run at most
+- rejected outcomes stay in the run history, not in the canonical ledger
+- accepted findings may update `.planning/security/FINDINGS.yaml` unless `--verify-only` is set
+- repo-local drafts are preferred over speculative issue filing side effects
+</context>
+
+<process>
+
+## 0. Initialize repo context
+
+```bash
+ROOT=$(git rev-parse --show-toplevel 2>/dev/null || true)
+if [ -z "$ROOT" ]; then
+  echo "Not inside a git repository. /security-audit must run from a project repo."
+  exit 1
+fi
+cd "$ROOT"
+```
+
+Parse flags from `$ARGUMENTS` (`--full`, `--focus`, `--threat-model`, `--verify-only`, `--create-confidential-issue`, `--issue-project`).
+
+Rules:
+- `audit_mode` is `full` when `--full` is set, otherwise `diff`
+- default `threat_model` to `changed-surface` when no explicit value is supplied
+- `--issue-project` is optional metadata; do not fail the run only because it is missing
+
+Capture: current UTC `timestamp`, `branch`, repo basename as `project_name`, `default_branch` (try `origin/HEAD`, then `origin/main`, `main`, `master`, then `HEAD`), `base_ref` (= `default_branch` in diff mode, else `full-repo`), `head_ref` (= `branch`).
+
+```bash
+mkdir -p .planning/security/REPORTS .planning/security/CANDIDATES .planning/security/VALIDATED .planning/security/ISSUES .planning/security/tmp
+```
+
+Scaffold when missing:
+- `.planning/security/FINDINGS.yaml` from `$HOME/.claude/templates/security-finding-register.yaml.template` with project name and default branch filled in
+- `.planning/security/POLICY.md` from `$HOME/.claude/templates/security-policy.md.template` with default branch filled in
+
+Paths: `findings_path`, `policy_path`, `report_path = .planning/security/REPORTS/{timestamp}.md`, `candidate_path = .planning/security/CANDIDATES/{timestamp}-candidate.md`.
+
+## 1. Build the audit scope
+
+Always read `AGENTS.md` (if present), `.planning/security/POLICY.md`, `.planning/security/FINDINGS.yaml`.
+
+Build `scope_summary`:
+- diff mode: summarize the changed surface from the current branch relative to `default_branch`, plus staged/unstaged changes
+- full mode: summarize the main attack-surface-bearing directories and entrypoints
+- when `--focus <path>` is present, keep the summary anchored to that path even in full mode
+
+Build `changed_paths` as a concise path list for the selector.
+
+## 2. Choose one target
+
+Spawn the `security-target-selector` subagent via the Task tool with `subagent_type: "security-target-selector"`. The prompt is the assignment block:
+
+```text
+<audit_assignment>
+project_root: {ROOT}
+audit_mode: {audit_mode}
+focus_path: {focus_path or "null"}
+threat_model: {threat_model}
+policy_path: {ROOT}/.planning/security/POLICY.md
+findings_path: {ROOT}/.planning/security/FINDINGS.yaml
+scope_summary: {scope_summary}
+changed_paths: {changed_paths}
+</audit_assignment>
+```
+
+If the selector returns `NO_TARGET`: write `report_path` from `security-report.md.template` with accepted/rejected counts `0`, explain no grounded target was selected, and stop after reporting in chat.
+
+## 3. Investigate the target
+
+Spawn the `security-investigator` subagent via the Task tool with `subagent_type: "security-investigator"` and prompt:
+
+```text
+<audit_assignment>
+project_root: {ROOT}
+audit_mode: {audit_mode}
+threat_model: {threat_model}
+selected_file: {selected_file}
+investigation_target: {investigation_target}
+likely_entry_point: {likely_entry_point}
+risk_class: {risk_class}
+policy_path: {ROOT}/.planning/security/POLICY.md
+findings_path: {ROOT}/.planning/security/FINDINGS.yaml
+candidate_path: {ROOT}/.planning/security/CANDIDATES/{timestamp}-candidate.md
+</audit_assignment>
+```
+
+If the investigator returns `NO_FINDING`: write `report_path` with `Accepted findings: 0` and `Rejected candidates: 1`, include the rejection reason and candidate path, and stop after reporting in chat.
+
+## 4. Validate the candidate
+
+Compute `next_finding_id` from `.planning/security/FINDINGS.yaml` (next unused `SEC-xxxx`).
+
+Spawn the `security-validator` subagent via the Task tool with `subagent_type: "security-validator"` and prompt:
+
+```text
+<audit_assignment>
+project_root: {ROOT}
+policy_path: {ROOT}/.planning/security/POLICY.md
+findings_path: {ROOT}/.planning/security/FINDINGS.yaml
+candidate_path: {ROOT}/.planning/security/CANDIDATES/{timestamp}-candidate.md
+next_finding_id: {next_finding_id}
+validated_dir: {ROOT}/.planning/security/VALIDATED
+</audit_assignment>
+```
+
+## 5. Write durable outcome
+
+Always write `report_path` from `security-report.md.template` and fill: project name, audit scope, base ref, head ref, threat model, focus path, timestamp, selected file and investigation target (when a target existed), accepted/rejected counts, accepted finding details (when accepted), rejection rationale (when rejected).
+
+If validation returned `ACCEPTED`:
+- if `--verify-only` is not set, append one new entry to `.planning/security/FINDINGS.yaml`, concise and consistent with the existing ledger shape
+- include the validated report path under `evidence.reports` and `validation.report_path`
+- set `last_security_audit.at`, `.branch`, and `.report`
+
+If validation returned `REJECTED`: do not mutate `.planning/security/FINDINGS.yaml`.
+
+## 6. Optional confidential issue draft
+
+If `--create-confidential-issue` is set and validation returned `ACCEPTED`: write `.planning/security/ISSUES/{timestamp}-confidential-issue.md` from `security-issue.md.template`, fill `issue-project` (or `unassigned`), and preserve the validated + audit report paths.
+
+## 7. Report results
+
+In chat: state `accepted` / `rejected` / `no target`; show the selected file and investigation target when applicable; link the durable report path; mention candidate and validated paths when they exist; mention whether `.planning/security/FINDINGS.yaml` was updated or skipped because of `--verify-only`.
+
+</process>
+
+<success_criteria>
+- [ ] Repo root resolved and `.planning/security/` scaffold exists
+- [ ] Exactly one target selected or explicitly rejected as unnecessary
+- [ ] Candidate report written for investigated runs
+- [ ] Candidate validated against duplicate and reachability bars
+- [ ] Durable report written under `.planning/security/REPORTS/`
+- [ ] Findings ledger updated only for accepted findings and only when not in `--verify-only` mode
+- [ ] Optional confidential issue draft written when requested and an accepted finding exists
+</success_criteria>

package/claude/commands/wiki-ingest.md

@@ -0,0 +1,112 @@
+---
+description: Compile one canonical source into a sparse, citation-heavy project wiki page, or re-sync an existing page to the current source with --refresh
+argument-hint: "<source-path> [--refresh]"
+allowed-tools: Read, Write, Edit, Bash, Grep, Glob, Task
+---
+
+<objective>
+Compile one canonical source into the repo-local project wiki under `.planning/wiki/`, or re-sync an existing summary to the current canonical source.
+
+Output artifacts:
+- `.planning/wiki/sources/<slug>.md`
+- updated `.planning/wiki/index.md`
+- updated `.planning/wiki/log.md`
+- optional conservative updates under `.planning/wiki/topics/` or `.planning/wiki/entities/`
+
+This is a derived-knowledge command. Raw repository docs, ADRs, tests, interfaces, and code remain canonical. The wiki must stay sparse, citation-heavy, and conservative.
+
+Argument handling:
+- accepts exactly one non-flag argument: an absolute source path or a repo-relative path inside the current repository
+- optional `--refresh` flag: re-sync an existing source summary to the current canonical source instead of writing it from scratch. In refresh mode: re-read the canonical source, update only the stable facts that changed, bump `Last reviewed`, keep the page's existing structure, and append a `wiki-refresh` log entry. Use this whenever the MR/PR, code, or doc behind a page has changed.
+- the source may be a repo doc, ADR, runbook, config surface, or a code file that defines a stable interface or behavior
+- do not restate an entire code file into a fake duplicate wiki page; summarize only stable, reusable facts with citations
+
+Scaffold templates live at `$HOME/.claude/templates/wiki-*.template` (installed by `scripts/sync-claude-assets.sh`).
+</objective>
+
+<context>
+Arguments: $ARGUMENTS
+</context>
+
+<process>
+
+## 0. Initialize repo context
+
+```bash
+ROOT=$(git rev-parse --show-toplevel 2>/dev/null || true)
+if [ -z "$ROOT" ]; then
+  echo "Not inside a git repository. /wiki-ingest must run from a project repo."
+  exit 1
+fi
+cd "$ROOT"
+```
+
+Parse `$ARGUMENTS`: require exactly one non-flag argument as `source_input`; reject empty input or multiple positional arguments with a clear error; capture an optional `--refresh` flag into `refresh_mode` (default false).
+
+Capture: current UTC `timestamp`, `branch`, repo basename as `project_name`, `default_branch` (try `origin/HEAD`, then `origin/main`, `main`, `master`, then `HEAD`).
+
+Resolve `source_input`: (1) if an existing absolute path, use as `source_abs`; (2) else if `$ROOT/$source_input` exists, use it; (3) else stop with a clear error.
+
+Derive: `source_rel` (when inside the repo, else absolute), `source_slug` (lowercase kebab), `source_kind` (one of `repo_doc`, `repo_code`, `repo_config`, `external_doc`, `generated_or_binary`), `source_page_path = {ROOT}/.planning/wiki/sources/{source_slug}.md`.
+
+```bash
+mkdir -p .planning/wiki/sources .planning/wiki/topics .planning/wiki/entities .planning/wiki/queries .planning/wiki/REPORTS .planning/wiki/tmp
+```
+
+Scaffold when missing from `$HOME/.claude/templates/wiki-*.template`:
+- `.planning/wiki/index.md` (project name filled in)
+- `.planning/wiki/log.md`
+- `.planning/wiki/POLICY.md` (project name + default branch filled in)
+
+## 1. Gather canonical context
+
+Read `AGENTS.md` (if present), `.planning/wiki/POLICY.md`, `.planning/wiki/index.md`, the target source directly, and nearby repo docs only when needed to disambiguate.
+
+Truth rules: the target source is canonical for its own content; the wiki is derived and must not replace the source; for code, extract only stable interfaces/invariants/behaviors (no whole-file paraphrase); for generated/vendored/binary sources, write a minimal note pointing back to the canonical path.
+
+## 2. Write or refresh the source summary
+
+In `refresh_mode` (the `--refresh` flag was passed): the source page should already exist at `source_page_path`; if it does not, fall back to a normal ingest and note this in the log. Pass `refresh_mode: true` in the assignment so the ingester re-reads the canonical source, updates only the stable facts that changed, preserves the existing page structure and unchanged facts, bumps `Last reviewed`, re-evaluates the `Contradictions And Freshness Notes` section, and logs the action as `wiki-refresh`. Refresh is the primary maintenance loop: run it whenever the MR/PR, code, or doc behind a page changes.
+
+Default path (no `--refresh`): spawn the `wiki-ingester` subagent via the Task tool with `subagent_type: "wiki-ingester"` and prompt:
+
+```text
+<wiki_assignment>
+project_root: {ROOT}
+source_abs: {source_abs}
+source_rel: {source_rel}
+source_kind: {source_kind}
+source_page_path: {ROOT}/.planning/wiki/sources/{source_slug}.md
+index_path: {ROOT}/.planning/wiki/index.md
+log_path: {ROOT}/.planning/wiki/log.md
+policy_path: {ROOT}/.planning/wiki/POLICY.md
+timestamp: {timestamp}
+branch: {branch}
+project_name: {project_name}
+refresh_mode: {refresh_mode}
+</wiki_assignment>
+```
+
+If Task/subagent execution is unavailable, run the ingester role inline and still write the source page and update index/log.
+
+## 3. Conservative topic and entity maintenance
+
+After the source page exists, create/update a topic page under `.planning/wiki/topics/` only if the source adds a durable concept appearing across multiple sources or repeated queries; create/update an entity page under `.planning/wiki/entities/` only if it identifies a stable interface, component, owner, or bounded concept that improves cross-linking. Every new topic/entity page must stay shorter than its combined raw sources, include `Last reviewed`, include canonical references, and call out contradictions or freshness uncertainty. Do not create a page for every file or hide uncertainty behind definitive language.
+
+## 4. Update index and log
+
+Ensure the source page is linked once in the `Sources` section of `.planning/wiki/index.md` (update only inside `<!-- wiki:sources:start -->`/`<!-- wiki:sources:end -->` when present, replacing `- None yet.` for the first real entry). Link any created topic/entity page once in the correct section. Append one entry to `.planning/wiki/log.md` (timestamp, action — `wiki-ingest` or `wiki-refresh` in refresh mode — source path, pages touched, conservative-mode/refresh-delta note), inside `<!-- wiki:entries:start -->`/`<!-- wiki:entries:end -->` when present.
+
+## 5. Report results
+
+Display the source page path, any topic/entity pages updated, and a short note that raw sources remain canonical.
+
+</process>
+
+<success_criteria>
+- [ ] Repo root resolved and wiki scaffold created if missing
+- [ ] Canonical source resolved from the input path
+- [ ] One source summary page written or refreshed under `.planning/wiki/sources/`
+- [ ] Index updated and log appended
+- [ ] No fake duplicate code-manual page created for a raw code file
+</success_criteria>

package/claude/commands/wiki-lint.md

@@ -0,0 +1,86 @@
+---
+description: Audit the project wiki for citation gaps, orphan pages, stale claims, contradictions, and broken cross-references; mirror contradictions into the persistent register
+argument-hint: "[--focus <path>]"
+allowed-tools: Read, Write, Edit, Bash, Grep, Glob
+---
+
+<objective>
+Run an advisory lint pass over `.planning/wiki/`.
+
+Output artifacts:
+- `.planning/wiki/REPORTS/<timestamp>-lint.md` (advisory snapshot)
+- `.planning/wiki/CONTRADICTIONS.md` (persistent register, updated in place)
+- updated `.planning/wiki/log.md`
+
+Flag handling:
+- `--focus <path>` — restrict advisory checks to one wiki page or subdirectory under `.planning/wiki/`
+
+This is an advisory governance command. Raw repository docs, ADRs, tests, interfaces, and code remain canonical even when the wiki disagrees or is stale. Scaffold templates live at `$HOME/.claude/templates/wiki-*.template`.
+
+Contradictions are classified by severity (`soft` / `scope-mismatch` / `hard`) and written to the persistent `CONTRADICTIONS.md` register. Unlike the per-run REPORTS snapshot, the register is durable: lint opens, updates, and resolves entries in place so contradictions do not leak (get reported and forgotten). An entry is `resolved` only after the conflicting wiki page has actually been reconciled to the canonical source.
+
+Reliability rule: run the lint inline in this command. Do not spawn a subagent and do not create todos for `/wiki-lint`.
+</objective>
+
+<context>
+Arguments: $ARGUMENTS
+</context>
+
+<process>
+
+## 0. Initialize repo context
+
+```bash
+ROOT=$(git rev-parse --show-toplevel 2>/dev/null || true)
+if [ -z "$ROOT" ]; then
+  echo "Not inside a git repository. /wiki-lint must run from a project repo."
+  exit 1
+fi
+cd "$ROOT"
+```
+
+Parse flags from `$ARGUMENTS`: optional `--focus <path>` pointing to one page or subdirectory under `.planning/wiki/`.
+
+Capture: current UTC `timestamp`, `branch`, repo basename as `project_name`, `default_branch` (try `origin/HEAD`, then `origin/main`, `main`, `master`, then `HEAD`), `report_path = {ROOT}/.planning/wiki/REPORTS/{timestamp}-lint.md`, `register_path = {ROOT}/.planning/wiki/CONTRADICTIONS.md`.
+
+```bash
+mkdir -p .planning/wiki/sources .planning/wiki/topics .planning/wiki/entities .planning/wiki/queries .planning/wiki/REPORTS .planning/wiki/tmp
+```
+
+Scaffold when missing from `$HOME/.claude/templates/wiki-*.template`: `.planning/wiki/index.md`, `.planning/wiki/log.md`, `.planning/wiki/POLICY.md`, `.planning/wiki/CONTRADICTIONS.md`.
+
+## 1. Gather wiki and canonical context
+
+Read `AGENTS.md` (if present), `.planning/wiki/POLICY.md`, `.planning/wiki/index.md`, `.planning/wiki/log.md`, and the relevant wiki pages under `sources/`, `topics/`, `entities/`, `queries/`. Read canonical raw docs or code only when needed to verify a suspected stale or contradicted claim. Do not consult memory tools and do not scan unrelated repo files; stay within the wiki plus directly cited canonical sources unless a contradiction requires one extra raw-source check.
+
+Truth rules: raw repo docs/tests/interfaces/config/code remain canonical; lint findings are advisory and should bias toward high-signal discrepancies; prefer a smaller number of real issues over speculative style cleanup.
+
+## 2. Run the advisory checks (inline)
+
+Check for: missing citations on non-trivial claims; orphan pages not discoverable from the index or any other wiki page; stale claims whose `Last reviewed` clearly lags the cited canonical sources; contradicted claims where the wiki no longer matches cited raw sources; missing obvious pages (only when the gap is clear and recurring); broken cross-references to missing wiki files or raw repo files.
+
+Finding-signal severity: `high` for contradicted claims or broken links on heavily used pages; `medium` for missing citations, stale, or orphan pages; `low` for optional missing pages or minor hygiene gaps.
+
+Contradiction severity (separate axis — classify every contradiction): `hard` (genuinely conflicting, must resolve), `scope-mismatch` (different scopes, coexists), `soft` (contextual, coexists).
+
+Write the report directly to `report_path` using the structure from `wiki-lint-report.md.template`:
+- `# Wiki Lint Report`; bullets for `Project`, `Generated at`, `Scope`, `Advisory status`
+- `## Summary` (counts per finding class, with contradiction severity breakdown); `## Contradictions (severity-tagged)`; `## High Signal Findings`; `## Medium Signal Findings`; `## Low Signal Findings`; `## Suggested Next Steps`
+
+Conservative rule: if there are zero meaningful findings, still write a report with zero counts and `- None.` in each findings section. If there is one clear contradiction or drift issue, report that instead of hunting for speculative findings.
+
+Then update the persistent contradiction register at `register_path` (`.planning/wiki/CONTRADICTIONS.md`): for each contradiction found, open or refresh an entry under `<!-- wiki:contradictions:open:start -->` with severity, `Status: open`, affected pages, conflicting claims, detection date; for contradictions whose page(s) now agree with the canonical source, flip `Status: open` → `resolved` and move the entry to `<!-- wiki:contradictions:resolved:start -->` with a resolution date. Do not delete entries — move resolved ones. An entry is `resolved` only after the page was actually reconciled, not merely acknowledged.
+
+## 3. Report results
+
+Display the report path, a short summary of the highest-signal findings, the number of register changes, and a reminder that the report is advisory and raw sources remain canonical. Append one `wiki-lint` entry to `.planning/wiki/log.md` (timestamp, focus scope, report path, register change count, short summary), inside `<!-- wiki:entries:start -->`/`<!-- wiki:entries:end -->` when present.
+
+</process>
+
+<success_criteria>
+- [ ] Repo root resolved and wiki scaffold created if missing
+- [ ] Relevant wiki pages and cited canonical sources inspected
+- [ ] Advisory lint report written under `.planning/wiki/REPORTS/`
+- [ ] Log appended
+- [ ] Final user-facing summary kept raw sources as the source of truth
+</success_criteria>

package/claude/commands/wiki-query.md

@@ -0,0 +1,92 @@
+---
+description: Answer from the project wiki first, then fall back to canonical repo sources, optionally writing back a reusable answer
+argument-hint: "[--writeback] <question>"
+allowed-tools: Read, Write, Edit, Bash, Grep, Glob, Task
+---
+
+<objective>
+Answer a repository question using the compiled wiki as a first-pass map, without letting the wiki outrank raw sources.
+
+Outputs:
+- chat answer
+- optional `.planning/wiki/queries/<timestamp>-<slug>.md`
+- updated `.planning/wiki/index.md` and `.planning/wiki/log.md` when `--writeback` is used
+
+Flag handling:
+- `--writeback` — store a reusable answer artifact under `.planning/wiki/queries/` and refresh index/log
+
+This is a retrieval-and-synthesis command. Raw repository docs, ADRs, tests, interfaces, and code remain canonical. Scaffold templates live at `$HOME/.claude/templates/wiki-*.template`.
+</objective>
+
+<context>
+Arguments: $ARGUMENTS
+</context>
+
+<process>
+
+## 0. Initialize repo context
+
+```bash
+ROOT=$(git rev-parse --show-toplevel 2>/dev/null || true)
+if [ -z "$ROOT" ]; then
+  echo "Not inside a git repository. /wiki-query must run from a project repo."
+  exit 1
+fi
+cd "$ROOT"
+```
+
+Parse flags from `$ARGUMENTS`: `--writeback`; the remaining text is the required `question`. If `question` is empty after flag parsing, stop with a clear error.
+
+Capture: current UTC `timestamp`, `branch`, repo basename as `project_name`, `default_branch` (try `origin/HEAD`, then `origin/main`, `main`, `master`, then `HEAD`), `query_slug` (lowercase kebab from the question).
+
+```bash
+mkdir -p .planning/wiki/sources .planning/wiki/topics .planning/wiki/entities .planning/wiki/queries .planning/wiki/REPORTS .planning/wiki/tmp
+```
+
+Scaffold when missing from `$HOME/.claude/templates/wiki-*.template`: `.planning/wiki/index.md`, `.planning/wiki/log.md`, `.planning/wiki/POLICY.md`.
+
+Paths: `index_path`, `log_path`, `policy_path`, `query_output_path = {ROOT}/.planning/wiki/queries/{timestamp}-{query_slug}.md` when `writeback` is true.
+
+## 1. Build the retrieval scope
+
+Read `AGENTS.md` (if present), `.planning/wiki/POLICY.md`, `.planning/wiki/index.md` first; use the index to shortlist relevant pages under `sources/`, `topics/`, `entities/`, `queries/`, and recent `REPORTS/`; read only the relevant wiki pages next; if the wiki is missing, stale, contradictory, or insufficient, read canonical repo docs/tests/interfaces/config/code directly.
+
+Truth rules: canonical raw sources outrank derived wiki pages; prior query pages are hints, not proof; when the wiki conflicts with raw sources, preserve the contradiction and trust the raw sources.
+
+## 2. Answer the question
+
+Spawn the `wiki-query-analyst` subagent via the Task tool with `subagent_type: "wiki-query-analyst"` and prompt:
+
+```text
+<wiki_assignment>
+project_root: {ROOT}
+question: {question}
+writeback: {writeback}
+index_path: {ROOT}/.planning/wiki/index.md
+log_path: {ROOT}/.planning/wiki/log.md
+policy_path: {ROOT}/.planning/wiki/POLICY.md
+output_path: {query_output_path or "null"}
+timestamp: {timestamp}
+branch: {branch}
+project_name: {project_name}
+</wiki_assignment>
+```
+
+If Task/subagent execution is unavailable, run the query-analyst role inline; still answer in chat and still write the reusable query page + update index/log when `writeback` is true.
+
+## 3. Report results
+
+Always answer in chat with preserved source references and caveats, calling out any contradictions or freshness uncertainty.
+
+If `writeback` is true: mention the saved query page path; confirm the artifact is derived, not canonical; update the `Queries` section of `.planning/wiki/index.md` inside `<!-- wiki:queries:start -->`/`<!-- wiki:queries:end -->` when present (replace `- None yet.` for the first real entry); append the log entry inside `<!-- wiki:entries:start -->`/`<!-- wiki:entries:end -->` when present.
+
+</process>
+
+<success_criteria>
+- [ ] Repo root resolved and wiki scaffold created if missing
+- [ ] Index consulted before deeper reads
+- [ ] Relevant wiki pages reviewed before canonical fallback
+- [ ] Final chat answer preserved source references and caveats
+- [ ] Reusable answer written under `.planning/wiki/queries/` when `--writeback` is used
+- [ ] Index and log updated when `--writeback` is used
+</success_criteria>