NEPLg2.0 self-host 実行計画

最終更新: 2026-04-26

1. 目的

この文書は self_host_plan.md の実装を進めるための運用計画である。
仕様・構造・成功条件は self_host_plan.md を正とし、この文書では branch、commit、merge、検証、Issue 更新の単位を固定する。

NEPLg2.0 self-host は長期作業になるため、作業途中の大きな branch を持たない。
main を常に統合済みの基準点にし、1 branch は 1 checkpoint に対応させる。

2. 基本規則

• 作業開始時は必ず main に戻り、直前作業 branch がある場合は main へ fast-forward merge してから新しい branch を作る。
• main へ直接 commit しない。例外は fast-forward merge のみ。
• 1 branch は 1 つの主目的と 1 つ以上の明示 Issue に対応させる。
• branch 内の一時的なテスト悪化は許容するが、commit と main merge は green checkpoint のみとする。
• 各 commit 後に doc/progress_report_template.md の形式で Discord へ報告する。
• plan.md は変更しない。計画との差異、作業結果、保留判断は note.n.md に書く。
• 未着手作業は todo.md に残し、完了したら削除または次の未着手に置き換える。
• Issue の正は issues/items/*.md とし、旧 doc/review20260425/ は更新しない。
• Rust 側コンパイラ修正と self-host 実装は同じ main を基準に統合する。
• self-host 実装中に Rust 側の不具合を見つけた場合は、self-host 側の回避実装で隠さず Issue として提出する。

3. Branch 命名

<topic> は 2-5 語の kebab-case にする。
stage をまたぐ branch 名にしない。たとえば lexer と module loader を同時に進める branch は作らず、selfhost/s1-lexer と selfhost/s2-module-vfs に分ける。

4. Branch 手順

1. git switch main
2. 直前作業 branch が未 merge なら git merge --ff-only <branch>
3. git status --short --branch で clean を確認する
4. git switch -c <branch>
5. 実装、doc、Issue、todo、note を更新する
6. focused test を先に通し、最後に共通検証を通す
7. commit する
8. commit ごとに Discord へ報告する
9. git switch main
10. git merge --ff-only <branch>

branch は merge 後に再利用しない。
同じ領域の続きでも、次の checkpoint は新しい branch にする。

5. Rust 側 main 変更の取り込み

Rust 側コンパイラの修正は self-host の参照実装を変えるため、常に main を経由して取り込む。
self-host branch から Rust 側修正 branch へ直接 merge しない。

6. Rust 側 Issue 提出規則

self-host 実装中に見つかった問題は、Rust 側へ提出する前に分類する。

7. Commit 単位

commit は「review 可能で、単独で検証でき、戻す場合も意味が明確な単位」にする。
作業量ではなく、境界と検証可能性で切る。

1 commit が 500 行を超える場合でも、生成 index や Issue 移行のように機械的で意味が 1 つなら許容する。
手書き実装が 500 行を超える場合は、まず data model、pure helper、public API、integration の単位へ分割できないか確認する。

8. Commit Message

基本形は次の通りにする。

<scope>: <summary>

推奨 scope:

例:

selfhost(s0): add compiler source tree skeleton
stdlib(fs): add result-returning write APIs
nodesrc(selfhost): add lexer parity runner
rust(core): fix parser span parity diagnostic

commit 本文が必要な場合は、主 Issue と検証を短く書く。

Issue: ISS-20260426T010001Z-STDFS-WRITE-B7C4D923
Verify: node nodesrc/issues.js check; trunk build; playground editor 13/13

9. 共通検証

commit 前の共通検証は次を必須にする。

node nodesrc/issues.js check
git diff --cached --check
trunk build
node nodesrc/cli.js -i tests/playground_editor --playground-editor-tests -o json=tmp/playground-editor-selfhost.json

JSON 出力は caseCount、passedCount、failedCount を確認する。
trunk build の既存 warning は記録のみとし、この作業で増えた warning は原因を確認する。

docs only の場合も、web/compiler artifact と Node CLI の前提を崩していない確認として trunk build と playground editor test を実行する。

10. 追加検証

追加検証で失敗を見つけた場合は、原因が今回の作業範囲にあるかを切り分ける。
今回の範囲外の既存不具合なら Issue を作り、今回の commit へ混ぜない。

11. Stage 別 checkpoint

12. Issue 更新ルール

• 実装 branch の開始時点で主 Issue を決める。
• 作業中に不足 interface や別原因を見つけた場合は、実装前に node nodesrc/issues.js new で Issue を作る。
• Issue を修正した commit では、同じ commit に status、resolved、updated、検証結果を含める。
• Issue を完全に閉じない準備 commit では status: investigating までに留める。
• 旧 RV-... を参照する場合は、新 ID と legacy_id の両方を commit 本文か note に残す。

13. Discord 報告

各 commit 後に次を必ず含める。

• commit hash
• branch 名
• 主 Issue
• 直近の改良
• これからする内容
• 検証結果

複数 commit を同じ branch に作る場合も、commit ごとに報告する。
報告後に main へ merge した場合、merge が fast-forward なら追加報告は不要とする。

14. 次の着手順

1. selfhost/s0-source-tree
2. selfhost/s0-infra-span-diag
3. nodesrc/selfhost-focused-tests
4. stdlib/fs-write-api
5. stdlib/fs-dirlist-api
6. stdlib/stdio-result-stderr
7. stdlib/text-utf8-validation
8. selfhost/s1-source-text
9. selfhost/s1-token-model
10. selfhost/s1-lexer-basic

I/O interface は lexer/parser と並行したい誘惑があるが、CLI と bootstrap comparison の根になるため、S1 の途中までに必ず片付ける。