Wakeup

---
name: wakeup
description: claude.ai セッション開始時に長期記憶をロードし、人格ディレクティブを適用する汎用エンジン。公開リポの記憶を Read token で SHA 固定取得し、必要時に Private リポを Read PAT で参照、記憶の書き戻しは PR フローで行う。リポ名・ファイル・commit identity・人格方針はすべて config から注入する。
---

# wakeup - セッション開始エンジン

claude.ai 環境のセッション開始時に、設定（config）に従って長期記憶をロードし、人格ロード方針を適用するスキルです。

> **このスキルは特定の人格・リポジトリに依存しません。** リポ名・ファイル・commit identity・人格ディレクティブはすべて config（`examples/<persona>.config.json`）と起動ディレクティブ md の値として与えます。下記の `<owner>` `<name>` `<path>` 等はプレースホルダです。

## 目次
- [前提](#前提)
- [ディレクトリ構成](#ディレクトリ構成claudeai-展開後)
- [デプロイ（zip 化の直前）](#デプロイzip-化の直前)
- [実装時の注意事項](#実装時の注意事項)
- [実行フロー](#実行フロー)
- [Private 参照（on-demand）](#private-参照on-demand)
- [記憶の書き戻し（on-demand）](#記憶の書き戻しon-demand)
- [セキュリティ規律](#セキュリティ規律)

---

## 前提
- **config**（`examples/` のサンプルを見本に実値化し、**`materialize` でルート直下へ `wakeup.config.json` として配置**）に `public_repo` / `load_files` / `commit_identity` / `directive_path`（任意で `private_repo`）を定義。配置は下記 [ディレクトリ構成](#ディレクトリ構成claudeai-展開後) と [デプロイ](#デプロイzip-化の直前) を参照。
- **起動ディレクティブ**（人格ロード方針）は `directive_path` が指す md。
- **engine**: `scripts/interfaces/wakeup_engine.py`（標準ライブラリのみ。claude.ai の bash で自己完結し、EpisodicRAG 本体パッケージには依存しない）。

---

## ディレクトリ構成（claude.ai 展開後）

スキル zip は `/mnt/skills/user/wakeup/` に展開される。`★` は**あなたが用意して配置する**もの：

```text
/mnt/skills/user/wakeup/
├── SKILL.md                  # この仕様書
├── wakeup.config.json    ★  # 自分用 config（examples/ のサンプルを実値化。名前固定）
├── <directive>.md        ★  # 起動ディレクティブ（config の directive_path が指す任意名）
├── token.tar.gz          ★  # Read/Write PAT 同梱（.gitignore 済、zip 化前に配置）
├── examples/                 # テンプレート見本（コピー元。実行時は参照しない）
│   ├── weave.config.json     #   Weave サンプル → wakeup.config.json として実値化
│   ├── WeaveDirective.md     #   Weave サンプル → directive_path が指す名で配置
│   └── PROJECT_INSTRUCTIONS_snippet.md
└── scripts/
    └── interfaces/wakeup_engine.py
```

- **`examples/` は見本**。実値化した config は自分の staging 場所に置き、そこから **`materialize` でルート直下へ配置**する（[デプロイ](#デプロイzip-化の直前)）。directive の名前は config の `directive_path` に書く（`examples/` 内のファイルは実行時に読まない）。
- **`directive_path` は config からの相対パス** → config と同じディレクトリ（ルート直下）に directive を置く。ファイル名は任意（汎用例 `directive.md`、Weave サンプルは `WeaveDirective.md`）。
- 実行時の **config パスは固定で `/mnt/skills/user/wakeup/wakeup.config.json`**（人格名を含めない汎用名。directive 名のみ config 経由で可変）。
- config・directive・token のファイル名は SKILL.md／config と**厳密一致**させる（Linux はケースセンシティブ）。
- **1 デプロイ ＝ 1 人格**（config パスが固定名のため）。複数人格を運用する場合はスキル自体を別名で分ける。どの人格が起動するかは後述 `verify` の fingerprint で確認する。

---

## デプロイ（zip 化の直前）

★ の配置は**手でコピーしない**。人格ごとの config（実値。この repo の `examples/` ではなく**自分の staging 場所**にあるもの）と、その隣の directive を、1 コマンドで skill root に流し込む：

```bash
python scripts/interfaces/wakeup_engine.py materialize \
  --config <自分の staging>/<persona>.config.json \
  --token  <自分の staging>/token.tar.gz \
  --out    /path/to/wakeup            # zip 化するスキルディレクトリ
```

- config → `<out>/wakeup.config.json`（固定の汎用名）
- directive → **source config の `directive_path` を、source config と同じディレクトリから解決**して `<out>/<directive_path>` へ（別名・サブディレクトリ可）
- token → `<out>/<元のファイル名のまま>`（**表示された名前をそのまま curl に書く**——勝手なリネームをしないことでケース不一致を防ぐ）
- 配置後に自動で `verify` が走り、不備があれば非ゼロ終了（**半端に materialize されたスキルを作らない**——検証は全コピーの前）
- `--token` を省くと既に `<out>` にある token アーカイブがそのまま使われる（再同期用）
- **zip 化の前に開発残骸を除く**: `.coverage` / `__pycache__` / `.pytest_cache` は開発ツリーをそのまま zip すると同梱される（`materialize` は 3 点の配置のみを担い、掃除はしない）

> **手コピーの何が壊れるか**: config と directive は別々に持ち回されるため、**directive だけ新しく config は数ヶ月前**という組み合わせが生じる（`commit_identity.coauthor` が旧世代名のまま書き戻される等）。`materialize` は両者を単一 source から都度コピーするのでドリフトが構造的に起きない。
> **器の交代時に更新する config キー**: `commit_identity.coauthor`（モデル世代名を含む。記録に残るため世代交代時は必ず更新）。

---

## 実装時の注意事項
> **UIメッセージはコードブロックで囲む**（VSCode 拡張では単一改行が空白に変換されるため）。
> **token を URL・stdout・ログに出さない**（後述のセキュリティ規律を厳守）。
> **token アーカイブのファイル名はケースセンシティブ**（Linux 環境。`token.tar.gz` と `TOKEN.tar.gz` は別物——実配置と厳密に一致させること）。

---

## 実行フロー

**⚠️ 以下を TodoWrite で作成し、順番に実行すること**

```
1. デプロイ検証       - verify で config/directive/token の実在を確認（FAIL なら起動を中断）
2. 記憶ロード         - Read token で SHA 取得＋認証付き raw を取得（load_repo＝private_repo 優先）
3. ディレクティブ適用 - directive_path の md を読み、人格方針を反映
```

| Step | 内容 | 処理 |
|------|------|------|
| 1 | デプロイ検証 | `wakeup_engine.py verify` が config（＝`/mnt/skills/user/wakeup/wakeup.config.json`）を解釈し、directive と token の実在も確認 |
| 2 | 記憶ロード | load_repo（private_repo 優先）の最新 SHA 取得 → raw URL を認証付き curl（Read token） |
| 3 | ディレクティブ適用 | config と同ディレクトリの `directive_path`（＝ルート直下の md）を読む |

### Step 1: デプロイ検証（verify）
Step 3 は md の Read なので、**directive が未配置でも黙って通ってしまう**（fail-open）。起動前に検証して落とす：

```bash
python /mnt/skills/user/wakeup/scripts/interfaces/wakeup_engine.py verify
```

```text
config    : ok  (load_repo=<owner>/<name>@main (private), load_files=3 (required 2 / optional 1))
directive  : ok  (<directive_path>, 826 bytes)
token      : ok  (token.tar.gz readable)
```

- **FAIL が出たら記憶ロードへ進まない**（不備を報告し、`materialize` で再配置する）
- `config` 行の fingerprint は「**今どの人格を起こそうとしているか**」の確認点（別人格の config を上げたままの事故を検知）
- token は **可読性のみ**を検査（中身は一切出力されない）。`--root` 省略時はこのスキル自身のルートを見る

### Step 2: 記憶ロード（要 Read token）
> **なぜトークンが要るか**: claude.ai は共有 IP のため未認証 `api.github.com` の 60 req/h がすぐ枯渇し SHA を取れない。かつ raw の **`main` 参照は CDN キャッシュが長く最新が取れない**ため、SHA 固定での取得が必須。→ SHA 取得（API）に認証が要る。公開・非公開いずれのリポでも Read token を使う（起動時ロード対象 load_files は load_repo＝private_repo があればそこ、なければ public_repo から取得）。

Read token は **Private リポ Contents:Read ＋ Public repositories read-only** を含む fine-grained PAT。最新 SHA を取得し、SHA 固定の raw を取得する（いずれも Authorization ヘッダ。token は単一 bash 呼び出しで使い切る）：
```bash
TOKEN=$(python /mnt/skills/user/wakeup/scripts/interfaces/wakeup_engine.py extract-token --archive /mnt/skills/user/wakeup/token.tar.gz) \
  && SHA=$(curl -s --fail -H "Authorization: Bearer $TOKEN" "https://api.github.com/repos/<load_repo-owner>/<load_repo-name>/git/refs/heads/<branch>" | grep -o '"sha": *"[^"]*"' | head -1 | cut -d'"' -f4) \
  && python /mnt/skills/user/wakeup/scripts/interfaces/wakeup_engine.py resolve-urls --config /mnt/skills/user/wakeup/wakeup.config.json --sha "$SHA" \
  && curl -s --fail -H "Authorization: Bearer $TOKEN" "https://raw.githubusercontent.com/<load_repo-owner>/<load_repo-name>/$SHA/<path>"
```

### Step 2 の迂回: GitHub gate のある環境（git transport）
クラウドセッション系のサンドボックス（Cowork、Claude Code on the web）には、egress proxy が GitHub だけを特別扱いする gate がある（anthropics/claude-code #84581 / #86828）。gate 下では `api.github.com` が**公開リポ・認証付きでも一律 403** になり、**自前の `Authorization` ヘッダは proxy に握り潰される**ので、上の curl は SHA 取得の時点で必ず落ちる。応答本文に次のいずれかが見えたら gate：

```text
GitHub access to this repository is not enabled for this session. Use add_repo to request access.
This GitHub API path is not available: sessions are bound to their configured repositories.
```

- **この署名を見たら curl を叩き直さない**（token の不備ではないので、何度やっても 403）。`add_repo` というツールは存在しないので探さない。`gh` も同じ API を叩くので代替にならない
- gate が塞ぐのは **`api.github.com` だけ**。`raw.githubusercontent.com` は認証ヘッダごと素通しする（実測 2026-09-19）。だから差し替えるのは **SHA 取得だけ**——`git ls-remote` で取り、本文は上と同じ SHA 固定の raw curl で読む：

```bash
WAKEUP_TOKEN=$(python /mnt/skills/user/wakeup/scripts/interfaces/wakeup_engine.py extract-token --archive /mnt/skills/user/wakeup/token.tar.gz) && export WAKEUP_TOKEN   && wgit() { git -c credential.helper= -c credential.helper='!f() { echo username=x-access-token; echo "password=$WAKEUP_TOKEN"; }; f' "$@"; }   && REPO="https://github.com/<load_repo-owner>/<load_repo-name>.git"   && SHA=$(wgit ls-remote "$REPO" "refs/heads/<branch>" | cut -f1) && [ -n "$SHA" ]   && curl -s --fail -H "Authorization: Bearer $WAKEUP_TOKEN" "https://raw.githubusercontent.com/<load_repo-owner>/<load_repo-name>/$SHA/<path>"
```

- token は **環境変数 → credential helper** で渡す（URL に載せない規律は git 経路でも同じ。remote URL の userinfo に token を書かない）。env は単一 bash 呼び出しで消える。helper 経由の token が proxy を通ることは実測済み
- **`[ -n "$SHA" ]` を外さない**: SHA が空だと raw の URL が崩れ、proxy の redirect 応答が「raw が落ちた」ように見える
- `load_files` の各 `<path>` を読む。`required` が読めなければ起動失敗、`optional` は欠けても続行
- GitHub App の installation token（`ghs_` 接頭辞）は git transport でも弾かれる報告があるので使わない

**raw も落ちたら**（raw が通るのは今の proxy の挙動で、保証ではない）、本文も git transport で取る。上の `wgit`／`REPO` 定義に続けて：

```bash
  rm -rf /tmp/wakeup-mem   && wgit clone -q --depth 1 --branch "<branch>" --filter=blob:none --no-checkout "$REPO" /tmp/wakeup-mem   && wgit -C /tmp/wakeup-mem show "HEAD:<path>"
```

- `--filter=blob:none --no-checkout` は必須（記憶リポは大きい。blob は `git show` した分だけ lazy fetch される——そのため `git show` にも `wgit` を使う）。remote URL に token を載せていないので `.git/config` には残らない

---

## Private 参照（on-demand）
Private リポの記憶（個別エントリ・Wiki 等）を対話中に引く時**だけ**実行します。token は**スキル同梱の tar.gz**（`/mnt/skills/user/wakeup/token.tar.gz`）から取り出し、**単一 bash 呼び出しで使い切る**（常駐させない）：

```bash
TOKEN=$(python /mnt/skills/user/wakeup/scripts/interfaces/wakeup_engine.py extract-token --archive /mnt/skills/user/wakeup/token.tar.gz) && curl -s --fail -H "Authorization: Bearer $TOKEN" "https://api.github.com/repos/<owner>/<private-name>/contents/<path>"
```

- token は fine-grained PAT（**admin でない write collaborator** が発行。記憶ロード／Private 参照／書き戻しを 1 本で兼用できる）。push 権限を持つが、**`main` は branch protection ＋ PR 承認で守られる**ため、漏洩しても正本は侵せない——**インテグリティは token のスコープ層でなく、ブランチ保護層に置く**設計。
- `$(...)` で stdout をキャプチャするため、token はツール出力に残りません。
- 失敗時も engine は token を漏らしません（マスク済み・非ゼロ終了）。
- **GitHub gate 下では `/contents/` も API なので 403**。[Step 2 の迂回](#step-2-の迂回-github-gate-のある環境git-transport) と同じ形で、`git ls-remote` の SHA に固定した raw を叩く。ディレクトリの一覧が要る時だけ clone して `wgit -C /tmp/wakeup-mem ls-tree --name-only HEAD <dir>/`。env も `wgit` も bash 呼び出しごとに消えるので、毎回 token の抽出から書く。

---

## 記憶の書き戻し（on-demand）
記憶（作業ログ・短期メモ等）を更新する時。**default ブランチへは直接 push せず**、`claude/*` ブランチ → PR → 人間がマージします：

```bash
git config user.name "<commit_identity.author_name>"
git config user.email "<commit_identity.author_email>"   # GitHub noreply 形式
git checkout -b claude/<topic>
# ... ファイルを更新 ...
git add <files>
git commit -m "<message>

Co-authored-by: <commit_identity.coauthor>"
git push origin claude/<topic>
gh pr create --base <branch> --head claude/<topic> --title "<title>"
```

- **Write 権限の PAT は admin でないアカウント**（write collaborator）で発行すること。admin のトークンはブランチ保護を bypass してしまう。
- 人格核（Identity 系ファイル）への書き戻しは特に PR レビューを必須とする。
- **GitHub gate 下では書き戻せない**: セッションの sources に入っていないリポへの push は、有効な PAT があっても git proxy が拒否する（`is not in this session's authorized repository set`）。`gh` も無い。回避策は無いので、差分を対話に出して人間に渡す。
- リポをセッションに**アタッチして**書く場合、push の主体は同梱 PAT ではなく **proxy が注入するセッション所有者の資格情報**になる。所有者がリポ admin なら、上の「admin でない write collaborator」の前提（＝ブランチ保護が効く）が崩れるので、`claude/*` ブランチ ＋ PR の規律を手順側で守ること。

---

## セキュリティ規律
- **記憶ロード**: Read token で SHA 取得（API レート回避）＋ SHA 固定 raw（CDN キャッシュ回避）。claude.ai 共有 IP では未認証が枯渇するため、公開リポでも認証する。
- **全 HTTP**: token は **Authorization ヘッダ**のみ（URL には絶対に載せない）、`curl -s --fail` を用いる。
- **git transport**（gate 迂回時）: token は環境変数 → credential helper のみ（remote URL に載せない。`.git/config` に残る）。
- token は `$(...)` で受け、stdout・ログに出さない。
- **default ブランチへの直接 push は禁止**（`claude/*` ブランチ ＋ PR）。
- token は公開リポに含めない（`.gitignore`）。token は **tar.gz でスキル同梱**（プロジェクトナレッジは zip 非対応・スキル zip はネスト zip 不可のため。バイナリゆえコンテキストに自動展開されない）。engine は tar.gz/tgz/tar/gz/zip を読める。難読化は補助で、本質防御は **fine-grained PAT の権限最小化**。

---
**EpisodicRAG** by Weave | [GitHub](https://github.com/Bizuayeu/Plugins-Weave)