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 として提出する。

2.1 Zenn 方針 review gate

NEPLg2.1 self-host の各 checkpoint は、Zenn 記事 https://zenn.dev/bem130/articles/1b352797de94e7 と AGENTS.md の方針を作業開始時と commit 前に確認する。

新しい issue、実装 slice、公開 API、diagnostic enum、Resource proof 境界、または既存 module の責務変更に着手する場合は、次を必須 gate とする。

1. Zenn 記事を再確認し、今回の slice に関係する方針を note.n.md または対応 issue に記録する。
2. 独立した subagent review を行い、設計、実装、ドキュメントコメント、source policy、検証方針を確認する。
3. Blocker は同じ branch 内で修正する。修正できない場合は、原因、影響、完了条件を持つ issue へ分離する。
4. Non-blocker は note.n.md、todo.md、または issue に残し、次 checkpoint の入口で再確認する。
5. source policy を追加または更新し、同じ方針違反が戻らないようにする。ただし、コメントを減らすための行数制限や説明削減の検査を入れてはならない。

subagent review では、少なくとも次を確認する。

• 詳細な review 入力、確認項目、指摘分類、note.n.md 記録形式は doc/neplg2/self_host_zenn_review_checklist.md に従う。
• review 依頼は nodesrc/selfhost_zenn_review_packet.js で生成した packet を土台にし、branch、base / head、committed / staged / unstaged / untracked に分けた変更 file list、accepted / fail-closed、検証欄、既存 warning、今回差分由来 warning、Zenn 記事 URL、YYYY-MM-DD または ISO-like date-time の Zenn 再確認日時、AGENTS.md、checklist、prompt authority を省かない。
• review response は nodesrc/selfhost_zenn_review_response_check.js で検査し、必須 section / field が欠けた返答、policy/spec と implementation/test のどちらかを欠いた返答、または弱い approve だけの返答を review 記録として扱わない。
• 失敗が Option / Result / enum diagnostic で表され、文字列や sentinel 値で分岐していないこと。
• match の網羅性検査が効く設計であり、公開 API が数値 tag や文字列 tag に依存していないこと。
• core / CLI boundary、parser / checker / HIR / Resource IR / backend boundary が混ざっていないこと。
• ドキュメントコメントが目的、契約、戻り値や error variant の条件、計算量、制約、典型例、現状の実装詳細と将来も守る契約の区別を説明していること。
• 高速化が静的検査を省略する方向ではなく、探索範囲、依存関係、artifact、cache key、事前検査済み summary の設計で行われていること。
• 暫定実装がある場合、その名前、妥協内容、fail-closed 範囲、解除条件が検索可能な形で記録されていること。

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 可能で、単独で検証でき、戻す場合も意味が明確な単位」にする。
作業量ではなく、境界と検証可能性で切る。

commit の大きさは行数では判定しない。生成 index、Issue 移行、広範囲の機械移行、丁寧なドキュメントコメント整備のように、意味が 1 つで検証可能なら大きな commit でも許容する。
手書き実装が大きい場合は、行数ではなく責務境界を見る。data model、pure helper、public API、integration、diagnostic projection、source policy のどれが混ざっているかを確認し、review 可能な境界へ分割できるなら分割する。

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 の途中までに必ず片付ける。