schema-author

schema-author — スキーマパックを拡張する

対象外（代わりにこれらのスキルを使用してください）

このスキルはスキーマパックを作成します（ページタイプ、リンク動詞、プレフィックス、フラグを追加します）。以下の関連タスクは、別の場所に振り分けてください。

• 特定のページを1つ登録する → skills/brain-taxonomist/SKILL.md。Brain-taxonomist は書き込み時に「このメモはどこに置く？」を振り分けます。schema-author は作成時に「どのタイプとプレフィックスが存在する？」というルールを変更します。
• EIIRP の反復作業の一環としてスキーマをチェックする → skills/eiirp/SKILL.md にスキーマチェックのフェーズがすでにあります。重複させないでください。
• タイプの設定を調べるだけ → gbrain schema explain <type> を直接使ってください。このスキルはパックを変更するためのものであり、パックから情報を読み取るためのものではありません。
• X に詳しい人を検索する → gbrain whoknows <topic> を直接使ってください。schema-author はタイプを専門家の振り分け対象にしますが、検索自体は実行しません。

規約

規約： 参照先：conventions/brain-first.md。検索チェーン（search → query → get_page → external）について説明しています。

規約： 参照先：conventions/schema-evolution.md。タイプ、エイリアス、プレフィックスのどれを追加するかを判断するためのヒューリスティックについて説明しています。

呼び出すタイミング

ユーザー（または関連するスキル）が次のいずれかを依頼した場合に呼び出してください。

• 「スキーマに researcher タイプを追加して」
• 「meetings/ の下にタイプ未設定のページが4000件ある」
• 「自分の brain が journal-article をタイプとして認識しない」
• 「paper を抽出可能にして」
• 「取り込んだ内容からタイプを提案して」
• 「既存ページを補完するために、新しいタイプを同期して」

「このメモはどこに置く？」の場合は呼び出さないでください（brain-taxonomist を使用）。「X に詳しい人は誰？」の場合も呼び出さないでください（expert-routing または gbrain whoknows を使用）。

チュートリアルとビジョン

• これが重要な理由： docs/what-schemas-unlock.md — 7つの強力なユースケース（検索可能になった4000件の見えない会議、創業者の業務用 brain、研究用 brain、法務用 brain、チーム用 brain、共同キュレーターとしてのエージェント）に加え、クエリ時にタイプが重要となる構造上の理由を解説しています。ユーザーにスキーマ作成を提案する前にお読みください。メモの山と、構造を持つ brain の違いを説明するドキュメントです。
• 5分間のウォークスルー： docs/schema-author-tutorial.md — 同梱パックをフォークし、researcher タイプを追加して同期し、gbrain whoknows で T1.5 の連携を確認します。プレースホルダーページを使うため、実際のコンテンツに影響を与えることなく、どの brain でも実行できます。

ワークフロー

フェーズ1 — Brain（有効なパックを確認する）

gbrain schema active --json

出力には pack_name、version、sha8、page_types_count、source_tier が含まれます。 source_tier === "default" の場合、ユーザーは同梱の gbrain-base を使用しているため、変更を加えるにはまずフォークが必要です（フェーズ4）。

フェーズ2 — 評価（現在のパックは何をカバーしているか？）

gbrain schema stats --json

タイプごとのページ数、タイプ未設定のページ数、dead_prefixes（一致するページが0件の、パックで宣言されたプレフィックス。誤った宣言の可能性があります）を返します。 カバレッジが90%未満の場合、タイプ付けする価値のある未分類コンテンツがあります。

gbrain schema review-orphans --json

タイプ未設定のページを詳しく確認します。共通するパスプレフィックスを探してください（例：「12件が research/papers/ の下にある」）。新しいタイプの候補になります。

フェーズ3 — 提案（パックに追加すべきタイプは？）

gbrain schema detect --json

ページを source_path ごとにクラスタリングし、候補となるタイプを提案します。ヒューリスティックのみを使用します（LLM の呼び出しはありません）。

gbrain schema suggest --json

信頼度スコア付きの、LLM によって絞り込まれた候補です。どの候補を採用するかの判断材料として、上位3件の的中率を使用してください。

フェーズ 4 — 適用（パックを変更する）

アクティブなパックがバンドル済みのもの（gbrain-base または gbrain-recommended）の場合は、 まずフォークします。

gbrain schema fork gbrain-base mine
gbrain schema use mine

次に、型を 1 つずつ追加します。

gbrain schema add-type researcher \
  --primitive entity \
  --prefix people/researchers/ \
  --extractable \
  --expert

複雑な複数変更のリファクタリング（例：型と、その型を指すリンク動詞を追加する）の場合、この処理を MCP 経由で利用するエージェントは、 バッチ処理の schema_apply_mutations オペレーションを使用できます。

