@infodb/p3 0.2.0 → 0.4.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (82) hide show
  1. package/README.md +6 -1
  2. package/dist/web/assets/{Outputs-Ni3pNuGU.js → Outputs-5Hby-S5Q.js} +1 -1
  3. package/dist/web/assets/{RequestStatus-K8TZwpur.js → RequestStatus-CTkGjT02.js} +1 -1
  4. package/dist/web/assets/TagInput-Rj3PNOAF.js +1 -0
  5. package/dist/web/assets/TaskDrawer-DtPhiYxP.js +3 -0
  6. package/dist/web/assets/_requestId-CGvAfIkB.js +30 -0
  7. package/dist/web/assets/_requestId-DxfYhgAq.js +1 -0
  8. package/dist/web/assets/board-wt47lfrE.js +1 -0
  9. package/dist/web/assets/copy-CKsXEjMi.js +1 -0
  10. package/dist/web/assets/directTask-Dk3H5Q2B.js +1 -0
  11. package/dist/web/assets/done-C9Ct7ssb.js +1 -0
  12. package/dist/web/assets/draft-CfJeyLOl.js +1 -0
  13. package/dist/web/assets/index-BTFL2rpp.js +12 -0
  14. package/dist/web/assets/index-DAyBsvua.css +2 -0
  15. package/dist/web/assets/milestoneOrder-N7b5XFJP.js +1 -0
  16. package/dist/web/assets/new-e4ID2vQV.js +1 -0
  17. package/dist/web/assets/preflightInput-DMxqnvF8.js +2 -0
  18. package/dist/web/assets/preload-helper-DhIyFaOW.js +1 -0
  19. package/dist/web/assets/release-notes-CQ0d2r0k.js +3 -0
  20. package/dist/web/assets/requestData-BDZqyl35.js +1 -0
  21. package/dist/web/assets/routes-Bipv3lwJ.js +2 -0
  22. package/dist/web/assets/settings-Dwh8fj6p.js +1 -0
  23. package/dist/web/assets/ui-DdOGYj9z.js +1 -0
  24. package/dist/web/assets/workTarget-Cijqq4yH.js +1 -0
  25. package/dist/web/index.html +4 -5
  26. package/docs/architecture.md +80 -15
  27. package/docs/development.md +83 -7
  28. package/docs/how-to-use.md +159 -15
  29. package/docs/installation.md +142 -5
  30. package/docs/publishing.md +27 -3
  31. package/package.json +8 -5
  32. package/skills/p3/SKILL.md +21 -8
  33. package/src/cli/args.ts +9 -2
  34. package/src/cli/help.ts +12 -3
  35. package/src/cli/main.ts +75 -5
  36. package/src/cli/output.ts +18 -0
  37. package/src/cli/preflightCommands.ts +10 -2
  38. package/src/cli/project.ts +268 -101
  39. package/src/cli/releaseNotesCommands.ts +63 -4
  40. package/src/cli/requestCommands.ts +4 -2
  41. package/src/cli/taskCommands.ts +1 -1
  42. package/src/core/context.ts +3 -2
  43. package/src/core/preflight/codexEngine.ts +2 -1
  44. package/src/core/preflight/render-image/Dockerfile +3 -0
  45. package/src/core/preflight/render-image/fonts-ja.conf +28 -0
  46. package/src/core/preflight/render-image/render.mjs +10 -1
  47. package/src/core/preflight/render.ts +5 -2
  48. package/src/core/preflight/service.ts +19 -2
  49. package/src/core/projectRegistry.ts +264 -0
  50. package/src/core/releaseNotes/completeRequests.ts +102 -0
  51. package/src/core/releaseNotes/generate.ts +12 -0
  52. package/src/core/releaseNotes/service.ts +9 -5
  53. package/src/core/store/locate.ts +3 -3
  54. package/src/core/userConfig.ts +25 -0
  55. package/src/server/api/chatgptRoutes.ts +6 -5
  56. package/src/server/api/manifest.ts +17 -1
  57. package/src/server/api/projectsRoutes.ts +89 -0
  58. package/src/server/api/releaseNoteRoutes.ts +11 -0
  59. package/src/server/api/routes.ts +33 -25
  60. package/src/server/server.ts +74 -15
  61. package/src/shared/directTask.ts +20 -0
  62. package/src/shared/milestoneOrder.ts +44 -0
  63. package/src/shared/types.ts +31 -1
  64. package/dist/web/assets/TagInput-BICKVH2x.js +0 -1
  65. package/dist/web/assets/TaskDrawer-BkDIstIN.js +0 -3
  66. package/dist/web/assets/_requestId-B5O_ytaq.js +0 -1
  67. package/dist/web/assets/_requestId-C66puEMO.js +0 -30
  68. package/dist/web/assets/board-CbfDjkls.js +0 -1
  69. package/dist/web/assets/copy-B1ZbihKL.js +0 -2
  70. package/dist/web/assets/done-CPQbCFHg.js +0 -1
  71. package/dist/web/assets/draft-dT3gLDIt.js +0 -1
  72. package/dist/web/assets/index-BUcs2J6N.js +0 -12
  73. package/dist/web/assets/index-C3DkqwJ9.css +0 -2
  74. package/dist/web/assets/link-_s8ndNKS.js +0 -1
  75. package/dist/web/assets/new-T60RB7de.js +0 -1
  76. package/dist/web/assets/preload-helper-dXqN7N-I.js +0 -1
  77. package/dist/web/assets/release-notes-DxrPhDbt.js +0 -3
  78. package/dist/web/assets/requestData-D8ZiSZss.js +0 -1
  79. package/dist/web/assets/routes-D9ZxXoLk.js +0 -2
  80. package/dist/web/assets/settings-DsHVyqzJ.js +0 -1
  81. package/dist/web/assets/supersede-CLXlhCq0.js +0 -1
  82. package/dist/web/assets/ui-Cvke4y4X.js +0 -1
@@ -62,7 +62,7 @@ Preflight で扱う要望が、プロジェクトで行う作業の粒度にな
62
62
  決まらなければ登録済みの一覧と選び方を出す(`src/core/store/locate.ts`)
63
63
  - プロジェクトを開く共通の入口(`core/context.ts` の `openProject`。CLI も `serve` の `startServer` もここを通る)で、
64
64
  データのフォルダと `project.yaml` があるかを確かめる(`locate.ts` の `checkDataDir`)。無ければ空のプロジェクトとして続けず
65
- `DataDirError`(終了コード 1)。何も作らない。無い(ENOENT)と読めない(権限・入出力)は分けて伝える。`init`(作成・参加)と
65
+ `DataDirError`(終了コード 1)。何も作らない。無い(ENOENT)と読めない(権限・入出力)は分けて伝える。`init`(作成)・`join`(参加)と
66
66
  `project` は開かないので妨げない。起動した後の切断は、画面の「再読み込み」の `ReloadError`(状態は変えない)が受け持つ
67
67
  - 登録が1つだけで決まった(`via: only`)ときは、今いる場所と関係なく当たるので読むだけにする。CLI の入口(`cli/main.ts`)で、
68
68
  プロジェクトを開く前に、読むだけの操作(`cli/readOnly.ts` の `readsOnly`。載っていない操作は変える操作として扱う)以外を止める。
@@ -119,6 +119,14 @@ Preflight で扱う要望が、プロジェクトで行う作業の粒度にな
119
119
  ディスクの今のファイルと照らし、違えば競合で何も書かない。rev のような番号ではなく中身で照らすので、番号を増やさない
120
120
  直接編集も見つかる。マイルストーンの ID は project.yaml と同じ形(英数字と `. _ -`、`.` と `..` は不可)で、保存先の外を
121
121
  指すものは断る。キャッシュを持たず問い合わせのたびに読むので、再読み込みは要らない。監視は `changed`/`release-note` を出す
122
+ - **要望の一括完了**(`releaseNotes/completeRequests.ts`): 判定は材料と同じ収録の条件で、見送りを除く全要望が収録でき、
123
+ マイルストーンが project.yaml にあり、所属の分からない読めない要望が無いときだけできる。変えるのは対応済 → 完了済だけ
124
+ (完了済・見送り・アーカイブ・タスク・ノート・マイルストーンは書かない。記録・ノート・済みは条件にしない)。詳細の
125
+ `completion` に判定(対象・既に完了済・見送り・できない理由・`basedOn`)を出し、CLI・API・画面はそれを見せて `basedOn` を添えて
126
+ 頼むだけ(画面で条件を作り直さない)。実行はディスクから読み直した材料で判定し直し、hash が違う・できないなら何も書かない。
127
+ 複数のファイルをまとめて書く仕組みは無いので1件ずつ書き、直前にタスクを読み直して確かめ、要望は判定したときの rev で書く
128
+ (`updateRequest`。変更の通知もそこから)。途中で止まったら戻さず(外の変更を上書きしない)、完了済にしたもの・失敗・未実行を
129
+ 返す。rev を増やさない直接編集や、確かめた直後の別のプロセスの書き込みまでは防げない(保存層の限界)
122
130
  - **マイルストーンとの関係**: ノート(読めないファイルも含む)のあるマイルストーンは消せない(`requestOps.ts` の
123
131
  `checkMilestoneRemoval`。CLI の `milestone rm` と画面の設定の保存で同じ)。保存は要望・マイルストーンの状態を変えない
