feat(lint): rule⑧ no-docs-relative-back-to-docs (Phase d P-2 / Bundle j-1 / 順位 94)

[aloekun]

Summary

docs/ 配下から ../docs/ への back-link を検出する custom lint rule⑧ (no-docs-relative-back-to-docs) を追加。Phase d roster の P-2 (Bundle j-1 / 順位 94) に該当。

• 新 rule⑧: (?i)\]\(\.\./docs/ regex 1 行で PR docs(todo): split summary and todo5.md tasks to keep files under 50KB #133 と同型の broken link bug class を pre-push で block
• 5 件の synthetic test: PR docs(todo): split summary and todo5.md tasks to keep files under 50KB #133 pattern 検出 / case-insensitive / 同階層 link skip / ../<other-dir>/ skip / 拡張子限定 (md のみ)
• 完了 todo cleanup: 順位 94 詳細 (todo6.md) + summary 行 (todo-summary.md) 削除、Bundle j 解説で j-1 land 済明記

変更内容

Commit 1 (前 PR carry-over): 順位 100 登録 + analysis.md P-1 完了反映

PR #139 (Bundle h+g-2) merge 後の post-merge-feedback で採用された Tier 3 #1 (development-workflow.md に「同一ファイル複数編集の 1 task 統合」+「partial completion + 後続 PR 追補明記」 の 2 pattern 追補) を 順位 100 として docs/todo6.md + docs/todo-summary.md に登録、analysis.md §4 #2 の P-1 行を ✅ 完了化 + dogfood outcome (classifier preview metrics + post-merge-feedback 結果) を記載。

本 commit は前 PR からの「フィードバック層」carry-over で、本 PR の P-2 implementation とは独立。

Commit 2: rule⑧ 追加 + linter test + 順位 94 cleanup

.claude/custom-lint-rules.toml

ルール⑧ no-docs-relative-back-to-docs を追加 (severity = error):

field	値
pattern	(?i)\]\(\.\./docs/
extensions	["md"]
severity	error

自己限定設計: paths filter は lint runner 未実装 (extensions のみサポート)。pattern semantics で自己限定可: ](../docs/ は parent-dir 経由で docs/ を再参照する形で、root-level README / docs 外の Markdown では自然な link 形式 ](docs/...) (相対なし) と区別される。grep 確認で false positive 影響範囲は todo6.md の説明文 1 件のみ (本 PR で削除)。

src/hooks-post-tool-linter/src/main.rs

5 件の synthetic test:

1. md_no_docs_relative_detects_pr133_pattern: PR docs(todo): split summary and todo5.md tasks to keep files under 50KB #133 で混入した [ADR-036](../docs/adr/adr-036-...) 形式の検出を確認
2. md_no_docs_relative_detects_uppercase_path: ../DOCS/... 大文字バリアント (case-insensitive) の検出
3. md_no_docs_relative_skips_same_directory_link: 同階層 [text](adr/foo.md) (相対参照なし) は skip
4. md_no_docs_relative_skips_parent_to_other_dir: ../README.md / ../src/main.rs 等 docs 以外への parent-dir 参照は skip
5. md_no_docs_relative_only_targets_md: .toml 等の他拡張子は対象外 (extensions = ["md"] 確認)

全 87 test pass、新規 5 test 含む。

todo cleanup

• docs/todo6.md: 順位 94 (docs/ 内 Markdown の ../docs/ 相対パストラップ検出 lint rule) 詳細削除
• docs/todo-summary.md: priority table から 順位 94 行削除、Bundle j 解説で j-1 land 済を明記

Phase d P-2 dogfood signal (classifier preview のみ、real pipeline 未実行)

P-1 と同じ方針 (feedback_global_config_backup を踏まえた commit pollution 回避):

Metric	P-1 (337-line / docs-only)	P-2 (203-line / Rust+TOML+MD mixed)
Latency	23s	46s
Findings	0	0
screen_decision	human_review (fallback)	human_review (fallback)
fallback_reason	JSON parse error: missing field screen_decision	同 (line 94 column 1)

観測:

• Fallback rate 2/2 = 100% (kill-switch criteria の 50% を超過、ただし Phase d guide §3 は 3/5 PR で停止 = まだ trend 内。real pipeline 経由なら kill-switch に厳密該当する)
• Latency 増加 (P-1 23s → P-2 46s): 短い diff (203 < 337) でも倍増 = 入力依存性 + mistral 内部状態の variance (cold/warm context) の両方が候補
• Mixed diff (Rust + TOML + MD) でも崩壊: 順位 98 (num_ctx overflow detection) の必要性が再々確認、P-3 着手前の優先実装を推奨

real pipeline 経由の P-2 metric は未取得。P-3 移行時に再判断。

Test plan

