audit-trace

監査トレース

縦方向のトレーサビリティチェックです。証拠に基づいて、仕様の三点セット（および任意のアーキテクチャ文書）で要件 ID が一致しているか、機能カタログに CODE の重複、Code セル内の OBS-<6hex>、壊れたシャード参照がないかを確認します。

これは判断を要するものではありません。すべての入力は grep と読み取りによる決定的な処理で収集され、すべての指摘は固定ルールに従います。同じリポジトリで実行すれば、どちらのエージェントも同じ指摘セットに到達します。

ドキュメントのみ： このチェックでは、要件 ID を求めてアプリケーションのソース、テストファイル、コミットメッセージを grep することはありません。テストによる動作のカバレッジは、execute-family の Spec レビュー、test-first、prove-claim の verify コマンドで担保します。コードに CODE-N.M を埋め込む方法は使いません。

生成される内容

各項目が ERROR または WARNING となる指摘セットです。

Code	Tier	Condition
E1	error	タスクが、どの要件ファイルにも定義されていない ID を引用している
E3	error	同じ ID が複数のファイルで（太字で）定義されている
W1	warn	Approved または In-progress の要件が、どのタスクからも引用されていない
W2	warn	requirements.md に Status: または Feature code: の行がない
E4	error	Respects: 行が、docs/architecture/ 内のどのファイルにも定義されていない ARCH-N を引用している
E5	error	Respects: 行が、廃止済み（取り消し線付き）の ARCH-N を引用している
W3	warn	有効な **ARCH-N** 不変条件が、どの design.md からも引用されていない
E6	error	Security: 行が、正規の Approved セキュリティ文書に有効な太字定義がない TB-N／THR-N／CMP-N を引用している
E7	error	Security: 行が、廃止済み（取り消し線付き）の TB-N／THR-N／CMP-N を引用している
E8	error	同じ TB-N／THR-N／CMP-N／SLO-N が、複数の正規ファイルで太字定義されている
E9	error	Reliability: 行が、Approved の docs/ops/reliability.md に有効な太字定義がない SLO-N を引用している
E10	error	Reliability: 行が、廃止済み（取り消し線付き）の SLO-N を引用している
E11	error	同じ Feature CODE が複数のカタログ行（シャード間）に存在する
E12	error	ルーターの Feature catalog パスが存在しない、または docs/specs/ 内の読み取り可能なファイルではない
E14	error	INDEX にフラットな `
E13	error	正規カタログの Code セルが OBS-<6hex>（OBS-[0-9a-f]{6}）である
W4	warn	カタログの Spec ポインター（—／空欄以外）が、存在しない docs/specs/ 内のディレクトリを指している
W5	warn	同じ OBS-<6hex> が複数の .skills/reverse-features/active/*.md カードに存在する

E4／E5／W3 は不変条件チェックで検出されます。これらは spine が存在する場合にのみ実行されます。 E6–E10 はシステム ID チェックで検出されます。定義文書が存在しない、または権威ある文書ではない場合はスキップされます。E11–E13 と W4 は docs/specs/INDEX.md が存在する場合にのみ実行されます。W5 はこれらのカタログチェックとまとめて扱われ、active/ が存在していても INDEX がなければスキップされます。有効なシステム ID が機能から引用されていないことだけを理由に、警告を出してはいけません。 意味上の適合性を判定してはいけません。 同じくドキュメントのみのルールが適用されます。

廃止済み： E2（Implemented／Shipped に対するコード側の ID 存在チェック）は出力されません。コードベース内の ID を grep する指摘を再導入してはいけません。

エラーは監査トレースが壊れていることを意味します。警告は監査トレースが不完全であるものの、誤りではないことを意味します。prove-claim／cut-release はエラーがあればゲートを失敗とします。警告は報告されますが、呼び出し側から別途指定がない限り、致命的な扱いにはなりません。

入力

• 仕様は docs/specs/（または docs/agents/project.md で指定された specsDir）にあります。定義は requirements.md または fixes.md で終わるファイルから取得し、タスクの引用は tasks.md で終わるファイルから取得します。
• アーキテクチャ（任意）：docs/architecture/ が存在する場合、不変条件のチェックではそのツリーと、機能の design.md ファイルにある Respects: 行を読み取ります。
• 決定記録（任意）：.skills/decisions/ が存在する場合、同梱のバリデーターを実行します（下記参照）。
• ツリーを走査する際は、意図的な決定記録のパスとカタログの OBS 一意性チェック（.skills/reverse-features/active/ のみ）を除き、node_modules .git dist build target coverage .next .skills vendor と、すべてのドットファイル／ドットディレクトリをスキップします。

要件 ID の網羅性を確認するために、アプリケーションやテストのツリーを検索しないでください。コンシューマーリポジトリ内の従来の /// REQ: やテストタイトルのタグは、このチェックでは無視されます。

チェック項目

リポジトリのルートに対してこれらを実行し、それぞれの出力を最後まで読みます。下記の「譲れない条件」セクションの、ツリー全体を対象とするルールに従ってください。

1. 定義 — 要件／修正ファイルにある太字の ID から、廃止されたものを除きます。

# every bold **CODE-N.M** in a requirements/fixes file, retired (~~struck~~) ones deleted first
grep -rnE '\*\*[A-Z][A-Z0-9]{1,11}-[0-9]+\.[0-9]+\*\*' docs/specs \
  --include='*requirements.md' --include='fixes.md' \
  | sed -E 's/~~[^~]*~~//g' \
  | grep -E '\*\*[A-Z][A-Z0-9]{1,11}-[0-9]+\.[0-9]+\*\*'

残った各行は path:line:text の形式です。行に残っている太字の ID はすべて定義であり、所有者は path です。sed は ~~ … ~~ の範囲を削除するため、廃止された ID は結果に含まれません。要件ファイル内の通常の（太字ではない）ID は説明文であり、定義ではありません。

2. ステータスと機能コード — 要件ファイルごとに確認します。

grep -rnE '^(Status:|Feature code:)' docs/specs --include='*requirements.md'

Status: の値は Draft | Approved | In-progress | Implemented | Shipped のいずれかです（最初に一致したものを採用します）。

3. タスクの引用 — _Requirements: 行にある ID を確認します。

grep -roE '_Requirements:.*' docs/specs --include='*tasks.md' \
  | grep -oE '^[^:]+:|[A-Z][A-Z0-9]{1,11}-[0-9]+(\.[0-9]+)+' \
  | grep -E '^[^:]+:$|^[A-Z][A-Z0-9]{1,11}-[0-9]+\.[0-9]+$'

タスクの引用となるのは、リテラルの _Requirements: を含む行にある ID のみです。出力は path: 行と、その行で引用されている ID が交互に並びます。各 ID は直前の path: に属します。末尾の grep は、レベルが 2 つのトークン全体にのみ絞り込むため、3 レベルの CODE-1.2.3 が CODE-1.2 の引用として読み取られることはありません。

不変条件のチェック — docs/architecture/ が存在する場合のみ

リポジトリに docs/architecture/ ディレクトリがない場合は、チェック項目 4～5 を完全にスキップします。検出対象は変更されず、チェック項目 1～3 です。基盤となるディレクトリが存在する場合は、このファイルと同じ場所にある invariant-passes.md を読み、記載どおりに厳密に従ってください。

システム ID のチェック — セキュリティと信頼性（ドキュメントは任意）

該当する標準ファイルがない場合は、チェック全体をスキップします。docs/security/threat-model.md、docs/security/compliance.md、または docs/ops/reliability.md が存在する場合は、このファイルと同じ場所にある system-id-passes.md を読み、記載どおりに厳密に従ってください。これらの ID をタスクのフッター引用として扱わないでください。また、設計文書のいずれにも引用されていないという理由だけで、有効なシステム ID に警告を出さないでください。

カタログ整合性のチェック — docs/specs/INDEX.md が存在する場合のみ

docs/specs/INDEX.md がない場合は、このセクションをスキップします（仕様ツリー全体がない場合には、「チェック対象なし」の停止条件がすでに適用されます）。INDEX が存在する場合は、catalog-passes.md を読み、記載どおりに厳密に従ってください。Recognized カードにトライアドが必要かどうかを判定しないでください（Spec の — は許容されます）。また、ここで OBS を CODE に昇格させないでください。

ルール

各チェック項目で作成した集合に、冒頭の検出結果テーブルを適用します。W1 のステータス要件は次のとおりです。

ステータス	タスクが必要（W1）
Draft	いいえ
Approved / In-progress	はい
Implemented / Shipped	いいえ（タスク履歴が残っていてもかまいません。コード側の ID 要件はありません）

Status: Implemented／Shipped の根拠となるのは、プロセス（タスクのチェック済み、検証の成功、Spec のレビュー）であり、テストファイル内で grep できる ID ではありません。

タスクの引用の整合性はテキストで判断します — 評価しないでください

ID がタスクで引用されているのは、その文字列が _Requirements: 行に含まれている場合です。それだけです。タスクがその要件を「実際に」実装しているかどうかを判断するために、タスクの手順を読まないでください。その判断は仕様レビュー／主張の検証に属し、このチェックでは行いません。

仕様ツリー内の要件ファイルとタスクファイルを、該当するものすべて収集してください。要件ファイルを一つでも見落とすと、誤った E1 が発生します。タスクファイルを一つでも見落とすと、誤った W1 が発生します。仕様ツリーを grep してください。サンプルだけを確認してはいけません。

同じルールは不変条件の検査にも適用されます。E4/E5/W3 で確認するのは、Respects: ARCH-N の引用が有効な不変条件を示しているか、つまり存在し、有効であるかだけです。設計が不変条件を実際に尊重しているかどうかは判断しないでください。その意味上の判断は inspect-invariants／inspect-change の範囲であり、audit-trace では行いません。

意思決定記録の検査 — .skills/decisions/ が存在する場合のみ

リポジトリに .skills/decisions/ ディレクトリがない場合、このセクション全体をスキップしてください。実行したすべての検査から得られた指摘事項は変わりません。存在する場合は、このファイルと同じ場所にある decision-record-pass.md を読み、その指示に正確に従ってください。

出力

件数を報告してから、指摘事項を示してください。

trace: 24 requirements · 24 task-cited
  ERROR E1 task cites unknown requirement SHELL-9.9 (docs/specs/…/tasks.md)
  warn  W1 NOTES-2.1 (…/requirements.md, Approved) is not cited by any task

正確な文言と順序は契約上の要件ではありません。要件となるのは指摘事項の集合です。docs/specs/ が存在しない場合は、確認対象がないことを伝えて終了してください。ゲート条件はエラーゼロです。カタログのエラー（E11～E13）は INDEX が存在する場合にカウントします。警告 W4～W5 は、呼び出し元から別途指示がない限り、致命的ではありません。