scrolls-update

docs/.scrolls/ の更新

docs/.scrolls/ が役立つ状態を保つには、実際の状況を反映している必要があります。このスキルでは、各ファイルに対して STARTER.md ですでに定められている更新ルールを適用します。新しい規約を作ることはありません。毎回すべてのファイルに手を加えるのではなく、実際に何かがあったファイルだけを、そのファイル独自の規約に従って正確に更新することが目的です（上書き、追記、または連動して追加・削除）。

また、これらのファイルが存在する前にセットアップされたプロジェクト向けに、SCROLLS.md、CLAUDE.md、AGENTS.md を冪等に補完します。これは毎回のセッションで実行するコマンドなので、1 回限りの /scrolls-setup のように一度だけ実行するのではなく、このギャップを自動的に埋めます。ステップ 2 を参照してください。

クロスプラットフォーム

同梱スクリプト 1 つ（ステップ 4）には 2 つの形式があります。session_diff.sh（bash — macOS、Linux、または Git Bash/WSL を使用する Windows）と、session_diff.ps1（PowerShell 7 以降 — Windows、または pwsh がインストールされた macOS/Linux）です。このスキルのその他の内容（フラグ、BASE_DIR の解決、scrolls フォルダーの場所の特定）は、すべてそのまま実行する平文の手順です。どの場合も git のみを呼び出し、実行中のシェルにかかわらず同じように動作するため、シェルごとの別バージョンは必要ありません。実際に利用できるスクリプトを選んでください。まず bash --version を試し、成功した場合は .sh スクリプトを使います。それ以外の場合は pwsh 経由で .ps1 スクリプトを使ってください（推奨。不足している場合は https://aka.ms/powershell からインストールしてください）。pwsh が本当に利用できない場合に限り、Windows に組み込みの Windows PowerShell powershell.exe を使います。これは古いバージョンではテストされていません。作成時および検証時には pwsh を使用しました。

オプション

これらのオプションは呼び出しテキストから、順不同で読み取ってください。実際の argv パーサーはないため、平文の中から自分で取り出してください。

• -p <path> / --path=<path> / --path <path> — 検索するカスタムの docs フォルダーです。絶対パスが指定されていない場合は、現在の作業ディレクトリからの相対パスになります。
• -t / --reporoot — 実際にどのサブディレクトリから呼び出したかにかかわらず、git リポジトリのトップレベル（$(git rev-parse --show-toplevel)）を基準に検索します。現在のディレクトリが git リポジトリ内にない場合は、明確なメッセージを表示して失敗します。
• -l / --local — 明示的に現在の作業ディレクトリを検索します。-p／-t／-l のいずれも指定しない場合、デフォルトでも同じ動作をします。このフラグは、たとえば以下の不一致チェックを省略するためなど、意図的にその場所を指定することを表すものです。
• -r / --recurse — scrolls フォルダーが明確な既定の場所（BASE_DIR/docs/.scrolls または BASE_DIR/docs/scrolls）にない場合、諦めずに BASE_DIR の下を再帰的に検索します。デフォルトでは無効です。grep／cp／rm などのツールにおける -r の一般的な意味に合わせています。

ここに -u／--unhide オプションはありません。このスキルは、どちらかを選ぶのではなく、すでに存在する scrolls フォルダーを特定します（ステップ 1 を参照）。-p、-t、-l はいずれも同じ質問（「docs フォルダーはどこか？」）に答える別々の方法です。最大 1 つだけ指定してください。複数指定された場合は、どれを意図したのか確認してください。-r は独立しており、これらのいずれかと自由に組み合わせられます。何も指定しない場合も同様です。

手順

1. BASE_DIR を解決してから、2つの名前を試してスクロールを探します

BASE_DIR を計算します。

