throughline 0.3.25 → 0.4.1

package/docs/INHERITANCE_ON_CLEAR_ONLY.md

@@ -1,5 +1,27 @@
 # 引き継ぎ発火条件の絞り込み調査 & 実装計画
 
+> **Status (2026-05-09 update): 本書は履歴扱い**
+>
+> 当時 (2026-04-18) は VSCode 拡張 2.1.112 で `/clear` 後も `source='startup'` に
+> 潰される問題があり、バトン方式 (案 E) を採用した。その後 Claude Code 2.1.105
+> (VSCode `/clear` not clearing context fix) と 2.1.126 (Windows env fix) で
+> 段階的に修正され、**2.1.128 で `source='clear'` が reliable**になった。
+>
+> 現行仕様 (v0.4.1): **baton path (primary)** + auto path (fallback) の 2 経路。
+> typed `/clear` / `/tl` はどちらも UserPromptSubmit hook で baton を書き、次
+> SessionStart が確定的にそのセッションを引き継ぐ。auto path は VSCode 拡張
+> メニュー由来 `/clear` のように UserPromptSubmit に届かない経路のための
+> fallback で、`THROUGHLINE_DISABLE_AUTO_HANDOFF=1` で OFF にできる (typed
+> `/clear` / `/tl` は env と無関係に引き続き発火する)。詳細は
+> [THROUGHLINE_CLEAR_AUTO_HANDOFF_PLAN.md](THROUGHLINE_CLEAR_AUTO_HANDOFF_PLAN.md)。
+>
+> 本書は当時のバトン採用判断を残す履歴ドキュメント。「結局 baton primary に
+> 戻った」という結末は皮肉だが、当時の判断は VSCode 拡張側 source バグへの
+> 適切な対応だった。今回 baton primary を再採択した理由は (a) typed `/clear`
+> が UserPromptSubmit に確実に届く、(b) multi-window で「最新更新セッション
+> ≠ /clear したセッション」になる場合に heuristic が誤った前任を選ばない、
+> の 2 点。
+
 ## Status (2026-04-18 更新)
 
 - **Phase 0 実機検証: 完了**

package/docs/PUBLIC_RELEASE_PLAN.md

@@ -78,7 +78,8 @@ schema v4 で PostToolUse (`capture-tool`) は廃止、L2/L3 は Stop 内で一
 | schema v4 migration（bodies 追加、judgments DROP） | [src/db.mjs](../src/db.mjs) |
 | schema v5 migration（details に kind / source_id 追加、L3 分離書き込み対応） | [src/db.mjs](../src/db.mjs) |
 | schema v6 migration（handoff_batons テーブル追加、`/tl` バトン引き継ぎ方式） | [src/db.mjs](../src/db.mjs), [src/baton.mjs](../src/baton.mjs) |
-| schema v7 migration（`handoff_batons.memo_text` カラム追加、in-flight メモ保存） | [src/db.mjs](../src/db.mjs), [src/baton.mjs](../src/baton.mjs), [src/cli/save-inflight.mjs](../src/cli/save-inflight.mjs) |
+| schema v7 migration（`handoff_batons.memo_text` カラム追加、in-flight メモ保存） | (v8 で memo_text drop、save-inflight 削除済み) |
+| schema v8 migration（`handoff_batons.memo_text` drop、`/clear` auto path 化、`save-inflight` / `/tl-trim` / `updateBatonMemo` 削除、注入を L1+L2+L3 refs のみに簡素化） | [src/db.mjs](../src/db.mjs), [src/session-start.mjs](../src/session-start.mjs), [src/resume-context.mjs](../src/resume-context.mjs), [docs/THROUGHLINE_CLEAR_AUTO_HANDOFF_PLAN.md](THROUGHLINE_CLEAR_AUTO_HANDOFF_PLAN.md) |
 | VSCode `.vscode/tasks.json` の自動プロビジョニング（token-monitor の folderOpen 自動起動） | [src/vscode-task.mjs](../src/vscode-task.mjs) |
 | Stop フック時の state.usage スナップショット（monitor の「止まって見える」問題の切り分け用） | [src/state-file.mjs](../src/state-file.mjs), [src/turn-processor.mjs](../src/turn-processor.mjs) |
 | `throughline doctor --session <id-prefix>` セッション診断（state/transcript ズレ検出） | [src/cli/doctor.mjs](../src/cli/doctor.mjs) |
@@ -133,6 +134,8 @@ schema v4 で PostToolUse (`capture-tool`) は廃止、L2/L3 は Stop 内で一
 | **npm 公開 (v0.3.25): Codex global Stop hook / skill install** | `throughline install` が Claude hooks / slash commands に加えて `~/.codex/hooks.json` に絶対 node + installed `bin/throughline.mjs codex-hook stop` を `async: false` で登録し、`~/.codex/config.toml` の `[features].codex_hooks = true` を有効化し、`~/.codex/skills/throughline` に `$throughline` skill を配置する。Codex App Server / VSCode host の PATH 差分で bare `throughline` が見えない可能性があるため、hook は Caveat と同じ絶対パス型に寄せる。既存 Caveat / Spotter などの Codex hooks は保持し、`throughline uninstall` は Throughline 管理の Codex hook / skill だけを削除する。既に bare command または `async: true` で登録済みの Throughline Codex Stop hook は次回 install で更新する。実環境では `codex exec --json` child thread `019dfd4f-93ff-7522-8f89-bd1e1996c8d7` が Stop hook で自然 capture され、`doctor --codex` の latest DB session が `codex:019dfd4f-93ff-7522-8f89-bd1e1996c8d7` に進むことを確認した。さらに絶対パス型へ更新後、child thread `019dfd5e-1248-7c11-8ddc-97e1b0701e10` でも latest DB session が `codex:019dfd5e-1248-7c11-8ddc-97e1b0701e10` に進むことを確認した。hook shape 変更後に新規開始した VSCode-origin thread `019dfd62-9a9d-7211-bf91-89d8e3fc908e` でも `doctor --codex` の current thread と latest DB session が一致し、自然 Stop hook capture を確認済み。hook shape 変更前から開いていた VSCode-origin parent thread は、変更後の自然 Stop smoke としては扱わない。Caveat 側にも `async: false` Stop hook が動く実測があるため、Codex 側は Caveat と同じ同期 hook 方針に寄せる。`codex-capture` / `codex-summarize` / `codex-resume --memo-stdin` は診断・明示操作 surface として維持し、model-visible smoke は明示 opt-in。2026-05-08 以降、Stop hook auto-refresh は verified usage 90% 以上で guarded rollback / inject を試行し、estimate usage では mutation しない |
 | **npm 公開 (v0.3.25): Codex-first roadmap** | [THROUGHLINE_CODEX_FIRST_ROADMAP.md](THROUGHLINE_CODEX_FIRST_ROADMAP.md) を追加。次フェーズは Codex primary 実用化、Codex Rewind 互換、Claude 側 finalization の順で進める。Codex primary の L2→L1 backend は Codex CLI を本線とし、`codex-sidecar` は Claude primary からの review / risk-check / second opinion / 互換 L2→L1 経路として整理する |
 | **npm 公開 (v0.3.25): npm docs packaging** | README から参照する `docs/` と `CHANGELOG.md` を npm `files` に追加。`docs/throughline-handoff-context.example.json` を含め、README の sidecar dry-run 例が tarball 内でも成立するようにする |
