PJR-34MQ リポジトリ構成を平易な名前へ改め README を初めての人に分かる形にする

1. 概要

npm の README は、初めて SpecDojo を使う人に向けた導入の説明で、説明のない用語が多い。とくに「Detached Unit」は定義がなく、なぜ別のリポジトリにするのかも書かれていない。リポジトリ構成を平易な名前へ改め、README を初めての人が読んで分かる形にする。

2. 決定した名前

旧	新	意味
Detached Unit	別リポジトリ構成	プロダクトリポジトリとプロジェクトリポジトリを分ける
Attached Unit	同一リポジトリ構成	1 つのリポジトリに両方を置く
プロダクトリポジトリ	プロダクトリポジトリ（維持）	プロダクトドキュメント（仕様・設計）を置く
SpecDojo 専用リポジトリ	プロジェクトリポジトリ	プロジェクトドキュメント（登録簿・計画・実行記録）を置く

道場にちなんだ名前（離れ / 母屋、出稽古 / 内稽古）も検討したが、平易さを優先した。弓道で「離れ」は矢を放つ瞬間を指す用語でもある。

リポジトリの呼び方は文書の分類（プロダクトドキュメント / プロジェクトドキュメント）とそのまま対応する。「プロジェクトリポジトリ」は既存の文書で使われておらず、意味がぶつからない。

「SpecDojo Unit」（1 つのプロダクト文脈を扱う論理的な管理境界）の概念は変えない。構成の名前だけを改める。

2.1. 初出で定義すること

注意点	書き方
一般には「プロジェクトリポジトリ＝アプリ本体のリポジトリ」と読まれやすい	「プロジェクトドキュメント（登録簿・計画・実行記録）を置くリポジトリ」と定義する
1 つのプロジェクトリポジトリに複数のプロジェクトが入る	「プロジェクトごとにリポジトリを作る」と誤解されないよう書く

3. README の分かりにくさ

「使い始める」の節だけで、説明のない用語が次のように出てくる。

用語	問題
Detached Unit	定義がない。なぜ別のリポジトリにするのかも書かれていない
worktree 用ディレクトリ	何に使うのか書かれていない
kata	説明の前に「node_modules/specdojo から参照される」と出てくる
current_project、projects、base_path、catalog、schedule	最初の導入には不要な設定の話
provider、executor / reporter、規範の本文、rules / skills	オーケストレーターの節で説明なしに出てくる

4. 方針

方針	内容
先に「なぜ」を書く	SpecDojo の記録（登録簿や実行の履歴）をプロダクトの Git 履歴と混ぜないため、別のリポジトリに置く
最初の導入に要らない話は後ろへ	設定キーの話は「設定を変えたいとき」の節へ移す
用語は初出で一言説明する	kata = 成果物を書くための型、provider = 使う AI ツール、など
オーケストレーターの節を短くする	表と起動コマンドだけにし、仕組みの説明はガイドへ移す

5. 完了条件

• README に「Detached Unit」「Attached Unit」「SpecDojo 専用リポジトリ」が残っていない。
• README の「使い始める」を、SpecDojo を知らない人が上から読んで意味が通る。説明のない用語がない。
• 別リポジトリにする理由が README の冒頭近くで分かる。
• プロジェクトリポジトリの定義と、複数のプロジェクトが入ることが書かれている。
• 最初の導入に不要な設定の説明が、導入の手順から外れている。
• 次の文書の用語が追従している：docs-structure-guide、quick-start-guide、specdojo-overview-guide、specdojo-config-reference、directory-layout-reference。
• 見出しを参照している文書のリンクが切れていない（別リポジトリ構成（Detached Unit） の章名など）。
• npm run -s lint:md と npm run docs:build が通過している。

6. 作業内容

No	作業	担当	状態	メモ
1	README の「使い始める」を書き直す	UX	done	構成の理由と用語説明を追加
2	ガイド・リファレンス 5 本の用語を揃える	UX	done	決定した平易な名称へ統一
3	章名を参照しているリンクを直す	UX	done	新しい章名へ参照を更新
4	初めての人の目で README を読み直す	UX	done	導入で使う用語の説明を補足

7. 対応結果

• README.md の導入を再構成し、別リポジトリ構成を採る理由、プロダクトリポジトリ・プロジェクトリポジトリ・worktree 用ディレクトリの役割を最初に示した。1つのプロジェクトリポジトリで複数プロジェクトを扱えることも明記した。
• kata、provider、rulebook、exec plan、result、routine など、導入手順で使う用語を初出で説明した。詳細な設定キーは手順から外し、後段の「設定を変えたいとき」へ移した。
• docs-structure-guide、quick-start-guide、specdojo-overview-guide、specdojo-config-reference、directory-layout-reference を「別リポジトリ構成」「同一リポジトリ構成」「プロジェクトリポジトリ」へ統一した。
• docs-structure-guide の章名を 別リポジトリ構成 へ変更し、同章を指す quick-start-guide 内の参照も更新した。
• 対象文書の Markdown lint と全 Markdown lint、SpecDojo の派生文書生成、catalog 検証は通過した。catalog 検証では未作成成果物に関する既存 warning のみ発生した。
• npm run docs:build は、sandbox が tsx の IPC ソケット作成を拒否したため文書生成前に停止した。IPC 不要の起動方法では派生文書生成まで通過したが、VitePress build は sandbox が Chromium の起動を拒否したため Mermaid SVG の生成時に停止した。変更内容に起因する build エラーは確認されていないが、制約のない環境での再実行が必要である。

7.1. 評価（2026-09-26 夜間）

完了条件をすべて満たす。

完了条件	判定
旧名（Detached / Attached Unit、SpecDojo 専用リポジトリ）が残っていない	満たす。README とガイド・リファレンス 5 本で 0 件
「使い始める」が初めての人に意味が通る	満たす（下記）
別リポジトリにする理由が冒頭近くで分かる	満たす。「SpecDojo の記録をプロダクトの Git 履歴に混ぜないため」
プロジェクトリポジトリの定義と複数プロジェクトの記載	満たす
最初の導入に不要な設定を手順から外す	満たす。「設定を変えたいとき」の節へ移した
ガイド・リファレンス 5 本の追従	満たす
章名の参照が切れていない	満たす。別リポジトリ構成 の章名と参照が一致
lint:md / docs:build	満たす（docs:build は下記の条件つき）

README は 3 つの置き場所（プロダクトリポジトリ、プロジェクトリポジトリ、worktree 用ディレクトリ）をそれぞれ 1 文で説明し、ディレクトリの図を添えている。kata は初出で「成果物を書くための規則・手順・テンプレート・サンプルの総称」と定義され、provider も「利用する AI ツール」と説明されている。オーケストレーターの節から executor / reporter と rules / skills の説明が外れ、表と起動コマンドだけになった。

旧名が残るのは過去の個票（PJR-QHKA、PJR-TBHH）だけで、当時の記録なので書き換えない。

7.2. docs:build のメモリ不足

npm run docs:build は既定の Node のヒープ上限でメモリ不足により失敗した。NODE_OPTIONS=--max-old-space-size=8192 を付けると 193 秒で通った。本項目の変更は文書 6 本の小さな差分であり、サイトの規模が既定の上限を超えたことによる環境の問題と判断した。本項目の不備ではない。

8. 関連ドキュメント

• prj-0001:pjr-rpsx-scaffold-orchestrator-npm-scripts
• README.md
• docs/ja/specdojo/guides/docs-structure-guide.md
• docs/ja/specdojo/guides/quick-start-guide.md