Skip to content

feat(weekly-review): 観点⑤ Todo妥当性 facet + file-size scan を todo 50KB に拡張 (順位154 + C01解消) #235

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
aloekun merged 1 commit into from
Jul 2, 2026
Merged

feat(weekly-review): 観点⑤ Todo妥当性 facet + file-size scan を todo 50KB に拡張 (順位154 + C01解消) #235

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
15 changes: 10 additions & 5 deletions .takt/facets/instructions/aggregate-weekly.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -23,7 +23,8 @@ ADR-031 § Findings スキーマ + § 採否フロー の input source として
- `simplicity-whole-review.md` — review-simplicity-whole facet の出力
- `security-whole-review.md` — review-security-whole facet の出力
- `architecture-whole-review.md` — review-architecture-whole facet の出力
- `file-length-watchlist.md` — file-length-watchlist facet の出力 (PR-W0、deterministic 800 行超 file scan)。本 watchlist は LLM 判断による findings ではなく機械的観測のため、Phase 1 統合では findings には含めず、Phase 2 の "file_length watchlist" 専用 section として weekly report に転載する
- `review-todo-whole.md` — review-todo-whole facet の出力 (観点⑤ Todo 妥当性、順位154)。docs/todo*.md corpus の dead pattern / cross-file 重複 / preamble drift。**findings として Phase 1 統合に含める**
- `file-length-watchlist.md` — file-length-watchlist facet の出力 (PR-W0 拡張、順位154。deterministic な `.rs` 800 行 + `docs/todo*.md` 50KB scan)。本 watchlist は LLM 判断による findings ではなく機械的観測のため、Phase 1 統合では findings には含めず、Phase 2 の "file size watchlist" 専用 section として weekly report に転載する

### Context

Expand Down Expand Up @@ -72,6 +73,9 @@ simplicity / security / architecture facets が emit する category を以下
- `cumulative-complexity` — 累積複雑度
- `dead-code` — 未参照コード
- `overspec` — overspec'd abstraction
- `todo-dead-entry` — todo corpus の完了済/陳腐化 entry (削除漏れ)
- `todo-duplicate` — todo*.md 跨ぎの重複 entry / 順位 table と detail の不整合
- `todo-preamble-drift` — todo.md preamble の routing 契約と実態の乖離
- `secret-exposure` — 機密漏出パターン
- `injection` / `auth-flaw` / `crypto-weak` / `unsafe-no-safety` / `path-traversal` / `prompt-injection` — security category

Expand Down Expand Up @@ -135,8 +139,8 @@ Markdown は人間 / Claude が読む summary 層。findings table を severity

### スコープ
- 対象ツリー: `src/` / `scripts/` / `.claude/` / `.takt/` / `docs/`
- レビューファセット: simplicity-whole / security-whole / architecture-whole
- 決定論的観測: file-length-watchlist (PR-W0)
- レビューファセット: simplicity-whole / security-whole / architecture-whole / todo-whole
- 決定論的観測: file-length-watchlist (`.rs` 800 行 + `todo*.md` 50KB)
- 採否方針: Phase C skill `/weekly-review` で AskUserQuestion 経由

### File Length Watchlist (機械的観測)
Expand Down Expand Up @@ -167,6 +171,7 @@ Markdown は人間 / Claude が読む summary 層。findings table を severity
- **simplicity-whole**: <observable patterns / クライテリア 0-3 で目立った傾向>
- **security-whole**: <observable patterns / hotspots>
- **architecture-whole**: <observable patterns / 観点 ① ハーネス遵守 + ② ③ sub criterion>
- **review-todo-whole**: <観点⑤ todo corpus の dead pattern / 重複 / preamble drift の傾向>

### 次のアクション

Expand All @@ -188,8 +193,8 @@ findings 全体がゼロの場合は以下を出力:

### スコープ
- 対象ツリー: `src/` / `scripts/` / `.claude/` / `.takt/` / `docs/`
- レビューファセット: simplicity-whole / security-whole / architecture-whole
- 決定論的観測: file-length-watchlist (PR-W0)
- レビューファセット: simplicity-whole / security-whole / architecture-whole / todo-whole
- 決定論的観測: file-length-watchlist (`.rs` 800 行 + `todo*.md` 50KB)