• -t／--reporoot が指定されている場合：BASE_DIR = $(git rev-parse --show-toplevel)。これが失敗した場合（Git リポジトリ内ではない場合）は、そこで処理を止めてユーザーに伝え、代わりに --path を使うよう提案します。
• -l／--local が指定されている場合：BASE_DIR = $(pwd)。
• 何も指定されていない場合（一般的なケース）：BASE_DIR = $(pwd)。ただし、まず現在のディレクトリが Git リポジトリ内にある場合は、git rev-parse --show-toplevel を実行して $(pwd) と比較します。同じである場合、または Git リポジトリではない場合は、通常どおり cwd を使って処理を進めます。異なる場合は、検索を始める前にそのことを伝えます。ここから実行すると $(pwd)/docs の下だけが検索され、リポジトリのルート（<repo-root>）にあるスクロールフォルダーは完全に見つからなくなります（単にスキップされるのではなく、プロジェクトが未設定のように見えてしまいます）。それでよいか確認し、特に希望がなければ cwd で進めます（このスキルで文書化されている既定の動作です）。

次に、-p が指定されている場合は --path の値を、そうでない場合は ${BASE_DIR}/docs を DOCS_BASE とします。その下にあるスクロールフォルダーは、.scrolls（非表示。/scrolls-setup の既定値）か scrolls（/scrolls-unhide の実行後、またはセットアップ時に --unhide を指定した場合）のいずれかの名前です。まず DOCS_BASE/.scrolls を確認し、次に DOCS_BASE/scrolls を確認します。存在する方を、このスキルの以降の処理では SCROLLS_PATH とします。

いずれもその場所に存在しない場合：

• -r／--recurse が指定されている場合：代わりに BASE_DIR の下を再帰的に検索します。検索する階層数には上限を設け、/scrolls-hide／/scrolls-unhide が除外するものと同じ、負荷の大きいディレクトリやベンダーディレクトリ（node_modules、.git、vendor、dist、build、.venv、venv、__pycache__、target、.next、.cache）を検索対象から除外します。STARTER.md を含む .scrolls または scrolls という名前のディレクトリを探します。見つかったものが1つだけなら、それを SCROLLS_PATH とします。複数見つかった場合（この BASE_DIR の下に複数の独立したスクロール設定があるモノレポの場合）は、それらを一覧表示して、このセッションの更新対象をユーザーに尋ねます。推測したり、複数箇所を更新したりしないでください。セッションのストーリーは、たまたま近くにネストされているすべてのプロジェクトではなく、特定のプロジェクトに属するものです。
• -r が指定されていない場合、または上記の再帰検索でも何も見つからない場合：ここでは作成しないでください。このプロジェクト（またはこのパス）はまだ設定されていないことをユーザーに伝え、/scrolls-setup を案内します。また、BASE_DIR がリポジトリのルートではなく cwd（既定の動作または -l によるもの）に解決されている場合は、試せる手段として -t／--reporoot に言及します。さらに、まだ使用していない場合は -r／--recurse にも触れ、スクロールが想定される場所以外にある可能性に備えます。

何らかの理由で、DOCS_BASE に .scrolls と scrolls の両方が存在する場合は、そこで処理を止め、どちらが現行のものかユーザーに尋ねます。これは、このスキルが暗黙のうちに解消すべきではない不整合な状態です。

2. このプロジェクトが古い場合は、SCROLLS.md、CLAUDE.md、AGENTS.md を補完する

2.0.0 より前の /scrolls-setup でセットアップされたプロジェクトには、SCROLLS.md や AGENTS.md がなく、CLAUDE.md がある場合も、SCROLLS.md を参照せずにスクロールのパスを直接埋め込んでいることがあります。毎回のセッションで実際に実行されるのは、一度限りの /scrolls-setup ではなく /scrolls-update です。そのため、このタイミングでプロジェクトを自動的に最新の状態に追いつかせます。

これはファイルごとに一度だけ行う、冪等な補完です。以下の3ファイルには、/scrolls-setup のステップ4と同じく、「存在しなければ作成／すでに参照していなければ挿入／すでに正しければ変更しない」という処理を適用するため、/scrolls-update を実行するたびに安全に実行できます。これらのファイルにすでにある内容を上書きしたり、順序を入れ替えたりすることは決してありません。 ここでは、この実行で解決した SCROLLS_PATH の場所だけを対象にします（-r を指定した場合も同様です）。これは、前述のステップ1にある「推測しない、複数箇所に手を加えない」というルールに沿ったものです。

