kenaz 0.0.0-stage → 0.3.2

package/core/dev/plans/FORMATION_RETIREMENT_PLAN.md

@@ -0,0 +1,313 @@
+# Formation Retirement Plan (TASK_2359)
+
+Status: plan only, no code removed by this card. Date: 2026-10-09.
+Decision (user, 2026-10-09): the Agent-tool subagent is the only dispatch path; Formation (the `claude -p` headless supervisor) is retired.
+Companion direction (user, 2026-10-09): agents are launched inside the target project folder (native `claude` + kenaz plugin, TASK_2358), not from the core repo with a `[專案: X]` pin.
+
+All line numbers are from main at commit 43fc13878 (worktree wt-566fcb6b). Re-run the verification commands in section 7 before acting on any row; line numbers drift.
+
+---
+
+## 0. Findings that change the shape of the plan
+
+1. **post-complete is not Formation-only.** `task-api.js complete` runs `postComplete()` in-process by default (`.collaboration/core/task-api.js:2142-2160`, `require('../../.formation/tools/post-complete.js')`). The subagent path lands through it. `post-complete.js` (3660 LOC) plus `post-complete/*` stay. Only the `FORMATION_HEADLESS` / `FORMATION_SCHEDULER` comments and tests around it are Formation-specific (`task-api.js:2120,2143-2144`; the env is only *set* by `runner.js:944,1105`, never read by task-api code).
+2. **`dispatch.js` is two programs in one file.** Subagent path: `getSubagentDispatchParams` (`dispatch.js:1454`, entry `:1372`). Formation path: `runSingle`/`runParallel` calls at `dispatch.js:1106,1166` (`require('./runner')` at `:24`), squad/legion prompt branches at `:1067,1075`, `--formation` default at `:1300`. The subagent path does NOT need `runner.js`. Wave 4 splits them.
+3. **`dispatchMode` defaults to `formation`** in `dispatch.js:1546` and in the Dashboard (`ModelSelectionPanel.tsx:89`, `dashboard_settings.rs:38`). Ansuz rules + the Dashboard setting were already switched, but the code default is still the Formation path. Wave 1 flips it before anything is deleted.
+4. **Formation is also the only unattended runner.** Non-task callers spawn `headless.js` with no parent Claude session: Heimdall trigger (`heimdall.rs:197-272,749`), code_watch trigger (`code_watch.rs:165-273`), agent_scheduler (`agent_scheduler/service.rs`), Ansuz sleep/wake on exit and project switch (`lib.rs:138-258,867-870`), `kenaz_specialist_dispatch` (Amelia/Huginn, `kenaz.rs:988-1160`), and the Legacy Scheduler script (`script/manager.rs:215-246,793-799`). The Agent tool only exists inside a live session, so "subagent is the only path" does not cover these. **Decision needed before Wave 2** (section 6, Q1).
+5. **Codex/Bifrost workers run only through Formation today** (section 4). Removing Formation first strands every Codex user's worker dispatch.
+6. **Dead code already in place:** `headless.js:290` is `if (false && !process.env.BIFROST_ADAPTER)`; the `.bifrost-active` auto-detect block never runs. `analytics.js` has exactly one writer (`dispatch-registry.js:71`).
+7. **`roles/_shared/modules/*.yaml` is live** (`prompt.js:103,808`). Only `roles/<name>/role.yaml` is Formation/headless-v2-only.
+
+---
+
+## 1. Caller map
+
+Notation: `file:line` = a real reference found by `git grep` (command in section 7). "R" = require/spawn (hard dependency), "C" = comment/doc/message only, "T" = test.
+
+### 1.1 headless.js (1071 LOC)
+
+| Caller | Line | Kind |
+|---|---|---|
+| `dashboard/src-tauri/.../mcp_tools/kenaz.rs` (`tool_dispatch`, `tool_specialist_dispatch`) | 672-675, 1030-1033 | R spawn |
+| `.../routes/heimdall.rs` | 204,214,749 | R spawn |
+| `.../routes/code_watch.rs` | 172,182,273 | R spawn |
+| `features/agent_scheduler/config.rs` (path), `service.rs` (exec) | config.rs:111-116, service.rs:71 | R spawn |
+| `features/script/manager.rs` (scripts: legacy-scheduler, start-task, 2 more) | 217,227,237,246 | R spawn |
+| `src-tauri/src/lib.rs` (Ansuz sleep/wake fallback) | 140,145,209,214,258,867-870 | R spawn |
+| `.formation/tools/formations.js` | 5,360,1031 | C (extracted from headless) |
+| `.formation/tools/prompt.js` | 901,903 | C: prompt text tells project agents to call `headless.js` |
+| `.formation/tools/task-utils.js` | 39 | R (`headlessPath` string for re-dispatch) |
+| `.formation/tools/dispatch.js` | 1277,1822,1830 | C (help text, parity comments) |
+| `k-cli/src/dispatch/run.ts` | 40,87,88,130 | R: generates prompt text invoking headless-v2/headless |
+| `.specialist/Ansuz/SYSTEM_DOC.md` | 149 | C (doc) |
+| `.specialist/tools/session.js` | 1375 | C |
+| `.collaboration/core/task-api.js` | 2120,2144 | C |
+| `.formation/bifrost/launch.js` | 308 | C+writes `.bifrost-active` consumed by headless (dead, see 0.6) |
+| T: `headless-dryrun.test.js`, `headless-branch-recovery.test.js`, `task2028-headless-worktree.test.js`, `tests/headless-mcp-args-plumbing.test.js`, `dashboard-models-chain.test.js:56-57`, `post-complete/task2345.test.js:35-36`, `spec/task_operations.parity.test.js:31`, `__tests__/m1-hmap-convid.test.js`, `task-2281-singleton-readers.test.js` | various | T |
+
+### 1.2 headless-v2.js (659 LOC)
+
+Callers: `k-cli/src/dispatch/run.ts:39,45,55,125-133,174-178` (prompt text only). No other `require`. It reads `role-map.yaml` (`headless-v2.js:43`) and `roles/*/role.yaml`. Self-contained; safe to delete once k-cli prompt text is rewritten.
+
+### 1.3 formations.js (1203 LOC)
+
+| Caller | Line |
+|---|---|
+| `headless.js` | 53 (`require('./formations')`) |
+| `formations.js` self-requires `./legacy-scheduler` | 988 |
+| T: `__tests__/task2030-worktree-node-modules.test.js:20` (comment), `post-complete/task2028.test.js:16` (comment) | |
+| `dev/scripts/gc-agent-worktrees.js` | 11 (C) |
+
+### 1.4 legacy-scheduler.js (1994 LOC)
+
+| Caller | Line |
+|---|---|
+| `formations.js` | 988 (R) |
+| `features/script/manager.rs` `formation-legacy-scheduler` | 215, 793-794 (spawns `--formation=legacy --skill=scheduler`) |
+| Dashboard UI: `AgentMonitor.tsx:27`, `LegacySchedulerCard.tsx:16-19` (306 LOC), `legacy-scheduler-section/LegacySchedulerSection.tsx:7`, `QuickActionsPanel.tsx:10`, `ScriptsSection.tsx:71` | |
+| `.claude/commands/legacy_dev.md`, `multi-agent.md`, skill `legacy_dev` | doc |
+
+### 1.5 broadcast.js (103 LOC)
+
+Required only by `formations.js:38` and `headless.js:83`. Lazy-loads `supabase-client`, `task-sync`, `commit-sync`. Dies with them (those three stay, see keep-list).
+
+### 1.6 process-state.js (33 LOC)
+
+Required only by `formations.js:37` and `headless.js:52`. Dies with them.
+
+### 1.7 dispatch-registry.js (346 LOC)
+
+| Caller | Line | Verdict |
+|---|---|---|
+| `headless.js` | 51 | dies |
+| `formations.js` | 35 | dies |
+| `task-utils.js` | 14 | dies (task-utils is headless/formations-only) |
+| `.specialist/tools/session.js` | 1554 (`readActiveDispatches`, `isProcessAlive` for orphan detection) | **reader stays until rewritten** (Wave 3) |
+| `dev/scripts/verify-task-1839.js` | 36 | one-off verifier, delete with it |
+| `.kenaz/specialist/verify_1838.js` | 22 | runtime artefact |
+| T: `merge-lock-heartbeat.test.js:7` (`cleanupStaleLocks`) | | moves with whatever keeps merge-lock |
+| Rust writer of `.formation/.active-dispatches.json`: `kenaz.rs:545-640` (`write_preliminary_dispatch`, `set_dispatch_pid_if_unset`), `agent_flow.rs:746` | | dies with `kenaz_dispatch` |
+| Readers of that file: `.claude/hooks/handoff-staleness.js:23,107` (route 1) | | route 1 removed, route 2 (dispatch brief) stays |
+
+### 1.8 analytics.js (172 LOC)
+
+Only writer: `dispatch-registry.js:57,71` (`recordDispatch`). No other `require`. Retires with the registry (Wave 3). `dev/scripts/dispatch-stats.js` reads `dispatch_prompt_stats.jsonl` and `phase9_dispatch_outcomes.jsonl`, not analytics JSONL, so it is unaffected.
+
+### 1.9 Other Formation-only modules (not in the requirement list but verified by grep)
+
+| Module (LOC) | Only callers | Verdict |
+|---|---|---|
+| `runner.js` (1332) | `dispatch.js:24` (Formation branch), `formations.js:22`, `headless.js:46`, `headless-v2.js:31`, `legacy-scheduler.js:39`; T: `pre-dispatch-snapshot.test.js:33`, `worktree-leak.test.js:33` | dies in Wave 4 (after dispatch.js trim) |
+| `logger.js` (273), `log-reader.js` (232) | runner / legacy-scheduler / `kenaz_dispatch_status` | dies with runner |
+| `task-utils.js` (344) | `formations.js:39`, `headless.js:87` | dies |
+| `coordinator.js` (350) | only its own `require`s (supabase-client, task-sync) | no production caller found; confirm then delete |
+| `dispatch-notifier.js` (84) | `formations.js:36` | dies |
+| `test-drift.js`, `revert-daemon-state.js`, `jev-correction.js`, `guard-attribution.js`, `memory-loader.js` | not required by Formation modules; **do not assume Formation-only**, re-grep before touching (memory-loader is required by `prompt.js:17`, stays) | out of scope |
+
+### 1.10 Formation directories and data
+
+| Path | Tracked files | Who reads it | Verdict |
+|---|---|---|---|
+| `.formation/unit/{do,plan,think,heimdall}.yaml` | 4 | `loader.js:27` via `dispatch.js:858,1382,1463` (subagent path loads `unit/do`) | **KEEP** (subagent assembly) |
+| `.formation/solo/*` (2), `squad/*` (4), `legion/*` (2) | 8 | `loadSkill(formation, ...)` when `--formation=solo|squad|legion`; `prompt.js:620-622` members; `dispatch.js:1067,1075` | retire Wave 5 (after confirming no subagent run uses them; subagent path defaults `unit`, `dispatch.js:1454`) |
+| `.formation/roles/_shared/modules/*.yaml` (3) | 3 | `prompt.js:103,808` | **KEEP** |
+| `.formation/roles/<backend,code_reviewer,...>/role.yaml` (10) | 10 | `headless-v2.js` `--role` only | retire Wave 5 |
+| `.formation/lead.yaml` | 1 | `formation_lead` skill / `/lead` command (doc-level) | retire Wave 5 with skill |
+| `.formation/role-map.yaml` | 1 | `headless-v2.js:43`; points at `legacy.bak/*` (lines 195,212) | retire Wave 5 |
+| `.formation/legacy.bak/*` (6) | 6 | `role-map.yaml`, `loadSkill('legacy', ...)` in `legacy-scheduler.js:819,1402` | retire Wave 5 |
+| `.formation/skills/coordinator.yaml`, `briefs/scheduler-evolution.md` | 2 | docs | retire Wave 5 |
+| `.formation/native/claude/*` (README, models.json) | 2 | verify before touching | out of scope |
+| `.formation/runes/*`, `.formation/Users/...` | 5 | stray artefacts (a `.synapse/db/graph` path under `.formation/Users/` is a mis-rooted write) | housekeeping, separate card |
+| `.formation/logs/<formation>/` | runtime | `kenaz.rs:663-670`, `heimdall.rs:132` | stops being written after Wave 2 |
+
+### 1.11 Rust MCP tools and Dashboard
+
+| Item | Locations |
+|---|---|
+| `kenaz_dispatch` | `mcp.rs:745` (arg rewrite), `:818` (route); `definitions.rs:477`; `kenaz.rs:638-847` (`tool_dispatch`) |
+| `kenaz_dispatch_status` | `mcp.rs:819`; `definitions.rs:491`; `kenaz.rs:849-~985` |
+| `kenaz_specialist_dispatch` (same headless spawn) | `mcp.rs:745,(route)`; `definitions.rs:504`; `kenaz.rs:988-1160` |
+| Helpers only they use | `kenaz.rs` `load_bifrost_adapter:107`, `load_dispatch_routing:205`, `load_dispatch_model:185`, `write_preliminary_dispatch:551`, `dispatch_entry_liveness:581`, `set_dispatch_pid_if_unset:607` |
+| Dispatch-mode UI/setting | `ModelSelectionPanel.tsx:24-137,254-295` (Dispatch Routing selector, `DispatchMode` type `:41`); `use-cli-settings.ts` (dispatchModel only, **keep**: model choice feeds subagent); `lib/models.ts:27` (comment); `dashboard_settings.rs:31-38,76-78,137-142` (`dispatch_mode`, `VALID_DISPATCH_MODES`) |
+| Tests asserting formation default | `__tests__/subagent-bifrost-guard.test.js:87,128,137` |
+| Agent scheduler feature | `features/agent_scheduler/*.rs` (~820 LOC), `routes/agent_scheduler.rs` (377) |
+| Unattended triggers | `routes/heimdall.rs` (882), `routes/code_watch.rs` (373) |
+
+### 1.12 Hooks and other references
+
+| Item | Lines | Verdict |
+|---|---|---|
+| `.claude/hooks/post-dispatch-handoff-nudge.js` | whole file; fires on `kenaz_dispatch` PostToolUse (`:4`) | retire with the tool (Wave 2). Replacement for subagent path: handoff reminder already comes from `handoff-staleness.js` route 2 |
+| `.claude/hooks/handoff-staleness.js` | route 1 `:23,107` (reads `.active-dispatches.json`); route 2 (dispatch brief `.kenaz/specialist/dispatch_prompt_<task>`) | **KEEP**, delete route 1 only (Wave 2) |
+| `.claude/settings.json` / plugin hook wiring for the nudge | find with `git grep post-dispatch-handoff-nudge` (no settings hit in this checkout; user-level settings may carry it) | check user settings.json (31 machine-absolute paths per TASK_2358) |
+| `.specialist/Ansuz/elixir.yaml:3,61-63` | text: "formation: kenaz_dispatch / claude -p" path description, `how:` and `mandate:` evaluating both paths, `dispatchMode` override | edit text in Wave 5 (it is *prompt content*, not code; `bifrost/shared/ansuz-boot-policy.js` "elixir" is the unrelated boot *depth* name, keep) |
+| `.specialist/Ansuz/SYSTEM_DOC.md:149-150`, `RULES.md:52` | `headless.js --project-path` example | edit Wave 3/5 |
+| `k-cli/src/dispatch/run.ts` | prompt text + paths | rewrite or delete with k-cli dispatch command |
+| `.claude/commands/{lead,legacy_dev,multi-agent,dev}.md`, skill `formation_lead` | slash entry points for squad/legion | retire Wave 5 (confirm `/dev` and `/multi-agent` usage with user) |
+
+---
+
+## 2. Keep-list (with reasons)
+
+| Keep | Reason / evidence |
+|---|---|
+| `dispatch.js` subagent path (`getSubagentDispatchParams:1454`, scope gate, claim/lease, model resolution, worktree isolation) | It *is* the subagent payload builder (Ansuz RULES.md:52). Formation branch removed in Wave 4. |
+| `prompt.js`, `loader.js`, `utils.js`, `remote-conflict.js`, `memory-loader.js`, `alaya-gate.js` | required by `dispatch.js:18-31`, `prompt.js:17,39`. |
+| `.formation/unit/{do,plan,think,heimdall}.yaml`, `roles/_shared/modules/` | `loadSkill` and `prompt.js:103`. |
+| WorktreeCreate hook `.claude/hooks/worktree-create.js` | independent of Formation; exports are required by `post-complete/git-merge.js` (`worktree-create.js:1164`). Not touched. |
+| `worktree-reclaim.js` | `task-api.js:2781` (`worktrees --reclaim`) and `dispatch.js:1616` (`ensureWorktreeSpace`). |
+| `analytics.js` | **Not kept**: only writer is `dispatch-registry.js:71` (finding 0.6). If product wants dispatch telemetry for the subagent path, `dispatch-stats.js` already reads `dispatch_prompt_stats.jsonl` + phase9 outcomes. Retire in Wave 3. |
+| `post-complete.js` + `post-complete/{git-merge,health,outcome,cognitive,staging,testing,wish,integration-gaps,bounded-http,subagent-transcript-stats}.js` | `task-api.js complete` default path (`:2147`), `task-api.js:202` (health.js for snapshots). Subagent landing runs through it. |
+| Modules post-complete requires: `integration.js` (`post-complete.js:2329`), `forseti-verify.js` (`:2658`), `verify-acceptance.js` (`:301`, `git-merge.js:14`), `commit-sync.js` (`:2354`), `git-salvage.js` (`git-merge.js:19`), `transcript-recorder.js` (`outcome.js:12`), `supabase-client.js`, `task-sync.js`, `yggdrasil-local.js`, `pool-status-push.js` | all reached from `post-complete` or `task-api.js:306,324,1128` |
+| `.specialist/Ansuz/tools/verify-and-land.js` | requires only `utils.js` (`:77`); subagent landing pipeline. After Wave 4 its `utils.js` imports must still resolve (they do; `utils.js` stays). |
+| `dispatch-registry.js` read side (`readActiveDispatches`, `isProcessAlive`) | `session.js:1554` orphan detection, until rewritten (Wave 3). |
+| `.formation/bifrost/*` | see section 4; interactive Codex launch is independent of headless.js. |
+| Which part of post-complete does `task-api complete` need? | All of it by default: archive, git merge/landing, commit-sync, rune extraction, outcome log, inbox signal, health KEEP/REVERT, episode close (steps listed at `post-complete.js:2185-3451`). The only Formation-specific piece is the `--skip-post-complete` + `FORMATION_HEADLESS` handshake. |
+
+---
+
+## 3. Staged removal
+
+LOC estimates are raw `wc -l` of whole files unless marked (est). Tests listed move or die with their wave. Each wave is independently landable and leaves main green.
+
+### Wave 0: measure (this card + one small follow-up)
+- Run section 7 commands, store output in the follow-up card.
+- Record a 7-day count of `kenaz_dispatch` / `headless.js` invocations (from `.formation/logs/` and `.active-dispatches.json` history) to confirm nobody depends on them.
+- Resolve open questions Q1-Q3 (section 6).
+
+### Wave 1: flip defaults, remove the choice (no deletions of code paths)
+- `dispatch.js:1546` default `formation` -> `subagent`; invalid value warns then uses `subagent`.
+- Dashboard: remove the Dispatch Routing selector (`ModelSelectionPanel.tsx:254-295`, `:41-137`), keep `dispatchModel`. Rust: `dashboard_settings.rs` stop accepting/writing `dispatch_mode` (read tolerates legacy key).
+- Update `subagent-bifrost-guard.test.js:87,128,137` (assertions expect `formation`).
+- Verification: `node .formation/tools/__tests__/subagent-bifrost-guard.test.js`, `dispatch-model-policy.test.js`, `m1-claim-gate.test.js`; Dashboard `npm run test:rust -- dashboard_settings`; manual: Ansuz dispatch with no `dispatchMode` in `.kenaz/dashboard-models.json` yields `effectiveMode: subagent`.
+- LOC removed (est): ~150 (UI + Rust setting). Tests move: 3 assertions.
+- Blocker: none. Codex still reaches Formation because the `bifrost` refusal at `dispatch.js:1498-1505` tells callers to use `kenaz_dispatch`.
+
+### Wave 2: remove MCP entry points and unattended callers (gated on Q1 and TASK_2315)
+- Delete `tool_dispatch`, `tool_dispatch_status`, helpers (`kenaz.rs:107-640` subset, 638-985; est ~600 LOC), `definitions.rs:477-504` entries, `mcp.rs:745,818-819`.
+- `kenaz_specialist_dispatch` (`kenaz.rs:988-1160`, ~170): decide per Q1 (Amelia/Huginn need a runner).
+- Remove Heimdall/code_watch/agent_scheduler/script-manager spawn paths or re-point them (Q1): `heimdall.rs` 882, `code_watch.rs` 373, `agent_scheduler/*` ~820 + route 377, `script/manager.rs` formation entries (~60), Legacy Scheduler UI ~320.
+- Hooks: delete `post-dispatch-handoff-nudge.js` and its settings entry; remove route 1 from `handoff-staleness.js` (`:23,107`).
+- `lib.rs` Ansuz sleep/wake fallbacks (`:138-258,867-870`): remove the headless.js fallback branches; SDK-runner path (`:244,3266`) is already primary.
+- Verification: `npm run test:rust -- mcp` (and `dashboard_settings`, `script`), then a live smoke: Ansuz `kenaz_ping`, `dispatch.js --dispatch-mode=subagent` for a P3 doc task, `verify-and-land.js`. `node .claude/hooks/handoff-staleness.js` fixture test. Expect `kenaz_dispatch` to return "unknown tool".
+- LOC removed (est): 3000-3500 Rust/TS. Tests die: Rust tests inside `kenaz.rs`, `script/manager_tests.rs` formation cases (5 refs), `agent_scheduler` tests.
+- Hard dependency: **TASK_2315** must be landed (or Codex worker loss accepted by the user) before this wave.
+
+### Wave 3: delete Formation-only JS
+- Delete: `headless.js` (1071), `headless-v2.js` (659), `formations.js` (1203), `legacy-scheduler.js` (1994), `broadcast.js` (103), `process-state.js` (33), `task-utils.js` (344), `dispatch-notifier.js` (84), `analytics.js` (172), `dispatch-registry.js` (346; first move `readActiveDispatches`/`isProcessAlive` needs of `session.js:1554` into session.js or drop the orphan-detection input), `coordinator.js` (350, after re-grep), `log-reader.js` (232).
+- Edit: `prompt.js:895-905` (remove the "headless" hint), `task-api.js:2120,2143-2144` comments, `k-cli/src/dispatch/run.ts` (rewrite/delete), `SYSTEM_DOC.md:149`.
+- Verification: `git grep -n -E "headless(-v2)?\.js|formations\.js|legacy-scheduler|broadcast\.js|process-state|dispatch-registry|analytics\.js" -- ':!.kenaz' ':!dev/plans'` returns only history/comments; `node --test` for `.formation/tools/post-complete/*.test.js`, `post-complete.test.js`, `prompt.test.js`, `.collaboration/core/task-2264-*.test.js`, `task-2288-followups.test.js`; `node .collaboration/core/task-api.js complete <test task> --dry-run`.
+- LOC removed: about 6600 (sum above, incl. coordinator/log-reader). Tests die: `headless-dryrun.test.js`, `headless-branch-recovery.test.js`, `task2028-headless-worktree.test.js`, `tests/headless-mcp-args-plumbing.test.js`, `merge-lock-heartbeat.test.js` (or retarget if merge-lock survives), `pool-status-push` stays. Tests move: `dashboard-models-chain.test.js:56-57` (re-point at `dispatch.js`), `post-complete/task2345.test.js:35-36`, `spec/task_operations.parity.test.js:31` (drop `headless` entry), `task-2288-followups.test.js` env cases (`FORMATION_HEADLESS`/`SCHEDULER` rows).
+
+### Wave 4: trim dispatch.js, runner.js, logger.js
+- `dispatch.js`: remove the Formation CLI path (`--formation` branches `:1067,1075`, `runSingle/runParallel` `:1106,1166`, `:24` import) and keep `getSubagentDispatchParams`, scope gate, claim, lease, worktree prep. Estimated 800-1000 LOC removed from 1913 (est; measure on a branch).
+- Delete `runner.js` (1332), `logger.js` (273). Check `utils.js` for runner-only exports (`getClaudeEnv`, `detectClaudeCmd` are still used by `verify-acceptance.js:22`, keep).
+- Verification: `.formation/tools/__tests__/{subagent-bifrost-guard,m1-claim-gate,m1-hmap-convid,task-1863-claim-late-release,task-2265-singleton-identity}*.test.js`, `.formation/tools/{dispatch-dryrun,dispatch-model-policy,dispatch-cortex-context,route-audit}.test.js`, `.specialist/tools/__tests__/freya-cli-contract.test.js`, `.specialist/Ansuz/tools/verify-and-land.test.js`.
+- Tests die: `pre-dispatch-snapshot.test.js` and `worktree-leak.test.js` (both import `runner.detectWorktreeLeak`; if the leak check is still wanted for the subagent path, move `detectWorktreeLeak` to `utils.js` first).
+- LOC removed: ~2400.
+
+### Wave 5: data, skills, docs
+- Delete `.formation/solo`, `squad`, `legion`, `roles/<8 non-shared>`, `legacy.bak`, `lead.yaml`, `role-map.yaml`, `skills/coordinator.yaml`, `briefs/`, skill `formation_lead`, commands `lead`, `legacy_dev`, `multi-agent` (confirm `/dev`).
+- Rewrite `elixir.yaml:3,61-63` (single path), `SYSTEM_DOC.md`, `.formation/README.md`, CLAUDE.md Formation lines, `.rule` entries that cite Formation dispatch.
+- Update `dashboard/scripts/kenaz-core-staging.js:27,118-120,249,266-267` once `.formation` shrinks (it stages the whole dir; excludes for logs/worktrees can stay).
+- Verification: `git grep -n -E "formation=(solo|squad|legion|legacy)|\.formation/(solo|squad|legion|roles|legacy)"` empty outside history; `loadSkill('unit','do')` smoke; `node dev/scripts/check-file-size.js --staged`.
+- LOC/lines removed: ~3900 YAML + docs.
+
+### Wave 6: naming cleanup (optional)
+- Rename `.formation/tools` to something neutral only if desired; touching this path affects `task-api.js`, 40+ hooks/tests, Rust. Not recommended unless TASK_2358 plugin packaging forces new paths.
+
+Total estimate: ~16-17k LOC across JS/Rust/TS/YAML (est). JS tooling: `cat .formation/tools/*.js | wc -l` = 26,792 today; Formation-only share is ~11k of it.
+
+---
+
+## 4. Bifrost / Codex
+
+**Where the dependency is:**
+- Interactive Codex (`node .formation/bifrost/launch.js --specialist Ansuz`) does not call headless.js. Its only coupling is writing `.formation/.bifrost-active` (`launch.js:308-310`, cleared `:441`), whose single consumer is the dead `if (false && ...)` block at `headless.js:290-296` plus `resolveLaunchBifrostAdapter` (`headless.js:176-196`). Removing headless.js therefore does not break interactive launch; the signal write can be deleted in Wave 3.
+- Codex **workers** are the problem. A Codex Ansuz cannot use `dispatch.js --dispatch-mode=subagent`: it refuses on purpose when `dispatchFamily=bifrost` (`dispatch.js:1498-1505`, test `subagent-bifrost-guard.test.js:98-99,178-179`, the error text names `kenaz_dispatch`). The only remaining route is `kenaz_dispatch` -> `headless.js` -> `runner.js` -> Bifrost relay (`runner.js:706-770,1104`, `bifrost/openai/relay.js`, `bifrost/session.js`) -> `codex exec`. Rust also tracks these headless Codex threads (`codex_wake.rs`, `codex-session-registry.js`, `relay.js:35,236,523`).
+- `kenaz.rs:107-129,205` (`load_bifrost_adapter`, `load_dispatch_routing`) feed `--bifrost-adapter` into headless.
+
+**Dependency on TASK_2315** (backlog, P3): "`dispatch.js --dispatch-mode=subagent --harness=codex`: emit a Codex-native sub-agent payload (prompt + isolated cwd, model inherited from the session)". That card is the replacement for the Codex worker path. It is a Wave 2 prerequisite. Suggest raising it from P3 to P1 and treating "Codex worker parity" as the gate for Wave 2.
+
+**What Codex users lose if Formation is removed before TASK_2315:**
+1. All worker dispatch (no `kenaz_dispatch`, no subagent for the bifrost family). Ansuz-in-Codex would have to do every task inline in its own context.
+2. Scope-gate + claim + worktree isolation for workers (those happen inside `dispatch.js`, which they can no longer call for bifrost).
+3. Headless Codex peer threads (`relay.js` `registerCodexHeadless`) and the `codex_wake.rs` headless discovery become dead code that should be deleted with them in Wave 3.
+4. Unaffected: interactive Codex session, `bifrost/session.js` boot/capsule (used by Ansuz boot, not by dispatch), peer messaging.
+
+Interim option if Wave 2 must go first: keep `kenaz_dispatch` + `headless.js` + `runner.js` + `bifrost/*` as a "Codex-only legacy path" (about 4.5k LOC) and delete everything else (squad/legion/legacy/headless-v2/scheduler). This is the recommended fallback.
+
+---
+
+## 5. Launch from the target project
+
+Direction (2026-10-09): start agents inside the target project folder with native `claude` + the kenaz plugin (TASK_2358, in progress), instead of from the core repo with `/Ansuz [專案: X]`.
+
+### 5.1 What assumes cwd = core today
+
+| Assumption | Where | Effect |
+|---|---|---|
+| Session pin: prompt text `[專案: X]` / `--project-path X` binds a core-cwd session to a project | `.claude/commands/Ansuz.md:4-8,33,43`; `.claude/hooks/ansuz-session-pin.js:75-77` (parser), `_session-pin.js:23-26` (loads `project-resolver.js` from inside `projectDir` = core), consumers `lease-touch.js:86-94`, `turn-context.js:52-61`, `_peer-waiting-line.js:21` | Pin exists only because cwd = core. With cwd = project, the pin is redundant. |
+| `--project-path` threaded through every tool call | `task-api.js:2629-2682` (flag parse) and `:504-577` (cwd fallback + warnings that already assume cwd may be the wrong dir), `.specialist/tools/session.js:34-44,71` (BASE_DIR vs state root diverge), `ansuz-boot-fast.js`, `phase-gate.js`, `dispatch.js` (`--project-path`), `BOOT_FULL.md:19,108,140`, `RULES.md:52,69`, `SYSTEM_DOC.md:138-150` | With cwd = project these default correctly; the flag becomes override-only. |
+| `core_path` resolution to find tool scripts | `.kenaz/project.yaml` `core_path` written by `project/manager.rs:292-327,381-427` (sentinel `__kenaz_core__` at `:654`), read by `.claude/hooks/core-resolve.js:10-11,76-95,161-181`, `collaboration/hooks/install.js:81-96`, `worktree-create.js:75,127` (token resolver), Rust `resolve_project_for_write` -> `project.core_path` (`kenaz.rs:647,672,1030`), fallback `KENAZ_SOURCE_DIR` (set by `lib.rs` at startup; used by `lease-touch.js:26`, `lease-release.js:38`, `task-api.js:277-279`) | Project sessions run core scripts (`task-api.js`, `dispatch.js`, `verify-and-land.js`, hooks) from `core_path`. Native launch still needs a way to find them. |
+| Hooks resolve from the core repo | project hooks installed by `install.js` call `core-resolve`; user-level `settings.json` has 31 machine-absolute paths (TASK_2358 description) | Plugin hooks via `${CLAUDE_PLUGIN_ROOT}` replace these. |
+| Prompt tells project agents to call core `headless.js` | `prompt.js:895-905` | removed Wave 3. |
+| MCP is localhost dashboard | `http://127.0.0.1:18080`, project selected by Dashboard `kenaz_project_switch`, or by `projectPath` argument on every `synapse_*`/`kenaz_*` call | with a native session, MCP needs the plugin `.mcp.json`; project identity should come from `CLAUDE_PROJECT_DIR`. |
+
+### 5.2 Which waves remove or simplify it
+
+| Wave | Effect on cwd=core assumptions |
+|---|---|
+| 2 | Removes `kenaz.rs` use of `project.core_path` to locate `headless.js` and the `log_dir` split (`:663-670`). Removes `lib.rs` `KENAZ_SOURCE_DIR` headless fallbacks. |
+| 3 | Removes the `prompt.js` core-headless hint and `SYSTEM_DOC.md:149-150` `{CORE}/.formation/tools/headless.js --project-path` example. Leaves `task-api.js`/`dispatch.js` examples (they still need `{CORE}`). |
+| 4 | `dispatch.js` becomes cwd-relative by default (`projectPath = null` path at `:1454`); simplest place to make `--project-path` optional. |
+| 5 | Update Ansuz.md/BOOT_FULL/RULES wording; mark `[專案: X]` as a fallback. |
+| New Wave 7 (after TASK_2358 lands) | Retire `ansuz-session-pin.js`/`_session-pin.js` pin path for plugin sessions (keep for core-launched sessions during a deprecation window), reduce `core-resolve.js` to `${CLAUDE_PLUGIN_ROOT}`, drop `install.js` core_path hook bootstrap, make `core_path` optional in `project.yaml`. |
+
+### 5.3 Open items specific to this direction
+- Where do `task-api.js`, `dispatch.js`, `verify-and-land.js`, `phase-gate.js` live for a native session? Options: plugin ships them (largest change), or plugin calls them through `KENAZ_SOURCE_DIR`/Dashboard HTTP. Decide in TASK_2358.
+- `lease-*` hooks and `worktree-create.js` already resolve `KENAZ_SOURCE_DIR` or walk up; verify they work with `CLAUDE_PROJECT_DIR` = target project and no core on disk (installed users).
+- The Dashboard "selected project" (`kenaz_project_current`) is global state; native sessions in several folders need per-call `projectPath` (already mandatory in CLAUDE.md) or derivation from `CLAUDE_PROJECT_DIR` server-side.
+- Wave 2 should land before the plugin ships hooks, otherwise the plugin would carry the `post-dispatch-handoff-nudge` hook for a tool that is going away.
+
+---
+
+## 6. Open questions for the user
+
+- **Q1 (blocks Wave 2):** unattended jobs (Heimdall trigger, code_watch, scheduled agents, Amelia/Huginn `kenaz_specialist_dispatch`, Ansuz exit-sleep). Options: (a) keep a minimal headless runner (`claude -p` one-shot, no formations, ~600 LOC) for these only; (b) drop the features; (c) re-implement them as Ansuz-session-triggered subagents. Recommendation: (a) for Heimdall + sleep/wake, (b) for agent_scheduler / Legacy Scheduler.
+- **Q2:** accept Codex worker loss during the gap, or hold Wave 2 for TASK_2315 (recommended)?
+- **Q3:** are `/dev`, `/multi-agent`, `/lead` still used? They route to Formation squads.
+
+---
+
+### Resolved 2026-10-09
+- **Q1 -> drop every unattended runner (option b, Heimdall re-homed).** Usage evidence (30 days to 2026-10-09): 96 of 98 headless dispatches were Heimdall; 64 Heimdall proposals June-10-04 with 0 accepted, while the 30 cards that did land came from one in-session triage (30/30 done); agent_scheduler never ran (enabled:false, lastRunAt:null); Legacy Scheduler and Amelia 0 runs; no evidence any sleep/wake output was read; TASK_2242 shows the unattended Heimdall path checking out main in a user's repo. Heimdall becomes a record-only post-commit hook plus an in-session scan offered at /Ansuz boot. The in-process Rust synapse_sleep_cycle stays. No ~600 LOC headless runner.
+- **Q2 -> hold the kenaz_dispatch removal for TASK_2315** (raised to P1). Unattended-runner removal does not depend on Codex and goes first as Wave 2a.
+- **Q3 -> /dev, /multi-agent, /lead are unused; retire them in Wave 1.**
+
+## 7. Verification commands
+
+Run from repo root. Each should list every file named in section 1; blank for a row means the row is stale.
+
+```bash
+# 7.1 headless / headless-v2 / formations / legacy-scheduler / broadcast / process-state / dispatch-registry / analytics
+git grep -n -E "headless(-v2)?\.js|headless-v2" -- '*.js' '*.ts' '*.tsx' '*.rs' '*.sh' '*.mjs' ':!dev/research'
+git grep -n -E "require\(.*(formations|legacy-scheduler|broadcast|process-state|dispatch-registry|analytics|task-utils|dispatch-notifier|runner|logger)(\.js)?['\"]\)" -- '*.js' '*.ts' ':!dev/research'
+# 7.2 callers outside .formation of post-complete / worktree-reclaim / verify-and-land / dispatch.js (keep-list)
+git grep -n -E "post-complete|worktree-reclaim|verify-and-land|dispatch\.js" -- '*.js' '*.ts' '*.tsx' '*.rs' ':!.formation' ':!dev/research' ':!.kenaz'
+# 7.3 directories and data files
+git ls-files .formation/unit .formation/solo .formation/squad .formation/legion .formation/roles .formation/legacy.bak .formation/lead.yaml .formation/role-map.yaml
+git grep -n -E "lead\.yaml|role-map\.yaml|legacy\.bak|roles/_shared|loadSkill\(" -- '*.js' '*.ts' '*.rs' '*.yaml' ':!dev/research' ':!.kenaz'
+# 7.4 Rust MCP tools and Dashboard
+git grep -n -E "kenaz_dispatch|kenaz_dispatch_status|kenaz_specialist_dispatch" -- '*.rs' '*.ts' '*.tsx' '*.js' ':!dev/research' ':!.kenaz'
+git grep -n -E "dispatchMode|dispatch_mode|dispatch-mode" -- '*.rs' '*.ts' '*.tsx' '*.js' ':!dev/research' ':!.kenaz'
+# 7.5 hooks and elixir
+git grep -n -E "handoff-staleness|post-dispatch-handoff-nudge|elixir\.yaml" -- '.claude' '.specialist' '.formation' ':!*.json'
+# 7.6 Launch-from-target-project assumptions
+git grep -n -E "project-path|core_path|__kenaz_core__|KENAZ_SOURCE_DIR|\[專案" -- '.claude' '.specialist' '.collaboration' 'dashboard/src-tauri/src' ':!*.test.js'
+# 7.7 LOC and file counts
+wc -l .formation/tools/*.js | sort -rn | head -40
+git ls-files .formation/unit .formation/solo .formation/squad .formation/legion .formation/roles .formation/legacy.bak | wc -l
+```
+
+After each wave, the same commands are the regression check: counts must drop to the "keep" rows listed above and nothing else.

