guarantee-ledger

Files (9)

• SKILL.md
• example-design.md · fixtures/decisions/
• guarantees-broken.md · fixtures/
• guarantees.md · fixtures/
• example.ts · fixtures/impl/
• example.test.ts · fixtures/tests/
• check-guarantee-cochange.sh · scripts/
• check-guarantees.sh · scripts/
• self-check.sh · scripts/

SKILL.md (first lines)

# Guarantee Ledger — 保証レコード

保証レコードとは、壊してはいけない約束を一枚の人間可読な文書に宣言し、その約束を裏付ける実装とテストへ索引を張る仕組みである。外部から観測できる面（HTTP API・CLI 出力・スケジューラ・Webhook・画面等）ごとに整理する。
呼び名は standards DOCS_OPS §3「呼び名」に従う（レコード＝行を足す集合。旧称: 保証台帳）。

## ① 目的と責務分割

保証レコードが持つのは「壊してはいけない約束の宣言」と「その約束を担う実装・裏付けテストへの索引」だけである。

その面にインターフェース定義（OpenAPI・CLI のヘルプ・型定義等）があるなら、それが形の正本である。次の文がその面と保証レコードの関係を定める。

> その面にインターフェース定義があるなら、それが形の正本である。保証レコードはそれを読んでも分からない振る舞いだけを持つ。

path・HTTP method・フィールド名と型のような、形の正本を読めば分かることは保証レコードに載せない。保証レコードが持つのは、正本を読んでも分からない振る舞い（条件分岐・副作用・エラー語彙の安定性等）である。

形の正本が存在しない面（バッチ処理等）では、載せる／載せないの線が消えて保証レコードが何でも入る箱になる。この場合は次のいずれかを選ぶ。

1. 先に形の正本を作る
2. その面を保証レコードの対象外とする

### 出自ルール

保証を保証レコードへ載せる根拠は、実装とテストの存在ではない。

> 保証は、指示・判断の出来事へ遡れるものだけを載せる。実装とテストが存在しても、遡れなければ載せない。実装が指示の隙間を埋めた振る舞いは、正しく動いていても保証ではない。

実装から拾うと、エージェントが指示されずに決めた振る舞いが契約へ昇格し、誤りを保証レコードが守る側へ回してしまう。

### 復元の天井

実装とテストを事後に棚卸しして保証を起こす手順（初回棚卸し）を検討したくなることがあるが、それには天井がある。

> 事後棚卸しが復元できるのは、過去の判断がテストへ化石化した分までである。規範の新規宣言はやりとり（レビュー・設計判断）からしか来ない。迷ったら載せない。

## ② 表書式と面のセクション

保証レコードの表は 7 列とし、列順は次のとおりとする。

| 列 | 内容 |
|---|---|
| `ID` | 保証を一意に識別する連番 `G-###` |
| `保証` | 壊してはいけない観測可能な振る舞い |
| `対応実装` | 保証を担う実装ファイル。リポジトリルートからの相対パス。複数は `, ` 区切り |
| `裏付けテスト` | 保証を実証するテストへの索引 |
| `pin確認` | 保証を壊して裏付けテストが赤くなることを観測した証跡。空欄、または `YYYY-MM-DD <壊し方の散文>` |
| `出自種別` | 出自の出来事の型。語彙は「指示」「選択」の2値 |
| `出自` | 保証の根拠となる指示・判断の出来事。`<リポジトリルートからの相対パス>::<見出し>` |

書式の worked example は `fixtures/guarantees.md` を参照。

### 面のセクション

面ごとに表を分けてセクションを作る。

> 保証が生まれてからセクションを作る。空のセクションを先に置かない。保証 0 件の面は、セクションが存在しないことで表現される。

### 出自種別の仕様

語彙は `指示` / `選択` の 2 値とする。空欄・語彙外の値は checker が `BROKEN` とする。