+| **npm 公開 (v0.4.0): /clear auto-handoff + memo / save-inflight / /tl-trim retire** | 2026-05-08 Claude Code 2.1.128 で `source='clear'` が reliable になったため、`/clear` で自動引継ぎがデフォルト ON になる auto path を追加。`THROUGHLINE_DISABLE_AUTO_HANDOFF=1` で OFF にできる。`/tl` slash command は明示意思マーカーへ簡素化 (memo 4 項目入力廃止、`save-inflight` CLI 削除、`/tl-trim` slash command 廃止、`updateBatonMemo` 関数削除、`handoff_batons.memo_text` を schema v8 で drop)。注入は L1 + L2 + L3 references のみに簡素化し、memo / 中断直前 thinking セクションを削除。Codex 側 trim path は維持。詳細は [CHANGELOG.md](../CHANGELOG.md) と [THROUGHLINE_CLEAR_AUTO_HANDOFF_PLAN.md](THROUGHLINE_CLEAR_AUTO_HANDOFF_PLAN.md) |
+| **npm 公開 (v0.4.1): typed `/clear` も baton を書く + 2 経路の優先順位入れ替え** | 2026-05-09 `/clear` を UserPromptSubmit hook で検出した時点で当該セッションの `session_id` を `handoff_batons` に書き込み、次 SessionStart が確定的にそのセッションを引き継ぐ。これで multi-window で「最新更新セッション ≠ /clear したセッション」になるシナリオで `findLatestClaudePredecessor` heuristic が誤った前任を選ぶ問題を解消。2 経路の優先順位を **baton path = primary、auto path = fallback** に変更 (auto path は VSCode 拡張メニュー由来など UserPromptSubmit に届かない経路のフォールバック)。`THROUGHLINE_DISABLE_AUTO_HANDOFF=1` は fallback path のみに作用するようになった (typed `/clear` / `/tl` は env と無関係に発火する)。あわせて `.vscode/tasks.json` を git 追跡から外し (gitignore)、`ensureMonitorTaskFile` が hook 発火ごとに絶対パスを書き換える挙動による別環境での dirty diff を解消。`src/prompt-submit.test.mjs` を新設し、`isClearCommand` / `isBatonCommand` 判定 14 件と subprocess+DB 実体テスト 3 件を追加。詳細は [CHANGELOG.md](../CHANGELOG.md) |
 | **グローバル E2E 検証** | 2026-04-17 別ディレクトリから `throughline doctor` 全緑を確認 |
 
 ### ❌ 未完タスク

package/docs/THROUGHLINE_CLEAR_AUTO_HANDOFF_PLAN.md

