overleaf-sync

Overleaf 同期

ローカルの論文ディレクトリと Overleaf プロジェクトを連携し、次のことができるようにします。

• あなたは Overleaf の Web UI で編集を続けられます（または共同作業者に編集権限を共有できます）。
• ARISは変更を読み取り、監査（/paper-claim-audit、/citation-audit、/auto-paper-improvement-loop）を実行し、修正を反映できます。

これは公式のOverleaf Git ブリッジ（Premium 機能）を使用します。エージェントがあなたの認証トークンを見ることはありません。認証は一度だけ手動で行うため、トークンはチャット履歴や .git/config ではなく、macOS キーチェーンに保存されます。

このスキルを使う場面

• Overleaf を編集環境として使い（共同作業に適しており、チームと共有できます）、それでも ARIS のパイプラインをローカルで実行したい場合
• 既存のローカルの ARIS 論文を Overleaf にプッシュし、共著者に編集してもらいたい場合
• 共同作業者が Overleaf で変更を加えたため、ローカル作業を続ける前にプルして差分を確認したい場合

定数

• CLONE_DIR_DEFAULT = paper-overleaf（既存の paper/ と同じ階層に配置し、paper/ の中には置きません）
• CREDENTIAL_HELPER = osxkeychain（macOS）／manager（Windows）／cache（Linux のフォールバック）
• TOKEN_HANDLING = **トークンをディスク、環境変数、チャットに決して書き込まないでください。**ユーザーがターミナルの認証情報プロンプトに一度だけ貼り付けると、それ以降は OS のキーチェーンに保存されます。

アーキテクチャ

┌─────────────────┐       git pull/push      ┌─────────────────┐
│  Local paper/   │ ◄─── rsync ──── ►       │ paper-overleaf/ │ ◄──► Overleaf web
│  (ARIS audits)  │                          │ (git bridge)    │     (collaborators)
└─────────────────┘                          └─────────────────┘

paper-overleaf/ ディレクトリは、Overleaf プロジェクトの Git クローンです。paper/ ディレクトリは、ARIS スキルを実行する作業用コピーです。これらは rsync を介して同期されます。

単一の信頼できる情報源のルール：常に、編集時の正として扱うのはいずれか一方だけにしてください。pull または push で明示的に方向を切り替え、予期しない差異を見つけるために、どちらかを実行する前に status チェックを行ってください。

サブコマンド

setup <project-id> — 初回のみ

新しい Overleaf プロジェクトのブリッジを設定します。**ユーザー自身のターミナルで実行してください。エージェント経由では決して実行しないでください。**このスキルには、セキュリティを強化したセットアップスクリプトが付属しており、次の処理を行います。

1. stdin/stdout が TTY でない場合は実行を拒否します（エージェントの実行環境内では動作しません）。
2. 非表示のプロンプトからトークンを読み取ります（チャット履歴にもシェル履歴にも残りません）。
3. クローン後、リモート URL からトークンを直ちに削除します。
4. OS のキーチェーンに認証情報を事前登録するため、以降のエージェント操作では認証が不要になります。
5. paper-overleaf/.git/hooks/ に pre-commit フックを自動インストールします。このフックはトークンのパターン olp_[A-Za-z0-9]{20,} を含む blob のコミットを拒否します。これは行動規範ではなく、技術的に強制されるブロックです。

エージェントがここで行うのは、ユーザー向けの指示を表示することだけです。

Run this in your own terminal (NOT through me):

    bash <ARIS_REPO>/tools/overleaf_setup.sh <project-id-or-url>

When it finishes, tell me "setup done" and I'll verify.

ユーザーから「setup done」と報告されたら、エージェントはトークンを扱わずに確認します。

cd paper-overleaf
git remote -v                    # must show URL WITHOUT token
git config --get credential.helper
git fetch && git log --oneline -3   # must succeed without prompting
ls .git/hooks/pre-commit         # must exist
bash <ARIS_REPO>/tools/overleaf_audit.sh .   # must report "Audit clean"

