@infodb/p3 0.0.0-stage → 0.2.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 (120) hide show
  1. package/LICENSE +21 -0
  2. package/README.md +56 -2
  3. package/bin/p3.mjs +18 -0
  4. package/dist/web/apple-touch-icon.png +0 -0
  5. package/dist/web/assets/Outputs-Ni3pNuGU.js +1 -0
  6. package/dist/web/assets/RequestStatus-K8TZwpur.js +1 -0
  7. package/dist/web/assets/TagInput-BICKVH2x.js +1 -0
  8. package/dist/web/assets/TaskDrawer-BkDIstIN.js +3 -0
  9. package/dist/web/assets/_requestId-B5O_ytaq.js +1 -0
  10. package/dist/web/assets/_requestId-C66puEMO.js +30 -0
  11. package/dist/web/assets/action-CMjATXqv.js +1 -0
  12. package/dist/web/assets/board-CbfDjkls.js +1 -0
  13. package/dist/web/assets/copy-B1ZbihKL.js +2 -0
  14. package/dist/web/assets/done-CPQbCFHg.js +1 -0
  15. package/dist/web/assets/draft-dT3gLDIt.js +1 -0
  16. package/dist/web/assets/format-DuK6P1hb.js +1 -0
  17. package/dist/web/assets/index-BUcs2J6N.js +12 -0
  18. package/dist/web/assets/index-C3DkqwJ9.css +2 -0
  19. package/dist/web/assets/link-_s8ndNKS.js +1 -0
  20. package/dist/web/assets/new-T60RB7de.js +1 -0
  21. package/dist/web/assets/preload-helper-dXqN7N-I.js +1 -0
  22. package/dist/web/assets/release-notes-DxrPhDbt.js +3 -0
  23. package/dist/web/assets/requestData-D8ZiSZss.js +1 -0
  24. package/dist/web/assets/rolldown-runtime-hePW80VL.js +1 -0
  25. package/dist/web/assets/routes-D9ZxXoLk.js +2 -0
  26. package/dist/web/assets/search-CJ8MBKTz.js +1 -0
  27. package/dist/web/assets/settings-DsHVyqzJ.js +1 -0
  28. package/dist/web/assets/supersede-CLXlhCq0.js +1 -0
  29. package/dist/web/assets/ui-Cvke4y4X.js +1 -0
  30. package/dist/web/favicon.ico +0 -0
  31. package/dist/web/favicon.svg +12 -0
  32. package/dist/web/index.html +23 -0
  33. package/docs/architecture.md +591 -0
  34. package/docs/chatgpt-sign-in.md +163 -0
  35. package/docs/development.md +194 -0
  36. package/docs/how-to-use.md +524 -0
  37. package/docs/installation.md +284 -0
  38. package/docs/publishing.md +65 -0
  39. package/package.json +86 -3
  40. package/skills/p3/SKILL.md +95 -0
  41. package/src/cli/args.ts +179 -0
  42. package/src/cli/chatgpt.ts +74 -0
  43. package/src/cli/codex.ts +28 -0
  44. package/src/cli/format.ts +9 -0
  45. package/src/cli/help.ts +99 -0
  46. package/src/cli/main.ts +267 -0
  47. package/src/cli/output.ts +99 -0
  48. package/src/cli/preflightCommands.ts +237 -0
  49. package/src/cli/project.ts +508 -0
  50. package/src/cli/readOnly.ts +36 -0
  51. package/src/cli/releaseNotesCommands.ts +139 -0
  52. package/src/cli/render.ts +60 -0
  53. package/src/cli/requestCommands.ts +170 -0
  54. package/src/cli/showView.ts +110 -0
  55. package/src/cli/taskCommands.ts +167 -0
  56. package/src/cli/userConfig.ts +58 -0
  57. package/src/core/chatgpt.ts +33 -0
  58. package/src/core/context.ts +57 -0
  59. package/src/core/machineSettings.ts +207 -0
  60. package/src/core/machineSettingsEdit.ts +156 -0
  61. package/src/core/ops.ts +114 -0
  62. package/src/core/preflight/carryover.ts +133 -0
  63. package/src/core/preflight/codexEngine.ts +702 -0
  64. package/src/core/preflight/codexImage.ts +98 -0
  65. package/src/core/preflight/diagnose.ts +124 -0
  66. package/src/core/preflight/engine.ts +92 -0
  67. package/src/core/preflight/input.ts +65 -0
  68. package/src/core/preflight/launch.ts +86 -0
  69. package/src/core/preflight/launcher.mjs +75 -0
  70. package/src/core/preflight/mock-ui.html +24 -0
  71. package/src/core/preflight/mock-ui.png +0 -0
  72. package/src/core/preflight/mockEngine.ts +145 -0
  73. package/src/core/preflight/render-image/Dockerfile +23 -0
  74. package/src/core/preflight/render-image/render.mjs +53 -0
  75. package/src/core/preflight/render.ts +336 -0
  76. package/src/core/preflight/service.ts +690 -0
  77. package/src/core/preflight/uiMaterials.ts +272 -0
  78. package/src/core/preflight/uiRender.ts +84 -0
  79. package/src/core/preflight/wireframe.ts +69 -0
  80. package/src/core/preflight/xlsx.ts +328 -0
  81. package/src/core/redact.ts +31 -0
  82. package/src/core/releaseNotes/generate.ts +271 -0
  83. package/src/core/releaseNotes/material.ts +114 -0
  84. package/src/core/releaseNotes/mockSummarizer.ts +28 -0
  85. package/src/core/releaseNotes/service.ts +106 -0
  86. package/src/core/releaseNotes/store.ts +216 -0
  87. package/src/core/repoAdmin.ts +81 -0
  88. package/src/core/repoRefs.ts +90 -0
  89. package/src/core/requestOps.ts +140 -0
  90. package/src/core/requestStatus.ts +58 -0
  91. package/src/core/store/attachments.ts +228 -0
  92. package/src/core/store/collection.ts +282 -0
  93. package/src/core/store/frontmatter.ts +22 -0
  94. package/src/core/store/fsutil.ts +90 -0
  95. package/src/core/store/locate.ts +181 -0
  96. package/src/core/store/normalize.ts +155 -0
  97. package/src/core/store/noteStore.ts +56 -0
  98. package/src/core/store/preflightStore.ts +136 -0
  99. package/src/core/store/projectFile.ts +101 -0
  100. package/src/core/store/workspace.ts +328 -0
  101. package/src/core/supersede.ts +74 -0
  102. package/src/core/userConfig.ts +180 -0
  103. package/src/core/userTheme.ts +22 -0
  104. package/src/core/workTargets.ts +120 -0
  105. package/src/server/api/chatgptRoutes.ts +48 -0
  106. package/src/server/api/local.ts +33 -0
  107. package/src/server/api/manifest.ts +119 -0
  108. package/src/server/api/releaseNoteRoutes.ts +78 -0
  109. package/src/server/api/repoRoutes.ts +67 -0
  110. package/src/server/api/routes.ts +374 -0
  111. package/src/server/api/userThemeRoutes.ts +62 -0
  112. package/src/server/server.ts +49 -0
  113. package/src/shared/dates.ts +12 -0
  114. package/src/shared/preflightInput.ts +27 -0
  115. package/src/shared/refs.ts +55 -0
  116. package/src/shared/repos.ts +113 -0
  117. package/src/shared/scopeView.ts +48 -0
  118. package/src/shared/tags.ts +27 -0
  119. package/src/shared/types.ts +700 -0
  120. package/src/shared/workTarget.ts +44 -0