@@ -0,0 +1,304 @@
+# Throughline `/clear` 自動引継ぎ計画 (TODO 兼)
+
+`/clear` をトリガーにした **自動かつ軽量な引継ぎ** を実現する計画。
+2026-05-08 セッションの議論と実機検証、外部仕様調査に基づく。
+A 案 (= /clear で自動引継ぎ + /tl は逃げ道として残す + /tl-trim 廃止) **採択確定**。
+
+> 過去の経緯 (なぜ `/tl` バトンを採用したか) は [INHERITANCE_ON_CLEAR_ONLY.md](INHERITANCE_ON_CLEAR_ONLY.md) を参照。
+> 本書は **2026-05-08 時点の現状検証 + 新理想設計** を扱う。
+
+> **2026-05-09 (v0.4.1) update**: 2 経路の優先順位を **入れ替えた**。
+> baton path が **primary**、auto path は **fallback**。理由: typed `/clear`
+> は UserPromptSubmit に届くので baton 書き込みで確定的に当該セッションを
+> 指名できる。一方 VSCode 拡張のメニュー由来 `/clear` は UserPromptSubmit
+> に届かない (= `findLatestClaudePredecessor` heuristic が誤った前任を選ぶ
+> リスクあり) ため、auto path を残してフォールバック化した。typed `/clear`
+> も UserPromptSubmit hook で baton を書く ([src/prompt-submit.mjs](../src/prompt-submit.mjs))。
+> `THROUGHLINE_DISABLE_AUTO_HANDOFF=1` は **fallback path のみに作用** する
+> ようになった (typed `/clear` / `/tl` には効かない)。
+
+---
+
+## 1. 確定した事実 (実機検証済み)
+
+### 1.1 `/clear` 後の SessionStart `source` は 2.1.128 で reliable
+
+```
+inheritance-decision.log (2026-05-08 12:26 検証)
+  12:26:08.481Z  source="startup"   session=05735717  ← 新 chat 開始
+  12:26:52.257Z  source="clear"     session=b2addc4a  ← /clear 後
+```
+
+- Claude Code `2.1.128` (VSCode native extension, Linux/WSL2) で `/clear` 後の SessionStart は **確実に `source='clear'`** を payload に乗せる
+- 過去の [GitHub issue #49937](https://github.com/anthropics/claude-code/issues/49937) (= VSCode 拡張で /clear 後も `source='startup'` になっていたバグ) は **解決済み**
+- v2.1.105 (VSCode `/clear` not clearing conversation context fix) と v2.1.126 (Windows SessionStart hook env files apply) のリリースで段階的に修正された
+
+### 1.2 SessionStart `source` の 4 値 (公式 docs)
+
+| 値 | 意味 |
+|---|---|
+| `startup` | 新 chat / VSCode 再起動 / 別 project / cold start |
+| `resume` | `--resume` / `--continue` / `/resume` |
+| `clear` | `/clear` 直後 |
+| `compact` | 自動 / 手動 compaction 直後 |
+
+source: [code.claude.com/docs/en/hooks](https://code.claude.com/docs/en/hooks)
+
+### 1.3 `/clear` 等価の user-defined slash command は **作れない**
+
+調査結果 (claude-code-guide Agent + bundled `claude-code` 検査):
+
+- `.claude/commands/*.md` (skill markdown) は **prompt 拡張**であり、built-in `/clear` を programmatic に invoke できない
+- "subcommand" や "exec built-in" 構文は無い
+- `/clear` には built-in alias が存在しない
+- CLI flag `claude clear` も無い
+- cross-platform で「新ウィンドウ起動」する built-in も無い (`/branch` は full history copy で軽量化と矛盾、VSCode URL scheme は VSCode 専用)
+
+→ **「引継ぎたい /clear」と「reset したい /clear」を `source` 値で区別する手段は無い**
+
+### 1.4 `/rewind` は fork 動作 (caveat 記録済み)
+
+- `/rewind` Continue 確認画面に "A new forked conversation will be created after rewinding" と明示
+- 同 thread 内 rollback ではなく、新 fork session id を生成
+- 詳細は caveat `claude-code/claude-code-rewind-fork-conversation-rollback-primitive` を参照
+- 本計画では `/rewind` は **対象外**
+
+---
+
+## 2. 採用する理想設計
+
+### 2.1 引継ぎ発火条件 (2 経路、v0.4.1 で baton primary に変更)
+
+| 経路 | 条件 | 起動 |
+|---|---|---|
+| **baton path (primary)** | `handoff_batons` テーブルに TTL (1 時間) 内 baton あり (= ユーザーが `/tl` または `/clear` を打った) | `source` 値関係なく確定的に引継ぎ |
+| **auto path (fallback)** | baton 不在 + `source='clear'` + env `THROUGHLINE_DISABLE_AUTO_HANDOFF` が `'1'` でない | `findLatestClaudePredecessor` heuristic で引継ぎ |
+
+判定ロジック (擬似コード):
+
+```
+on UserPromptSubmit(prompt, session_id, project_path):
+  if isBatonCommand(prompt) or isClearCommand(prompt):
+    writeBaton(project_path, session_id, now)  // typed /clear / /tl が確定的に baton を書く
+
+on SessionStart(source, session_id, project_path):
+  baton = consumeBaton(project_path)  // atomic SELECT + DELETE, TTL 超過は sessionId=null で返る
+  if baton.sessionId:
+    inject(curated_memory_from(baton.sessionId))  // baton path (primary, env 関係なく発火)
+    return
+  if source == 'clear' and env.THROUGHLINE_DISABLE_AUTO_HANDOFF != '1':
+    predecessor = findLatestClaudePredecessor(project_path, session_id)
+    inject(curated_memory_from(predecessor))  // auto path (fallback)
+    return
+  // 何もしない
+```
+
+`consumeBaton` が先発なので「両方同時成立」は構造上発生しない (= baton ありなら baton 経路、無ければ source 判定)。typed `/clear` も UserPromptSubmit hook で baton を書くため、通常はほぼ常に baton path が走る。auto path は VSCode 拡張のメニュー由来 `/clear` のように UserPromptSubmit に届かない経路のためのフォールバック。
+
+### 2.2 注入内容: L1 + L2 + L3 refs のみ (baton/auto どちらの経路でも同一)
+
+含める:
+- ヘッダ + Reading Contract framing (= Codex 側 `renderCodexRolloutMemoryPreview` の写像)
+- **L1 summaries** (古い turn の一行要約)
+- **L2 bodies** (直近 20 turn の verbatim)
+- **L3 references** (= `throughline detail <時刻>` の取り出しコマンド一覧、Codex 風の `- ${kind}: ${detailCommand}` フォーマット)
+- Continuation Instruction (= 「これは過去ログではなく現在進行中の作業」と明示)
+
+含めない (= 削除):
+- 中断直前の in-flight memo (memo セクション)
+- 中断直前の thinking (extended thinking セクション)
+- 既存の Claude 向け footer の冗長な使い方説明
+
+理由: L2 全文があれば最後の assistant turn 自体に「次に何をしようとしていたか」が含まれている。memo / thinking は redundant。
+
+### 2.3 `/tl` の役割: **残すが簡素化**
+
+- `/tl` slash command 自体は **維持** (= 明示意思マーカー = baton path のトリガー)
+- 簡素化:
+  - memo 4 項目入力要求を **削除** ([.claude/commands/tl.md](../.claude/commands/tl.md) を「baton 立てるだけ」の最小実装に)
+  - `save-inflight` CLI を **削除** (memo を baton.memo_text に保存する役目だった)
+  - `handoff_batons.memo_text` 列を **drop** (schema v8 migration)
+  - `src/baton.mjs` の `updateBatonMemo` 関数を **削除** (memo_text 列が drop されるため)
+- `prompt-submit.mjs` の baton 書き込み path は **維持** (`UserPromptSubmit` hook で `/tl` 検出 + writeBaton)
+- v0.4.1 で `/clear` も同じ hook で baton を書くように拡張 ([src/prompt-submit.mjs](../src/prompt-submit.mjs) `isClearCommand`)
+
+ユーザーから見た `/tl` の使い方:
+- typed `/clear` (デフォルト): `/clear` を打った時点で baton が書かれ、次セッションが確定的に引継ぐ。`/tl` を打つ必要なし
+- VSCode メニュー `/clear` 経由: UserPromptSubmit に届かないので baton は書かれず、auto path (fallback) が `findLatestClaudePredecessor` で前任を選ぶ
+- 非 `/clear` 境界 (新規 chat / VSCode 再起動): `/tl` で baton を立ててから新セッションを開く
+- env で auto OFF: typed `/clear` / `/tl` は引き続き動く (env は fallback 専用)
+
+### 2.4 `/tl-trim` 廃止 (Codex 側を壊さない)
+
+- 元機能: memo 入力 + dry-run preview 表示
+- 新仕様で memo 廃止 + 軽量化方針 → 役割なし
+- 削除対象:
+  - [.claude/commands/tl-trim.md](../.claude/commands/tl-trim.md) (slash command)
+  - [src/cli/trim.mjs](../src/cli/trim.mjs) の **Claude path 部分のみ** 削除 (`describeTrimHost('claude')` ブランチ、Claude 用 memory preview 経路など)
+  - 関連 test
+- **維持** (Codex 側を壊さないため):
+  - [src/cli/trim.mjs](../src/cli/trim.mjs) の Codex path (`--host codex`, `--codex-thread-id`, `--preflight`, `--execute`, etc.) はすべて維持
+  - [src/trim-model.mjs](../src/trim-model.mjs) の `describeTrimHost('codex')` / `buildTrimPlan` の Codex 関連
+  - [src/codex-app-server.mjs](../src/codex-app-server.mjs), [src/codex-rollout-memory.mjs](../src/codex-rollout-memory.mjs), `codex-*` CLI 全般
+  - `bin/throughline.mjs` の `trim` dispatch (Codex 経路で必要)
+  - Codex skill ([codex/skills/throughline](../codex/skills/throughline)) の trim 機能 (= 機能自体は無変更、SKILL.md 内の `/tl-trim` 言及があれば 4 TODO で update)
+
+### 2.5 `THROUGHLINE_DISABLE_AUTO_HANDOFF` env var
+
+- 値が `'1'` のとき auto path を skip
+- それ以外の値、または未設定 → auto path 有効 (= デフォルト ON)
+- 判定箇所: [src/session-start.mjs](../src/session-start.mjs)
+- 設定方法: ユーザーが `.bashrc` / `.zshrc` / VSCode terminal env / `~/.claude/settings.json` の `env` セクションで設定
+
+### 2.6 トレードオフ (受容する)
+
+- ⚠️ 「reset したい /clear」も auto path で引継ぎ発火する → 受容 (= 不要なら env で OFF)
+- ⚠️ baton TTL は 1 時間 (= 既存仕様維持)
+
+---
+
+## 3. 確定した内部判断
+
+### 3.1 `/rewind` source 検証 — 不要
+
+A 採択により本計画は `/rewind` を扱わない。`/rewind` 後の `source` 値は将来要件で再検討。
+
+### 3.2 `handoff_batons` テーブル — 残す + memo_text 列だけ drop
+
+- table 自体は baton path で必要なので **維持**
+- `memo_text TEXT` 列を schema v8 migration で drop
+- 既存の memo データは廃棄 (受容)
+- **SQLite DROP COLUMN 互換確認必須**: `ALTER TABLE ... DROP COLUMN` は SQLite 3.35.0+ で利用可。Node.js v22.5+ 同梱の SQLite バージョンで動作するか実装時に検証
+
+### 3.3 旧 `/tl` ユーザー移行 — `/tl` 自体は continue、memo 関連だけ breaking
+
+- `/tl` slash command 自体は使い続けられる (簡素化されただけ)
+- 廃止される機能: memo 4 項目入力、`save-inflight` CLI、`/tl-trim`
+- breaking change として CHANGELOG に明示
+
+### 3.4 `source='compact'` 扱い — 引継ぎしない
+
+auto-compaction は Claude Code 内部の context 圧縮で、conversation 連続性は host 側が担保している。Throughline 側で別途引継ぎを発火する必要なし。
+
+### 3.5 ログファイルの扱い
+
+- `~/.throughline/logs/inflight-memo.log`: `save-inflight` CLI 削除で **新規書き込みなし**。既存ファイルは削除提案を README / CHANGELOG に書く (= 自動削除はしない、ユーザー手動)
+- `~/.throughline/logs/inheritance-decision.log` 内の `baton_has_memo` フィールド: memo 廃止で意味を失うため、`logDecision()` から **削除**
+- `~/.throughline/logs/baton-write.log`: 維持 (= `/tl` baton 書き込みログとして引き続き有用)
+
+---
+
+## 4. 実装 TODO (実装開始可)
+
+優先度順:
+
+- [ ] **schema v8 migration** ([src/db.mjs](../src/db.mjs)): `ALTER TABLE handoff_batons DROP COLUMN memo_text`
+  - SQLite 3.35.0+ サポート確認 (Node.js v22.5+ 同梱版)
+  - 動かない場合は `CREATE TABLE` + `INSERT SELECT` + `DROP` の rebuild migration に切り替え
+- [ ] **`src/baton.mjs`**:
+  - `consumeBaton` 戻り値から `memoText` プロパティを削除
+  - `updateBatonMemo` 関数を **削除**
+  - `BATON_TTL_MS`, `writeBaton`, `consumeBaton` は維持
+- [x] **`src/handoff-record.mjs`**: **維持** (Codex 側 codex-handoff.mjs / codex-resume / codex-handoff-smoke 等が `memory.inflightMemo` / `memory.latestThinking` を参照しているため、削除すると Codex を壊す)。Claude 側で「使わない」のは resume-context.mjs 側で実現済み
+- [ ] **`src/resume-context.mjs`**: 注入テキストを新仕様に書き換え:
+  - memo セクション削除
+  - thinking セクション削除
+  - L3 references 一覧追加 (Codex `renderCodexRolloutMemoryPreview` 形式)
+  - footer 簡素化 (Continuation Instruction だけ残す)
+- [ ] **`src/session-start.mjs`** を 2.1 のロジックに改修:
+  - `consumeBaton` 先発 → `baton.sessionId` あれば inject
+  - 無ければ `source==='clear'` かつ env が `'1'` でない場合に inject
+  - それ以外は何もしない
+  - `logDecision()` から `baton_has_memo` フィールド削除
+- [ ] **`src/cli/save-inflight.mjs`** 削除
+- [ ] **`bin/throughline.mjs`** の `save-inflight` dispatch 削除 (`trim` dispatch は **維持**)
+- [ ] **`src/prompt-submit.mjs`**: 維持 (baton 書き込み + ensureMonitorTaskFile)
+- [ ] **[.claude/commands/tl.md](../.claude/commands/tl.md)**: memo 4 項目入力要求を削除、純粋に「baton 立てるだけ」の最小実装に書き換え
+- [x] **`/tl-trim` 関連削除**:
+  - [.claude/commands/tl-trim.md](../.claude/commands/tl-trim.md) ファイル削除
+  - **`src/cli/trim.mjs` 自体は維持**: Codex 経路 (`--host codex`, `--preflight`, `--execute`, `--codex-app-server-bin` 等) と doctor `--trim --host claude` で使う `describeTrimHost('claude')` の dry-run 表示が依存しているため、コード削除はしない (= ユーザーが直接 `throughline trim --host claude --dry-run` を打つ余地は残す。実用は SessionStart 自動経路に置き換わる)
+- [ ] **[src/cli/install.mjs](../src/cli/install.mjs)**: Throughline 管理 slash commands の copy 対象リストから `tl-trim.md` を除外。`tl.md` は維持。`src/cli/install.test.mjs` の関連 test も update
+- [ ] **[bin/throughline.mjs](../bin/throughline.mjs) の `showHelp()` 文言 update**:
+  - `save-inflight` 関連 help 文言を削除
+  - `/tl-trim` / Claude trim 関連の help 文言を削除
+  - Codex trim 関連 (`trim --dry-run`, `--preflight`, `--execute --host codex` など) は **維持**
+  - `bin/throughline.mjs` の `save-inflight` dispatch case 削除 (上の TODO と重複するが help text だけ別作業)
+- [ ] **[codex/skills/throughline/SKILL.md](../codex/skills/throughline/SKILL.md)**: `/tl-trim` への言及があれば削除し、`throughline trim --execute --host codex` 直接呼び出しに統一。Codex 側 trim 案内自体は維持
+- [ ] **[.codex-sidecar.yml](../.codex-sidecar.yml)** 確認: `/tl-trim` / `save-inflight` 経路の参照があれば削除。無ければ no-op
+- [ ] **テスト全部更新**:
+  - `src/baton.test.mjs` → memo 関連 test 削除、`updateBatonMemo` test 削除
+  - `src/session-merger.test.mjs` → source='clear' 自動経路の test 追加
+  - `src/resume-context.test.mjs` → memo/thinking 削除を反映
+  - `src/handoff-record.test.mjs` → projection 簡素化
+  - `src/hook-entrypoints.test.mjs` → save-inflight subprocess test ケース削除 (= 独立ファイルではなく本ファイル内の test)
+  - `src/turn-processor.test.mjs` → 既存維持
+  - `src/trim-cli.test.mjs` / `src/trim-model.test.mjs` → Claude path 関連テストのみ削除、Codex 経路テストは維持
+  - 新規: env var 判定 test、source='clear' auto path test
+- [ ] **docs 更新**:
+  - [CLAUDE.md](../CLAUDE.md): 設計の核を書き換え (「`/tl` バトンのみ」→「`source='clear'` 自動 + `/tl` 逃げ道」)
+  - [README.md](../README.md): 以下範囲を update:
+    - Quick Start: 「`/clear` で自動引継ぎ」中心に書き直し
+    - 「Explicit handoff via `/tl`」セクション: `save-inflight` / memo 4 項目要求の記述を削除、`/tl` は逃げ道として簡素な記述に
+    - Troubleshoot / How it compares 等の他セクション: `/tl-trim`, `save-inflight`, `inflight-memo.log` への言及をすべて削除
+    - `THROUGHLINE_DISABLE_AUTO_HANDOFF` env var 紹介を新規追加
+    - 既存 `inflight-memo.log` ファイルは新版で書き込み停止することを README で告知 (= 手動削除提案)
+  - [CHANGELOG.md](../CHANGELOG.md): breaking change を明示 (memo 廃止、save-inflight 削除、/tl-trim 削除、`updateBatonMemo` 削除、baton_has_memo フィールド削除)
+  - [INHERITANCE_ON_CLEAR_ONLY.md](INHERITANCE_ON_CLEAR_ONLY.md): 「2026-04 段階の検証 → 2026-05 でバグ修正により案 A 成立、本書は履歴扱い」note 追加
+  - [PUBLIC_RELEASE_PLAN.md](PUBLIC_RELEASE_PLAN.md): version bump + breaking change 反映
+- [ ] **package.json**: **0.4.0** に bump (semver minor、pre-1.0 の breaking)
+- [ ] **caveat 記録**: 「`/clear` SessionStart `source` は 2.1.128 で reliable、過去 #49937 は fix 済み」を public で記録
+
+---
+
+## 5. 削減できるコード規模 (見積もり)
+
+廃止対象:
+- `src/cli/save-inflight.mjs` (~80 行) → 削除
+- `src/cli/trim.mjs` の Claude path 部分 (~30 行) → 削除 (Codex path は維持)
+- [.claude/commands/tl-trim.md](../.claude/commands/tl-trim.md) (~40 行) → 削除
+- `src/baton.mjs` の `updateBatonMemo` 関数 (~10 行) → 削除
+- `handoff_batons.memo_text` 列 (schema migration、コードへの影響は consumeBaton 戻り値変更のみ)
+- `src/hook-entrypoints.test.mjs` 内 save-inflight test ケース (~30 行) → 削除
+- `resume-context.mjs` の memo/thinking セクション (~30 行) → 削除
+- `handoff-record.mjs` の memo/thinking projection (~50 行) → 削除
+- [.claude/commands/tl.md](../.claude/commands/tl.md) の memo 4 項目要求 (~20 行) → 削除
+
+代わりに追加:
+- `session-start.mjs` の env / source 判定 (~15 行)
+- `resume-context.mjs` の L3 refs framing (~30 行)
+
+純減 ~245 行。
+
+---
+
+## 6. Codex 側との整合 (壊さない)
+
+Codex 側 v0.3.25 の以下は本計画で **完全に無変更**:
+
+- `codex-capture` / `codex-summarize` / `codex-resume` (Codex primary L1/L2/L3 path)
+- `codex-resume --format handoff` (新規 Codex thread 用 prompt)
+- `trim --execute --host codex` / `--preflight --host codex` (app-server `thread/rollback` + `thread/inject_items`)
+- Codex Stop hook 90% auto-refresh
+- restore-safety / host primitive audit diagnostics
+- Codex skill ([codex/skills/throughline](../codex/skills/throughline)) の trim 機能 (= 機能自体は無変更、SKILL.md 内の `/tl-trim` 言及があれば 4 TODO で update)
+- [src/codex-app-server.mjs](../src/codex-app-server.mjs), [src/codex-rollout-memory.mjs](../src/codex-rollout-memory.mjs)
+- [src/trim-model.mjs](../src/trim-model.mjs) の Codex 関連 (`describeTrimHost('codex')`, `buildTrimPlan` の Codex source path)
+
+`codex-resume --memo-stdin` は引き続きユーザーが stdin で memo を流す経路。Throughline DB の baton.memo_text には依存していない (= 列削除の影響なし)。
+
+`/tl-trim` 削除に伴って Codex 経由でも slash command としての `/tl-trim` は使えなくなる。Codex 用 trim は `throughline trim --execute --host codex` を **CLI 直接呼ぶ**運用に統一 (Codex skill SKILL.md がそれを案内する)。
+
+---
+
+## 7. 進め方
+
+1. **本計画 確定** (ユーザー A 採択済み、本書 update により方針固定)
+2. **実装** (上記 TODO 順)
+3. **テスト + 実機 smoke + commit**
+4. **publish** (npm 0.4.0 として release)
+
+実機 smoke 手順:
+- 自動引継ぎ ON (デフォルト): /clear → 新セッションで curated memory 注入を確認
+- 自動引継ぎ OFF: env を立てて /clear → 注入されないことを確認
+- baton path: `/tl` を打って新 chat タブで開く → baton 経由で注入を確認
+- Codex 側 regression: `npm test` で既存 Codex test がすべて pass することを確認、`throughline trim --execute --host codex` の CLI 動作も維持

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "throughline",
-  "version": "0.3.25",
+  "version": "0.4.1",
   "type": "module",
   "description": "Claude Code hooks plugin for structured context compression (/clear-safe persistent memory)",
   "keywords": [

package/src/baton.mjs

@@ -1,19 +1,20 @@
 /**
  * baton.mjs — 引き継ぎバトン管理
  *
- * バトン方式の設計 (docs/INHERITANCE_ON_CLEAR_ONLY.md):
- *   - ユーザーが旧セッションで /tl スラッシュコマンドを打つ → UserPromptSubmit hook が
+ * バトン方式の設計 (docs/THROUGHLINE_CLEAR_AUTO_HANDOFF_PLAN.md):
+ *   - 新仕様では `/clear` 自動引継ぎがデフォルト ON。バトンは「/clear 自動引継ぎを
+ *     使わずに明示的に引き継ぎたい」ユーザーのための逃げ道。
+ *   - ユーザーが旧セッションで `/tl` スラッシュコマンドを打つ → UserPromptSubmit hook が
  *     baton テーブルに (project_path, session_id, created_at) を INSERT OR REPLACE
- *   - 新セッションの SessionStart hook が baton を消費:
- *     TTL 1 時間以内 かつ session_id が自分自身でない → 前任として merge
- *     期限切れ or 自己指名 → 破棄
- *   - 消費は atomic (BEGIN IMMEDIATE トランザクション内で SELECT + DELETE)
+ *   - 新セッションの SessionStart hook が baton を atomic に消費 (BEGIN IMMEDIATE 内で
+ *     SELECT + DELETE)。TTL 1 時間以内なら前任として merge、超過は破棄。
+ *   - 注入する curated memory は L1 + L2 + L3 refs のみ (memo / thinking なし)。
  *
- * なぜバトン方式か:
- *   - VSCode 拡張では SessionStart payload の source が /clear 後も "startup" に潰される
- *     ため source 値だけで /clear を識別できない (GitHub issue #49937)
- *   - 時間差ヒューリスティック (案 D) は誤爆の可能性があり、ユーザー明示の意思表示を
- *     引き継ぎ発火の唯一の条件とする方が決定論的
+ * 履歴: もともと VSCode 拡張で SessionStart payload の source が /clear 後も
+ *       "startup" に潰される問題 (#49937) に対する明示意思マーカーとして導入。
+ *       2026-05-08 時点で Claude Code 2.1.128 で source='clear' は reliable に
+ *       なったため auto path 中心の設計に変わったが、明示意思の signal として
+ *       baton 仕組み自体は残す。詳細は docs/THROUGHLINE_CLEAR_AUTO_HANDOFF_PLAN.md。
  */
 
 /**
@@ -24,9 +25,7 @@ export const BATON_TTL_MS = 60 * 60 * 1000; // 1 時間
 
 /**
  * 現在セッション (= /tl を発動したセッション) を次回 SessionStart で merge 対象に指名する。
- * 同 project_path の既存バトンがあれば session_id / created_at のみ上書き。
- * v7 で追加された memo_text は保持する（連続した /tl → save-inflight の順番で
- * 呼ばれた場合に、再度 /tl を打った時点で古い memo が消えないようにする）。
+ * 同 project_path の既存バトンがあれば session_id / created_at を上書き。
  *
  * @param {import('node:sqlite').DatabaseSync} db
  * @param {{ projectPath: string, sessionId: string, now?: number }} params
@@ -41,43 +40,17 @@ export function writeBaton(db, { projectPath, sessionId, now = Date.now() }) {
   ).run(projectPath, sessionId, now);
 }
 
-/**
- * 既存バトンの memo_text を更新する。バトンが存在しない場合は NOOP。
- * /tl 発動後、現行セッションの Claude が `throughline save-inflight` CLI 経由で
- * 呼び出す。memo_text は Markdown 形式の「次の一手 / 現在の方針 / 未解決 /
- * 進行中 TODO」をまとめたテキスト。
- *
- * Windows 互換: ドライブレター（`C:` / `c:`）やパス区切りの差異で
- * /tl 書き込み時と save-inflight 呼び出し時の project_path が一致しない
- * ケースがあるため、SQLite の COLLATE NOCASE で大小無視で照合する。
- *
- * @param {import('node:sqlite').DatabaseSync} db
- * @param {{ projectPath: string, memoText: string, now?: number }} params
- * @returns {{ updated: boolean }}
- */
-export function updateBatonMemo(db, { projectPath, memoText }) {
-  const result = db
-    .prepare(
-      `UPDATE handoff_batons SET memo_text = ? WHERE project_path = ? COLLATE NOCASE`,
-    )
-    .run(memoText, projectPath);
-  return { updated: (result.changes ?? 0) > 0 };
-}
-
 /**
  * 同 project_path のバトンを読み出して削除する (atomic)。
  *
  * 戻り値:
- *   - { sessionId, ageMs, memoText }   : バトン存在 かつ TTL 以内
- *   - { sessionId: null, skipReason: 'expired', ageMs }  : TTL 超過で破棄
+ *   - { sessionId, ageMs }                                : バトン存在 かつ TTL 以内
+ *   - { sessionId: null, skipReason: 'expired', ageMs }   : TTL 超過で破棄
  *   - { sessionId: null, skipReason: 'missing' }          : バトン無し
  *
- * memoText は /tl 後に save-inflight で書き込まれた in-flight メモ。
- * 未保存なら null。
- *
  * @param {import('node:sqlite').DatabaseSync} db
  * @param {{ projectPath: string, now?: number, ttlMs?: number }} params
- * @returns {{ sessionId: string | null, ageMs?: number, memoText?: string | null, skipReason?: 'expired' | 'missing' }}
+ * @returns {{ sessionId: string | null, ageMs?: number, skipReason?: 'expired' | 'missing' }}
  */
 export function consumeBaton(db, { projectPath, now = Date.now(), ttlMs = BATON_TTL_MS }) {
   db.exec('BEGIN IMMEDIATE');
@@ -85,7 +58,7 @@ export function consumeBaton(db, { projectPath, now = Date.now(), ttlMs = BATON_
     // Windows 互換: ドライブレターの大小差を吸収するため COLLATE NOCASE
     const row = db
       .prepare(
-        `SELECT session_id, created_at, memo_text FROM handoff_batons WHERE project_path = ? COLLATE NOCASE`,
+        `SELECT session_id, created_at FROM handoff_batons WHERE project_path = ? COLLATE NOCASE`,
       )
       .get(projectPath);
 
@@ -108,7 +81,6 @@ export function consumeBaton(db, { projectPath, now = Date.now(), ttlMs = BATON_
     return {
       sessionId: row.session_id,
       ageMs,
-      memoText: row.memo_text ?? null,
     };
   } catch (err) {
     try {

package/src/baton.test.mjs

@@ -1,7 +1,7 @@
 import { test } from 'node:test';
 import assert from 'node:assert/strict';
 import { DatabaseSync } from 'node:sqlite';
-import { writeBaton, consumeBaton, updateBatonMemo, BATON_TTL_MS } from './baton.mjs';
+import { writeBaton, consumeBaton, BATON_TTL_MS } from './baton.mjs';
 
 function makeDb() {
   const db = new DatabaseSync(':memory:');
@@ -9,8 +9,7 @@ function makeDb() {
     CREATE TABLE handoff_batons (
       project_path TEXT    PRIMARY KEY,
       session_id   TEXT    NOT NULL,
-      created_at   INTEGER NOT NULL,
-      memo_text    TEXT
+      created_at   INTEGER NOT NULL
     );
   `);
   return db;
@@ -99,46 +98,10 @@ test('consumeBaton: scopes per project_path (does not cross-consume)', () => {
   assert.equal(rows.length, 1);
 });
 
-test('updateBatonMemo: writes memo_text into existing baton', () => {
-  const db = makeDb();
-  writeBaton(db, { projectPath: '/proj', sessionId: 'S1', now: 1000 });
-  const result = updateBatonMemo(db, { projectPath: '/proj', memoText: '次の一手: X' });
-  assert.equal(result.updated, true);
-  const row = db.prepare('SELECT memo_text FROM handoff_batons').get();
-  assert.equal(row.memo_text, '次の一手: X');
-});
-
-test('updateBatonMemo: is a NOOP when no baton exists (no throw)', () => {
-  const db = makeDb();
-  const result = updateBatonMemo(db, { projectPath: '/missing', memoText: 'hello' });
-  assert.equal(result.updated, false);
-});
-
-test('writeBaton: preserves memo_text when same project_path is re-batoned', () => {
-  const db = makeDb();
-  writeBaton(db, { projectPath: '/proj', sessionId: 'S1', now: 1000 });
-  updateBatonMemo(db, { projectPath: '/proj', memoText: 'preserved memo' });
-  // 同じ project_path に再度 /tl を打っても memo は残る
-  writeBaton(db, { projectPath: '/proj', sessionId: 'S2', now: 2000 });
-  const row = db.prepare('SELECT * FROM handoff_batons').get();
-  assert.equal(row.session_id, 'S2');
-  assert.equal(row.created_at, 2000);
-  assert.equal(row.memo_text, 'preserved memo');
-});
-
-test('consumeBaton: returns memoText when set', () => {
-  const db = makeDb();
-  writeBaton(db, { projectPath: '/proj', sessionId: 'S1', now: 1000 });
-  updateBatonMemo(db, { projectPath: '/proj', memoText: '中断メモ' });
-  const result = consumeBaton(db, { projectPath: '/proj', now: 1000 + 1000 });
-  assert.equal(result.sessionId, 'S1');
-  assert.equal(result.memoText, '中断メモ');
-});
-
-test('consumeBaton: returns memoText=null when not set', () => {
+test('consumeBaton: returns no memoText property in v8 (memo column dropped)', () => {
   const db = makeDb();
   writeBaton(db, { projectPath: '/proj', sessionId: 'S1', now: 1000 });
   const result = consumeBaton(db, { projectPath: '/proj', now: 1000 + 1000 });
   assert.equal(result.sessionId, 'S1');
-  assert.equal(result.memoText, null);
+  assert.equal('memoText' in result, false, 'memoText property should be removed in v8');
 });

package/src/cli/install.mjs

@@ -18,7 +18,7 @@ import { homedir } from 'node:os';
 
 const PACKAGE_ROOT = resolve(dirname(fileURLToPath(import.meta.url)), '..', '..');
 const SLASH_COMMANDS_SRC = join(PACKAGE_ROOT, '.claude', 'commands');
-const SC_SLASH_COMMAND_FILES = ['tl.md', 'sc-detail.md', 'tl-trim.md'];
+const SC_SLASH_COMMAND_FILES = ['tl.md', 'sc-detail.md'];
 const CODEX_SKILLS_SRC = join(PACKAGE_ROOT, 'codex', 'skills');
 const CODEX_SKILL_NAMES = ['throughline'];
 const CODEX_HOOKS_RELATIVE_PATH = ['.codex', 'hooks.json'];
@@ -415,7 +415,7 @@ export async function run(args = []) {
   console.log('有効な hooks:');
   console.log('  SessionStart     → throughline session-start  (セッション記録・バトン消費・引き継ぎ注入)');
   console.log('  Stop             → throughline process-turn   (L1 要約 + L2 本文保存 + L3 詳細保存)');
-  console.log('  UserPromptSubmit → throughline prompt-submit  (/tl バトン書き込み)');
+  console.log('  UserPromptSubmit → throughline prompt-submit  (/tl & /clear バトン書き込み)');
   if (codex) {
     console.log(`  Codex Stop       → ${buildCodexStopHookCommand()} (Codex rollout capture + L1 要約)`);
   }

package/src/cli/install.test.mjs

@@ -54,7 +54,7 @@ test('global install copies Throughline slash commands to ~/.claude/commands/',
     const trim = join(home.dir, '.claude', 'commands', 'tl-trim.md');
     assert.ok(existsSync(tl), 'tl.md should be installed globally');
     assert.ok(existsSync(sc), 'sc-detail.md should be installed globally');
-    assert.ok(existsSync(trim), 'tl-trim.md should be installed globally');
+    assert.ok(!existsSync(trim), 'tl-trim.md should NOT be installed (deprecated in v0.4.0)');
     const tlBody = readFileSync(tl, 'utf8');
     assert.match(tlBody, /Throughline/, 'tl.md content should be real');
     const settings = JSON.parse(readFileSync(join(home.dir, '.claude', 'settings.json'), 'utf8'));
@@ -261,8 +261,6 @@ test('uninstall removes slash command files', async () => {
     assert.ok(!existsSync(tl), 'uninstall should remove tl.md');
     const sc = join(home.dir, '.claude', 'commands', 'sc-detail.md');
     assert.ok(!existsSync(sc), 'uninstall should remove sc-detail.md');
-    const trim = join(home.dir, '.claude', 'commands', 'tl-trim.md');
-    assert.ok(!existsSync(trim), 'uninstall should remove tl-trim.md');
     const codexSkill = join(home.dir, '.codex', 'skills', 'throughline', 'SKILL.md');
     assert.ok(!existsSync(codexSkill), 'uninstall should remove Throughline Codex skill');
   } finally {

package/src/db-schema.test.mjs

@@ -38,10 +38,10 @@ function indexNames(db) {
     .map((row) => row.name);
 }
 
-test('schema v7 preserves Claude-facing tables, fields, and unique indexes', async () => {
+test('schema v8 preserves Claude-facing tables, fields, and unique indexes', async () => {
   await withIsolatedDb((db) => {
     const version = db.prepare('PRAGMA user_version').get();
-    assert.equal(version.user_version, 7);
+    assert.equal(version.user_version, 8);
 
     assert.deepEqual(columnNames(db, 'sessions'), [
       'session_id',
@@ -87,7 +87,6 @@ test('schema v7 preserves Claude-facing tables, fields, and unique indexes', asy
       'project_path',
       'session_id',
       'created_at',
-      'memo_text',
     ]);
 
     const indexes = indexNames(db);

package/src/db.mjs

@@ -9,7 +9,7 @@ import { join } from 'path';
 
 const DB_DIR = join(homedir(), '.throughline');
 const DB_PATH = join(DB_DIR, 'throughline.db');
-const CURRENT_VERSION = 7;
+const CURRENT_VERSION = 8;
 
 let _db = null;
 
@@ -202,6 +202,19 @@ function initSchema(db) {
     }
   }
 
+  // v7 → v8: handoff_batons から memo_text 列を drop。
+  // 新仕様 (docs/THROUGHLINE_CLEAR_AUTO_HANDOFF_PLAN.md) で memo 廃止:
+  //   - /clear 自動引継ぎ (SessionStart source='clear') + /tl baton (memo なし) の 2 経路に
+  //   - 注入は L1 + L2 + L3 refs のみ
+  //   - save-inflight CLI / updateBatonMemo 関数も併せて削除
+  // SQLite 3.35.0+ で DROP COLUMN サポート (Node.js v22.5+ 同梱版で利用可)。
+  if (version < 8) {
+    const batonCols = db.prepare('PRAGMA table_info(handoff_batons)').all();
+    if (batonCols.some((c) => c.name === 'memo_text')) {
+      db.exec('ALTER TABLE handoff_batons DROP COLUMN memo_text');
+    }
+  }
+
   if (version < CURRENT_VERSION) {
     db.exec(`PRAGMA user_version = ${CURRENT_VERSION}`);
   }