124
132
  - **直接編集の限界と直し方**: ロックを使わない外部のエディタとの完全な排他は保証しない(保存の直前に照らすので、
@@ -194,6 +202,41 @@ Preflight で扱う要望が、プロジェクトで行う作業の粒度にな
194
202
  参照先の名前に置き換える。個人設定のエラーは `hideConfigPath` で「個人設定(config.yaml)」にする。想定外の変更は
195
203
  `<参照先>:<パス>`)。画面のエンジンの状態(共有しない)には個人設定の場所を出してよい
196
204
 
205
+ ### プロジェクトを跨ぐ serve(`p3 serve --all-projects`)
206
+
207
+ 通常の serve は1つのプロジェクト(今いる場所・`--project`・`--dir` で決めたもの)だけを開く。`--all-projects` を付けると、個人設定に
208
+ 登録したプロジェクトを跨いで扱う(`--project` / `--dir` とは一緒に使えず、serve 以外には付けられない。通常の serve の決め方は変えない)。
209
+ 閲覧専用にはせず、通常の serve と同じ操作(作成・編集・添付・設定・Preflight・タスク化・リリースノート)をプロジェクトごとにできる。
210
+
211
+ - 対象は個人設定に登録した名前だけ(`core/projectRegistry.ts` の `ProjectRegistry`)。任意のパスは開かず、名前は登録名の形
212
+ (`PROJECT_NAME`)で確かめる。API はプロジェクトごとに `/api/projects/<名前>/...` で、中身は通常の serve の `/api/...` と同じ
213
+ (`server/api/projectsRoutes.ts` が名前を外して `apiRoutes(ctx)` へ渡す。接続元の情報はそのままなので、ローカルだけの操作の
214
+ 確かめ方も同じ)。プロジェクトを書かないデータの API は 404(`project_required`)、無い API は画面ではなく 404 の JSON
215
+ - 一覧は `GET /api/projects` のたびに個人設定を読み直す(`inspectUserProjects`)。読めない・壊れた個人設定は登録0件と分けて
216
+ `configError` に出し、それまでの一覧と開いている文脈を残す。形の違う登録は `invalid` に理由を付け、ほかは使える。登録0件でも起動する
217
+ - 文脈(Workspace・PreflightService・ReleaseGenerator・変更通知)はプロジェクトごとに、使うときに開く。同時に開こうとしたら1回に
218
+ まとめ、失敗は覚えずに次でやり直す(フォルダを戻せば使える)。1つが開けなくてもほかは使える。`process.chdir` や「今の
219
+ プロジェクト」は持たないので、タブごとに別のプロジェクトを同時に操作できる
220
+ - 同じデータのフォルダ(実体のパス)を複数の名前で登録していたら、どれも開かない(Preflight・生成を二重に動かさないため。
221
+ どれを残すかは人が決める)
222
+ - 登録世代(`generation`): 一覧を読み直したときに、登録が無くなっていた・データのフォルダが変わっていた・重なりを解いたら変わる
223
+ (読み直すまでの間に外して同じフォルダで付け直したものは同じ登録として扱う。書き込む先は同じなので取り違えは起きない)。
224
+ 変える操作には `x-p3-project-generation` が要り、違えば 409(`changed`)で何も書かない(古い画面の保存を新しい登録先へ流さない。
225
+ 自動で送り直さない)。参照先のパスだけの変更は世代を変えずに今の文脈へ反映し、次の Preflight から使う
226
+ - 登録から外れた文脈には新しい要求を渡さない。始めていた Preflight・生成は元のプロジェクトで終わるまで待ってから閉じる(取り消さない)
227
+ - ChatGPT の接続(サインインの待ち受け)は全プロジェクトで1つ(`openProject` の `chatgpt`)。接続・テーマの変更は開いている
228
+ 全プロジェクトの画面へ知らせる。プロジェクトを選ばない入口(`/api/chatgpt`・`/api/user-theme`・`/api/events`)もある。
229
+ エンジンの状態はプロジェクトごと
230
+ - 画面(`web/Boot.tsx`・`web/lib/scope.ts`): ページを開いたときに `/api/mode` と URL(`/projects/<名前>`)からこの画面の対象を
231
+ 一度だけ決め(`fixScope`)、API の基点(`/api/projects/<名前>`)・登録世代のヘッダー・ルーターの basepath に使う。ページの間は
232
+ 変えない。切り替えはページごと移る(`components/ProjectSwitcher.tsx`)ので、前のプロジェクトの取得・SSE・タイマー・キャッシュ・
233
+ 遅い応答は新しいプロジェクトに混ざらない(文脈を差し替える仕組みを持たない)。保存していない入力は各画面が `useUnsaved` で、
234
+ 送っている保存は `api.ts` が数え(`lib/unsaved.ts`)、切り替えの前に確かめる・待つ。API が登録の変化(`changed` など)で断ったら
235
+ 知らせを出し、選び直しを案内する。対象が決まらない・開けないときは一覧(`components/ProjectChooser.tsx`)で理由を出す。入口(`/`)は登録が1つで開けるなら
236
+ 一覧を飛ばす(`location.replace`。`/?list` なら飛ばさない)。一覧は戻ったとき(`pageshow` の保存から)・タブに戻ったときに読み直す
237
+ - 止める(SIGTERM・SIGINT。通常の serve も同じ): 新しい接続を断り、開いている接続(SSE)を閉じ、実行中の Preflight・生成を取り消して
238
+ (記録は「中止しました」)終わるまで待つ(10 秒まで)。監視を外す。2回目の信号ではすぐ終わる
239
+
197
240
  ### 画面
198
241
 
199
242
  - 画面のテーマ(`ui.theme`)の反映: index.html の先頭(CSS より前)で `/api/user-theme.js` を同期で読み、
@@ -217,9 +260,10 @@ Preflight で扱う要望が、プロジェクトで行う作業の粒度にな
217
260
  済み・関係の操作のように入力欄以外を自分で変えたときは、入力欄の項目が変わっていなければ自分の上げた rev に合わせる。
218
261
  要望の取り直し(`web/lib/requestLoad.ts`): 404 は表示中なら gone(前の内容と入力を残して保存を止める)、初めからなら
219
262
  「見つかりません」。ほかの失敗は前の内容のまま知らせる。要望を移ると作り直す(`RequestDataProvider` の key)
220
- - 要望の画面の見出し(`routes/requests/$requestId.tsx` の RequestFrame)はタイトルとタスクの完了数だけ。ステータス・ID・
221
- ブランチの印は外した(ステータスは概要・Preflight の管理情報で選ぶ。ブランチはデータに残り、CLI で見る)。要望 ID は
222
- 概要・Preflight の管理情報(RequestMeta)のタイトルの上にだけ出す(`components/RequestIdCopy.tsx`)。コピーは
263
+ - 要望の画面の見出し(`routes/requests/$requestId.tsx` の RequestFrame)は要望 ID とコピー・タイトル・タスクの完了数だけ。
264
+ ステータス・ブランチの印は外した(ステータスは概要・Preflight の管理情報で選ぶ。ブランチはデータに残り、CLI で見る)。見出しと
265
+ タブは本文のスクロールの外に置き、要望 ID はタイトルの上に、どのタブでも1組だけ出す(`components/RequestIdCopy.tsx`。概要の
266
+ 管理情報(RequestMeta)には出さない。本文を下へ送ってもコピーできる)。コピーは
223
267
  `web/lib/copy.ts` の `copyText`(ボタンは枠つきでコピーのアイコンと文字。成功したらアイコンをチェックにする): Clipboard API が無ければ unavailable、拒まれたら denied(例外は外へ出さない)、書き込みが
224
268
  終わってから copied。知らせは role="status" で、どの ID の結果かを持ち、別の要望の結果は出さない。ボタンは mousedown で
225
269
  フォーカスを奪わないので、入力中のタイトルを保存させない。ID は select-all で、コピーできないときは手で選ぶ
@@ -316,8 +360,11 @@ src は5つの層に分け、依存の向きを `test/layers.test.ts` で確か
316
360
  | 画面の API の失敗の扱い(rev の競合・評価対象の変更・無い) | `web/lib/api.ts` の `failureOf` |
317
361
  | リリースノートの本文の下書き(外の変更・削除・読めないときに入力を残す・編集を始めた版で保存) | `web/lib/releaseNoteDraft.ts` |
318
362
  | 読み取り(一覧・参照の解き方・進捗) | `core/ops.ts` |
319
- | リリースノート(材料の規則・保存・出力・要約の生成) | `core/releaseNotes/`(`material.ts`・`store.ts`・`service.ts`・`generate.ts`) |
363
+ | リリースノート(材料の規則・保存・出力・要約の生成・要望の一括完了) | `core/releaseNotes/`(`material.ts`・`store.ts`・`service.ts`・`generate.ts`・`completeRequests.ts`) |
320
364
  | タスクの関係(`depends_on`・`supersedes` だけ。同じ要望の中。Preflight のタスク化だけが張る) | `shared/types.ts` の `RELATION_TYPES`・`core/preflight/service.ts` の `materialize` |
365
+ | プロジェクトを跨ぐ serve(登録の一覧・登録世代・文脈の開閉) | `core/projectRegistry.ts`(API は `server/api/projectsRoutes.ts`) |
366
+ | Preflight を通さずにタスクを作る道の案内(付かないものの言い方・失敗と取消の見分け。取消は `PREFLIGHT_CANCELLED` で残す) | `shared/directTask.ts`(CLI の案内文は `cli/output.ts` の `directTaskHint`) |
367
+ | マイルストーンの表示の順(ID のバージョンの降順。CLI・API・画面の一覧と選ぶ欄。project.yaml の順は変えない) | `shared/milestoneOrder.ts` |
321
368
 