この3ファイルの配置場所は、すでに /scrolls-hide／/scrolls-unhide で行っている方法で算出します（構成上、CLAUDE.md は常に docs フォルダーと直接同じ階層にあります）。

PTR_DIR    = dirname(DOCS_BASE)                          # e.g. "packages/api" for DOCS_BASE "packages/api/docs"
DOCS_NAME  = basename(DOCS_BASE)                          # normally "docs"
SCROLLS_DIR_NAME = basename(SCROLLS_PATH)                 # ".scrolls" or "scrolls", whichever was found
SHORT_SCROLLS_PATH = "${DOCS_NAME}/${SCROLLS_DIR_NAME}"    # e.g. "docs/.scrolls" — always correct relative to PTR_DIR

3つの共通ポインターテンプレートは、/scrolls-setup 自身の assets/templates/ という一か所だけに配置されています。ここでは複製せず、その場所から読み込みます。これにより、今後テンプレートの内容を変更する際に、2つのスキルを同期して編集する必要がありません。

• SCROLLS.md：<scrolls-setup-skill-dir>/assets/templates/SCROLLS_MD_BLOCK.md を読み込み、{{SCROLLS_PATH}} を SHORT_SCROLLS_PATH に置き換えます。${PTR_DIR}/SCROLLS.md が存在しない場合は作成します。存在するものの、SCROLLS_PATH/STARTER.md を（短縮形でもフルパスでも）まだ参照していない場合は、空行で区切ってブロックをファイルの上部付近に挿入します。ファイルがトップレベルの見出しで始まっている場合は、見出しレベルをファイルの構成に合わせます。すでに参照している場合は変更しません。
• CLAUDE.md：<scrolls-setup-skill-dir>/assets/templates/CLAUDE_MD_BLOCK.md をそのまま読み込みます。これは置換不要の固定2行ポインターです。${PTR_DIR}/CLAUDE.md が存在しない場合は、そのブロックだけを内容として作成します。存在するものの、まだ SCROLLS.md を参照していない場合は、空行で前後の内容と区切って、ファイルの上部付近にブロックを挿入します（「まずこれを読む」は最初に読まれなければ機能しないため、ほかの指示より前に配置します）。ファイル分割が導入される前から SCROLLS_PATH/STARTER.md を直接参照している場合も同様です。これは実際によくあるケースです（/scrolls-setup の 1.2.0 より前のバージョンでセットアップされたプロジェクト）。まさにこのケースを補完するため、既存の記述にかかわらずスタブを挿入し、CLAUDE.md が必ず SCROLLS.md を参照するようにします。これは追加のみの処理です。すでにある内容を削除したり書き換えたりすることは決してありません。その結果、古い直接参照と新しいスタブが同じファイルに残る場合もあります。すでに SCROLLS.md を参照している場合は変更しません。
• AGENTS.md：<scrolls-setup-skill-dir>/assets/templates/AGENTS_MD_BLOCK.md をそのまま読み込みます。CLAUDE.md を参照する形で、同じ3通りの処理を行います。

ステップ7の報告では、スクロールファイルとあわせて、この方法で3ファイルのいずれかを作成または更新したかどうかも記載します。

3. STARTER.md を信頼できるマップとして読む

/scrolls-setup にある最小構成の6ファイルが、今もすべてだと思い込まないでください。STARTER.md には、プロジェクトの成長に伴って、アーキテクチャ決定、セキュリティレビュー、サブシステムの詳細分析などの追加の scrolls が増え、それぞれに固有の読み取り／更新ルールがあると明記されています。現在の STARTER.md を最後まで読み、どのファイルが存在し、それぞれをどう更新するかについては、そこに記載された番号付きリストと「When to update」セクションを信頼できる情報源として使ってください。あるファイルの更新方法が以下の一般ルールと異なる場合（たとえば、このリポジトリ自身の SECURITY_ANALYSIS.md のように、追記専用の日付付きログで、既存箇所を編集してはならない場合）は、一般ルールよりもそのファイル固有のルールに従ってください。

4. このセッションで実際に起きたことを確認する

