fix(review): align tool contracts and smoke docs

Author: vicary

docs/SmokeTests.md

@@ -102,9 +102,9 @@ explicit by returning `action` and the relevant identifiers/counts directly.
     when you resume an interrupted topic, need the exact wording of a pinned user
     instruction, or want to verify what you previously noted before acting on it.
 
-    If `id` is provided, returns that single note. If `id` is omitted, returns all
-    notes for the current session. Returns
-    `{ notes: [{ note_id, text, created_at, updated_at }] }`.
+    Use this after `session_search` returns a matching note hit. `session_notes_read`
+    requires `id` and returns `{ note: { id, text, created_at, updated_at } }`.
+    When the note does not exist, it returns `{ note: null }`.
 
     Always prefer reading a pinned note over reciting its contents from recall —
     notes are the source of truth for intentionally preserved context.
@@ -130,9 +130,10 @@ response. When `id` is omitted and no notes exist, returns `{ notes: [] }`
     - Before re-solving a problem that may already have a solution in session history
     - To check whether pinned session notes already contain the context you need
 
-    Results may include indexed memory content (type: "memory") and, when pinned
-    session notes exist, matching notes (type: "note"). Note results include a
-    `note_id` — use `session_notes_read` with that id to reopen the full note
+    Results may include exact indexed hits (type: "entry"), summaries
+    (type: "summary"), and, when pinned session notes exist, matching notes
+    (type: "note"). Note results include an `id` — use `session_notes_read`
+    with that id to reopen the full note
     text. Not every query will return note results; notes only appear when they
     match the search query and the session has pinned notes.
 
@@ -159,9 +160,10 @@ tracked session has `biasState` `"new-session"` or `"post-compaction"`. See Task
     - Before re-solving a problem that may already have a solution in session history
     - To check whether pinned session notes already contain the context you need
 
-    Results may include indexed memory content (type: "memory") and, when pinned
-    session notes exist, matching notes (type: "note"). Note results include a
-    `note_id` — use `session_notes_read` with that id to reopen the full note
+    Results may include exact indexed hits (type: "entry"), summaries
+    (type: "summary"), and, when pinned session notes exist, matching notes
+    (type: "note"). Note results include an `id` — use `session_notes_read`
+    with that id to reopen the full note
     text. Not every query will return note results; notes only appear when they
     match the search query and the session has pinned notes.
 
@@ -429,21 +431,20 @@ compaction-envelope tests for notes will be added to this existing file.
   `{ action: "deleted", note_id }`
 - `session_notes_write` with empty text + replace `"*"` → returns
   `{ action: "replaced", cleared_count }`
-  - `session_notes_read` without id → returns all notes
-  - `session_notes_read` with id → returns single note
-  - `session_notes_read` with no notes → returns `{ notes: [] }`
+  - `session_notes_read` with id → returns a single note
+  - `session_notes_read` with a missing note → returns `{ note: null }`
   - Responses validate against the Zod response schemas
 
 - [ ] **Step 3: Write failing tests for `session_search` note merge**
 
-  - `session_search` returns note hits with `type: "note"` and `note_id`
-  - Existing memory results have `type: "memory"` (or undefined for backward
-    compat)
+  - `session_search` returns note hits with `type: "note"` and `id`
+  - Existing indexed hits use `type: "entry"`; summary-only hits use
+    `type: "summary"`
   - Note hits and memory hits coexist in the results array, sorted by score
     descending
   - Note hits include snippet from note text
-  - When no notes exist, search returns only memory results (no empty note
-    entries)
+  - When no notes exist, search returns only entry/summary results (no empty
+    note entries)
 
 - [ ] **Step 4: Accept `SessionNotesService` as runtime option**
 
@@ -459,8 +460,8 @@ compaction-envelope tests for notes will be added to this existing file.
 
   In the `session_search` handler, after `searchLocalCorpus()`, also call
   `notesService.searchNotes()`. Merge results:
-  - Memory hits: `type: "memory"` (or omit for backward compat)
-  - Note hits: `type: "note"`, `note_id` set, `corpus_ref` set to note ref
+  - Indexed hits: `type: "entry"`; summary hits: `type: "summary"`
+  - Note hits: `type: "note"`, `id` set, `corpus_ref` set to note ref
   - Sort merged results by score descending — both sources produce `0`–`1`
     floats so interleaving by score is meaningful
   - Cap total results conservatively to avoid overwhelming output

docs/superpowers/plans/2026-04-11-session-notes-anti-drift.md

@@ -44,7 +44,7 @@ Use two Redis hashes:
   - `created_at`
   - `updated_at`
 
