NDF のスクリプト全体をモデル・クラスの設計からやり直し、分割と重複の整理を 1 回で行う #1142

依頼（原文）

NDF のスクリプト全体をモデル・クラスの設計からやり直す（分割と重複の整理）。ファイルを切るだけでなく、モデルとクラスの設計からやり直す。範囲は NDF のスクリプト全体。relay.py は複製の仕組みごと設計に含める。重複した関数はライブラリへまとめる。/ndf:development-workflow の standard モードで進める。pace: fast は使わない（承認ゲート 1・2 は利用者の承認）。これまでの改善効果をしっかり計測し、振り返る。（2026-09-25 利用者）

最初に改善効果の計測と振り返り。引継ぎ文書の「効果の順」の 3' に書いた要求の材料 (a)〜(e) を課題の本文へ足してから要求を固める。（2026-09-25 利用者の起動指示）

何が起きているか

NDF のスクリプト（plugins/ndf/scripts/ と各 Skill の scripts/。テストを除く）は、課題ごとの継ぎ足しで育った。2026-09-25 23:30 UTC に測り直した値は次のとおりである（/tmp/ndf-measure-1142/structure.py。設計 PR で scripts/ へ移す）。

500 行を超えるファイル（2026-09-26 に develop で測った値。区分は markdown-writing のルール 9 と同じで、501 行以上は分ける）

同じ概念が別々に実装されている（構文木で拾った数。main と build_parser を除く）

使う側から見えている不足（2026-09-25 区間 12 と、この課題の計測で観測）

進み具合（2026-11-07、develop 22002f8）

上の計測表は着手前の基準である。

