開発中の版で工程名を記録すると、hook が使う配布済みの版に無い名前は黙って捨てられる #459

何を見つけたか

開発中のリポジトリの工程名で進行を記録すると、hook が使う配布済みの版にその名前が無い
場合、記録が黙って捨てられる。

progress-record.sh は issue の本文へ書くだけで、通過工程の控えを積むのは tool 実行前の
hook である。hook はランタイムが導入した配布物から起動するため、開発中のリポジトリの版とは
別の版の工程名の一覧を読む。

2026-09-07 に #451 の作業中で観測した。リポジトリは v10.6.0、導入済みの ndf は v10.5.1。

$ bash plugins/ndf/scripts/projects-sync.sh 451 stage "実装レビュー"
NOTE: 控えの識別子で書き込めませんでした。盤面を読み直します

$ jq -c '.stages' ~/.local/state/ndf/stages/devbasex__ai-plugins__451.json
["要求と受け入れ条件","作業場所の用意","実装","完了判定","Pull Request","後片付け"]

「実装レビュー」は積まれていない。 v10.5.1 の一覧が持つのは レビュー であり、
v10.6.0 で改名した 実装レビュー を知らない。同じ理由で ドキュメントレビュー と
ドキュメント再構成、モードの operation も積まれない。

出力は成功に見える。 progress-record.sh は #451 進行 = 実装レビュー を返し、
終了コードも 0 である。捨てられたことは、控えを直接読むまで分からない。

どこで見つけたか

#451（控えの工程名の移行を案内へ入れる）の後片付けで、通過工程を報告したとき。

$ bash plugins/ndf/skills/development-workflow/scripts/stage-check.sh report 451
#451 の通過工程（モード不明）
  記録あり: 要求と受け入れ条件 / 作業場所の用意 / 実装 / 完了判定 / Pull Request / 後片付け
モードの記録が無いため、必須の工程は判定しません。

実際には実装レビュー（cross-review）を通し、モードは light と判定している。

なぜこの変更の範囲外なのか

#451 の受け入れ条件は「利用者の手元の控えが旧い工程名のまま残る状態を無くす」ことで、
対象は配布物の移行の案内である。この事象は逆向きで、控えではなく hook の側が旧い。
利用者には起きず、このリポジトリを開発するときにだけ起きる。

直さないと何が起きるか

NDF 自身の開発で、工程名を変えた版の開発中は記録が欠け続ける。

工程名を変える版では必ず起きる。 v10.6.0 は 2 件を改名し 1 件を足したため、開発中の
セッションでは 3 つの工程が積まれない。

claude plugin update では当座しのぎにならない。 更新は実体を入れ替えるだけで、
動いているセッションには反映されない（「Restart to apply changes」）。改名を含む版を
開発している間は、その版を配布して各ランタイムを再起動するまで食い違いが続く。

考えられる向き（決めるのは着手時）

食い違いの原因は、記録のスクリプトと hook が別の実体を選ぶことにある。 記録のスクリプトは開発中の版から、控えを積む hook は配布済みの版から動く。

• 記録のコマンドが、hook の一覧に無い工程名を渡されたときに気づける形で知らせる
• 開発中のリポジトリの hook を使う手段（設定での上書き）を案内として持つ
• 一覧を配布物ではなく対象リポジトリの SKILL.md から読む

由来

issue #451

同じ事象が繰り返し起きている

マイルストーン「01 リファクタリングの方法論と構造」の 7 件でも、工程の記録が積まれなかった。
振り返りの時点で控えを読むと、記録そのものが残っていない。

$ bash plugins/ndf/skills/development-workflow/scripts/stage-check.sh report 442
#442 の進行の記録がありません。

7 件すべてで工程を記録するコマンドを呼んでいる。 呼び出しは成功を返すが、hook が読む
一覧に新しい工程名（実装レビュー / ドキュメントレビュー / ドキュメント再構成）が無い。

関連

#452 と症状が同じで、原因が違う。 どちらも「気づけない」ことが実害である。

直し方は重なりうる（記録が積まれたかを確かめる手を置けば、両方に効く）。

• 根本原因の親 issue（2 つ目のクラスタ）: 通過工程の控えを記録のスクリプト自身が積むようにし、控えの取りこぼしと食い違いを根本原因の場所で直す #725（通過工程の控えを記録のスクリプト自身が積む）。1 つ目の 実行する版を解決する層を 1 つにし、開発中の版と配布済みの版の食い違いを根本原因の場所で直す #715 とはサブイシュー関係で結ばれている

親 issue: #725（修正レイヤー: 通過工程の控えを記録のスクリプト（progress-record.sh / projects-sync.sh）自身が積む）。単独では着手せず、#725 の修正で同時に直す。

やらないと判断した（2026-10-01）

• 理由（N6 不便）: 2026-09-07 に 控えの工程名の移行が更新の案内に無く、通った工程が「記録なし」として出る #451 で観測（v10.6.0 開発中、導入済み v10.5.1 の hook が「実装レビュー」を捨てた）。工程名を改名する版の NDF 自身の開発中だけ起き、工程名はいまも workflow-common.sh:20 の WF_STAGE_MATRIX に固定で、改名は稀。
• 再び考える条件: 工程名を改名する版の開発で再び記録が欠け、月に 2 回以上踏んだら