> 要求の本文を著述したのは誰か。人間が要求の本文そのものを著述したなら指示。エージェントが著述した問い・提案・選択肢に、人間が採否・選択で応えたなら選択。人間がエージェントの下書きに実質的な修正を加えて確定した場合は指示側とする。

`guarantee-interview` の裁定、レビュー指摘への採否、退役提案の keep / retire、エージェント作成 PR のマージによる承認は `選択` とする。人間が書いた issue・プロンプト・人間が自ら著述した設計上の決定は `指示` とする。

既存行への後付けは、出自文書が記録する出来事の型から読んで付与する。文書から読めない行は推測で埋めず、移行 PR のレビューで人間が確定する。

### 出自列の仕様

- 形式は `<リポジトリルートからの相対パス>::<見出し>` の一形式
- `::` は**最初の 1 つ**で分割する。見出しに `::` が含まれても壊れない
- 見出しに `|` を含むものは表セルを壊すため使えない
- PR やレビューでの裁定も、まず `.docs/reviews/` か `.docs/plans/` へ書いてから参照する

> 文書に残らないやりとりは保証にできない。

## ③ ID 体系

- ID は `G-###` の連番
- 欠番は再利用しない
- 保証をやめるときは行を削除せず `(retired: YYYY-MM-DD 理由)` を付けて残す

理由は「破棄した約束を削除すると、後から見たときに『そんな約束は最初から無かった』という履歴へ化ける」ためである。

### 退役提案（人間の判断待ち）

`(retired: ...)` は確定した退役を表す。エージェントが退役を提案し、人間が行ごとに判断する場合は、確定と区別できる最小形にする。

- `出自` 列にだけ `(retired: YYYY-MM-DD 理由)` を置く
- `保証`・`対応実装`・`裏付けテスト` は変更しない

keep と判断されたら `出自` セルを裁定文書の該当節へ書き換えるだけで戻る。裏付けテストはこの提案では撤回されないため、失われるのは「保証レコード上の約束」という地位だけである。checker の挙動は確定退役と変わらない（⑨参照）。

### 並行採番の衝突

複数ブランチが並行して `G-###` を採番すると衝突する。rebase 後に保証レコード全体の G-ID 重複と単調増加を確認し、`main` に存在する ID を保持したまま、自ブランチで追加した衝突 ID だけを現在の最大 ID の次から繰り下げる。繰り下げ後も単調増加させ、空いたように見える番号を再利用しない。

## ④ 載せる／載せないの二段の門

| 段 | 判定 |
|---|---|
| 第 1 門（出自） | ユーザー指示・設計文書の決定・レビュー裁定・PR rubric のいずれかへ遡れるか。遡れなければ載せない |
| 第 2 門（書き方） | 条件分岐の振る舞い／検証の網羅性／副作用の有無・冪等性／エラーコード語彙の安定性／存在秘匿・テナント分離 |

載せないもの: 形の正本が持つ内容（path・HTTP method・フィールド名と型・単純なステータスコード一覧）、内部実装。

> 実装もテストも存在するのに指示へ遡れないものは載せない。

### 昇格経路

> 観測は昇格させない。裁定が昇格させる。中間の振る舞いを保証したければ、まず判断の出来事を作る（レビューで裁定する / 設計文書へ決定として書く）。それから保証レコードへ載せる。

CLI や画面に固有の判定基準はここでは定めない。上記は原則であり、面ごとの具体的な判定基準を新たに発明しない。

## ⑤ テスト索引形式

- 索引は `<ファイル名>::<describe>` または `<ファイル名>::<describe> > <it>`
- 複数テストが 1 保証を裏付けるなら `describe` 単位で束ねる
- 1 索引で保証全体を裏付けられないなら、保証そのものを分割する
- 索引に件数・行番号など変動する値を書かない。正しいテスト追加のたびに保証レコードが陳腐化するため

From elchika-inc/agent-toolkit, MIT.

More from elchika-inc/agent-toolkit