brain-link-discipline

brain-link-discipline — リンクも成果物の一部です

規約： _output-rules.md を参照してください。Deterministic Links セクションには、スキル間で共通する規範（ページ内では相対リンク、メッセージ内では検証済みリンクを使用することと、フォールバックチェーン）が記載されています。このスキルでは、パスの導出、リンクより先にプッシュする順序、検証、サブエージェントへの中継時の書き換え、一括リストの書式という仕組みを扱います。

規約： conventions/brain-first.md では、1 行の原則（「出力内の脳ページへの参照にはすべて、デプロイ環境に適したクリック可能なリンク形式を使用する」）が示されています。このスキルは、その原則を詳しく説明するものです。

これは、ハーネスが脳ページの配信メッセージに適用する報告規約です。このようなメッセージを作成するときに適用する恒常的なルールであり、ツールによって機械的に強制される保証ではありません。

ルール（同じメッセージ内）

脳ページをコミットしてプッシュしたら、その作業を報告する SAME メッセージにリンクを記載します。毎回必ずです。プッシュが成功したら、同じ返信にリンクを載せずに「コミットしてプッシュします」と伝えてはいけません。ユーザーに「リンクをください」や「ページはどこですか」と尋ねさせてはいけません。

これは以下に適用されます。

• 作成または編集した脳ページを報告するすべてのメッセージ
• 一括報告（「5 ページを作成しました」など。各ページにそれぞれリンクの行を記載します）
• 通常の会話で脳ページに言及する場合
• 脳のパスに言及したサブエージェントの結果を中継する場合（先に書き換えます。下記を参照）

最もよくあるリンクの不備は、脳ページをコミットした後、ユーザーに自分で見つけさせることです。リンクは成果物であり、後から補足するものではありません。

適用範囲の違い：メッセージ内とページ内（逆転）

2 つの出力先では、正反対のリンク形式を使用します。

出力先	リンク形式	理由
ユーザーへのチャットメッセージ	絶対 URL（検証済みのもの、または以下のフォールバックチェーンを使用）	チャットの出力先では、リポジトリ相対パスをクリックできません
脳ページ本文内	相対マークダウンリンク：[Alice Example](../people/alice-example.md)	gbrain のリンク抽出は、ファイルシステム相対リンクからリンクとバックリンクのグラフを構築します。このグラフが関係性に基づく検索を支えます。2 つの脳ページ間の絶対 URL は、このグラフでは認識されません

脳ページ内のページ間参照に絶対 URL を使ってはいけません。 ページ本文内で絶対 URL を使用するのは、実際に外部を参照する場合だけです。フロントマターの related: / people: キーには、相対パスのみを記述します（機械的に解析されるものであり、レンダリングされる文章ではありません）。リンクを多く含む内容を書き込んだ後は、gbrain check-backlinks check でグラフを監査し、gbrain sync --no-pull でページを検索可能にします。

パスを機械的に導出する

ホストされている Git リモートが提供するリポジトリ相対パスは、現在の作業ディレクトリではなく、Git リポジトリのルート（git rev-parse --show-toplevel）を基準にします。リポジトリルートが作業ディレクトリより上位にあるときに、作業ディレクトリのプレフィックスを手作業で削除すると、途中のディレクトリ部分が気付かないうちに抜け落ち、作成したリンクがすべて 404 になります。プレフィックスを手作業で削除してはいけません。次のように導出します。

# From anywhere inside the repo, prints the EXACT path the remote serves:
cd "$(dirname <file>)" && git ls-files --full-name "$(basename <file>)"
# e.g. people/alice-example.md

次に組み立てます。

https://<host>/<owner>/<repo>/blob/<branch>/<that-exact-path>

• git remote get-url origin から <host>/<owner>/<repo> を取得します
• git rev-parse --abbrev-ref HEAD（またはリモートのデフォルトブランチ）から <branch> を取得します
• ファイルには /blob/、ディレクトリには /tree/ を使用します（GitHub 形式のホスト）

手順（リンクを貼る前にプッシュ）

1. brain ファイルを作成または編集します。
2. scripts/brain-commit-push.sh "<msg>" <file>（brain にヘルパーがない場合は gbrain git commit-push -m "<msg>" -- <file>）を実行します。 チェックアウトのライターロック下でそのファイルのみをコミットしてプッシュし、 他のエージェントのファイルには触れずにリモートのコミットをマージします。
3. プッシュが反映されたことを確認します — コマンドが終了コード 0 で終了し、 pushed <sha> to origin/<branch>（または nothing to commit）と出力される必要があります。 チェックアウトの遅れを示す [gbrain notice] が表示されても、プッシュは反映されています。 ホスト上の URL はプッシュが完了するまで 404 になります。終了コードが 0 以外の場合は、 リンクを出力しないでください。commit_lock_busy の場合は 1 回だけ再試行し、 integrate_conflict または writer_coordinator_required の場合は停止してユーザーに伝えてください。 stash、pull --rebase、通常のプッシュには決してフォールバックしないでください （結果）。
4. コミットを報告するのと同じメッセージ内にリンクを出力します — クリック可能な Markdown リンクまたは URL をそのまま記載してください。バッククォートで囲んだコードスパンは使用しないでください。

