@cairnkeep/cli 1.0.2

package/opencode/command/memory-sync.md

@@ -0,0 +1,94 @@
+---
+description: Sync project memory (AgentFS, AnythingLLM) with current MR/PR state from your git provider
+argument-hint: "[--dry-run] [--force]"
+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 unset, or no provider MCP is registered, skip the provider steps and continue locally.
+
+<objective>
+Sync all memory tools with the current state of tracked MRs and PRs.
+
+Output artifacts:
+- Updated AgentFS keys: `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 memory stores.
+</objective>
+
+<context>
+Arguments: $ARGUMENTS
+
+Default behavior:
+1. Read `.opencode/memory.json` to determine project scope and workspaces
+2. Read AgentFS key `internal-mrs-status` to get tracked MR list
+3. For each tracked MR, query the git-provider MCP for current state
+4. Read AgentFS key `upstream-prs-status` to get 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
+   - If anythingllm_workspaces is configured and new docs exist, offer sync
+8. Print 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 `.opencode/memory.json` 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
+Read AgentFS keys `internal-mrs-status` and `upstream-prs-status` from the `project` scope.
+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:
+- Call the git-provider `get_merge_request` with `project_id` and `merge_request_iid`
+- Capture: state, draft, assignees, merge_status, updated_at, latest discussion notes (last 3)
+
+For each tracked PR:
+- Call the git-provider `get_pull_request` (or your provider's equivalent) for the PR
+- 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, etc.)
+- 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` with current state (preserve historical notes)
+- Update AgentFS `upstream-prs-status` with current state
+- If `anythingllm_workspaces` is configured, check if any new `.md` files exist in the repo root that aren't yet synced. If so, offer to sync (don't auto-sync).
+
+## 6. Print summary
+Output a compact table of:
+- Each tracked item
+- Current state
+- Changed? (yes/no)
+- Notable change (if any)
+</process>

package/opencode/command/recall.md

@@ -0,0 +1,38 @@
+---
+description: Recall known info across memory layers (AgentFS project scope, wiki index, optional AnythingLLM)
+argument-hint: "<question or topic>"
+tools:
+  read: true
+  grep: true
+  glob: true
+  cairn-memory_memory_read: true
+  cairn-memory_memory_search: true
+  cairn-memory_domain_knowledge_query: true
+---
+
+<objective>
+Cross-layer read companion to the automatic session-start 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
+`cairn-memory_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: `cairn-memory_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/opencode/command/remember.md

@@ -0,0 +1,46 @@
+---
+description: Persist a durable finding to AgentFS, flagging wiki/AnythingLLM candidates
+argument-hint: "<the fact to remember>"
+tools:
+  read: true
+  grep: true
+  glob: true
+  cairn-memory_memory_read: true
+  cairn-memory_memory_search: true
+  cairn-memory_memory_write: true
+  cairn-memory_memory_supersede: true
+---
+
+<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 AgentFS (the shared, cross-harness durable store), 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 copies of the same thing):
+- AgentFS project scope: short key/value facts, accepted and branch-safe. Direct write. The sole durable structured store for OpenCode.
+- 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 `cairn-memory_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 `cairn-memory_memory_supersede` on that key. Otherwise use `cairn-memory_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. 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.
+
+## 5. Confirm
+Print: the AgentFS key written, and any flagged candidates.
+</process>

package/opencode/command/security-audit.md

@@ -0,0 +1,80 @@
+---
+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>]"
+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>
+Run one governed local security assessment against the current repository.
+
+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 with a concrete threat model or attack surface description; 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 broad review of the changed attack surface when no stronger prior exists
+- `authenticated-http-request` — authenticated API or web request abuse path
+- `privilege-escalation` — boundary crossing between roles, users, or capabilities
+- `session-upgrade` — session fixation, upgrade, or post-login boundary problems
+- `deserialization` — parser or decoder abuse in structured input handling
+- `archive-extraction` — tar/zip/extraction path traversal or unsafe unpacking
+- `path-traversal` — untrusted path resolution or file access escape
+- `subprocess-injection` — unsafe shell or subprocess composition
+- `config-file-injection` — generated config or template injection into downstream interpreters
+- `localhost-service-abuse` — repo-owned local daemon or localhost trust-boundary misuse
+- `native-crash` — native parser, memory-safety, or crash-triggering input path
+- `memory-corruption` — stronger native-memory-safety focus when corruption is the specific concern
+
+Usage rule:
+- use a short, concrete phrase that helps the selector and investigator reason about attacker capability or failure mode
+- prefer the values above for consistency across repos and findings
+</objective>
+
+<execution_context>
+@$HOME/.config/opencode/workflows/security-audit-workflow.md
+</execution_context>
+
+<context>
+Arguments: $ARGUMENTS
+
+Default behavior:
+- scaffold `.planning/security/` when missing
+- choose exactly one narrow target for this run
+- investigate that target deeply enough to confirm or reject one candidate finding
+- validate the candidate with a stricter duplicate and reachability bar
+- write durable repo-local artifacts for the outcome
+
+Important rules:
+- 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>
+Execute the security-audit workflow from @$HOME/.config/opencode/workflows/security-audit-workflow.md end-to-end.
+</process>

