最終更新: 2026/07/06 13:16

Pipeline 起案 payload の typed_edges 5 欄 (ADR-0201)

Decision Pipeline (drp) の POST /drafts 起案 endpoint に 関連 ADR (型付き辺) を指定する payload の書き方と挙動をまとめる。ADR-0201 (Accepted 2026-07-04 · PR #4437 で Done) の docs SSoT 同期。

目的

起案時に指定した関連 ADR が生成 ADR の frontmatter に自動反映されるようになった (PR #4437)。従来は本文 §10.1 に書いても frontmatter は空配列のまま出荷され、手動修正コミット 30 分/件 + Gate 2 CONFLICT 差戻が発生していた。本 runbook はその使い方 (5 欄の意味 · 検証挙動 · Gate 2 突き合わせ · 再投入時の挙動 · autofix との排他) を書き手側で参照するためのもの。

1. 5 欄の意味と例

POST /drafts の payload の options.typed_edges に、次の 5 欄を書くと生成 ADR の frontmatter 該当欄へそのまま反映される (ADR-0131 の型付き辺)。

{
  "container": "draft-material-xxxxx",
  "options": {
    "typed_edges": {
      "supersedes": ["ADR-0056"],
      "amends": ["ADR-0073"],
      "refines": [],
      "depends_on": [],
      "relates_to": ["ADR-0131"]
    }
  }
}
欄意味例
supersedes廃止置換する ADR本 ADR が既存決定を置き換える (元 ADR は Superseded 化される)
amends部分修正する ADR本 ADR が既存決定の一部を訂正する (Immutable 原則の corrigendum 相当)
refines詳細化する ADR抽象決定を具体化する派生 (元 ADR は生きたまま)
depends_on前提とする ADR本 ADR の成立が別 ADR の受理を前提とする
relates_to関連する ADR上記 4 種のいずれでもない関連 (影響先 · 参照元 等)

空配列 ([]) は「該当なし」を意味する。書かなければ空配列と同じ扱い。

2. 検証の挙動 (allowlist / warning / BLOCK しない)

options.typed_edges の検証は次のとおり:

  • allowlist は 5 キーのみ: supersedes / amends / refines / depends_on / relates_to。未定義キー (例: supersede / amend_to の typo) は 値ごと無視 + warning。
  • 値の形式: ADR-NNNN (4 桁) 形式のみ受理。不適合 (例: ADR-56 / adr-0056 / #0056) は warning + skip (該当値のみ落とす)。
  • BLOCK しない: warning は生成 PR 本文に転記されるが 422 差戻はしない。起案自体は受理されて run が起動する。

3. Gate 2 突き合わせ

Gate 2 (Consistency) で options.typed_edges の指定と生成本文の宣言を突き合わせる:

  • 指定した ADR (例: supersedes: ["ADR-0056"]) が 生成本文 §10.1 関連 ADR 等に登場しない と CONFLICT 差戻。
  • 本文の Supersedes/Amends 宣言と options.typed_edges の指定が 食い違う と CONFLICT 差戻。

Gate 2 CONFLICT を回避するには「起案 payload の typed_edges」と「起案本文 §10.1」を一致させる。生成 ADR 本文は Gate 4 通過後に自動生成されるため、書き手は payload と起案本文の両方に同一の関連 ADR を書く運用になる。

4. 差戻→再投入時の挙動 (?overwrite=1)

Gate 2 CONFLICT で差戻された起案を修正して再投入する際は POST /drafts?overwrite=1 で payload を置換する。次の run では最新の options.typed_edges の指定が毎回上書き反映される。

overwrite=0 (既定) は既存 payload を残すため、typed_edges を追加/変更するには overwrite=1 が必要。

5. source marker と autofix の関係

反映された frontmatter 欄には 行末 marker # 起案時指定 (source=options) が付く:

supersedes:
  - ADR-0056  # 起案時指定 (source=options)
amends:
  - ADR-0073  # 起案時指定 (source=options)

merge 後の CI autofix (相手側 ADR の逆辺自動追記) は この marker が付いた欄は上書きしない (排他規約 · 本 marker 付きは起案者の意思決定として温存)。

相手側 ADR への逆辺追記 (例: ADR-0056 側の superseded_by: [ADR-XXXX]) は 本機構の範囲外。従来どおり CI autofix (adr-lint --check-edges + follow-up PR) または手動で追記する。

6. 参照

  • ADR-0201 (本 runbook の SSoT): docs/adr/0201-pipeline-draft-payload-options-を-frontmatter-typed-edges-に反映.md (Accepted · Done · Review After 2026-09-26)
  • ADR-0131 (型付き辺の両端宣言規約): docs/adr/0131-*.md — 本機構の準拠先
  • drp 実装 PR: #4437 (body_generation.ts に options.typed_edges 反映機構 + allowlist 検証 + Gate 2 突き合わせ + unit test 4 パターン)
  • 関連 handover (main 発注): tasks/prompts/handover_2026-07-04_adr-0201-autofix-exclusion-plus-deploy-migration-check_to_main.md (autofix 排他規約 + deploy migration)