@@ -0,0 +1,591 @@
1
+ # 構成の方針: ローカルで完結させる
2
+
3
+ > この文書は **設計と規則**(なぜそうするか・どこで守っているか)を書く。コマンド・画面の操作・設定の項目など **使い方** は
4
+ > [導入ガイド](installation.md) と [使い方ガイド](how-to-use.md) に書き、ここでは繰り返さない(文書の分担は [開発ガイド](development.md#文書を直すとき))。確認作業の記録(どの幅・どのブラウザで確かめたか)は書かず、PR と
5
+ > タスクの成果物に残す。
6
+
7
+ p3 は **ファイルが唯一の正(source of truth)で、すべてローカルで完結する** ことを前提にする。
8
+ サーバ(S3 / API Gateway / Cognito など)にデータを置く案も検討したが、採らない。以下はその判断と、
9
+ 残っている課題の整理。
10
+
11
+ ## 作業の単位は要望
12
+
13
+ Preflight で扱う要望が、プロジェクトで行う作業の粒度になる。そこで **要望ごとにフォルダを作り**、
14
+ そこから生まれたタスクや評価の記録はすべてその下に置く。要望 = フォルダ。ブランチ(作業ツリー)は作業先のリポジトリごとに1つ。
15
+
16
+ ```
17
+ <データのフォルダ>/requests/<作成日-乱数>/request.md
18
+ tasks/T001.md ...
19
+ preflight/<run>/...
20
+ ```
21
+
22
+ - **要望の ID は作成日 + 乱数5文字**(例: `261009-k7m3x`)。時刻順に並び、人が読み書きでき、
23
+ 複数人が別々に作っても実用上衝突しない。タイトルは後から変わるので含めない(ULID は人が扱うには長い)
24
+ - **一覧の並び**は日時だけで決めず、同じ日時のときの第2キー(ID)を必ず持つ([使い方ガイド](how-to-use.md#データの持ち方) の「一覧の並び」)。
25
+ 乱数を含む ID の順は作った順ではないので、「作った順」が要るところは日時で比べる。
26
+ - **タスクは要望をまたいで移動しない** ので、要望の中の素直な連番(T001, T002, ...)で採番できる。
27
+ `tasks/.archive/` にある ID も使用済みとして扱い、再利用しない(アーカイブしたタスクへの関係が新しいタスクを指さないように)。
28
+ 守れるのはアーカイブのファイルが残っている範囲まで。消したアーカイブの ID や、既に再利用された ID は直さない。
29
+ 同じ要望を複数人が同時に触ることは少なく、触る場合の排他は人が行う
30
+ - 要望をまたぐ関係(影響・依存)は `<要望ID>/T003` の絶対参照で書き、インテリジェンス層が要望を横断して辿る
31
+ - タスクボード(V 字: 未着手 → 作業中 → 完了。済みにすると消え、対応済みの一覧へ)は要望の中で見る。進捗は要望ごとの状況を横断して見る
32
+ - 日程は要望の単位で持つ(期限)。リリースは複数の要望をまとめることがあるので、マイルストーンで束ねる
33
+ - タスクは予定の日付・見積り・進捗%を持たない。AI が実施する作業の量や期間は人の感覚では見積もれず、
34
+ AI に自己申告させても正確にはならないため。代わりに、ステータスを変えた日時(作業中にした=着手を指示した目安、
35
+ 完了にした)を p3 が記録する
36
+ - タスクは AI か人が実施する。人から見て要るのは「まだ動いていない / AI が処理中 / 処理が終わった」だけなので、
37
+ 状態は 未着手 / 作業中 / 完了 で固定する(保留・取りやめは持たない)。終わったもの(PR・MR・ドキュメント)のレビューは成果物の側で行い、タスクとしては完了にする
38
+ - 担当者(メンバー)は持たない。誰が変えたか(`ai:claude` / `human:<git の user.name>`)だけを記録する
39
+ - AI が作業中に見つけた追加の作業は、AI がそのままタスクとして足す。人への質問(Human in the Loop)は
40
+ タスクにせず、Claude Code などのチャットで行う
41
+
42
+ ## プロジェクトの置き場所と個人設定
43
+
44
+ 管理したいシステムは、本体・ドキュメント・基盤のように **複数のリポジトリに分かれている** ことが多い。
45
+ プロジェクトのデータは **データのフォルダ** に置き、操作するプロジェクトはその場所ではなく個人設定の登録で決める。
46
+ `p3 init` の既定は本体のリポジトリのルート(git のメインの作業ツリー)の `.p3/` で、ふつうのプロジェクトはそれでよい。
47
+ 公開できない要望を含むときや、横断するリポジトリのどれとも別に管理したいときは、`--dir` でリポジトリの外
48
+ (例: `~/p3-data/myapp`、チームで同期するフォルダ)に置く。どちらでも同じに動く(既定は `init` の入口だけが持つ)。
49
+
50
+ | 何を | どこに | 共有 |
51
+ | --- | --- | --- |
52
+ | プロジェクトのデータ(要望・タスク・Preflight の記録、`project.yaml`) | データのフォルダ | する(方法は下の「共有」) |
53
+ | 個人設定(参加しているプロジェクトとフォルダの場所、手元のリポジトリの場所、画面の設定、マシンごとの設定(Codex の認証の選び方・パスの対応・serve の待ち受けなど)) | `~/.config/infodb-p3/config.yaml` | しない |
54
+ | ChatGPT の接続(トークン) | `~/.config/infodb-p3/chatgpt.json`(所有者だけが読める) | しない |
55
+ | コード・ドキュメント | 各リポジトリ | 今までどおり |
56
+
57
+ ### 個人設定とプロジェクトの決め方
58
+
59
+ - 手元のリポジトリの場所はマシンごとに違うので、プロジェクトのデータではなく個人設定に持たせる
60
+ - **操作するプロジェクトは環境変数では決めない**(同じ人が複数のプロジェクトを行き来するため)。
61
+ `--project <名前>` → 今いる場所(登録したリポジトリ・作業ツリー・データのフォルダの中)→ 登録が1つならそれ、の順で決め、
62
+ 決まらなければ登録済みの一覧と選び方を出す(`src/core/store/locate.ts`)
63
+ - プロジェクトを開く共通の入口(`core/context.ts` の `openProject`。CLI も `serve` の `startServer` もここを通る)で、
64
+ データのフォルダと `project.yaml` があるかを確かめる(`locate.ts` の `checkDataDir`)。無ければ空のプロジェクトとして続けず
65
+ `DataDirError`(終了コード 1)。何も作らない。無い(ENOENT)と読めない(権限・入出力)は分けて伝える。`init`(作成・参加)と
66
+ `project` は開かないので妨げない。起動した後の切断は、画面の「再読み込み」の `ReloadError`(状態は変えない)が受け持つ
67
+ - 登録が1つだけで決まった(`via: only`)ときは、今いる場所と関係なく当たるので読むだけにする。CLI の入口(`cli/main.ts`)で、
68
+ プロジェクトを開く前に、読むだけの操作(`cli/readOnly.ts` の `readsOnly`。載っていない操作は変える操作として扱う)以外を止める。
69
+ 案内の文は `locate.ts` の `onlyRegistrationNotice`(明示の方法と移る先を示す)
70
+ - 使う人はフォルダや実行パスを意識しない前提で、セットアップは2段階まで・エラーは次にすることを示す、を守る
71
+ - 個人設定に登録していないリポジトリの中の `.p3/` も、今いる場所から上へ辿って読める(`via: legacy`。デモ・テスト・登録前の clone)。
72
+ 登録していれば今いる場所(`cwd`)で決まる
73
+ - 個人設定の書き換えは、ロック(`config.yaml.lock`)の中で最新のファイルを読み、対象の項目(プロジェクト1つの登録・
74
+ `ui.theme`)だけを変えて書く(`updateUserConfig`)。init・project add / rm・テーマの保存が同じ経路を通るので、
75
+ CLI と serve が同時に書いても消し合わない。壊れた YAML・読めないファイルは書かずにエラーにする(無いのとは区別する)。
76
+ ChatGPT の接続(`chatgpt.json`)は別のファイル・別のロックのまま
77
+ - 1人1つのサーバで画面からプロジェクトを切り替える形(決定済み)は、次の段階で入れる
78
+
79
+ ### 要望・タスクのデータ
80
+
81
+ - タグ(要望の `tags`)は外部 ID・分類のための自由な文字列。仕様(用途・対象外・入力の決まり・絞り込み・URL)は
82
+ [使い方ガイド](how-to-use.md#タグ期限マイルストーン) の「タグ・期限・マイルストーン」にまとめた。保存の形(文字列の配列)は変えない。
83
+ - 入力(`components/TagInput.tsx`、`shared/tags.ts`): 値ごとに足す・外す。要望の管理情報では足す・外すたびに編集を始めた
84
+ ときの rev で保存し(保存中は次の操作を待たせる)、下書き(`web/lib/draft.ts`)で持つので取り直しても入力中の値は残る。
85
+ 入力欄のまだ足していない文字は、新しい要望では作成のときに足す
86
+ - 進捗の絞り込み(`components/TagFilter.tsx`、`web/lib/requestFilter.ts`): ヘッダーにはボタンだけを置き、開いた中
87
+ (画面に固定。ボタンの下で画面の幅に収める)に検索・選択中(高さを決めてスクロール)・候補(同じ。一度に 200 件まで)を
88
+ 出す。URL は `tags`(ルーターが JSON の配列で書く)。以前の `tag` は読むだけで、選び直すと外す
89
+ - タスクの成果物(`outputs: string[]`)は URL・文章・パスを1項目ずつ混ぜてよい。画面は `components/Outputs.tsx` で、
90
+ 項目全体が絶対の http(s) URL(`web/lib/outputs.ts` の `outputHref`。前後の空白は判定でだけ除く)ならリンク、ほかは文字。
91
+ 保存の形を変えないので、既存のデータの移し替えはしない
92
+ - 全件の読み直し(`Workspace.reloadAll`、`POST /api/reload`): project.yaml・要望・全タスクをディスクから読み、読み終えて
93
+ から同期でまとめて入れ替える(`MarkdownCollection.prepareLoad` → `commit`。読んでいる途中の空や半分の状態は見せず、
94
+ 要望だけ新しくタスクは古い、ということもない)。読み込みの間に作成・更新・アーカイブ・1件の読み直し(監視)があった ID は、
95
+ 読んだ結果ではなくその時点の状態を残す(タスク化や画面からの保存を、先に読んだ古い内容で戻さない)。タスクのコレクションは
96
+ 作り直さない(処理中の操作が持っている参照に書いた結果も残る)。同時には走らせず、読み込み中の呼び出しは終わってから
97
+ もう1回にまとめる。project.yaml とデータのフォルダが読めなければ ReloadError(503)で何も変えない。終えたら変更通知
98
+ `changed`/`reload` を出す。Preflight の履歴・メモ・リリースノートは問い合わせのたびに
99
+ ディスクを読むので扱わない。応答は読み直しを終えた後(画面はその後に取り直す)。ほかの serve・CLI が同時に書いている
100
+ 最中のファイルは、読んだ時点の内容になる(次の読み直しで追いつく)
101
+
102
+ ### リリースノートのデータ
103
+
104
+ マイルストーンごとに1件、`<data>/release-notes/<マイルストーンID>.md` に置く(`core/releaseNotes/`)。要望のフォルダの外に
105
+ 置くのは、複数の要望をまとめるものだから。
106
+
107
+ - **材料**(`releaseNotes/material.ts`): マイルストーンに属する要望(アーカイブしたものは除く)を全部返し、収録するかを決める。
108
+ 収録するのは、要望が対応済か完了済で、タスクが1件以上あり、全部が完了で、読めないタスクが無いもの(完了済でもタスクの
109
+ 実態を確かめる)。見送りは理由だけ、ほかの状態は未完了として警告する。要約の材料は、収録する要望の **変更の記録のある
110
+ 完了したタスク** だけで、記録の無いものは警告し、要望やタスクの本文・タイトルで補わない。読めない要望は所属が分からないので
111
+ 全体の警告に残す。並びは要望が作成日時の古い順 → ID、タスクが ID(ID は数字の部分を数として比べる。`8nda1` が `88d8b` より先、`T2` が `T10` より先。`material.ts` の `byId`)。並びは `hash` にも入るので、変えると材料が変わったことになる。抽出のたびにディスクから読み直した別の `Workspace` を使い、
112
+ その時点を固定する。`hash` は所属・状態・タイトル・収録の可否と材料(記録まで)から作り、生成や保存のあとの変更を見つける
113
+ - **ファイル**: frontmatter に `milestone`・`title`・作成と更新の日時と変更者・`materialHash`・`sources`(保存したときの材料:
114
+ 要望とタスクの ID・タイトル・状態・変更の記録)、本文に公開する Markdown を書く。出力(`p3 release-notes export` など)は
115
+ 本文だけで、frontmatter と出典は出さない
116
+ - **保存**(`releaseNotes/store.ts`): 明示的に保存したときだけ書く。要望・タスクが後で変わっても、保存した本文と出典は
117
+ 変えない(詳細で `materialChanged` として知らせる)。新規は排他作成で、既にあれば(読めないファイルでも)上書きしない。
118
+ 更新は読んだときの **版**(ファイル全体の sha256)が必須で、プロセス間のロック(`release-notes/.<ID>.lock`)の中で
119
+ ディスクの今のファイルと照らし、違えば競合で何も書かない。rev のような番号ではなく中身で照らすので、番号を増やさない
120
+ 直接編集も見つかる。マイルストーンの ID は project.yaml と同じ形(英数字と `. _ -`、`.` と `..` は不可)で、保存先の外を
121
+ 指すものは断る。キャッシュを持たず問い合わせのたびに読むので、再読み込みは要らない。監視は `changed`/`release-note` を出す
122
+ - **マイルストーンとの関係**: ノート(読めないファイルも含む)のあるマイルストーンは消せない(`requestOps.ts` の
123
+ `checkMilestoneRemoval`。CLI の `milestone rm` と画面の設定の保存で同じ)。保存は要望・マイルストーンの状態を変えない
124
+ - **直接編集の限界と直し方**: ロックを使わない外部のエディタとの完全な排他は保証しない(保存の直前に照らすので、
125
+ 照らした後・書く前の一瞬の書き込みは失われうる)。frontmatter を壊す・`milestone` をファイル名と違えると「読めない」と
126
+ 示し、空のノートとして扱わない(直すまで新規保存もしない)。直すときは frontmatter を戻すか、本文を退避してファイルを
127
+ 消してから保存し直す。project.yaml を直接編集してマイルストーンが消えても、ノートは一覧・閲覧・出力でき、孤立を警告する
128
+ (マイルストーンを足し直すか、不要ならファイルを消す)
129
+
130
+ ### 参照先と作業先
131
+
132
+ - Preflight の参照先(`shared/repos.ts`・`core/repoRefs.ts`): 共有の定義は project.yaml の `repos`(名前をキーにした対応。
133
+ 名前・役割・readFirst・writable・主なフォルダ map。入口 entry がそのフォルダで最初に読むファイル)、このマシンのパスは個人設定の `projects.<p>.repos`。
134
+ `Workspace.refs()` が始めるたびに合わせ、`ok / unregistered / missing / notdir` を決める。`p3 init` が本体を参照先として
135
+ 登録する。`p3 repo` は project.yaml の `repos` の1件だけを書き(`writeRepoEntry`。コメント・知らない項目は残す)、
136
+ 設定の保存(画面・`p3 config`)は `repos` を書き換えない。コンテナの中の名前(mount)は論理名から英数字と `. _ -` だけで作り、
137
+ 重複は番号で分ける。参照の書き方 `<名前>:<パス>`(`parseRepoPath`)は areas・evidence で共通。名前なしは先頭の参照先。
138
+ - マウント(`withMounts`): dockerCommand の `/workspace` の bind を tmpfs に替え、参照先を `/workspace/<mount>` に
139
+ `readonly` で、データを `/data` に置く。Codex の cwd は `/workspace` のまま。変更のパスは参照先の対応で戻す
140
+ - 調べた範囲(`run.scope`)は P3 が始めるときに決めて残す(パスは入れない)。根拠(`assessment.evidence`)は Codex が書き、
141
+ P3 が `parseEvidence` で確かめる(verified は読めた参照先の中の、ある相対パスを指すときだけ)
142
+ - タスクの作業先とリポジトリごとのブランチ(`shared/workTarget.ts`・`core/workTargets.ts`): タスクとタスク案の `repo`
143
+ (名前 / null = 作業先なし。書かずに足すと、作業先にできる参照先が1つならそれ)、要望の `workstreams`(名前 → branch。
144
+ 作業ツリーの置き場所は記録しない)、タスクの `repoOutputs`。作業先は writable の参照先だけで、API・CLI・タスク化の
145
+ 前に `checkRepoTarget` で確かめ、変える前に断る。割当は `planWorkstreams`(既存は残す・git でないフォルダはブランチなし・
146
+ 同じ git の実体を指す2つの名前は断る。git の実体は `--git-common-dir` で見る)で決め、タスク化では計画を run の
147
+ materialization に残してやり直しでも同じにする。今の要望(`cli/project.ts` の `currentRequest`)は、今いる参照先
148
+ (`locateHere`)の割当のブランチ → ブランチ名の要望 ID の順で、パスの中の要望 ID だけでは決めない(detached HEAD では決めない)。
149
+ git のブランチ・作業ツリーは作らない
150
+ - 参照先の登録・変更・削除は `core/repoAdmin.ts` に集め、CLI(`p3 repo`)と設定画面(`/api/repos`・`components/ReposPanel.tsx`)が
151
+ 同じものを使う。このマシンのパスは `localOnly` でローカルの画面にだけ返し、変えられるのもローカルの画面(Origin)からだけ。
152
+ パスつきで足すときは、共有の定義を書く前にフォルダかを確かめる
153
+ - 設定画面はほかの画面と同じく画面の横幅いっぱいに使う。入力欄のラベルは短くし、補足は `Field` の `hint` で入力欄の下に出すので、
154
+ ラベルの折り返しで横に並んだ入力欄の高さがずれない
155
+ - 主なフォルダの行は、広い画面ではフォルダ・役割・入口を3等分し(見出しの行を上に置く)、狭い画面では縦に並べる。構成の説明
156
+ (`mapFile`)の欄は無い(以前の `mapFile` とプロジェクトの `docs` が残った project.yaml で参照先を保存すると、どちらも消える)
157
+ - 設定画面はタブで「個人」(ChatGPT の接続・テーマ)・「プロジェクトの基本」(project.yaml)・「参照先」(共有の定義と
158
+ このマシンのパス)に分ける。選んだタブは `?tab=personal|project|repos`(既定は個人)に持ち、読み直しても同じタブを開く。
159
+ ほかの画面から設定へのリンク(説明が無いときの案内・マイルストーンを作る)は `tab=project`。選んでいないタブは消さずに
160
+ `hidden` で隠すので、タブを移っても書きかけの入力は残り、保存していない変更があるタブには印(●・読み上げは「未保存」)を
161
+ 付ける(参照先は各参照先の編集・このマシンのパス・「足す」の欄の入力を `onDirtyChange` で集める)。保存のバーは
162
+ プロジェクトの基本のタブだけに出す。タブは矢印キー・Home・End で移る
163
+
164
+ ### マシンごとの設定と Codex の起動
165
+
166
+ - マシンごとの設定は、項目ごとに CLI の明示 → 環境変数(`P3_*`)→ 個人設定 → 既定値 で決める(`src/core/machineSettings.ts`)。
167
+ CLI と serve・Codex エンジンが同じ解決を使い、`process.env` を個人設定の値で書き換えない。`.env` はどこからも読まない
168
+ (P3 は pnpx などで入れるので、パッケージの場所は利用者が触らない)。項目と環境変数の対照は [導入ガイド](installation.md#設定の決まり) の「設定の決まり」
169
+ - マシンごとの設定の書き換え(`p3 user-config set`。`src/core/machineSettingsEdit.ts`): `キー=値` で書き、`キー=` で消し、
170
+ パスの対応は `codex.pathMap+=A=B` / `codex.pathMap-=A` で1件ずつ足し・外す(全部の置き換えは受けない。書き間違いで全部を
171
+ 失わないように)。`updateUserConfig` の中で変更を当ててから、環境変数を見ずに `resolveMachineSettings` で確かめ、読めなければ
172
+ 何も書かない(テーマを含めて一括)。表示(`describeSettings`)は項目ごとの効いている値と出どころ(環境変数 / 個人設定 / 既定)。
173
+ 空の環境変数は既定に戻すので出どころも既定。プロジェクトの登録(projects)は表示しない(`p3 project ls`)
174
+ - パスの対応のエラー(`bind source path does not exist`)には、直し方(`pathMapHowTo`)として設定するコマンド・例・ホストの
175
+ パスの調べ方を添える。共有の記録に残るので、このマシンのパスは例のパスで示す。対応が当たっていたなら行き先の誤りとして案内する
176
+ - 旧来の認証の auth.json は、P3 のイメージの中の Codex(`CODEX_HOME=/codex`)で `codex login --device-auth` すれば、ボリュームの
177
+ 一番上にでき、そのまま `authVolume`(`volume-subpath=auth.json`)で使える(サインインそのものは人が行う)。`authFile` は Docker のホストのパスで
178
+ 渡すので `codex.pathMap` は効かない
179
+ - serve の Codex と Preflight の設定は `SettingsSource`(`machineSettingsSource`)から、Preflight を始めるたび・エンジンの状態を
180
+ 見るたびに読み直す(`loadUserSettings` で厳密に読み、形が違えば空にせずエラー)。Codex エンジンは `snapshot()` で始めるときの
181
+ 設定に決めたエンジンを作り、その run の間はそれを使う。既定のエンジンも始めるたびに決める。読めなければ、その run を
182
+ 設定のエラーで失敗にする(`PreflightService` の failing エンジン。Docker は起こさない)。エンジンの状態のため込み(1分)は、
183
+ ChatGPT の接続のファイルと設定の中身が変われば確かめ直す。待ち受けとプロジェクトは起動のときに決めたまま。CLI の1回の
184
+ 操作は起動のときに一度だけ読む。テストは MachineSettings をそのまま渡して決まった設定にする
185
+ - app-server の診断(`preflight/launcher.mjs`・`launch.ts`・`diagnose.ts`): codex-workspace は子の stderr を捨てるので、
186
+ docker run の前に中継を挟む(`node launcher.mjs <一時フォルダ> -- docker run ...`)。中継は stdin / stdout をそのまま通し、
187
+ stderr(先頭 8KB と末尾 56KB。間は省略を明示)と `{code, signal}` か `{spawnError}` を一時フォルダ(所有者だけが読める)に
188
+ 書く。初期化で失敗したら(stopIfRunning で応答しない中継を止めてから)、途中で「app-server が終わりました」となったら、
189
+ その内容で診断する。中止(signal.aborted)とほかの失敗には付けない。うまくいったときは stdin を閉じて中継から子へ伝わる。
190
+ 最後に中継が残っていれば止め、一時フォルダを消す。伏せるのは今までどおり Codex エンジンの log とエラーの包みで行う
191
+ (チャンクをまたいだ値も、まとめてから伏せる)
192
+ - Preflight の記録(run.json のログ・エラー)は共有するので、このマシンのパス・Docker のホストのパス・個人設定のファイルの
193
+ 場所を入れない(`diagnose.ts` の `describeMapping` は名前とコンテナの中のパスだけ、`hidePaths` で Docker の出力の中のパスを
194
+ 参照先の名前に置き換える。個人設定のエラーは `hideConfigPath` で「個人設定(config.yaml)」にする。想定外の変更は
195
+ `<参照先>:<パス>`)。画面のエンジンの状態(共有しない)には個人設定の場所を出してよい
196
+
197
+ ### 画面
198
+
199
+ - 画面のテーマ(`ui.theme`)の反映: index.html の先頭(CSS より前)で `/api/user-theme.js` を同期で読み、
200
+ html 要素に `data-theme`・class `dark`・`color-scheme` を付ける(Tailwind の `dark:` は class `dark` を見る
201
+ `@custom-variant`。OS のメディアクエリでは切り替えない)。応答はテーマだけを埋め込み `no-store`。その後は画面の
202
+ `web/lib/theme.ts` が持ち、`system` の間だけ `prefers-color-scheme` の変化を購読する。保存先は個人設定だけで、
203
+ localStorage は使わない。ほかのプロセスでの変更は読み直しで反映する
204
+ - 設定画面のテーマの選択は、選んだらすぐ `PUT /api/user-theme` で保存し、保存できてから画面に反映する
205
+ (`web/lib/themeSave.ts`。保存中に続けて選んだら、終わってから最後の選択だけを保存する。失敗したら保存済みの表示に戻す)。
206
+ - 進捗のスケジュールの狭い画面: 左の一覧の幅を枠の幅から決める(`web/lib/timeline.ts` の `leftWidth`。640px 未満で
207
+ 枠の 36%・112〜380px、640px 以上は 380px)。スケジュールの見える幅(`scheduleSpan`)・描く期間の右端・見える範囲の判定・
208
+ 今日への移動・ズームの中央の日付は、すべてこの幅から計算する(測る前は幅 0 で、見える幅は負にならない)。行の高さと
209
+ 縦の仮想スクロールは変えない。
210
+ - 画面の取り直し(`web/lib/appData.tsx`): `reload` は API から取り直すだけ(変更通知・保存の後)、`refresh` はサーバに
211
+ 全件を読み直させてから取り直す(`web/lib/refresh.ts`。ヘッダーの「再読み込み」と、タブが見えた・ウィンドウにフォーカスが
212
+ 戻ったとき。離れてから戻ったときだけで、両方続けて起きても1回)。実行中に頼まれたら終わってからもう1回だけ。取得は
213
+ `web/lib/latest.ts` で最後に始めたものの応答だけを使う(読み直しより前に始めた取得の遅い応答で上書きしない)。自分の
214
+ 再読み込み中に届いた `reload` の通知では取り直さない。どの通知でも全件の読み直しは呼ばない
215
+ - 入力の保持(`web/lib/draft.ts`): 要望のタイトル・タグとタスク詳細は下書き(値・編集を始めたときの値と rev・外の最新)で
216
+ 持つ。編集していなければ追従し、編集中は上書きせず知らせる。保存は編集を始めたときの rev。古い rev の応答は無視する。
217
+ 済み・関係の操作のように入力欄以外を自分で変えたときは、入力欄の項目が変わっていなければ自分の上げた rev に合わせる。
218
+ 要望の取り直し(`web/lib/requestLoad.ts`): 404 は表示中なら gone(前の内容と入力を残して保存を止める)、初めからなら
219
+ 「見つかりません」。ほかの失敗は前の内容のまま知らせる。要望を移ると作り直す(`RequestDataProvider` の key)
220
+ - 要望の画面の見出し(`routes/requests/$requestId.tsx` の RequestFrame)はタイトルとタスクの完了数だけ。ステータス・ID・
221
+ ブランチの印は外した(ステータスは概要・Preflight の管理情報で選ぶ。ブランチはデータに残り、CLI で見る)。要望 ID は
222
+ 概要・Preflight の管理情報(RequestMeta)のタイトルの上にだけ出す(`components/RequestIdCopy.tsx`)。コピーは
223
+ `web/lib/copy.ts` の `copyText`(ボタンは枠つきでコピーのアイコンと文字。成功したらアイコンをチェックにする): Clipboard API が無ければ unavailable、拒まれたら denied(例外は外へ出さない)、書き込みが
224
+ 終わってから copied。知らせは role="status" で、どの ID の結果かを持ち、別の要望の結果は出さない。ボタンは mousedown で
225
+ フォーカスを奪わないので、入力中のタイトルを保存させない。ID は select-all で、コピーできないときは手で選ぶ
226
+ - 進捗の画面の絞り込み(`web/lib/requestFilter.ts`): 未完了(既定)は下書き・Preflight・レビュー済・進行中で、対応済は
227
+ 含めない(リリース前のものは対応済のまましばらく残るため)。確認待ちは対応済だけ、完了・見送りは完了済・見送りだけ、
228
+ すべては7つとも。左の一覧とスケジュールは同じ行(`filterRequests`)から描く。CLI の `progress` は今までどおり既定でも
229
+ 対応済を出す(完了済・見送りだけを隠す)。`CLOSED_STATUSES`(人が閉じたもの)に対応済は入れない
230
+ - 要望の画面(概要・Preflight)の幅: 内容はブラウザの幅をそのまま使う(上限なし。以前は 1024px)。左右の余白は
231
+ 画面の幅で縮める(16 / 24 / 32px)。並びは変えない(評価 → メモ → タスク案)。文脈とログは 1024px 以上で
232
+ 左右、妥当性と実現可能性・リスクと確認事項は 640px 以上で左右。長い語(パス・参照・ログ・本文)は折り返し、ページ全体を
233
+ 横にスクロールさせない(タスク案の段の列とログだけが中でスクロールする)。
234
+ - タスク案の題(`web/lib/draftTitle.ts`、カードの `TitleField`): 案には rev が無いので、題の値で比べる下書きにする(基準の題・
235
+ 入力・外の最新・保存中の値)。下書きは 要望 / run / 案のキー の組で持ち、別の run の入力や遅い応答を混ぜない(run を替えたら
236
+ 持ち越さない)。保存は編集を始めたときの題を `expectedTitle` に添え、`PreflightService.updateDraft` が案のファイルを読み直して
237
+ 今の題と比べ、違えば `DraftConflictError`(409 `rev_conflict`、`current` に今の案)で書かない。期待値はファイルに書かない。
238
+ 画面から題を変えるときは必ず渡し、CLI・内部の呼び出しは渡さない(確かめない)。読み直してから書くまでの間に外のプロセスが
239
+ 書くことまでは防げない。保存の応答は、表示中の run が同じときだけ、その案だけを入れる(そのあいだに取り直したほかの案・項目を
240
+ 巻き戻さない)。未保存・保存中・競合中の題があればタスク化を止める
241
+ - タスク案の詳細(`components/request/DraftDetail.tsx`): カードの「内容を見る」で開くネイティブの dialog(最大 960px、
242
+ 狭い画面では画面の中に収め、見出しと「閉じる」を残して本文だけ縦にスクロール)。読むだけで、採否・題・作業先は一覧で直す。
243
+ 開いている案は run と案のキーの組で持ち(`lib/markdown.ts` の `selectedDraft`)、run が切り替わる・案が無くなると閉じ、
244
+ 外で更新されたら最新を見せる。閉じたら開いたボタンへフォーカスを戻す
245
+ - 画面で Markdown を読むのは、今はタスク案の本文だけ(`components/Markdown.tsx`。react-markdown + remark-gfm)。安全のため、
246
+ 生の HTML は要素にせず文字で見せ(HTML を差し込むプラグインは使わない)、リンクは絶対の http(s) URL だけ(成果物と同じ判定。
247
+ 別のタブ・`noopener noreferrer`。ほかは文字)、画像は取りに行かず代替テキストを出す。チェックリストは読むだけ。
248
+ 要望の本文・タスクの詳細などほかの欄には広げていない
249
+
250
+ ## 役割
251
+
252
+ ```
253
+ ┌──────────── 各メンバーのマシン ────────────┐
254
+ 人 ──┐ │ │
255
+ ├─▶ p3 CLI ─────┐ │
256
+ AI ──┘ ├─▶ <データのフォルダ>/*.md ◀── 読み直し ── p3 serve ──▶ ブラウザ(ビューア)
257
+ 人 ─────▶ ブラウザ ───┘ ▲ │
258
+ │ ファイル契約 │
259
+ Codex(自分のアカウント, コンテナ内で /workspace = repo, /data = データのフォルダ)
260
+ └────────────────────────────────────────────┘
261
+ │ 共有は同期だけ(git)
262
+ ▼
263
+ GitHub などのリモート
264
+ ```
265
+
266
+ | 部品 | 位置付け |
267
+ | --- | --- |
268
+ | データのフォルダ(Markdown / YAML / JSON) | 正。タスク・要望・Preflight の記録。人も AI も直接読める |
269
+ | CLI(`p3`) | 主な操作口。人も AI も使う。ファイルを直接読み書きするので **認証が要らない** |
270
+ | `p3 serve` + ブラウザ | ローカルのビューア兼エディタ。ファイルを読んで画面に流す(外での変更は「再読み込み」で取り込む。監視は補助)。データは持たない |
271
+ | Codex(`@infodb/codex-workspace`) | 操作する人のマシンで、その人のアカウントで動く。リポジトリとデータのフォルダだけを見せたコンテナの中 |
272
+
273
+ CLI は serve を経由せずファイルに直接書く(serve が常に動いている前提にしない。プロジェクトを跨いでも書き先の制御が増えない)。
274
+ serve の中で起きたこと(画面からの保存、Preflight の進み具合と終了)は SSE で画面に届く。外での変更は、画面の「再読み込み」と
275
+ タブ・ウィンドウに戻ったときの読み直し(POST /api/reload)で取り込む。ファイル監視は補助で、届かないことがある
276
+ (NFS や、Node の再帰的な監視が置き換えて保存したファイルの2回目以降の変更を通知しないことがある)。
277
+
278
+ 画面は定期的には問い合わせない、の例外を1つだけ置く: 要望の「概要・Preflight」を開いている間だけ、その要望の最新の Preflight を
279
+ 軽く確かめる(`GET /api/requests/:rid/preflight-status`、`PreflightService.pulse`)。CLI など外で始めた run とその進み・終わりは
280
+ serve の SSE に乗らず、監視も届かないことがあるため。返すのは要望の `lastPreflight` と、指定した run の `run.json` の状態・日時と
281
+ 更新を見分ける値(`version`)だけで、要望と run.json をディスクから読む(読み込んだ内容・索引・ファイル・rev は変えず、古い
282
+ キャッシュに戻すこともない。`MarkdownCollection.peek`)。run の状態は ready / pending(フォルダはあるが run.json がまだ無い)/
283
+ missing / broken、要望は ok / gone(削除・アーカイブ)/ broken。全件の読み直し・全 run・案・ログの走査はしない。ID は形を確かめ、
284
+ パスは受け取らない。
285
+
286
+ 画面の側(`web/lib/preflightWatch.ts`、要望の概要の `RequestPanel`): 確かめるのは 3 秒ごと(`PULSE_INTERVAL_MS`)で、前の確かめが
287
+ 終わってから次を予約する。タブが隠れたら止め、見えたらすぐ1回。ページを離れたら止める。SSE の `preflight-status` は速い経路として
288
+ 残し、届いたら今すぐ1回(確かめ中なら終わってから1回にまとめる)。表示する run は `?run=` で決め、無ければ開いたとき(と `?run=` が
289
+ 無くなったとき)の最新に留める。新しい run ができても表示は変えず、知らせ(`PreflightNotice`)から人が開く(自分で実行したときは
290
+ 今までどおりその run を開く)。表示中の run の版・状態が変わったら取り直す。run の取得は最後に頼んだものだけを使い、表示中の
291
+ run でない応答は捨てる。要望が消えた・読めないときは要望の枠の扱い(gone・読めない)に任せる
292
+
293
+ REST API はブラウザのためのローカル API として残すが、AI には CLI を使わせる。
294
+ CLI がファイルを直接触る形なら、API ごとに認証を持たせる問題はそもそも起きない。
295
+
296
+ ## 規則の置き場所
297
+
298
+ 同じ規則を入口(CLI・API・画面)ごとに書かない。足すときは次の1か所を直す。
299
+
300
+ src は5つの層に分け、依存の向きを `test/layers.test.ts` で確かめる:
301
+
302
+ | 層 | 中身 | 読み込んでよいもの |
303
+ | --- | --- | --- |
304
+ | `shared` | 型と判定(サーバと画面で共通) | なし(node: も外のパッケージも使わない。画面のビルドに入るので I/O を置かない) |
305
+ | `core` | CLI と serve の共通の中核(保存の層・規則・変更の手順・Preflight・設定・ChatGPT の接続) | `shared`(HTTP の hono は使わない) |
306
+ | `server` | HTTP の API と配信(`p3 serve`) | `core`・`shared` |
307
+ | `cli` | CLI | `core`・`shared`(serve の起動の `server/server.ts` だけ) |
308
+ | `web` | 画面 | `shared`(node: は使わない) |
309
+
310
+ | 何を | どこに |
311
+ | --- | --- |
312
+ | 要望・タスクの変更の手順(確かめる → 保存 → ブランチの割り当て・進行中に戻す → 変更通知) | `core/requestOps.ts`(CLI の各コマンドと API はここを呼ぶだけ) |
313
+ | Preflight(開始・評価対象の固定・タスク化) | `core/preflight/service.ts`(`PreflightService`) |
314
+ | 個々の規則(対応済・置き換え・作業先とブランチ・評価対象の比べ方) | `core/requestStatus.ts`・`core/supersede.ts`・`core/workTargets.ts`・`shared/preflightInput.ts` |
315
+ | サーバと画面の両方で使う判定・表示名 | `shared/` |
316
+ | 画面の API の失敗の扱い(rev の競合・評価対象の変更・無い) | `web/lib/api.ts` の `failureOf` |
317
+ | リリースノートの本文の下書き(外の変更・削除・読めないときに入力を残す・編集を始めた版で保存) | `web/lib/releaseNoteDraft.ts` |
318
+ | 読み取り(一覧・参照の解き方・進捗) | `core/ops.ts` |
319
+ | リリースノート(材料の規則・保存・出力・要約の生成) | `core/releaseNotes/`(`material.ts`・`store.ts`・`service.ts`・`generate.ts`) |
320
+ | タスクの関係(`depends_on`・`supersedes` だけ。同じ要望の中。Preflight のタスク化だけが張る) | `shared/types.ts` の `RELATION_TYPES`・`core/preflight/service.ts` の `materialize` |
321
+
322
+ CLI は `cli/main.ts`(振り分け・プロジェクトと変更者の決定・終了コード)と、種類ごとのコマンド(`taskCommands.ts`・
323
+ `requestCommands.ts`・`preflightCommands.ts`)に分ける。大きい画面は、ルートのファイルを組み立てだけにして部品を
324
+ `web/components/<ページ>/` に分ける。
325
+
326
+ ## サーバに置かない理由
327
+
328
+ 1. **Codex の置き場所が決まらない。** サーバ側で Codex を動かすと共有アカウントになる(OpenAI の規約上も避けたい)。
329
+ ユーザーごとにサーバへ認証情報を預けるのは運用が重い。ローカルなら各自のアカウントで動き、何も預けない。
330
+ 2. **プロジェクトのドキュメントがサーバに寄ってしまう。** Preflight はリポジトリのコードとドキュメントを読んで判断する。
331
+ サーバ側で判断するなら、それらをサーバへ複製し続ける必要がある。ローカルならリポジトリをそのまま見せればよい。
332
+ 3. **認証・運用のコスト。** Cognito を使っても、CLI・AI・ブラウザそれぞれのトークン管理が残る。
333
+
334
+ 外部に出ていくのは、各自が自分の Codex で OpenAI に送る内容だけになる(これは Codex を使う以上避けられない)。
335
+
336
+ ## Codex の使い方
337
+
338
+ - Preflight は **実行した人のマシン** で、`codex-workspace` のコンテナの中で動く。コンテナには管理対象リポジトリを
339
+ `/workspace`、データのフォルダを `/data` としてマウントする。データのフォルダはリポジトリの外にあってよい。
340
+ 認証情報は各自の ChatGPT の接続か `auth.json`(個人の場所に置き、プロジェクトには置かない)。
341
+ - 結果は戻り値ではなく **ファイル**(要望のフォルダの `preflight/<RUN>/assessment.json`, `drafts/*.md`)。
342
+ 同期すればチームの全員が同じ評価とタスク案を見られる。誰が実行したかは `run.json` とタスクの `updatedBy` に残る。
343
+ - 画面資料(`preflight/<RUN>/ui/`)もファイル契約にする(`src/core/preflight/uiMaterials.ts`)。エンジンは画像と
344
+ `ui/index.json` を書き、P3 が取り込む前に確かめて `run.json` の `ui` に記録する。画像の形式と大きさは拡張子ではなく
345
+ 中身から読み、配信のときも同じ確かめ方をもう一度する(取り込んだ後に差し替えられた画像は返さない)。画像は
346
+ 要望 / run / 資料 ID で決め、パスを受け取らない。応答には `X-Content-Type-Options: nosniff` と
347
+ `Content-Security-Policy: default-src 'none'` を付け、HTML / SVG は配信しない。資料が不正でも評価は残し、
348
+ 必要な画面イメージが足りないときだけ go を clarify にする(新しい承認の状態は作らない)
349
+ - 同じ要望を複数人が Preflight しても、run ごとに別ディレクトリ(ID に乱数を含む)なので衝突しない。
350
+ 「直近の run」は開始時刻の新しい順で決めるが、時計は戻ることがある(WSL2 の時刻の補正など)ので、前回を引き継いだ run
351
+ (`previous`)は引き継いだ相手より必ず新しいとする(`preflightStore.ts` の `newestFirst`)
352
+ - Codex との会話は続けない(1 run = 新しいコンテナ・新しいスレッドで1往復)。確認事項への回答や方針の変更は
353
+ **メモ**(要望のフォルダの `notes/N-....md`。1件1ファイル、書いた人と日時つき)として書き足し、次の run に
354
+ 前回の結果と一緒に渡す。経緯がファイルに残り、別の人が続きから Preflight できる。
355
+ - 前回: 直近の run が完了していて評価を読めるときだけ引き継ぐ。失敗・欠損なら古い成功 run に戻らず「前回なし」
356
+ - メモ: 前回を引き継ぐなら、引き継ぎの経路(`run.json` の `previous` を辿った run)で渡し済みのものを除く。
357
+ 失敗した run に渡しただけのメモは渡し済みにしない。前回を引き継がないなら全部渡す
358
+ - 選んだものは開始の時点で `carryover.md` に固定し、`run.json` に `previous` と `notes`(メモの ID)を残す。
359
+ 実行中に書き足したメモは次の run に回る
360
+ - 再評価のプロンプトには `carryover.md` の内容を資料として入れる。メモは尊重するが、書き込み先などの制約は変えさせない
361
+ - 操作は `p3 preflight <要望> --note "..."`(書き足してから実行)、`--note-only`(書くだけ)、`p3 notes <要望>`(一覧)。
362
+ 実行を始められなくてもメモは残るので、再試行でメモを書き直さない
363
+ - 画面のメモ欄は評価の下に1つだけ置く(評価を読んでから書くため)。評価が無い間(実行中・失敗)も同じ並びの位置にあり、
364
+ 入力中の文は保つ(別の要望に移ると消える)。評価の確認事項の「メモ欄で答える」から入力欄に移れる
365
+ - まだ一度も実行していなければメモ欄は出さない。CLI などで先に保存したメモがあればそれだけを見せ、最初の Preflight に渡す
366
+ (API と CLI は最初の実行の前のメモも受け付ける)
367
+ - 入力中のメモがある間は、上の通常の実行を止める(入力が渡らないまま実行されないように)。「保存して再実行」で保存してから
368
+ 実行するか、入力を消す。保存済みのメモだけなら通常の実行でも渡る
369
+ - 実行中も「メモだけ保存」はでき、実行中の評価ではなく次の Preflight に渡る。保存してから始められなかったときは、保存済みと
370
+ 伝え、書き直さずに再実行できる。過去の run を表示していても、引き継ぎ元は直近の run なので、何を引き継ぐかを入力欄の上に出す。
371
+ run ごとに、引き継いだ前回の run(クリックで移る)と渡したメモを表示する
372
+ - 過去の経緯は p3 が選ばず、Codex が調べる(`codexEngine.ts` の `historySection`)。以前は TF-IDF と areas(パス)の
373
+ 重なりで選んだ10件を渡していたが、リファクタリングでパスが変わる・ファイルを分割すると外れ、読み替えの表では分割や
374
+ 移動の繰り返しを扱えない。git は行ごとに履歴を追え(`blame -C -M`)、マージのコミットのブランチ名に要望 ID があるので、
375
+ コード → コミット → 要望 → `/data` の記録と辿れる。p3 を入れる前の経緯も分かる。全件はプロンプトに入れず、Codex が
376
+ rg と git で必要な分だけ読む(件数が増えて探しにくくなったら、ベクトル検索を検討する)
377
+ - 参照先ごとに git の履歴が使えるか(`repoRefs.ts` の `gitHistory`)を始めるときに決め、`scope` の `history` と指示に出す。
378
+ コンテナには参照先のフォルダだけを読むだけでマウントするので、`.git` がフォルダの中にあるときだけ使える(作業ツリーの
379
+ `.git` ファイルが指す本体・サブフォルダの上の `.git` はマウントの外)。浅い clone は途中まで
380
+ - Codex に書かせてよいのは run ディレクトリ(`/data/requests/<要望ID>/preflight/<RUN>/`)だけ。それ以外の変更は検出して警告する(git 差分による検出は今後)。
381
+ Codex のスレッドは `danger-full-access`・`approvalPolicy: never` で動く(コンテナを囲いにするため)が、これは何かを
382
+ 追加で許す保証ではない。コマンドの実行は禁止していない。参照先は読むだけのマウントで書けない。データのフォルダ(`/data`)は
383
+ 書けるマウントなので、「run の中だけ」は指示と事後の警告で守っている(書き込みを run に閉じ込める囲いは今は無い)。
384
+ 画面イメージの描画は、この Codex のコンテナではなく別のコンテナで行う
385
+ - ファイル契約なので、Mock エンジンでも人手で書いても同じ取り込み処理になる。案の `supersedes` のうち同じ要望に無いタスクはタスク化のときに捨てる
386
+ - テストは偽の app-server で、マウントの引数・指示文・記録・根拠の扱いを確かめる。本物の Codex が実際にどこまで読むか、
387
+ 読むだけのマウントへの書き込みが拒まれることは、偽の app-server では確かめられない
388
+
389
+ ### 評価対象の固定と、評価のあとの要望の変更
390
+
391
+ 要望のタイトルと本文は、Preflight の前後・実行中・完了済を含め、いつでも書き換えられる(`p3 request set --body` / `title=`、
392
+ API の PATCH。`rev` で楽観ロック)。書き換えても状態・既存のタスク・過去の run は変えない。そのかわり、古い評価からはタスク化しない
393
+ (`src/core/preflight/input.ts`)。
394
+
395
+ - **固定**: Preflight を始めるとき、要望をディスクから読み直し(監視していない外部の編集も取り込む)、タイトルと本文を
396
+ `run.json` の `input` に固定する。人が読む `request.md` とエンジンに渡す要望も同じ内容にする。実行中に要望が書き換えられても、
397
+ この run は固定した内容で評価し、終わったときに要望の本文を戻さない(ステータスだけを部分更新する)
398
+ - **比べるもの**: 保存されたタイトルと本文そのもの。`rev` や `lastPreflight` では比べない(Preflight 自身の状態の更新や、
399
+ タグ・期限・ステータスだけの変更では古くならない)。本文を元に戻せば一致に戻る。正規化は「改行を LF にそろえ、前後の空白・空行を
400
+ 除く」だけ(要望のファイルは保存するときに本文の前後を除くので、保存の形の違いで変わったことにしない)。行末の空白(Markdown の改行)
401
+ や途中の空行は違いとして扱う
402
+ - **run ごとの判定**(`inputMatch`): `same`(同じ)/ `changed`(`changed` に `title`・`body`)/ `unknown`(評価対象が読めない)。
403
+ `input` の無い以前の run は `request.md`(`# <要望ID> <タイトル>` の後に空行と本文)から読み、無い・形が違うときは unknown にする
404
+ (一致とはみなさない)。以前の run のファイルは書き換えない。API の run(一覧・詳細・要望の詳細の `runs`)と `p3 drafts` に添える
405
+ - **タスク化**: `previewMaterialize` は `inputMatch` を返し、`materialize` は直前に要望をディスクから読み直して same でなければ
406
+ `StaleInputError` で断る(API は 409 `code: "stale_input"`、rev の競合は 409 `code: "rev_conflict"`。CLI の `accept --json` は
407
+ `{ error, code, inputMatch }` を出して終了コード 1)。断るときはタスク・関係・アーカイブ・ブランチの割り当て・`materialization` を書かない。
408
+ 途中で失敗したタスク化のやり直しも同じ規則で、変わっていれば断る(評価した時点の内容に戻せば、作ったタスクを作り直さずに続ける。
409
+ 自動で巻き戻しはしない)。タスク化済みの run・過去の run・評価・案・画面資料はそのまま読める
410
+ - **再評価**: いつもどおり前回の結果とメモを引き継ぎ、前回の評価のあとでタイトル・本文が変わっていれば、`carryover.md` に
411
+ 「前回の評価のあとで変わった要望」として前回の時点の内容を書く。評価の基準は今の要望で、前回の評価・案・メモとの食い違いは
412
+ 確認事項に入れさせる。白紙の再評価や履歴の消去は作らない(前回を引き継がせたくなければ、メモでそう書く)
413
+ - **限界**: 比べるのは「始めたとき」と「タスク化の直前」。タスク化の途中に別のプロセスが本文を書き換えることまでは排他しない
414
+ (同じ要望を同時に触るときの調整は、これまでどおり人が行う)
415
+ - **戻し方**: 古い評価でタスク化したいときは、要望を評価した時点の内容(`request.md`)に戻す。今の内容でよければ再評価する
416
+ - **画面**(`web/components/request/BodyEditor.tsx`、`web/lib/requestDrafts.ts`、`web/lib/requestEdit.ts`): 本文は明示の保存だけ。
417
+ タイトル・タグ・本文の下書きは要望の画面(`useRequestDrafts`)が持ち、取り直しは項目ごとに比べる(`syncFieldDraft`: その項目が変わって
418
+ いなければ baseRev を進め、変わっていれば競合として知らせる)。未保存のタイトル・本文がある間は Preflight の実行とタスク化を止める。
419
+ タスク化の 409 は `code` で分ける(`stale_input` はサーバの理由をそのまま、`rev_conflict` は置き換えの候補の読み直し)
420
+
421
+ ### 置き換えられたタスク
422
+
423
+ 再評価でタスク化すると、新しい案が同じ要望の古いタスクを置き換える(`supersedes`)ことがある。
424
+ タスクの状態は 未着手 / 作業中 / 完了 の3つのままにし、置き換えは関係として扱う(`src/core/supersede.ts`)。
425
+
426
+ - **タスク化で知らせる候補**: **採用した** 案の `supersedes` のうち、同じ要望にある未完了(未着手・作業中)のタスク。
427
+ 不採用の案だけにあるもの・完了したタスク・無いタスクは候補にしない。
428
+ - **アーカイブは選んだものだけ**(既定はどれも残す)。確定の時点で候補を読み直し、候補でない・rev が変わった
429
+ ものがあれば何も変えずに失敗する(もう一度確認してもらう)。作業中のタスクをアーカイブしても、作業そのものは止まらない。
430
+ - **順序と再試行**: 新しいタスクと関係を保存してからアーカイブする(古いタスクを先に外さない)。途中経過は
431
+ `run.json` の `materialization`(作った案とタスク、選んだもの、アーカイブ済み)に残し、途中で失敗したら同じ
432
+ タスク化をもう一度行えば、作った案は作り直さず、アーカイブも重ねずに続きから終える。
433
+ - **印**: 保存済みのタスクの `relations` にある `supersedes` から導く。案に書かれた置き換えは、その案から作ったタスクの
434
+ 関係として残る(今あるタスクを指すものだけ)。
435
+ - **進捗**: 残したタスクは進捗に数える(完了しないと要望の全タスクは終わらない)。アーカイブしたものだけが外れる。
436
+ - タスク化の結果は `{ tasks, archived, kept }`(作ったタスク、アーカイブしたもの、置き換えられるが残したもの)。
437
+ 以前は作ったタスクの配列だった(CLI の `accept --json` と API の POST materialize。利用者は `.tasks` を読む)。
438
+ - **着手の警告**: 置き換えられたタスクが作業中に変わったとき(CLI の `move` / `set`、API の PATCH、画面のボードと詳細)、
439
+ 操作は行ったうえで `warnings`(code・対象・置き換えた側・文言)を返す。作業中のままの再指定では出さない。
440
+ - API: `GET .../preflight/:run/materialize` で確認(何も変えない)、`POST` に `{archive: [{id, rev}]}`。
441
+ 要望の詳細と タスクの GET は印 `superseded` を返す。
442
+
443
+ ### リリースノートの要約(生成の境界)
444
+
445
+ マイルストーンのリリースノートの機能の要約は、Preflight と同じ Codex の接続(個人設定・認証・イメージの確かめ・起動の診断)で頼む
446
+ (`CodexWorkspaceEngine.ask`、`core/releaseNotes/generate.ts`)。Preflight の評価・タスク化は行わない。
447
+
448
+ - **渡すもの**: 始めるときに固定した材料([リリースノートのデータ](#リリースノートのデータ))のうち、マイルストーンのタイトルと、
449
+ 収録する要望とタスクの ID・タイトル・変更の記録だけを依頼文に入れる。要望やタスクの本文・成果物・参照先・データのフォルダは
450
+ 渡さず、コンテナには何もマウントしない(`/workspace` は空の tmpfs で、終われば消える。パスの対応も要らない)
451
+ - **受け取るもの**: 最後の応答の JSON(項目ごとの文と出典)。P3 が形・件数(100)・長さ(1項目 600 文字・合計 2 万文字)・
452
+ 出典が依頼文に入れた要望とタスクにあるかを確かめ、だめなら `invalid_output` で失敗にする。ローカルのパス・秘密らしい文字列・
453
+ メールアドレスは `suspicious_content` の警告にする。本文の案(Markdown)は確かめた項目から P3 が組み立て、出典は本文に入れない
454
+ - **頼まないとき**: 材料(記録のある完了したタスク)が無ければ Codex を呼ばずに断る(本文は手で書いて保存できる)。
455
+ 入力(記録とタイトルの合計)が 12 万文字を超えたら、黙って切らずに断る
456
+ - **生成と保存は別**: 生成は保存したノートを変えない。結果(実行 ID・生成中・完了・失敗・取消、失敗の種類 `unavailable`・
457
+ `usage_limit`・`timeout`(既定 15 分)・`invalid_output`・`error`)はこのプロセスのメモリにだけ置き、変更通知
458
+ `release-generation` を出す。同じマイルストーンでは1つずつ。終わったら材料を読み直し、変わっていれば `material_changed`
459
+ (古い材料からの生成)を付ける。作り直しも上書きもしない
460
+ - ChatGPT のトークンは Preflight と同じく、ログとエラーから伏せる
461
+
462
+ ### llmcs の部品の依存(codex-workspace・chatgpt-plan)
463
+
464
+ llmcs の部品を npm の公開版で使う:
465
+
466
+ - `@infodb/codex-workspace`(codex-workspace-ts): Codex をコンテナで動かす
467
+ - `@infodb/chatgpt-plan`(chatgpt-plan-ts): Sign in with ChatGPT のサインイン・トークンの保存と更新・解除([docs/chatgpt-sign-in.md](chatgpt-sign-in.md))
468
+
469
+ package.json では公開版の版の範囲(`^0.2.0` など)で指定し、手元のフォルダへのリンク(`link:` / `file:`)は置かない。
470
+ 新しくチェックアウトしても隣に llmcs が無くて構わない。新しく公開された版は、pnpm の `minimumReleaseAge`(公開から1日)を
471
+ 過ぎてから入れる。待たずに入れる例外(`pnpm-workspace.yaml` の `minimumReleaseAgeExclude`)は、自分たちが公開した
472
+ `@infodb/*` の部品を、版を固定して書くときだけ置く(`@infodb/chatgpt-plan@0.1.1` の形。`test/package.test.ts` が確かめる)。
473
+ 公開から1日を過ぎたら外してよい。
474
+
475
+ `@infodb/codex-workspace` について P3 が使う公開 API と約束:
476
+
477
+ - `dockerCommand(workspace, { accessTokenEnv | authVolume, authFile })` が作る `docker run` は、作業場所を
478
+ `/workspace` にマウントする。P3 はそのマウントの直後に、データのフォルダを `/data` にマウントする引数を足す
479
+ - `WorkspaceSession.open(command, { model, effort, env, clientInfo, onEvent })` で app-server を起動する。ChatGPT の
480
+ トークンは `env`(`ACCESS_TOKEN_ENV`)で渡し、`docker run` の引数や記録には値を出さない
481
+ - `UsageLimitError` は使用量の上限(ChatGPT プランの `subscription_sharing_usage_limit_exceeded` を含む)
482
+ - `ensureImage({ maxAgeMs })` はイメージが無いか `maxAgeMs` より古ければ作り直し、中の Codex の版を返す。作り直すたびに
483
+ `CODEX_REFRESH`(その時刻)が変わるので、Codex を入れる段はキャッシュを使わず、その時点の最新が入る
484
+ - いつもの Preflight: 既定の1日より古ければ作り直す(個人設定 `codex.ensureImage: false` か `P3_CODEX_ENSURE_IMAGE=0` で止める)
485
+ - 強制更新(`p3 codex update`): `maxAgeMs` を -∞ にして、作った日時によらず作り直す。プロジェクト・認証を決める前に動き、
486
+ 個人設定の自動更新の停止(`codex.ensureImage: false`)とも関係しない。前に `docker version` でデーモンを確かめ、
487
+ 失敗した段(docker が無い / デーモン / 作成 / 版の取得)ごとに次にすることを出す(`src/core/preflight/codexImage.ts`)
488
+ - テストは偽の docker(`test/fixtures/fake-docker.mjs`)で行い、本物の Docker では次で確かめる:
489
+ `XDG_CONFIG_HOME=$(mktemp -d) p3 codex update --json`(未登録・未認証のままでよい)
490
+
491
+ 手元の llmcs の変更を P3 で試すときは、一時的にリンクに替え、試し終えたら公開版に戻す(リンクはコミットしない):
492
+
493
+ ```bash
494
+ pnpm add @infodb/codex-workspace@link:../llmcs/codex-workspace-ts # 一時的に手元の llmcs を使う
495
+ # …試す…
496
+ git checkout package.json pnpm-lock.yaml pnpm-workspace.yaml && pnpm install # 公開版に戻す
497
+ ```
498
+
499
+ `npm pack` やコミットの前に、`package.json` と `pnpm-lock.yaml` に `link:` が無いことを確かめる。
500
+ llmcs の変更を P3 で使うには、llmcs 側で新しい版を公開し、P3 の版の範囲を上げる(chatgpt-plan も同じ)。
501
+
502
+ ### 画面イメージの描画のイメージ
503
+
504
+ 画面イメージの描画(`src/core/preflight/render.ts`)は、Codex のイメージ(llmcs の Dockerfile)とは別に、P3 が持つ
505
+ Dockerfile(`src/core/preflight/render-image/`)で作る。llmcs の Dockerfile は変えない。将来 llmcs のイメージに
506
+ Playwright が入っても、それだけでは描画の安全の条件(ネットワークなし・認証情報なし・リポジトリなし・原稿は読むだけ)を
507
+ 満たさないので、描画は別のコンテナで行う。
508
+
509
+ - 版: Playwright 1.63.0(Chromium の headless shell)、Node 22(`node:22-bookworm-slim`)、`fonts-noto-cjk`。
510
+ Playwright はイメージの中で npm から入れる(P3 の依存には足さない)。版は公開から1日を過ぎたものに固定する
511
+ - イメージの名前は Dockerfile と `render.mjs` の中身の hash(`infodb-p3-render:<12桁>`)。中身が変われば次の描画で作り直す。
512
+ 大きさは約 1.4GB(amd64 で確かめた)
513
+ - Chromium の sandbox は使わない。コンテナを囲いにする(`--network none`・`--read-only`・`--cap-drop ALL`・
514
+ `no-new-privileges`・root ではない利用者・メモリ / CPU / プロセス数・時間の上限)。読み込みを止めるのは二重目の囲い
515
+ - 原稿は描く前に確かめる(`render.ts` の `checkHtml`): 使えるのは `<style>` の CSS・`data:` の画像とフォント・ページの中の `#id`。
516
+ スクリプト・`on*` 属性・`javascript:`・外のファイルや通信を指す参照(`http(s):`・`file:`・相対パス・`@import`)・
517
+ `iframe` / `object` / `embed` / `link` / `base` / `meta http-equiv` は断る。幅は 320〜2560 px、原稿は 2MB まで、高さ 16384 px を超える
518
+ ところは切る。DevContainer の中からは、出力先のフォルダにも `codex.pathMap` が要る
519
+ - 日本語のフォントは Debian の `fonts-noto-cjk`(SIL Open Font License 1.1)。イメージの中にだけ入り、P3 の配布物には含めない
520
+
521
+ ### 添付の確かめ方と置き場所
522
+
523
+ - 形式は拡張子ではなく中身で確かめる(PNG / JPEG の署名と大きさ、xlsx は ZIP の中央ディレクトリだけを読み、ブックであること・
524
+ マクロが無いこと・中のパスが外を指さないこと・項目 1 万まで・展開して 200MB まで)。保存のときは展開しない
525
+ - 原本は内部の名前(`file.png` など)で `attachments/A-.../` に置き、元の名前・説明・出典・追加した人と日時を `meta.json` に残す。
526
+ ダウンロードの名前は元の名前からパスの区切り・制御文字を外したもの
527
+ - xlsx の取り出し(`preflight/xlsx.ts`)は Preflight を始めて run に固定した原本から行う。展開後 1 項目 30MB・合計 200MB、
528
+ セル 5 万、画像 20、10 秒で打ち切り、打ち切ったこと・扱っていないもの(図形・グラフ・リンクの画像・EMF など)を記録する。
529
+ 外部のブック・URL は取りに行かず、マクロ・OLE は動かさず、XML の DOCTYPE は読まない
530
+
531
+ ## プロジェクトのドキュメントの扱い
532
+
533
+ - ドキュメントは **リポジトリに置いたまま**(`docs/`, README, コードのコメント)。p3 は複製も同期もしない。
534
+ - Codex はコンテナの中から、それらをリポジトリのファイルとして直接読む。
535
+ - p3 が作る記録(要望・評価・タスク案・タスク)もリポジトリ内の Markdown なので、それ自体がドキュメントになる。
536
+ 「なぜこのタスクがあるのか」は、タスク → 要望 → Preflight の評価を辿れば分かる。コードの経緯は git の履歴(マージのコミットの
537
+ ブランチ名 `req/<要望ID>-...` から要望へ)で辿る。
538
+ - Preflight で最初に読ませるドキュメント(設計方針・用語集など)は、「最初に読む」(`readFirst`)参照先の主なフォルダ
539
+ (`repos.<名前>.map`。フォルダでもファイルでもよい)に書く。指示文ではそれを「最初に読むもの」として、以前のプロジェクトの
540
+ `docs` と同じく「評価の前に、必要な範囲で読んでください」と渡し、ほかの参照先の主なフォルダは「どこから読むかの案内」として
541
+ 分けて渡す(docs を外したときに、指示が案内だけに弱まっていたのを戻した。入口 `entry` は任意で、あればそこから読ませる)。参照先ごとに書くので、どの参照先のファイルかが曖昧にならない
542
+ (以前のプロジェクトの `docs` は、名前を付けないと先頭の参照先のパスになり分かりにくかったので外した。構成の説明の
543
+ Markdown `mapFile` も入口と重なるので外した。どちらも保存のときに project.yaml から消す)。
544
+ `preflight.instructions` にはプロジェクト固有の評価の観点・制約を書く。どちらも Codex への指示に加わる。
545
+
546
+ ## 共有(同期)の方法
547
+
548
+ 同期の手段は **git**(またはファイル共有)。要望のフォルダ単位で push / pull すれば、その要望の状況を共有できる。
549
+ 開発者はすでに認証済みで、履歴(誰がいつ状態を変えたか)、PR による Preflight 結果のレビュー、
550
+ 1タスク1ファイルによる小さな差分がそのまま使える。排他制御は人が行う(同じ要望を同時に触らない)。
551
+
552
+ ### 解決したこと
553
+
554
+ - **ID の衝突** — 要望は作成日 + 乱数、タスクは要望の中の連番にしたので、別々の人が作った要望どうしは衝突しない
555
+ - **状態がブランチごとに分岐する** — データは1つのデータのフォルダに書く(リポジトリの中の `.p3/` なら
556
+ git のメインの作業ツリーのものに書き、要望の作業ツリーの `.p3/` は使わない)。要望の作業ツリーの中で実行しても書き込み先は1か所で、今の要望は今いる参照先のブランチから決まる
557
+
558
+ ### 残っている課題
559
+
560
+ 1. **データのフォルダの共有方法(保留)。** データのフォルダ自体を git リポジトリにして `p3 sync`(pull → commit → push)で
561
+ 同期する案があるが、使い勝手を見てから決める
562
+ 2. **rev による偽の衝突。** frontmatter の `rev` は、同じタスクの別々の項目を変えただけでも git のマージで衝突する。
563
+ ファイル内容のハッシュによる楽観ロックに変えれば、`rev` をファイルに書かずに済む。要望単位で人が排他するので優先度は低い(今後)
564
+ 3. **git を使わないメンバー。** 閲覧だけなら、静的な HTML に書き出して共有する(`p3 export`、今後)
565
+
566
+ ## AI エージェントへの指示(`p3 init --agents` で AGENTS.md / CLAUDE.md に追記する内容)
567
+
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` が違いを知らせる)。
574
+
575
+ ```markdown
576
+ ## タスク管理(infodb p3)
577
+
578
+ - 作業の単位は要望。タスクは `p3` CLI(入っていなければ `pnpx @infodb/p3`)で操作し、`--json` で結果を読むこと(データのフォルダを直接編集しない)。
579
+ 詳しい手順はスキル `.claude/skills/p3/SKILL.md`(Claude Code)・`.agents/skills/p3/SKILL.md`(Codex)。中身は同じ
580
+ - 変更するときは環境変数 `P3_ACTOR=ai:<エージェント名>` を付ける
581
+ - 操作する要望は `--req <要望ID>` で指定する(要望の作業ツリーの中なら省ける)。まず `p3 whoami --json` で確かめる
582
+ - `whoami` の `via`(プロジェクトの決まり方)が `cwd` でなければ(`dir` / `project` / `legacy` / `only`)、それ以上 p3 を操作せず、対象のプロジェクトでよいか人に確かめる(推測した `--project` / `--dir` で避けない。人が指定・確認した後はその対象のまま続ける)
583
+ - 新しい作業を頼まれたら `p3 request new "<タイトル>" --body "..."` で要望を登録し、ID を伝えて終える。
584
+ Preflight(`preflight`)とタスク化(`accept`)は人が行う(AI は実行しない。結果を `p3 drafts` で読むのと、頼まれたメモの保存 `--note-only` はよい)
585
+ - 着手する前に `p3 show T003 --brief --json` で本文・依存とその状態(`dependencies`)・置き換えの注意(`warnings`)を読む
586
+ - 着手する前に、`--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)は人が決める
589
+ - 置き換えられたタスク(`p3 ls` の `※置換`、`--json` の `superseded`)からは始めない。`move` が `warnings` を返したら止めて人に確かめる
590
+ - 作業中に新しく必要になった作業は `p3 new "<タイトル>" --body "..."` でタスクにする(人への質問はタスクにしない)
591
+ ```