trace

Trace

垂直トレーサビリティチェックです。次の1つの問いに、証拠を添えて答えます。各要件 ID は、定義・引用・テストの各箇所で一致していますか？

これは主観的な判断ではありません。すべての入力は grep で収集して読み取る、決定論的な処理です。また、すべての指摘は固定されたルールに従います。同じリポジトリでこれを実行する2つのエージェントは、同じ指摘セットにたどり着きます。

出力内容

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

コード	レベル	条件
E1	error	タスクまたはテストが、どの要件ファイルにも定義されていない ID を引用している
E2	error	Implemented または Shipped の要件に、それを網羅するテストがない
E3	error	同じ ID が複数のファイルで太字の定義として登場する
W1	warn	Approved の要件がどのタスクからも引用されていない
W2	warn	requirements.md に Status: または Feature code: の行がない
E4	error	Respects: 行で引用されている ARCH-N が、docs/architecture/ 内のどのファイルにも定義されていない
E5	error	Respects: 行で引用されている ARCH-N が、廃止済み（取り消し線付き）である
W3	warn	有効な **ARCH-N** 不変条件が、どの design.md からも引用されていない

E4／E5／W3 は不変条件のパスから生成されます。このパスは、スパインが存在する場合にのみ実行されます。

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

入力

• 仕様書は docs/specs/（または docs/agents/project.md で指定された specsDir）にあります。定義は requirements.md または fixes.md で終わるファイルから取得し、タスクの引用は tasks.md で終わるファイルから取得します。
• テストはリポジトリのテスト用ディレクトリにあります。検索するデフォルトのルートは次のとおりです（存在しないものはスキップします）。 tests test e2e src src-tauri crates app lib packages。その中で、テストファイルとは、パスが次のいずれかに一致するファイルです。 \.(test|spec)\.[cm]?[jt]sx?$ · /tests?/ または /e2e/ のパスセグメント · _test\.(rs|go|py)$ · または任意の .rs ファイル（Rust では doc コメントに ID が記載されるため）。
• docs/agents/project.md に異なるテスト glob または除外リストが指定されている場合は、それらを使用します。このファイルがない場合は、その旨を伝え、デフォルトを使用します。
• node_modules .git dist build target coverage .next .skills vendor と、ドットファイル／ドットディレクトリはスキップします。

パス

リポジトリのルートに対して以下を実行し、各処理の出力全体を読み取ってください。これは、下記の「譲れない条件」セクションにあるリポジトリ全体を対象とするルールに従います。

1. 定義 — 要件／修正ファイルにある太字の ID から、廃止済みの 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 がその ID の定義元です。sed は ~~ … ~~ の範囲を削除するため、廃止済みの ID が結果に含まれることはありません。要件ファイル内の通常の（太字ではない）ID は、定義ではなく文章です。

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

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

Status: は Draft | Approved | 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 の引用として読み取られることはありません。

4. テストの網羅性 — テストファイル内の任意の場所にあるすべての ID 文字列。既存のテストルートをそれぞれ検索します。以下は JS／TS と Rust のデフォルトです。

grep -roE '[A-Z][A-Z0-9]{1,11}-[0-9]+(\.[0-9]+)+' \
  $(printf '%s ' tests test e2e src src-tauri crates app lib packages) 2>/dev/null \
  --include='*.test.*' --include='*.spec.*' --include='*_test.rs' \
  --include='*_test.go' --include='*_test.py' --include='*.rs' \
  | grep -E ':[A-Z][A-Z0-9]{1,11}-[0-9]+\.[0-9]+$' \
  | sort -u

出力の各行は path:ID の形式で、網羅するテストファイルと、そのファイルが網羅する ID を示します。ルート／include は、リポジトリの実際の構成に合わせて調整してください。ID の文法はパス3と同じで、2階層の ID のみが対象です。

不変条件のパス — docs/architecture/ が存在する場合のみ

リポジトリに docs/architecture/ ディレクトリがない場合は、パス 5〜6 を完全にスキップします。検出結果は変更せず、パス 1〜4 のみです。背骨が存在する場合は、次を追加します。

5. 不変条件の定義 — 背骨内の太字の **ARCH-N** を、パス 1 で要件を扱う場合とまったく同じ方法で、廃止済みの集合（取り消し線）と有効な集合（残存項目）に分けます。

# retired invariants — the E5 set (struck-through, captured BEFORE deletion)
grep -rhoE '~~\*\*ARCH-[0-9]+\*\*~~' docs/architecture | grep -oE 'ARCH-[0-9]+' | sort -u
# live invariants — strike spans deleted first, then match (as in pass 1)
grep -rh '' docs/architecture --include='*.md' \
  | sed -E 's/~~[^~]*~~//g' \
  | grep -oE '\*\*ARCH-[0-9]+\*\*' | grep -oE 'ARCH-[0-9]+' | sort -u

最初の grep が廃止済みの集合です。2 番目の grep では取り消し線の範囲を削除し、有効な集合を得ます。どちらにも含まれない ARCH-N は未定義です。

