Skip to content
Merged
26 changes: 21 additions & 5 deletions .takt/facets/instructions/review-todo-whole.md
Original file line number Diff line number Diff line change
@@ -1,4 +1,4 @@
Focus on **whole-tree todo hygiene** — the health of the planning corpus (`docs/todo.md` + `docs/todo2.md` … `docs/todo13.md` + `docs/todo-summary.md`) taken as a whole. This facet is invoked by the weekly-review workflow (ADR-031、観点⑤ Todo 妥当性) and reviews the entire todo corpus, not a diff.
Focus on **whole-tree todo hygiene** — the health of the planning corpus (`docs/todo.md` + `docs/todo2.md` … `docs/todo13.md` + `docs/todo-summary.md` + `docs/claude-code-web-tasks.md`) taken as a whole. This facet is invoked by the weekly-review workflow (ADR-031、観点⑤ Todo 妥当性) and reviews the entire todo corpus, not a diff.

This is the **weekly batch** counterpart to the edit-time todo hooks. It exists because the deterministic layer only sees the entry being touched right now; it cannot see the corpus-wide decay that accumulates across dozens of untouched entries.

Expand All @@ -15,7 +15,7 @@ Your job is the **broad, cross-file, time-based decay** none of the above can se

## Reading the corpus

1. `Glob docs/todo*.md` + `docs/todo-summary.md` — enumerate the whole corpus and note sizes.
1. `Glob docs/todo*.md` + `docs/todo-summary.md` + `docs/claude-code-web-tasks.md` — enumerate the whole corpus and note sizes.
2. Read `docs/todo.md` の preamble (冒頭の使い分けルール) first — it defines the routing contract (新規は todo6.md へ、編集専用は todo2-7.md、順位 table は todo-summary.md 等).
3. Sample the largest / oldest-looking files. Use `Grep` to follow task titles / 順位 numbers / `WR-` ids across files.
4. Cross-check the `docs/todo-summary.md` 順位 table against the detail entries it points to (`| N | Tier | title | todoX.md | ... |`).
Expand Down Expand Up @@ -50,6 +50,22 @@ The `docs/todo.md` preamble encodes a routing contract that silently rots:
- A file described as "編集専用・新規追加しない" that has in fact received new entries.
- Preamble file enumeration (「本ファイル + todo2.md + … の使い分け」) that omits or miscounts an existing `docs/todo*.md` file.

## Criterion 3: 自律実行台帳 (`docs/claude-code-web-tasks.md`) の鮮度

This ledger is **read by the nightly todo loop (WP-18) as its task-selection source**, so its decay has a consequence the rest of the corpus does not have: a stale row can send an unattended agent to implement something already done, or something whose intent nobody has settled. The ledger's own § ライフサイクル designates this weekly review as the place where its freshness is checked.

Check three things, in this order:

1. **Landed-but-listed rows** — for each 順位 in the ledger's tables, `Grep` the same 順位 in `docs/todo-summary.md` / `docs/todo-summary2.md`. A row present in the ledger but **absent from both 順位 tables** has landed and should be removed (with the evidence recorded in the ledger's § 棚卸し履歴). Verify the task really landed (grep the artifact it claims to produce) before raising — a 順位 can also disappear because it was deprioritized.

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🎯 Functional Correctness | 🟠 Major | ⚡ Quick win

現行タスク表だけを抽出し、順位を表セルとして照合してください。

Line 59 の「ledger's tables」は、§ 棚卸し履歴も含む表現です。docs/claude-code-web-tasks.md の Line 145-146 は、削除済みの順位 120 と 134 を履歴として意図的に保持しています。これらは summary table には存在しないため、現在の手順では毎週「landed-but-listed」と誤判定します。Grep も順位の裸の数字ではなく、| <順位> | の表セルを検索してください。対象を ### Batch 1### Batch 2 の現行表に限定し、理由表と棚卸し履歴を除外してください。

修正例
-For each 順位 in the ledger's tables, ...
+For each 順位 in the active task tables under `### Batch 1` and `### Batch 2`, excluding the reason table and `§ 棚卸し履歴`, ...

-`Grep` the same 順位 in `docs/todo-summary.md` / `docs/todo-summary2.md`.
+Match the exact summary-table cell `| <順位> |` in `docs/todo-summary.md` / `docs/todo-summary2.md`.

台帳の現行表と棚卸し履歴の関係に基づく指摘です。

📝 Committable suggestion

‼️ IMPORTANT
Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.

