Codex verified delivery kit

この directory は、Codex を使う Web アプリ開発で、一件の変更を意図から本番観測まで追跡するコピー用テンプレートである。各書式は「書いた」ことではなく、判断に必要な証拠を exact fingerprint へ結ぶために使う。

原則と理由は 13 章、技術基準は 05 章、セキュリティ基準は 06 章、創業者時間は 09 章、agent 委任は 10 章、AI の品質・価値・原価・継続は 12 章を正本とする。

含まれる 9 書式と参照例

書式	決めること
AGENTS.md.template	repo 全体の正確な command、invariant、review、完了条件
NESTED-AGENTS.md.template	subtree 固有の差分規則
TASK-BRIEF.md	今回の成果、非対象、受入条件、risk、必要証拠
ADR.md	重要な選択、代替、結果、移行、再検討
THREAT-MODEL.md	変更で増える脅威、control、test、monitor、残余 risk
EVAL-PLAN-AND-RESULT.md	test/eval の事前計画、case、version、実行結果、gate
PR-HANDOFF-AND-REVIEW.md	exact SHA の差分と証拠索引、review 判断
RELEASE-RECORD.md	artifact、migration、露出、monitor、rollback、本番結果
INCIDENT-LEARNING.md	事故の事実、因果、復旧、再発防止 control
EXAMPLE-BILLING-GRACE.md	架空 webhook 変更を全証拠へつないだ記入例

推奨配置

AGENTS.md
docs/
  adr/
    ADR-0001-<slug>.md
  delivery/
    CHG-YYYYMMDD-<slug>/
      TASK.md
      THREAT.md          # trigger 時だけ
      EVAL.md            # 挙動変更または AI 変更
      PR.md
      RELEASE.md         # production 変更
    CHG-YYYYMMDD-incident-<slug>/
      INCIDENT.md        # 事故ごとに新しいresponse bundle。originating CHGは別field

ファイル名や directory は repo に合わせて変えてよい。change_id と exact fingerprint の対応は変えない。

導入

AGENTS.md.template を repo root の AGENTS.md へコピーする。
placeholder を実在する directory、command、invariant に置き換え、該当しない例を削る。
局所 command・規則だけが異なる場合、NESTED-AGENTS.md.template を対象 subtree の AGENTS.md へコピーする。
変更ごとに CHG-YYYYMMDD-<slug> を一つ発行し、必要な書式だけを上記 directory へコピーする。incident は原因が未確定でも新しい response change_id を発行し、originating/remediation IDs を別 field で結ぶ。
<<required: ...>> は実値へ置換する。該当しない欄は空欄にせず N/A — 理由 とする。
test、eval、review 後にコードを変えたら、該当 evidence snapshot を再取得する。

同じ directory に AGENTS.override.md がある場合、Codex は通常それを AGENTS.md より先に選ぶ。temporary override は理由と期限を明記し、目的が終わったら削除する。意図しない override が残っていないかも、次の読込確認で調べる。

Codex が active instruction を読めるか、repo root と対象 subtree の両方から確認する。

codex --sandbox read-only --ask-for-approval never exec "List the instruction files you loaded and summarize the active repository rules. Do not edit files."
codex --cd path/to/subtree --sandbox read-only --ask-for-approval never exec "List the instruction files you loaded and explain which local rules override broader guidance. Do not edit files."

read-only と never の組合せは、この確認を非対話かつ書込・network 昇格なしにする。追加 tool、hook、wrapper が別経路で副作用を持つ環境では disposable checkout/container でも確認する。出力に global、root、nested の意図した chain が現れない場合は、作業を始める前に root、filename、override、size、起動 directory を直す。Codex は通常、session 開始時に instruction chain を作るため、変更後は新しい session で確認する。公式 AGENTS.md guide / Agent approvals & security

AGENTS.md 以外の成果物は次の意味を持つ header を使う。YAML parser を必須にする意図ではなく、人と CI が同じ field を検索できるようにする契約である。

