kenaz 0.0.0-stage → 0.3.2

package/core/.kenaz/designs/TASK_1385_handoff_mcp_design.md

@@ -0,0 +1,426 @@
+# TASK_1385 · Specialist Handoff MCP/HTTP Design
+
+**Status**: v2 — Amelia v1 review fixes applied (7 issues addressed); awaiting v2 sign-off
+**Version history**:
+- v1 (2026-05-01 ~07:05): initial draft. Amelia v1 review found 7 issues — see review log for details.
+- v2 (2026-05-01 ~07:15): logic fixes — ADR-4 archive-before-overwrite scoped by `session_id` only; schema enum drift resolved (Rust contracts to `FatigueWarning` only); System B citation added (§10 #4); Phase B includes ritual rewrite + reader switch + dual-write writer atomically; cross-machine sync promoted from Open Question to §9 spec with `originating_machine_id` + `written_at_db_clock`; ADR rune confidence 0.85 → 0.7 (deferred bump to TASK_1386 Phase A).
+**Author**: Ansuz (in-session draft, 2026-05-01)
+**Scope**: System A "active slot" handoff only — System B (TASK_905 ISBAR archive) and other Plane B state files explicitly out of scope per evidence-driven scope review
+
+---
+
+## 1. Background
+
+The active-slot handoff (`<project>/.kenaz/specialist/ansuz_session_handoff.json`) carries fatigue-triggered context across an Ansuz session boundary. Phase 11 (fatigue_warning trigger) writes; Phase 0 Tier 3x reads, ingests into Hippocampus as an episode, and unlinks. At most ONE file exists at any time per project.
+
+Three observed problems with the current file-based design:
+
+1. **Path resolution fragility** — TASK_1380 surfaced that callers may compute the wrong `.kenaz/` path under MCP-spawned cwd inheritance. Symptom: CognitiveLabs sub-project Ansuz session loaded a 0-byte / wrong-project handoff. TASK_1384 fixes the propagation but does not eliminate the fragility class.
+2. **Writer-reader asymmetry** — writer is the Ansuz LLM executing a kernel ritual via the Edit tool; reader is `phase-gate.js` Node code. A ritual-step skipped or partially executed by the LLM produces a malformed file the reader must defensively skip. No central validation.
+3. **Cross-machine non-portability** — Wishing Well syncs `memory.db`; the handoff JSON file does not travel between machines.
+
+This design moves the active-slot handoff to a typed HTTP endpoint backed by `memory.db`, with an MCP wrapper for AI-agent consumers and direct HTTP for `phase-gate.js`. The Ansuz LLM ritual changes from "Edit a JSON file" to "call `hippocampus_handoff_write` MCP tool".
+
+---
+
+## 2. Current State (System A vs System B)
+
+| Aspect | System A — Active Slot (THIS DESIGN) | System B — TASK_905 ISBAR Archive (OUT OF SCOPE) |
+|---|---|---|
+| Path | `<project>/.kenaz/specialist/ansuz_session_handoff.json` | `<project>/.kenaz/specialist/ansuz/handoffs/{sessionId}_{ts}.yaml` + `latest.yaml` + `archive/` |
+| Schema | `ansuz_session_handoff.schema.json` (JSON Schema draft-07) | YAML, defined inline in `ansuz-handoff.js` |
+| Trigger | muninn `fatigue_warning` injected into Ansuz prompt | Programmatic via `preservation-coordinator.js` |
+| Writer | Ansuz LLM executes kernel ritual (`fatigue_handoff.yaml` step 5: `Edit` file) | `ansuz-handoff.writeHandoff()` (Node) |
+| Reader | `phase-gate.js:restoreSessionHandoff()` Tier 3x → ingest episode + unlink | `session.js:756` reads via `ansuzHandoff.readLatestHandoff()` |
+| Lifecycle | Single slot, consumed-on-read | Append + archive >10, gzip compression |
+| Stale window | None (consumed immediately) | 24h, then null |
+| Project validation | None at write/read | `path.resolve(record.project_path)` cross-check at read |
+
+**This design redesigns System A only.** System B is functional and orthogonal; touching it expands scope without evidence of need.
+
+---
+
+## 3. Target Architecture
+
+```
+┌── Phase 11 fatigue_handoff ritual ───────────────────────────┐
+│                                                              │
+│  Ansuz LLM:                                                  │
+│    mcp__kenaz-dashboard__hippocampus_handoff_write({         │
+│      session_id, project_id, specialist_id: 'ansuz',         │
+│      isbar: { identification, situation, background,         │
+│               assessment, recommendation },                  │
+│      triggered_by: 'fatigue_warning',                        │
+│      fatigue_potential, context_size_kb                      │
+│    })                                                        │
+│                                                              │
+│  Server (Rust):                                              │
+│    1. Validate ISBAR shape against schema                    │
+│    2. INSERT INTO specialist_handoff (...)                   │
+│    3. If existing unconsumed handoff for                     │
+│       (project_id, specialist_id):                           │
+│         set replaced_by_id = new.id                          │
+│         (archive-before-overwrite is implicit)               │
+│    4. Return { id, created_at }                              │
+└──────────────────────────────────────────────────────────────┘
+
+┌── Phase 0 Tier 3x ───────────────────────────────────────────┐
+│                                                              │
+│  phase-gate.js (HTTP):                                       │
+│    GET /api/hippocampus/handoff?project_id=X                 │
+│        &specialist_id=ansuz&consume=true                     │
+│                                                              │
+│  Server (Rust):                                              │
+│    1. SELECT latest unconsumed for (project, specialist)     │
+│    2. If found: ingest as Hippocampus episode (existing      │
+│       conversion logic preserved server-side)                │
+│    3. UPDATE consumed_at = now WHERE id = found.id           │
+│    4. Return { handoff: {...}, episode_id }                  │
+│                                                              │
+│  phase-gate.js consumes summary, no file deletion needed.    │
+└──────────────────────────────────────────────────────────────┘
+```
+
+**Key invariant preserved**: Phase 0 still archives the consumed handoff into Hippocampus episode with `agent_skill: 'session_handoff'`. The episode is the long-term memory; the new table is the durable inbox until consumption.
+
+---
+
+## 4. ADRs
+
+### ADR-1 · Storage backend → memory.db, new table `specialist_handoff`
+
+| Option | Pros | Cons |
+|---|---|---|
+| **(a) memory.db new table** ← chosen | Single DB, ops simplicity; Wishing Well already syncs memory.db; transactional with episode insert | Couples handoff lifecycle to memory.db availability |
+| (b) New specialist_state.db | Clean separation | Two DBs to back up / sync / migrate |
+| (c) Reuse Hippocampus episode table | One table to rule them all | Conflates "inbox" and "archive" semantics; episode close ≠ handoff consume; no unique active-slot enforcement |
+
+**Decision**: (a). Add `specialist_handoff` table. Episode ingest at consume time is a separate row insert in `episode_entries` — handoff and episode keep their distinct purposes.
+
+### ADR-2 · Endpoint shape → typed `/api/hippocampus/handoff`
+
+| Option | Pros | Cons |
+|---|---|---|
+| (a) Generic `/api/specialist/state/{key}` arbitrary JSON | Future-proof for other Plane B candidates | Schema enforcement deferred to clients; invites drift |
+| **(b) Typed `/api/hippocampus/handoff`** ← chosen | Server validates ISBAR; no future drift | One endpoint per state type; more code surface if many types |
+
+**Decision**: (b). Drift risk dominates; the "future Plane B candidates" we cited as motivating generic are now explicitly out of scope (no observed failures). When/if a second state type joins Plane B, copy the pattern; do not generalize prematurely.
+
+### ADR-3 · Transport → HTTP + MCP wrapper
+
+| Consumer | Preferred surface |
+|---|---|
+| `phase-gate.js` (Node CLI, not MCP-aware) | HTTP `GET /api/hippocampus/handoff?consume=true` |
+| Ansuz LLM (Phase 11 ritual) | MCP `hippocampus_handoff_write` |
+| Future debug CLI / dashboard UI | HTTP + MCP both available |
+
+**Decision**: HTTP is the canonical surface; MCP is a thin wrapper over HTTP. Existing pattern matches `synapse_*` family. No MCP-only or HTTP-only.
+
+### ADR-4 · Retention → keep all rows + `consumed_at`; archive-before-overwrite scoped by `session_id` only
+
+**Amelia v1 review caught a logic contradiction**: scoping archive-before-overwrite by `(project_id, specialist_id)` would silently mark a parallel-session A's handoff `consumed_at` when session B writes 30s later — silent loss exactly like the file-based design's collision bug. Fixed in v2 by scoping by `session_id` only.
+
+```
+specialist_handoff
+  id                TEXT PK
+  session_id        TEXT NOT NULL
+  project_id        TEXT NOT NULL
+  specialist_id     TEXT NOT NULL  -- 'ansuz' for now (single-value); future: 'amelia' | 'huginn'
+  triggered_by      TEXT NOT NULL  -- 'fatigue_warning' (matches JSON Schema enum exactly; no Manual/ContextSize until schema expanded)
+  isbar_json        TEXT NOT NULL  -- serialized ISBAR object, schema-validated at write
+  fatigue_potential REAL
+  context_size_kb   INTEGER
+  originating_machine_id TEXT       -- TASK_1385 v2: machine where written (uname/hostname); supports cross-machine sync detection
+  written_at_db_clock INTEGER NOT NULL  -- server INTEGER ms — used by reader to detect handoffs from other machines arriving via Wishing Well
+  created_at        INTEGER NOT NULL  -- client wall-clock (may differ across machines)
+  consumed_at       INTEGER         -- NULL = unconsumed (active inbox)
+  replaced_by_id    TEXT            -- pointer to handoff that superseded this same session_id's prior unconsumed handoff
+  consumed_episode_id TEXT          -- episode_entries.id created at consume
+```
+
+Indexes:
+- `(project_id, specialist_id, consumed_at)` — partial index WHERE consumed_at IS NULL for the active-slot lookup
+- `(session_id)` — same-session re-fire detection
+- `(created_at)` — history queries
+
+**Retention policy**: Keep all rows. Storage cost ~10KB × N sessions; even at 10 handoffs/day for a year that's <40MB. If pressure emerges, add a vacuum job that deletes `consumed_at < now() - 90 days`.
+
+**Archive-before-overwrite semantics (v2, scoped by session_id)**: At write time, check for existing unconsumed row with the **same `session_id`**. If found: set `old.replaced_by_id = new.id`, set `old.consumed_at = now()`, INSERT a Hippocampus episode for the displaced row (`agent_skill: 'session_handoff'`, outcome: 'overwritten') in the same transaction. INSERT new row with `consumed_at IS NULL`. This faithfully mirrors the existing fatigue_handoff.yaml step 3 same-session-double-fire archive behavior — parallel sessions never collide.
+
+**Reader semantics (active-slot lookup)**: `SELECT * FROM specialist_handoff WHERE project_id = ? AND specialist_id = ? AND consumed_at IS NULL ORDER BY created_at DESC LIMIT 1`. If multiple unconsumed rows exist (different session_ids — parallel sessions both wrote), reader returns the most recent and DOES NOT auto-consume the older. Older parallel-session handoffs remain in inbox until the user explicitly opens that session for next /Ansuz boot, OR until staleness vacuum runs.
+
+### ADR-5 · Concurrency (multi-Ansuz session) → session_id-keyed isolation, no auto-overwrite across sessions
+
+**v2 reconciliation with ADR-4**: each session has unique `session_id`, writes its own row. Auto-overwrite (per ADR-4) ONLY triggers within the same `session_id` (same-session double-fatigue). Different sessions' handoffs coexist as multiple unconsumed rows; reader takes latest by `created_at`.
+
+| Option | Behavior |
+|---|---|
+| (a) Row-lock single handoff per (project, specialist) | Rejected: false serialization on rare event; A blocks B |
+| **(b) session_id-keyed isolation, multi-row coexistence** ← chosen | Each session writes its own row; same-session re-fire archives to episode + replaces; cross-session never auto-touches each other |
+| (c) Reject concurrent writes | Rejected: drops state; collision rate not high enough to warrant rejection cost |
+
+Solves `feedback_parallel_ansuz_file_collision` memory: file-based design silently overwrites between concurrent sessions; DB design preserves all parallel handoffs as separate rows.
+
+---
+
+## 5. Schema
+
+### 5.1 Canonical (Rust struct in `dashboard/src-tauri/src/features/hippocampus/handoff.rs`)
+
+```rust
+#[derive(Serialize, Deserialize, Debug, Clone)]
+pub struct Handoff {
+    pub id: String,                       // UUIDv4
+    pub session_id: String,
+    pub project_id: String,
+    pub specialist_id: String,            // 'ansuz' only for now (matches schema constraint)
+    pub triggered_by: TriggeredBy,        // enum: FatigueWarning ONLY (matches JSON Schema enum)
+    pub isbar: Isbar,
+    pub fatigue_potential: Option<f64>,
+    pub context_size_kb: Option<u32>,
+    pub originating_machine_id: Option<String>,  // hostname/uname
+    pub written_at_db_clock: i64,         // server clock at write
+    pub created_at: DateTime<Utc>,
+    pub consumed_at: Option<DateTime<Utc>>,
+    pub replaced_by_id: Option<String>,
+    pub consumed_episode_id: Option<String>,
+}
+
+#[derive(Serialize, Deserialize, Debug, Clone)]
+#[serde(rename_all = "snake_case")]
+pub enum TriggeredBy {
+    FatigueWarning,  // ONLY value; matches JSON Schema enum exactly
+}
+
+#[derive(Serialize, Deserialize, Debug, Clone)]
+pub struct Isbar {
+    pub identification: Identification,
+    pub situation: Situation,
+    pub background: Background,
+    pub assessment: Assessment,
+    pub recommendation: Recommendation,
+}
+// inner fields mirror ansuz_session_handoff.schema.json exactly
+```
+
+**v2 fix**: removed `Manual | ContextSize` variants from `TriggeredBy`. Only `FatigueWarning` is currently authorized by JSON Schema. Adding new variants requires atomic update across all 3 surfaces (JSON Schema enum + Rust enum + TS interface) in a single PR — see ADR-2 reasoning.
+
+### 5.2 TypeScript mirror (hand-mirrored)
+
+Hand-mirrored for now (single type). File: `dashboard/src/lib/handoff.ts`. Includes `tsTriggeredBy = 'fatigue_warning'` literal type matching Rust enum exactly. When Plane B grows beyond handoff, evaluate `ts-rs` codegen.
+
+### 5.3 JSON Schema (existing `ansuz_session_handoff.schema.json`) — canonical source of truth
+
+Already exists as draft-07 with `triggered_by` enum constrained to `["fatigue_warning"]`. Server-side validation: write endpoint validates payload against this schema (using `jsonschema` crate). Reject 400 on schema violation.
+
+**Drift detection (ships in Phase A, not later)**: `cargo test schema_compatibility` test added in Phase A:
+1. Loads `ansuz_session_handoff.schema.json`
+2. Reflects on `Handoff` struct via `schemars` or manual schema export
+3. Asserts every JSON Schema enum value appears in the corresponding Rust enum AND vice versa
+4. Asserts every required JSON Schema field maps to a non-Option Rust field
+5. Asserts Zod schema (loaded as JSON) matches the Rust-derived schema
+
+CI fails if any layer drifts. **Update protocol when adding a new enum value**: open a single PR that touches all three surfaces simultaneously; the test cannot pass on partial updates.
+
+---
+
+## 6. Endpoint Specification
+
+### 6.1 POST `/api/hippocampus/handoff`
+
+Write a new handoff. Idempotency-key via `session_id` (re-POST with same session_id is allowed but creates a new row — fatigue can fire twice in one session).
+
+Request body:
+```json
+{
+  "session_id": "ansuz-1777615255619",
+  "project_id": "proj_1774545608638_gyvs5lz",
+  "specialist_id": "ansuz",
+  "triggered_by": "fatigue_warning",
+  "fatigue_potential": 1.05,
+  "context_size_kb": 142,
+  "isbar": { /* per schema */ }
+}
+```
+
+Responses:
+- `201 Created`: `{ id, created_at, replaced_id?: string }` — `replaced_id` present iff archive-before-overwrite triggered
+- `400 Bad Request`: schema validation error, with field-level error array
+- `500 Internal Server Error`: DB or unexpected error
+
+### 6.2 GET `/api/hippocampus/handoff`
+
+Read latest unconsumed handoff for `(project_id, specialist_id)`. Optional `consume=true` flag marks the returned handoff consumed and ingests it into Hippocampus episode in the same transaction.
+
+Query params:
+- `project_id` (required)
+- `specialist_id` (required)
+- `consume` (optional, default `false`) — when `true`, set `consumed_at = now()` and create episode
+
+Responses:
+- `200 OK`: `{ handoff: Handoff | null, episode_id?: string }`
+- `404 Not Found`: explicit alternative when caller wants negative confirmation; default `200` with `null` is preferred
+- `500`: DB error
+
+### 6.3 GET `/api/hippocampus/handoff/history`
+
+History query for debug/audit.
+
+Query params: `project_id`, `specialist_id`, `limit=10`, `include_consumed=true`
+
+Response: `{ handoffs: [Handoff], total_count }`
+
+### 6.4 POST `/api/hippocampus/handoff/{id}/consume`
+
+Manual consume endpoint (debug/manual recovery). Idempotent.
+
+Response: `200 OK` `{ id, consumed_at, episode_id }` or `404`.
+
+---
+
+## 7. MCP Wrapper Definitions
+
+```typescript
+// dashboard/src-tauri/src/infrastructure/http_server/routes/mcp_tools/hippocampus.rs additions
+
+mcp_tool("hippocampus_handoff_write", {
+  description: "Write Ansuz/specialist session handoff (ISBAR). Called at fatigue_warning trigger.",
+  input_schema: {
+    session_id: string,
+    project_id: string (default: active project),
+    specialist_id: string (default: 'ansuz'),
+    triggered_by: enum,
+    isbar: object,
+    fatigue_potential?: number,
+    context_size_kb?: number,
+  },
+  output: { id, created_at, replaced_id? },
+})
+
+mcp_tool("hippocampus_handoff_read", {
+  description: "Read latest unconsumed handoff for the active project. Returns null if none.",
+  input_schema: {
+    project_id: string (default: active project),
+    specialist_id: string (default: 'ansuz'),
+    consume: boolean (default: true),
+  },
+  output: { handoff: object | null, episode_id?: string },
+})
+
+mcp_tool("hippocampus_handoff_history", {
+  description: "Query handoff history for debug. Includes consumed and unconsumed rows.",
+  input_schema: { project_id, specialist_id, limit?: 10, include_consumed?: true },
+  output: { handoffs: array, total_count: number },
+})
+```
+
+---
+
+## 8. Migration Plan (TASK_1386 phasing) — v2 corrections
+
+**v2 fixes from Amelia review**: ritual rewrite moved from Phase F to Phase B (kernel.yaml step 3 archive-before-overwrite logic must move server-side BEFORE the LLM ritual diverges); reader is HTTP-first from Phase B onward (eliminates dual-source-of-truth window); explicit handling of MCP-OK + file-fail asymmetric failure mode.
+
+| Phase | Action | Risk | Rollback |
+|---|---|---|---|
+| **A** (T+0) | Server: Add `specialist_handoff` table + write/read/consume/history HTTP endpoints + 3 MCP wrappers + `cargo test schema_compatibility` drift detector. **No client changes**. | None | Drop table |
+| **B** (T+1d) | **Atomic kernel rewrite + reader switch + dual-write writer**: (1) `fatigue_handoff.yaml` step 3 deleted (server owns archive-before-overwrite per ADR-4); step 5 replaced with `mcp__kenaz-dashboard__hippocampus_handoff_write` call. (2) `phase-gate.js:restoreSessionHandoff` switches to **HTTP-first** with file fallback for not-yet-cut-over sessions. (3) Phase 11 LLM ritual ALSO writes file as belt-and-suspenders for MCP-fail case. Both writes recorded in dual-write log so failure mode visible. | Medium — coordinated 3-file change | Revert all three; keep both servers responsive |
+| **C** (T+3d) | Verify ≥3 successful Phase 0 boots have used HTTP path successfully (per project). Confirm file fallback never triggered. | Low — observation only | n/a |
+| **D** (T+7d) | If C green: drop file write at Phase 11 ritual (LLM only calls MCP). HTTP becomes authoritative writer. | Medium — first irreversible step | Re-enable file write in fatigue_handoff.yaml |
+| **E** (T+14d) | Drop file-fallback in `phase-gate.js:restoreSessionHandoff`. HTTP-only end-to-end. | Low — D verified absence of fallback hits | Re-enable fallback |
+| **F** (T+30d) | Remove `restoreSessionHandoff` file path code; remove `ANSUZ_HANDOFF_PATH` constant; ash inscribe; close TASK_1386. | None — cleanup | Trivial revert |
+
+**Asymmetric failure handling at Phase B**:
+
+| State | Reader (HTTP-first) sees | Resolution |
+|---|---|---|
+| MCP-OK + file-OK | Reader gets handoff via HTTP; file unread; file-fallback never triggers | ✓ canonical path |
+| MCP-OK + file-fail | Reader gets handoff via HTTP; file may not exist; OK | ✓ HTTP authoritative |
+| MCP-fail + file-OK | Reader queries HTTP, gets null/error; falls back to file; reads + ingests episode + unlinks file | ✓ rescue path; **alert** logs MCP-fail |
+| MCP-fail + file-fail | Reader gets nothing; Phase 0 banner shows session_handoff_loaded=false (current behavior preserved) | ✓ no regression |
+
+**Dual-write log location**: `<project>/.kenaz/specialist/dual_write_audit.jsonl` (append-only) — each write logs both surfaces' outcomes. Phase D entry condition: zero MCP-fail entries in the audit log over 3 successful boots.
+
+**Each phase has explicit acceptance**: A handoff write+read cycle on (1) KenazAI core, (2) CognitiveLabs sub-project, (3) cross-machine after Wishing Well sync — see §6.5.
+
+---
+
+## 9. Cross-Machine Sync Spec (v2 promotion from Open Question)
+
+Wishing Well syncs `memory.db` between user's machines but the sync is asynchronous and may lag minutes-to-hours. A handoff written on machine A may not be available on machine B yet when the user opens /Ansuz there. v1 buried this in Open Questions. v2 makes it a first-class concern.
+
+**Schema additions (already in §4 ADR-4)**: `originating_machine_id` + `written_at_db_clock`.
+
+**Reader behavior**:
+
+```
+GET /api/hippocampus/handoff?project_id=X&specialist_id=ansuz&consume=true
+
+Server logic:
+  1. Load latest unconsumed for (project, specialist)
+  2. If found:
+       a. Check originating_machine_id vs current_machine_id (uname/hostname)
+       b. Check written_at_db_clock vs memory.db's last_sync_at_meta
+       c. If from-different-machine OR before-last-sync: include staleness flag in response
+  3. Return: { handoff, episode_id, cross_machine: bool, db_age_at_write_seconds: int }
+```
+
+**Phase 0 banner display when cross_machine=true**:
+
+```
+ᚨ Ansuz online — handoff loaded from machine "iMac-Studio" (written 2h ago, synced 5m ago)
+   Topic: <isbar.situation.current_topic>
+```
+
+This makes cross-machine handoff visible (not silent) so the user knows they're picking up another machine's session.
+
+**Sync-receipt acknowledgment (defer to TASK_1386 Phase E)**: when a handoff is consumed, optionally write a "consumed-on-machine-X" record back so machine A doesn't re-surface it. Implementation deferred — for v2 design, accepting "best-effort cross-machine handoff" is sufficient.
+
+## 10. Open Questions for Review (v2 — narrowed)
+
+1. **Specialist scope** — should the table be `specialist_handoff` or `ansuz_handoff`? Generic name is forward-compatible (Amelia/Huginn might want handoffs eventually); specific is honest about current usage. **Default: `specialist_handoff` with `specialist_id` column. Constrained at JSON Schema level to `'ansuz'` until evidence supports more.**
+
+2. **Schema source of truth resolution path** — JSON Schema canonical + Rust enum + TS literal type. Phase A test enforces consistency. When adding a new triggered_by value (e.g. `manual_override`), the protocol is: open single PR touching all 3 surfaces; test fails on partial. Confirm this protocol acceptable.
+
+3. **Phase D entry trigger** — "zero MCP-fail entries in dual-write audit log over 3 successful boots". Is 3 enough, or should it be e.g. 10 boots across 3 distinct projects? **Default: 3 boots, ≥1 of which MUST be a sub-project (CognitiveLabs) — captures the original bug surface.**
+
+4. **System B (TASK_905 ISBAR archive) interaction** — confirmed no overlap of file paths. `session.js:756` reads System B specifically via `ansuzHandoff.readLatestHandoff(BASE_DIR)` (also calls `:776` `acknowledgeHandoff`, `:782` `ansuzState.readState`); writer is `preservation-coordinator.js:450` calling `ansuzHandoff.writeHandoff(projectPath, sessionId, trigger, {...})`. Verified 2026-05-01 via `grep -n "writeHandoff\|readLatestHandoff" .specialist/Ansuz/tools/*.js .specialist/tools/session.js`. System B continues file-based throughout TASK_1386; future task may migrate it but is **explicitly OUT OF SCOPE here**.
+
+---
+
+## 10. Out of Scope (explicit)
+
+- **System B (TASK_905 ISBAR archive)** — `ansuz/handoffs/{sid}_{ts}.yaml` history + `latest.yaml` + `archive/`. Different role (history vs inbox), different consumers (`session.js` Tier 3 vs phase-gate Tier 3x). Functional, no observed bugs. Could be migrated to a `specialist_handoff_archive` table later but not now.
+- **Other Plane B candidates** — `ansuz_session_report.json`, `ansuz_predictions.json`, `ansuz_self_model.json`, `motivational_state.json`, `ansuz_motivational_state.json`, `ambient_signals.json`, `initiator_state.json`. No observed user-visible failures. TASK_1384 covers their path-propagation theoretical bug pragmatically. Future migration only when concrete failure surfaces.
+- **Plane C event logs** — append-only JSONL files (`pulse_log`, `ddx_log`, `inscribe_log`, etc.). Already structurally robust under append-only file pattern. Path propagation handled by TASK_1384.
+- **Specialist self-model and motivational states** — touch identity-formation, distinct concerns, would benefit from MCP but not now.
+- **User-scoped state** (`user_model.json`, `~/.kenaz/user_profile.json`) — different scope (cross-project). Independent design conversation.
+
+---
+
+## 11. Acceptance for TASK_1385 (this task)
+
+This document committed under `.kenaz/designs/TASK_1385_handoff_mcp_design.md` ✓
+
+5 ADR runes inscribed in Synapse via `synapse_inscribe` (type=`decision`, **v2 confidence 0.7** per Amelia review note: unimplemented design proposals — bump to 0.9 after TASK_1386 Phase A passes acceptance):
+
+- ADR-1: storage backend → memory.db new table (`rune_60cdb600ead44d168f035a74d106cf87`)
+- ADR-2: endpoint shape → typed (`rune_6ff830957a4140309acf2b66ecf56e10`)
+- ADR-3: transport → HTTP + MCP (`rune_71e19e8a8bb44a03be6eed3f39182372`)
+- ADR-4: retention → keep all + consumed_at; archive-before-overwrite scoped by session_id only (`rune_fc836fd1e2324351a1f7366a2459e459`)
+- ADR-5: concurrency → session_id keyed isolation, cross-session never auto-touch (`rune_e1be78d013614da7870675825425e825`)
+
+Amelia or user sign-off on **v2** design captured in Status field.
+
+When passed: TASK_1386 can be opened with concrete sub-task acceptance derived from §8 migration phases (A/B/C/D/E/F).
+
+---
+
+## 12. Triggers / Trail
+
+- 2026-04-30: TASK_1380 partial fix; CognitiveLabs handoff loss surfaced
+- 2026-05-01 morning: Ansuz session diagnosed half-fix pattern; Amelia audit established TASK_1384 scope (path propagation)
+- 2026-05-01 mid: user proposed MCP-ification of handoff ("讓 Ansuz 有規範")
+- 2026-05-01 mid: Ansuz proposed full Plane B framework redesign; user challenged scope; reduced to handoff-only per evidence rule
+- 2026-05-01 late: this design drafted in-session
+
+This task is the design phase for the user-visible bug observed at the start of the trail. Implementation lives in TASK_1386 (not yet opened).

package/core/.kenaz/designs/TASK_932_hippocampus_consolidation.md

@@ -0,0 +1,103 @@
+# TASK_932: Hippocampus Episode Consolidation — Architecture Draft
+
+## Problem Statement
+
+Episodes in Hippocampus never consolidate or decay. A 6-month-old episode with
+10 entries takes the same space and has the same recall priority as yesterday's
+critical debugging session. There's no mechanism for:
+- Compressing old episodes into schemas
+- Identifying cross-episode patterns
+- Prioritizing novel/important episodes for consolidation
+- Forgetting truly irrelevant episodes
+
+## Biological Model (Nature Human Behaviour 2024)
+
+1. **Hybrid storage**: Fast autoassociative encoding (episodes) + slow generative learning (schemas)
+2. **Age-dependent consolidation**: Young = detailed, old = schema-based
+3. **Semantic emergence**: Repeated patterns across episodes crystallize into knowledge
+4. **Novelty prioritization**: Surprising episodes get priority consolidation
+5. **Constructive recall**: Reconstruct from latent patterns, not literal storage
+
+## Proposed Consolidation Pipeline
+
+### Phase 1: Episode Scoring (daily cron or on-demand)
+
+For each closed episode, compute a **consolidation score**:
+
+```
+ConsolidationScore(ep) = Novelty(ep) * Utility(ep) * Age(ep)
+
+Novelty = surprise_score from Norn predictions (high surprise = novel)
+        + rune_inscription_count (more runes = more discovered knowledge)
+        + task_outcome != 'success' (failures are more informative)
+
+Utility = acted_on_count of runes linked to this episode's symbols
+        + recall_count (how often this episode was recalled by future sessions)
+
+Age     = days_since_creation (older = higher consolidation pressure)
+```
+
+### Phase 2: Consolidation Tiers
+
+| Tier | Age | Action |
+|------|-----|--------|
+| **Fresh** | 0-7 days | No consolidation. Full detail preserved. |
+| **Warm** | 7-30 days | Compress entries to summary + lesson + key_facts. Drop raw content. |
+| **Cool** | 30-90 days | If ConsolidationScore < threshold: merge similar episodes into schema-episode. |
+| **Archive** | 90+ days | If recall_count = 0 AND rune_links = 0: mark as archival (excluded from default recall). |
+
+### Phase 3: Cross-Episode Pattern Detection (monthly)
+
+```
+1. Group episodes by touched_symbols overlap (> 3 shared symbols)
+2. For each group: extract common lessons/outcomes
+3. If common pattern found across 3+ episodes → crystallize as Sigil
+4. If common fix pattern → crystallize as Ash Rune
+```
+
+This is the "replay" mechanism — re-reading old episodes to find patterns
+that single-session extraction missed.
+
+### Phase 4: Novelty-Based Priority Queue
+
+Integrate with Norn Curiosity:
+- Episodes with high surprise scores get priority for consolidation (replayed first)
+- Episodes linked to symbols with active Thalamus cascades get priority
+- FOREVER-style spaced repetition: consolidation intervals follow Ebbinghaus curve (1,3,7,15,30 days)
+
+### Schema Format (Consolidated Episode)
+
+```json
+{
+  "id": "schema_ep_xxx",
+  "type": "consolidated",
+  "source_episodes": ["ep_001", "ep_002", "ep_003"],
+  "time_span": {"from": "2026-01-15", "to": "2026-03-20"},
+  "key_facts": ["fact 1", "fact 2"],
+  "lesson": "consolidated lesson",
+  "pattern": "description of cross-episode pattern",
+  "confidence": 0.8,
+  "recall_count": 0,
+  "touched_symbols": ["sym_a", "sym_b"]
+}
+```
+
+### Implementation Path
+
+Phase A: Add consolidation_score computation to episode recall (read-only metric)
+Phase B: Implement Warm tier compression (7+ day episodes → summary-only)
+Phase C: Implement cross-episode pattern detection (monthly batch)
+Phase D: Integrate with FOREVER-style spaced repetition for review scheduling
+
+### Open Questions
+
+1. Should consolidation be in Rust (performance) or JS (flexibility)?
+2. How to handle episodes that span multiple tasks?
+3. Should archived episodes be deletable or permanently retained?
+4. How to measure if consolidation improves recall quality?
+
+### References
+
+- Nature Human Behaviour 2024 (pubmed/38242925): Generative model of memory construction
+- arxiv 2601.03938 (FOREVER): Forgetting curve-inspired replay scheduling
+- arxiv 2508.11347 (SAGE): Scale-aware gradual evolution for continual KG embedding

package/core/.kenaz/designs/TASK_934_efe_signal_engine.md

@@ -0,0 +1,97 @@
+# TASK_934: EFE-Based Unified Signal Decision Engine — Architecture Draft
+
+## Problem Statement
+
+Kenaz currently has fragmented signal systems:
+- **Heat** (Thalamus): recent edit intensity per symbol
+- **Curiosity** (Norn): predicted next-change symbols via co-change
+- **Knowledge Gaps** (Synapse): symbols with high traffic but zero runes
+- **Task Priorities** (task-api): manually assigned P0-P3
+- **Health Score** (Heimdall): structural health metrics
+- **Ambient Signals** (preamble): hot symbols, curiosity spikes
+
+Ansuz currently combines these via **human-like judgment** — no formal decision framework.
+The Curiosity formula uses **multiplication** which has a zero-problem.
+
+## Proposed Architecture: Expected Free Energy (EFE)
+
+Based on active inference (arxiv 2504.14898).
+
+### Core Formula
+
+```
+EFE(action_a) = G_risk(a) + G_ambiguity(a) + G_novelty(a)
+q*(a) = softmax(-EFE(a) / temperature)
+```
+
+### Signal Mapping
+
+| EFE Component | Signal Source | Formula |
+|---------------|-------------|---------|
+| **G_risk** | Heat + task priority + bug density | `heat(s) * priority_weight(s) + rune_risk_count(s)` |
+| **G_ambiguity** | InformationGap (5 sub-factors) + orphan_ratio + test coverage | Existing InformationGap formula (weighted sum) |
+| **G_novelty** | Prediction (co-change) * Recency * surprise_history | `P(s|hot_cluster) * recency(s) * (1 - prediction_accuracy(s))` |
+
+### Key Design Decisions
+
+1. **Additive, not multiplicative**: G components are summed. A well-documented symbol (low G_ambiguity) can still attract attention via high G_risk.
+
+2. **Temperature parameter**: Controls exploration/exploitation balance.
+   - Low temperature → exploit (focus on highest-EFE actions)
+   - High temperature → explore (more uniform distribution)
+   - Could be adaptive: high temperature when health is good, low when under pressure
+
+3. **Action space**: What are the "actions" that EFE ranks?
+   - `investigate(symbol)` — deep-dive a symbol
+   - `fix(symbol)` — address a known issue
+   - `inscribe(symbol)` — fill a knowledge gap
+   - `dispatch(task)` — execute a queued task
+   - `explore(topic)` — curiosity-driven research
+
+4. **Incremental updates**: EFE recomputes as signals change.
+   - On commit: Heat updates → G_risk changes
+   - On rune inscribe: G_ambiguity decreases for that symbol
+   - On task completion: G_risk decreases, G_novelty may increase (new predictions)
+
+### Architecture Layers
+
+```
+Layer 1: Signal Collection
+├── Heat Engine (real-time, per-symbol)
+├── Curiosity Engine (periodic, batch predictions)
+├── Knowledge Gap Scanner (on-demand)
+├── Task Priority Reader (event-driven)
+└── Health Score (periodic snapshots)
+
+Layer 2: EFE Computation
+├── G_risk aggregator: combines Heat + priority + risk runes
+├── G_ambiguity aggregator: uses InformationGap + orphan status
+├── G_novelty aggregator: uses Prediction + Recency + surprise
+└── Policy: softmax(-EFE / temperature) → ranked actions
+
+Layer 3: Policy Consumer
+├── Ansuz Phase 2 (background research targets)
+├── Huginn (auto-mode hypothesis generation)
+├── Preamble (top-K signals for session injection)
+└── Dashboard UI (signal visualization)
+```
+
+### Implementation Path
+
+Phase 1: Compute EFE for all symbols using existing signals (read-only)
+Phase 2: Replace Curiosity multiplicative formula with EFE additive
+Phase 3: Add temperature adaptation based on health score
+Phase 4: Integrate as Ansuz decision engine for autonomous sessions
+
+### Open Questions
+
+1. Should G_risk include Thalamus cascade state? (fire_count, potential)
+2. How to handle symbols with no heat data (cold start)?
+3. Should EFE be computed in Rust (fast, per-commit) or JS (flexible, per-session)?
+4. What's the right temperature range? Need empirical calibration.
+
+### References
+
+- arxiv 2504.14898: Expected Free Energy-based Planning as Variational Inference
+- arxiv 2409.05386: Predictive Coding with SNNs — free energy framework
+- arxiv 2501.01974: Hawkes-based TKG — temporal influence decay for G_novelty