paper-overleaf/ は存在するものの空の場合（新しい Overleaf プロジェクトの場合）、その後、エージェントはローカルの paper/ をそこにミラーリングします（push ワークフローを参照）。

pull — 各編集セッションの前

cd paper-overleaf && git pull --ff-only

# Show what changed since last pull
LAST=$(git rev-parse HEAD@{1})
git diff --stat $LAST..HEAD
git diff $LAST..HEAD -- 'sec/*.tex'        # detailed view for prose changes

**差分プロトコル — ローカルの paper/ に無条件でマージしないでください。**Overleaf での編集には、次のようなものが頻繁に含まれます。

• 書きかけの文（共同作業者が考えをまとめる途中で保存をクリックしたもの）
• 正式な参考資料にはない誤字（Large が Lrage になっているなど）
• 意図的なものか、一時退避のためのものか判断できないコメントアウトされたブロック
• /paper-claim-audit を再実行すべき数値の変更
• /citation-audit を再実行すべき引用キーの変更

差分の各ハンクについて、次のいずれかを判断してください。

ハンクの内容	対応
適切な編集上の改善	paper/ に同期します。監査は不要です
数値／主張の変更	同期後、/paper-claim-audit を再実行します
新しい \cite{...}	同期後、/citation-audit を再実行します
書きかけの文／明らかな誤字	ユーザーに伝え、自動同期はしません
新しいセクション／構成変更	中止し、同期する前にユーザーに確認します

各ハンクについて判断した後：

# Sync only the files the user approved into local paper/
rsync -av paper-overleaf/sec/0.abstract.tex paper/sec/0.abstract.tex
# (or use Edit tool for surgical changes that skip half-sentences)

push — ローカル編集後

ARIS スキルで paper/ を編集した後、Overleaf の共同作業者にも変更を反映したい場合に使用します。

# 1. Always pull first to surface remote drift
cd paper-overleaf && git pull --ff-only

# 2. If pull was a no-op, sync local paper → paper-overleaf
rsync -av --delete \
  --exclude='.git' --exclude='.DS_Store' \
  --exclude='*.aux' --exclude='*.log' --exclude='*.bbl' --exclude='*.blg' \
  --exclude='*.fls' --exclude='*.fdb_latexmk' --exclude='*.out' \
  --exclude='*.synctex.gz' --exclude='*.toc' \
  paper/ paper-overleaf/

# 3. Show what would be pushed
git status --short
git diff --stat

# 4. Commit + push
git add -A
git commit -m "<descriptive message — what ARIS changed and why>"
git push

コミットメッセージのルール：変更を作成した ARIS スキルを含め、Overleaf の共同作業者が変更元を把握できるようにします。例：

• paper-write: regenerated sec/3.assurance after audit cascade refactor
• citation-audit: fix 14 metadata entries (madaan2023, lee2024, ...)
• paper-claim-audit: correct sec/5 numbers vs results/run_2026_04_19.json

確認ゲート：push は共有リソースに書き込みます。git push を実行する前に、必ず git diff --stat と（文章の変更の場合は）代表的な差分をユーザーに提示してください。ユーザーが事前に auto: true と指定していない限り、明示的な確認を待ってください。

status — 診断

cd paper-overleaf
git fetch
echo "=== Remote-vs-local divergence ==="
git log --oneline HEAD..origin/master    # remote ahead
git log --oneline origin/master..HEAD    # local ahead
echo "=== paper/ vs paper-overleaf/ divergence ==="
diff -rq --brief paper/ paper-overleaf/ 2>/dev/null \
  | grep -v "Only in paper/.*\.\(aux\|log\|out\|fls\|fdb_latexmk\|bbl\|blg\|synctex\|toc\)" \
  | grep -v "Only in paper-overleaf/.git" \
  | grep -v "DS_Store"

3 方向の状態評価：

リモートの方が先行？	paper/ と paper-overleaf/ に差異がある？	意味	推奨する操作
いいえ	いいえ	クリーン	対応不要
はい	いいえ	Overleaf に新しい編集があります	pull を実行し、その後 status を再実行
いいえ	はい	ローカルの ARIS による編集が未同期です	push を実行
はい	はい	分岐しています — マージが必要です	停止してユーザーに状況を伝え、自動で解決しないでください