---
schema: codex-delivery/<document-type>@1
document_id: <TYPE-ID>
change_id: CHG-YYYYMMDD-<slug>
risk_tier: R0 | R1 | R2 | R3
document_status: draft | active | superseded
decision_state: STOP | PAUSE | UNKNOWN | SHIP | N/A
owner: <one accountable person>
evidence_as_of: <ISO 8601 timestamp or UNKNOWN>
commit_sha: <full exact Git object ID or N/A with reason>
supersedes: <document_id or N/A>
refs: []
---

`document_status` と `decision_state`

document_status: 文書の lifecycle。draft / active / superseded。
decision_state: その文書が支える出荷判断。STOP / PAUSE / UNKNOWN / SHIP / N/A。

完成した threat model が STOP、作成途中の task が UNKNOWN でもよい。両者を一つの status にしない。

変更 lifecycle

proposed
→ specified          TASK と AC が固定
→ approved           scope と risk を承認
→ implemented        exact commit が存在
→ verified           required evidence が同じ commit に対応
→ reviewed           exact commit を review
→ merged
→ deployed           artifact を配置
→ released           対象 cohort が利用可能
→ exposed            対象利用者が実際に変更へ到達したことを観測
→ observed           value / incident の期限に到達
→ closed | reopened

状態を飛ばす場合は、不要だった理由と承認者を残す。merged は released、deployed は exposed、exposed は value observed を意味しない。

書式 trigger

変更	Task	ADR	Threat	Eval	PR	Release	人の承認
誤字・非実行文書	必須	不要	不要	link/format	必須	不要	通常 review
可逆 UI・内部 refactor	必須	条件付	差分確認	test	必須	簡易	owner
public API・重要 dependency	必須	必須	必須	contract/security	必須	必須	owner
auth・tenant・課金・個人情報	必須	条件付	必須	negative/E2E	必須	必須	明示承認
schema migration・backfill	必須	必須	必須	migration/reconciliation	必須	必須	明示承認
AI model/prompt/retrieval	必須	条件付	差分確認	必須	必須	必須	risk に応じる
AI tool write/send/pay/delete	必須	必須	必須	effect/attack 必須	必須	必須	明示承認

条件付 は decision が将来を拘束する、重要 trade-off がある、戻す費用が大きい場合。軽微変更へ全書式を強制せず、trust boundary または重要な判断を隠さない。

trigger から最低 tier と必要書式を導出する

author の自己申告だけで R0/R1 または N/A にしない。CI または reviewer は semantic diff/path に加え、state/schema/event contract の consumer/reference/dataflow graph と release manifest から少なくとも次を判定する。

Semantic trigger	Minimum tier	N/A にできない証拠
auth、tenant、権限、課金、個人情報、外部 write	R2	threat、negative/effect eval、PR、release
schema migration、backfill、retention/delete	R2	ADR、migration/reconciliation、rollback/forward repair
privileged CI、build action、重要 dependency、artifact producer	R2	privilege-flow review、provenance、artifact binding
AI tool の write/send/pay/delete、権限拡大	R2	action/effect ledger、attack eval、人の承認
rollback、monitor、kill switch を弱める	R2	threat、recovery drill、明示承認
高損害・不可逆・規制判断	R3	適用分野の専門 review、段階露出、残余 risk 受容

trigger 検出結果、再分類理由、tier 変更、承認を append-only に残す。applicable trigger の minimum tier/required artifact は waiver 不可である。下げられるのは positive evidence で false positive を証明した場合、または triggering scope を除去して scan を再実行した場合だけで、owner approval 単独では足りない。R3 の専門 review は N/A 不可。trigger classification を完了できない状態は UNKNOWN とし、provisional risk_tier を最低 R2 に置いて SHIP を止める。risk_tier は影響、10 章の delegation level は agent 権限なので相互に代用しない。

判定規則

優先順位は次で固定する。

