memtrace-skills 0.7.25 → 0.8.0

package/plugins/memtrace-skills/skills/memtrace-code-review/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: memtrace-code-review
-description: "Always use when the user asks to review a GitHub pull request, run Memtrace code review, post Memtrace review comments, create a PR with a review step, or publish local graph-backed review findings to GitHub. Prefer the review_github_pr MCP tool over manual diff inspection."
+description: "Review GitHub pull requests with Memtrace's local graph-backed review engine. Use when the user asks to review a GitHub pull request, run Memtrace code review, post Memtrace review comments, create a PR with a review step, or publish local graph-backed review findings to GitHub. Prefer the review_github_pr MCP tool over manual diff inspection. Do not use for local working-tree diffs — that is the built-in /code-review; this skill is for GitHub PRs via review_github_pr."
 ---
 
 ## Overview
@@ -15,6 +15,8 @@ Use Memtrace's local-first PR review workflow. The agent should call the `review
 4. Default to `minSeverity: "high"` and `maxComments: 5` when posting. For previews, `maxComments: 10` is acceptable.
 5. Pass `repoRoot` when the PR checkout is not the current working directory. Pass `repoId` when the indexed repository id is known.
 
+Full parameter spec for every Memtrace tool: `references/mcp-parameters.md` (bundled at the memtrace-skills plugin root).
+
 ## Example User Prompts
 
 - "Review this PR with Memtrace: https://github.com/OWNER/REPO/pull/123"
@@ -25,6 +27,7 @@ Use Memtrace's local-first PR review workflow. The agent should call the `review
 
 - Do not start with generic grep, rg, or manual diff review when `review_github_pr` is available.
 - Do not post comments unless the user explicitly requested publication.
+- After posting comments (`post: true`), record the PR URL and the posted comment IDs in the session output as the audit trail.
 - Do not create benchmark-specific or PR-specific findings. The review must come from general Memtrace detectors, graph evidence, and policy ranking.
 - If the tool reports missing auth, tell the user to run `memtrace auth login`.
 - If the tool reports missing GitHub App installation, tell the user to install Memtrace Code Reviewer on that repository.
@@ -32,10 +35,11 @@ Use Memtrace's local-first PR review workflow. The agent should call the `review
 
 ## Output
 
-For previews, summarize:
-- PR URL and repository
-- Graph state
-- Number of candidate comments
-- File, line, severity, and message for each finding
+Summarize the `review_github_pr` result with these fields:
 
-For posted reviews, report the PR URL and number of comments posted.
+| Field | Preview (`post: false`) | Posted (`post: true`) |
+|---|---|---|
+| PR URL + repository | yes | yes |
+| Graph state | yes | yes |
+| Findings | count of candidate comments, plus file, line, severity, message per finding | number of comments posted |
+| Posted comment IDs | — | yes — record with the PR URL as the audit trail |

package/plugins/memtrace-skills/skills/memtrace-codebase-exploration/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: memtrace-codebase-exploration
-description: "Always use when the user wants to explore, understand, onboard to, map, or get an overview of an indexed source-code repo, architecture, modules, or major flows. Do not use Glob, find, tree, rg, or manual file browsing as the first exploration path; Memtrace provides structured graph briefing."
+description: "Map an indexed source-code repo into a structured overview — scale, communities, central symbols, execution flows, API surface, recent activity. Use when the user wants to explore, understand, onboard to, map, or get an overview of an indexed source-code repo, architecture, modules, or major flows. Do not use Glob, find, tree, rg, or manual file browsing as the first exploration path; Memtrace provides structured graph briefing. Do NOT use for change history / what-changed questions — use memtrace-evolution."
 ---
 
 ## Overview
@@ -36,7 +36,11 @@ Each community represents a cohesive module — these are the "areas" of the cod
 
 ### 4. Find the most important symbols
 
-Call `find_central_symbols` with `limit: 15`. It ranks symbols by PageRank over the repo's CALLS / REFERENCES edges (default `method: "pagerank"`, 0.85 damping factor).
+Call `find_central_symbols` — PageRank over CALLS/REFERENCES edges (no `method` param):
+
+```json
+{ "repo_id": "<repo>", "limit": 15 }
+```
 
 These are the symbols that the rest of the codebase depends on most heavily. They form the "skeleton" of the architecture.
 
