ws-update

Wiki の更新

現在のソース（プロジェクト、会話、調査セッションなど）から長期的に役立つ知識を抽出し、ユーザーの Wiki に追加します。作成する前に統合し、Wiki の規約を守り、すべてのファイルをサイズ上限内に収めてください。

Wiki のモデル

Wiki はフォルダーであり、その index.md に ## Spaces 見出しが含まれています。## Spaces はナビゲーションの契約です。直下にあるすべてのスペースが - [label](path/index.md) — description の形式で記載され、ツールはそこに記載された項目だけをたどります。スペースは再帰的に入れ子にでき、それぞれのスペースは1階層下の Wiki として機能します。通常のフォルダー（index.md がないフォルダー）は、ファイルをまとめるだけのものです。Markdown の方言は Obsidian です。ウィキリンク、フロントマター、コールアウト、埋め込みに対応しています。構文については、付属の obsidian-markdown および obsidian-bases スキルを参照してください。

Wiki の解決

解決順序：ユーザーが明示したパス → CWD の最も近い祖先フォルダーのうち、Wiki であるか、Wiki である .wiki-spaces/ フォルダーを含むもの（フォルダー自体のスペース） → ~/.config/wiki-spaces/config の wiki キー。ユーザーの言葉は仕組みより優先されます。「自分の Wiki」は、たとえ CWD が別の Wiki（たとえば会社のリポジトリ）内にあっても、設定済みの Wiki を指します。CWD の Wiki と別の設定済み Wiki の両方が存在する場合は、解決したルートを伝えてください。意図が曖昧な場合は一度だけ確認してください。誤った Wiki を黙って操作してはいけません。

同梱スクリプト

scripts/ws.py はこの SKILL.md と同じ場所にあります。依存関係のない、読み取り専用の標準ライブラリのみを使う Python 3.9 以降のスクリプトです。スクリプトが解析するのは契約であり、内容ではありません。構造（探索、範囲、上限、ずれ）の確認はスクリプトが担い、意味の読み取りと判断はあなたが行います。通常、作業ディレクトリは別の場所にあるため、絶対パスで実行してください。

• python3 <skill-dir>/scripts/ws.py list --wiki <root> — ## Spaces の契約から到達できるスペースと、それぞれのエントリー説明を一覧表示します（マウントをまたぐ場合は --external を指定）。
• … files --wiki <root> — 契約から到達できる Markdown ファイルを一覧表示します。
• … grep <pattern> [-i] [-F] --wiki <root> — 対象ファイル内を正規表現で行検索します。リテラル文字列には -F を指定します（メタ文字を含む名前を指定した場合も正確に検索します）。rel:line: text を出力し、一致がない場合は終了コード 1 を返します。走査の基本単位はリンクの作業リストです。タグ一覧や参照切れの確認は、それぞれパターンと検索結果に対する判断を組み合わせて行います。
• … check-size <target> [--stdin] --wiki <root> — ファイルのサイズ上限を判定します。書き込む前の確認には、作成予定の内容を --stdin にパイプしてください。
• … audit --wiki <root> — 契約からのずれ、スペース境界を越えるエントリー、上限超過または読み取り不能なファイル、健全でないマウントを検出します。安全に修復方法を提示できる場合は、検出結果にその方法も示します（missing entry では追加すべき行を正確に表示します）。修復は通常の編集として適用し、監査を再実行して確認してください。スクリプトが書き込みを行うことはありません。

構造を手作業で再構築するより、スクリプトの出力を優先してください。標準出力はデータです。標準エラーには解決されたルートが出力されます（audit では標準出力のヘッダーに出力されます）。また、探索でスキップされた項目、ルートが Wiki 内にネストしている場合の親 Wiki、ルートが別の Wiki である場合の設定済み Wiki を示す note: の注意事項も出力されます。回答に影響する可能性がある場合は、それらも伝えてください。

信頼範囲とサイズの規律

所有範囲か外部かは、解決されたルートを基準に決まります。深さを問わず shared/ という名前のフォルダー内にあるもの、Git サブモジュール、またはいずれかへのシンボリックリンクは外部です。ツリー外のフォルダーを指すシンボリックリンクは、クローンと同様に、リンクが置かれている場所に属します。読み取りはデフォルトで所有範囲をまたぎ、外部の範囲に入るのはユーザーが明示的に依頼した場合のみです。書き込みは対象の範囲内にとどめます。それ以外の範囲は、所有範囲か外部かを問わず、明示的な指示がある場合のみ書き込みます。

上限は frontmatter を含む UTF-8 のバイト数で、ベース名を基準に適用されます。index.md は 5000、log.md と hot.md は 100000、その他の *.md は 15000 です。