会話のコンテキストが第一の情報源です。あなたはその場にいました。ただし、それだけに頼らないでください。特に、コンテキストが圧縮されている場合、セッションを再開した場合、あるいはこの会話が始まる前に行われた作業について scrolls の更新を求められた場合は注意してください。同梱スクリプトを実行して git と照合します。<skill-dir>/scripts/ にある2つのうち、現在の環境に合う方を選んでください（「Cross-platform」を参照）。

bash <skill-dir>/scripts/session_diff.sh SCROLLS_PATH
pwsh <skill-dir>/scripts/session_diff.ps1 -ScrollsDir SCROLLS_PATH

このスクリプトは、未コミットの変更、docs/.scrolls/ が最後に変更されてからのコミット、変更されたファイルの統計概要を表示します。これで、会話の記憶から抜け落ちたことを確認できます。完全な差分をコンテキストに大量に流し込む必要はありません。特定の変更について詳しく知る必要があれば、必要な範囲の git diff／git log -p を自分で確認してください。

5. 更新が必要な各ファイルを、それぞれのルールに従って更新する

コア6ファイルの一般ルール（STARTER.md より）：

• HANDOFF.md — 上書きし、追記しないでください。これはスナップショットです。現在の状態、直近に起きたこと、既知の問題／未解決の事項を記録します。このセッションで意味のある変更がなければ、内容を水増しして何もないことを記すより、そのままにしておいて構いません。
• SPEC.md — 実際にリリースされた機能（動作する状態であり、着手しただけではないもの）についてのみ、セクションを追記します。実装方法ではなく、ユーザーにとって何ができるかを説明してください。
• GAP_ANALYSIS.md + GAP_CONTEXT.md — この2つは常に一致させてください。ギャップを解消した場合は、GAP_ANALYSIS.md の該当行を完了扱いにするのではなく削除し、GAP_CONTEXT.md の該当エントリも削除します。新たなギャップを見つけた場合は、GAP_ANALYSIS.md に簡潔な行を追加し、その理由（意図的な見送り／見落とし／ブロッカー）を GAP_CONTEXT.md に記します。
• PLAN.md — 完了したチケットは [ ]→[x] に変更し、新たな要望で順番が変わった場合は優先順位を見直し、新たに判明した作業のチケットを追加します。
• WISDOM.md — 本当に新しい学びがあった場合に限り、適切なセクション（Constraints／Traps／Ditches／Wisdom）にエントリを追加します。実際に遭遇したバグ、再利用する価値のあるパターン、判明した厳しい制約などが該当します。このセッションで新たな学びがなければ、無理にエントリを追加しないでください。

このコアセット以外にプロジェクト固有の scrolls がある場合は、そのファイルについて STARTER.md に記載されたルールに従ってください。一般ルールと異なる記述があるファイルに、上記の一般ルールを当てはめないでください。

6. 事実を捏造したり、過大に主張したりしない

何かがリリース済みなのか、着手しただけなのか判断できない場合は、未リリースとして扱います。完成した SPEC.md のエントリとして記載せず、HANDOFF.md の「known issues / open threads」または PLAN.md に記録してください。本当に判断が難しい場合（たとえば、ギャップが実際に解消されたのか、回避策を講じただけなのか）は、推測せずに質問してください。これらのファイルは、今後のすべてのセッションの基盤になります。

7. 変更内容を報告する

変更した scrolls ファイルと、それぞれの変更理由を一行で列挙してください。セッション中に作業があっても、意図的に変更しなかったファイル（たとえば、リリースされた機能がないため SPEC.md に新しいエントリが不要だった場合）は、記載しなくても構いません。変更していないファイルをすべて列挙する必要はありません。SCROLLS.md／CLAUDE.md／AGENTS.md は、手順2で実際に作成または更新した場合に限り含めてください。3つともすでに正しい状態で変更がなかった場合は、他の未変更ファイルと同様に記載しなくて構いません。

開発

ディレクトリ構成、tests/ の回帰テストスイートの実行方法、バージョン管理に関する注意事項については、meta/MAINTAINERS.md を参照してください。これらはユーザーの /scrolls-update リクエストに対応する際には参照しません。リクエストへの対応中は、meta/MAINTAINERS.md や tests/ に対して操作しないでください。