@@ -64,13 +68,29 @@ Call `find_api_endpoints` to list all HTTP routes.
 
 ### 8. Recent activity
 
-Call `get_evolution` with mode `overview` and a 30-day window to see which modules have been most active recently.
+Call `get_evolution` to see recent activity:
+
+```json
+{ "repo_id": "<repo>", "from": "30d ago", "mode": "overview" }
+```
+
+Check `totals.episode_count` and episode boundaries. For file/symbol hotspots, switch to `compound`:
 
-**Decision:** If the user asks about specific recent changes, switch to mode `compound` for symbol-level detail.
+```json
+{ "repo_id": "<repo>", "from": "30d ago", "mode": "compound" }
+```
+
+Review `top_changed_files` and `top_touched_symbols`.
 
 ### 9. Complexity hotspots
 
-Call `find_most_complex_functions` with `limit: 10` to identify potential technical debt.
+Call `find_most_complex_functions`:
+
+```json
+{ "repo_id": "<repo>", "top_n": 10 }
+```
+
+Full parameter spec for every Memtrace tool: `references/mcp-parameters.md` (bundled at the memtrace-skills plugin root).
 
 ## Report Synthesis
 
@@ -84,6 +104,18 @@ Synthesize findings into a structured overview:
 6. **Recent Activity** — what's been changing in the last 30 days
 7. **Technical Debt** — complexity hotspots and potential dead code
 
+## Output
+
+The deliverable is the 7-part overview above. Skeleton (one headline per part):
+
+1. Scale — 2 languages, 4,812 symbols, 19,344 relationships
+2. Architecture — 12 communities; top 5: auth, indexing, api, ui, billing
+3. Critical Infrastructure — `EngineHandle::open` (central AND bridge — flag it)
+4. Execution Flows — 14 processes: 9 HTTP handlers, 3 CLI commands, 2 jobs
+5. API Surface — 42 endpoints; 2 cross-repo service dependencies
+6. Recent Activity — 31 episodes in 30d; hottest file per `top_changed_files`
+7. Technical Debt — top-10 complex functions, highest complexity first
+
 ## Common Mistakes
 
 | Mistake | Reality |

package/plugins/memtrace-skills/skills/memtrace-continuous-memory/SKILL.md

@@ -1,96 +1,90 @@
 ---
 name: memtrace-continuous-memory
-description: "Always use when the user asks to keep Memtrace fresh while editing, watch a repo, enable live or incremental indexing, set up always-on memory, or make just-saved source code queryable immediately. Do not fall back to repeated Grep or manual rescans; configure Memtrace watching."
+description: "Keep the Memtrace index fresh while editing by watching a repo for live, incremental re-indexing. Use when the user asks to keep Memtrace fresh while editing, watch a repo, enable live or incremental indexing, set up always-on memory (meaning Memtrace index watching, not generic agent memory), or make just-saved source code queryable immediately. Do not fall back to repeated Grep or manual rescans; configure Memtrace watching."
 ---
 
 ## Overview
 
-Memtrace keeps the knowledge graph live as you edit. Once you call `watch_directory`, every save runs through the **incremental indexing fast-path** — a notify-based file watcher debounces saves, the indexer re-parses only the touched files, and the engine commits the delta in a single WAL transaction. Steady-state latency is **~80 ms from save to queryable** on a typical project.
+Keep the knowledge graph live while editing. `watch_directory` triggers incremental re-indexing on file saves (~80 ms typical latency after debounce).
 
-This is what makes "session continuity" actually work: by the time you ask `find_symbol` after a save, the new symbol is already in the graph.
+## Required parameters — `watch_directory`
+
+| Param | Required | Notes |
+|---|---|---|
+| `path` | yes | Absolute directory path |
+| `repo_id` | yes | Must already be indexed |
+| `branch` | no | default `"main"` |
+
+```json
+{ "path": "/abs/path/to/repo", "repo_id": "memdb" }
+```
+
+Full parameter spec for every Memtrace tool: `references/mcp-parameters.md` (bundled at the memtrace-skills plugin root).
 
 ## Steps
 