6. Respects の引用 — いずれかの design.md にある Respects: 行の各 ARCH-N を確認します。

grep -rnE 'Respects:.*ARCH-[0-9]+' docs/specs --include='*design.md' \
  | grep -oE '^[^:]+:|ARCH-[0-9]+'

引用された各 ARCH-N は、それが記載されている design.md に属します。

ルール

4 つの集合、つまり defined（ID → {file, status}）、taskCited、testCovered がそろったら、次を適用します。

• E1 — taskCited ∪ testCovered に含まれ、defined に含まれない各 ID を、その ID を引用しているファイルとともに報告します。
• E2 — defined に含まれる ID のうち、ステータスが Implemented または Shipped で、testCovered に含まれない各 ID を報告します。（タスクで引用されていても E2 は満たされません。満たすのはテストのみです。）
• E3 — 2 つ以上の異なるファイルで太字定義されている各 ID を、そのファイルとともに報告します。（同じファイル内で太字の ID が 2 回出現しても、重複ではありません。）
• W1 — ステータスが正確に Approved で、taskCited に含まれない各 defined ID を報告します。
• W2 — Status: 行または Feature code: 行のない各 requirements.md（fixes.md は対象外）について、欠落している行を報告します。

docs/architecture/ が存在する場合は、liveArch、retiredArch、respectsCited（ARCH-N → 引用している design）もそろえたうえで、次も適用します。

• E4 — respectsCited に含まれ、liveArch にも retiredArch にも含まれない各 ARCH-N を、引用している design.md とともに報告します。
• E5 — respectsCited に含まれ、retiredArch に含まれる各 ARCH-N を、引用している design.md とともに報告します。
• W3 — liveArch に含まれ、respectsCited に含まれない各 ARCH-N を報告します。

ステータスごとの要件の概要：

ステータス	テストが必要（E2）	タスクが必要（W1）
Draft	いいえ	いいえ
Approved	いいえ	はい
Implemented / Shipped	はい	いいえ

カバレッジはテキストの存在で判定し、評価はしない

ID の文字列がテストファイルに含まれていれば、その ID はカバー済みです。それだけです。テストを読んで、そのテストが要件を「実際に」検証しているか、アサーションに意味があるか、コメントアウトされた行をカウントすべきかを判断してはいけません。その判断はこのチェックの対象ではありません。判断を加えると、結果が読み手によって変わるようになります。このチェックが防ごうとしているのは、まさにその事態です。

唯一認められる除外は、docs/agents/project.md の除外リストです。ここに記載されたファイル（ID をデータとして含むフィクスチャやテスト支援ファイルなど）は、テスト検索からファイル全体を除外します。ID ごとに手作業で除外してはいけません。

同様に、一致するファイルはすべて収集します。テストファイルを 1 つでも見落とすと、誤った E2 が発生します。要件ファイルを 1 つでも見落とすと、誤った E1 が発生します。ツリー全体を grep し、サンプル抽出したり、どのファイルが「おそらく」関係するかを推測したりしてはいけません。

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

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

リポジトリに .skills/decisions/ ディレクトリがない場合は、このセクション全体をスキップしてください。検出結果は、パス 1～6（または 1～4）のまま変更ありません。

.skills/decisions/ が存在する場合は、同梱のバリデーターを実行します（このスキルセットのインストール先を基準にしたパスで、record-decision と同じ場所にあります）。

sh skills/ship/record-decision/validate-records.sh --mode=trace

診断行をそのままレポートに追加します。終了コードが 1 の場合は、トレースエラーとして扱います（ゲート失敗）。終了コードが 2 の場合、意思決定記録のパスは未実行です（「合格」としてはなりません）。終了コードが 0 の場合、意思決定記録のエラーはありません（警告が出る場合はあります）。

バリデーターの検出結果を独自に解釈しないでください。記録のない本番移行: バリデーターは、「本番移行に記録がない」ことを自動検出しません。スキルを介した判定と、人間による直接の操作や外部からの貢献を区別できないためです。エージェントまたは人間がそのような欠落に気付いた場合は、警告レベルの懸念としてのみ扱ってください。エラーとして扱ったり、リリース／検証ゲートの失敗としたりしてはなりません。既存の E1～E5／W1～W3 の意味は変更ありません。

出力

件数を報告し、その後に検出結果を示します。

trace: 24 requirements · 24 task-cited · 22 tested · 18 test files
  ERROR E1 test cites unknown requirement SHELL-9.9 (src/shell.test.ts)
  ERROR E2 SHELL-1.4 (docs/specs/2026-07-01-shell/requirements.md, Implemented) has no covering test
  warn  W1 NOTES-2.1 (…/requirements.md, Approved) is not cited by any task

正確な文言と順序は契約上定められていません。重要なのは検出結果の集合です。docs/specs/ が存在しない場合は、確認対象がないことを伝えて終了してください。呼び出し元（verify、release）が合否を必要とする場合、ゲート条件はエラーが 0 件であることです。