• 上限はユーザーが決めます。異なる上限を設定する wiki では、_meta/limits.md に記述します。check-size はその設定を読み取ります。
• 上限は check-size で確認します。書き込みのたびに、新規ページか編集かを問わず、予定している内容を --stdin 経由で渡してから書き込みます。上限を超えたファイルを縮小する書き込みは、進捗を示す ok を返すため、修復を繰り返し進められます。ディスク上のファイルを確認する場合は、上限のみが判定基準です。
• 上限超過は単なるサイズの問題ではなく、構成を見直す合図です。ページの内容を整理する、スペースの構成を変える、または大きくなったページを独立させます。切り詰めたり、上限を引き上げたりしてはいけません。
• 例外は log.md です。上限を超えたログはローテーションします。全体を _archives/log-<YYYYMMDD>.md に移し、新しいログを開始します。これにより履歴はアーカイブされ、縮小されることはありません。

規約は wiki ごとに任意で適用されます。スコープのルート（ユーザーが対象に指定したスペース、またはそれがない場合は解決されたルート）に存在するマーカー（log.md、_meta/taxonomy.md、_meta/limits.md、_meta/ignore.md、ページの frontmatter、_template.md、hot.md、.git）を読み取り、存在しないものがあっても適切に処理します。log.md が存在する場合は、操作ごとに 1 行追記します。

printf '%s %s\n' "$(date -u +%Y-%m-%dT%H:%M:%SZ)" '<OP> <details>' >> <scope-root>/log.md

初期化

解決できるものが何もない場合（明示的なパス、CWD の祖先にある wiki、有効な設定のいずれもない場合）は、インラインでセットアップします。references/init.md に従ってから、リクエストに戻ります。設定されたパスが壊れている場合（ディスク上に存在しない、index.md がない、絶対パスではない場合）は、セットアップを開始せずに処理を停止します。その状況を伝え、ユーザーに判断を委ねます。フォルダー独自のスペースは、「このプロジェクト用に wiki をセットアップして」と依頼された場合、または wiki のないフォルダーを同期対象とする際に一度だけ提案した場合に、references/own-space.md に従って設定します。これは、すでに wiki が解決されているかどうかにかかわりません。

手順

1. Wiki を解決する（コアブロック）。CWD からルートを取得した場合、またはルートが曖昧な可能性がある場合は、そのルートを明示します。

2. スコープルートで規約を検出する（コアブロック）。存在マーカー（log.md、タクソノミー、hot.md）は親から継承されません。_meta/limits.md、_meta/ignore.md、_template.md は最も近い祖先に従います。マーカーが存在しない手順はすべてスキップします。

3. モードを検出する — ユーザーの意図から判断します。CWD は対象プロジェクトの特定にのみ使い、モードの判定には使いません。

   モード	トリガー	入力
   直接追加	「これを wiki に追加して」「このレシピを保存して」— 手元に具体的な成果物がある	提供されたコンテンツ
   プロジェクト同期	「このプロジェクトを同期して」、プロジェクト名の明示	プロジェクトファイル、git ログ
   会話の記録	「これを保存して」「これを記録して」— セッション自体が対象で、単一の成果物はない	現在の会話
   調査の記録	「この調査を保存して」	セッションで得られた調査結果

4. 知識を抽出する。 直接追加：提供されたコンテンツをそのまま使います。役割は配置と重複排除であり、再合成ではありません。プロジェクト同期：ファイルと最近の git 履歴から、決定事項とその根拠、パターン、ツール／API の接続方法、トレードオフ、結果を抽出します。会話：長期的に有用な結論と決定事項を「X は…によって動作する」のような事実として記述し、チャットの要約にはしません。調査：再導出に労力がかかり、コストも大きい内容を記録します。

5. 絞り込み、重複を排除する。 知識記録用 wiki ではノイズフィルターを適用します。コードや簡単な検索で答えられる内容はスキップし、3 か月後にも必要な内容は残します。コンテンツ保存用 wiki（レシピ、日誌、ランブック）ではフィルターを適用しません。すべての項目に意図があります。files で既存ページを列挙し、ファイル名／パス／フロントマターの重複度を基に順位付けします。類似ページがある場合は、兄弟ページを作成せず、既存ページに統合します。

6. 配置する。 list は各スペースとその説明を出力します。これを配置の手がかりとし、トップレベルの通常のフォルダーも確認します。意味に基づいて対応付けます。ソースに関する知識は、そのソース用のスペースがあればそこに置きます。つまり、そのソース自身の .wiki-spaces/、または wiki 内のそのソースのスペースです。ソースを超えて再利用できる知識は、関連するトピックのスペースに置きます。フォルダー自身のスペースにいる場合、そのトピックのホームはスクリプトが示す設定済み wiki です。これは第 2 のルートです。その wiki に置くページ名と場所を提示し、承認されたら、書き込む前にそのルートを手順 2 と 5 に通します。候補が複数あり同程度に妥当な場合、または候補がない場合は、質問します。フラットな wiki ではルートに書き込みます。名前は wiki 自体のパターンに従います。既存ページの形式に合わせ、パターンがない場合は小文字、ハイフン区切り、50 文字以下を既定とします。