-### 1. Confirm the repo is indexed
+### 1. Confirm indexed
 
 ```
-mcp__memtrace__list_indexed_repositories
+list_indexed_repositories()
 ```
 
-If the repo isn't there, run `index_directory` first. The watcher requires an existing repo_id — it never bootstraps from scratch.
+Run `index_directory` first if missing (poll `check_job_status`; stop after ~5 minutes and report the job id — see memtrace-index).
 
 ### 2. Start watching
 
-```
-mcp__memtrace__watch_directory(
-  path: "/abs/path/to/repo"
-)
-```
-
-The tool registers a `notify` watcher on the directory tree, debounces save bursts (so a `:wq` that touches a swap file doesn't trigger twice), and routes deltas through the indexer's incremental fast-path. Returns immediately — watching runs in the background.
+See JSON above. Returns immediately; watcher runs in background.
 
-### 3. Confirm it's live
+### 3. Confirm active watches
 
 ```
-mcp__memtrace__list_watched_paths
+list_watched_paths()
 ```
 
-Each entry shows the watched root, the bound repo_id, and the last delta's `persist_ms`.
+Response shape: see [Output](#output).
 
-### 4. Edit normally — Memtrace catches up
+### 4. Edit normally
 
-After every save the watcher emits a `labels_updated` WebSocket event:
+Next `find_symbol` / `get_symbol_context` call sees saved changes after debounce (~500 ms) + incremental persist (~80 ms).
 
-```json
-{
-  "event":           "labels_updated",
-  "repo_id":         "demo",
-  "nodes_changed":   12,
-  "persist_ms":      78,
-  "timestamp":       "2026-04-27T10:42:13Z"
-}
-```
+### 5. Stop watching (kill switch)
 
-Dashboards and IDE plugins subscribe to this on `/ws` and refresh themselves. As an agent you don't have to listen — your next `find_symbol` / `find_code` / `get_symbol_context` call will see the new state automatically.
+`unwatch_directory`:
 
-### 5. Stop watching
-
-```
-mcp__memtrace__unwatch_directory(path: "/abs/path/to/repo")
+```json
+{ "path": "/abs/path/to/repo" }
 ```
 
 Idempotent — unwatching an already-unwatched path is a no-op.
 
-## When to Use
+## Latency expectations
 
-- **Long sessions on the same repo** — keeps `get_symbol_context` accurate without rerunning `index_directory`
-- **Pair programming with an IDE plugin** — the dashboard's WebSocket subscription auto-refreshes panels
-- **Demo / live coding** — every save reflects in the graph within 80–150 ms
-- **Long-running agents** — instead of polling `index_directory`, the watcher pushes deltas
-
-## When NOT to Use
+| Stage | Typical |
+|---|---|
+| Debounce | **500 ms** (MCP schema) |
+| Incremental persist | ~80 ms |
+| Save → queryable | ~80–150 ms after debounce |
 
-- **One-shot batch edits** — running `index_directory --incremental` at the end is cheaper than spinning up a watcher
-- **Generated / build output trees** — exclude paths under `target/`, `dist/`, `node_modules/` (the watcher honours common ignore patterns but a noisy build can still saturate the debounce queue)
-- **CI / containerised runs** — file events are unreliable across container boundaries; index explicitly instead
+## Output
 
-## Latency Expectations
+`watch_directory` returns an immediate acknowledgment; the watcher runs in the background. `list_watched_paths` returns:
 
-| Operation | Typical wall time |
-|---|---|
-| File save → watcher fires | < 5 ms |
-| Debounce window | 50 ms |
-| Incremental parse + delta persist | ~80 ms |
-| `labels_updated` broadcast | < 1 ms after persist |
-| Total: save → queryable | ~80–150 ms |
+```json
+{
+  "watches": [
+    { "path": "...", "repo_id": "...", "branch": "...", "started_at": "...", "origin": "..." }
+  ],
+  "count": 1
+}
+```
 
-If you see `persist_ms` consistently above 500 ms, the saved files are larger than expected (e.g., generated bundles) — narrow the watch root or add ignore patterns.
+There is **no `persist_ms`** field in this response.
 
 ## Common Mistakes
 
 | Mistake | Reality |
-|---|---|
-| Calling `watch_directory` on an unindexed repo | Returns an error — run `index_directory` first |
-| Watching `node_modules/` or `target/` | Saturates the watcher with build noise — point at the source root only |
-| Polling `find_symbol` every second to "wait" for indexing | Subscribe to the `labels_updated` WS event, or just call once after the save — the delta is already there |
-| Forgetting to `unwatch_directory` between sessions | Watchers are per-process; restarting `memtrace start` wipes them, but for hosted instances unwatching cleanly avoids leaks |
+|---------|---------|
+| `watch_directory(path=...)` without `repo_id` | **Both required** |
+| Watching unindexed repo | Index first |
+| Expecting `persist_ms` from `list_watched_paths` | Field not in MCP response |
+| Debounce "50 ms" | Schema documents **500 ms** |

package/plugins/memtrace-skills/skills/memtrace-daily/SKILL.md

@@ -0,0 +1,63 @@
+---
+name: memtrace-daily
+description: "Orient at the start of a coding session, review what recently changed in a repository, and self-audit after completing work. Use when the user wants the daily briefing (what changed in the last 24h with complexity deltas), hotspots (complexity × churn refactor priorities), or a session review (clean/review/risky verdicts per editing session). For catching up after time away or resuming a prior session, use memtrace-session-continuity; daily is the last-24h briefing + hotspots + self-audit. Do not reconstruct recent activity from git log; Memtrace diffs the graph at save granularity."
+---
+
+## Overview
+
+Session bookends: orient before you start, audit before you finish. All
+three tools read the bi-temporal version history — every save is a change
+event with complexity deltas, so "what happened" includes "did it make the
+code better or worse".
+
+## Quick Reference
+
+| Tool | Purpose |
+|------|---------|
+| `get_daily_briefing` | Last 24h diffed at graph level: changed functions with complexity deltas, new functions, new endpoints, per-module distribution |
+| `find_hotspots` | Functions ranked by complexity × recent changes — the ordered refactor priority list |
+| `review_agent_sessions` | Editing sessions clustered by actor, judged clean / review / risky |
+
+> **Parameter types:** MCP parameters are strictly typed. Numbers
+
+Full parameter spec for every Memtrace tool: `references/mcp-parameters.md` (bundled at the memtrace-skills plugin root).
+> (`window_hours`, `window_days`, `top_n`) must be JSON numbers.
+
+## Steps
+
+### 1. Orient at session start
+
+`get_daily_briefing` with `repo_id`. Read the summary first:
+- `net_cyclomatic_delta` positive → recent work added complexity; check
+  whether your task touches the same area before piling on.
+- `changed` rows with large positive deltas → recently-destabilised code;
+  prefer `preflight_check` before editing anything in that list.
+
+### 2. When the task is refactoring or cleanup
+
+`find_hotspots` — work the list top-down. A hotspot you simplify pays off
+on every future change; a complex-but-untouched function can wait.
+
+### 3. Self-audit before declaring work done
+
+`review_agent_sessions` and find YOUR session (newest, your agent id):
+- `clean` — done; state the verdict in your summary.
+- `review` — re-read your top_changes rows; justify each complexity
+  increase or simplify it.
+- `risky` — do not hand off yet. You added >30 net cyclomatic or touched
+  a >50-complexity function; extract helpers / flatten nesting first,
+  then re-run the review.
+
+## The standard a session should meet
+
+Net complexity delta ≤ 0 unless the task genuinely required new branching
+(new feature with new cases). "I left the code simpler than I found it"
+is verifiable here — verify it.
+
+## Output
+
+| Tool | Returns |
+|------|---------|
+| `get_daily_briefing` | summary with `net_cyclomatic_delta`; `changed` rows (function + complexity delta); new functions, new endpoints, per-module distribution |
+| `find_hotspots` | ranked list of functions scored by complexity × recent changes |
+| `review_agent_sessions` | per-session verdict (`clean` / `review` / `risky`) with `top_changes` rows and net cyclomatic delta |

package/plugins/memtrace-skills/skills/memtrace-decision-memory/SKILL.md

@@ -0,0 +1,129 @@
+---
+name: memtrace-decision-memory
+description: "Check Cortex decision memory — the umbrella entry point for decision recall, provenance (why is this here), intent verification, and governing contracts. Use before assuming WHY code exists, before making a choice that may contradict a past one, or before deleting/rewriting code that looks odd or redundant. Route: free-text what-was-decided → memtrace-decision-recall; why does this symbol exist / what constrains it → memtrace-provenance; did the decision hold → memtrace-intent-verification. Do not guess rationale from the diff or git log; Cortex remembers the decision, the ban, and whether it still holds."
+---
+
+# Decision Memory First
+
+## The Iron Law
+
+```
+BEFORE you assume why code exists, contradict a convention, re-pick a settled
+choice, or delete code that "looks unused/weird" → CHECK DECISION MEMORY.
+
+recall_decision(free-text)  →  what did we decide / ban about X?
+why_is_this_here(symbol_id) →  what decision put this here?
+verify_intent(decision_id)  →  did that decision still hold, or was it violated?
+get_arc(decision_id)        →  what episodes implemented it?
+governing_contracts(sym_id) →  what constraints bind this symbol?
+```
+
+This is the **rationale layer** of the codebase. `memtrace-first` answers *what the
+code is and how it's wired* (symbols, calls, git, blast radius). Decision memory
+answers *why it is the way it is, what we already decided, and whether that decision
+still holds* — extracted from real coding conversations and decisions, not the AST.
+
+The graph can tell you a function exists and who calls it. Only decision memory can
+tell you that three weeks ago you **banned** the approach you're about to reintroduce.
+
+Full parameter spec for every Memtrace tool: `references/mcp-parameters.md` (bundled at the memtrace-skills plugin root).
+
+## The honesty contract — read this first
+
+These five tools are **deterministic, zero-LLM**. Every call returns a labeled
+**Verdict / Evidence / CannotProve** answer carrying its FactStatus and proof path.
+**No tool ever fabricates an answer.**
+
+| Answer | What it means | What you must NOT do |
+|---|---|---|
+| **Verdict + Evidence** (Observed / DeterministicallyDerived / StatisticallyRanked) | A recorded decision/provenance backs this | — |
+| **CannotProve** | No recorded decision governs this | Do **not** read it as "safe / approved / unconstrained." It means *unknown*, not *permitted*. Fall back to `memtrace-first` + asking the user. |
+
+`CannotProve` is a real, trustworthy answer ("memory has nothing on this"), not a
+failure and not a green light. Never invent a rationale to fill the gap.
+
+## Server check (once per session)
+
+These tools are served by the **`memcortex`** MCP server (decision memory), separate
+from the `memtrace` code-graph server. If `recall_decision` isn't available, decision
+memory isn't wired in this environment — say so and use `memtrace-first` instead;
+don't fabricate decisions.
+
+## The decision rule
+
+| What you're about to do / be asked | Right tool | Sub-skill |
+|---|---|---|
+| "Did we already decide/choose/reject X?" "What's our convention on Y?" | `recall_decision("X")` | `memtrace-decision-recall` |
+| "Is there a ban / a 'don't do this' on Z?" | `recall_decision("Z")` — bans surface as decisions | `memtrace-decision-recall` |
+| About to re-pick a library/pattern/approach | `recall_decision` FIRST — don't re-litigate a settled call | `memtrace-decision-recall` |
+| "Why is this code here?" "Why is it done this odd way?" | `why_is_this_here(symbol_id)` | `memtrace-provenance` |
+| About to delete/refactor code that looks unused or strange | `why_is_this_here` + `governing_contracts` before touching it | `memtrace-provenance` |
+| "What rules/contracts constrain this symbol?" | `governing_contracts(symbol_id)` | `memtrace-provenance` |
+| "Did decision D actually hold, or did we drift?" | `verify_intent(decision_id)` | `memtrace-intent-verification` |
+| "What commits/episodes implemented decision D?" | `get_arc(decision_id)` | `memtrace-intent-verification` |
+
+## How the tools chain (ids come from recall, not from names)
+
+Only `recall_decision` takes free text. The other four take **numeric node ids**
+(`decision_id` / `symbol_id`, uint64). The normal flow is:
+
+```
+recall_decision("auth strategy")
+        │  returns ranked hits, decisions first: [{ id, kind: "decision", ... }]
+        │  (pick a kind:"decision" hit; conversation hits are context, not chainable)
+        ├─► verify_intent(decision_id)   did it hold?
+        └─► get_arc(decision_id)         what implemented it?
+
+why_is_this_here(symbol_id)
+        │  returns the governing decision lineage for a symbol
+        └─► verify_intent(that decision_id)   is that rationale still valid?
+```
+
+`symbol_id` comes from a prior recall/arc result or the Cortex view — **if you only
+have a name or a free-text question, start with `recall_decision`.** Do not invent ids.
+
+## Standard workflows
+
+### "Why does this code exist / can I delete it?"
+1. `why_is_this_here(symbol_id)` → the governing decision, if any
+2. `governing_contracts(symbol_id)` → constraints that must survive a rewrite
+3. If a decision governs it → `verify_intent(decision_id)` to see if it still holds
+4. **CannotProve on all three ≠ safe to delete** — confirm with `memtrace-impact` (blast radius) and the user
+
+### "Should I do X?" (about to make a choice)
+1. `recall_decision("X")` → did we already decide or ban this?
+2. If a prior decision exists → `verify_intent(decision_id)` → is it still in force?
+3. Honor a held decision; only revisit a `ViolatedAt`/superseded one — and say so explicitly
+
+### "Did we follow through on decision D?"
+1. `verify_intent(decision_id)` → Held | ViolatedAt | CannotProve
+2. `get_arc(decision_id)` → the episodes that implemented (or should have) it
+
+## Red flags — STOP, check decision memory
+
+| Thought | Reality |
+|---|---|
+| "This code looks unused, I'll delete it" | `why_is_this_here` first — a decision may govern it; deletion may reopen a closed issue |
+| "I'll just use library/pattern X" | `recall_decision("X")` — you may be undoing a deliberate ban |
+| "The diff/git log will tell me why" | Git shows *what changed*, not *what was decided or rejected*. Decision memory has the rationale and the bans. |
+| "CannotProve, so it's fine/approved" | CannotProve = unknown, not approved. Don't treat absence of a record as permission. |
+| "I'll guess the rationale from the code" | Don't fabricate a why. Return what the tool proves, or say it's unknown. |
+
+## Skill priority
+
+This is a **process skill** — it runs alongside `memtrace-first` before
+implementation. Use `memtrace-first` for *what/where/impact* (code graph); use
+decision memory for *why/whether-it-held* (rationale). When both apply, decision
+memory gates the intent, the code graph gates the mechanics.
+
+## Output
+
+The routing outcome: which sibling skill/tool to invoke, and the evidence to quote.
+
+```
+Ask:    "Should I switch to library X?"
+Route:  recall_decision("library X")   →  memtrace-decision-recall
+Hit:    { id: 4217, kind: "decision", ... }   (a ban exists)
+Next:   verify_intent(4217)            →  memtrace-intent-verification
+Quote:  Verdict + Evidence (FactStatus, proof path) — or CannotProve = unknown, not permission
+```

package/plugins/memtrace-skills/skills/memtrace-decision-recall/SKILL.md

@@ -0,0 +1,83 @@
+---
+name: memtrace-decision-recall
+description: "Recall ranked decisions, bans, and conventions from Cortex decision memory by free-text query. Use when the user asks what was decided, what was chosen or rejected, whether there's a convention/ban/policy on something, or before re-picking a library, pattern, or approach that may already be settled. Do not reconstruct past decisions from git log or guesswork. To verify whether a known decision held, use memtrace-intent-verification; for symbol-scoped decision lineage/contracts, use memtrace-provenance."
+---
+
+## Overview
+
+`recall_decision` is the **free-text entry point** to decision memory. Given a query,
+it returns the statistically-ranked set of decisions/conversations that bear on it —
+including **bans** ("never use X", "don't do Y"), which are recorded as decisions.
+Use it before re-litigating a settled choice or contradicting a convention.
+
+This is the one decision-memory tool that takes plain text. The ranked decisions it
+returns carry the `decision_id`s the other tools (`verify_intent`, `get_arc`) need.
+
+Full parameter spec for every Memtrace tool: `references/mcp-parameters.md` (bundled at the memtrace-skills plugin root).
+
+## Quick Reference
+
+| Tool | Purpose |
+|------|---------|
+| `recall_decision` | Ranked decisions/bans for a free-text query (the entry point) |
+| `verify_intent` | Given a returned `decision_id` — did it still hold? (see `memtrace-intent-verification`) |
+| `get_arc` | Given a returned `decision_id` — what implemented it? (see `memtrace-intent-verification`) |
+
+> **Honesty contract:** an empty or unknown query returns an explicit **CannotProve**,
+> never a fabricated decision. CannotProve means "no recorded decision on this" — it is
+> *unknown*, not *approved*. Don't treat it as a green light.
+
+## Steps
+
+### 1. Query in the user's own terms
+
+`recall_decision(query)` — `query` is free text. Use the noun phrase of the thing in
+question: a library (`"redis vs in-memory cache"`), a pattern (`"error handling
+strategy"`), a subsystem (`"auth tokens"`), or the exact thing you're about to do.
+
+### 2. Read the ranked result
+
+Results come back ranked (lexical + semantic lanes, RRF-fused) with an `id`, a
+`kind`, and a score per hit. **`decision`-kind hits are ranked first**; lower-ranked
+`conversation` hits are supporting context (the verbatim turns around the decision).
+For anything you mean to chain (step 4), use a hit whose `kind` is `decision` — its
+`id` is the `decision_id` the other tools require.
+
+### 3. Act on what's there
+
+| Result | Action |
+|---|---|
+| A matching decision | Honor it. Quote it back to the user before doing anything that contradicts it. |
+| A **ban** ("never/don't …") | Do **not** reintroduce the banned approach without explicit user sign-off. |
+| Several competing/old hits | Run `verify_intent(decision_id)` on the top one to see if it still holds before relying on it. |
+| **CannotProve** | No recorded decision. Don't invent one — fall back to `memtrace-first` and/or ask the user. |
+
+### 4. Chain into the id-based tools when you need more
+
+The `id` of a `kind: "decision"` hit feeds `verify_intent` (did it hold?) and
+`get_arc` (what implemented it?). Don't pass a `conversation` hit's id — those tools
+require a Decision node and will honestly return CannotProve. See
+`memtrace-intent-verification`.
+
+## Decision Points
+
+| Situation | Action |
+|-----------|--------|
+| About to choose a library/pattern/approach | `recall_decision` FIRST — you may be undoing a deliberate choice or ban |
+| User asks "did we decide X?" / "what's our convention on Y?" | `recall_decision("X" / "Y")` |
+| You suspect a "don't do this" rule exists | `recall_decision` — bans are decisions and will surface |
+| Recall returns a decision you're about to contradict | Surface it to the user verbatim; don't silently override |
+| Recall returns CannotProve | Treat as unknown, not approval; do not fabricate a rationale |
+
+## Output
+
+`recall_decision` returns ranked hits — `kind: "decision"` first, `conversation` hits below as supporting context — or an explicit **CannotProve**:
+
+```json
+[
+  { "id": "…", "kind": "decision", "score": 0.91 },
+  { "id": "…", "kind": "conversation", "score": 0.44 }
+]
+```
+
+Only a `decision`-kind hit's `id` is a `decision_id` usable with `verify_intent` / `get_arc`. An empty or unknown query returns CannotProve, never fabricated hits.