<!-- sage-metadata cost-tier: haiku activation: auto tags: [context, persistence, session, continuity] inputs: [codebase] outputs: [session-state] -->

Session Bridge

プランファイルを信頼できる情報源として使用し、セッション間の連続性を維持します。

コア原則: ファイルシステムが信頼できる情報源です。.sage/work/ に存在するアーティファクトとそのフロントマター状態から、現在地を把握できます。decisions.md は、アクティブな作業を素早く見つけるのに役立つ推論コンテキストを提供します。状態更新はチェックポイント(ルール7)で発生し、タスクごとではありません。

状態アーキテクチャ

それぞれ異なる目的を持つ、2つのレベルの状態があります。

信頼できる情報源: .sage/work/ 内のアーティファクト

.sage/work/<feature>/ には YAML フロントマター付きのアーティファクトが含まれます:

• brief.md、spec.md、plan.md — それぞれ status と phase を持つ
• ステータスフィールド: pending、in-progress、completed、blocked
• アーティファクトの存在とそのフロントマター状態が状態そのものです

これは常に正確です なぜなら、アーティファクトはワークフローの一部として作成および更新されるからです。別の「保存」アクションは不要です。

コンテキスト: decisions.md

.sage/decisions.md はエージェントと人間の両方が重要な決定とコンテキストを記述する共有ログです。アーティファクトのフロントマターでは捉えられない推論を提供します — 決定がなされた理由、どのような代替案が検討されたか、および人間の優先事項は何かです。

ロード(セッション開始時)

作業を再開する際は、この優先順序に従います。

ステップ1: アーティファクトから状態をスキャンする

.sage/work/ をスキャンしてアクティブなイニシアチブを探します。brief.md、spec.md、または plan.md(存在するもの)からフロントマターを読み込みます。タイトル、ステータス、フェーズを記録します。プランが存在する場合は、タスクチェックボックスをスキャンして実装がどの程度進んだかを理解します。

これが信頼できる情報源です — どのアーティファクトが存在するかが、プロジェクトがどこにあるかを示します。

ステップ2: コンテキストの決定を読む

.sage/decisions.md が存在する場合は、最後の3～5エントリを読み込みます。これらは最近の決定と方向転換を記録します — プロジェクトがどの状態にあるか(WHAT)ではなく、なぜその状態にあるのか(WHY)を示します。

ステップ3: コードベースに対して検証する

アーティファクトとコードベースが矛盾している場合(例:プランは「スペック段階」と言っているが実装ファイルが存在する)、コードベースを信頼します。ファイルシステムが究極の信頼できる情報源です。アーティファクトを現実と一致するよう更新します。

ステップ4: 人間に報告する

Sage: [フィーチャー名] を再開中です。[フェーズ]段階です。 [存在するものと次に何をするかの概要。]

保存(チェックポイント時)

状態更新はチェックポイント(ルール7)でのみ発生し、タスクごとではありません。

各チェックポイントで:

重要な決定を .sage/decisions.md の先頭に追加します:

### 2025-03-13 — トークンストレージの決定
JWT ストレージに localStorage ではなく httpOnly クッキーを選択しました。
XSS 保護は CSRF 処理コストを上回ります。
spec.md はクッキーベースの認証アプローチで更新されました。

ステータスが変わった場合、アーティファクトのフロントマターを更新します。

規約を発見した後:

.sage/conventions.md に追加します:

### エラーハンドリング
プロジェクトは src/middleware/error-handler.ts の一元化されたエラーハンドラを使用しています。
すべてのルートハンドラは型付きエラーをスロー します。ミドルウェアがレスポンスをフォーマットします。

保存(セッション終了時)

セッションが正常に終了する場合(人間が「停止」「今のところ終了」と言う):

1. 現在のフェーズを反映するようアーティファクトのフロントマターを更新
2. 重要な作業が行われた場合は、セッション概要を decisions.md の先頭に追加
3. 報告: "Sage: セッションを保存しました。次回再開するには /build を入力してください。"

セッションが予期せず終了した場合: .sage/work/ 内のアーティファクトとそのフロントマターは実際の状態を反映します。次のセッションのスラッシュコマンド自動ピックアップはそれらを読み込んで方向を定めます。

FIX モード状態

FIX モードは通常、プランアーティファクトを持ちません。FIX モードの場合:

• 根本原因と修正は、クローズチェックポイントで decisions.md に記録されます
• 修正は通常1つのセッション内で完了するため、状態はより単純です
• 中断された場合、次の /fix コマンドは実行中の修正作業をスキャンします

復旧

アーティファクトが見つからない: "Sage: 新しいプロジェクト、進行中の作業はありません。"

すべてのアーティファクトが完了している: 前のイニシアチブ [名前] は完了しています。 新しいタスクの準備ができています。

アーティファクトとコードベースが矛盾している: ファイルシステム(git log、ファイル存在)をアーティファクトより常に信頼します。アーティファクトのフロントマターを現実と一致するよう更新します。

ルール

• .sage/work/ 内のアーティファクトが状態の信頼できる情報源です。
• decisions.md が推論とコンテキストの信頼できる情報源です。
• チェックポイントでのみ状態を更新します(ルール7)、タスクごとではありません。
• decisions.md に追加する — 上書きしません。conventions.md に追加します。
• 状態が曖昧な場合は、コードベースに対して検証します。

障害モード

• アーティファクトが見つからない: 新しいプロジェクト。報告して、何を構築するかを尋ねます。
• 複数の実行中のイニシアチブ: 人間に再開するものを尋ねます。 推測しないでください — 誤った選択はセッションを無駄にします。
• アーティファクトとコードベースが矛盾している: コードベースを信頼します。 アーティファクトを現実と一致するよう更新します。 スペックのステータスを更新してください。
• 複数のイニシアチブに実行中のアーティファクトがある: 人間に再開するものを尋ねます。推測しないでください — 誤った選択はセッションを無駄にします。