リンクを貼る前に確認（ホスト上のリモートがある場合）

ユーザー向けメッセージにホスト上のリモートへのリンクを含める前に、そのパスがリモートに存在することを確認してください。GitHub の例（プライベートリポジトリではトークンが必要です）：

curl -sf -o /dev/null -w '%{http_code}' \
  -H "Authorization: token $GITHUB_TOKEN" \
  "https://api.github.com/repos/<owner>/<repo>/contents/<repo-relative-path>"

200 の場合にのみリンクを送信してください。プッシュした直後でホストの API の反映が遅れている場合は、参照先が更新されたことを示すプッシュ出力で十分な証拠になります。ただし、URL を作り出したり推測したりしてはいけません。

トークンは発行元のホストにのみ送信してください。 上記の Authorization: token ヘッダーの送信先が api.github.com なのは、リモートが github.com のリモートだからです。git remote get-url origin から導き出したホストがトークンの発行元であると確認できていない場合は、$GITHUB_TOKEN を決して送信しないでください。改ざんされた、または予期しないリモート（origin が攻撃者のホストや、トークンの利用範囲外のエンタープライズ／セルフホスト型ホストを指している場合）は、認証情報を盗み取るおそれがあります。github.com のリモートには api.github.com を使用してください。それ以外のリモートの場合は、未認証で確認してください（パブリックリポジトリの存在確認にトークンは不要です）。確認しない場合は、プッシュによる参照先更新の証拠にフォールバックしてください。迷った場合は、トークンを送信しないでください。

フォールバックの順序

1. ホスト上の git リモート URL（確認済み）。 brain リポジトリにファイルを表示できるホスト上のリモートがある場合 → 上記のとおり URL を作成して確認します。
2. リポジトリ相対パスと適用範囲の注記。 ホスト上のリモートがない場合（通常の PGLite brain にはリモートがないか、リポジトリがローカルのみの場合）→ リポジトリ相対パス（people/alice-example.md）を示し、brain リポジトリ内のローカルパスであることを明記します。
3. 添付可能な HTML アーティファクトとしての gbrain publish の出力。 gbrain publish <page-path> は自己完結型のローカル HTML ファイルを出力します（出力行は Published: <local-path> です）。そのファイルを添付または送信すると案内してください。これは URL ではないため、URL として提示してはいけません。機密性の高い内容には --password を使用してください。

サブエージェントへの引き継ぎ時の書き換えルール

サブエージェントはローカルコンテキストで実行され、ローカルパスを返します。サブエージェントの完了報告をそのまま引き継ぐことは、リンクの不具合が発生する最大の原因です。サブエージェントが media/books/widget-co-notes.md（または brain のチェックアウト内の絶対パス）を報告し、引き継ぎ側がそれをそのまま繰り返してしまいます。サブエージェントの完了報告をユーザー向けの返信に変換する前に、brain ページのパスをすべて、上記と同じ導出方法およびフォールバックの順序に従って書き換えてください。

brain ページを書き込むサブエージェントを起動する場合は、タスクのプロンプトに次の内容を含めてください。

brain ページは git ls-files --full-name から取得したリポジトリ相対パスで報告してください。 親エージェントがリンクに書き換えてから引き継ぎます。

一覧をまとめて出す場合

各行にリンクを 1 つずつ、完全な URL（またはフォールバック形式）で記載してください。バッククォートは使用しないでください。

Created 3 pages:
- https://github.com/<owner>/<repo>/blob/main/people/alice-example.md
- https://github.com/<owner>/<repo>/blob/main/people/charlie-example.md
- https://github.com/<owner>/<repo>/blob/main/companies/acme-example.md

適用範囲の注記：リンクを開けるのはリポジトリのメンバーのみ

プライベート brain リポジトリへのホスト上のリモートリンクを開けるのは、そのリポジトリへのアクセス権を持つ人だけです。ユーザー本人とのチャット上で使う場合は問題ありませんが、外部の人と共有できるリンクではありません。外部と共有する場合は、フォールバックの手順 3 にある gbrain publish のアーティファクトを使用してください。

契約

このスキルでは、次のことを保証します。