322
369
  CLI は `cli/main.ts`(振り分け・プロジェクトと変更者の決定・終了コード)と、種類ごとのコマンド(`taskCommands.ts`・
323
370
  `requestCommands.ts`・`preflightCommands.ts`)に分ける。大きい画面は、ルートのファイルを組み立てだけにして部品を
@@ -481,6 +528,8 @@ package.json では公開版の版の範囲(`^0.2.0` など)で指定し、
481
528
  - `UsageLimitError` は使用量の上限(ChatGPT プランの `subscription_sharing_usage_limit_exceeded` を含む)
482
529
  - `ensureImage({ maxAgeMs })` はイメージが無いか `maxAgeMs` より古ければ作り直し、中の Codex の版を返す。作り直すたびに
483
530
  `CODEX_REFRESH`(その時刻)が変わるので、Codex を入れる段はキャッシュを使わず、その時点の最新が入る
531
+ - イメージの中身(Dockerfile)は `@infodb/codex-workspace` が同梱し、Python 版と同じ名前のイメージを共有する。
532
+ 中身が変わる版が出たら P3 も上げる(古い版のままだと、1日ごとの作り直しで共有のイメージを古い中身に戻す)
484
533
  - いつもの Preflight: 既定の1日より古ければ作り直す(個人設定 `codex.ensureImage: false` か `P3_CODEX_ENSURE_IMAGE=0` で止める)
485
534
  - 強制更新(`p3 codex update`): `maxAgeMs` を -∞ にして、作った日時によらず作り直す。プロジェクト・認証を決める前に動き、
486
535
  個人設定の自動更新の停止(`codex.ensureImage: false`)とも関係しない。前に `docker version` でデーモンを確かめ、
