watashi-db 0.0.13 → 0.0.15

package/misc/20260316_110841_groom-recipe.md

@@ -0,0 +1,483 @@
+# 蒸留機能の実用化: /groom + アーカイブ + 検索2段階化
+
+## Context
+
+Episode 112件、Decision 84件が溜まっているが、蒸留（Insight/Theory/Model への統合）は Insight 3件、Theory 5件のみ。蒸留のインフラ（groom_episodes, mark_groomed, watashi_store_knowledge）は実装済みだが、ワークフローとして回す仕組みがない。蒸留済みレコードのアーカイブ機能も未実装。
+
+**目的**: `/groom` コマンドで蒸留を実行 → 古いレコードをアーカイブ → 検索ノイズを減らしつつ必要時に archived も引ける状態にする。
+
+---
+
+## Step 1: Decision に `archived` ステータスを追加
+
+Episode は既に `archived` を持つが Decision にはない。蒸留後のアーカイブに必要。
+
+### `src/constants.ts`
+
+```typescript
+// 変更前:
+export const DECISION_STATUSES = [
+  "active",      // 有効
+  "reversed",    // 撤回済み
+  "obsolete",    // 廃止
+  "promoted",    // 別Storeへ昇格済み
+] as const;
+
+// 変更後:
+export const DECISION_STATUSES = [
+  "active",      // 有効
+  "reversed",    // 撤回済み
+  "obsolete",    // 廃止
+  "archived",    // アーカイブ済み（蒸留済み）
+  "promoted",    // 別Storeへ昇格済み
+] as const;
+```
+
+### `src/types.ts`
+
+`ManageClaimSchema` の `decision_status` enum に `"archived"` を追加:
+
+```typescript
+// 変更前:
+decision_status: z.enum(["reversed", "obsolete"]).optional(),
+
+// 変更後:
+decision_status: z.enum(["reversed", "obsolete", "archived"]).optional(),
+```
+
+> マイグレーション不要（status カラムは TEXT 型、CHECK 制約なし）
+
+---
+
+## Step 2: アーカイブ関数の実装
+
+### `src/database/queries-core.ts` — 新関数2つ
+
+```typescript
+/** Episode をアーカイブ（蒸留済み + 最新N件を除外） */
+export function archiveEpisodes(db: Database.Database, params: {
+  episodeIds?: string[];
+  keepLatest?: number;
+  scope?: string;
+}): { archivedIds: string[]; archivedCount: number } {
+  const keepLatest = params.keepLatest ?? 20;
+
+  if (params.episodeIds && params.episodeIds.length > 0) {
+    // 個別指定モード: 指定IDのみアーカイブ
+    const updated: string[] = [];
+    const stmt = db.prepare(
+      "UPDATE episodes SET status = 'archived', updated_at = @now WHERE id = @id AND status = 'active'"
+    );
+    const now = new Date().toISOString();
+    for (const id of params.episodeIds) {
+      const result = stmt.run({ id, now });
+      if (result.changes > 0) updated.push(id);
+    }
+    return { archivedIds: updated, archivedCount: updated.length };
+  }
+
+  // 自動モード: groomed_at IS NOT NULL かつ最新 keepLatest 件を除外
+  const scopeFilter = params.scope ? " AND scope = @scope" : "";
+  const scopeValues = params.scope ? { scope: params.scope } : {};
+
+  // 最新 keepLatest 件の ID を取得（保護対象）
+  const protectedIds = db.prepare(`
+    SELECT id FROM episodes
+    WHERE status = 'active'${scopeFilter}
+    ORDER BY created_at DESC
+    LIMIT @keepLatest
+  `).all({ ...scopeValues, keepLatest }) as { id: string }[];
+
+  const protectedSet = new Set(protectedIds.map(r => r.id));
+
+  // groomed_at IS NOT NULL かつ保護対象外をアーカイブ
+  const candidates = db.prepare(`
+    SELECT id FROM episodes
+    WHERE status = 'active' AND groomed_at IS NOT NULL${scopeFilter}
+  `).all(scopeValues) as { id: string }[];
+
+  const toArchive = candidates.filter(r => !protectedSet.has(r.id));
+  const now = new Date().toISOString();
+  const stmt = db.prepare(
+    "UPDATE episodes SET status = 'archived', updated_at = @now WHERE id = @id"
+  );
+  for (const r of toArchive) {
+    stmt.run({ id: r.id, now });
+  }
+
+  return { archivedIds: toArchive.map(r => r.id), archivedCount: toArchive.length };
+}
+
+/** Decision をアーカイブ（最新N件を除外） */
+export function archiveDecisions(db: Database.Database, params: {
+  decisionIds?: string[];
+  keepLatest?: number;
+  scope?: string;
+}): { archivedIds: string[]; archivedCount: number } {
+  const keepLatest = params.keepLatest ?? 20;
+
+  if (params.decisionIds && params.decisionIds.length > 0) {
+    const updated: string[] = [];
+    const stmt = db.prepare(
+      "UPDATE decisions SET status = 'archived', updated_at = @now WHERE id = @id AND status = 'active'"
+    );
+    const now = new Date().toISOString();
+    for (const id of params.decisionIds) {
+      const result = stmt.run({ id, now });
+      if (result.changes > 0) updated.push(id);
+    }
+    return { archivedIds: updated, archivedCount: updated.length };
+  }
+
+  // 自動モード: 最新 keepLatest 件を除外してアーカイブ
+  const scopeFilter = params.scope ? " AND scope = @scope" : "";
+  const scopeValues = params.scope ? { scope: params.scope } : {};
+
+  const protectedIds = db.prepare(`
+    SELECT id FROM decisions
+    WHERE status = 'active'${scopeFilter}
+    ORDER BY created_at DESC
+    LIMIT @keepLatest
+  `).all({ ...scopeValues, keepLatest }) as { id: string }[];
+
+  const protectedSet = new Set(protectedIds.map(r => r.id));
+
+  const candidates = db.prepare(`
+    SELECT id FROM decisions
+    WHERE status = 'active'${scopeFilter}
+  `).all(scopeValues) as { id: string }[];
+
+  const toArchive = candidates.filter(r => !protectedSet.has(r.id));
+  const now = new Date().toISOString();
+  const stmt = db.prepare(
+    "UPDATE decisions SET status = 'archived', updated_at = @now WHERE id = @id"
+  );
+  for (const r of toArchive) {
+    stmt.run({ id: r.id, now });
+  }
+
+  return { archivedIds: toArchive.map(r => r.id), archivedCount: toArchive.length };
+}
+```
+
+### `src/database/queries.ts` — ラッパー追加
+
+```typescript
+export function archiveEpisodes(params: {
+  episodeIds?: string[];
+  keepLatest?: number;
+  scope?: string;
+}): { archivedIds: string[]; archivedCount: number } {
+  return core.archiveEpisodes(getDatabase(), params);
+}
+
+export function archiveDecisions(params: {
+  decisionIds?: string[];
+  keepLatest?: number;
+  scope?: string;
+}): { archivedIds: string[]; archivedCount: number } {
+  return core.archiveDecisions(getDatabase(), params);
+}
+```
+
+---
+
+## Step 3: フェデレーション対応
+
+### `src/store/federation.ts` — 新関数
+
+既存の `federatedMarkEpisodesGroomed` のパターンに倣う。default store のみ対象で十分（マルチストアのアーカイブは現時点では不要）。
+
+```typescript
+export function federatedArchiveEpisodes(
+  manager: StoreManager,
+  context: ActiveContext,
+  params: { episodeIds?: string[]; keepLatest?: number; scope?: string },
+): { archivedIds: string[]; archivedCount: number } {
+  const db = manager.getStore(context.activeStore);
+  return archiveEpisodes(db, params);
+}
+
+export function federatedArchiveDecisions(
+  manager: StoreManager,
+  context: ActiveContext,
+  params: { decisionIds?: string[]; keepLatest?: number; scope?: string },
+): { archivedIds: string[]; archivedCount: number } {
+  const db = manager.getStore(context.activeStore);
+  return archiveDecisions(db, params);
+}
+```
+
+---
+
+## Step 4: maintenance-tools にアクションハンドラ追加
+
+### `src/types.ts` — MaintainSchema 拡張
+
+`action` enum に追加:
+```typescript
+"archive_episodes", "archive_decisions"
+```
+
+新パラメータ追加:
+```typescript
+archive_entity_ids: z.array(z.string()).optional().describe("(archive_episodes/archive_decisions) 個別指定でアーカイブ"),
+archive_keep_latest: z.number().int().min(0).default(20).optional().describe("(archive_episodes/archive_decisions) 最新N件を残す"),
+```
+
+### `src/tools/maintenance-tools.ts` — ハンドラ追加
+
+```typescript
+if (params.action === "archive_episodes") {
+  if (params.dry_run) {
+    // dry_run: アーカイブ対象件数のみ返す（実際には更新しない）
+    // → 対象候補を SELECT で取得して件数を返す
+  }
+  const result = federatedArchiveEpisodes(manager, context, {
+    episodeIds: params.archive_entity_ids,
+    keepLatest: params.archive_keep_latest ?? 20,
+    scope: params.scope,
+  });
+
+  // 監査ログ
+  if (result.archivedCount > 0) {
+    insertAuditLog({
+      operation: "archive",
+      entity_type: "episode",
+      entity_id: result.archivedIds.join(","),
+      summary: `${result.archivedCount}件のEpisodeをアーカイブ`,
+      provenance,
+    });
+  }
+  notifyWrite();
+  return ok(result);
+}
+
+// archive_decisions も同様
+```
+
+> **dry_run 対応**: `params.dry_run === true` の場合はトランザクション内で SELECT のみ実行し、対象件数とIDリストを返す。UPDATE はしない。
+
+---
+
+## Step 5: 検索の2段階フォールバック
+
+### 方針
+
+- unified_search_items は active レコードのみ保持（トリガー設計）
+- query モードで結果0件の場合、ソーステーブルの FTS を直接クエリして archived を含む再検索
+- archived ヒット時はレスポンスに注記を付与
+
+### `src/database/queries-core.ts` — archived 含む検索関数
+
+```typescript
+/**
+ * archived を含む FTS 検索（フォールバック用）
+ * unified_search_items ではなくソーステーブルの FTS を直接クエリ
+ */
+export function searchIncludingArchived(db: Database.Database, params: {
+  query: string;
+  scope?: string;
+  limit: number;
+}): UnifiedSearchRow[] {
+  const results: UnifiedSearchRow[] = [];
+
+  // 検索対象テーブル（FTS テーブル名、ソーステーブル名、entity_type）
+  const targets = [
+    { fts: "episodes_fts", table: "episodes", type: "episode" },
+    { fts: "decisions_fts", table: "decisions", type: "decision" },
+    { fts: "claims_fts", table: "claims", type: "claim" },
+    { fts: "theories_fts", table: "theories", type: "theory" },
+    { fts: "insights_fts", table: "insights", type: "insight" },
+    { fts: "models_fts", table: "models", type: "model" },
+  ] as const;
+
+  for (const target of targets) {
+    try {
+      const scopeFilter = params.scope
+        ? ` AND (t.scope = '${params.scope}' OR t.scope = 'global')`
+        : "";
+      const rows = db.prepare(`
+        SELECT t.id as entity_id, '${target.type}' as entity_type,
+               t.title as title_summary, t.scope, t.status,
+               t.created_at, t.updated_at
+        FROM ${target.table} t
+        JOIN ${target.fts} f ON f.rowid = t.rowid
+        WHERE ${target.fts} MATCH @query${scopeFilter}
+        ORDER BY rank
+        LIMIT @limit
+      `).all({ query: params.query, limit: params.limit }) as UnifiedSearchRow[];
+
+      results.push(...rows);
+    } catch {
+      // FTS テーブル未存在等はスキップ
+    }
+  }
+
+  // スコア順でソートして limit 件に制限
+  return results.slice(0, params.limit);
+}
+```
+
+> 注意: FTS MATCH のクエリ構文は unified_search_fts と同じ。ソーステーブルの FTS カラム構成は異なるため、必要に応じて調整。
+
+### `src/tools/query-tools.ts` — フォールバック組み込み
+
+query モードのハンドラで結果が0件だった場合:
+
+```typescript
+// 既存: federatedUnifiedSearch で検索
+const results = federatedUnifiedSearch(manager, context, searchParams);
+
+if (results.length === 0 && params.query) {
+  // フォールバック: archived 含む再検索
+  const archivedResults = federatedSearchIncludingArchived(manager, context, {
+    query: params.query,
+    scope: params.scope,
+    limit: params.limit ?? 20,
+  });
+
+  if (archivedResults.length > 0) {
+    // archived からのヒットを返す
+    return {
+      content: [{
+        type: "text",
+        text: JSON.stringify({
+          query: params.query,
+          results: archivedResults,
+          total_count: archivedResults.length,
+          note: "アクティブなレコードでは見つかりませんでした。アーカイブ済みレコードから検出しました。",
+        }, null, 2),
+      }],
+    };
+  }
+}
+```
+
+### `src/store/federation.ts` — フェデレーション対応
+
+```typescript
+export function federatedSearchIncludingArchived(
+  manager: StoreManager,
+  context: ActiveContext,
+  params: { query: string; scope?: string; limit: number },
+): UnifiedSearchRow[] {
+  // 各ストアで searchIncludingArchived を実行し結果をマージ
+  // 既存の federatedUnifiedSearch のパターンに倣う
+}
+```
+
+---
+
+## Step 6: /groom スキルの作成
+
+### `cowork-plugin/skills/groom/SKILL.md` — 新規作成
+
+```markdown
+---
+description: >
+  記録の棚卸し（蒸留）を行う。未処理のEpisode/Decisionからパターンを抽出し、
+  Insight/Theory/Modelとして蒸留する。蒸留済みの古いレコードはアーカイブする。
+---
+
+記録の棚卸し（蒸留）を行います。
+
+## 引数
+- `$ARGUMENTS`: （オプション）蒸留したいトピックやスコープ
+
+## 手順
+
+### Step 1: 素材の収集
+以下のツールを並行して呼び出し、蒸留対象のデータを収集する:
+- `watashi_maintain(action='groom_episodes')`: 未グルーミングのEpisode一覧
+- `watashi_search(entity_types=["decision"], limit=50)`: active Decision一覧
+- `watashi_search(entity_types=["insight"], limit=20)`: 既存Insight（重複回避用）
+
+### Step 2: パターン分析と蒸留
+収集したEpisode/Decisionから以下を分析:
+
+1. **繰り返しテーマの検出**: 複数のEpisodeに共通するトピック・問題パターン
+2. **原則の統合**: 個別Episodeの l2_principles を横断分析し、汎用的な原則を抽出
+3. **既存Insightとの照合**: 重複・矛盾がないか確認
+
+分析結果に基づき生成:
+- **Insight**: 具体的で再利用可能な知見（1つのパターン）
+  → `watashi_store_knowledge(kind='insight', supporting_episode_ids=[...])`
+- **Theory**: 体系的なフレームワーク（複数パターンの統合）
+  → `watashi_store_knowledge(kind='theory', supporting_episode_ids=[...])`
+
+l2_trigger_conditions（いつ適用するか）と l2_resolution_steps（具体的に何をするか）を必ず記入すること。
+「まとめただけ」にならないよう、「次に同じ状況になったときの行動が変わる」レベルの知見を目指す。
+
+### Step 3: グルーミング済みマーク
+蒸留に使用したEpisodeをマーク:
+- `watashi_maintain(action='mark_groomed', episode_ids=[...])`
+
+### Step 4: アーカイブ（ユーザー承認制）
+蒸留済みの古いレコードをアーカイブ（最新20件は維持）:
+1. `watashi_maintain(action='archive_episodes', archive_keep_latest=20, dry_run=true)` でプレビュー
+2. 件数と対象をユーザーに提示し、承認を得る
+3. 承認後 `dry_run=false` で実行
+4. Decision も同様に実行
+
+### Step 5: サマリー報告
+
+## 出力形式
+
+```
+## 棚卸しサマリー
+
+### 分析した素材
+- Episode: X件（うち未グルーミング: Y件）
+- Decision: Z件
+
+### 蒸留結果
+- 新規Insight: N件
+  - [タイトル]（出典: [Episode ID一覧]）
+- 新規Theory: N件（該当があれば）
+
+### アーカイブ
+- Episode: X件をアーカイブ（最新20件は維持）
+- Decision: Y件をアーカイブ（最新20件は維持）
+```
+
+## 注意事項
+- 素材が5件未満の場合は蒸留を見送り、蓄積を促す
+- アーカイブは必ず dry_run でプレビュー → ユーザー承認後に実行
+- supporting_episode_ids を必ず設定する
+- 既存のInsight/Theoryと重複する場合は統合を提案する
+```
+
+---
+
+## 実装順序
+
+1. `src/constants.ts` + `src/types.ts` — Decision archived 追加 + MaintainSchema 拡張
+2. `src/database/queries-core.ts` + `src/database/queries.ts` — アーカイブ関数 + archived 検索関数
+3. `src/store/federation.ts` — フェデレーション対応
+4. `src/tools/maintenance-tools.ts` — archive_episodes / archive_decisions ハンドラ
+5. `src/tools/query-tools.ts` — 検索2段階フォールバック
+6. `cowork-plugin/skills/groom/SKILL.md` — /groom スキル
+7. テスト追加
+
+## 検証方法
+
+1. `npm run build` でコンパイル通過
+2. `npm test` で既存839テスト通過
+3. 新規テスト:
+   - Episode/Decision の archive → status 変更確認
+   - archived レコードが unified_search_items から除外されることを確認
+   - 検索2段階: active で0件 → archived からヒットすることを確認
+4. 手動確認: Claude Code 再起動後、`/groom` でワークフローが動作するか
+
+## 既存コードの参考箇所
+
+| 用途 | ファイル | 関数/行 |
+|------|---------|---------|
+| groomed Episode 取得 | queries-core.ts | `listUngroomedEpisodes` (L1235) |
+| groomed マーク | queries-core.ts | `markEpisodesGroomed` (L1310) |
+| Decision ステータス変更 | queries-core.ts | `updateDecisionStatus` |
+| Knowledge 生成 | knowledge-tools.ts | `watashi_store_knowledge` |
+| フェデレーション パターン | federation.ts | `federatedMarkEpisodesGroomed` |
+| unified_search トリガー | schema.ts | L2032-2065（INSERT/UPDATE/DELETE トリガー） |
+| 既存 Skill フォーマット | cowork-plugin/skills/reflect/SKILL.md | |