Purpose & Output Contract

• ゴール: ナレッジソースの追加・変更差分が registry.json との照合で検知され、knowledge-extractor による6カテゴリ分類と router.json 更新までナレッジ同期が完了した状態。
• 出力契約: 検知/抽出/分割/graph 検証の結果レポート（NEW/MODIFIED 件数・格納先・分割要否・graph status）+ knowledge/*.json 更新 + router.json/registry.json/sync-log.jsonl 追記 + 差分があるときの knowledge-relations.json/knowledge-graph.json 再生成。
• 境界: vault 内ナレッジソースは read-only 入力。書込先は確認済み target scope 内の PLUGIN_ROOT/knowledge/、同 skill の assets/kitahara-principles-db.md、PROJECT_ROOT/eval-log/ubm-goal-setting/run-ubm-knowledge-sync/ だけ。それ以外と symlink 経由の scope 外は write 前に停止する。目標設定対話は run-ubm-goal-setting へ委譲する。
• 6カテゴリ: principles（原則）/ consultation（相談）/ phase-advice（フェーズ）/ action-guides（行動）/ mindset（転換）/ case-studies（事例）。
• 必須禁則: --dry-run で plugin knowledge や vault を書き換えない。external mutation は canonical receipt flow 外で実行しない。

Runtime root contract

• runtime_root_policy: host-skill-path を適用する。
• Claude Codeでは CLAUDE_PLUGIN_ROOT をplugin rootとして使用する。
• Codexではホストが提示したこの SKILL.md のabsolute pathから、plugin manifestを持つ祖先を上方探索して論理 PLUGIN_ROOT を解決する。
• PROJECT_ROOT は呼出元が渡すリポジトリ絶対パス（Claude Code では CLAUDE_PROJECT_DIR）に固定し、realpath containment を確認する。未解決なら mutation や eval-log write を始めない。
• cwd からplugin rootを推測せず、literal placeholderをshellへ渡さない。各shell invocation内で解決済みabsolute pathを PLUGIN_ROOT に設定する。
• prompts/ 配下はこのowner Skill契約を継承する。

Pre-choice usable artifact execution

Purpose & Output Contractの最小の実成果物またはremote mutation previewをmain contextで作成する。effect別のparse/open・secret・irreversible・corrupt guardだけを実行し、現物path・digest・開き方またはpreview receiptを提示してからaccept-as-is/light/standard/detailedを記録する。accept-as-isはmutationを実行せずhandoff完了とし、後続sectionを実行しない。

Post-choice selected improvement execution

以下の既存workflow・goal-seek・評価・修正sectionおよびexternal mutation safety wrapperはlight/standard/detailedが記録されてsemantic_evaluator_startedへ遷移した場合だけ実行する。actual mutationはcanonical preview→hook-confirm→authorize→execute wrapperだけを通し、release/exhaustiveは別の明示eventを必要とする。

<!-- external-mutation-guard-cli:v1 -->

Canonical external mutation receipt flow (mandatory)

Never execute the external mutation argv directly. Replace every angle-bracket placeholder with the reviewed value from this run; the central CLI fails closed on missing/invalid values.

Resolve the guard plugin root once, before preview. An installed plugin cannot reach a sibling plugin as <plugin root>/.., so never guess that path:

python3 "${PLUGIN_ROOT:-${CLAUDE_PLUGIN_ROOT}}/scripts/extract-plugin-root.py" skill-governance-adapters

Use the printed absolute path as <GUARD_PLUGIN_ROOT> in preview, authorize and execute (other Bash is blocked while the confirmation is pending, so do not resolve it again). If the resolver exits non-zero, stop without any external mutation and tell the user to install the skill-governance-adapters plugin.

python3 "<GUARD_PLUGIN_ROOT>/scripts/build-external-mutation-guard.py" preview --project-root "$PWD" --entrypoint-ref "plugin:<PLUGIN_NAME>/skills/<SKILL_NAME>/SKILL.md" --target-scope "<TARGET_SCOPE>" --diff-summary "<DIFF_SUMMARY>" --side-effect-summary "<SIDE_EFFECT_SUMMARY>" --command-json '<MUTATION_ARGV_JSON>'

Present that official preview output to the user. Only the exact user reply printed by preview may trigger the registered hook-confirm producer. Then use the two returned receipt paths:

python3 "<GUARD_PLUGIN_ROOT>/scripts/build-external-mutation-guard.py" authorize --project-root "$PWD" --preview-receipt "<PREVIEW_RECEIPT_PATH>" --confirmation-receipt "<CONFIRMATION_RECEIPT_PATH>"
python3 "<GUARD_PLUGIN_ROOT>/scripts/build-external-mutation-guard.py" execute --project-root "$PWD" --authorization-receipt "<AUTHORIZATION_RECEIPT_PATH>" --command-json '<MUTATION_ARGV_JSON>'

Do not use an auto-approval flag or invoke the mutation command outside this receipt flow.

<!-- /external-mutation-guard-cli:v1 -->

run-ubm-knowledge-sync

UBM ナレッジソース（YouTube 議事録・合宿記録・月報 FB・セミナー等）の新規追加・更新差分を検知し、内容別 JSON ファイル（6カテゴリ）へ反映する。北原さんの最新の教えを継続的に取り込み、run-ubm-goal-setting の品質を底上げする。

End-to-End Flow

Phase	責務	実行体
Phase1-detect	detect-knowledge-updates.py が registry.json との MD5 照合で NEW/MODIFIED ソースを漏れなく検知。出力から 05_Project/UBM/目標設定/ を含む行を除外したものが Phase2 入力	script
Phase2-extract	本 skill が NEW/MODIFIED を最大20ファイルずつのバッチへ分割し、各バッチで knowledge-extractor が6カテゴリへ分類して Rule A-F に従い knowledge/*.json + router.json/registry.json を更新	本 skill（batch制御）+ knowledge-extractor（Task）
Phase3-split-check	check-knowledge-split.py がナレッジ JSON の500行閾値超過を機械検査し、knowledge-extractor が25エントリ超過時の意味単位分割を完了して corpus を確定する	script / knowledge-extractor（必要時の Task）
Phase5-graph-sync（Phase3 完了後）	確定済み corpus に対し knowledge-relation-extractor が根拠付き有方向辺の候補 JSON を read-only で返し（knowledge へ書込しない=幻覚防止）、呼び出し側が候補を eval-log へ materialize、validate-knowledge-graph.py --merge-relations が canonical key (source_id,target_id,relation_type) で knowledge/knowledge-relations.json へ冪等 merge（既存辺は保持=first-write-wins）する。全検証 PASS 後に relations→knowledge-graph.json を正準書込し、途中書込失敗は同じ候補の再実行で冪等修復する（2ファイル跨ぎの atomicity は主張しない）。dry-run 時は write 禁止	knowledge-relation-extractor（Task）/ validate-knowledge-graph.py --merge-relations（script）
Phase4-report（Phase5 完了後）	検知/抽出/分割/graph-sync の結果（NEW/MODIFIED 件数・格納先・分割要否・graph検証）を最終レポートへ統合する	本 skill

Phase5 は差分 entry 起点で発火するため、差分ゼロの周回では不発になる。既存 corpus へ辺が一度も付いていない（knowledge-relations.json 不在＝edges=0 の退化グラフ）場合の初回適用は、RUNBOOK（plugin 直下 RUNBOOK.md）の「初回 edge backfill」手順を使う。

ゴールシーク実行

goal_seek.engine: task-graph / engine_profile: checklist-graph / fork: inline を使い、同じ corpus を更新・読取する責務を安全な依存順 Phase1 → Phase2 → Phase3 → Phase5 → Phase4 で1件ずつ消費する。これは checklist の縮小 DAG であり、planner の full task-spec graph ではない (full_task_spec_graph: false)。

完了チェックリスト (Checklist)

• C1: Phase1-detect を実行し差分一覧または差分0件の証跡を得る (depends_on: [], verify_by: script)
• C2: Phase2-extract を完了する。dry-run または差分0件なら条件不成立を記録して no-op 完了にする (depends_on: [C1], verify_by: reasoning)
• C3: Phase3-split-check を完了し、後続が読む corpus を確定する。dry-run なら書込禁止の no-op 完了にする (depends_on: [C2], verify_by: script)
• C4: Phase5-graph-sync を確定済み corpus に対して完了する。dry-run または差分0件なら no-op 根拠を残す (depends_on: [C3], verify_by: script)
• C5: Phase4-report に C1〜C4 の結果、skip理由、未解決事項を統合する (depends_on: [C4], verify_by: reasoning)
• C6: task-graph 消費検証と Anchor 検証が exit 0 で、pending/blocked が残らない (depends_on: [C5], verify_by: script)

ゴールシーク配線

• goal_seek.progress: 初回に上の C1〜C6 を {id,text,status:"pending",depends_on,verify_by} として eval-log/ubm-goal-setting/run-ubm-knowledge-sync/goal-seek-progress.json へ記録し、top-level に engine:"task-graph"、iteration、open_issues、status、max_loops:9 を置く。 goal_seek.intermediate: 各周回末の Anchor Step で run-ubm-knowledge-sync-intermediate.jsonl に original_goal / current_goal_snapshot / delta_from_original / merged_directive_for_next / drift_signal と、その周回の ready_set / selected_item を append-only で残す。 goal_seek.handoff: 完了時に検知件数、更新先、split-check/graph検証結果、dry-run 有無、未解決課題を handoff-run-ubm-knowledge-sync.json へ書く。
• ループ・ready-set・外部mutation guard・ユーザー確認・progress write は親 context が所有する。Phase2 の抽出と Phase5 の関係候補生成だけを対応する knowledge-extractor / knowledge-relation-extractor へ Task 委譲し、各自は個別 surface 成果だけを返す。各 Task input には親が host-skill-path から解決した absolute PLUGIN_ROOT を明示し、SubAgent は未指定または非 absolute なら write 前に fail-closed で停止する。preview 後の exact reply は親が受け、confirmation receipt を得てから同じ周回を authorize→execute へ再開する。
• 各周回は python3 "${PLUGIN_ROOT:-${CLAUDE_PLUGIN_ROOT}}/skills/run-ubm-knowledge-sync/scripts/extract-ready-set-from-checklist.py" "$PROJECT_ROOT/eval-log/ubm-goal-setting/run-ubm-knowledge-sync/goal-seek-progress.json" で raw ready を算出する。effective ready_set は raw ready から 2 種類を除いた集合とする: (a) C6 以外の item が1件でも未消費なら最終 completion gate である C6、(b) available_from_iteration が現在の周回 index より後の追記 item (まだ有効化されていない)。除去後の最小IDだけを選択する。この 2 条件は validate-knowledge-sync-task-graph.py の ready 再計算と同一であり、片方だけを適用すると検証器と食い違って周回が FAIL する。実行または条件付きno-opの証跡を残して該当itemを done にしてから再計算する。実行中に追加必須作業を発見した場合だけ同じ skill 配下の build-self-reflection-entry.py で C7 以降のidと実際の先行item（C6 以外）への depends_on を持つitemを同じ checklist 末尾へ追記する（別 task graph state は作らない）。effective ready が空で将来周回から有効な追記itemがある場合は、その周回を未選択traceとして残し C6 を先行させない。
• --dry-run 指定時も C1→C2(no-op)→C3(no-op)→C4(no-op)→C5 の順に選択してtraceを残し、Phase2 extraction・Phase3 split repair・Phase5 graph writeを禁止する。condition不成立を「未選択」のまま残さない。
• C6 は selected_item trace を先に追記し、C6をdone・全体をcompleted候補へ更新してから下記検証を最終実行する。exit非0ならcompletedを確定せず status: handed_off と open_issues へ違反を残す。
• max_loops 到達時は PASS 扱いせず、残チェック項目を open_issues に残して human review へ差し戻す。

dependency graph knowledge consult

各 surface の着手前に python3 "${PLUGIN_ROOT:-${CLAUDE_PLUGIN_ROOT}}/skills/run-ubm-knowledge-sync/scripts/extract-capability-dependency-graph.py" "${PLUGIN_ROOT:-${CLAUDE_PLUGIN_ROOT}}" の出力を $PROJECT_ROOT/eval-log/ の派生JSONへ保存する。通常実行では dangling/cycle が無いときだけ同じ skill 配下の build-capability-graph-knowledge-entry.py へ graph path と --target-knowledge-dir "${PLUGIN_ROOT:-${CLAUDE_PLUGIN_ROOT}}/knowledge" を渡し、source_ref 付き要約をappend/mergeする。--dry-run では extract 結果を eval-log 内でのみ consult し、record と plugin knowledge/ write を no-op trace にする。通常時は knowledge/knowledge-capability-graph.json を consult し、未完成依存を先に実行しない。この knowledge は実行順stateではなく派生判断であり、progress checklistだけを唯一のtruthとする。

ゴールシーク検証

Anchor Step と依存順消費を同時に機械検証する。absence-as-violation とし、task-graph なのに ready_set / selected_item trace が無い場合は失敗させる。申告 ready_set は信用せず、checklist・過去の selected_item・available_from_iteration から各周回の ready 全集合を再計算し、未消費の C6 以外itemがある間は completion gate C6 を effective ready から除く。以下を順に実行し、両方 exit 0 を必須とする。前者の正本は required_keys / original_goal_hash / hashlib.sha256 を検査し、後者は追記itemが C6 より前に全てdoneとなる self-reflect 完了 gate を含む依存順消費を検査する。

python3 "${PLUGIN_ROOT:-${CLAUDE_PLUGIN_ROOT}}/scripts/validate-inline-goal-seek-anchor.py" \
  "$PROJECT_ROOT/eval-log/ubm-goal-setting/run-ubm-knowledge-sync/goal-seek-progress.json" \
  "$PROJECT_ROOT/eval-log/ubm-goal-setting/run-ubm-knowledge-sync/run-ubm-knowledge-sync-intermediate.jsonl"
python3 "${PLUGIN_ROOT:-${CLAUDE_PLUGIN_ROOT}}/skills/run-ubm-knowledge-sync/scripts/validate-knowledge-sync-task-graph.py" \
  "$PROJECT_ROOT/eval-log/ubm-goal-setting/run-ubm-knowledge-sync/goal-seek-progress.json" \
  "$PROJECT_ROOT/eval-log/ubm-goal-setting/run-ubm-knowledge-sync/run-ubm-knowledge-sync-intermediate.jsonl"

• inner ループ (IN1): Phase1 で detect-knowledge-updates.py --registry knowledge/registry.json --sources $UBM_VAULT_ROOT/05_Project/UBM [--all|--since] を実行し、NEW/MODIFIED を registry との MD5 照合で漏れなく検知する。
• outer ループ (OUT1): 既知の更新済みソースを投入し、knowledge-extractor が6カテゴリへ正しく分類し router.json/registry.json が同期完了することを受入テストで確認する。

Key Rules

• 検知対象: $UBM_VAULT_ROOT/05_Project/UBM/ 配下の全 .md（YouTube/合宿/月報フィードバック/動画教材/ルート直下）。05_Project/UBM/目標設定/（ユーザー自身の目標記録＝北原ナレッジ非該当）は consumer 側で除外する。
• 抽出モード: 引数なし=未処理のみ / --all=全件強制 NEW（mode:full 全再構築・knowledge-extractor Rule F）/ --since YYYY-MM-DD=指定日以降 / --dry-run=検知のみで書込なし。
• 必須フィールド: 各エントリに content/background/intent/root_cause/expected_outcome 等（schema.json 準拠）。引用は北原さんの原文を正確に抜き出す（要約でなく引用）。分類はソース種別でなく内容の種類で行う。
• 命名規則（厳守）: {category}-{subtopic}.json。subtopic は内容を英語で表現（relationship/organization/0to1 等）。連番 -1/-2/-a/-b は絶対禁止（ファイル名だけで対象読者が分かること）。
• 分割基準の二層化: 25エントリ超過は意味単位の分割検討トリガー、500行超過は check-knowledge-split.py の機械的な肥大ガード。両者が衝突する場合は 25エントリ基準でサブテーマを設計し、500行ガードを必ず解消する。
• registry の file_hash: Bash の md5 由来 32文字ハッシュを記録。日付文字列・偽値の使用は禁止。extracted_entry_ids は null 禁止（次回 MODIFIED 検知時の削除に使用）。
• MODIFIED 処理: registry の extracted_entry_ids を辿って既存エントリを削除 → 全件再抽出 → registry を上書き（Case A/B は knowledge-extractor の Step U-1〜U-4 を正本とする）。
• legacy null の移行: シード registry の extracted_entry_ids: null 7件（_note: legacy）は、初回 MODIFIED 検知時に該当ソース由来のエントリを全削除 → 再抽出で extracted_entry_ids を backfill し、以後は null 禁止を適用する。
• 途中失敗の再開: 最大20ファイルは並列 transaction ではなく1 sourceずつ処理する。source ごとに knowledge/*.json → router 再集計 → idempotency key 付き sync-log → registry の順で確定し、registry の (file_path,file_hash,status=processed) を唯一の commit point とする。registry 確定前の失敗は同じ source を再実行し、content/source 重複検査と sync-log key で冗等に収束させる。commit 後の source は detect が再選択しない。未 commit source を残したまま次へ進まない。

Gotchas

• schema は plugin-root 共有 surface: 本 skill の knowledge-extractor は knowledge/schema.json 準拠でエントリを書き、run-ubm-goal-setting の info-collector は router.json 経由でその knowledge/*.json を読む。consumer が schema ファイル自体を直接読む契約ではなく、共有データを schema 準拠に保つことで skill 間を整合させる。
• 初期シードの非対称: registry.json は実台帳（処理済み67ファイル・移植元の dead path 6件は build 時に除去）を初期値として vendor 済み（初回 sync 全件 NEW 誤検知を回避）。sync-log.jsonl は空（0エントリ）で開始し append-only で追記する。
• L2 vault 未接続時: sources が空でも検知0件レポートを正常終了として返す（個人利用で vault 未接続でも FAIL 扱いしない）。L1 curated knowledge は vendor 同梱のため疎通不要。
• 書き込み保護: vault ソースは常に read-only。plugin 同梱 knowledge/*.json / 同 skill asset / 専用 eval-log 以外は書かず、各 Task は解決済み absolute root と realpath containment を write 前に確認する。

Additional Resources

• agents: knowledge-extractor（6カテゴリ分類・Rule A-F・router/registry 更新）/ knowledge-relation-extractor（read-only 候補辺生成）。どちらも plugin 直下 agents/。
• scripts: skill 直下の差分検知・分割・ready/self-reflect/capability graph・task-graph trace 検査と、plugin 直下 validate-knowledge-graph.py / validate-inline-goal-seek-anchor.py。frontmatter script_refs が実パスの正本。
• references: references/knowledge-sources.md（取得方法・優先順位）/ references/knowledge-design-principles.md（記録対象・必須フィールド・命名規則）。
• assets: assets/kitahara-principles-db.md（北原さん原則 DB・新原則発見時に追記する L3 mutable asset）。
• knowledge: plugin 直下 knowledge/（schema.json/router.json/registry.json/sync-log.jsonl + 6カテゴリ *.json）。