競合の解決

真の分岐が原因で git pull --ff-only が失敗した場合：

1. git pull（自動マージされます）を実行しないでください。
2. git reset --hard や git push --force（破壊的な操作）を実行しないでください。
3. git log origin/master ^HEAD（Overleaf 側のコミット）と git log HEAD ^origin/master（ローカルの ARIS によるコミット）をユーザーに提示します。
4. ファイルごとにどちらの変更を採用するかユーザーに尋ねるか、Overleaf で手動マージしてから再度 pull するよう依頼します。

トークンのセキュリティ — 多層防御

行動ルールだけでは不十分です。このスキルを読む次のエージェントがルールを忘れる可能性があるためです。そのため、このスキルでは、エージェントが誤った動作をしても機能する技術的な保護策を採用しています。

層	保護策	適用箇所
1. セットアップ	overleaf_setup.sh は、対話型 TTY がない場合（エージェントにはありません）は実行を拒否します	tools/overleaf_setup.sh
2. 入力	トークンは read -s で読み取られます（非表示のプロンプト、シェルの履歴に残らず、チャットにも入りません）	tools/overleaf_setup.sh
3. 保存	トークンは git credential approve を介して OS のキーチェーンに直接保存され、リモート URL からトークンが除去されます	tools/overleaf_setup.sh
4. コミット	paper-overleaf/.git/hooks/pre-commit は、ステージされた内容を olp_[A-Za-z0-9]{20,} に一致する文字列がないか検索し、見つかった場合は中止します	セットアップスクリプトによって自動インストール
5. 監査	overleaf_audit.sh は、作業ツリー、リモート URL、git の履歴、認証情報ファイルをスキャンします	tools/overleaf_audit.sh

行動ルール（引き続き適用されますが、優先度は低めです）：

• ユーザーにトークンをチャットに貼り付けるよう決して求めないでください。ユーザーが貼り付けた場合は、(a) 受け取ったことを伝え、(b) https://www.overleaf.com/user/settings でトークンを失効させるよう伝え、(c) キーチェーンがすでに設定済みの場合はキーチェーンから復旧します。
• リポジトリにコミットされるファイル（.env、.netrc、tools/*.sh など）にトークンを決して書き込まないでください。
• git remote -v の URL にトークンを決して含めないでください。クローン後にトークンを除去します。
• push/pull で 401 Unauthorized が返された場合は、キーチェーンのエントリが期限切れになったため、overleaf_setup.sh を再実行するようユーザーに伝えてください。新しいトークンを求めないでください。

相互排他ルール

双方向同期で最も大きな問題の原因は、両方で同時に編集することです。

• ユーザーが Overleaf で編集中の場合、ユーザーが /overleaf-sync pull を実行するまで、ARIS スキルは paper/ へのアクセスを読み取り専用にしてください。
• ARIS が /auto-paper-improvement-loop または /paper-write の実行中の場合、ループが完了して /overleaf-sync push が実行されるまで、ユーザーは Overleaf での編集を一時停止してください。

判断に迷った場合は、まず status を実行してください。

出力仕様

• リポジトリのルートにある paper-overleaf/ ディレクトリ。Overleaf プロジェクトを git clone したもので、origin URL にトークンは含まれません
• paper/ ディレクトリの役割は変更しません。引き続き ARIS の作業コピーとして使用します
• 各 pull／push 操作では、ユーザーに1行で概要を伝えます（pull／push したコミット、ファイル数、Overleaf プロジェクトの URL へのリンク）

関連項目

• /paper-claim-audit — 数値に関わる Overleaf の変更を pull した後に再実行します
• /citation-audit — \cite{...} の追加・編集を伴う Overleaf の変更を pull した後に再実行します
• /paper-compile — ローカルでの LaTeX ビルドです。Overleaf ではクラウド上で個別にコンパイルされます
• Overleaf の Git ブリッジに関するドキュメント：https://www.overleaf.com/learn/how-to/Using_Git_and_GitHub