STOP > PAUSE > UNKNOWN > SHIP

STOP: critical invariant、法令・契約、重大安全条件、critical eval が失敗。
PAUSE: 既知 blocker、承認、修正、rehearsal、顧客確認待ち。
UNKNOWN: required evidence が欠損、stale、未成熟、coverage 不足、分母 0。
SHIP: required gate が exact fingerprint に肯定証拠を持ち、上位 veto がない。

N/A は evidence を省く近道ではない。Required=yes と Result=N/A の組合せは不正で UNKNOWN にする。N/A は Required=no、理由、判定者、時刻がそろう場合だけ使える。forward の deploy/release/expose/expand state は自由入力で昇格せず、次の順に導出する。

non-waivable FAIL / active critical veto                 → STOP
既知の修正・承認・rehearsal待ち                         → PAUSE
required gate が PASS 以外 / fingerprint不一致 / stale → UNKNOWN
required gate が全てPASS、veto/blockerなし              → SHIP

上位状態を平均や別 gate の PASS で相殺しない。判定 event は gate snapshot hash、actor、scope、expiry とともに append-only で記録する。

STOP は recovery を禁止する状態ではなく、forward movement を止める状態である。contain/fence/rollback/quarantine/compensate/forward-repair は、事前定義した緊急権限、least privilege、対象 scope、runbook、non-waivable constraint、post-condition を持つ別 event として実行する。回復後の再出荷には新しい forward gate と承認が必要である。

証拠の正本と binding

同じ PASS を TASK、EVAL、PR、RELEASE へ手入力で複製しない。TASK は claim と evidence plan を定義し、test/eval 実行結果は一つの immutable EVID run manifest を正本にする。manifest には plan/case hash、code/config fingerprint、environment、exact command/runner、time、exit/skip/unknown、raw artifact hash を持たせる。PR と release はその ID/hash を参照し、内容を再解釈・上書きしない。runtime/authority、telemetry、incident、business gate は、それぞれの immutable receipt、snapshot、event を正本にする。

R0/R1 の単一 deterministic run は、environment、command、time、exit、skip/unknown、raw artifact を含む PR 内 snapshot 全体を hash し、その snapshot 自体を manifest にしてよい。critical/probabilistic/複数 run、AI、R2/R3 は独立 EVAL または同等の manifest を使い、oracle source を実装前に freeze する。一人運営で author/test/reviewer を完全分離できない場合は、外部仕様、生成 property、holdout、DB constraint、別時点 review 等の補償 control と残る限界を書く。

deploy 承認は approved deploy manifest + suspended stage 0 + target + trusted upstream fence + expiry に結ぶ。deploy manifest は reviewed head、merge/source tree、build run/provenance、artifact digest、schema、intended runtime config/flag/model/prompt/tool/policy、IaC、runtime identity/IAM/DB role/RLS/grants、secret/credential ID-version-scope、egress policy を適用分だけ結ぶ。fence receipt → suspended deploy → actual runtime/authority receipt を検証して promotion manifest を作り、その後だけ promotion manifest + release/exposure stage + target/cohort/blast radius + enabled traffic/webhook/queue/cron/tool-effect capability + expiry へ fresh approval を結ぶ。trusted control plane の activation receipt が実際の cohort/capability/residual fence と approval の一致を証明して初めて stage を active にする。bound runtime identity が変われば new manifest、stage/cohort/effect-scope/expiry だけが変わるなら unchanged manifest に対する fresh gate snapshot/approval/activation receipt が必要である。

Lint 可能な不変条件

CI で次を機械検査できる。意味上の妥当性は人の review が必要である。

