@cairnkeep/cli 1.0.2

package/opencode/workflows/memory-review-workflow.md

@@ -0,0 +1,66 @@
+<purpose>
+Review memory candidates staged by the SessionEnd hook (memory-capture.sh) and
+accept (write to AgentFS) or discard them. This is the accept gate between
+autonomous extraction and durable writes.
+</purpose>
+
+<required_reading>
+@$HOME/.config/opencode/templates/wiki-policy.md.template
+</required_reading>
+
+<process>
+
+## 0. Initialize Repo Context
+
+Resolve the repo root and staging dir:
+
+```bash
+ROOT=$(git rev-parse --show-toplevel 2>/dev/null || pwd)
+cd "$ROOT"
+STAGING="$ROOT/.planning/memory-staging"
+```
+
+Parse `--all` from `$ARGUMENTS` (default: newest session only).
+If `$STAGING` is missing or has no `*.json`, report "No staged memory candidates to review" and stop.
+
+## 1. Load Staged Candidates
+
+- default: read the newest `*.json` only
+- `--all`: read every `*.json`, oldest first
+
+Each file is the JSON from `mcp-memory-server extract`:
+`{ model, count, candidates: [{ key, value, category, importance, rationale }] }`
+
+## 2. Review Each Candidate (judgment gate)
+
+For each candidate, apply acceptance rules:
+- **Accept**: durable, branch-safe, short fact/decision/pitfall/convention that future sessions benefit from and is not already in AgentFS. Check duplicates with `memory_search` on the candidate's key/terms.
+- **Discard**: branch-local/speculative, a restatement of canonical code/config, trivial/transient, or already in AgentFS.
+
+Classify scope: `project` (default), `domain-engineering` (reusable patterns), `identity` (user facts only).
+
+## 3. Write Accepted Candidates
+
+For each accepted candidate, call the cairn-memory MCP:
+```
+memory_write(scope="<scope>", key="<key>", value="<value>", promote_to="<category if applicable>")
+```
+If it supersedes an existing entry (same key, updated value), use `memory_supersede(scope, key, value, reason)`.
+
+## 4. Clear Staging
+
+Delete staged files whose candidates have been fully reviewed (accepted or discarded). With `--all`, clear the entire staging dir once done.
+
+## 5. Report
+
+Summary: N reviewed, N accepted (→ AgentFS), N discarded, N superseded. Accepted facts are now durable across both harnesses.
+
+</process>
+
+<success_criteria>
+- [ ] Staging dir read; candidates parsed
+- [ ] Each candidate judged (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/opencode/workflows/security-audit-workflow.md

@@ -0,0 +1,197 @@
+<purpose>
+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/`.
+</purpose>
+
+<required_reading>
+@$HOME/.config/opencode/templates/security-policy.md.template
+@$HOME/.config/opencode/templates/security-report.md.template
+@$HOME/.config/opencode/templates/security-finding-register.yaml.template
+@$HOME/.config/opencode/templates/security-issue.md.template
+</required_reading>
+
+<available_agent_types>
+Valid subagent types for this workflow:
+- security-target-selector
+- security-investigator
+- security-validator
+</available_agent_types>
+
+<process>
+
+## 0. Initialize Repo Context
+
+Resolve the repo root:
+
+```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 <path>`
+- `--threat-model <name>`
+- `--verify-only`
+- `--create-confidential-issue`
+- `--issue-project <group/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` using `origin/HEAD`, then `origin/main`, `main`, `master`, then `HEAD`
+- `base_ref` as `default_branch` in diff mode, otherwise `full-repo`
+- `head_ref` as `branch`
+
+Create directories:
+
+```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 `security-finding-register.yaml.template` with project name and default branch filled in
+- `.planning/security/POLICY.md` from `security-policy.md.template` with default branch filled in
+
+Paths:
+- `findings_path = {ROOT}/.planning/security/FINDINGS.yaml`
+- `policy_path = {ROOT}/.planning/security/POLICY.md`
+- `report_path = {ROOT}/.planning/security/REPORTS/{timestamp}.md`
+- `candidate_path = {ROOT}/.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`:
+- in diff mode, summarize the changed surface from the current branch relative to `default_branch`, plus any staged or unstaged changes
+- in 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
+
+Preferred path: spawn `security-target-selector`.
+
+```text
+◆ Selecting one high-signal security target...
+```
+
+Spawn with:
+
+```text
+Task(
+  prompt="Read $HOME/.config/opencode/agents/security-target-selector.md for instructions. FIRST ACTION: change into {ROOT}.\n\n<audit_assignment>\nproject_root: {ROOT}\naudit_mode: {audit_mode}\nfocus_path: {focus_path or \"null\"}\nthreat_model: {threat_model}\npolicy_path: {ROOT}/.planning/security/POLICY.md\nfindings_path: {ROOT}/.planning/security/FINDINGS.yaml\nscope_summary: {scope_summary}\nchanged_paths: {changed_paths}\n</audit_assignment>",
+  subagent_type="security-target-selector",
+  description="Security audit: target selector"
+)
+```
+
+If the selector returns `NO_TARGET`:
+- write `report_path` from `security-report.md.template`
+- set accepted and rejected counts to `0`
+- explain that no grounded target was selected for this run
+- stop after reporting the result in chat
+
+## 3. Investigate The Target
+
+Preferred path: spawn `security-investigator`.
+
+```text
+◆ Investigating selected target...
+```
+
+Spawn with:
+
+```text
+Task(
+  prompt="Read $HOME/.config/opencode/agents/security-investigator.md for instructions. FIRST ACTION: change into {ROOT}.\n\n<audit_assignment>\nproject_root: {ROOT}\naudit_mode: {audit_mode}\nthreat_model: {threat_model}\nselected_file: {selected_file}\ninvestigation_target: {investigation_target}\nlikely_entry_point: {likely_entry_point}\nrisk_class: {risk_class}\npolicy_path: {ROOT}/.planning/security/POLICY.md\nfindings_path: {ROOT}/.planning/security/FINDINGS.yaml\ncandidate_path: {ROOT}/.planning/security/CANDIDATES/{timestamp}-candidate.md\n</audit_assignment>",
+  subagent_type="security-investigator",
+  description="Security audit: investigator"
+)
+```
+
+If the investigator returns `NO_FINDING`:
+- write `report_path` with `Accepted findings: 0` and `Rejected candidates: 1`
+- include the rejection reason and the candidate path
+- stop after reporting the result in chat
+
+## 4. Validate The Candidate
+
+Compute `next_finding_id` from `.planning/security/FINDINGS.yaml` by taking the next unused `SEC-xxxx` identifier.
+
+Preferred path: spawn `security-validator`.
+
+```text
+◆ Validating candidate against exploitability and duplicate bars...
+```
+
+Spawn with:
+
+```text
+Task(
+  prompt="Read $HOME/.config/opencode/agents/security-validator.md for instructions. FIRST ACTION: change into {ROOT}.\n\n<audit_assignment>\nproject_root: {ROOT}\npolicy_path: {ROOT}/.planning/security/POLICY.md\nfindings_path: {ROOT}/.planning/security/FINDINGS.yaml\ncandidate_path: {ROOT}/.planning/security/CANDIDATES/{timestamp}-candidate.md\nnext_finding_id: {next_finding_id}\nvalidated_dir: {ROOT}/.planning/security/VALIDATED\n</audit_assignment>",
+  subagent_type="security-validator",
+  description="Security audit: validator"
+)
+```
+
+## 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 and rejected counts
+- accepted finding details when validation accepted a finding
+- rejection rationale when the run ended with a rejected candidate
+
+If validation returned `ACCEPTED`:
+- if `--verify-only` is not set, append one new entry to `.planning/security/FINDINGS.yaml`
+- keep the entry 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`, `last_security_audit.branch`, and `last_security_audit.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` when provided, otherwise use `unassigned`
+- preserve the validated report path and audit report path in the draft
+- treat the markdown draft as the durable artifact even if no external tracker is updated in this run
+
+## 7. Report Results
+
+In chat:
+- state whether the run ended with `accepted`, `rejected`, or `no target`
+- show the selected file and investigation target when applicable
+- link the durable report path
+- mention the candidate path and validated path 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/opencode/workflows/wiki-ingest-workflow.md

@@ -0,0 +1,149 @@
+<purpose>
+Compile one canonical source into the repo-local project wiki while keeping raw sources authoritative. Produce or refresh a source summary under `.planning/wiki/sources/`, update `.planning/wiki/index.md`, and append `.planning/wiki/log.md`.
+</purpose>
+
+<required_reading>
+@$HOME/.config/opencode/templates/wiki-policy.md.template
+@$HOME/.config/opencode/templates/wiki-index.md.template
+@$HOME/.config/opencode/templates/wiki-log.md.template
+@$HOME/.config/opencode/templates/wiki-source-summary.md.template
+</required_reading>
+
+<available_agent_types>
+Valid GSD subagent types (use exact names — do not fall back to 'general-purpose'):
+- wiki-ingester
+</available_agent_types>
+
+<process>
+
+## 0. Initialize Repo Context
+
+Resolve the repo root:
+
+```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 from `$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` using `origin/HEAD`, then `origin/main`, `main`, `master`, then `HEAD`
+
+Resolve `source_input`:
+1. if it is an existing absolute path, use it as `source_abs`
+2. else if `$ROOT/$source_input` exists, use that path
+3. else stop with a clear error
+
+Derive:
+- `source_rel` when the file is inside the repo, otherwise use the absolute path
+- `source_slug` from the relative path or basename, normalized to lowercase kebab case
+- `source_kind` as one of `repo_doc`, `repo_code`, `repo_config`, `external_doc`, or `generated_or_binary`
+- `source_page_path = {ROOT}/.planning/wiki/sources/{source_slug}.md`
+
+Create directories:
+
+```bash
+mkdir -p .planning/wiki/sources .planning/wiki/topics .planning/wiki/entities .planning/wiki/queries .planning/wiki/REPORTS .planning/wiki/tmp
+```
+
+Scaffold files when missing:
+- `.planning/wiki/index.md` from `wiki-index.md.template` with project name filled in
+- `.planning/wiki/log.md` from `wiki-log.md.template`
+- `.planning/wiki/POLICY.md` from `wiki-policy.md.template` with project name and default branch filled in
+
+## 1. Gather Canonical Context
+
+Before any synthesis:
+- read `AGENTS.md` if present
+- read `.planning/wiki/POLICY.md`
+- read `.planning/wiki/index.md`
+- read the target source directly
+- read nearby repo docs only when needed to disambiguate the source
+
+Truth rules:
+- the target source is canonical for its own content
+- the wiki is derived and may summarize or cross-link, but must not replace the source
+- when the source is code, do not paraphrase the whole file or create a fake per-file manual; extract only stable interfaces, invariants, behaviors, or references worth reusing
+- if the source is generated, vendored, or mostly binary, write a minimal source note that points back to the canonical path and explains why no richer summary was created
+
+## 2. Write Or Refresh The Source Summary
+
+In `refresh_mode` (the `--refresh` flag was passed):
+- the source page must 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` to the `wiki-ingester` assignment so it re-reads the canonical source, updates only the stable facts that changed, preserves the existing page structure and unchanged facts, bumps `Last reviewed` to the current timestamp, 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, so the derived wiki tracks state instead of going stale
+
+Default path (no `--refresh`): spawn `wiki-ingester`.
+
+```text
+◆ Compiling wiki source summary...
+```
+
+Spawn with:
+
+```text
+Task(
+  prompt="Read $HOME/.config/opencode/agents/wiki-ingester.md for instructions. FIRST ACTION: change into {ROOT}.\n\n<wiki_assignment>\nproject_root: {ROOT}\nsource_abs: {source_abs}\nsource_rel: {source_rel}\nsource_kind: {source_kind}\nsource_page_path: {ROOT}/.planning/wiki/sources/{source_slug}.md\nindex_path: {ROOT}/.planning/wiki/index.md\nlog_path: {ROOT}/.planning/wiki/log.md\npolicy_path: {ROOT}/.planning/wiki/POLICY.md\ntimestamp: {timestamp}\nbranch: {branch}\nproject_name: {project_name}\nrefresh_mode: {refresh_mode}\n</wiki_assignment>",
+  subagent_type="wiki-ingester",
+  description="Wiki: source ingester"
+)
+```
+
+If Task/subagent execution is unavailable:
+- run the ingester role inline
+- still write the source page and update index/log
+
+## 3. Conservative Topic And Entity Maintenance
+
+After the source page exists:
+- create or update a topic page under `.planning/wiki/topics/` only if the source adds a durable concept that already appears across multiple sources or repeated queries
+- create or update an entity page under `.planning/wiki/entities/` only if the source identifies a stable interface, component, owner, or bounded concept that improves cross-linking
+- every new topic or entity page must:
+  - stay shorter than the combined raw sources it points to
+  - include `Last reviewed`
+  - include canonical source references
+  - call out contradictions or freshness uncertainty explicitly
+
+Do not:
+- create topic or entity pages for every file
+- mirror whole code modules into wiki pages
+- 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`
+- if `<!-- wiki:sources:start -->` and `<!-- wiki:sources:end -->` exist, update only inside that block and replace `- None yet.` when adding the first real entry
+- any created topic or entity page is linked once in the correct section, using the matching marker blocks when present
+- `.planning/wiki/log.md` gets one new append-only entry with timestamp, command, source path, pages touched, and whether the run stayed in conservative code-summary mode
+- in `refresh_mode`, log the action as `wiki-refresh` (not `wiki-ingest`) so the maintenance loop is distinguishable from first-time ingests
+- if `<!-- wiki:entries:start -->` and `<!-- wiki:entries:end -->` exist, append inside that block
+
+## 5. Report Results
+
+Display:
+- source page path
+- any topic or entity pages updated
+- 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
+- [ ] Log appended
+- [ ] No fake duplicate code-manual page created for a raw code file
+</success_criteria>

package/opencode/workflows/wiki-lint-workflow.md

@@ -0,0 +1,128 @@
+<purpose>
+Run an advisory lint pass over the repo-local project wiki. Produce a durable report under `.planning/wiki/REPORTS/` and append `.planning/wiki/log.md`.
+</purpose>
+
+<required_reading>
+@$HOME/.config/opencode/templates/wiki-policy.md.template
+@$HOME/.config/opencode/templates/wiki-index.md.template
+@$HOME/.config/opencode/templates/wiki-log.md.template
+@$HOME/.config/opencode/templates/wiki-lint-report.md.template
+@$HOME/.config/opencode/templates/wiki-contradictions.md.template
+</required_reading>
+
+<available_agent_types>
+Valid GSD subagent types (use exact names — do not fall back to 'general-purpose'):
+- wiki-lint-auditor
+</available_agent_types>
+
+<process>
+
+## 0. Initialize Repo Context
+
+Resolve the repo root:
+
+```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` using `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`
+
+Create directories:
+
+```bash
+mkdir -p .planning/wiki/sources .planning/wiki/topics .planning/wiki/entities .planning/wiki/queries .planning/wiki/REPORTS .planning/wiki/tmp
+```
+
+Scaffold files when missing:
+- `.planning/wiki/index.md` from `wiki-index.md.template` with project name filled in
+- `.planning/wiki/log.md` from `wiki-log.md.template`
+- `.planning/wiki/POLICY.md` from `wiki-policy.md.template` with project name and default branch filled in
+- `.planning/wiki/CONTRADICTIONS.md` from `wiki-contradictions.md.template`
+
+## 1. Gather Wiki And Canonical Context
+
+Before linting:
+- read `AGENTS.md` if present
+- read `.planning/wiki/POLICY.md`
+- read `.planning/wiki/index.md`
+- read `.planning/wiki/log.md`
+- read the relevant wiki pages under `sources/`, `topics/`, `entities/`, and `queries/`
+- read canonical raw docs or code when needed to verify suspected stale or contradicted claims
+- do not consult memory tools for this command
+- do not scan unrelated repo files; stay within the wiki plus directly cited canonical sources unless a contradiction requires one extra raw-source check
+
+Linting truth rules:
+- raw repo docs, tests, interfaces, config, and 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
+
+Check for:
+- missing citations on non-trivial claims
+- orphan pages that are not discoverable from `.planning/wiki/index.md` or any other wiki page
+- stale claims whose `Last reviewed` context clearly lags the cited canonical sources
+- contradicted claims where the wiki no longer matches the cited raw sources
+- missing obvious pages, but only when the gap is clear and recurring rather than speculative
+- broken cross-references to missing wiki files or raw repo files
+
+Contradiction severity (classify every contradiction found, mirroring the policy):
+- `hard` — genuinely conflicting claims that cannot both be correct; must be resolved before downstream work relies on either page
+- `scope-mismatch` — the two claims apply to different scopes/contexts and do not truly conflict
+- `soft` — non-blocking, contextual difference; coexists
+
+Run this lint pass inline in the current command.
+
+Reliability rule:
+- do not spawn another agent or task for `/wiki-lint`
+- do not create todos for this command
+- inspect the current wiki state, write the report directly, then append the log entry and return
+
+Write the report directly to `report_path` using the required structure from `wiki-lint-report.md.template`.
+
+Conservative execution 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 searching for additional speculative findings
+
+## 3. Update The Contradiction Register
+
+Mirror every contradiction finding into the persistent register at `.planning/wiki/CONTRADICTIONS.md`. This is what stops contradictions from leaking (reported once, then forgotten):
+
+- read the existing register
+- for each contradiction found this run: if an open entry for the same page-pair/claim already exists, update it (severity, evidence, last-seen timestamp); otherwise open a new entry under `<!-- wiki:contradictions:open:start -->` with severity, `Status: open`, affected pages, the conflicting claims, and the detection date
+- for contradictions that previously existed but whose underlying wiki 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 and the refresh/ingest that fixed it
+- do not delete entries — move resolved ones to the Resolved section so the history is preserved
+- a contradiction is `resolved` only after the conflicting page was actually reconciled (via `/wiki-ingest --refresh` or a manual edit), not merely acknowledged
+
+## 4. Report Results
+
+Display:
+- report path
+- a short summary of the highest-signal findings
+- a reminder that the report is advisory and raw sources remain canonical
+- append the log entry inside `<!-- wiki:entries:start -->` and `<!-- wiki:entries:end -->` when those markers exist
+
+</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
+- [ ] Missing citations, orphan pages, stale or contradicted claims, missing obvious pages, and broken links were considered conservatively
+- [ ] Final user-facing summary kept raw sources as the source of truth
+</success_criteria>

package/opencode/workflows/wiki-query-workflow.md

@@ -0,0 +1,122 @@
+<purpose>
+Answer repository questions by consulting the compiled wiki first and canonical raw sources second. Optionally store a reusable derived answer under `.planning/wiki/queries/`.
+</purpose>
+
+<required_reading>
+@$HOME/.config/opencode/templates/wiki-policy.md.template
+@$HOME/.config/opencode/templates/wiki-index.md.template
+@$HOME/.config/opencode/templates/wiki-log.md.template
+@$HOME/.config/opencode/templates/wiki-query-answer.md.template
+</required_reading>
+
+<available_agent_types>
+Valid GSD subagent types (use exact names — do not fall back to 'general-purpose'):
+- wiki-query-analyst
+</available_agent_types>
+
+<process>
+
+## 0. Initialize Repo Context
+
+Resolve the repo root:
+
+```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 explaining that the command needs a question
+
+Capture:
+- current UTC `timestamp`
+- `branch`
+- repo basename as `project_name`
+- `default_branch` using `origin/HEAD`, then `origin/main`, `main`, `master`, then `HEAD`
+- `query_slug` from the question, normalized to lowercase kebab case
+
+Create directories:
+
+```bash
+mkdir -p .planning/wiki/sources .planning/wiki/topics .planning/wiki/entities .planning/wiki/queries .planning/wiki/REPORTS .planning/wiki/tmp
+```
+
+Scaffold files when missing:
+- `.planning/wiki/index.md` from `wiki-index.md.template` with project name filled in
+- `.planning/wiki/log.md` from `wiki-log.md.template`
+- `.planning/wiki/POLICY.md` from `wiki-policy.md.template` with project name and default branch filled in
+
+Paths:
+- `index_path = {ROOT}/.planning/wiki/index.md`
+- `log_path = {ROOT}/.planning/wiki/log.md`
+- `policy_path = {ROOT}/.planning/wiki/POLICY.md`
+- `query_output_path = {ROOT}/.planning/wiki/queries/{timestamp}-{query_slug}.md` when `writeback` is true
+
+## 1. Build The Retrieval Scope
+
+Before answering:
+- read `AGENTS.md` if present
+- read `.planning/wiki/POLICY.md`
+- read `.planning/wiki/index.md` first
+- use the index to shortlist relevant pages under `sources/`, `topics/`, `entities/`, `queries/`, and recent `REPORTS/` when needed
+- read only the relevant wiki pages next
+- if the wiki is missing, stale, contradictory, or insufficient, read the canonical repo docs, tests, interfaces, config, or code directly
+
+Truth rules:
+- canonical raw repo sources outrank derived wiki pages
+- reusable prior query pages are helpful context, not proof by themselves
+- when the wiki conflicts with raw sources, preserve the contradiction and trust the raw sources
+
+## 2. Answer The Question
+
+Preferred path: spawn `wiki-query-analyst`.
+
+```text
+◆ Building wiki-grounded answer...
+```
+
+Spawn with:
+
+```text
+Task(
+  prompt="Read $HOME/.config/opencode/agents/wiki-query-analyst.md for instructions. FIRST ACTION: change into {ROOT}.\n\n<wiki_assignment>\nproject_root: {ROOT}\nquestion: {question}\nwriteback: {writeback}\nindex_path: {ROOT}/.planning/wiki/index.md\nlog_path: {ROOT}/.planning/wiki/log.md\npolicy_path: {ROOT}/.planning/wiki/POLICY.md\noutput_path: {query_output_path or \"null\"}\ntimestamp: {timestamp}\nbranch: {branch}\nproject_name: {project_name}\n</wiki_assignment>",
+  subagent_type="wiki-query-analyst",
+  description="Wiki: query analyst"
+)
+```
+
+If Task/subagent execution is unavailable:
+- run the query-analyst role inline
+- still answer in chat
+- still write the reusable query page and update index/log when `writeback` is true
+
+## 3. Report Results
+
+Always:
+- answer in chat with preserved source references and caveats
+- call out any contradictions or freshness uncertainty explicitly
+
+If `writeback` is true:
+- mention the saved query page path
+- confirm that the query artifact is derived, not canonical
+- update the `Queries` section of `.planning/wiki/index.md` inside `<!-- wiki:queries:start -->` and `<!-- wiki:queries:end -->` when those markers exist, replacing `- None yet.` when adding the first real entry
+- append the log entry inside `<!-- wiki:entries:start -->` and `<!-- wiki:entries:end -->` when those markers exist
+
+</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>