• scripts/supervise.py は 306 行、skills/cross-review/scripts/state.py は 297 行（基準は 3401 行・5121 行）
• 500 行を超えるファイルは 24 本（基準は 23 本）。最大は scripts/release-steps.py の 1170 行、次が scripts/lib/claude_accounts.py の 1141 行。scripts/check-script-structure.py は違反 0 件（例外リスト scripts/script-structure-allow/ で許した 144 件）
• 「コードに残る旧い語」の行数（tests を除く .py / .sh）は 関門 25・作業ツリー 225・改修計画 110・主ディレクトリ 56・進行側 35・共通層 49
  • 数え方: plugins/ndf/ の scripts/・skills/*/scripts/ の .py / .sh。テストと scripts/experimental/ を除く

直さないと何が起きるか

• 手を入れる worker が大きなファイルを読み通す。supervise.py は約 190 KB で、1 回で 6〜7 万トークンほどになる（見積り）
• 並列のスプリントが同じファイルに触り、衝突する（2026-09-25 の区間 11 では ユビキタス言語を先に定めて設計する段取り（用語集のスクリプト・仕様の写し・設計とレビューの手順） #1135 と Update: 実装レビューを開発版ごとに通し、構造改善のトリガーの閾値を下げる #1137、検査: m26-s11-review #1138 と Update: 検査で見終えた位置を origin の check-done/* に残し、検査を通らずに配布された変更を次の検査の範囲に含める #1139）
• 同じ概念の実装が食い違う。片方だけ直した不具合がもう片方に残る
• 効果を測れないまま改善を重ねる（f）

決めたこと（2026-09-25 利用者）

• 範囲は NDF のスクリプト全体。ファイルを切るだけでなく、モデルとクラスの設計からやり直す。relay.py は複製の仕組みごと含める
• 重複した関数はライブラリ（今の plugins/ndf/scripts/lib/）へまとめる。NDF の語彙で「共通層」は pace.json の点数を重くする領域を指すため、この課題では使わない
• 不足 a〜f はこの課題の受け入れ条件に含め、設計の移行の順序で最初の移行ステップに置く（d・f を先に直さないと、移行の前後を同じ物差しで比べられない）
• /ndf:development-workflow の standard モードで進める。pace: fast は使わない（承認ゲート 1・2 は利用者の承認）
• 語: 「段」は使わない。「入口」ではなく「エントリポイント」と書く
• 外部パッケージを使ってよい。依存は uv で解決し、uv が無い環境では入れる（2026-09-26 利用者。不足 h）
• 計画の実行（supervise.py のステップの遷移）とキューは、自作をやめて既存のライブラリへ置き換える。条件は、サーバーを立てずに動くこと。多少の揮発（落ちたときに進行中のステップをやり直す程度）は許容する（2026-09-26 利用者。不足 i）
• 汎用的で車輪の再発明になる処理は、自作をやめて外部ライブラリを使うように設計を調整する（2026-09-26 利用者。不足 j）

目的

• スクリプトの変更 1 回で読む量を減らす
• 触るファイルが重ならない単位でスプリントを並べられるようにする
• 同じ概念の実装を 1 つにする
• conductor が手で組み立てている操作を、NDF のエントリポイントにする（a〜c）
• 改善の効果を、同じ物差しで移行の前後に測れるようにする（d・f）
• ほかのプロジェクトでも同じように使える形を保つ（MVV の Value 6。プロジェクトごとに違うものは .ndf/ の宣言か引数で受ける）

前提

• 前提 1: Skill の手順・計画の JSON・hook・.ndf/ の宣言が呼ぶエントリポイント（パス・引数・出力の形）は変えない。変えるエントリポイントは設計が 1 つずつ挙げ、古いエントリポイントを移行の間だけ残す
• 前提 2: 移行は複数のスプリントに分ける。各スプリントは版を 1 つ出し（10.17.x）、途中の版でも利用者の手順は変わらない
• 前提 3: 移行の間も、ほかのスプリントは並列に進む。移行のスプリントが触るファイルは、同時に流れるほかのスプリントと重ならないように設計が順序を決める
• 前提 4: 試行（plugins/ndf/scripts/experimental/）は範囲に含むが、試行の置き場の規則（既定で動くものから参照しない）は変えない。ライブラリを試行と安定で共有するのは、試行 → 安定の向きだけとする

対象範囲

含む:

• plugins/ndf/scripts/（lib/・experimental/ を含む）と各 Skill の scripts/ の、テストを除くすべて
• relay.py と、それを ~/.claude/ndf/ へ複製する仕組み
• 不足 a〜f のうち、スクリプトの構造で直すもの（エントリポイントの追加・記録の欠け）
• 外部パッケージの宣言と、uv による依存の解決（不足 h）
• 移行の前後の計測と振り返り

含まない:

• Skill・エージェントの本文の書き直し（エントリポイントのパスが変わるところの追随だけを含む）
• scripts/（リポジトリの根。開発用）の構造の変更。ただし計測のスクリプト（token-usage.py ほか）の不足 f は含む
• playwright-kit と mcp-* プラグインのスクリプト
• シェルのスクリプトを Python へ書き換えるかどうかの判断そのもの（設計が決める。要求は置き場と重複だけを見る）
• 3 層の初回の測定で supervisor が割る候補（実作業の中央値 296k・最大充填 787k）、worker の 24 件中 8 件が実作業 < 固定費 #773（supervisor の切れ目）。この設計の後に着手する

進め方

0. 計測と振り返り: マイルストーン 26（トークン消費の削減）で入れた改善の効果を、同じ物差しで測って振り返る（/ndf:retrospective）。測るのは、区間（スプリント）ごとの LLM の費用・トークン（cache read / write・出力）・所要時間・worker の起動の数と固定費・検査とレビューの回数と指摘の数・流出不具合の数。材料は各計画の state.json と progress.jsonl、skill-stats.py --agents、phase_cost.py、check-trigger.py stats、引継ぎ文書の表。移行の前の値を基準として残し、設計が何を減らすかの根拠にする
1. 要求: この本文を仕様の正とし、用語集（.ndf/glossary.json）にスクリプトの語をそろえる
2. 設計（設計 PR・承認ゲート 1）: 設計文書の先頭のドメインモデルの節（開発ワークフローに、プロジェクトのユビキタス言語を先に定めて設計する段取りを入れる（DDD） #1111）に、ライブラリ（git / gh / 結果の契約 / 状態ファイル / 時刻 / claude と外部 CLI の呼び出し）と、各コンテキスト（計画の実行・収束ループ・配布・worktree・中継・記録と測定）を書く。クラスの責務・モジュールの置き場所・移行の順序を決める
3. 実装: 設計の順に、触るファイルが重ならない単位で並列に移す（6 本まで）。既存のテストで振る舞いが変わらないことを確かめる。スプリントは複数に分かれる

#773（supervisor の切れ目）はこの設計の後に着手する。

ドメインイベント

用語

受け入れ条件

計測と振り返り:

• マイルストーン 26 の改善効果の計測（区間ごとの費用・トークン・所要時間・worker の固定費・検査とレビューの回数と指摘・流出不具合）と振り返りが、この課題のコメントに残る。測れなかった値は理由と一緒に残る
• 計測に使ったスクリプトがリポジトリにあり、同じコマンドで打ち直せる
• 移行の後に同じ物差しで測り直し、移行の前の基準と比べた結果が残る

設計:

• 設計文書に、ライブラリと各コンテキストのモデル（持ち主・不変条件）、クラスとモジュールの責務、移行の順序（移行ステップごとに触るファイル）がある
• 設計文書が、エントリポイントの一覧（今のエントリポイントと移行後の置き場）を持ち、変えるエントリポイントを 1 つずつ理由付きで挙げる

構造:

• 移行の後、テストを除くスクリプトに 500 行を超えるファイルが無い（例外リストに理由と行数付きで載るものを除く）。例外リストのファイルは載せた行数を超えず、新しく作るファイルは例外リストに載らない
• 「同じ概念が別々に実装されている」の表の概念ごとに実装が 1 つになる。構文木で「本体の同じ関数」と「同じ名前で本体の違う関数」を数えるチェックが継続的統合で走り、設計の決めた例外のほかに当たらない

エントリポイントと不足:

• conductor が即時修正を、テスト → PR → merge-when-green の 1 つのエントリポイントで流せる（a）
• conductor が直に使うエントリポイントの一覧が 1 か所にあり、一覧に無いエントリポイントを起動指示に書かずに済む（b）
• 本番の計画が、配布の対象の差分に含まれる ndf 以外のプラグインの版も上げる（c）
• 検査のフェーズレポートと check-trigger.py stats が、実際に回ったラウンド数と指摘の数を返す（d）
• mvv-gate.py の設計の判定に、設計 PR の設計文書が材料として渡る（e）
• 計画が起動した claude -p の消費が、版ごとの集計に入る。計画の状態は OS の再起動と /tmp の掃除で消えない場所に残り、usage はステップごとにモデル・呼び出し回数・書き込みの 5 分と 1 時間を分けて持つ（f）
• GitHub の読み書きが 1 つのライブラリを通る。読み直し（CI と PR の状態の待ち）は REST の ETag 付きの要求で行い、変わっていない間は上限に数えられない。片方の枠が上限のときは、代われる操作をもう片方の枠で行い、代われない操作は回復の時刻まで待ってからやり直す。待ちの問い合わせの間隔は、変化が無い間は伸ばす（g）
• 外部パッケージを、1 つの宣言と lock で版を固定して使える。エントリポイントを起動する形（python3 <パス>）は変わらず、依存の解決は uv が行う。uv が無い環境では版を固定して入れてから続け、入れられないとき（ネットワークが無いなど）は理由を出して止まる。hook とラッパーは、SessionStart とラッパーの複製が同じ lock から用意した環境の python を直に起動し、deps.require() を呼ばない。環境がまだ無いとき、hook は判定をせずにパススルーで終わる（h。設計の決定 20）

退行しないこと:

• 既存のテストが、置き換え先の変更だけで通る
• Skill の手順・計画の JSON・hook が呼ぶエントリポイントのパスと引数と出力の形が変わらない（設計が挙げたエントリポイントを除く。挙げたエントリポイントは移行の間、古い形でも動く）
• bash scripts/build-runtime-plugins.sh --check が通り、Codex の導入先に新しいモジュールが入る
• ~/.claude/ndf/relay.py の複製が、移行の後も 1 回の導入で動く

非機能の条件

影響

検証手段

前提とする取り決め

境界

コードに残る旧い語（#1166）

#1166 は語をエンジニアになじむ語へ直したが、直したのは .md と用語集だけで、コードが読み書きする値・スクリプトの出力・docstring は旧い語のまま残した（読む側と書く側を同時に変えるため）。この課題の移行で新しい語へ揃える。数は 2026-09-25 のテストを除く plugins/ndf/ の .py / .sh の行数。

コードに残る旧い語（2026-10-08、develop 0aa346f、同じ数え方。行 / ファイル）

関門 162/35・作業ツリー 212/58・改修計画 111/24・主ディレクトリ 50/15・進行側 35/21・提示物 30/10・区間 72/19。関門・作業ツリー・改修計画・提示物は前の測定より増えた。スプリント 3 では、語を揃えた後に旧い語が戻らないチェック（用語集の廃止語をコードへも当てる）を一緒に入れる。スプリント 3 の子 issue は起票されていない（サブイシューは #889・#1248 の 2 件で、どちらも閉じた）。

コードに残る旧い語（2026-10-11、develop f19c7d2、同じ数え方。行 / ファイル）

関門 167/37・作業ツリー 210/57・改修計画 111/24・主ディレクトリ 50/15・進行側 35/21・提示物 32/10・区間 74/19。関門・提示物・区間は 10-08 よりさらに増えた。スプリント 3 の子 issue は未起票。

スプリント 2c の要求と受け入れ条件（不足 i・決定 21）

依頼の原文の語は、用語集の語へ直してスプリント 2c と書く（上の「進み具合」の表の行と同じ）。

依頼（原文）

#1142。範囲はミッション 2c（計画の実行とキューを DBOS Transact へ置き換える。設計の決定 21、issues/issue-1142-design-libraries.md の「決定 21」と issues/issue-1142-design-decisions.md）だけに絞る。本文の既存の節（依頼・決めたこと・受け入れ条件）は消さず、「ミッション 2c の要求と受け入れ条件」の節を足す（不足 i、#1248・#1249・#889 の扱い、計画の JSON・supervise.py のエントリポイント・進捗ログの形を変えないこと、kill -9 からの再開）。#773（supervisor の切れ目）は設計の入力として関係を書く。人へ問わずに進め、決められない点は前提か未決として課題の本文へ書く。（2026-09-30 conductor の起動指示）

この節はスプリント 2c だけを扱う。上の「決めたこと」（2026-09-26 利用者。サーバーを立てない・進行中のステップをやり直す程度の揮発は許容する）と、設計の決定 21（DBOS Transact を SQLite で使う）はすでに決まっており、この節はそれを受け入れ条件へ落とす。

何を置き換えるか（2026-09-30、develop dfeb3517 で数えた行数）

数え方: wc -l。supervise_lib/plan.py（248 行）はプランの JSON の形を持つため、形は変えずに残す（下の受け入れ条件）。不足 i の表の「6 本・約 1,500 行」は 2026-09-26 の値で、その後に スプリント 2b の移行で行数が動いた。

関係する課題の扱い

ドメインイベント（2c）

番号は全体の E1〜E9 と分けて C を付ける。

C8 は引き金を持たない（外から起きる）。再開の振る舞いは受け入れ条件 C-6 に移した。C2 の「待たせる」か「止める」かは未決 1 に移した。

前提

• 前提 C1: DBOS Transact は試行と同じ dbos==3.1.0 を SQLite で使い、plugins/ndf/pyproject.toml の extra（1 グループ）と uv.lock に載せ、エントリポイントは deps.require() で使う（決定 17・23）。計画の実行は hook の経路ではないため、決定 20 の所要の制約を受けない（決定 21）
• 前提 C2: DBOS の状態ファイル（SQLite）は、不足 f で決めた「OS の再起動と /tmp の掃除で消えない状態の置き場所」に置く
• 前提 C3: 揮発の許容は「落ちたときに流れていたステップを頭から流し直す」までとする（2026-09-26 利用者）。流し直すステップの副作用（コミット・push・PR の作成）が 2 回起きても壊れないことは、今のステップの作り（冪等な打ち直し）に任せ、2c では足さない
• 前提 C4: 移行の版より前に書き出して流していたプラン（state.json だけを持つもの）は、移行の後に打ち直すと先頭から流し直してよい。今の state.json から DBOS の記録への読み替えは作らない（プランは長くて数時間で終わり、移行の版をまたいで流れるプランは少ない）
• 前提 C5: 同時の本数の既定は今の値（queue --max の既定 3）を保ち、GraphQL の枠の既定は設計が決める。どちらも .ndf/supervise.json の宣言か引数で変えられる（MVV の Value 5）
• 前提 C6: 2c の移行ステップの切り方と順序は、2b の後に設計が決める（決定 21）。この節は切り方を決めない

未決（設計で決める）

1. 重なりが見つかったとき、後から入れる側を待たせるか（直列にする）、止めて知らせるか。supervise.py queue: 同時に流す計画の --files の重なりを流す前に知らせる（ディレクトリの包含で止まった） #1248 の案は両方を挙げる。受け入れ条件 C-4 はどちらでも「同時には流さず、重なる組を知らせる」を満たせば通る
2. 共有の一覧をどこで宣言するか（.ndf/supervise.json に置くか、プランの --files とは別の引数にするか）
3. GraphQL の枠の既定の本数（並行の本数が共有する外部の枠（GitHub の GraphQL・CLI の利用上限）を数えず、枠を使い切って全員が止まる #889。1 本あたりの問い合わせの見込みの測り方を含む）
4. supervise_lib/slow.py（遅れの見張り）を DBOS の上へ移すか、ステップの中の見張りとして残すか

対象範囲（2c）

含む:

• 上の「何を置き換えるか」の表のステップの遷移・状態の保存と再開・キュー・投稿キュー・収束ループのラウンドの駆動を、DBOS のワークフロー・ステップ・キューへ置き換える
• supervise.py queue: 同時に流す計画の --files の重なりを流す前に知らせる（ディレクトリの包含で止まった） #1248・並行の本数が共有する外部の枠（GitHub の GraphQL・CLI の利用上限）を数えず、枠を使い切って全員が止まる #889 と、並列の実装が行数の上限の例外リストを書き換え、マージで互いに衝突する #1249 の一般の形（共有の一覧）の検査と枠
• 試行（scripts/experimental/runner-trial.py と runner-trial/）の撤去と、台帳（docs/ndf-experiments.md）の「行き先」の記入

含まない:

• プランの JSON の形・雛形の中身（ステップの並び）の変更
• supervise.py の副命令の追加・削除
• 3 層の初回の測定で supervisor が割る候補（実作業の中央値 296k・最大充填 787k）、worker の 24 件中 8 件が実作業 < 固定費 #773 の supervisor の切れ目の変更と、agent-layers.md・parallel-work.md の本文の書き直し
• ステップの中で動くもの（worker の起動・claude -p の包み・GitHub の呼び出し）の置き換え（決定 16・17・24 のまま）
• DBOS を Postgres で使うこと・サーバーを立てること

受け入れ条件（2c）

置き換え:

• C-1 ステップの遷移・状態の保存と再開・同時の本数と枠が DBOS のワークフロー・ステップ・キューで動き、上の表の置き場に、遷移のループ・状態ファイルへの再開位置の書き込み・子プロセスの数え上げによる同時の本数の制御が残らない（設計が挙げる置き場と関数の一覧を、構文木で確かめるチェックが継続的統合で走る）
• C-2 supervise.py run / queue の実行中に、NDF のプロセスが待ち受けるポートが 0 本で、状態は SQLite のファイル 1 つ以上だけに残る（前提 C2 の置き場所）

形を変えないこと:

• C-3a supervise.py new <種別>（sprint・impl・fix・check・release・close）が書き出すプランの JSON が、同じ引数で移行の前と同じになる（移行の前に書き出した JSON と突き合わせるテスト）。移行の前の版で書き出したプランの JSON を、移行の後の run で流せる
• C-3b supervise.py の副命令 10 個（run・history・expected・example・new・queue・wait・design-glossary・note・sync-check）の引数・結果 JSON の鍵・終了コードが変わらない。wait は done で 0・attention で 20・上限で 3 を返す
• C-3c 進捗ログ（<state-dir>/progress.jsonl）の行の鍵と値の形が変わらず、移行の前の supervise.py wait と history が移行の後の進捗ログを読める。<プラン>-state のパスも変わらない
• C-3d on_fail・judge の選択・上限 20・承認ゲートの振る舞いが変わらない（既存のテストが置き換え先の変更だけで通る）

関係する課題:

• C-4 queue と run は、キューへ入れる時点で、同時に流れる候補との --files の重なり（ディレクトリの包含を含む）と、宣言した共有の一覧を触る組を数え、重なる組を結果 JSON の items と標準エラーへ知らせ、同時には流さない。手で再開・マージして終わったプランは並行中に数えない（supervise.py queue: 同時に流す計画の --files の重なりを流す前に知らせる（ディレクトリの包含で止まった） #1248・並列の実装が行数の上限の例外リストを書き換え、マージで互いに衝突する #1249）
• C-5 GitHub の GraphQL を使うと宣言したステップは、資源のタグの枠の本数を超えて同時に流れない。枠の本数は宣言か引数で変えられる（並行の本数が共有する外部の枠（GitHub の GraphQL・CLI の利用上限）を数えず、枠を使い切って全員が止まる #889）

再開:

• C-6 run / queue のプロセスをステップの途中で kill -9 し、同じコマンドを打ち直すと、落ちたときに流れていたステップから流し直し、済んだステップを流し直さない。キューの後続（--then）は前のプランが済むまで流れない。承認ゲートで止まったプランは、承認の無い打ち直しでは同じ所で止まったまま、承認で続く（試行 runner-trial.py check dbos と同じ 5 つのシナリオを、置き換えた本体に対するテストで流す）

依存と試行:

• C-7 dbos が plugins/ndf/pyproject.toml の 1 つの extra と uv.lock に版を固定して載り、python3 plugins/ndf/scripts/supervise.py ... の起動の形は変わらない。uv が無い環境では決定 17 の手順で入れてから続け、入れられないときは理由を出して止まる
• C-8 scripts/experimental/runner-trial.py と runner-trial/ が消え、docs/ndf-experiments.md の台帳の「行き先」に置き換えた PR が書かれる

非機能の条件（2c）

検証手段（2c）

進行

モード: —

• 要求と受け入れ条件 — 2026-09-30 01:57
• 作業場所の用意
• 設計 — 2026-09-30 02:08
• 素材の収集と出典の確定
• ドキュメント再構成
• ドキュメントレビュー
• 計画
• 実装
• 構造改善
• 実装レビュー
• 完了判定
• Pull Request
• 確定仕様化
• 後片付け — 2026-09-26 06:56
• 配布 — 2026-09-26 06:45
• 体裁レビュー
• リリース後テスト — 2026-09-26 06:55
• 振り返り — 2026-09-26 18:18