active 文書に <<required: placeholder が残っていない。
一つの delivery bundle 内で change_id が directory と全成果物で一致する。incident は別 response bundle を作り、originating IDs を結ぶ。
risk_tier が bundle 内で一致する。tier を下げるのは trigger false-positive の肯定証拠または triggering scope 除去後の再scanがある場合だけで、承認だけでは下げない。
document_id が repo 内で一意。
commit_sha は abbreviated ref でなく、その repo の full Git object ID とし、PR review と eval result が同じ SHA を参照する。
decision_state: SHIP の文書では required gate がすべて PASS。Required=yes + N/A、required UNKNOWN、未解決 STOP/PAUSE は拒否する。
全 AC-* が EVID-* または明示した manual evidence へ対応する。
High/Critical の全 TH-* に control、test、monitor、owner、structured residual severity/active/waivable/acceptance があり、active residual Critical は STOP、active residual High は少なくとも PAUSE になる。
eval result に case set hash、config version、raw result path、x/n、unknown がある。
release に artifact/authority fingerprints、trusted effect fence、target/effect scope、stop trigger、rollback class、owner、runtime/authority verification がある。
superseded 文書は後継 document_id へ到達できる。
semantic trigger から導出した minimum tier と required artifact を author が下げていない。
reviewed head から artifact/intended target/config/authority までが approved deploy manifest、trusted fence と suspended deploy 後の actual runtime/authority receipt が promotion manifest へ到達し、authority-drift gate、cohort/effect-scope/expiry 承認、matching activation receipt が各 stage で current である。
changed または release-relevant な privileged producer/consumer/deployer job に privilege-flow record があり、untrusted code/artifact と write token/secret/OIDC/self-hosted runner が同じ context で交差しない。
open incident が無効化した manifest/gate を prior approval で再利用していない。
root/nested AGENTS.md の差分を owner review し、non-waivable invariant は instruction だけでなく CI/DB/policy で強制する。

CI が証明しないこと

requirement が顧客課題に合うこと
test oracle が正しいこと
threat を網羅したこと
reviewer agent が独立であること
残余 risk が受容可能なこと
release 後に顧客価値が生じたこと

合成例: webhook の支払猶予

実顧客情報を使わない最小の参照例。具体的な記入結果は EXAMPLE-BILLING-GRACE.md を参照する。

成果物	ID / 要点
Task	`CHG-20260801-billing-grace`; replay、逆順、期限境界、success 競合でも一貫した状態/effect
ADR	`ADR-0042`; ledger + transactional outbox + rollback-compatible writer を二段階導入
Threat	`TM-CHG-20260801-billing-grace`; 偽造、tenant 越境、effect crash、expiry race、rollback 切替
Eval	`EVAL-CHG-20260801-billing-grace`; affected reader/writer、provider receipt、期限、migration、recovery の synthetic 35 cases
PR	exact review tuple、`AC-01 → EVID-INT-01`、単一 EVID manifest、append-only review round
Release	deploy manifest → runtime/authority receipt → promotion manifest → activation receipt、2 synthetic accounts / 1 tenant canary、ingress fence
Observation	limited stage 5/5 accounts、telemetry 20/20、reconciliation delta 0。顧客価値は `UNKNOWN`、小標本を一般化しない

この例で「test passed」だけを書かず、どの受入条件を、どの case が、どの fingerprint で支えたかをたどれるようにする。

秘密・個人情報

production secret、token、cookie、顧客 prompt、個人情報を書式へ貼らない。
必要な証拠は access-controlled artifact の ID、redacted excerpt、hash、query 名で参照する。
test/eval fixture は synthetic、許諾済み、または適切に匿名化・削除可能なものを使う。
hash がある ことは、収集・利用・保存が適法または安全であることを意味しない。

更新のしかた

同じ失敗が二度起きたら、注意文を増やす前に code constraint、test、lint、CI、監視で止められるか検討する。
AGENTS.md rule は consequential、non-obvious、scope が明確なものだけ追加し、noise を出す rule は狭めるか削除する。
書式欄が三回連続で判断に使われなければ削除候補にする。ただし欠損を隠すために UNKNOWN 欄を消さない。
schema を変えたら @2 へ上げ、既存文書を黙って意味変更しない。