ADR-0145: COVERAGE_GAPS ページを handover 残タスク一覧ページへ転用する

• Status: Accepted (PR #1887 merge = 受理の規約により 2026-06-12 受理・代表取締役判断)
• Mode: Standard
• Kruchten Type: Executive/Property
• Scope: platform
• Implementation Status: In Progress
• 起案者: [email protected]
• 起案日時 (JST): 2026-06-12 16:02
• 承認日時 (JST): 2026-06-12 16:52
• Approver Role: platform
• Approver Who: [email protected]
• Driver: [email protected]
• Consulted: Decision Pipeline AI 審査 (Gate 0-4)

決定の早わかり（Y-statement）

本節は ADR-0140 の touch-time 運用により 2026-06-12 のミニ改訂で追加された本文の要約で、新しい意味は加えていない (意思決定内容は本文が正)。「文脈で問題に直面し、対抗案でなくこの案を選び、目的のため代償を受け入れる」と読む。詳細はコンテキスト以降の本文に展開する。

• 文脈: セッション間の申し送り (handover) は tasks/prompts/ に 117 本蓄積している。docs サイトの COVERAGE_GAPS ページは known-unknowns 一覧として手動更新前提で運用されてきた。
• 問題: 残タスクの全体像を知るには最新の handover を 1 本ずつ読むしかなく、「探す・迷うコスト」が毎セッション発生している。COVERAGE_GAPS は実質的な更新が約 3 週間止まり、ページの存在意義が薄れている。
• 問題点と課題（直せる原因 → 発生を止めるためにやること）:
  • 残タスク節の見出しが 1 ヶ月で 16 種類に揺れ、機械集約ができない → 残タスク節を固定マーカー (固定 H2 見出し) で機械可読化する。
  • COVERAGE_GAPS が手動転記前提のため停滞する → ビルド時自動生成の派生ページへ転用し、手書きを禁止する。
• 決定（対応策）: 手動転記運用の継続 (案 A)・TODO_future.md への一本化 (案 B)・新規ページ追加 (案 C) でなく、handover 残タスク節の固定マーカー化 + COVERAGE_GAPS ページのビルド時自動生成ビューへの転用を採用する。生きている known-unknowns は TODO_future.md へ移送し、ADR-0048 決定②を同一 PR で正式改訂する。
• 目的: 残タスクの俯瞰が 1 ページで完結する状態にし、セッション開始時の状況把握コストを下げる。
• 代償: docs ビルドに tasks/prompts (本番管理対象外) への読み取り依存が生じる (不在時はスキップする非致命設計で緩和)。直近 4 週間より前の handover はバックフィルしないため、古い生きたタスクが漏れる可能性が残る。
• 詳細は本文の影響・撤退条件セクションを参照のこと

コンテキスト

§1.1 背景

セッション間の申し送り (handover) は tasks/prompts/ に 117 本蓄積している。一方、docs サイトの COVERAGE_GAPS ページ (ADR-0048 決定②の known-unknowns 一覧) は手動更新前提で運用されてきたが、実質的な内容更新は 2026-05-23 が最後 (約 3 週間停滞) であり、ページの存在意義が薄れている。

§1.2 現状 (As-Is)

残タスクは各 handover の節に書かれるが、節見出しは 2026-06 の 1 ヶ月だけで 16 種類の表記揺れがある (「残タスク(優先順)」「残作業」「未着手 / 次セッション候補」「次にやること」等)。COVERAGE_GAPS ページの「Accepted ADR の未着手一覧」節は、Status×Impl の warn lint (PR #1800) や ADR-0144 の実装フォローアップ検知と役割が重複し始めている。

§1.3 課題

残タスクの全体像を知るには最新の handover を 1 本ずつ読むしかない。複数のセッション系列にまたがる残タスクを俯瞰するビューがなく、「探す・迷うコスト」が毎セッション発生している。見出し表記揺れにより機械集約ができない。

§1.4 制約・要件

• 手動転記運用は不可 (COVERAGE_GAPS 3 週間停滞の原因が手動前提のため)
• tasks/prompts は ADR-0132 により本番管理対象外。読み取り依存は非致命 (不在でもビルド継続) であること
• 執筆時の認知負荷を増やさない (タスク単位のタグ付け不要)
• 既存パターン (doc-news / doc-changelog) の流用を優先し、新規機構を増やさない

§1.5 目標 (To-Be)

handover 残タスク節の機械可読化 + COVERAGE_GAPS ページのビルド時自動生成ビューへの転用により、残タスクの俯瞰が 1 ページで完結する状態を実現する。Non-Goals: タスク単位のメタ情報 (担当者・期日タグ) 付与、過去 handover の全数正規化。

決定

docs 運用の文脈で、handover に散在する残タスクの全体像が見えない課題に対し、(1) handover の残タスク節を機械可読な固定マーカー化 (固定 H2 見出し or HTML コメントマーカー、形式は実装着手前に §3 比較表で確定)、(2) 生成スクリプトが handover 群から残タスク節を抽出し、COVERAGE_GAPS ページをビルド時に自動生成 (doc-news と同型の derived doc・手書き禁止)、(3) 表示対象は handover マーカー節に書かれたタスク全て、(4) 各タスクに出典 handover へのリンクと日付を表示し、消化判定は handover 本文更新またはアーカイブで反映、(5) 既存 known-unknowns のうち生きている項目は TODO_future.md 等へ移送しページ転用と同一 PR で処理、を採用する。同一 PR で ADR-0048 決定② を正式改訂し known-unknowns の新 SSOT を明示する。

改訂 (2026-06-18 ミニ改訂・抽出完全性の是正): 決定(3)「表示対象は handover マーカー節に書かれたタスク全て」を、次のハイブリッド契約へ改める。

1. 取りこぼしゼロの硬い保証: 現役 handover (tasks/prompts/ 直下) は抽出可否によらず最低1行をページに出す。残タスク節を特定できない handover は「未構造・要マーカー」行として出す。現役 handover が1行も生成されない場合は CI を fail とする。
2. 寛容抽出: 固定マーカー ## 残タスク(優先順) に加え、同義の節見出し (例「次にやること」「次の一手」「残作業」「残っている設計判断」等) を吸収して抽出する。(従来の寛容パースは同一マーカーの全角半角・空白揺れ吸収に限られ、別語の見出しを拾えなかった。)
3. 精度は警告で督促: フォールバック行になった handover (=見出しを認識できなかった) は --check で警告列挙する。ページからは消えないが推奨マーカーへ寄せる契機を得る。## 残タスク(優先順) は引き続き推奨形として維持する。
4. 段階施行: 当面は警告 (exit 0)。フォールバック率が表示 handover の 20% を恒常的に超える場合に個別チェックの fail 昇格を検討する (ADR-0134 二段階施行と同型)。

なぜ改めるか (errata・盲点の記録): 当初の決定(3)はマーカー節を持つ handover のみを表示対象とした。これは目的「残タスクの網羅的把握」に対し抽出完全性を満たせず、固定マーカーを使わない handover (実測で現役 25 本中 17 本) が静かに脱落していた。根因は「取りこぼさない」を再生成が確実に発火するか (トリガー完全性) としてのみ捉え、全ソースが実際にページへ載るか (抽出完全性) を別物として検証しなかったこと。ADR-0149 §1.2 も As-Is として「マーカー節を持つ handover のみ (120 本中 23 本)」を記録していたが、決定スコープ (全ソース集約・役割タグ・自動更新トリガー) に抽出完全性は含まれていなかった。本改訂はこの盲点を塞ぐ。あわせて Confirmation の KPI「ページと handover マーカー節の乖離 0 件」は、マーカーを持たない handover を測定母集団から外していた点で過小評価だったため、「現役 handover のうちページ未掲載 0 件」を追加指標とする。

判断基準 (Decision Drivers)

3.1 評価軸

K.O. criterion: Must 軸 (#usable) の score < 3 は不採用。

3.2 評価軸 × 案スコア表

計算: 満点 5 × Σ係数 3.5 = 17.5。採択案 = (4×2.0 + 4×1.0 + 4×0.5)/17.5 = 14/17.5 = 0.800。

3.3 マーカー形式の比較 (実装着手前に確定)

実装着手 PR の冒頭でどちらかに確定し、ADR をミニ改訂する。コスト試算 §コスト試算 はマーカー選択による変動幅 (±0.25 人日) を含む。

確定 (2026-06-12 ミニ改訂・実装着手時): 固定 H2 見出し ## 残タスク(優先順) を採用する。 理由: ①視認性の高さが執筆規約の定着に直結する (HTML コメントはプレビュー非表示で書き忘れやすい) ②直前 handover (2026-06-12 夕方分) が既にこの見出しで運用を開始しており移行コストが最小 ③弱点の文字揺れは、生成スクリプト側の寛容パース (空白・括弧の全角半角を吸収) と --check の乖離 warn で緩和できる。

検討した代替案 (Alternatives Considered)

• 案 A: 手動転記運用 (現状維持 + 転記ルール追加): 転記漏れと陳腐化が現状の問題そのものであり、COVERAGE_GAPS の停滞 (3 週間) を再生産する。#maintainable #usable で不採用。
• 案 B: TODO_future.md §7 (DOC-OPS backlog) へ一本化し COVERAGE_GAPS は廃止: backlog は案件単位の起票粒度で、handover の優先順・セッション文脈が失われる。handover → backlog の転記という同じ手作業が残り #maintainable で K.O. 抵触。
• 案 C: 新規ページを追加し COVERAGE_GAPS は残置: ページが増えて探すコストが増える。停滞した known-unknowns 一覧も残り続け #usable で K.O. 抵触。

影響 (Consequences)

§5.1 正の影響 (Good)

• 残タスクの一覧性・鮮度が上がり、セッション開始時の状況把握が 1 ページで済む
• handover の見出し規約固定は今後の機械処理 (ADR-0144 系の検知など) の土台になる
• doc-news パターンの流用で、derived doc 設計の社内ノウハウが横展開される

§5.2 負の影響 (Bad)

• docs ビルドに tasks/prompts (ADR-0132 で本番管理対象外) への読み取り依存が生じる。doc-news と同じく「不在ならスキップしてコミット済みページを温存」する非致命設計で緩和するが、tasks/prompts が存在しないローカル環境では古いページが表示され開発者の誤認 (ページが更新されていないという錯覚) を生むリスクが残る。ローカルビルド時は警告ログを stderr に出す仕様で緩和する
• 過去 handover の見出し正規化は全数やらず直近 4 週間 (推定 20-30 本) のみバックフィルする。それ以前の handover に生きているタスクが含まれる可能性は残るが、事前サンプル調査 (実装 PR で 30 本程度を抽出し生存率を測定) で実数を確認し、撤退条件 (a) の 20% 閾値の妥当性を再評価する
• 並走系列が同一タスクを独立して記載した場合、出典リンクの異なる重複エントリーが発生しうる。生成スクリプト設計フェーズで「タスクテキストの正規化 + ハッシュ一致による重複折り畳み」または「系列ごとのセクション分割表示」のどちらを採用するかを決定し、ADR ミニ改訂で確定する
  • 確定 (2026-06-12 ミニ改訂・実装着手時): 系列ごとのセクション分割表示 (出典 handover 単位) を採用する。 理由: ①誤折り畳み (別タスクを同一視する事故) が構造的に起きない ②各タスクの出典リンク・日付が一意に定まり ADR 決定 (4) と整合する ③実装が単純で doc-news 同型を保てる。重複エントリーは折り畳まず、--check の重複 warn で可視化する (Confirmation と整合)

§5.3 中立・トレードオフ (Neutral / Trade-offs)

• ADR-0048 決定②の known-unknowns SSOT としての役割は縮小する (部分修正)。同一 PR で ADR-0048 の決定② を正式改訂し、known-unknowns の新 SSOT (TODO_future.md またはその後継) を明示する
• 消化済みタスクの削除責任を明確化するため、handover 執筆規約に「新規 handover 作成時は直前 handover のマーカー節から消化済みタスクを削除してから書く」ステップを追加する。生成スクリプトの --check モードで前回 handover のマーカー節が一定期間 (例: 4 週) 未更新の場合に CI warn を出し、幽霊エントリー蓄積を検知する
• TODO_future.md の管理規約 (所有者・更新頻度・廃止条件) は本 ADR の前提として現状未整備。同一 PR で TODO_future.md の管理規約 §を追記するか、既存規約 ADR があればリンクする。規約整備が間に合わない場合は移送先を別途検討する

撤退条件 (Rollback Plan)

運用 4 週で次のどちらかに該当したら生成を止め、手動台帳 (TODO_future.md) 運用へ戻す:

• (a) 抽出漏れ・誤抽出 (消化済みタスクの残存表示を含む) が表示タスクの 20% を超える。判定方法: 運用開始から 4 週後に表示タスクを全件サンプリングし、消化済み / 抽出漏れを人手分類して比率を算出
• (b) 達希のセッション開始フローでページ参照が週 0 回 (使われていない)。判定方法: 4 週連続で参照ログまたは口頭ヒアリングで「見ていない」が確認された場合

撤退手順: (1) 生成スクリプトを CI から外す、(2) 最終生成ページを手動編集モードへ戻す or 削除、(3) 残存する生きたタスクを TODO_future.md へ転記、(4) ADR-0048 改訂分を再改訂し SSOT を戻す。

コスト試算

運用増分: handover 執筆時に固定見出しを使うだけでほぼ 0。LLM・インフラの直接金銭支出 0 円。マーカー形式の選択 (固定 H2 / HTML コメント) により実装複雑度が変動するため、上限値はその振れ幅を含む。doc-news との差分要件 (重複排除・消化判定・複数系列) を当初見積から追加計上した。

Confirmation

• 検証手段: 生成スクリプトに --check モードを設け、CI (docs ビルド) で handover ↔ ページの乖離を検出する (doc-news と同型)。加えて (1) 前回 handover のマーカー節が 4 週以上未更新の場合に CI warn、(2) tasks/prompts 不在時は stderr に警告ログ出力、(3) 重複エントリー検出時に warn
• 実行頻度: 毎 PR (docs ビルド時) + 週次の生存率サンプリング (4 週運用評価期間中のみ)
• 違反時対応: 乖離検出で CI warn → 同一 PR で再生成して解消。撤退条件 (a)(b) に抵触した場合は撤退手順へ
• KPI: ページと handover マーカー節の乖離 0 件 / 最新 handover の反映ラグ ≤ 1 ビルド / 表示タスクの消化済み残存率 < 20%

Review After

• 次回レビュー: 2026-12-12(運用 6 ヶ月後。4 週運用評価とは別に、handover 見出し規約の形骸化〔固定見出し・マーカーが守られなくなり抽出率が劣化していないか〕と派生ページの負債化リスクを再評価する時期)
• レビュー主体: docs 運用の所有者(現任 = 代表取締役)
• 前倒しトリガ: ① 撤退条件 (a)(b) のいずれかに抵触した時 ② tasks/prompts の移管・構造変更(ADR-0132 の改訂)が起きた時 — 生成スクリプトの読み取り契約が連鎖して壊れるため ③ マーカー形式・重複処理方式のミニ改訂時

参照 (References)

• 関連 ADR:
  • ADR-0048 (doc インベントリ・カバレッジ追跡): 決定② (COVERAGE_GAPS = known-unknowns SSOT) を本 ADR と同一 PR で正式改訂する
  • ADR-0130 (索引・目次・カタログの自動生成): 手作業更新廃止の横断規律 — 本決定はこの規律を残タスク一覧へ適用する個別化
  • ADR-0132 (tasks/prompts は本番管理対象外): ベストエフォート読み取り (不在でもビルド非致命) で整合させる
  • ADR-0144 (実装フォローアップ半自動検知): 役割分担 — 0144 は ADR 実装完了時の関連 doc 反映漏れ検知、本件はセッション申し送りの残タスク俯瞰。出力先 (DOC-OPS backlog) と本ページは粒度が異なる別レイヤ
  • ADR-0136 (doc-news): 生成パターン (git 管理ソース → 派生ページ・[skip] 系の除外規約) を流用する
  • ADR-0134 (tasks/prompts 消費者退避): アーカイブ移動が「消化済み」のシグナルとして本ページの表示から外れる動線になる
• 関連 PR/Issue: PR #1800 (Status×Impl warn lint)
• 外部資料: -