package/opencode/command/wiki-ingest.md

@@ -0,0 +1,55 @@
+---
+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]"
+tools:
+  read: true
+  write: true
+  edit: true
+  bash: true
+  grep: true
+  glob: true
+  agent: true
+  question: true
+---
+<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
+</objective>
+
+<execution_context>
+@$HOME/.config/opencode/workflows/wiki-ingest-workflow.md
+</execution_context>
+
+<context>
+Arguments: $ARGUMENTS
+
+Default behavior:
+- resolve the repo root and the requested source path
+- ensure `.planning/wiki/` scaffold exists
+- treat the source as immutable and canonical
+- write or refresh one source summary page under `.planning/wiki/sources/`
+- refresh the wiki index and append a log entry
+- update topic or entity pages only when the source clearly adds reusable, cross-source knowledge
+
+Important rules:
+- the wiki complements repo docs, AgentFS memory, and AnythingLLM; it does not replace them
+- source summaries must preserve provenance, freshness, and contradiction notes
+- when the source is code, prefer narrow interface or invariant summaries over file paraphrase
+</context>
+
+<process>
+Execute the wiki-ingest workflow from @$HOME/.config/opencode/workflows/wiki-ingest-workflow.md end-to-end.
+</process>

package/opencode/command/wiki-lint.md

@@ -0,0 +1,51 @@
+---
+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>]"
+tools:
+  read: true
+  write: true
+  edit: true
+  bash: true
+  grep: true
+  glob: true
+  agent: true
+  question: true
+---
+<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.
+
+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.
+</objective>
+
+<execution_context>
+@$HOME/.config/opencode/workflows/wiki-lint-workflow.md
+</execution_context>
+
+<context>
+Arguments: $ARGUMENTS
+
+Default behavior:
+- ensure `.planning/wiki/` scaffold exists
+- inspect the wiki index, policy, log, and relevant derived pages
+- check for missing citations, orphan pages, stale claims, contradicted claims, missing obvious pages, and broken cross-references
+- write a durable lint report and append a log entry
+
+Important rules:
+- lint findings are advisory and must not outrank canonical raw sources
+- prefer conservative findings over speculative cleanup demands
+- call out contradictions and freshness uncertainty explicitly instead of rewriting them away
+</context>
+
+<process>
+Execute the wiki-lint workflow from @$HOME/.config/opencode/workflows/wiki-lint-workflow.md end-to-end.
+</process>

package/opencode/command/wiki-query.md

@@ -0,0 +1,50 @@
+---
+description: Answer from the project wiki first, then fall back to canonical repo sources, optionally writing back a reusable answer
+argument-hint: "[--writeback] <question>"
+tools:
+  read: true
+  write: true
+  edit: true
+  bash: true
+  grep: true
+  glob: true
+  agent: true
+  question: true
+---
+<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.
+</objective>
+
+<execution_context>
+@$HOME/.config/opencode/workflows/wiki-query-workflow.md
+</execution_context>
+
+<context>
+Arguments: $ARGUMENTS
+
+Default behavior:
+- read `.planning/wiki/index.md` first
+- inspect only relevant wiki pages next
+- if wiki pages are missing, stale, contradictory, or insufficient, read the canonical repo sources directly
+- answer in chat with preserved source references
+- if `--writeback` is present, write a reusable answer with citations and caveats
+
+Important rules:
+- treat `.planning/wiki/` as a derived layer, not a canonical one
+- preserve contradiction and freshness notes instead of smoothing them over
+- when raw sources disagree with the wiki, trust the raw sources and say so explicitly
+</context>
+
+<process>
+Execute the wiki-query workflow from @$HOME/.config/opencode/workflows/wiki-query-workflow.md end-to-end.
+</process>