{"op": "add_type", "name": "researcher", "primitive": "entity", "prefix": "people/researchers/", "extractable": true, "expert_routing": true}
{"op": "add_type", "name": "paper", "primitive": "annotation", "prefix": "research/papers/", "extractable": true}
{"op": "add_link_type", "name": "authored", "inference": {"page_type": "researcher", "target_type": "paper"}}

同期前に検証します。

gbrain schema lint --with-db

--with-db フラグを指定すると、4 つの DB 対応ルール（extractable_empty_corpus、 mutation_count_anomaly、 stored_type_is_alias、stored_type_undeclared）が有効になり、 実行時にしか判明しない型の誤宣言を検出します。

フェーズ 5 — 同期（既存のページに新しい型を適用する）

まずドライランを実行します。

gbrain schema sync --json

プレフィックスごとの would_apply 件数とサンプルスラッグが返されます。数値に問題がなければ：

gbrain schema sync --apply

1000 行単位のチャンクで UPDATE を実行します。同時実行中の書き込みが停止することはありません。 再実行しても冪等です（2 回目の --apply では、バックフィル対象は見つかりません）。

フェーズ 6 — 検証

gbrain schema stats --json

カバレッジは 95% 以上になっているはずです。新しい型をスポットチェックします。

gbrain whoknows "machine learning"

researcher が --expert として宣言されていれば、結果には researcher 型のページが含まれるはずです。（クエリパスでパックを考慮した接続処理は v0.40.6.0 で追加されました。v0.40.6 より前の brains では、エキスパートルーティング対象のカスタム型は無言で無視されていました。）

フェーズ 7 — コミット（変更を保持する）

パックがソース管理下にある場合は、パックファイルのみをコミットしてプッシュします。

cd ~/.gbrain/schema-packs/mine
gbrain git commit-push -m "schema: add researcher + paper types + authored link" -- pack.json

チェックアウトの書き込みロックを取得し、リベースせずにプッシュ拒否をマージするため、他のエージェントが同じチェックアウトを共有していても安全です。終了コードが 0 以外の場合：commit_lock_busy なら 1 回だけ再試行します。integrate_conflict なら停止し、どちらのバージョンの pack.json を採用するかユーザーに確認します。git_push_unavailable の場合、リモートに到達できません（コミットは保存済みなので、後で --push-only を指定して再実行してください）。または、パックのリポジトリにリモートがまったくない場合は何もコミットされていません。その場合は git add pack.json && git commit -m "<msg>" -- pack.json でパックのみをローカルにコミットします。stash、pull --rebase、通常のプッシュへのフォールバックは絶対に行わないでください（結果）。

brain デーモン（gbrain serve --http）が実行中の場合、他のプロセスは 1 秒以内に変更を認識します（loadActivePack の stat-mtime TTL ゲートにより、v0.40.6.0 でプロセス間の無効化の不整合が解消されました）。

出力

• ~/.gbrain/schema-packs/<name>/pack.{json,yaml} に変更済みのパックファイル。
• 変更ごとの監査行を ~/.gbrain/audit/schema-mutations-YYYY-Www.jsonl に記録します。
• sync --apply の後、一致する行の pages.type がバックフィルされます。
• クエリパス（whoknows、find_experts）が、新しいエキスパート型を使ってルーティングするようになります。

契約

• 入力： 型／プレフィックス／リンク動詞／フラグの変更を指定した自然言語のリクエスト、または新しい型が必要な未分類ページを示す gbrain schema review-orphans の実行結果。
• 出力： ~/.gbrain/schema-packs/<name>/pack.{json,yaml} に変更済みのパックファイル、~/.gbrain/audit/schema-mutations-YYYY-Www.jsonl の監査行、および（sync --apply を実行した場合）一致する行でバックフィルされた pages.type。
• 副作用： インプロセスのパックキャッシュと、ソースのクエリキャッシュを無効化します。他のプロセスは 1 秒以内に変更を認識します（stat-mtime TTL）。
• 冪等性： すべてのプリミティブは冪等です。add-alias／add-prefix は重複時に何もしません。sync --apply は 2 回目の実行では更新対象を検出しません。
• 信頼： CLI はローカルの信頼を前提とします（スコープの確認なし）。MCP は書き込みオペレーションに OAuth の admin スコープを要求します。監査ログには変更ごとに actor: mcp:<clientId8> が記録されます。
• アトミック性： 各変更は withMutation のアトミック書き込み（.tmp + fsync + rename）と、パックごとの O_CREAT|O_EXCL ロックでラップされます。書き込み中にクラッシュしても、元のファイルは変更されません。

失敗した場合

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

• 変更コード：PACK_READONLY → まずフォークします（gbrain schema fork gbrain-base mine）。STILL_REFERENCED → 名前が示された参照を先に削除します。LOCK_BUSY → 約30秒待ってから再試行します。
• MCP 経由で変更すると insufficient_scope が返されます。スキーマへの書き込みには admin スコープが必要で、これは brain ホストのオペレーターのみが付与できます。ユーザーに伝えてください。
• 書き込み前の lint ゲートで変更が拒否された場合は、エラーを読み、指定されたプレフィックスまたはエイリアスの競合を修正して再実行します。lint を回避してはいけません。