-2. `project:{groupId}:notes`
+2. `session:notes:${groupId}`
 
 - same-project cross-session note store
 - field: `id`
@@ -74,12 +74,12 @@ scoped.
 
 Public note identity is `id`, not `note_id`.
 
-`id` must be unique within `project:{groupId}:notes`.
+`id` must be unique within `session:notes:${groupId}`.
 
 On note creation:
 
 1. Generate a UUID.
-2. Check whether `project:{groupId}:notes` already contains that `id`.
+2. Check whether `session:notes:${groupId}` already contains that `id`.
 3. If yes, generate a new UUID and retry until unique.
 4. Persist the new note to both stores.
 

docs/superpowers/specs/2026-04-11-session-notes-anti-drift-design.md

@@ -39,7 +39,7 @@ The desired behavior is:
 
 - `session:{rootSessionId}:notes` stores current-session note bodies and is used
   for compaction note injection
-- `project:{groupId}:notes` stores same-project notes for cross-session search
+- `session:notes:${groupId}` stores same-project notes for cross-session search
   and direct reopen by `id`
 
 ### Search Ranking
@@ -220,7 +220,7 @@ Stored fields remain:
 
 ### Project Store
 
-`project:{groupId}:notes`
+`session:notes:${groupId}`
 
 - remains the cross-session source of truth for same-project search and direct
   reopen by `id`

docs/superpowers/specs/2026-05-10-session-notes-freshness-without-ttl-design.md

@@ -0,0 +1,14 @@
+import { assertEquals } from "jsr:@std/assert@^1.0.0";
+
+import { createSnapshotSummaryResult } from "./redis-snapshot.ts";
+
+Deno.test("createSnapshotSummaryResult keeps session scope separate from temporal granularity", () => {
+  const result = createSnapshotSummaryResult({
+    rootSessionId: "root-1",
+    created_at: "2026-06-05T00:00:00.000Z",
+    snippet: "snapshot summary",
+  });
+
+  assertEquals(result.scope, "session");
+  assertEquals(result.granularity, undefined);
+});

src/services/redis-snapshot.test.ts

@@ -34,7 +34,7 @@ export const createSnapshotSummaryResult = (input: {
   id: input.id ?? input.created_at,
   root_session_id: input.rootSessionId,
   scope: "session",
-  granularity: input.granularity ?? "session",
+  granularity: input.granularity,
   source: "snapshot",
 });
 

src/services/redis-snapshot.ts

@@ -132,7 +132,7 @@ export const SESSION_NOTES_READ_DESCRIPTION = [
   "- When you need the exact wording of a pinned user instruction, plan, or",
   "  checklist before acting on it.",
   "",
-  "If `id` is provided, returns that single note as",
+  "returns that single note as",
   "`{ note: { id, text, created_at, updated_at } }`; when the id does not exist,",
   "returns `{ note: null }`.",
   "",
@@ -158,7 +158,7 @@ export const SESSION_SEARCH_BASELINE_DESCRIPTION = [
   "  history, or contradicting an earlier decision.",
   "- To check whether pinned session notes already contain the context you need.",
   "",
-  'Results may include indexed memory content (type: "memory") and, when pinned',
+  'Results may include exact indexed hits (type: "entry"), summaries (type: "summary"), and, when pinned',
   'session notes exist, matching notes (type: "note"). Note results include',
   '`id`, `root_session_id`, `scope: "local" | "project"`, `created_at`, and',
   "`updated_at` — when a note hit is relevant, immediately call",
@@ -234,7 +234,7 @@ const sessionMcpToolArgs: Record<SessionMcpToolName, PluginToolArgs> = {
     replace: pluginSchema.string().min(1).optional(),
   },
   session_notes_read: {
-    id: pluginSchema.string().min(1).optional(),
+    id: pluginSchema.string().min(1),
   },
 };
 

src/services/session-mcp-runtime.ts

@@ -52,6 +52,7 @@ describe("tool routing", () => {
     }
     assertEquals(decision.reason, "webfetch-denied");
     assertStringIncludes(decision.guidance, "WebFetch");
+    assertStringIncludes(decision.guidance, "session_fetch_and_index");
   });
 
   it("rewrites Bash curl commands", () => {

src/services/tool-routing.test.ts

@@ -98,7 +98,7 @@ const routeWebFetch = (): RoutingDecision => ({
   action: "deny",
   reason: "webfetch-denied",
   guidance:
-    "WebFetch is blocked. Use a safer search/fetch flow instead of raw page fetches.",
+    "WebFetch is blocked. Use session_fetch_and_index to fetch the URL, then session_search to query the fetched content.",
 });
 
 const routeBash = (