package/opencode/plugins/memory-capture.ts

@@ -0,0 +1,188 @@
+import type { Plugin } from "@opencode-ai/plugin"
+import { spawn } from "node:child_process"
+import fs from "node:fs"
+import path from "node:path"
+
+// OpenCode-native reimplementation of the Claude SessionEnd `memory-capture`
+// hook (OCP-01, D-08). OpenCode has no `session.end` event; per 04-RESEARCH.md
+// the best-fit trigger is `session.idle` (D-09), filtered to top-level
+// sessions and de-duplicated so one working session stages at most one
+// capture (Pitfall 2). The session transcript is obtained via the SDK
+// `client.session.messages()` call (04-SPIKE-INJECTION.md confirmed shape),
+// never by reading OpenCode's undocumented internal storage layout directly
+// (Anti-Pattern).
+//
+// SERVER_ENTRY carries the install-rendered @@INFRA_ROOT@@ token (mirrors the
+// Claude hook's substitution and opencode/plugins/memory-wakeup.ts's existing
+// convention — the sync script, not this plugin, resolves it to the real repo
+// root at install time; never accept a runtime-overridable server path here.
+// T-04-03 mitigation).
+//
+// Fail-open everywhere (D-03): a missing server binary, missing
+// .agentfs/.planning, a missing/unset env guard, or a failed subprocess call
+// must never wedge an OpenCode session — the whole handler is try/catch, and
+// a missing staging file after a fire-and-forget event handler is a tolerated
+// degraded outcome, not a retry loop (Pitfall 3).
+
+const SERVER_ENTRY = "@@INFRA_ROOT@@/mcp-memory-server/dist/index.js"
+const MAX_CHARS = 12000
+const RETENTION_CAP = 5
+
+type SessionMessage = {
+  info?: { role?: string }
+  parts?: Array<{ type?: string; text?: string }>
+}
+
+// Runs `node <serverEntry> extract <model>` piping `input` on stdin via
+// Node's own child_process API (never the plugin runtime's `$` BunShell
+// helper — live verification found `$`...`.quiet().nothrow()`'s returned
+// promise has no usable `.stdin` writer at runtime in this OpenCode build,
+// throwing `TypeError: undefined is not an object (evaluating
+// 'shellPromise.stdin.getWriter')` on every call, which silently no-oped
+// capture end to end via the outer fail-open catch (OCP-06 defect, this
+// phase). Async/non-blocking so a slow extraction call never freezes a live
+// interactive session; bounded by `timeoutMs` and resolves (never rejects)
+// so the caller's existing fail-open handling is unchanged.
+function runExtract(
+  serverEntry: string,
+  model: string,
+  input: string,
+  timeoutMs = 120000,
+): Promise<{ stdout: string; stderr: string }> {
+  return new Promise((resolvePromise) => {
+    let stdout = ""
+    let stderr = ""
+    let settled = false
+    const finish = () => {
+      if (settled) return
+      settled = true
+      clearTimeout(timer)
+      resolvePromise({ stdout, stderr })
+    }
+
+    const child = spawn("node", [serverEntry, "extract", model], {
+      stdio: ["pipe", "pipe", "pipe"],
+    })
+    const timer = setTimeout(() => {
+      try {
+        child.kill("SIGTERM")
+      } catch {
+        // best-effort kill only
+      }
+    }, timeoutMs)
+
+    child.stdout?.on("data", (chunk: Buffer) => {
+      stdout += chunk.toString("utf8")
+    })
+    child.stderr?.on("data", (chunk: Buffer) => {
+      stderr += chunk.toString("utf8")
+    })
+    child.on("close", finish)
+    child.on("error", finish)
+
+    child.stdin.write(input)
+    child.stdin.end()
+  })
+}
+
+// Reimplements scripts/transcript-to-text.mjs's behavior (skip tool/reasoning/
+// file noise, join user/assistant text in order, cap total length keeping the
+// most recent turns) against OpenCode's { info, parts } message shape rather
+// than Claude's JSONL transcript shape (Pattern 3).
+function messagesToText(messages: SessionMessage[]): string {
+  const turns: string[] = []
+  for (const message of messages) {
+    const role = message.info?.role
+    if (role !== "user" && role !== "assistant") continue
+    const text = (message.parts ?? [])
+      .filter((part) => part && part.type === "text" && typeof part.text === "string")
+      .map((part) => part.text as string)
+      .join("\n")
+      .trim()
+    if (!text) continue
+    turns.push(`${role === "user" ? "USER" : "ASSISTANT"}: ${text}`)
+  }
+  let out = turns.join("\n\n")
+  if (out.length > MAX_CHARS) out = out.slice(-MAX_CHARS)
+  return out
+}
+
+export const MemoryCapturePlugin: Plugin = async ({ client, directory }) => {
+  const processed = new Set<string>()
+
+  return {
+    event: async ({ event }) => {
+      try {
+        if (event.type !== "session.idle") return
+        const sessionID = event.properties?.sessionID
+        if (!sessionID) return
+        // De-dupe: one attempt per real top-level session, no matter how
+        // many times session.idle fires within it (Pitfall 2).
+        if (processed.has(sessionID)) return
+
+        const repo = directory
+        const agentfsDb = path.join(repo, ".agentfs", "project.db")
+        if (!fs.existsSync(agentfsDb)) return
+        if (!fs.existsSync(SERVER_ENTRY)) return
+
+        const apiKey = process.env.CAIRN_LLM_API_KEY
+        const model = process.env.CAIRN_LLM_EXTRACTION_MODEL
+        if (!apiKey || !model) return
+
+        // session.idle's event payload only carries sessionID (no parentID) —
+        // fetch the full session record to filter out subagent subsessions
+        // (Pitfall 2: subagent tool calls also idle and would otherwise
+        // over-stage past the 5-session retention cap's intent).
+        const sessionRes = await client.session.get({ path: { id: sessionID } })
+        const session = (sessionRes as { data?: { parentID?: string } })?.data
+        if (session?.parentID) return
+
+        // Mark processed before doing the (possibly slow) extract call so a
+        // second session.idle fire for this session never double-attempts,
+        // even if this attempt ultimately yields no staged file.
+        processed.add(sessionID)
+
+        const messagesRes = await client.session.messages({ path: { id: sessionID } })
+        const messages = ((messagesRes as { data?: SessionMessage[] })?.data ?? []) as SessionMessage[]
+        const text = messagesToText(messages)
+        if (!text) return
+
+        // Pipe the session text into the shared `extract` subcommand via
+        // stdin (T-04-01 mitigation) — never string-interpolate arbitrary
+        // session/message content into the shell command.
+        const res = await runExtract(SERVER_ENTRY, model, text)
+        const candidatesJson = String(res.stdout ?? "").trim()
+        if (!candidatesJson) return
+
+        let parsed: { candidates?: unknown[] }
+        try {
+          parsed = JSON.parse(candidatesJson)
+        } catch {
+          return
+        }
+        if (!Array.isArray(parsed.candidates) || parsed.candidates.length === 0) return
+
+        // Stage for the next session's accept gate — identical contract to
+        // claude/hooks/memory-capture.sh (D-08): one file per session, same
+        // candidate JSON shape, same UTC timestamp filename.
+        const stagingDir = path.join(repo, ".planning", "memory-staging")
+        fs.mkdirSync(stagingDir, { recursive: true })
+        const ts = new Date().toISOString().replace(/[-:]/g, "").replace(/\.\d+Z$/, "Z")
+        const stageFile = path.join(stagingDir, `${ts}.json`)
+        fs.writeFileSync(stageFile, `${candidatesJson}\n`)
+
+        // Keep the staging dir bounded — drop the oldest beyond 5 sessions.
+        const staged = fs
+          .readdirSync(stagingDir)
+          .filter((f) => f.endsWith(".json"))
+          .map((f) => ({ f, mtime: fs.statSync(path.join(stagingDir, f)).mtimeMs }))
+          .sort((a, b) => b.mtime - a.mtime)
+        for (const { f } of staged.slice(RETENTION_CAP)) {
+          fs.unlinkSync(path.join(stagingDir, f))
+        }
+      } catch {
+        // Fail open — never block a session because capture failed.
+      }
+    },
+  }
+}