package/core/dev/plans/KUZU_REPLACEMENT_PLAN.md

@@ -0,0 +1,126 @@
+# Kuzu replacement plan (draft for user review)
+
+Date: 2026-10-07. Owner: Ansuz. Status: EXECUTED 2026-10-07 - see Outcome at the end.
+
+## Why
+
+Pre-registered experiment on this repo (dev/research/code-graph-eval/RESULTS.md): for
+"who calls X", Synapse code graph recall 0.56 vs LSP 0.97 (precision 1.00 vs 0.94);
+cross-language 0.33 vs grep-on-entry-string 1.00; impact failed on 25% of symbols.
+Kuzu also carries most of our maintenance load (graph bloat TASK_2294/2316, CHECKPOINT
+poisoning TASK_2293/2317, SEH crashes, index lock "unavailable while indexing", 16-min
+release builds, 33 MB vendored fork whose upstream is archived).
+
+## Decisions taken (user, 2026-10-07)
+
+| Topic | Decision |
+|---|---|
+| Kuzu | Remove completely in ONE change. No legacy switch; rollback = git revert / previous release. |
+| Caller / impact questions | LSP, exposed as Kenaz MCP tools so Claude Code and Bifrost Codex share one implementation; installer provisions the language servers. |
+| Norn (heat, co-change, ΔGraph, curiosity, preamble, EFE, attention, thalamus, pulse) | Remove. |
+| Health score / Heimdall | Drop graph metrics, keep the non-graph ones. |
+| Graph-based hooks and prompts (pulse-before-*, Active Signals, thalamus, synapse-first) | Remove; synapse-first nudge becomes an LSP nudge. |
+| Episodes + transcripts (stored in Kuzu today) | Move to SQLite and migrate existing data on every machine via a one-time export helper shipped with the release (removed again in the following release). |
+| LSP languages | Rust (rust-analyzer), TypeScript/JavaScript (typescript-language-server), C# (csharp-ls, Unity projects such as Ashfall), Python (pyright). |
+| Old graph files | After a verified migration, the new version deletes .synapse/db/graph* and graph backups. |
+| Symbol search (synapse_search) + symbol index | Remove. Pre-registered experiment: grep 20/20 in 32 calls vs synapse_search 12/20 in 69 calls. |
+
+## Target architecture
+
+```
+Agents (Claude Code, Bifrost Codex)
+   |  MCP (existing kenaz-dashboard endpoint)
+   v
+Kenaz backend
+   |- LSP service (NEW): spawns rust-analyzer / typescript-language-server per project,
+   |    lazy start, kept warm; tools: kenaz_lsp_callers (call hierarchy, depth N),
+   |    kenaz_lsp_references, kenaz_lsp_definition, kenaz_lsp_symbols
+   |- Memory (SQLite, unchanged): runes, sigils, cortex, alaya, bija
+   |- Episodes + transcripts (MOVED to SQLite)
+   `- Health (non-graph metrics), field reports, peer, Yggdrasil ... (unchanged)
+```
+
+## Workstreams (one integration branch, parallel worktrees, single merge + release)
+
+| WS | Content | Notes |
+|---|---|---|
+| W1 LSP service | Rust module managing one language server per (project, language): rust-analyzer (buildScripts off, separate targetDir), typescript-language-server, csharp-ls, pyright; lazy start on first query for that language, kept warm, idle shutdown; MCP tools kenaz_lsp_callers (call hierarchy, depth N), kenaz_lsp_references, kenaz_lsp_definition, kenaz_lsp_symbols; returns a clear warming-up status (rust-analyzer measured 188 s cold on this repo). Same tools reach Bifrost Codex through the existing MCP endpoint. | Reuse the JSON-RPC client from dev/research/code-graph-eval/harness. |
+| W2 Episodes to SQLite | SQLite tables for Episode, EpisodeEntry, links (LED_TO, CONTINUES, REFERENCES, IN_SCOPE), touched symbols as stable-id strings, TranscriptSession/Chunk; port hippocampus episode.rs + transcript.rs. Migration: a separate small crate `tools/kuzu-export` (outside the main workspace, the only thing that still links kuzu) builds `kenaz-kuzu-export.exe`; the app runs it once at startup when an old graph exists, imports its JSON into SQLite, verifies counts, records success, then deletes the graph files. | Main app stays kuzu-free; the helper is dropped in the next release. |
+| W3 Indexer | Delete the whole indexer (scanner, index_*, calls/imports/exports/implements/dataflows/varflows, community/process detection, stable_id_migration, reconcile, symbol FTS/embeddings, file watcher auto-index). Rune inscribe validates that the referenced FILE exists instead of a graph symbol. | Largest diff; pure deletion. |
+| W4 Remove graph features | Delete Kuzu plumbing (connection pool, writer gate, worker processes, db_pool, quarantine, crash/SEH guards specific to kuzu, IS_INDEXING), graph MCP tools (context, impact, pulse, map, cypher, trace_route, pain_paths, orphans, import_cycles, detect_changes, link_cognitive, ...), Norn, thalamus, attention, pulse, EFE; strip graph_context from recall; drop "symbol exists in graph" gates on inscribe/declare; synapse_status reports SQLite stores only. | ~56k LOC production + ~13k tests. |
+| W5 Hooks, rules, prompts | Remove pulse-before-read/edit, jev-thalamus-context, synapse-first-*, Active Signals in turn-context; rewrite CLAUDE.md (SYN, Norn sections), .rule (synapse-code-intelligence, cognitive-fusion, ddx-synapse-stack), Ansuz elixir/exo_cortex/core, Heimdall/Huginn skills, Formation dispatch/post-complete callers of impact/pulse/context. Post-commit hook (HOOK_VERSION 4): keep Heimdall trigger, drop Norn on-commit. | Agents must never be told to call a removed tool. |
+| W6 Frontend | Remove Synapse graph viewer, thalamus/pulse views, EFE panel; Synapse page becomes memory + search (+ LSP status). | |
+| W7 Build + provisioning | Remove kuzu crate, vendor/kuzu (33 MB, 2,857 files), build.rs kuzu guard, c_shim, cxx pin, CI/sccache/verify-script kuzu handling. Installer/startup provisioning (pattern of TASK_2319) installs language servers on demand: rust-analyzer via rustup component, typescript-language-server and pyright via npm, csharp-ls via dotnet tool (report clearly if the .NET SDK is missing). | Last; proves the app builds with no kuzu in cargo tree (helper crate excluded). |
+
+## Verification (gate for the single merge)
+
+1. `cargo tree | grep -i kuzu` empty; release build succeeds; build time recorded (was ~10 min, kuzu C++ ~16 min cold).
+2. Full Rust tests, dashboard tsc + jest, node tests for hooks/specialist/formation touched.
+3. Rerun the code-graph experiment harness against the new kenaz_lsp_callers tool: recall >= 0.95 on the same 27 symbols.
+4. Episodes: count and spot-check content after migration equals pre-migration; hippocampus recall works.
+5. Memory: synapse_recall, inscribe, sigils, cortex/alaya unchanged (existing tests + live check).
+6. Live: Claude Code session and a Bifrost Codex session each call kenaz_lsp_callers successfully.
+7. Prompt audit: grep all live prompt/rule/hook files for removed tool names = 0.
+8. Clean-machine install: language servers provisioned, no Kuzu files created.
+
+## Risks
+
+- Data loss if episode migration runs after Kuzu is gone (see question 1).
+- Agents calling removed tools from docs we missed (mitigated by verification 7).
+- rust-analyzer resource use (RAM, first warm-up ~3 min) on team machines.
+- Team projects in other languages lose code navigation unless their language server is provisioned (see question 2).
+- Large single diff: conflicts with other work on main during the change window.
+
+## Execution order (all on one integration branch `kuzu-removal`, merged to main once)
+
+1. W1 LSP service and W2 episode storage + export helper, in parallel. Both are additive
+   and are tested while Kuzu still exists (migration tested against this machine's real
+   graph copy).
+2. W5 hooks/rules/prompts and W6 frontend, in parallel, pointing everything at the new
+   LSP tools and memory-only Synapse.
+3. W3 + W4 deletion (indexer, graph features, Norn, plumbing).
+4. W7 build removal + language-server provisioning.
+5. Verification gate (section above) on the integration branch, then ONE merge to main,
+   release, and the migration runs on each machine at first start.
+
+Main keeps moving meanwhile: the integration branch merges main in at each step; other
+work should avoid src-tauri/src/features/synapse during the window.
+
+## Open questions
+
+None left from planning.
+
+## Outcome (2026-10-07)
+
+Executed in one change (merge d90658b64). Cards: TASK_2333 (W1 LSP), 2334 (W2 episodes),
+2335/2336/2340/2341 (W5 prompts, hooks, specialist, health gate), 2337 (W6 frontend),
+2338 (W3+W4 deletion), 2339 (W7 provisioning + helper bundling), 2342 (CommonJS callers).
+
+Verification:
+1. Cargo.lock has no kuzu; dev rebuild 50 s (was ~10 min with the kuzu C++ build).
+2. Rust lib tests 1930 passed / 0 failed; dashboard tsc clean; jest 444/444; node suites
+   touched by each card green.
+3. kenaz_lsp_callers on a checkout of afec99026 (the experiment commit): callers recall
+   0.974 at first (TS 0.925: tsserver find-references does not follow CommonJS
+   `module.exports = { f }`); after TASK_2342 (definition-verified text pass) 0.981 overall,
+   R 1.00, TS 0.97, X-lang 0.667, 0.995 excluding X-lang. Synapse was 0.56. Gate 0.95 PASS.
+4. Migration on this machine: 14 projects; every marker has expected == stored (one project
+   skipped 6 orphan entries no episode owned, by design). KenazAI's live graph already had 0
+   episodes (all 2,120 were in memory.db). Legacy graph + backups deleted (3.4 GB here).
+5. synapse_status / recall / health and hippocampus episode + transcript recall answer live.
+6. Claude Code (`claude -p`) and Codex (`codex exec` with Bifrost's `-s danger-full-access`)
+   both got the same 11 call sites from kenaz_lsp_callers. Codex in a read-only sandbox with
+   approval=never refuses MCP calls unless the tool is approved in config.toml.
+7. Prompt audit: removed tool names remain only in dated design/investigation docs and in
+   tests that assert their absence.
+8. Clean-machine install: pending the release.
+
+Deviations:
+- vendor/kuzu stays for this release: tools/kuzu-export builds from the same fork that wrote
+  the old graphs. Drop vendor/kuzu, tools/kuzu-export and tauri.kuzu-migration.conf.json
+  together in the next release.
+- Health is record-only (score_version memory-v1): a memory score cannot judge a code change,
+  so it no longer reverts or gates merges.
+- synapse_declare stays (writes a decision rune); POST /api/synapse/verify stays; spike-bus
+  routes stay on an in-memory buffer.
+- Provisioned TypeScript is pinned to typescript@5: TypeScript 7 (native) has no tsserver.js.