アンチパターン

• gbrain-base や gbrain-recommended を変更してはいけません。 まずフォークします（gbrain schema fork gbrain-base mine）。これらは同梱パックであり、編集内容はアップグレード時に失われます。変更プリミティブは PACK_READONLY を返して拒否します。
• トリアージのために一度だけインポートしたディレクトリに対して、型を追加してはいけません。 パックの型は永続的な決定ですが、一度限りのインポートはそうではありません。<20ページはパックとして形式化しないというヒューリスティックについては、skills/conventions/schema-evolution.md を参照してください。
• path_prefixes がない型に --expert を追加してはいけません。 expert_routing_without_prefix lint が警告します。プレフィックスのないエキスパートルーティング対象の型は、put_page の推論に一致しないため、whoknows に表示されないままになります。
• プレフィックスが実際のコンテンツに一致することを確認せずに、schema suggest の候補を昇格させてはいけません。 add-type の前に lint --with-db を実行し、書き込み前にプレフィックスの競合を検出します。
• 「1ページを登録すること」と「スキーマを進化させること」を混同してはいけません。 登録は brain-taxonomist 経由で振り分けます。schema-author は型の分類体系自体を作成するためのものです。境界については、上記の「対象外」セクションで説明しています。
• sync --apply の前にドライランを省略してはいけません。 必ず先に sync を実行して、would_apply の件数とサンプルのスラッグを確認します。50,000ページに一致するパックプレフィックスも復旧可能ですが時間がかかります。事前確認は簡単です。
• 参照を確認せずに型を削除してはいけません。 他の型の aliases／enrichable_types／link_types／frontmatter_links がその型を参照している場合、remove-type は STILL_REFERENCED を返して拒否します。まず参照を解消します。--force を追加してはいけません。

出力形式

呼び出されると、このスキルは人間と JSON の両方で利用できる構造化出力を生成します。

変更ごとの結果（JSON）：

{"schema_version": 1, "pack": "mine", "path": "~/.gbrain/schema-packs/mine/pack.json", "format": "json", "prev_sha8": "a1b2c3d4", "new_sha8": "e5f6g7h8"}

バッチごとの結果（schema_apply_mutations MCP op から）：

{"schema_version": 1, "pack": "mine", "batch_id": "batch-1716491400-abc123", "mutations_applied": 3, "results": [{...}, {...}, {...}]}

統計 JSON（ソースごと＋集計＋デッドプレフィックスのヒント）：

{"schema_version": 1, "pack_identity": "[email protected]+abc12345", "aggregate": {"total_pages": 4823, "typed_pages": 4710, "untyped_pages": 113, "coverage": 0.9766, "by_type": [{"type": "person", "count": 2104}, ...]}, "per_source": [...], "dead_prefixes": [{"type": "researcher", "prefix": "people/researchers/"}]}

同期ドライラン JSON：

{"schema_version": 1, "apply": false, "pack_identity": "[email protected]+abc12345", "per_prefix": [{"type": "meeting", "prefix": "meetings/", "would_apply": 4000, "sample_slugs": ["meetings/2026-01-01-foo", ...], "dead_prefix": false, "applied": 0}], "total_would_apply": 4000, "total_applied": 0}

人間向け出力（エージェントの最終要約）：

• 変更ごとに1行：Pack: <name> (<format>) と Sha8: <prev> → <new>
• 統計：ページ総数、型付け済みの割合、型なしの件数、型ごとの内訳、デッドプレフィックスの一覧
• 同期：ドライランモードでのプレフィックスごとの would_apply／applied 件数とサンプルのスラッグ

失敗時のエラーエンベロープは、標準の StructuredAgentError 形式に従います：{error, code, message, details?}。変更プリミティブのコードは次のとおりです：PACK_NOT_FOUND、PACK_READONLY、PACK_CORRUPT、TYPE_EXISTS、TYPE_NOT_FOUND、INVALID_PRIMITIVE、INVALID_RESULT、IO_ERROR、STILL_REFERENCED、LOCK_BUSY。

失敗モード

• PACK_READONLY → gbrain-base または gbrain-recommended を変更しようとしました。まずフォークしてください。
• INVALID_RESULT → 変更によって参照切れまたはプレフィックスの競合が生じます。書き込み前の lint ゲートが検出しました。エラーメッセージを読み、lint ルール名から問題を特定してください。
• STILL_REFERENCED → 別の型の aliases／enrichable_types／link_types／frontmatter_links が参照している型を削除しようとしました。エラーにはすべての参照が示されます。先にそれらを削除してください。
• LOCK_BUSY → 別のプロセスが変更の途中です。30秒待って再試行するか、ロック保持プロセスが停止していると分かっている場合は --force を渡します。
• permission_denied（MCP のみ）→ OAuth クライアントに admin スコープがありません。gbrain auth register-client --scopes admin で再登録してください。