### File Length Watchlist (機械的観測)

Expand Down
96 changes: 44 additions & 52 deletions .takt/facets/instructions/file-length-watchlist.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,97 +1,89 @@
# File Length Watchlist (週次 800 行超 scan)
# File Size Watchlist (週次 機械 scan: `.rs` 800 行 + `todo*.md` 50KB)

決定論的 scan で 800 行超 file を全件列挙する。LLM が判断する余地はなく、shell command 出力を markdown table に整形するだけの mechanical task。
決定論的 scan で **サイズ閾値を超えた/接近した file を全件列挙**する。2 次元を計測する:

## 背景
- `src/**/*.rs` の **行数** (800 行閾値、観点⑦・順位 147 file length と整合)
- `docs/todo*.md` の **バイト数** (50KB=51200B 閾値 / 48KB=49152B で接近警告、観点⑦ Todo 分割 trigger)

LLM が判断する余地はなく、shell command 出力を markdown に整形するだけの mechanical task。

順位 147 (file_length lint、PR #202) は `hooks-post-tool-comment-lint-rust` の PostToolUse hook として実装されており、**触られた file の編集時のみ** `additionalContext` で 800 行超を警告する設計 (soft-nag、touch-trigger ratchet)。
> **決定論性と persona について (WR-2026-07-01-C01 解消)**: 本 step は純機械 (LLM 判断ゼロ) だが、
> takt は **全 step に persona (agent) を必須**とし persona-less な shell step 型を持たない。
> よって workflow 上の `persona:` 指定は **takt の構造的要件**であり、データに対する LLM 判断を
> 意味しない。矛盾を避けるため本 step は「Bash が最終 markdown まで生成 → agent はそれを Report
> Directory へ書き出すだけ (整形も判断もしない)」形とし、`weekly-review.yaml` 側にも同旨コメントを
> 付す。ADR-031 の 3 層分離 (Rust/shell 機械 / takt AI / skill ask) のうち **機械層**に属する。

このため:
## 背景

- 未触り state の violation は警告されない
- AI / 人が警告を無視して進められる
- 結果として PR-3a (#217) 時点で 7 件の 800 行超 file が累積した経緯あり (PR #218 で計画書 `docs/file-length-enforcement-plan.md` が land、PR-W0 として本 step を追加)
順位 147 (file_length lint、PR #202) と PR-W5 (`[file_length_gate]` Stop gate、#234) は **触られた file / PR 範囲の file** を対象とする edit-time / push-time の強制で、**未触り state の全件棚卸し**は対象外。`docs/todo*.md` の 50KB 分割 trigger (PR #88 / #96 / #101 / #123 / #172 で実証) も同様に自動計測経路が無い。

本 facet は週次 1 回 master HEAD の `src/` 全体を deterministic に scan し、800 行超 file を全件列挙して watchlist として report 化する。これにより ratchet が未発火の violation も可視化でき、aggregate-weekly が weekly report の "file_length watchlist" section として記載する。
本 step は週次 1 回 master HEAD を deterministic に scan し、両次元の閾値超過/接近を watchlist として report 化する。aggregate-weekly が weekly report の "file size watchlist" section として転載する。

## Phase 1: scan 実行

以下の shell command を実行 (Bash tool):
以下の shell command を実行 (Bash tool)。出力は整形済みなので、そのまま次 Phase で転記する。

```bash
echo "### rs-lines (>800)"
find src -name '*.rs' -not -path '*/target/*' -exec wc -l {} + 2>/dev/null \
| awk '$1 > 800 && $2 != "total" { print $0 }' \
| sort -rn
echo "### todo-bytes (>=49152 = 48KB, 閾値 50KB=51200)"
find docs -maxdepth 1 -name 'todo*.md' -exec wc -c {} + 2>/dev/null \
| awk '$1 >= 49152 && $2 != "total" { print $1, $2 }' \
| sort -rn
```

出力例 (PR-3a #217 land 直後の master state):

```text
1606 src/hooks-post-tool-comment-lint-rust/src/main.rs
1432 src/cli-merge-pipeline/src/feedback.rs
1404 src/cli-pr-monitor/src/stages/poll/mod.rs
982 src/cli-push-runner/src/stages/lint_screen.rs
972 src/cli-pr-monitor/src/fix_commit.rs
946 src/cli-push-runner/src/config.rs
890 src/cli-merge-pipeline/src/main.rs
```

0 件のとき: command が空出力。
各 section が空出力のとき: その次元は 0 件 (clean)。

## Phase 2: markdown 整形

`file-length-watchlist.md` を以下の format で Report Directory に出力する。

### 800 行超 file が 1 件以上ある場合
`file-length-watchlist.md` を以下の format で Report Directory に出力する。両次元とも常に section を出す (0 件でも「clean state」と明示、aggregate が常に Read 可能)。

```markdown
# File Length Watchlist (週次 800 行超 scan)
# File Size Watchlist (週次 機械 scan)

- scan 日時: <ISO 8601 UTC、本 step の wall clock>
- scan 対象: `src/**/*.rs` (`target/` 除外)
- 閾値: 800 行 (coding-style.md File Organization)
- 件数: N 件
- 対象/閾値: `src/**/*.rs` 行数 > 800 (`target/` 除外) / `docs/todo*.md` バイト数 >= 50KB (48KB で接近)

## 800 行超 file 一覧 (上限 800 行を超過、N 件)
## `.rs` 行数 watchlist (> 800 行)

- 件数: N 件 (0 件のときは「**0 件 (clean state)**」)

| 行数 | ファイル |
|---|---|
| 1606 | `src/hooks-post-tool-comment-lint-rust/src/main.rs` |
| 1432 | `src/cli-merge-pipeline/src/feedback.rs` |
| 921 | `src/cli-merge-pipeline/src/main.rs` |
| ... | ... |

## 進捗参照

`docs/file-length-enforcement-plan.md` の Phase 1 (PR-W1 〜 W4) で各 file の分割計画が capture されている。本 watchlist は分割 PR の land 状況を週次で可視化する役割。
## `docs/todo*.md` サイズ watchlist (>= 48KB)

完了条件 (本 watchlist の 0 件到達) を満たすと、計画書の削除条件 1/3 を満たす。
```
- 閾値: 50KB=51200B 到達で分割推奨、48KB=49152B で接近警告
- 件数: N 件 (0 件のときは「**0 件 (clean state)**」)

### 0 件 (clean state) の場合
| バイト数 | ファイル | 状態 |
|---|---|---|
| 49915 | `docs/todo-summary.md` | 接近 (48KB超) |
| ... | ... | 分割推奨 (50KB超) / 接近 (48KB超) |

```markdown
# File Length Watchlist (週次 800 行超 scan)

- scan 日時: <ISO 8601 UTC>
- scan 対象: `src/**/*.rs` (`target/` 除外)
- 閾値: 800 行 (coding-style.md File Organization)
- 件数: **0 件 (clean state)**
## 進捗参照

現時点で 800 行超 file は存在しない。Phase 1 (file-length-enforcement-plan.md PR-W1〜W4) は完了状態にあるか、もしくは新規 file が制約内に収まっている。
`.rs` 側は `docs/file-length-enforcement-plan.md` / PR-W5 `[file_length_gate]`、`todo` 側は
`docs/todo.md` preamble の分割ルーティング (新規は次 file へ) と対応。
```

## Output contract

- File: `file-length-watchlist.md` (Report Directory)
- Format identifier: `file-length-watchlist`
- 0 件 case でも file を生成 (clean state 確認のため。aggregate-weekly が常に Read 可能)
- 両次元とも 0 件でも section を生成 (clean state 確認のため。aggregate-weekly が常に Read 可能)

## Completion criteria

scan 完了 + markdown 出力で `analysis complete` を articulate (他の facet と同じ条件文字列を使用、step-level rule `all("analysis complete")` と整合)。
scan 完了 + markdown 出力で `analysis complete` を articulate (他 facet と同じ条件文字列、step-level rule `all("analysis complete")` と整合)。

## 重要な原則

- **読み取り専用 (`edit: false`)**。コード修正は行わない (= watchlist 報告のみ)
- **LLM 判断の余地なし**: 命令通りに Bash を実行し、出力を整形するだけ
- **件数 0 でも file を生成**: aggregate-weekly が常に Read 可能な前提を満たすため
- **読み取り専用 (`edit: false`)**。コード / todo の修正は行わない (= watchlist 報告のみ)
- **LLM 判断の余地なし**: 命令通りに Bash を実行し、出力を転記するだけ。file の中身を解釈しない
- **両次元とも件数 0 でも section を生成**: aggregate-weekly が常に Read 可能な前提を満たすため
73 changes: 73 additions & 0 deletions .takt/facets/instructions/review-todo-whole.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,73 @@
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.

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.

## Determinism layer guarantees (do NOT duplicate)

The following are enforced by deterministic hooks / CI lint at edit time and MUST NOT be re-enumerated here (raise a finding only if the layer itself has a gap):

- **Working-copy / add-edit staleness** (順位 136 hook): flags stale-looking edits and missing progress notes **on the entry being edited**.
- **Delete-time land verification** (順位 152): on `docs/todo*.md` deletion, greps for the corresponding land commit.
- **Preamble file-count + cross-reference** (`cli-docs-lint`, push-runner quality_gate): broken relative links / anchor drift are caught at push time.
- **File-size thresholds** (file-length-watchlist step): 50KB todo files / 800-line `.rs` are measured mechanically — do NOT eyeball file sizes here.

Your job is the **broad, cross-file, time-based decay** none of the above can see at edit time.

## Reading the corpus

1. `Glob docs/todo*.md` + `docs/todo-summary.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 | ... |`).

Do NOT run `jj diff` — this is a whole-corpus review. Use `jj log` / `Grep` only to verify claims (e.g. whether a referenced land commit exists).

## Criterion 0 (MVP top priority): Dead / stale patterns

Entries that have decayed into noise the edit-time hook never revisits:

- **Aged-out entries**: a task entry that (a) has no related commit in recent `jj log`, AND (b) whose blocking dependencies have already landed (so it is either done-but-not-removed or obsolete), AND (c) shows no "現在地 / 詰まっている箇所" progress for a long stretch. Verify with `Grep` / `jj log` before raising — an entry that is simply *not yet started* is not dead.
- **Completed-but-not-removed**: an entry whose 完了基準 is demonstrably met by landed code/docs but which still occupies the corpus (violates 運用ルール「完了タスクは ADR か仕組みに反映後、削除する」).
- **Superseded pointers**: entries referencing an ADR / 順位 / file that has been superseded or removed (dead pointer within the planning corpus itself).

For each finding, name the **specific file + entry title** and the evidence (which dependency landed / which commit satisfies 完了基準). No evidence → downgrade to 🤔 様子見.

## Criterion 1: Cross-file duplicate entries

The corpus is split across 14 files; the same task can be registered twice as it migrates:

- The **same task** described in two `docs/todo*.md` files (e.g. a task drafted in todoN then re-drafted in todoN+1 without removing the first).
- A `docs/todo-summary.md` 順位 row whose detail entry no longer exists (or exists in a different file than the row claims).
- The reverse: a detail entry with no corresponding 順位 row (silently dropped from the execution order).

Use `Grep` on distinctive title fragments / `WR-` ids / 順位 numbers to confirm the duplication. Point to **both** locations.

## Criterion 2: Preamble routing drift

The `docs/todo.md` preamble encodes a routing contract that silently rots:

- A file the preamble calls "新規追加先" that has actually crossed 50KB (should have rolled over to the next file, per the split precedent) — cross-check against the file-length-watchlist output rather than guessing sizes.
- 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.

## 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.

If a finding needs natural-language judgment about task intent (「これはもう不要では?」), that is exactly what belongs here — but articulate the evidence, and default to 🤔 様子見 when the intent is ambiguous (never propose deleting a user's planning entry on a hunch).

## 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.
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`.

## Output contract

- 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).
- If nothing survives evidence-gathering, output「特筆すべき todo-hygiene の findings なし」and end with `analysis complete` (do not manufacture findings).
Loading