• cargo test -p hooks-post-tool-linter — 87/87 pass (新規 5 test 含む)
• pnpm deploy:hooks でビルド・デプロイ確認
• takt pre-push-review APPROVE (1 iter / 4m 6s)
• markdownlint clean (PostToolUse hook 確認)
• PostToolUse lint で rule⑧ 自体が rule⑥ (no-ephemeral-todo-reference) に当たって fix 済 (lint dogfood 成功)
• サイズチェック: todo6.md (~30KB) / todo-summary.md (~35KB) 50KB 内

Out of scope

• paths filter の lint runner 実装: 現状 extensions のみ。多数の false positive 観測時は別 PR で実装検討
• 順位 98 (num_ctx overflow detection): P-2 fallback で再確認したが本 PR scope 外、別 PR で実施
• real pipeline 経由 Phase d metric: P-3 移行時の trade-off 再判断
• 派生プロジェクト (techbook-ledger / auto-review-fix-vc) への deploy 確認: 各 repo の docs/ 構造確認が必要、別タイミングで実施

Summary by CodeRabbit

リリースノート

• New Features

  • Markdown ファイル内の不適切な相対リンクパターンを検出するカスタムリントルールを追加しました。

• Documentation

  • フェーズ進捗情報と実装ワークフロー推奨事項を更新しました。

• Tests

  • 新しいリントルール検証用のテストケースを追加しました。

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Pro

Run ID: 802ff5fb-8a08-4c68-aa23-3fc1a35d735c

📥 Commits

Reviewing files that changed from the base of the PR and between d5a3af2 and 9cdfc8c.

📒 Files selected for processing (5)

• .claude/custom-lint-rules.toml
• docs/local-llm-offload-analysis.md
• docs/todo-summary.md
• docs/todo6.md
• src/hooks-post-tool-linter/src/main.rs

---

📝 Walkthrough

Walkthrough

新しいカスタムリントルールno-docs-relative-back-to-docsを定義し、Markdownの../docs/形式の相対リンク検出機能を実装。テストケースで動作を検証し、dogfood実行結果をドキュメントに記録。開発ワークフロー改善タスクも追加。

Changes

MD相対リンク検出ルール実装・テスト・ドキュメント更新

Layer / File(s)	Summary
ルール定義 .claude/custom-lint-rules.toml	新規ルール⑧no-docs-relative-back-to-docsを追加。Markdown対象で](../docs/パターンをエラーとして検出。修正手順（相対パス置換）と違反/非違反例を定義。
テスト実装 src/hooks-post-tool-linter/src/main.rs	ルール検証用ヘルパー関数と6つのテストケース追加。../docs/検出、大文字小文字対応、同一ディレクトリ除外、別ディレクトリ除外、md以外拡張子除外を確認。
Dogfood実行結果 docs/local-llm-offload-analysis.md	Phase d P-1を完了（PR #139, 2026-05-10）と記載。classifier-previewメトリクス、検出フォールバック理由、post-merge feedback結果（10findings → 1accepted）、num_ctx overflow診断重要性を記録。P-2移行時の実パイプラン測定再評価計画を注記。
タスク進捗更新 docs/todo-summary.md	推奨実行順序テーブルで順位94の相対リンク検出ルールを削除、順位100のdevelopment-workflow.md追補タスク追加。Bundle j説明文でSub-PR j-1 land済（Phase d P-2）を明示。
開発ワークフロー追補 docs/todo6.md	PR #133 T1-1ルール作成タスク削除。PR #139フィードバック受けた``development-workflow.md追補新タスク追加：同一ファイル複数編集の1task統合、partial completion時の後続PR追補明記の運用ルール化。

Estimated code review effort

🎯 2 (Simple) | ⏱️ ~12 minutes

Possibly related PRs

• aloekun/claude-code-hook-test#6: カスタムリントエンジンの同じファイルとカスタム規約ファイルを対象として、新規ルール実装とテストを追加しているため関連。
• aloekun/claude-code-hook-test#134: ../docs/相対リンク検出ルール実装に関連。本PR実装一方、当該PRではタスク/todoドキュメントに追記。
• aloekun/claude-code-hook-test#91: カスタムリント規約設定とsrc/hooks-post-tool-linter/src/main.rsテストコード追加で共通。Markdownリント機能拡張の関連実装。

🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 75.00% which is insufficient. The required threshold is 80.00%.	Write docstrings for the functions missing them to satisfy the coverage threshold.

✅ Passed checks (4 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	プルリクエストのタイトルは、新しいカスタムリントルール（rule⑧ no-docs-relative-back-to-docs）の追加という主要な変更を明確に要約しており、変更セットの主要な目的を的確に反映しています。
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ Finishing Touches

📝 Generate docstrings

• Create stacked PR
• Commit on current branch

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands and usage tips.}