@@ -508,7 +557,8 @@ Playwright が入っても、それだけでは描画の安全の条件(ネッ
508
557
 
509
558
  - 版: Playwright 1.63.0(Chromium の headless shell)、Node 22(`node:22-bookworm-slim`)、`fonts-noto-cjk`。
510
559
  Playwright はイメージの中で npm から入れる(P3 の依存には足さない)。版は公開から1日を過ぎたものに固定する
511
- - イメージの名前は Dockerfile と `render.mjs` の中身の hash(`infodb-p3-render:<12桁>`)。中身が変われば次の描画で作り直す。
560
+ - イメージの名前は資材(`Dockerfile`・`fonts-ja.conf`・`render.mjs`。`render.ts` の `RENDER_IMAGE_FILES`)の中身の hash
561
+ (`infodb-p3-render:<12桁>`)。どれかが変われば(フォントの設定だけでも)次の描画で作り直す。
512
562
  大きさは約 1.4GB(amd64 で確かめた)
513
563
  - Chromium の sandbox は使わない。コンテナを囲いにする(`--network none`・`--read-only`・`--cap-drop ALL`・
514
564
  `no-new-privileges`・root ではない利用者・メモリ / CPU / プロセス数・時間の上限)。読み込みを止めるのは二重目の囲い
@@ -517,6 +567,15 @@ Playwright が入っても、それだけでは描画の安全の条件(ネッ
517
567
  `iframe` / `object` / `embed` / `link` / `base` / `meta http-equiv` は断る。幅は 320〜2560 px、原稿は 2MB まで、高さ 16384 px を超える
518
568
  ところは切る。DevContainer の中からは、出力先のフォルダにも `codex.pathMap` が要る
519
569
  - 日本語のフォントは Debian の `fonts-noto-cjk`(SIL Open Font License 1.1)。イメージの中にだけ入り、P3 の配布物には含めない
570
+ - Playwright の依存(`--with-deps`)で WenQuanYi Zen Hei(中国語の字形)も入り、fontconfig ではそれが総称の既定に先に来る。
571
+ `fonts-ja.conf`(`/etc/fonts/conf.d/99-p3-ja.conf` に置く)で、総称(`sans-serif`・`system-ui`・`serif`・`monospace`)と、
572
+ イメージに無い日本語のフォント名を Noto CJK JP に寄せる(対応は how-to-use.md の「画面資料」)。`binding="strong"` にするのは、
573
+ Chromium(Skia)が、名前で探したフォントの代わりに強く結んだものだけを受け入れるため。明示したほかのフォントと埋め込みのフォントは変えない
574
+ - Chromium の既定(フォントの指定なし)は Times New Roman(イメージでは Liberation Serif)で、欧文が明朝系になる。Codex の原稿の多くは
575
+ フォントを指定しないので、`render.mjs` が原稿の先頭(doctype の後。無ければ先頭で、quirks の判定は変わらない)に
576
+ `:where(html){font-family:sans-serif}` を足す。詳細度 0 で最初に置くので、原稿の指定(`html`・`body`・`*`・`:root` を含む)が必ず勝つ
577
+ - Chromium は無い字を総称に関係なく探すので、`serif` の欧文(Liberation Serif)に無いかな・漢字は Noto Sans CJK JP になる。
578
+ `Times New Roman` を明朝体に寄せると、`sans-serif` のかな・漢字まで明朝体になったのでやめた
520
579
 
521
580
  ### 添付の確かめ方と置き場所
522
581
 
@@ -563,14 +622,17 @@ Playwright が入っても、それだけでは描画の安全の条件(ネッ
563
622
  ファイル内容のハッシュによる楽観ロックに変えれば、`rev` をファイルに書かずに済む。要望単位で人が排他するので優先度は低い(今後)
564
623
  3. **git を使わないメンバー。** 閲覧だけなら、静的な HTML に書き出して共有する(`p3 export`、今後)
565
624
 
566
- ## AI エージェントへの指示(`p3 init --agents` で AGENTS.md / CLAUDE.md に追記する内容)
625
+ ## AI エージェントへの指示(`p3 init --agents` / `p3 agents` で AGENTS.md / CLAUDE.md に足す節)
567
626
 
568
- 手順の詳しい版は同梱のスキル(原本は `skills/p3/SKILL.md` の1つ。プロジェクトの `.claude/skills/p3/SKILL.md`(Claude Code)と
569
- `.agents/skills/p3/SKILL.md`(Codex)に同じものを写す。置き場所の一覧は `src/cli/project.ts` の `SKILL_TARGETS`。
570
- 個人のスキルの場所には置かない)で、役割と終わり方は両方でそろえる
571
- (`src/cli/project.ts` の `AGENTS_SNIPPET`。`test/agents.test.ts` が確かめる)。
572
- `p3 init --agents` は既にあるスキル・追記を上書きしないので、原本を変えても各プロジェクトに置いたものには届かない。
573
- 変えたときは、置いたプロジェクトで手で更新する(`init --agents` が違いを知らせる)。
627
+ 手順の詳しい版は同梱のスキル(原本は `skills/p3/SKILL.md` の1つ。選んだ先(`claude` は `.claude/skills/p3/SKILL.md`(Claude Code)、
628
+ `codex` は `.agents/skills/p3/SKILL.md`(Codex))に同じものを写す。置き先の一覧は `src/cli/project.ts` の `AGENT_TARGETS`、
629
+ 選び方は `AGENT_CHOICES`。個人のスキルの場所には置かない)で、役割と終わり方は両方でそろえる
630
+ (`src/cli/project.ts` の `agentsSnippet`。節のスキルの参照は、選んだ先と既にある先だけを書く。下は両方のときの `AGENTS_SNIPPET`。
631
+ `test/agents.test.ts` が確かめる)。置き先を覚えておく共有の設定は持たない(参加の `join` は置かず、置く・最新にするのは人が明示する
632
+ `p3 agents` だけなので、消した先が戻らない)。
633
+ 既にあるスキル・節は上書きしないので、原本を変えても各プロジェクトに置いたものには届かない。変えたときは、置いたプロジェクトで
634
+ `p3 agents <先>` で違いを確かめ、`--force` で選んだ先のスキルと p3 の節だけを同梱の版にする(節の前後の文は残す。節が複数・
635
+ 見出しになっていなければ変えずに手で整理してもらう)。
574
636
 
575
637
  ```markdown
576
638
  ## タスク管理(infodb p3)
@@ -580,12 +642,15 @@ Playwright が入っても、それだけでは描画の安全の条件(ネッ
580
642
  - 変更するときは環境変数 `P3_ACTOR=ai:<エージェント名>` を付ける
581
643
  - 操作する要望は `--req <要望ID>` で指定する(要望の作業ツリーの中なら省ける)。まず `p3 whoami --json` で確かめる
582
644
  - `whoami` の `via`(プロジェクトの決まり方)が `cwd` でなければ(`dir` / `project` / `legacy` / `only`)、それ以上 p3 を操作せず、対象のプロジェクトでよいか人に確かめる(推測した `--project` / `--dir` で避けない。人が指定・確認した後はその対象のまま続ける)
645
+ - プロジェクトが無い・未登録のときは `p3 init` / `p3 join` を自分から実行せず、新しく作る(`init`)のか共有されたものに参加する(`join`)のかを人に確かめる
583
646
  - 新しい作業を頼まれたら `p3 request new "<タイトル>" --body "..."` で要望を登録し、ID を伝えて終える。
584
647
  Preflight(`preflight`)とタスク化(`accept`)は人が行う(AI は実行しない。結果を `p3 drafts` で読むのと、頼まれたメモの保存 `--note-only` はよい)
585
648
  - 着手する前に `p3 show T003 --brief --json` で本文・依存とその状態(`dependencies`)・置き換えの注意(`warnings`)を読む
586
649
  - 着手する前に、`--brief --json` の `work`(作業先のリポジトリとブランチ)を見て、そのリポジトリでブランチに入る(作業先なしなら移動しない)
587
- - 着手するときは `p3 move T003 doing`、終えたら `p3 move T003 done --output <PR の URL など> --record -`(変更の記録は必須: 何を変えたか・なぜ・入れた決まり・やめたもの を標準入力から Markdown で)。複数のリポジトリにまたがるときは最後のタスクに `--repo-output <参照先>=<PR の URL>` で全部の PR を残す
588
- - 要望のタスクを全部終えたら `p3 request set <要望ID> status=resolved`(対応済)にする。完了済(done)・見送り(rejected)とタスクの済み(check)は人が決める
650
+ - 着手するときは `p3 move T003 doing`。テストを通したら、コミットする前に `p3 move T003 done --output <今ある成果物(変えたファイルや説明)> --record -` で完了にする(変更の記録は必須: 何を変えたか・なぜ・入れた決まり・やめたもの を標準入力から Markdown で。まだ無い URL は書かない)
651
+ - 要望のタスクを全部終えたら、コミットする前に `p3 request set <要望ID> status=resolved`(対応済)にする。完了済(done)・見送り(rejected)とタスクの済み(check)は人が決める
652
+ - データのフォルダがこの作業ツリーの中で git 管理されているなら、要望のフォルダ(`requests/<要望ID>/`)の変更も実装と同じコミットに入れる(ほかの要望・関係ない変更は入れない。外・無視・worktree のときは入らないので、移動や `git add -f` はしない)。push に失敗したら完了の記録は残し、公開できていないことを伝える
653
+ - コミットや PR の URL は後から `p3 move T003 done --output <URL>` で足す(完了・記録はそのまま。データをコミットしているなら追記もコミットして push)。複数のリポジトリにまたがるときは最後のタスクに `--repo-output <参照先>=<PR の URL>` で全部の PR を残す
589
654
  - 置き換えられたタスク(`p3 ls` の `※置換`、`--json` の `superseded`)からは始めない。`move` が `warnings` を返したら止めて人に確かめる
590
655
  - 作業中に新しく必要になった作業は `p3 new "<タイトル>" --body "..."` でタスクにする(人への質問はタスクにしない)
591
656
  ```
@@ -30,9 +30,11 @@ pnpm build && pnpm start # ビルドした画面を p3 serve から配信 h
30
30
  pnpm typecheck
31
31
  pnpm lint # oxlint(型情報も使う。下の「lint」)
32
32
  pnpm test # ユニットテスト(vitest)。pnpm test:watch で監視
33
- pnpm check # 型検査 + lint + テスト + ビルド
33
+ pnpm test:ui # ブラウザで画面を操作する UI テスト(ビルドした画面が要る。下の「UI テスト」)
34
+ pnpm check # 型検査 + lint + テスト + ビルド + UI テスト
34
35
  pnpm demo:reset # デモデータ(.p3-demo/)を作り直す
35
36
  pnpm verify:pack # 配布物を別の場所に入れて動かす(--docker で codex update と render も)
37
+ pnpm video # 使い方の動画を録り直す(.p3-video/p3-demo.mp4。下の「使い方の動画」)
36
38
  ```
37
39
 
38
40
  - `pnpm dev` / `pnpm start` は P3 自身の開発を題材にしたデモデータ(`.p3-demo/`、git 管理外)を開く。無ければ自動で作る
@@ -48,8 +50,8 @@ pnpm verify:pack # 配布物を別の場所に入れて動かす(-
48
50
  - テストは一時ディレクトリに git リポジトリと `.p3/` を作って動かす(`test/helpers.ts`)
49
51
  - Codex の経路は、JSON-RPC を話す偽の app-server(`test/fixtures/fake-codex.mjs`)に差し替えて確かめる。本物の Codex が実際に
50
52
  どこまで読むか、読むだけのマウントへの書き込みが拒まれることは、偽の app-server では確かめられない
51
- - `init --agents` で置いたスキルを本物の Codex が見つけて読むかは、偽の app-server では確かめられない。置き場所
52
- (`SKILL_TARGETS`)や Codex の版を変えたときは、手で確かめる(結果はタスクの変更の記録に残す):
53
+ - `init --agents` / `p3 agents` で置いたスキルを本物の Codex が見つけて読むかは、偽の app-server では確かめられない。置き場所
54
+ (`AGENT_TARGETS`)や Codex の版を変えたときは、手で確かめる(結果はタスクの変更の記録に残す):
53
55
 
54
56
  ```bash
55
57
  # 一時フォルダに git リポジトリを作り、個人設定も分けて置く(p3 を使わない別のリポジトリ other/ も作っておく)
@@ -71,6 +73,38 @@ pnpm verify:pack # 配布物を別の場所に入れて動かす(-
71
73
  pnpm vitest run test/showBrief.test.ts --reporter=verbose
72
74
  ```
73
75
 
76
+ ### UI テスト
77
+
78
+ `test/ui/*.ui.test.ts` は、ブラウザ(Playwright の Chromium headless shell)で `p3 serve` のビルドした画面を開いて操作する。
79
+ 設定は `vitest.ui.config.ts` で、通常の `pnpm test` には入らない。型検査・lint の対象には入る。
80
+
81
+ - `pnpm check` は、型検査・lint・テスト・ビルドの後に `pnpm test:ui` を流す。単独で流すときは先に `pnpm build` する
82
+ (ビルドが無ければ、Chromium の有無によらず失敗にする)
83
+ - Chromium は `pnpm exec playwright-core install chromium-headless-shell` で入れる(自動では入れない)。Playwright が起動する
84
+ 実行ファイル(既定のキャッシュか `PLAYWRIGHT_BROWSERS_PATH`)が無いときだけ、理由と入れ方を出して UI テストを飛ばす(件数は
85
+ vitest の skipped に出る)。実行ファイルがあるのに起動できない(共有ライブラリが無いなど)・サーバが起きない・操作の対象が
86
+ 見つからないときは失敗にする(判定は `test/ui/chromium.ts`、本物の Chromium を使わない確認は `test/uiHarness.test.ts`)
87
+ - シナリオごとに一時のフォルダを作り、その中に HOME・個人設定(`XDG_CONFIG_HOME`)・git リポジトリ・データを置いて、本物の CLI
88
+ (`bin/p3.mjs init`・`serve`)で動かす(`test/ui/env.ts`)。子の p3 には親の `P3_*`・`INIT_CWD`・`GIT_*`・`XDG_*` を渡さず、
89
+ Mock のエンジン・変更者・cwd を明示する。手元の個人設定・プロジェクト・`.p3-demo/` には触れない。`p3 serve` は 127.0.0.1 の
90
+ 空いたポートで起こす(取られていたら別のポートで試し直す)。ブラウザは親の環境で起こす(一時の HOME をブラウザの探索に使わない)
91
+ - 主な流れ(`test/ui/flow.ui.test.ts`): 要望の登録 → Mock の Preflight → 評価と案 → タスク化 → ボード → タスクの着手・完了
92
+ (成果物・変更の記録)→ 済み → 要望の完了済を、すべて画面の操作で進め、再読み込みと CLI でも残っていることを確かめる
93
+ - 表示(`test/ui/layout.ui.test.ts`): 進捗・新しい要望・概要と Preflight の案・タスクボード・タスクの詳細を幅 1280 と 375 で、
94
+ 案の詳細(Markdown の本文)を幅 375 / 768 / 1280 の明暗のテーマで開き、長い題・長いパス・複数の案・依存・表とコードのある本文で確かめる:
95
+ ページ全体の横のはみ出し、枠(カード・行・詳細)からのはみ出し、ボードの並び(広い幅は未着手と完了が横、狭い幅は縦に積む)、
96
+ 詳細の枠と閉じるボタンが画面に収まること、局所スクロール(進捗の表・案の段階の列・本文・表・コード)の先へ届くこと、主な操作に届くこと、
97
+ 閉じる / Escape の後に開いたボタンへフォーカスが戻ること。状態(要望・Preflight・タスク化・案の本文)は CLI とデータのファイルで用意し、
98
+ 開く・閉じるなどの確かめる操作はブラウザで行う。測り方(`test/ui/layout.ts`)は DOM の寸法で、意図した局所スクロール(overflow が
99
+ visible 以外の要素の中)とページ全体のはみ出しを分ける。測り方が崩れを見逃さないことも、わざと崩した要素で確かめる
100
+ - 限界: 画像の比較はしないので、色・重なり方・文字の欠けなど、測っていない見た目の乱れは保証しない。測るのは上の画面・幅・テーマだけ
101
+ - 日本語のフォント: Noto Sans CJK JP があれば、ブラウザを使い方の動画と同じ fontconfig(`scripts/fonts-ja.conf`)で起こし、寸法を
102
+ 日本語のフォントで測る(無い環境では既定のフォントのまま測り、そのことを出す。飛ばしはしない)
103
+ - 操作の対象は画面の文言・role・label で探し、固定の sleep はせず状態を待つ(上限は `UI_TIMEOUT`。`test/ui/scenario.ts`)。
104
+ 失敗すると、シナリオと手順・対象・その時の URL・画面の画像(`/tmp/p3-ui-failed-*/page.png`。中身は一時のデータだけ)・
105
+ `p3 serve` のログの末尾を出す。画面の文言を変えたら、そのテストの対象の名前を直す
106
+ - 成功・失敗・時間切れのどれでも、ブラウザとサーバを止めて終わるのを待ってから一時のフォルダを消す(診断用の画像だけ残る)
107
+
74
108
  ## lint
75
109
 
76
110
  `pnpm lint` は [oxlint](https://oxc.rs/docs/guide/usage/linter) で、型情報を使う規則(`--type-aware`。`oxlint-tsgolint` が
@@ -143,8 +177,8 @@ src/ 依存の向き: shared ← core ← server / cli、web →
143
177
  routeTree.gen.ts ルート一覧(自動生成)
144
178
  components/ 部品(複数のページで使うもの。大きいページの部品は components/<ページ>/)
145
179
  bin/p3.mjs CLI の起動口(tsx でソースをそのまま動かす)
146
- skills/p3/SKILL.md AI 向けスキルの原本(p3 init --agents で各プロジェクトの .claude/skills と .agents/skills に写す)
147
- scripts/ デモデータ・配布物の確認
180
+ skills/p3/SKILL.md AI 向けスキルの原本(p3 init --agents / p3 agents で各プロジェクトの .claude/skills・.agents/skills の選んだ先に写す)
181
+ scripts/ デモデータ・配布物の確認・使い方の動画(video/)
148
182
  docs/ 導入・使い方・開発・設計・公開の文書
149
183
  test/ ユニットテスト
150
184
  ```
@@ -171,12 +205,54 @@ test/ ユニットテスト
171
205
  | bin | `p3`。起動口は今いる場所の `tsconfig.json` を読まない。`INIT_CWD` に戻るのは P3 自身の `pnpm p3` スクリプトのときだけ |
172
206
 
173
207
  ```bash
174
- pnpm -s check # 型検査・lint・テスト・画面のビルド
208
+ pnpm -s check # 型検査・lint・テスト・画面のビルド・UI テスト
175
209
  pnpm verify:pack --docker # npm pack → 実行時の依存だけで別の場所に入れて動かす(scripts/verify-pack.mjs)
176
210
  # DevContainer の中では、描画の出力先を Docker のホストから見えるところにする
177
211
  P3_CODEX_PATH_MAP=/workspaces=/home/me/workspaces pnpm verify:pack --docker --render-dir /workspaces/tmp
178
212
  ```
179
213
 
214
+ ## Docker のイメージ
215
+
216
+ `Dockerfile`(Docker Hub の `tamuto/p3`。ビルドは Node 24 と packageManager の pnpm でロックファイルどおりに入れ、`pnpm pack` と同じ中身に実行時の依存だけを
217
+ 入れる。実行は Node 22・git・Docker の CLI と buildx。既定は `serve --all-projects --host 0.0.0.0`)と `.dockerignore`
218
+ (git・依存・ビルドの出力・データ・個人設定・認証・テストを入れない)。約束は `test/docker.test.ts` が確かめる。
219
+ 公開(人が行う)は [publishing.md](publishing.md#6-docker-hubtamutop3) の手順で、CI は使わない。使い方は [導入ガイド](installation.md#docker-で動かすプロジェクトを跨ぐ-serve)。
220
+
221
+ ```bash
222
+ docker build -t tamuto/p3:dev .
223
+ node scripts/verify-docker.mjs # ビルドして、使い捨ての2つのプロジェクトで動かす(スモーク)
224
+ # DevContainer の中では、Docker のホストから見えるフォルダと、そのホストのパスを渡す。公開したポートはホストにしか開かないので、
225
+ # このコンテナのネットワークに入れる
226
+ P3_CODEX_PATH_MAP=/workspaces=/home/me/workspaces node scripts/verify-docker.mjs --work /workspaces/tmp --network-of auto
227
+ ```
228
+
229
+ スモークで確かめること: 起動の約束(ENTRYPOINT・既定の CMD・入れた道具)・2つのプロジェクトの一覧・登録世代つきの作成と手元の
230
+ ファイル・同じ ID の分離・添付・ソケットが無いときのエンジンの状態・Mock の Preflight の同時実行と片方の取消・再起動のあとに残る
231
+ こと・データのフォルダの欠落と復旧・`docker stop`(SIGTERM)で実行中の Preflight を取り消して止まること・コマンドの明示で通常の
232
+ serve になること。本物の Codex(ソケット・pathMap・ChatGPT の接続)での Preflight・画面資料・要約の生成は、このスクリプトでは
233
+ 確かめない(接続できる環境で手で確かめ、結果を PR に残す。Mock の成功で代わりにしない)。
234
+
235
+ ## 使い方の動画
236
+
237
+ 一般公開する使い方の動画(日本語の字幕、約3分)は `pnpm video` で録り直す(`scripts/video/record.mjs`)。機能や画面を
238
+ 変えて動画と合わなくなったら、台本(同じファイルの `scenes`。場面ごとの操作と字幕)を直して録り直す。出来上がりは
239
+ `.p3-video/p3-demo.mp4`(git 管理外。`--out <mp4>` で変える)で、リポジトリには入れない(公開先は人が決める)。
240
+
241
+ - 架空の経費精算アプリのリポジトリを使い捨ての HOME(`/home/me`)に作り、① 導入(`p3 init`)→ ② 要望の登録(AI の CLI と
242
+ `p3 serve`)→ ③ Preflight → ④ 作業(AI の CLI と再読み込み)→ ⑤ 確認とリリース の順に、実際に p3 を動かしながら録る。
243
+ ② の前に過去の要望と v1.0 のリリースを入れる(`scripts/video/seed.sh`。その間は録らない)。Preflight とリリースノートの
244
+ 要約は Mock(字幕とタイトルでそう断る)
245
+ - 映るのは汎用のパスと名前だけにする(`/home/me/src/expense`・`human:demo`・`github.com/example`)。P3 自身のデータは映さない
246
+ - 前提: Chromium(`pnpm exec playwright-core install chromium-headless-shell`)、ffmpeg(libx264)、日本語のフォント
247
+ Noto Sans CJK JP(Debian / Ubuntu なら `fonts-noto-cjk`)、`/home/me` を作れること(DevContainer の root なら作れる)、
248
+ ポート 4310 が空いていること。足りなければ録り始める前に止める。日本語は録画のときだけの fontconfig(`scripts/fonts-ja.conf`。UI テストと共用)で
249
+ Noto Sans CJK JP に寄せる(中国語の字形のフォントで描かれないように)
250
+ - `/home/me` は印(`.p3-video-demo`)のあるときだけ消して作り直す。終わったら消す
251
+ - 画面の文言や操作が変わって操作の対象が見つからないと、15 秒で「場面「③ Preflight」で止まりました(対象: ボタンの名前)」と
252
+ その時の画面の画像の場所を出して止まる(作業のフォルダは残す)。台本の対象の名前を今の画面に合わせて直す
253
+ - 録画は Chrome DevTools Protocol の screencast(変わったときだけ届く JPEG)で、届いた時刻から各フレームの長さを決めて
254
+ ffmpeg で 30fps の mp4 にする(字幕・カーソル・CLI のパネルはページに重ねる `scripts/video/overlay.js`)
255
+
180
256
  ## 文書を直すとき
181
257
 
182
258
  | 文書 | 書くこと |
@@ -191,4 +267,4 @@ P3_CODEX_PATH_MAP=/workspaces=/home/me/workspaces pnpm verify:pack --docker --re
191
267
 
192
268
  同じ説明を複数の文書に書かない(片方からリンクする)。確認作業の記録(どの幅・どのブラウザで確かめたか)は文書に書かず、
193
269
  PR とタスクの変更の記録に残す。CLI のヘルプ(`src/cli/help.ts`)・API の説明(`src/server/api/manifest.ts`)は入口が変わったとき、
194
- AI の手順が変わったときは `skills/p3/SKILL.md` と `src/cli/project.ts` の `AGENTS_SNIPPET` の両方を直す。
270
+ AI の手順が変わったときは `skills/p3/SKILL.md` と `src/cli/project.ts` の `agentsSnippet`(`AGENTS_SNIPPET`)の両方を直す。
@@ -126,10 +126,26 @@ git switch -c req/261009-k7m3x-notify # request show で見た実際の
126
126
  export P3_ACTOR=ai:claude # 変更者の記録(AI は ai:<名前>)
127
127
  p3 show T001 --brief --json # 本文・依存とその状態・作業先とブランチ・置き換えの注意
128
128
  p3 move T001 doing # 着手
129
- # ... 作業し、テストを通し、コミットして push する ...
130
- p3 move T001 done --output https://github.com/me/myapp/pull/42 --record - < record.md
129
+ # ... 作業し、テストを通す ...
130
+ p3 move T001 done --output "src/notify.ts(送信)" --record - < record.md # コミットする前に完了にする
131
+ p3 request set k7m3x status=resolved # 最後のタスクなら、これもコミットの前に(7.)
132
+ git add src/notify.ts .p3/requests/261009-k7m3x # データを git で管理していれば、要望のフォルダも同じコミットに
133
+ git commit -m "通知の送信" && git push
134
+ p3 move T001 done --output https://github.com/me/myapp/commit/<sha> # URL は後から足す(完了・記録はそのまま)
135
+ git add .p3/requests/261009-k7m3x && git commit -m "成果物の URL" && git push
131
136
  ```
132
137
 
138
+ - **完了を記録してからコミットする**: テストを通したら、コミットの前に完了(と最後なら対応済)を保存する。データのフォルダが
139
+ リポジトリの中にあって git で管理していれば、要望とタスク・変更の記録が実装と同じコミットに入り、PR / MR を見る人は
140
+ 「何を頼まれ、何をしたか」をコードと一緒に読める。入れるのはその要望のフォルダだけ(ほかの要望の変更は入れない)
141
+ - 成果物は、完了にする時点で今あるもの(変えたファイル・ドキュメントのパス・短い説明)。まだ無い URL や仮の SHA は書かない。
142
+ コミット・PR / MR の URL は push してから `move … done --output <URL>` で足す(完了・記録・前の成果物・完了の日時は変わらず、
143
+ 要望も進行中に戻らない)。この追記は次のコミットに入れる(追記のコミット自身の URL は要らない)
144
+ - データのフォルダがリポジトリの外・別のリポジトリ・git で無視されているときは、同じコミットには入らない。git の作業ツリー
145
+ (worktree)で作業していても、データは登録したフォルダ(既定はメインの作業ツリーの `.p3`)に書かれ、その作業ツリーのコミットには
146
+ 入らない。どちらもデータを移したり写したり `git add -f` したりせず、コードとは成果物の URL で結ぶ
147
+ - push に失敗しても、完了の記録はそのまま。公開できていないだけなので、直して push し直す
148
+
133
149
  - 依存の相手が終わっていないタスクや、置き換えられたタスク(`※置換`)からは始めない
134
150
  - **変更の記録**(`--record`)は、何を変えたか・なぜ・入れた決まり・やめたものを Markdown で短く書く。AI が完了にするときは必須。
135
151
  後の Preflight が経緯を調べるとき、タスクの解析・リリースノートの材料になる
@@ -137,7 +153,8 @@ p3 move T001 done --output https://github.com/me/myapp/pull/42 --record - < reco
137
153
 
138
154
  ### 7. 要望を対応済にする
139
155
 
140
- 全タスクを完了にしたら、作業した側が要望を **対応済** にする(人に確認を頼む印)。
156
+ 全タスクを完了にしたら、作業した側が要望を **対応済** にする(人に確認を頼む印)。最後のタスクのコミットの前にしておけば、
157
+ 対応済も同じコミットに入る(6.)。
141
158
 
142
159
  ```bash
143
160
  p3 request set k7m3x status=resolved
@@ -255,6 +272,39 @@ p3 move T005 done --repo-output app=https://…/pull/1 --repo-output infra=https
255
272
 
256
273
  `areas` と根拠の参照は `<参照先>:<パス>`(例 `docs:guide/`)で書ける。名前なしは先頭の参照先の中のパス。
257
274
 
275
+ ### Preflight を通さずにタスクを作る
276
+
277
+ 小さく内容のはっきりした要望なら、Preflight を通さずにタスクを直接作ってよい。Docker や ChatGPT の接続が無い・Preflight が
278
+ 止まる間も、同じ道で進められる(要望・タスク・変更の記録・マイルストーンは Docker も ChatGPT も使わない)。直接作ったタスクには、
279
+ Preflight の評価・細分化・根拠の調査・画面イメージは付かない。必要な調査と完了条件は、作る人が整理して本文に書く。
280
+
281
+ 流れ: 要望を書く(1.)→ タスクを直接作る(下)→ 作業を始めるなら要望を進行中にする → いつもどおり作業・変更の記録・確認(6.〜8.)。
282
+
283
+ - **画面**: 要望のタスクボードの「+ タスクを追加」(タスクが無くても出る)。題(必須。空白だけは不可)・本文(作業内容・
284
+ 完了条件)・作業先を書いて「作成」で、未着手のタスクになる。作業先は作業先にできる参照先か「作業先なし」から選び、
285
+ 既定は CLI と同じ(作業先にできる参照先が1つならそれ)。Enter で作成、Escape か「取消」で保存せずに閉じる。
286
+ 保存に失敗したときは入力が残り、タスクの一覧を読み直す(保存できたあとで失敗したこともあるので、同じタスクが未着手に
287
+ できていないか確かめてから、もう一度作成する)
288
+ - **CLI**: `p3 new "<題>" --req <要望> --body "<作業内容と完了条件>"`(作業先は `--repo`。後の「参照先と作業先」)
289
+ - 関係(依存・置き換え)は張らない。順序が要るなら本文に書く
290
+ - 要望の状態は、下書き・評価中・開始前のときは変わらない。作業を始めるときは、概要のステータスを「進行中」にする
291
+ (CLI は `p3 request set <要望> status=active`)。対応済の要望に足したときは進行中に戻る(後の「状態」)
292
+
293
+ **Preflight を使えないときの案内**: Docker が無い・デーモンに繋がらない・権限が無い、ChatGPT に未接続、使用量の上限、そのほかの
294
+ Codex の失敗のどれでも、止まった理由と直し方に並べて、この道を案内する。
295
+
296
+ - 画面: 概要のエンジンの状態が ✕ のとき・失敗した run に「Preflight を通さずにタスクを作成」(タスクボードのフォームが開く)。
297
+ 個人設定の ChatGPT の欄には、要望を開いてタスクボードで作る手順。エンジンの状態を確かめられなかった(通信の失敗)ときは、
298
+ 使えるとも使えないとも言えないので案内しない
299
+ - CLI: `p3 preflight` が始められなかった・失敗したときに、実際の要望 ID で `p3 new "タスクの題" --req <要望> --body "作業内容と完了条件"`
300
+ を stderr に出す(`--project` / `--dir` を付けていればそのまま付ける)。終了コードと `--json` の stdout は変えない
301
+ - 取り消しただけの run(「中止しました」)・実行中は失敗と扱わず、案内しない
302
+
303
+ **後から Preflight を使えるようになったら**: その要望にも `p3 preflight <要望>`(画面は概要の「▶ Preflight を実行」)で評価できる。
304
+ 実行しても既にあるタスクは変わらない。案をタスク化すると新しいタスクが増えるので、直接作ったタスクと重なる案は採らない
305
+ (5. で採否を選ぶ)。案が既にあるタスクを置き換えるとき(`supersedes`)は、同じ要望の中で人が採否とアーカイブを選ぶ
306
+ (後の「タスクの関係と置き換え」)。自動で置き換えたりまとめたりはしない
307
+
258
308
  ### 要望の本文を変えたとき
259
309
 
260
310
  要望のタイトル・本文は、いつでも書き換えられる(画面の「本文を編集」→「本文を保存」、CLI の `request set`)。
@@ -302,7 +352,8 @@ Preflight は始めたときの内容を固定して評価する。**評価の
302
352
 
303
353
  ### 成果物と変更の記録
304
354
 
305
- - **成果物**(`outputs`): 1項目ずつ、PR / MR の URL・文章・ドキュメントのパスのどれでもよい。項目全体が `http(s)://` の URL なら
355
+ - **成果物**(`outputs`): 1項目ずつ、PR / MR の URL・文章・ドキュメントのパスのどれでもよい。完了にするときは今あるもの
356
+ (変えたファイルや説明)を書き、URL は push してから `move <T> done --output <URL>` で足す(完了のまま追記する)。項目全体が `http(s)://` の URL なら
306
357
  画面でリンクになる(文章の中の URL は拾わない)。足すのは `move <T> done --output 値`(繰り返し可。カンマで分けない)か画面の
307
358
  「成果物を編集」。`set <T> outputs=a,b` はカンマで分けて置き換える
308
359
  - **リポジトリごとの成果物**(`repoOutputs`): `--repo-output <参照先>=<URL>`。複数のリポジトリにまたがるときに最後のタスクに残す
@@ -314,6 +365,13 @@ Preflight は始めたときの内容を固定して評価する。**評価の
314
365
  - **期限**(`due`): 要望の期限(`--due YYYY-MM-DD`)。進捗のスケジュールに ⚑ で出る
315
366
  - **マイルストーン**: まとめてリリースする単位(`p3 milestone add v0.2 --title "通知まわり" --due 2026-11-30`、要望に `--milestone v0.2`)。
316
367
  リリースノートはマイルストーンごとに作る([リリースノート](#リリースノート))
368
+ - **並び**: 選ぶ欄(新しい要望・要望の概要)・進捗のまとまり・リリースノートの一覧・設定・`p3 milestone` / `progress` / `config` の
369
+ 一覧は、**ID のバージョンの降順**(新しいものが上)。比べるのは ID だけで(タイトル・期限・リリース済みかは見ない)、先頭の
370
+ `v` / `V` は比べるときだけ外し、数字は数として比べる(`0.10.0` > `0.9.0`、`v2.0` > `v1.10` > `v1.9`)。バージョンでない ID も
371
+ 同じ規則で並べる(SemVer のプレリリースの順は持たない)。選ぶ欄の「(なし)」は先頭、進捗の「マイルストーンなし」と
372
+ project.yaml に無いリリースノートは最後。リリースノートの画面は、指定(`?m=`)が無ければ先頭を開く
373
+ - project.yaml の順は表示のために変えない(足した順のまま)。設定の画面は開いたときに降順に並べ、編集の間は行を動かさない
374
+ (ID を書き換えても、足した行は最後のまま)。保存すると並べ直す
317
375
  - **タグ**(`tags`): 外部 ID や分類の自由な文字列(例 `jira:PROJ-123`、`group:顧客A`)。同じ値を複数の要望に付けてグループにできる。
318
376
  要望・タスクの参照の代わりにはせず、外部のシステムとは同期しない
319
377
  - CLI: `request new --tag 値`(繰り返し可。カンマで分けない)、`request set <要望> --tag 値 ...`(この並びに置き換える)、
@@ -344,10 +402,45 @@ p3 release-notes export v0.2 > RELEASE.md # 公開する本文だけ(出
344
402
  - **生成**: Preflight と同じ Codex の接続(ChatGPT プラン)で頼む。渡すのはマイルストーンのタイトルと、要望・タスクの ID・タイトル・
345
403
  変更の記録だけ。結果の出典(要望・タスク)は P3 が確かめ、内部のパスらしいものは警告する。Ctrl-C で取り消せる。
346
404
  `--engine mock` は要約しない試し用(記録の1行目を並べる)
405
+ - **生成せずに手で書く**: 本文の保存は生成によらず、Docker も ChatGPT の接続も要らない。生成できない(Codex を使えない・
406
+ 使用量の上限・材料が無いなど)ときも、この手順で進める。画面では生成の欄の案内と、失敗したときの「本文を手で書く」から
407
+ 本文の欄へ進む(失敗・再生成しても入力は消えない)
408
+
409
+ ```bash
410
+ p3 release-notes show v0.2 # 材料(収録する要望と変更の記録)を確かめる
411
+ # 変更の記録を読んで、本文(Markdown)を notes.md に書く
412
+ p3 release-notes save v0.2 --file notes.md # 新しく保存する
413
+ p3 release-notes show v0.2 --json # 既にあるノートを更新するなら、版(note.version)を読む
414
+ p3 release-notes save v0.2 --file notes.md --version <版>
415
+ p3 release-notes export v0.2 > RELEASE.md
416
+ ```
417
+
418
+ `p3 release-notes generate` が始められない・失敗したときも、このコマンドを stderr に出す(取り消しただけなら出さない)
347
419
  - **古い材料**: 生成や保存のあとで要望・タスクが変わると「材料が変わった」と知らせる(本文は自動では直さない)。
348
420
  必要なら生成し直して、確かめてから保存する
349
421
  - **競合**: 保存したノートを直すときは、読んだときの版(`--version`)が要る。画面・エディタなど別のところで先に変わっていれば
350
422
  終了コード 3 で何も書かない。`show` で読み直してからやり直す
423
+ - **要望を一括で完了済にする**: リリースが終わったら、人がマイルストーンの要望の状態をまとめて閉じられる(対応済 → 完了済)。
424
+ できるのは、見送りを除く全要望が収録の条件(対応済か完了済・タスクが全部完了・読めないタスクなし)を満たすときだけ。
425
+ 変えるのは対応済の要望だけで、完了済・見送り、タスク(済みを含む)、ノート、マイルストーン(リリース済み)は変えない。
426
+ 変更の記録が無い・ノートを保存していない・済みを付けていないことは条件にしない。ノートの保存・生成とは別の、明示の操作
427
+
428
+ ```bash
429
+ p3 release-notes show v0.2 # 「要望の一括完了」に、できるか・できない理由・完了済にする要望と実行のコマンド
430
+ p3 release-notes complete-requests v0.2 --based-on <材料の hash> # show に出た hash で実行する
431
+ ```
432
+
433
+ - 確かめたあとで要望・タスクが変わっていれば(hash が違う)何も変えずに終了コード 3。できない(未完了がある)ときも何も
434
+ 変えずに終了コード 1。`show` で読み直してからやり直す
435
+ - 1件ずつ書くので、途中で別の変更とぶつかる(要望が変わった・タスクが戻った)・書けないと、その要望で止まる。完了済にした
436
+ もの・止まった要望と理由・まだ変えていないものを出す(戻さない)。直して `show` から読み直し、もう一度実行すれば残りを
437
+ 完了済にする(完了済にしたものは書き直さない)
438
+ - 完了済にすると材料が変わるので、保存したノートには「材料が変わった」と出る(本文はそのまま)
439
+ - 画面では、マイルストーンの「このマイルストーンの要望」の下の「要望の一括完了」。できないときは理由(要望ごと)と要望を開く
440
+ 導線を出し、ボタンは押せない。対象が無ければ「完了済にする要望はありません」。「要望を一括で完了済にする(N件)」で対象の
441
+ 要望と「タスクの済みは変えない」ことを確かめる欄を開き、キャンセルできる。実行の結果(完了済にした件数・途中で止まったときの
442
+ 完了済にした / 止まった / まだ変えていない)を出し、表示と進捗を取り直す。表示したあとで変わっていれば何も変えずに知らせる
443
+ (自動では頼み直さない。内容を確かめてもう一度押す)。本文の入力は消えない
351
444
  - **ファイル**: `<データのフォルダ>/release-notes/<マイルストーン>.md`(本文と、出典を書いた frontmatter)。エディタで直してもよい。
352
445
  壊すと「読めない」と出て、直すまで新しく保存しない。ノートのあるマイルストーンは消せない。保存の形と直し方は
353
446
  [docs/architecture.md](architecture.md#リリースノートのデータ)
@@ -377,21 +470,55 @@ p3 attach rm <A-ID>
377
470
  p3 render 画面.html --width 1280 # 画面.png ができる(幅 320〜2560 px・原稿 2MB まで。スクリプト・外部の参照は使えない。data: の画像はよい)
378
471
  ```
379
472
 
473
+ 日本語は Noto CJK JP で描く(描画のイメージに入っているのは Noto CJK と欧文のフォントだけ):
474
+
475
+ - ゴシック体の `sans-serif`・`system-ui` と、無いフォントの名前 `Noto Sans JP`・`Hiragino Sans`・`Hiragino Kaku Gothic ProN`・
476
+ `ヒラギノ角ゴ ProN`・`Yu Gothic`・`游ゴシック` は Noto Sans CJK JP
477
+ - 明朝体の名前 `Noto Serif JP`・`Hiragino Mincho ProN`・`Yu Mincho`・`游明朝` は Noto Serif CJK JP、`monospace` は Noto Sans Mono CJK JP
478
+ - フォントを指定していない原稿は `sans-serif`(欧文は Liberation Sans、かな・漢字は Noto Sans CJK JP)。原稿の指定はどれもこれより優先する
479
+ - `serif` だけを指定すると、欧文は Liberation Serif、かな・漢字は Noto Sans CJK JP(ゴシック体)。明朝体にするなら上の名前を指定する
480
+ - ほかに明示したフォント(`Noto Sans CJK SC` など)と、`data:` で埋め込んだフォントはそのまま使う
481
+ - 描き方の決まりが変わると、次の描画で描画のイメージを作り直す。保存済みの PNG は描き直さない(新しく描くには Preflight をかけ直す)
482
+
380
483
  ### 画面
381
484
 
382
485
  `p3 serve` で開く(既定 http://localhost:4310)。画面の状態は URL に載る。
383
486
 
487
+ `p3 serve --all-projects` で開くと、今いる場所のプロジェクトではなく、個人設定に登録したプロジェクト(`p3 project ls`)を跨いで
488
+ 扱う。どのプロジェクトでも通常の serve と同じ操作ができる(閲覧専用ではない)。`--project` / `--dir` とは一緒に使えない。
489
+ 登録を足した・外したら、画面で一覧を読み直せば反映する(serve の起動し直しは要らない)。同じデータのフォルダを複数の名前で
490
+ 登録していると、どれも開かない(`p3 project rm <名前>` で1つにする)。決まりは [architecture](architecture.md#プロジェクトを跨ぐ-servep3-serve---all-projects)
491
+
492
+ - **選ぶ**: 入口(`/`)は登録したプロジェクトの一覧(行のどこを押しても開く)。登録が1つだけで開けるときは、一覧を飛ばして
493
+ そのプロジェクトを開く(使えない登録や個人設定の読めない理由があるときは一覧に出す)。選ぶと `/projects/<名前>/...` になり、
494
+ ほかの URL(要望・ボード・リリースノート・設定、`?task=` など)はこの下に今までどおり続く。URL を直接開く・再読み込み・戻るも効く
495
+ - **今のプロジェクト**: どの画面でも、ヘッダーのロゴの横(通常の serve でプロジェクト名を出す場所)の選ぶ欄に出る。ここで切り替える
496
+ (選ぶ欄を開くと一覧を読み直す。狭い画面でも隠さず、長い名前は欄の幅で切る)。
497
+ 「プロジェクトの一覧…」では、登録が1つでも一覧を出す(`/?list`)。一覧は、戻ったとき・そのタブに戻ったときにも読み直すので、
498
+ 途中で足した・外した登録が出る
499
+ 作成・保存・Preflight は、ここに出ているプロジェクトにだけ届く。タブごとに別のプロジェクトを開いてもよい
500
+ - **切り替え**: ページごと移る。保存していない入力があれば「このプロジェクトに残る / 入力を破棄して切り替える」を選ぶ(破棄した
501
+ 入力はどこにも送らない)。送っている保存は、結果が決まるまで待ってから移る(待っている間はヘッダーの下に出し、選ぶ欄は押せない)。実行中の Preflight・生成は元のプロジェクトで続き、
502
+ 戻れば状態を読み直す(取消は表示中のプロジェクトの実行にだけ届く)
503
+ - **登録が変わったとき**: 開いている間にデータのフォルダを変えた・外した(CLI の `p3 project rm` / `add`)プロジェクトの画面からは
504
+ 保存しない。「登録が変わりました」と出るので、一覧から選び直す(入力は残すが、新しい登録先へ自動では送らない)
505
+ - **開けないとき**: 登録に無い・データのフォルダが無い・同じデータの重複などは、一覧に名前と理由を出す(ほかは選べる)。
506
+ CLI で直して(`p3 project ls` / `add` / `rm`)、「一覧を読み直す」
507
+ - ChatGPT の接続とテーマはプロジェクトによらず共通(どのプロジェクトの設定画面からでも同じ)
508
+
384
509
  | URL | 画面 |
385
510
  | --- | --- |
386
511
  | `/` | 進捗。左に要望、右にスケジュール。`?show=` で 未完了(既定)/ `resolved`(確認待ち)/ `closed`(完了済・見送り)/ `all`。`?tags=` |
387
512
  | `/requests/new` | 新しい要望(添付も) |
388
513
  | `/requests/<要望>` | 要望の概要(タイトル・本文・期限・マイルストーン・タグ・添付)と Preflight(`?run=PF-...` で過去の評価) |
389
- | `/requests/<要望>/board` | タスクボード(V 字。ドラッグで列を移動。完了のカードの「✓ 済み」でボードから外す) |
514
+ | `/requests/<要望>/board` | タスクボード(V 字。ドラッグで列を移動。完了のカードの「✓ 済み」でボードから外す。「+ タスクを追加」で直接作る) |
390
515
  | `/requests/<要望>/done` | 対応済み(済みにしたタスクと成果物の一覧。要望の「対応済」とは別) |
391
516
  | `/release-notes` | リリースノート(`?m=<マイルストーン>`)。下の「リリースノートの画面」 |
392
517
  | `/settings` | 個人(ChatGPT の接続・テーマ)/ プロジェクトの基本 / 参照先(`?tab=personal|project|repos`) |
393
518
 
394
- 要望の中のページでは `?task=T003` でタスク詳細を重ねて開く。
519
+ 要望の中のページでは `?task=T003` でタスク詳細を重ねて開く。どのタブでも、見出しのタイトルの上に要望 ID と「コピー」が出る
520
+ (本文を下へ送っても見出しは残るので、上まで戻らずにコピーできる)。コピーできない(拒まれた・http で別のマシンから開いて
521
+ Clipboard API が無い)ときはそう出るので、ID をクリックして全体を選び、手でコピーする。
395
522
 
396
523
  進捗のスケジュールの記号:
397
524
 
@@ -485,8 +612,9 @@ updatedBy: ai:claude
485
612
 
486
613
  ### AI エージェントから使う
487
614
 
488
- AI にも CLI を使わせる(認証を持たせずに済む)。`p3 init --agents` で、`AGENTS.md`(無ければ `CLAUDE.md`)に短い使い方を追記し、
489
- 詳しい手順のスキルを置く。どちらにも上の「役割と言葉」の役割が書いてある。置いたファイルはリポジトリに入れて共有する。
615
+ AI にも CLI を使わせる(認証を持たせずに済む)。`p3 init --agents claude|codex|both`(値を省くと both)か、作った後なら
616
+ `p3 agents claude|codex|both` で、`AGENTS.md`(無ければ `CLAUDE.md`、どちらも無ければ `AGENTS.md` を作る)に短い使い方の節を足し、
617
+ 詳しい手順のスキルを選んだ先に置く。どちらにも上の「役割と言葉」の役割が書いてある。置いたファイルはリポジトリに入れて共有する。
490
618
 
491
619
  | 置く場所(リポジトリのルート) | 読む AI |
492
620
  | --- | --- |
@@ -497,11 +625,27 @@ AI にも CLI を使わせる(認証を持たせずに済む)。`p3 init --a
497
625
  置くのはプロジェクトの中だけにする。個人のスキルの場所(`~/.claude/skills`・`~/.agents/skills`)に置くと、p3 を使わない
498
626
  プロジェクトでも読まれ、関係ない作業で p3 を操作しかねない。
499
627
 
500
- **P3 を新しくしたとき**: 置いたスキルと追記は、手で直した分を消さないよう上書きしない。登録済みのリポジトリで
501
- `p3 init --agents --project <名前> --dir <データのフォルダ>`(ルートの `.p3` なら `--dir` は省ける)をもう一度実行すると、登録とデータはそのままで、スキルの場所ごとに
502
- 無ければ置き、「最新です」か「同梱の版と違う」かを出す。片方(以前の版で置いた `.claude/skills` だけなど)しか無ければ、
503
- 足りない方が置かれる。違うものは同梱の原本と見比べて手で直す(追記は見出しがあれば足さないので、最新の内容は
504
- [docs/architecture.md](architecture.md) の「AI エージェントへの指示」と見比べる)。
628
+ 節のスキルの参照は、選んだ先と、リポジトリに既にある先だけを書く(無い先は書かない)。
629
+
630
+ **後から置く・最新にする(`p3 agents`)**: 今いるリポジトリのルート(サブフォルダからでも)に、選んだ先だけを扱う。プロジェクトは
631
+ 決めず、データ・個人設定は変えない。選ばなかった先は作らず・変えず・消さない(チームで消した先は戻らない)。置く先は省けない。
632
+
633
+ | 今の状態 | `p3 agents <先>` | `p3 agents <先> --force` |
634
+ | --- | --- | --- |
635
+ | 無い | 作成(置く・節を足す) | 同じ |
636
+ | 同梱の版と同じ | 同一(何もしない) | 同じ |
637
+ | 違う(手で直した・古い版) | 保護(変えずに知らせる。スキルは違う行も出す) | 更新(スキルは同梱の版に、節は p3 の節だけを置き換え、前後の文は残す) |
638
+ | 節が複数・見出しになっていない | 保護(手で1つの節に整理するよう知らせる) | 同じ(変えない) |
639
+
640
+ - `--force` が上書きするのは、選んだ先のスキル(`SKILL.md`)と、`AGENTS.md` / `CLAUDE.md` の「タスク管理(infodb p3)」の節
641
+ (その見出しから、同じか上の段の次の見出しの前まで。見出しの段はそのまま)だけ。手で直した分は消えるので、先に差分を見る
642
+ - 後から片方を足したときは、スキルは置き、節(前の参照のまま)は「保護」になる。両方を指す節にするなら `--force`
643
+ - チームで使うとき: 置いた・最新にした変更(`git diff`)をレビューしてコミットし、push して共有する。ほかの人は pull するだけで
644
+ よい(参加の `p3 join` は AI 向けのファイルを書かない)
645
+ - 新しい版の P3 で手順が変わっても、置いたスキルと節は自動では変わらない(例: 完了をコミットの前にする順番)。`p3 agents <先>` で
646
+ 違いを確かめ、手で直していなければ `--force` で最新にする
647
+ - 以前の版との違い: 以前は `init --agents` で両方に置き、参加(init)のときも置き、登録済みのリポジトリで実行し直すと足りない方を
648
+ 置いていた。今は、置く先を選び、参加では置かず、後から置く・最新にするのは `p3 agents` だけ
505
649
 
506
650
  ブラウザ用の REST API(`/api/...`、自己記述は `GET /api/ai/manifest`)もあるが、ローカルの画面のためのもの。
507
651
 
@@ -511,7 +655,7 @@ AI にも CLI を使わせる(認証を持たせずに済む)。`p3 init --a
511
655
 
512
656
  | コマンド | 内容 |
513
657
  | --- | --- |
514
- | `p3 init` / `p3 project` / `p3 whoami` | 初期設定・参加 / 個人設定のプロジェクト / 今の判定 |
658
+ | `p3 init` / `p3 join` / `p3 project` / `p3 whoami` | 新しく作る / 共有されたものに参加する / 個人設定のプロジェクト / 今の判定 |
515
659
  | `p3 config` / `p3 repo` / `p3 user-config` | プロジェクトの設定 / 参照先 / 個人設定(テーマ・マシンごとの設定) |
516
660
  | `p3 progress` | 要望ごとの進捗(マイルストーンごと。`--all` で完了・見送りも) |
517
661
  | `p3 milestone ls\|add\|set\|rm` | マイルストーン |
@@ -521,4 +665,4 @@ AI にも CLI を使わせる(認証を持たせずに済む)。`p3 init --a
521
665
  | `p3 new` / `p3 set` / `p3 move` / `p3 check` / `p3 archive` | タスクを足す / 直す / 状態を変える / 済みにする / アーカイブ |
522
666
  | `p3 preflight` / `p3 notes` / `p3 drafts` / `p3 accept` | Preflight の実行(`--note`)/ メモ / 評価とタスク案 / タスク化 |
523
667
  | `p3 attach` / `p3 render` | 添付 / 画面イメージの描画 |
524
- | `p3 chatgpt` / `p3 codex update` / `p3 serve` | ChatGPT の接続 / Codex のイメージ / 画面 |
668
+ | `p3 chatgpt` / `p3 codex update` / `p3 serve` | ChatGPT の接続 / Codex のイメージ / 画面(`--all-projects` で登録したプロジェクトを跨ぐ) |