--- name: ai-loop-cycle description: "ai-loop-workflow の 1 サイクル（C-3' 裁定）を実行する。Use when: 「ai-loop で回して」「C-3' 裁定を実行」「arbiter で裁定して」「ai-loop 初回実走」。恒久定義（責務・terminal state・C-3' 経路）の正本 = 同梱 references/00_concept.md、適用制限（Phase 1 rollout eligibility）の正本 = 同梱 references/rollout-policy.md（導入先が独自正本を保持する場合はそちらを優先）。" --- # ai-loop-cycle > 本スキルは **bundled resources**（`references/`・`scripts/`・`schemas/`）で自己完結する。 > > **パス表記の規約（重要）**: 本 SKILL.md 中の `references/…` / `scripts/…` / > `schemas/…` は、すべて **本スキルディレクトリからの相対パス**（= `/…`） > であって、導入先リポジトリのルートからの相対パスではない。実行時はまず > ``（このファイルが置かれているディレクトリ）を解決してから使う: > > | 環境 | `` | > | --- | --- | > | plugin 導入先（Claude marketplace） | `/skills/ai-loop-cycle/` | > | `install.sh --claude` 導入先 | `.claude/skills/ai-loop-cycle/` | > | Codex 導入先 | `.codex/skills/ai-loop-cycle/` | > | 上流リポジトリ（正本側） | `.agents/skills/ai-loop-cycle/` | > > 導入先が独自の正本（上流リポジトリの `docs/workflows/ai-loop/` に相当するもの）を > 別途保持している場合は、そちらを優先すること。 本スキルに同梱される ai-loop ドキュメント（`references/` 配下。導入先で正本を 別途保持している場合はそちらを優先する）の `references/execution-runbook.md` に定義された 1 サイクル（変更対象ファイル取得 → W チェック → `arbiter.py` 裁定 → record 保存 → 分岐後の行動）を 実行するための手順スキル。判定ロジック・provenance スキーマの正本は runbook 側にあり、本スキルは それらを実行するための **委託プロンプト定型** と **手順の要約** のみを持つ（二重定義しない）。 詳細な手順・分岐表は都度 `references/` を読みに行く（progressive disclosure。本 SKILL.md は 手順の要点のみを持ち、runbook 等の全文を転記しない）。 > **参照解決順（導入先で必ずこの順に探す）**: 本 Skill は **上流リポジトリ基準の `docs/**` パスを直接参照しない**（#1232 AC-9 で除去済み）。`docs/**` は `install.sh --claude` / plugin（Claude marketplace）/ Codex の **3 経路とも配布対象外**であり、書いた時点で導入先では必ず空振りするためである。したがって解決順は次のとおり: (1) **`` 配下の同梱物**（`references/` / `scripts/` / `schemas/`）を第一に読む → (2) 導入先リポジトリが独自の正本（上流の `docs/workflows/ai-loop/` に相当するもの）を保持していればそちらを優先する → (3) いずれでも解決できなければ **「正本 `` を参照できなかった」と明示**し、本 Skill 内の記述を代替正本として扱い、推測で内容を補わない。**plugin root 直下に `docs/` を探しに行かないこと**: plugin が配布するのは `agents` / `commands` / `skills` / `rules` 等の定義ディレクトリのみで `docs/` を配布対象として認識せず、plugin root 配下に相当する配布物が存在しないため必ず空振りする（クラス A の rules 参照が plugin root 配下で解決できるのは `rules/` が実際に配布されるからであり、この非対称を `docs/**` に持ち込まない）。 ## 前提 - **C-1 PASS・C-2 完了済み**であること（`references/execution-runbook.md` §2 前提）。 本サイクルは C-3' ゲートの位置づけであり、C-1/C-2 未完了の変更には使わない。 この C-1 の実施結果（`PASS`）を Step 1 の入力 `gates.c1` にそのまま渡す（#780 Slice B）。 - 対象は **lite 帯候補の変更**（`references/lite-criteria.md` §2 の 4 軸を満たしうる変更）。 high-risk / critical 相当や boundary=touches-HO が明らかな変更には使わない （使っても flow フェーズで即 human escalate になる）。 - 適用制限（Phase 1 rollout eligibility）は同梱 `references/rollout-policy.md` を正本とする （導入先が独自正本を保持する場合はそちらを優先）。導入先での適用は **①ho-paths の 導入先確定 ②LoopSpec `scope.allowed_paths` 宣言** の 2 条件が前提。恒久定義 （責務・terminal state・C-3'/Human C-3 経路）の正本は同梱 `references/00_concept.md`。 本サイクルは導入先の本番承認フロー（ゲート・hook 等の統制機構）からは呼ばれない（不変）。 - **auto-approve 方針（Phase 1）**: lite 4 軸（`references/lite-criteria.md` §2）を 申告制・AND・判定不能→false で満たせば、**実機能も `AUTO_APPROVED` 対象に含めてよい** （docs 級限定ではない）。`size_ok` は申告するが、arbiter が `changed_files` の 実ファイル数で機械検証する（`SIZE_OK_MAX_FILES`=2。実ファイル数が 2 を超えて `size_ok=true` を申告すると priority 1.9 で human escalate。#780 Slice C）。 他 3 軸（`no_new_design`/`follows_pattern`/`reversible`）は引き続き申告制のまま。 - **裁定記録・摩擦台帳の保存先は導入先プロジェクトで定義する**（本スキルは強制しない）。 既定案として、導入先の作業ディレクトリ配下に run 単位の裁定 record 用サブディレクトリ （例: `<作業ディレクトリ>/ai-loop-runs/`）を設ける配置が参考になるが、導入先の ディレクトリ規約を優先すること。 ## CLI 依存の分離（`bin/plangate` は配布されない） PlanGate の CLI（`bin/plangate`）は **plugin / `install.sh --claude` / Codex の どの経路でも導入先に配置されない**（Human 決定 #1144: plugin が配るのは読み物層のみで、 enforcement 層〔`scripts/hooks/`〕と CLI は含めない）。本スキルの手順を CLI 必須／ CLI 不要で分けると次のようになる。 | 手順 | CLI 依存 | 導入先での実行可否 | | --- | --- | --- | | Step 0 breakdown-gate 粒度判定 | **不要** | 実行可（スキル判断のみ） | | Step 1 入力の組み立て（lite 4 軸・`gates`・`run`） | **不要** | 実行可 | | Step 1 `plan_package` の組み立て・LoopSpec 派生 | **不要** | 実行可（同梱 `scripts/plan_package.py`） | | Step 2 W チェック | **不要** | 実行可 | | Step 3 arbiter 裁定 | **不要** | 実行可（同梱 `scripts/arbiter.py`。`python3` があればよい） | | Step 4 record の保存 | **不要** | 実行可 | | Step 5 分岐後の行動（exec / セルフレビュー / PR） | **不要** | 実行可 | **結論: ai-loop の 1 サイクルは CLI 非依存で完結する。** `python3` と `git` があれば 導入先だけで回せる。 CLI（＝上流リポジトリの clone）が要るのは、本スキルの外にある次の作業だけである。 これらに到達したときは「上流リポジトリの clone が必要」と明示して停止し、 **CLI が無いことを理由に手順を省略した、と誤読させない**こと: | CLI 必須の作業 | 必要なもの | 本スキルとの関係 | | --- | --- | --- | | PlanGate 本番フロー（WF-00〜07）の `plangate plan` / `exec` / `validate` | 上流リポジトリの clone | **本スキルの範囲外**（`/ai-dev-workflow` 側。ai-loop は本番フローの置き換えではない） | | `plangate doctor --check-settings` による settings 配線検証 | 上流リポジトリの clone | 本スキルの範囲外（導入先では `.claude/settings.json` を直接確認する） | | hook による機械強制（EH-1〜EH-13） | `scripts/hooks/`（**配布外** / #1144） | 本スキルの範囲外。導入先では **arbiter の裁定と実行者の規律が担保層**になる | > **`plangate ai-loop run …` は存在しない。** `run TASK-XXXX` は `/ai-loop-workflow` > コマンドの引数仕様であって CLI サブコマンドではない（CLI 入口を設けるか否かは > issue #982 で未決）。 ## Step 0: breakdown-gate による粒度判定（#780 Slice B） `breakdown-gate` スキル（同梱・または導入先の等価スキル）でタスク粒度を 判定する（理想 / 許容 / 分割必須の 3 段階）。判定結果を `gates.breakdown` へ変換する: - 理想 / 許容 → `"pass"` - 分割必須 → `"pass"` 以外の値（例 `"split-suggested"`）。arbiter は priority 1.7 で human escalate する（分割してから再度サイクルへ） ## Step 1: 入力の組み立て ### `harness_version.corpus_hash` は producer から取る（#1299） `corpus_hash` は **`scripts/ai-loop/corpus_hash.py` が単一 producer** である。 run 開始時に実行して得た値を注入し、run 終了時にもう一度実行して `--harness-version-end` に渡す（AC-12 の drift 検査はこの 2 値の byte 一致を見る）。 ```sh python3 scripts/ai-loop/corpus_hash.py # 既定 scope = full（111 ファイル） python3 scripts/ai-loop/corpus_hash.py --explain # 対象の全数と各ファイルの digest ``` 対象は carve-out（`scripts/ai-loop/**` 等）に加えて **enforcement 層** （`scripts/hooks/**` / `check-approval-token-write.sh` / `bin/plangate` / `schemas/*.schema.json` / `.codex`・`.cursor` の hooks）を含む。#1299 以前の定義は enforcement を含んでおらず、**HO patch で hook を +158/−5 しても値が動かなかった**。 **機械強制は未接続（follow-up）**: `run_evidence.py` は注入値の**形式**（`sha256:`+64hex）と run 中不変（AC-12）しか検査せず、**producer の計算値と照合しない**。したがって producer を呼ばずに任意の 64hex を注入できる。照合を `run_evidence.py` に入れると golden fixture 8 件（`corpus_hash` がプレースホルダ `sha256:0…0`）が byte 不一致に なるため、fixture の再生成とセットで別 PBI とする。現状は `tests/extras/ta-84-corpus-hash.sh` の TC-06 が**未接続であること自体を実測で固定** しており、接続されたらそのテストが赤くなって本節の更新を強制する。 `changed_files` を決定する: - **計画時**（exec 前の C-3' 裁定）: plan の Files to Touch を使う - **再裁定時**（実装後・PR 前の再確認）: `git diff --name-only ...HEAD` の実差分を使う lite 4 軸（`references/lite-criteria.md` §2）をそれぞれ根拠つきで宣言する。**いずれかの軸が 判定不能なら false**（AC-8 安全側、虚偽宣言禁止）。 `allowed_paths` は LoopSpec の `scope.allowed_paths` 宣言をそのまま渡す（#809）。 - `size_ok`: 変更規模が light 相当以下か（ファイル数 1〜2 目安）。**申告するが、 arbiter が `changed_files` の実ファイル数で機械検証する**（`SIZE_OK_MAX_FILES`=2。 実ファイル数が 2 を超えて `size_ok=true` を申告すると priority 1.9 で human escalate。#780 Slice C） - `no_new_design`: 新規設計がないか（既存構造の枠内か） - `follows_pattern`: 既存パターンを踏襲しているか（ミラー実装か） - `reversible`: 可逆か（`git revert` 一発等、機械的な巻き戻し手順があるか） `class` は `merge` を含む変更なら `"merge"`（即 human escalate）、含まなければ `"no-merge"`。 `target_sha` は対象コミットの SHA。 `gates`（任意・#780 Slice B）は plan 品質ゲート（priority 1.7）の入力。**Step 0** （breakdown-gate 判定）の verdict を `gates.breakdown` に（`理想`/`許容` → `"pass"`、 `分割必須` → それ以外の値。`"pass"` 以外はすべて未充足扱い）、**Step 1 の前提** （C-1 実施結果）を `gates.c1` に（`"PASS"` のみ通過）設定する。**gates 省略も 入力エラーにはならないが、priority 1.7 で human escalate に倒れる**（後方互換・ 安全側。以前の auto-approve 経路を壊さないためには gates を両方 `"PASS"`/`"pass"` で渡す必要がある）。 `run`（任意）は `run_id`（`run-NNN` 連番）・`round_index`（**初回呼び出し=1**、再試行ごとに +1。1 起点。metrics は round_index==1 を初回 sentinel に first_pass 判定するため 0 起点不可）・`task_id`（対象 PBI）を刻む。省略可だが、省略すると metrics 集計対象外（legacy）になる。 `production` / `plan_package`（任意・TASK-0872）: **Plan-first 正式入口（`ai-loop run TASK-XXXX`）から開始した production run では両方を必ず入力に含める**（この入口は **`/ai-loop-workflow` の引数仕様**であり、**PlanGate CLI のサブコマンドではない** — 上記「CLI 依存の分離」を参照）。`scripts/plan_package.py`（`arbiter.py` と同ディレクトリ）で Plan Package（pbi-input / plan / todo / test-cases + C-1/C-2 evidence）の presence・evidence 判定・hash を検証して `plan_package` ブロックを組み立て、`production: true` を宣言する。`production: true` で `plan_package` が欠落・構造不正なら priority 1.6 で escalate、reviewer snapshot 三つ組不一致・`source_sha != target_sha` は priority 1.65 で blocked（フィールド契約・stale 規則・LoopSpec 派生マッピングの正本 = `references/c3-prime-contract.md`）。LoopSpec は同モジュールの `derive_loopspec()` で Plan Package から決定論派生する（手入力しない）。非 production の PoC 実験 run では両フィールドとも省略可（既存挙動不変・additive）。 入力 JSON の例: ```json { "changed_files": ["docs/example.md"], "allowed_paths": ["docs/example.md"], "lite": { "size_ok": true, "no_new_design": true, "follows_pattern": true, "reversible": true }, "class": "no-merge", "verdicts": { "model_a": "approve", "model_b": "approve", "reject_category": null, "model_c": null, "model_d": null }, "target_sha": "abc1234", "gates": { "c1": "PASS", "breakdown": "pass" }, "run": { "run_id": "run-022", "round_index": 1, "task_id": "TASK-XXXX" } } ``` ## Step 2: W チェック（サブエージェント 2 体・独立並列） Model A / Model B を Agent ツールで **独立に**（相手の結論を見せずに）並列起動する。 返答は `verdict` / `reject_category`（reject 時のみ）/ `理由` の 3 行 raw 指定で受け取る。 ### Model A（順方向・設計妥当性）委託プロンプト定型 ```text 対象: （target_sha: ） 役割: 変更が「正しく作られているか」を検証する。 観点: 設計妥当性・受入基準（AC）網羅・スコープ整合。計画中の『検証済み』申告には**証跡（実行出力の貼付）**があるか確認し、なければ未検証として扱う。 他モデルの結論は見せない・参照しない。 出力形式（常に3行、raw）: verdict: approve | reject reject_category: none (approve時) | ho_path_contact | permission | irreversible | security_break | public_api | data_integrity | migration | auth_change | logic | performance | test_shortage | documentation | format | naming (reject時) 理由: <1〜3文> ``` ### Model B（逆方向・adversarial）委託プロンプト定型 ```text 対象: （target_sha: ） 役割: 変更が「どう壊れるか」を検証する（adversarial）。 観点: 失敗モード・境界値・悪用経路・想定外の入力。加えて、LoopSpec の external_sources に列挙された出典について、記録物（裁定 record・plan-memory・摩擦台帳・run 記録への追記分）の diff を対象に、当該出典の内容がコピーされている箇所を探し、出典（URL / issue・PR 番号）の併記がない転記があれば違反として指摘する。検出できるのは逐語（高一致率）コピーのみ — 言い換え転記・provenance の真偽は判別できず maker の誠実申告に依存する（限界の自己開示）。 他モデルの結論は見せない・参照しない。 出力形式（常に3行、raw）: verdict: approve | reject reject_category: none (approve時) | ho_path_contact | permission | irreversible | security_break | public_api | data_integrity | migration | auth_change | logic | performance | test_shortage | documentation | format | naming (reject時) 理由: <1〜3文> ``` `reject_category` は `references/flow-detect.md` §3.2.1 のカテゴリマッピング表に照合可能な文字列で 記録する。一致しないカテゴリは分類器側で `critical`（human escalate）にフォールバックされる。 **reject_category は enum の英小文字値をそのまま（verbatim）返させる。和訳・言い換え・自由記述は禁止**（例: 『ロジック変更』ではなく `logic`）。非一致は分類器が critical 扱いになる（安全側）ため裁定は壊れないが、意図しない escalate を生む。 ## Step 3: `arbiter.py` へ入力し裁定を得る `arbiter.py` は **本スキルディレクトリ直下の `scripts/arbiter.py` として同梱** される （同梱 `references/` と対になる形で配布される）。冒頭「パス表記の規約」のとおり `` を解決してから起動する。cwd がスキルディレクトリとは限らないため、 **`scripts/arbiter.py` をそのまま cwd 相対で叩かないこと**: ```sh # はこの SKILL.md が置かれているディレクトリ（冒頭の表を参照） ARBITER="/scripts/arbiter.py" python3 "$ARBITER" --input /path/to/input.json # または stdin 経由: echo '{...}' | python3 "$ARBITER" ``` > `arbiter.py` は `sh` / `bash` で起動すると `exit 2` で止まる（#1169 の polyglot > ガード）。必ず `python3` で起動する。 | exit code | decision | 動作 | | --------- | ----------------- | --------------------------------------------------------------------------------- | | `0` | `AUTO_APPROVED` | 自動承認。provenance 刻印（正本）を保存 | | `2` | `HUMAN_ESCALATED` | **停止して人間へ escalate**（`w_check` / `boundary_check` / `lite_check` を提示） | | `3` | `BLOCKED` | 当該変更を不採用。理由（stderr の裁定サマリ）を記録 | | `1` | 入力エラー | stderr の理由に従い入力 JSON を修正して再実行 | 分岐表・severity 分類・優先順位ロジックの正本は `references/execution-runbook.md` §2(5) および `references/decision-table.md`。本スキルはこれを再定義しない。 ## Step 4: record の保存 裁定 record（decision record）の保存先は**導入先プロジェクトで定義する**（本スキルは 配置を強制しない）。参考として、run 単位のディレクトリ（例: `<導入先の作業ディレクトリ>/ ai-loop-runs/`）へ、裁定日時とコミット SHA を含むファイル名で保存する運用が考えられる: ```sh mkdir -p <導入先で定義した保存先> python3 "/scripts/arbiter.py" --input /path/to/input.json \ > "<導入先で定義した保存先>/$(date -u +%Y%m%dT%H%M%SZ)-$(git rev-parse --short HEAD).json" ``` - `AUTO_APPROVED` の record のみ **provenance 刻印（正本）** - `HUMAN_ESCALATED` / `BLOCKED` の record は **audit record（暫定）** （`references/execution-runbook.md` §2(4) 注記） ## Step 5: 分岐後の行動 - **exit 0（AUTO_APPROVED）**: exec → 強化セルフレビュー（diff-audit スキル全観点 + 導入先の plan-review readiness 相当の観点）→ PR 作成 → CI/AI レビュー指摘対応ループ （`MERGE_READY` まで） - **exit 2（HUMAN_ESCALATED）**: **停止して人間へ**。`w_check` / `boundary_check` / `lite_check` の内容を提示し、人間の判断を仰ぐ。AI が自己解決してはならない - **exit 3（BLOCKED）**: 当該変更を採用しない。理由を audit record に記録して終了 - **severity=minor/low の不一致のみ**、Model C（セキュリティ・認証・権限観点）/ Model D（後方互換・データ整合観点）の委託プロンプト定型で再裁定する （`references/flow-detect.md` §3.3）。委託プロンプトは Model A/B と同じ 3 行 raw 形式・ 独立起動を踏襲し、観点のみ以下に差し替える: - Model C: 「セキュリティ・認証・権限の観点で、この変更が悪用・権限昇格・認証バイパスを 許さないかを検証する」 - Model D: 「後方互換性・データ整合性の観点で、この変更が既存の契約やデータ状態を 壊さないかを検証する」 C/D の verdict を得たら、**Step 1 の入力 JSON の `verdicts.model_c` / `verdicts.model_d` に設定し（`reject_category` は Model B のものを保持）、 `arbiter.py` を再実行**する（Step 3〜4 を繰り返す）。C/D 裁定を経た record には `w_check.severity` / `w_check.model_c` / `w_check.model_d` が刻印される （`references/decision-table.md` §5）。 ## Step 5.5: exec 差分への rubric grader AUTO_APPROVED → exec 完了後・PR 作成前に、maker と独立の sonnet サブエージェント （grader）へ exec 差分を委託する（W チェックと同じ maker≠grader・独立文脈方式）。 入力 = maker 差分 + 計画の Goal/確定文言。 ### rubric 5 項目（レビュー 5 観点からの docs-run 翻訳） 以下の表は maker がそのまま SKILL.md に転記する確定版。定義の正本は導入先の レビュー原則（5 観点: 可読性/拡張性/パフォーマンス/セキュリティ/保守性）にあり、 本表はそれを再定義せず docs-run に適用可能な fail 条件へ翻訳したものである。 | # | 基準（レビュー 5 観点からの docs-run 翻訳） | fail 条件（判定可能形） | | --- | ------------------------------------------- | ------------------------------------------------------------------------------------------------------------- | | 1 | **正確性・正本整合**（保守性/可読性由来） | 差分中のファイルパス・コマンド・参照リンクに実在しないものが 1 つ以上ある、または参照正本と矛盾する記述がある | | 2 | **要件適合**（計画との 1:1） | 計画の Goal・確定文言に対し宣言外の変更、または要求要素の欠落がある | | 3 | **文体・構造踏襲**（可読性由来） | 追記が既存文書の見出し階層・表形式・文体から逸脱している | | 4 | **境界安全**（セキュリティ由来） | 承認境界・HO 境界・停止規則を弱める/緩和する記述を含む | | 5 | **重複定義回避**（拡張性/保守性由来） | 既存正本に定義済みの規範を参照でなく再定義している | （パフォーマンス観点は docs-run では該当稀のため基準 1 に「実行例の到達性」として包含。 5 観点との対応は各行に明記し重複定義しない — 定義の正本は導入先のレビュー原則のまま） ### grader 委託プロンプト定型（W チェック定型の形式踏襲） ```text 対象: （maker 差分） 役割: この差分を上記 rubric 5 項目で採点する。 計画: <計画 Goal / 確定文言> 観点: rubric 5 項目（本節の表）。各項目を pass/fail で判定する。 出力形式（常に3行、raw）: verdict: pass | fail failed_criteria: feedback: <1〜3文> ``` 判定ブロック（上記 3 行）に**続けて、基準ごとの証跡ブロックを別掲**する（行数自由・ 判定ブロックの 3 行 raw 形式とは別領域）: - **fail とする基準ごとに、差分からの引用（行）を必須添付する。引用のない fail は無効** とし、maker は再試行前に grader へ差し戻せる - pass にも基準ごとに 1 行の根拠を証跡ブロックへ書く（全 5 行。「問題なし」のみは不可） - `feedback:` 行自体は 1 行に収める（複数論点はセミコロン区切り。詳細は証跡ブロックへ） ### 再試行ループ - `verdict: fail` → feedback（引用込み）を添えて maker に再試行を委託する。**上限 2 回** - 上限超過 → `HUMAN_ESCALATED` として扱い、**grader の全出力（引用込み）を人間へ提示** （false-fail 連鎖を人間が判断可能にする） - grader 出力は裁定 record と同様、run 記録へ全文貼付する（監査可能性。record 保存先は 導入先プロジェクトで定義） ## Step 6: RunEvidence + passive PBI live-shadow capture（shadow-only） terminal RunEvidence が **concrete 40-hex `final_head_sha`** を持つ Evidence 発行時に、 **repository-visible な observed signal が実際に存在する場合だけ** PBI materializer の passive capture を追加してよい。signal が無い run にダミー signal / capture を作ってはならない。 ```text observed repository source ↓ normalized admission signal ↓ pbi_materializer.py --capture-signal ↓ passive capture artifact ↓ run_evidence.py --evidence-ref --evidence-ref ↓ RunEvidence ↓ independent review / live-shadow evaluation ``` ### 6.1 capture（RunEvidence finalize 前） capture は **stdout-only** の primitive なので、保存先は呼び出し側が repo 相対 path として決める。 `captured_at` は run の `started_at..completed_at` 内、`runtime_head_sha` は後続 RunEvidence の `final_head_sha` と一致させる。 ```sh python3 "/scripts/pbi_materializer.py" \ --capture-signal "" \ --capture-task-id "TASK-XXXX" \ --capture-run-id "" \ --captured-at "" \ --runtime-head-sha "<40-hex HEAD>" \ --capture-ref "" \ --format json \ > "" ``` normalized signal の `source_ref` は capture artifact 自身ではなく、実在する **repository-visible upstream artifact** （feedback snapshot / Issue snapshot / delivery record / failure evidence 等）を指すこと。外部URLや一時的なchat本文だけを live evidenceとして扱わず、まずrepo-visible evidenceへmaterializeしてから参照する。raw transcript / hidden CoT を signal に入れない。 ### 6.2 RunEvidence へ束縛 通常の `run_evidence.py` 呼び出しに、少なくとも upstream source と capture artifact の 2 ref を `--evidence-ref` で追加する。 ```text --evidence-ref --evidence-ref ``` RunEvidence producer / verifier の既存 terminal-state・schema・privacy 契約は変更しない。 capture のために terminal decision / final_head_sha / completed_at を書き換えてはならない。 ### 6.3 capture 後の扱い - capture 成功だけでは `live_shadow` 評価成立ではない。RunEvidence 保存後に `capture_ref + run_evidence_ref` の binding 検証が必要。 - oracle / expected decision を capture agent 自身が自動付与しない。独立 reviewer / evaluator の review artifact を後段で接続する。 - `final_head_sha="unavailable"` の run（典型例: delivery record を持たない一部の `BLOCKED`）では passive live capture を作らず、live-shadow evidence として数えない。`source_sha` / `target_sha` を代用しない。 - capture 失敗は既存 terminal decision を変更しないが、**live-shadow evidence として数えない**。 失敗を隠して historical/synthetic case を live と再ラベルしてはならない。 - `no_action` も source Issue/PBI を close / suppress する authority を持たない。 - 本 Step は shadow Evidence 収集のみで、PBI write / close / merge / Harness live mutation を行わない。 ### 6.4 Evidence collector（実runでの推奨経路） 実runでは primitive の stdout を手作業で配置せず、同梱 collector を使って `capture -> blind review packet -> reviewed admission case` を create-or-reuse-identical で保存する。 ```text source artifact -> collector capture -> RunEvidence finalize（source_ref + capture_ref を evidence_refs へ） -> collector packet -> independent reviewer が oracle artifact を別途作成 -> collector case -> pbi_materializer --eval-admission-batch ``` capture: ```sh python3 "/scripts/pbi_live_shadow_collector.py" \ --repo-root "" capture \ --signal "" \ --task-id "TASK-XXXX" \ --run-id "" \ --captured-at "" \ --runtime-head-sha "<40-hex final HEAD>" \ --capture-ref "docs/working/TASK-XXXX/evidence/pbi-live-shadow//capture.json" ``` RunEvidence 保存後: ```sh python3 "/scripts/pbi_live_shadow_collector.py" \ --repo-root "" packet \ --capture-ref "docs/working/TASK-XXXX/evidence/pbi-live-shadow//capture.json" \ --run-evidence-ref "docs/working/TASK-XXXX/evidence/pbi-live-shadow//run-evidence.json" \ --packet-ref "docs/working/TASK-XXXX/evidence/pbi-live-shadow//review-packet.json" ``` review packet は maker の actual decision を含まない。Reviewer は `blind_review_source_ref` の upstream source から expected admission decision を決め、oracle を **別artifact** として作る。 collector は reviewer identity / independence を自己証明しない。 oracle artifact は同じ `TASK-XXXX/evidence/pbi-live-shadow//` 配下へ保存し、 raw transcript / hidden CoT / session log 等の privacy-forbidden field を含めない。 oracle の最小 contract: ```json { "schema_version": 1, "domain": "plangate.pbi-live-shadow-admission-oracle/v1", "case_ref": "LIVE-ADMISSION-...", "packet_ref": "", "packet_hash": "sha256:...", "reviewed_source_ref": "", "reviewed_source_sha256": "sha256:...", "expected_admission_decision": "materialize | no_action | discover_more", "independent_review_asserted": true, "maker_actual_not_consulted_asserted": true } ``` oracle 作成後: ```sh python3 "/scripts/pbi_live_shadow_collector.py" \ --repo-root "" case \ --packet-ref "" \ --oracle-ref "" \ --case-artifact-ref "docs/working/TASK-XXXX/evidence/pbi-live-shadow//admission-case.json" ``` collector の保存は同一内容の retry のみ再利用可能。既存artifactの内容が異なる場合は fail closed。 oracle は `expected.oracle_ref` で束縛し、source `evidence_refs[]` へ混ぜない。 collector は PBI / Issue / RunState / Harness / merge を変更しない。 ### 6.5 Live-shadow inventory（read-only） tracked live-shadow case が増えたら、repository全体を read-only で再走査する: ```sh python3 "/scripts/pbi_live_shadow_collector.py" \ --repo-root "" inventory ``` inventory は次だけを探索する: ```text docs/working/TASK-*/evidence/pbi-live-shadow/**/admission-case.json ``` 各caseについて: - case artifact / capture / RunEvidence / oracle が同じ TASK live-shadow namespace に属するか再確認する - existing admission evaluator contractで再検証する - duplicate logical `case_ref` は全件invalidにする - invalid caseを集計から黙って除外せず `invalid_case_artifacts[]` に残す - historical corpusをliveへ昇格しない - synthetic fixtureをtracked live countに含めない 主要出力: ```text tracked_live_case_total evaluated_case_total invalid_case_total observed_admission_decisions observed_source_kinds rollout_quality ``` 0件は0件のまま扱う。未観測を成功率0%やrollout完了へ変換しない。 またinventoryはrepository chainの再検証であり、次は証明しない: ```text runtime_execution_verified = false source_preexistence_verified = false reviewer_identity_verified = false representative_coverage_claim_allowed = false quality_acceptance_decided = false ``` したがって `tracked_live_case_total > 0` は「tracked chainが存在する」ことだけを意味し、 real runtime execution / representative coverage / write-capable rollout の承認には使わない。 ### 6.6 Live Materialization review（post-admission） Admission live case が reviewer expectation と実評価の両方で `materialize` に一致した場合だけ、 post-admission Materialization shadow へ進む。 collector は payload / existing-work snapshot / oracle を**生成しない**。別工程で repository-visible artifact として用意されたものを hash で束縛し、既存 `evaluate_shadow_batch()` 互換caseへ組み立てる。 必要artifact: ```text admission-case.json materialization-payload.json existing-work.json materialization-oracle.json ``` すべて同じ: ```text docs/working/TASK-XXXX/evidence/pbi-live-shadow// ``` 配下へ置く。 materialization oracle の最小contract: ```json { "schema_version": 1, "domain": "plangate.pbi-live-shadow-materialization-oracle/v1", "case_ref": "LIVE-MATERIALIZATION-...", "admission_case_ref": "", "admission_case_hash": "sha256:...", "payload_ref": "", "payload_hash": "sha256:...", "existing_work_ref": "", "existing_work_hash": "sha256:...", "expected": { "decision": "create_new | update_existing | link_only", "matched_ref": null, "readiness_status": "ready | blocked", "readiness_route": "" }, "independent_review_asserted": true, "maker_actual_not_consulted_asserted": true } ``` case assembly: ```sh python3 "/scripts/pbi_live_shadow_collector.py" \ --repo-root "" materialization-case \ --admission-case-ref "" \ --payload-ref "" \ --existing-work-ref "" \ --oracle-ref "" \ --case-artifact-ref "docs/working/TASK-XXXX/evidence/pbi-live-shadow//materialization-case.json" ``` collector は以下を再検証する: - Admission case が reviewer expectation / actual ともに `materialize` で一致 - admission case / payload / existing-work / oracle の同一TASK namespace - oracle が admission case / payload / existing-work の exact hash を束縛 - oracle が maker actual を保存していない - assembled case が既存 `_validate_shadow_batch()` を通る - oracle は `expected.oracle_ref` にのみ置き、source `evidence_refs[]` へ混ぜない tracked Materialization case の再集計: ```sh python3 "/scripts/pbi_live_shadow_collector.py" \ --repo-root "" materialization-inventory ``` 主要出力: ```text observed_materialization_decisions missing_materialization_decisions duplicate_false_positive_rate duplicate_false_negative_rate decision_mismatch_count readiness_mismatch_count ``` 0分母は `null` のまま扱う。1件の `create_new` だけで duplicate FN が 0% とは判断しない。 また: ```text runtime_execution_verified = false source_preexistence_verified = false reviewer_identity_verified = false representative_coverage_claim_allowed = false quality_acceptance_decided = false ``` を維持する。Materialization inventory はduplicate FP/FNを**測るためのread-only projection**であり、 write-capable rolloutのGateではない。 ### 6.7 Live collection plan（read-only / non-quota） admission / materialization inventory の current gap をまとめて確認する: ```sh python3 "/scripts/pbi_live_shadow_collector.py" \ --repo-root "" collection-plan ``` collection plan が使う coverage basis は **reviewed expected decision**。 maker の actual decision は model behavior の観測であり、ground-truth coverage として数えない。 ```text admission: reviewed expected = materialize | no_action | discover_more materialization: reviewed expected = create_new | update_existing | link_only ``` materialization target は reviewed admission `materialize` が観測済みの場合だけ: ```text prerequisites_satisfied = true collector_path_available = true real_runtime_observation_available = null ``` となる。これは「そのcaseを作れ」という指示ではなく、自然に実runで遭遇した場合に **collector経路が成立している** ことだけを示す。現在real runtime observationが存在するかは未検証であり、`null` のまま扱う。 必ず次の境界を維持する: ```text opportunistic_observation_only = true synthetic_case_generation_for_coverage_allowed = false historical_relabeling_allowed = false decision_coverage_quota_defined = false source_kind_coverage_requirement_defined = false representative_coverage_claim_allowed = false coverage_complete_implies_representative = false observation_gap_is_quota = false observation_gap_is_case_generation_instruction = false coverage_gap_basis = reviewed_expected_decisions maker_actual_counts_as_ground_truth_coverage = false runtime_execution_verified = false quality_acceptance_decided = false ``` したがって observation gap を埋めるために synthetic case を作成したり、 historical case を live へ昇格したりしてはならない。 collection-plan の出力を保存して後から再利用する場合は、必ず判断直前に再実行する。 plan は元になった inventory projection の canonical SHA-256 を持つ。 ```text inventory_binding.admission_inventory_hash inventory_binding.materialization_inventory_hash inventory_binding.combined_inventory_hash plan_reuse_without_reinventory_allowed = false runtime_head_bound = false repository_commit_verified = false inventory_hashes_are_commit_identity = false ``` hash は「このplanがどのinventory内容から導出されたか」を識別するためのもので、 Git commit / runtime execution / Evidence時系列真正性の証明ではない。 保存済みplanのgapをそのまま実行判断に使わず、repository evidenceが変わっていないか `collection-plan` を再実行して確認する。 ### 6.6 Completion status（read-only） 実装を増やす前に、残課題がどの種類かを分類する。 ```sh python3 "/scripts/pbi_live_shadow_collector.py" \ --repo-root "" completion-status \ --context "" ``` context は GitHub / Human 側で確認した事実を明示的に渡す: ```json { "latest_full_test_green": true, "design_dependency_finalized": false, "generalization_claim_required": false, "representative_live_evidence_review_ref": null, "quality_review_ref": null, "isolated_generalization_review_ref": null } ``` collector はこれらの外部状態を自己検証しないため: ```text assertions_independently_verified = false latest_full_test_status_verified_by_collector = false design_dependency_status_verified_by_collector = false ``` を維持する。 review ref が指定された場合は repository-visible regular file の実在と byte SHA-256 まで束縛するが、 内容妥当性 / reviewer identity / independence は証明しない。 ```text semantic_content_verified = false reviewer_identity_verified = false independence_verified = false ``` `next_action` は残課題の分類だけを行う: ```text fix_repository_or_evidence_integrity finalize_design_dependency collect_opportunistic_real_live_evidence perform_human_evidence_and_quality_review human_rollout_decision ``` 重要: ```text rollout_completion_machine_decidable = false rollout_complete = false automatic_write_activation_allowed = false machine_completion_decision_allowed = false machine_write_activation_allowed = false ``` したがって completion-status は **停止条件 / 次行動の整理** 用であり、 rollout完了・quality acceptance・write activationを自動承認しない。 ## 禁止事項 - lite 宣言の虚偽（判定不能を `true` 側に倒す） - W チェック結果の改変（Model A/B/C/D の verdict を都合よく書き換える） - touches-HO の迂回（boundary 判定を回避する目的でのファイル分割・命名変更） - escalate の自己解決（exit 2 を人間に提示せず AI 単独で処理を続行する） ## 関連ドキュメント 本スキルは以下のドキュメント（本スキル同梱の `references/` 配下。導入先が 別途正本を保持する場合はそちらを優先）を前提として動作する: - `references/execution-runbook.md` — 1 サイクル手順の正本 - `references/lite-criteria.md` — lite 4 軸・AC-8 安全側 - `references/flow-detect.md` — W チェック・severity 分類・C/D 裁定 - `references/decision-table.md` — Decision table・provenance schema - `references/c3-prime-contract.md` — `plan_package` フィールド契約・stale 規則・LoopSpec 派生 - `scripts/arbiter.py` — 入力 JSON 仕様（docstring） - `scripts/plan_package.py` — Plan Package 検証と `derive_loopspec()` - `schemas/run-evidence.schema.json` — run evidence の JSON Schema - `references/ho-paths.md` — HO（Hardening Override）パス一覧（**プロジェクト固有・導入先で確定**） - 導入先の強化セルフレビュー観点（存在する場合） （いずれも `` 配下の同梱物。冒頭「パス表記の規約」を参照）