Suggested change
Check three things, in this order:
1. **Landed-but-listed rows** — for each 順位 in the ledger's tables, `Grep` the same 順位 in `docs/todo-summary.md` / `docs/todo-summary2.md`. A row present in the ledger but **absent from both 順位 tables** has landed and should be removed (with the evidence recorded in the ledger's § 棚卸し履歴). Verify the task really landed (grep the artifact it claims to produce) before raising — a 順位 can also disappear because it was deprioritized.
Check three things, in this order:
1. **Landed-but-listed rows** — for each 順位 in the active task tables under `### Batch 1` and `### Batch 2`, excluding the reason table and `§ 棚卸し履歴`, match the exact summary-table cell `| <順位> |` in `docs/todo-summary.md` / `docs/todo-summary2.md`. A row present in the ledger but **absent from both 順位 tables** has landed and should be removed (with the evidence recorded in the ledger's § 棚卸し履歴). Verify the task really landed (grep the artifact it claims to produce) before raising — a 順位 can also disappear because it was deprioritized.
🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In @.takt/facets/instructions/review-todo-whole.md around lines 57 - 59, Update
the “Landed-but-listed rows” procedure to inspect only the current ledger tables
under “### Batch 1” and “### Batch 2”, excluding the “§ 棚卸し履歴” and reason
tables. Require exact table-cell matching using the pattern “| <順位> |” when
checking docs/todo-summary.md and docs/todo-summary2.md, so historical entries
such as 120 and 134 are not flagged.

2. **Promotion candidates** — 順位 rows in `docs/todo-summary*.md` that satisfy the ledger's § 採用タスク (2) criteria (verifiable by `cargo test --workspace`, no real Windows hook / `pnpm push` e2e, no cwd-dependent `#[ignore]` dependency) but are **not yet listed** in the ledger. Name the 順位 and which criterion you checked. Do not propose promotion on title alone — read the detail entry.
3. **無人可 marks that no longer hold** — this is the check nothing else can perform, because it depends on state **outside the corpus**. For every row marked `✅ 無人可`, confirm condition 3 of the ledger's § 自律実行可否の 2 段階分類 (no duplicate work in flight): use `jj log` and remote bookmark inspection to look for an unmerged branch or in-flight PR implementing the same task. A mark whose task now has an implementation branch must be raised — the nightly loop would otherwise duplicate it. Also re-read the row's 注意 column against conditions 1 and 2 (no 「再選定」「着手時判断」「見積り」「検討」; implementation uniquely determined); a row whose 注意 text has been edited since marking may no longer qualify.

**Absence of evidence is not evidence of absence here.** Unlike Criterion 0/1/2, this check reads state outside the repository (remote bookmarks, PR status), which can be unreachable — no network, no `gh` auth, a shallow or non-colocated clone. If you cannot actually observe remote/PR state, report condition 3 for that row as **unverified** and say which lookup failed. Do **not** write it up as "no duplicate found": a silent downgrade from "could not check" to "checked, clean" is exactly how a stale mark survives into the nightly loop. Reporting unverified is the correct advisory-layer behavior — this facet blocks nothing, so the cost of saying so is one line in the report.

Severity guidance for this criterion: a stale `✅ 無人可` mark is `high` (it can cause an unattended agent to do conflicting or duplicate work); an **unverified** condition 3 is `medium` (the mark may be fine, but nobody has confirmed it this cycle); landed-but-listed rows and missing promotions are `low`–`medium` (ledger noise).

**Do not propose adding or removing a `✅ 無人可` mark yourself as a settled decision** — the ledger states the marks are set by a human (ADR-022). Raise the finding with evidence and let the `/weekly-review` adoption step carry it to the user.

## Calibration

Resist checklist-thinking. The edit-time hooks + cli-docs-lint + file-length-watchlist already enforce the objective, per-entry, per-link, per-size rules. This facet earns its keep only on corpus-wide, time-based, cross-file decay that no single edit can surface. If you can only flag something by a mechanical rule the deterministic layer already runs, flag the *layer gap*, not the instance.
Expand All @@ -59,7 +75,7 @@ If a finding needs natural-language judgment about task intent (「これはも
## Judgment procedure

1. Glob the corpus + read the `docs/todo.md` preamble (routing contract).
2. For Criterion 0/1/2, gather evidence with `Grep` / `jj log` — never raise a corpus-decay finding without a verified pointer.
2. For Criterion 0/1/2/3, gather evidence with `Grep` / `jj log` — never raise a corpus-decay finding without a verified pointer.

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🎯 Functional Correctness | 🟡 Minor | ⚡ Quick win

🧩 Analysis chain

🏁 Script executed:

#!/bin/bash
set -euo pipefail

file=".takt/facets/instructions/review-todo-whole.md"
if [ -f "$file" ]; then
  wc -l "$file"
  sed -n '1,120p' "$file"
else
  echo "missing: $file"
  fd -a 'review-todo-whole.md|review-todo|instructions' .
fi

echo '--- searches ---'
rg -n "Criterion 3|remote bookmark|in-flight|gh|Grep|jj log|unverified|unverified" "$file" || true

Repository: aloekun/claude-code-hook-test

Length of output: 14024


Criterion 3 の外部状態確認を判定手順に明記してください。

Line 61 は remote bookmark と in-flight PR の確認を求めています。Line 78 の証拠収集では Grep / jj log だけが列挙されているため、remote state の確認を省略して Criterion 3 を判定する可能性があります。gh または同等の remote/PR lookup を明記し、lookup できない場合は unverified を出力してください。

修正例
-For Criterion 0/1/2/3, gather evidence with `Grep` / `jj log` ...
+For Criterion 0/1/2, gather evidence with `Grep` / `jj log`; for Criterion 3, also inspect remote bookmarks and in-flight PRs. If unavailable, report `unverified` ...
📝 Committable suggestion

‼️ IMPORTANT
Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.

Suggested change
2. For Criterion 0/1/2/3, gather evidence with `Grep` / `jj log` — never raise a corpus-decay finding without a verified pointer.
2. For Criterion 0/1/2, gather evidence with `Grep` / `jj log`; for Criterion 3, also inspect remote bookmarks and in-flight PRs. If unavailable, report `unverified` rather than raising a corpus-decay finding.
🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In @.takt/facets/instructions/review-todo-whole.md at line 78, Criterion 3
の判定手順に、remote bookmark と in-flight PR を確認するための gh または同等の remote/PR lookup
を追加してください。lookup に失敗または利用できない場合は Criterion 3 を判定せず、必ず unverified
と出力するよう明記してください。

3. For each finding, articulate: what it is, where it lives (file + entry title/順位), the verifying evidence, and the proposed action (remove / merge / re-route / re-number).
4. Classify each finding by severity (`critical` / `high` / `medium` / `low`) per ADR-031 § Findings スキーマ. Todo-hygiene findings are typically `low`–`medium` (corpus noise, not production risk); reserve `high` for a duplicate that could cause conflicting work.
5. Write the report per the output contract (`review-todo-whole.md`). End with `analysis complete`.
Expand All @@ -68,6 +84,6 @@ If a finding needs natural-language judgment about task intent (「これはも

- File: `review-todo-whole.md` (Report Directory)
- Format identifier: `review-todo-whole`
- Read-only (`edit: false`): report findings only; the `/weekly-review` skill + user decide adoption (never edit `docs/todo*.md` from this facet).
- Category hint for aggregate-weekly: use `todo-dead-entry` / `todo-duplicate` / `todo-preamble-drift` (aggregate normalizes into the ADR-031 category set).
- Read-only (`edit: false`): report findings only; the `/weekly-review` skill + user decide adoption (never edit `docs/todo*.md` or `docs/claude-code-web-tasks.md` from this facet — the ledger's 無人可 marks in particular are a human decision).
- Category hint for aggregate-weekly: use `todo-dead-entry` / `todo-duplicate` / `todo-preamble-drift` / `ledger-staleness` (aggregate normalizes into the ADR-031 category set).
- If nothing survives evidence-gathering, output「特筆すべき todo-hygiene の findings なし」and end with `analysis complete` (do not manufacture findings).
3 changes: 3 additions & 0 deletions .takt/workflows/weekly-review.yaml
Original file line number Diff line number Diff line change
Expand Up @@ -131,6 +131,9 @@ steps:
# 観点 ⑤ Todo 妥当性 (ADR-031 拡張、順位154)。docs/todo*.md 全 corpus の
# dead pattern / cross-file 重複 / preamble routing drift を週次 batch で棚卸し。
# 順位136 hook (編集時 immediate) / cli-docs-lint が拾えない経年・横断的劣化を補完。
# 2026-08-06 (WP-18 PR 2): docs/claude-code-web-tasks.md の鮮度検査を追加。同台帳は
# 夜間 todo 消化ループのタスク選択元で、stale な 無人可 マークが無人 agent の重複実装を
# 招く。台帳の lifecycle が本 step を定期棚卸しの場として指名している。
- name: review-todo-whole
edit: false
persona: architecture-reviewer
Expand Down
Loading
Loading