7. 書き込みのたびに上限を確認する。 書き込む前に、予定しているコンテンツをパイプで渡します。

   python3 <skill-dir>/scripts/ws.py check-size <target> --stdin --wiki <root> <<'EOF'
   <planned content>
   EOF
   

   編集時も同じ方法で予定内容をパイプに渡します（上限超過ページを縮小した場合は ok が報告されます）。監査は見逃したものを補います。over の場合、切り詰めたり、無視したり、上限を引き上げたりしてはいけません。ページとそのスペースのインデックスを読み直し、超過した理由を診断してから対処します。

   • 肥大化 — 水増し、ほぼ重複する内容、生のまま貼り付けた文章、現在なら作り直さない項目 → 統合、簡潔化、削除によって整理します。この判断を促すために上限があります。
   • 増加 — 1 つのファイルに真に異なるトピックが共存している → 今日のコンテンツを前提に設計した場合のスペース構成に作り直します。ハブ配下に独立して読める兄弟ページを作る、昇格させる、またはレイアウトを再編成します（スペース操作には両方の手順へのリンクがあります）。 両方に当てはまる場合は、先に整理し、残った内容を再編成します。変更したインデックスはすべて更新します。topic-2.md や topic-more.md のようなファイル名は、スペースを再検討せずにファイルを分割したことを意味します。このような状態で公開してはいけません。 上限を超えた index.md はナビゲーション上の負債です。詳細を子ページに移し、各項目を 1 行にします。

8. 書き込む。 新規ページでは、最も近い祖先に _template.md があればそれを使い、なければ wiki のページ形式に従います（フロントマターは wiki 内ですでに使われている場合に限ります）。ソースにない主張には %%inferred%%、ソースが矛盾する場合は %%ambiguous%% を付けます。最初に自然な形で言及する箇所に、Wiki リンクを最大 2 つ追加します。更新時は内容を統合し、手動のコンテンツを保持し、フロントマターを使用している場合は updated: を更新し、無関係なセクションは上書きしません。プロジェクト同期では、プロジェクトのハブページにリポジトリのパス（~ に短縮）を記録します。フロントマターを使用している場合は repo:／sources: に、それ以外の場合は通常の行として記録し、後のセッションでチェックアウト先とページを対応付けられるようにします。変更対象が約 10 ページを超える場合は、先に計画を示して確認を求めます。

9. 規約を維持する。 新しいスペースを作成した、削除した、またはページを移動した場合は、下記の スペース操作 に従って ## Spaces を更新します。## Items セクションは任意の人手によるキュレーション用です。インデックスにすでに存在する場合は維持します。次に、残す構成を確認します。項目の説明が実態に合っているか、名前が歴史的な経緯を知らないと意味が通じないものになっていないかを確認します。小さな修正はその場で行い、大規模な再編成は終了時の ws-tend の提案にします。

10. 終了処理を行う。 audit を実行します。安全な構造修正は自分で適用し、すべて解消されるまで各ラウンドの間に再監査します。

    • missing entry の指摘に表示されるエントリ行をそのまま追加し、その末尾に — description を付けます。これは、後続の各操作が参照する配置ヒントです。
    • 登録済み の裸の子に欠けている ## Spaces 見出しを挿入します。ただし、指摘のヒントが挿入を求めている場合に限ります。ニアミスのヒントが名前の変更を求めている場合は、作成者の意図として報告したままにします。
    • 別のスペースの境界を越えていると監査で指摘されたエントリを削除します。より深い階層の一覧はそのスペースが所有します。エントリが不足している場合は、そちらに登録してください。

    宣言されていない裸のインデックスは昇格の判断事項です。明示し、ユーザーの指示があった場合にのみ対応します。それ以外の指摘は報告するだけで、自動修復はしません。この同期の書き込み範囲外の内容については、ws-tend の実行を提案します。提案だけにとどめ、自分では実行しないでください。コアブロックの形式に従って、項目ごとに UPDATE 行を記録し、1つのブロック内で Updated wiki (<root>) と作成したパス、更新したパス、モード、監査結果を報告します。

スペースの操作

スペースを作成する（第一級のナビゲーションが必要なフォルダー）：

mkdir -p <root>/<path> && printf '# <Title>\n\n## Spaces\n' > <root>/<path>/index.md

最も近い親スペースの ## Spaces に登録します。形式は - [<name>/](<name>/index.md) — description で、名前に応じて href をパーセントエンコードします。description は後続の操作が参照する配置ヒントです。迷った場合は、監査の missing entry の指摘に正確な行が表示されます。

ページを削除する：まず、そのページを参照しているものがないか調べます — grep -F '<stem>' --wiki <root>（すべてのリンク形式に stem が含まれます。コード例は除き、各ヒットを判断してください）。実際のリンクを書き換えるか削除し、ページの削除より _archives/ への移動を優先してから、audit を実行します。

スペースを削除する：ユーザーに確認し（削除より _archives/ への移動を優先）、フォルダーを削除して、親の ## Spaces からそのエントリを削除し、最後に audit を実行して参照切れがないことを確認します。

他の人のスペースをマウントする：references/mount.md。自分のスペースを共有する：references/share.md。

ページをスペースに昇格する — ページの構成上、必要になれば通常の手順として行います。リンクを一覧化し、スナップショットを取り、移動し、書き換えて、検証します：references/promote.md。スペースの名前変更、移動、統合、または降格も、同じ基本構成に従います：references/restructure.md。