• brain ページへの書き込みを報告するすべての送信メッセージに、リンク（または代替形式）が同じメッセージ内に含まれます。ユーザーが尋ねる必要はありません。
• リンクは、git のデータ（git ls-files --full-name、git remote get-url origin）から機械的に構築し、記憶に頼って作成することはありません。
• push が完了する前にホストされた URL を送信することはありません。リンクを送る前に、検証（または参照先更新の証拠）を確認します。
• サブエージェントからの伝達内容は、ユーザーに届ける前に書き換えます。
• ページ内の相互参照は相対パスのままにし、リンク／バックリンクのグラフを維持します。
• ルーティングは、フロントマター内の正規のトリガーに一致させます。
• プライバシーに関する契約を維持します。実名、フォーク固有のファイルシステムパスのリテラル、上流フォークへの言及は含めません。

出力形式

ホストされたリモート（検証済み）：

完了 — push しました。 https://github.com///blob/main/concepts/widget-co-pricing.md

変更をコミットしました（abc1234）：

• concepts/widget-co-pricing.md（編集） — 価格設定のセクションを改訂

ホストされたリモートなし（代替手順 2～3）：

brain リポジトリに concepts/widget-co-pricing.md を保存しました（ローカルパス — この brain にはホストされたリモートがありません）。共有可能な HTML レンダリングが必要ですか？gbrain publish で生成して ファイルを添付できます。

失敗した場合

gbrain のエラー code、終了コード、[AGENT] ブロック、または通知ブロックについては、エージェントオペレータープロトコルに従ってください。このスキル固有の事項は次のとおりです。

• ページが未コミットまたは未同期のためbrainページのリンクが 404 になる場合は、リンクがまだ有効ではないことを伝え、リポジトリ相対パスを示してください。ホストされた URL を捏造してはいけません。
• リンクしようとしたスラッグに対して get_page / gbrain get が page_not_found を返す場合は、リンクする前にタイトルで検索して正しいスラッグを特定してください。推測したスラッグを使ってはいけません。
• gbrain publish が失敗した場合は、壊れた共有リンクではなく、スコープに関する注記を添えてリポジトリ相対パスをユーザーに示してください。

アンチパターン

• ❌ 「コミットして push しました。」— リンクがありません。
• ❌ 「ページは /absolute/local/path/... にあります。」— リンクまたはリポジトリ相対パスではなく、ローカルの絶対パスを示しています。
• ❌ コミットした後、ユーザーがリンクを尋ねるまで待つこと。
• ❌ ローカルの brain パスを含むサブエージェントの結果を、そのまま伝えること。
• ❌ push が完了する前にホストされた URL を出力すること（push が完了するまで 404 になります。先に push し、参照先の更新を確認してからリンクしてください）。
• ❌ gbrain publish の出力を URL として提示すること。これはローカルの HTML ファイルパスを出力します。添付可能な成果物として提示してください。
• ❌ cwd のプレフィックスを手動で取り除いて、リポジトリ相対パスを作成すること。git ls-files --full-name を使用してください。
• ❌ brain ページ内のページ間参照に絶対 URL を使用すること。関係性に基づく取得に必要なリンク／バックリンクのグラフが壊れます。
• ❌ クリック可能なリンクを作成できるのに、チャット内でパスをバッククォートで囲むこと。
• ❌ 記憶を頼りに URL を推測または再構築すること。

重複の整理（明確な境界）

• skills/publish/SKILL.md — 共有可能な HTML アーティファクトを生成する方法（不要部分の削除、暗号化、出力オプション）を担当します。brain-link-discipline が判断するのは、いつそれにフォールバックするかだけであり、その出力を URL として約束することは禁止しています。
• skills/_output-rules.md（Deterministic Links）— スキル間で共通する標準を担います。決定論的な構築、ページ内とメッセージ内の対象範囲の分割、フォールバックチェーンです。このスキルが担うのは、メッセージごとの仕組み、つまり導出、順序付け、検証、中継時の書き換え、一括フォーマットです。
• skills/conventions/brain-first.md — 参照規約内で、クリック可能なリンクを1行で示す原則を定めています。このスキルは、それを配信メッセージ向けに拡張したものです。
• skills/conventions/subagent-routing.md — サブエージェントに作業を割り当てる方法を定めています。このスキルは、中継時のパス書き換え義務を追加します。subagent-routing はリンクやパスの書き換えには触れていません。
• skills/citation-fixer/SKILL.md — 既存の brain ページ内にある壊れた引用を修正します。送信メッセージのリンクは対象外です。
• skills/reports/SKILL.md — レポートページを保存および読み込みます。レポートの配信メッセージで brain ページを参照する場合、そのメッセージにはこの規律が適用されます。reports スキル自体にはリンク規則はありません。