@infodb/p3 0.11.0 → 0.13.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 (138) hide show
  1. package/README.md +33 -33
  2. package/dist/web/assets/CompletionReview-gZKZrDu_.js +1 -0
  3. package/dist/web/assets/ImprovementDialog-Dno6dPnG.js +1 -0
  4. package/dist/web/assets/Outputs-BgHalMGb.js +1 -0
  5. package/dist/web/assets/RequestStatus-hZcBUUIu.js +1 -0
  6. package/dist/web/assets/Tabs-C3NmwCc3.js +1 -0
  7. package/dist/web/assets/TagInput-B2b862qn.js +1 -0
  8. package/dist/web/assets/TaskDrawer-4BQBELXa.js +6 -0
  9. package/dist/web/assets/_requestId-BMAG1t3o.js +1 -0
  10. package/dist/web/assets/_requestId-tbg2pA2S.js +1 -0
  11. package/dist/web/assets/archive-DMl6WyOe.js +1 -0
  12. package/dist/web/assets/board-BMTcHKyt.js +1 -0
  13. package/dist/web/assets/done-CL6Nlsua.js +1 -0
  14. package/dist/web/assets/draft-BvGxfD7v.js +2 -0
  15. package/dist/web/assets/index-Dp7Fc4VI.css +2 -0
  16. package/dist/web/assets/index-KdlgMitg.js +12 -0
  17. package/dist/web/assets/metrics-Cu7gJ7Rk.js +1 -0
  18. package/dist/web/assets/new-DTXWHuFO.js +1 -0
  19. package/dist/web/assets/outputs-CXqnjSqV.js +1 -0
  20. package/dist/web/assets/preflightInput-ClKwkp8R.js +2 -0
  21. package/dist/web/assets/preload-helper-oLCrNCwz.js +1 -0
  22. package/dist/web/assets/quality-RFd-7k3r.js +1 -0
  23. package/dist/web/assets/release-notes-Bpdi6RdY.js +5 -0
  24. package/dist/web/assets/requestData-CbFxwW5w.js +1 -0
  25. package/dist/web/assets/routes-BIt8bExF.js +6 -0
  26. package/dist/web/assets/settings-CsCqF_1B.js +1 -0
  27. package/dist/web/assets/taskReview-_WCgnQit.js +1 -0
  28. package/dist/web/assets/ui-BGK72r3u.js +1 -0
  29. package/dist/web/assets/workTarget-CySfKyfB.js +30 -0
  30. package/dist/web/index.html +4 -4
  31. package/docs/architecture.md +610 -33
  32. package/docs/development.md +61 -17
  33. package/docs/how-to-use.md +554 -17
  34. package/docs/installation.md +235 -144
  35. package/docs/publishing.md +1 -1
  36. package/lib/cli/agentsStatus.js +197 -0
  37. package/lib/cli/args.js +111 -2
  38. package/lib/cli/guide.js +27 -0
  39. package/lib/cli/guide.md +214 -0
  40. package/lib/cli/help.js +74 -1
  41. package/lib/cli/main.js +97 -17
  42. package/lib/cli/metricsCommands.js +77 -0
  43. package/lib/cli/output.js +19 -1
  44. package/lib/cli/preflightCommands.js +7 -1
  45. package/lib/cli/project.js +13 -24
  46. package/lib/cli/qualityCommands.js +188 -0
  47. package/lib/cli/readOnly.js +17 -0
  48. package/lib/cli/requestCommands.js +33 -4
  49. package/lib/cli/requirementCommands.js +288 -0
  50. package/lib/cli/retroCommands.js +106 -0
  51. package/lib/cli/revisitCommands.js +73 -0
  52. package/lib/cli/showView.js +183 -4
  53. package/lib/cli/taskCommands.js +341 -20
  54. package/lib/cli/taskReviewCommands.js +178 -0
  55. package/lib/cli/userConfig.js +47 -0
  56. package/lib/core/completionRefs.js +46 -0
  57. package/lib/core/context.js +4 -1
  58. package/lib/core/metrics/definitions.js +434 -0
  59. package/lib/core/metrics/index.js +88 -0
  60. package/lib/core/metrics/manual.js +180 -0
  61. package/lib/core/milestoneReview/material.js +11 -1
  62. package/lib/core/milestoneReview/mockReviewer.js +1 -0
  63. package/lib/core/milestoneReview/review.js +70 -6
  64. package/lib/core/milestoneReview/service.js +29 -93
  65. package/lib/core/milestoneReview/store.js +12 -62
  66. package/lib/core/ops.js +23 -3
  67. package/lib/core/preflight/carryover.js +6 -2
  68. package/lib/core/preflight/codexEngine.js +34 -17
  69. package/lib/core/preflight/diagnose.js +4 -9
  70. package/lib/core/preflight/engine.js +15 -0
  71. package/lib/core/preflight/hostPaths.js +260 -0
  72. package/lib/core/preflight/input.js +33 -5
  73. package/lib/core/preflight/instructions.js +36 -2
  74. package/lib/core/preflight/mockEngine.js +24 -2
  75. package/lib/core/preflight/render.js +22 -3
  76. package/lib/core/preflight/service.js +99 -8
  77. package/lib/core/preflight/uiRender.js +3 -0
  78. package/lib/core/projectRegistry.js +3 -3
  79. package/lib/core/quality.js +21 -0
  80. package/lib/core/qualityImprovement.js +221 -0
  81. package/lib/core/requestOps.js +294 -11
  82. package/lib/core/retrospective.js +208 -0
  83. package/lib/core/reviewCandidates.js +56 -0
  84. package/lib/core/reviewRuns.js +205 -0
  85. package/lib/core/store/archivedTasks.js +74 -0
  86. package/lib/core/store/collection.js +32 -3
  87. package/lib/core/store/normalize.js +35 -2
  88. package/lib/core/store/preflightStore.js +23 -1
  89. package/lib/core/store/projectFile.js +10 -0
  90. package/lib/core/store/workspace.js +49 -3
  91. package/lib/core/taskReview/material.js +459 -0
  92. package/lib/core/taskReview/mockReviewer.js +30 -0
  93. package/lib/core/taskReview/paths.js +15 -0
  94. package/lib/core/taskReview/review.js +312 -0
  95. package/lib/core/taskReview/service.js +187 -0
  96. package/lib/core/taskReview/store.js +214 -0
  97. package/lib/server/api/manifest.js +104 -5
  98. package/lib/server/api/milestoneReviewRoutes.js +4 -3
  99. package/lib/server/api/routes.js +265 -17
  100. package/lib/server/api/taskReviewRoutes.js +66 -0
  101. package/lib/server/server.js +2 -2
  102. package/lib/shared/acceptance.js +618 -0
  103. package/lib/shared/completionRecord.js +327 -0
  104. package/lib/shared/metrics.js +42 -0
  105. package/lib/shared/milestoneReview.js +2 -1
  106. package/lib/shared/preflightInput.js +1 -1
  107. package/lib/shared/quality.js +391 -0
  108. package/lib/shared/qualityImprovement.js +1 -0
  109. package/lib/shared/qualityTemplates.js +31 -0
  110. package/lib/shared/requirementSource.js +635 -0
  111. package/lib/shared/retrospective.js +286 -0
  112. package/lib/shared/reviewCandidate.js +308 -0
  113. package/lib/shared/reworkHistory.js +81 -0
  114. package/lib/shared/taskBlock.js +142 -0
  115. package/lib/shared/taskReview.js +56 -0
  116. package/package.json +3 -2
  117. package/skills/p3/SKILL.md +9 -152
  118. package/dist/web/assets/Outputs-ddwte0jj.js +0 -1
  119. package/dist/web/assets/RequestStatus-Bg1OLbRc.js +0 -1
  120. package/dist/web/assets/Tabs-DTmggzgg.js +0 -1
  121. package/dist/web/assets/TagInput-BHAgjLP7.js +0 -1
  122. package/dist/web/assets/TaskDrawer-Dz_5c2NH.js +0 -3
  123. package/dist/web/assets/_requestId-D9-gtIcG.js +0 -1
  124. package/dist/web/assets/_requestId-DzCNYvqf.js +0 -30
  125. package/dist/web/assets/appCtx-Cm24VpAf.js +0 -1
  126. package/dist/web/assets/board-MCHcZ-PU.js +0 -1
  127. package/dist/web/assets/done-zq10Bt08.js +0 -1
  128. package/dist/web/assets/draft-CfJeyLOl.js +0 -1
  129. package/dist/web/assets/index-Ce0ndpne.js +0 -12
  130. package/dist/web/assets/index-D68mkSnw.css +0 -2
  131. package/dist/web/assets/new-9TKiNT4O.js +0 -1
  132. package/dist/web/assets/preflightInput-BAeEJYUK.js +0 -2
  133. package/dist/web/assets/preload-helper-FBLw7u7x.js +0 -1
  134. package/dist/web/assets/release-notes-hK5XezLW.js +0 -5
  135. package/dist/web/assets/requestData-BnN7mctX.js +0 -1
  136. package/dist/web/assets/routes-usHwrrA0.js +0 -3
  137. package/dist/web/assets/settings-BVZDnL6O.js +0 -1
  138. package/dist/web/assets/workTarget-Cijqq4yH.js +0 -1
package/lib/cli/help.js CHANGED
@@ -13,6 +13,8 @@ export const HELP = `p3(infodb p3)— 要望ごとにフォルダを分け
13
13
  --agents claude|codex|both AI 向けの使い方(スキルと AGENTS.md / CLAUDE.md の節)を置く先(値を省くと both。付けなければ置かない)
14
14
  agents claude|codex|both [--force] AI 向けの使い方を、今いるリポジトリに後から置く・最新にする(選んだ先だけ。データ・個人設定は変えない)
15
15
  違うものは上書きせず知らせる。--force で選んだ先のスキルと p3 の節だけを同梱の版にする(ほかの文は残す)
16
+ guide AI エージェント向けの作業の手順(この CLI に同梱した版)を出す。プロジェクトを決めず、何も変えない
17
+ --json で schemaVersion・cliVersion(実行中の版)・entryVersion(入口の決まりの版)・guide(手順の全文)
16
18
  join 既にあるプロジェクト(共有されたデータのフォルダ)に参加する。個人設定に登録するだけで、データ・リポジトリのファイルは変えない
17
19
  --project 名前 --dir フォルダ(既定はリポジトリのルートの .p3)--repo-name 参照先の名前(共有の定義にあるもの)--yes
18
20
  project [ls | add <名前> <フォルダ> | rm <名前>] 個人設定のプロジェクト
@@ -27,6 +29,18 @@ export const HELP = `p3(infodb p3)— 要望ごとにフォルダを分け
27
29
  codex.effort / codex.ensureImage / preflight.engine / serve.host / serve.port(キー= で消す)
28
30
  set codex.pathMap+=<このマシンのパス>=<Docker デーモンから見たパス> パスの対応を足す
29
31
  set codex.pathMap-=<このマシンのパス> 外す(codex.pathMap= で全部外す)
32
+ paths <このマシンのパス> ... Docker にマウントするときのホストのパスと決め方(DevContainer では自動。変えない)
33
+ quality 品質基準(project.yaml の quality。未設定・設定済み・読めない)とテンプレートの改版の差分
34
+ templates / template <id> 同梱のテンプレート(版つきの例。業界の標準への認証ではない)
35
+ 未設定のままでも作業は続けられる(init は必須ではない)。未設定から add / adopt をそのまま使える
36
+ init 意図して空にする(設定済みなら何も変えない)/ adopt <テンプレート> 写して採用する / upgrade <テンプレート> 改版の差分を当てる
37
+ add --text 文 [--repo 名前 ...] (--command コマンド --success 成功の条件 | --reference 確かめ方)
38
+ set <Q1> [--text] [--repo 名前 ...|all] [...] / rm <Q1> / exempt <Q1> --reason 理由 / unexempt <Q1>
39
+ --repo は繰り返して複数の参照先(例: --repo app --repo infra)。add で省くと全参照先、set で省くと対象を変えない。
40
+ all は全参照先で、個別の名前とは一緒に使えない。--repo を繰り返せるのは quality add / set だけ
41
+ --version <版> で、他で変わっていれば競合(終了コード 3)。P3 はコマンドを実行しない
42
+ improve [task <要望>/<T> <run> | milestone <ID> <run>] 品質の不足の診断と改善要望の原稿(読むだけ)
43
+ --key <不足の鍵>... で選ぶ / --register --hash <診断の版> [--title] [--body] [--reopen] で明示して登録する
30
44
  progress 要望ごとの進捗(マイルストーンごと。--all で完了・見送りも。既定でも対応済を出す)
31
45
  milestone [ls | add <id> | set <id> | rm <id>] マイルストーン(リリース) --title 名前 --due YYYY-MM-DD --done
32
46
  milestone show <id> 目的・予定している機能と版(--json の milestonesVersion)
@@ -48,6 +62,13 @@ export const HELP = `p3(infodb p3)— 要望ごとにフォルダを分け
48
62
  できるか・対象・hash は show で見る。材料が変わっていれば何も変えずに終了コード 3、途中で止まったら非ゼロ
49
63
  例: p3 release-notes generate v0.2 > draft.md → 直す → p3 release-notes save v0.2 --file draft.md
50
64
  p3 release-notes export v0.2 > RELEASE.md
65
+ metrics [--milestone <ID>] 開発の指標(要望の作成から対応済・完了済までの時間、受け入れ基準の未達・未検証・証拠なし・再確認、
66
+ 手戻り、AI レビューの未達判定・意図しない変更の候補)。
67
+ 値・単位・対象・欠損・算出の方法を出す(読むだけ。記録の欠けは 0 にせず欠損と出す。成績の評価には使わない)
68
+ metrics record <指標> <値> 人が記録する値: cost(--unit JPY など通貨ごと)/ post_release_defects(0 以上の整数)
69
+ --from YYYY-MM-DD --to YYYY-MM-DD --source 出典 [--milestone ID(省くと全体)] [--note メモ]
70
+ 同じ指標・範囲・期間・単位の再送は何もしない。値を変える訂正は --rev 版(無い・違えば競合で終了コード 3)
71
+ metrics records / rm <M1> 人の記録の全部 / 消す(--rev 版)
51
72
  whoami 操作するプロジェクト・変更者・今の要望
52
73
  serve [--port] [--host] ブラウザ用のビューアを起動(既定は個人設定の serve.port / serve.host か $P3_PORT / $P3_HOST)
53
74
  --all-projects 個人設定に登録したプロジェクトを跨いで扱う(画面で選ぶ。--project / --dir とは一緒に使えない)
@@ -77,19 +98,67 @@ export const HELP = `p3(infodb p3)— 要望ごとにフォルダを分け
77
98
 
78
99
  タスク(今の要望の中。--req <要望> で指定、要望の作業ツリーの中なら省略可)
79
100
  ls 一覧 --status s1,s2 --area パス -q 語句 --repo <参照先>|none(作業先) --all(全要望)
101
+ --blocked 止まっているタスクだけ(ほかの条件と AND。--archived とは一緒に使えない)
102
+ --review 見直しが必要(候補)の完了したタスクだけ(ほかの条件と AND)
80
103
  show <T003|要望|語句> 詳細と関係(依存・置き換え)
81
104
  --brief 作業に要る項目だけ(本文・状態・依存とその状態・置き換えの注意・成果物・rev)
82
105
  new <タイトル> --body 本文|- --area a --label l --status --output 成果物(繰り返し可)
83
106
  --repo <参照先>|none 作業先(作業先にできる参照先だけ。足りないブランチは割り当てる)
107
+ --criterion 文 受け入れ基準(繰り返し可。ID は A1, A2, ... を振る)
84
108
  set <T003> キー=値 ... title status labels areas outputs repo(空で消す。outputs= はカンマ区切りで置き換える。repo=none は作業先なし)
85
109
  --repo-output <参照先>=<成果物> リポジトリごとの成果物を足す(repoOutputs= で全部外す)
110
+ --criterion 文 受け入れ基準を足す / --evidence・--evidence-file・--evidence-json 証拠を残す(move と同じ)
86
111
  move <T003> <ステータス> --output URL・文章・パス(成果物を足す。繰り返し可。カンマで分けない)
87
112
  --repo-output <参照先>=<URL> リポジトリごとの成果物(最後のタスクに全リポジトリの PR を残す)
88
113
  --record 本文|- 変更の記録(何を変えたか・なぜ・入れた決まり・やめたもの。AI が完了にするときは必須。set でも直せる)
114
+ --evidence <ID>=met|unmet|unverified[:本文] 受け入れ基準ごとの証拠(繰り返し可。met は本文が要る)
115
+ --evidence-file 証拠.md|- 見出し「## A1 met」ごとの証拠をまとめて(- は --record - と一緒に使えない)
116
+ --evidence-json 証拠.json|- 根拠つきでまとめて [{"id":"A1","result":"met","evidence":"…","basis":{"kind":"machine",…}}]
117
+ (--evidence と --evidence-file は根拠を書けない: 前の同じ結果の根拠を引き継ぎ、無ければ申告のみ・unverified は未確認)
118
+ 不足(証拠なし・未達・未検証・基準を変えた後・申告のみの met)があっても完了は拒まず、stderr に出す
89
119
  check <T003> [--off] 完了したタスクを人が確認して「済み」にする(--off で外す)
90
- archive <T003> .archive/ へ移す
120
+ block <T003> --reason 理由|- [--decision 決めてほしいこと|-]
121
+ 作業中のタスクに止まっている理由を付ける・内容を直す(状態は作業中のまま。止まった時刻は直しても変えない)
122
+ 理由 2000・決めてほしいこと 2000 文字まで。- は標準入力(どれか1つ)
123
+ unblock <T003> --resolution 回答・解決の内容|-
124
+ 停止を解除する(回答・解決の内容は必須・4000 文字まで。状態は変えず、自動では再開しない)
125
+ 止まったままは未着手・完了へ動かせない(先に解除する)。付けた・直した・解除したことは履歴に残る
126
+ criteria <T003> 受け入れ基準と証拠・不足(作業した側の申告。人が済みにする前に読む)
127
+ add <文>... 足す / edit <ID> <文> 文を変える(記録済みの証拠は再確認が必要になる)
128
+ rm <ID>... 消す(証拠は残る。ID は使い直さない) / order <ID>... 並べ替える(今の ID を全部)
129
+ evidence <T003> <ID> <結果> 証拠を残す(再記録は置き換え)。本文は続けて書くか --body 本文|- / --file 本文.md
130
+ --basis unverified|declaration|read|machine 根拠の種類(作業した側の申告。P3 は検査を実行しない)
131
+ read: --reference 読んだもの / machine: --command コマンド --check-result 結果 --target <参照先>:<コミット>
132
+ evidence <T003> --file 証拠.md|- まとめて / --evidence-json 証拠.json|- 根拠つきでまとめて
133
+ evidence <T003> rm <ID>... 消す
134
+ 済みのタスクの基準・証拠の中身を変えると済みが外れる(同じ値の再保存・成果物の追加では外れない)
135
+ review <T003> 完了したタスクの AI レビュー(別の Codex のスレッドが、固定した差分と前後のコードを読むだけで基準と比べる。
136
+ 終わるまで待つ。Ctrl-C で取り消す。結果はタスクの状態・済み・基準・証拠を変えない)
137
+ --target <参照先>:<コミット>[,<コミット>] | <参照先>:<base>..<head> 比較対象(繰り返し可。省くと成果物のコミット)
138
+ --viewpoint builtin|project|<参照先>@<SHA>:<パス> 観点(省くと既定。project は project.yaml の taskReview.viewpoints)
139
+ --engine codex|mock(Preflight の担当が agent なら Codex には --engine codex の明示が要る)--preview 材料を見るだけ
140
+ reviews <T003> レビューの履歴 / review-show <T003> <run> 1回分 / review-cancel <T003> <run> 取消
141
+ (所有者を確かめられない run は --acknowledge-stopped で中断。無い → 2、実行中・終わっている・材料が変わった → 3)
142
+ archive <T003> .archive/ へ移す(消さない。ID は再利用しない)
143
+ ls --archived アーカイブしたタスクの一覧(今の要望。読むだけ。壊れたファイルは「読めない」に出す)
144
+ show <T003> --archived アーカイブしたタスクの詳細(本文・変更の記録・成果物)。通常の ls / show / 進捗には出ない
91
145
  find <語句> 参照・タイトルで探す
146
+ source [<要望>] 要求の出典と確認(任意): 根拠の記録と状態(未記録・未確認・確認記録あり・再確認が必要・対応先不明)・回答
147
+ add --target 対象の要求・前提 --source 出典(役割・資料名・版・節)--grounds 根拠|-(承認された計算例など)
148
+ edit <S1> [同じ項目] / confirm <S1> --by 確かめた役割・アクター --on YYYY-MM-DD / rm <S1>
149
+ (確認には出典・根拠・人・日が要る。題・本文・記録を変えると再確認が必要。記録は申告で P3 の保証ではない)
150
+ source <T003|D1> [<A1> 操作] 受け入れ基準ごとの記録(D1 はタスク案。--run PF-...)。add --from S1 で要望の記録を写す(確認は引き継がない)
151
+ --sources-json 操作.json|- まとめて([{"criterion":"A1","op":"add","source":"…","basis":"…"}])
92
152
 
153
+ retro [<要望>] 振り返り: 対象(確定した採用済みの Preflight とリスクの原文)と候補(採用を終えた run と作ったタスク・子の根拠)
154
+ confirm <run> [--reason 訂正の理由] 対象を確定する(最新の実行・採用では変わらない。訂正は理由が要る。--rev で版)
155
+ judge <番号> --state occurred|not_occurred|unchecked リスクの確認(人の判断)。起きた → --facts 事実、
156
+ 起きなかった → --scope 確認した範囲、どちらも根拠が要る。判断を変える・戻すには --reason
157
+ --evidence review:T001:<run>:<項目>[:<位置>] | milestone:<ID>:<run>:<項目>[:<位置>][:<理由>] | rework:T001:R1 | manual:<参照>
158
+ revisit [<要望>] [--all] 見直しが必要(候補): 完了の記録(完了・済みにしたときの条件)と今の条件の差(品質基準・受け入れ基準・
159
+ 要求の根拠・前提の変更)。完了済みも含む。候補を出すだけで状態・済みは変えない。確かめたら済みにし直す
160
+ premise [<要望>] 前提の変更の一覧 / add --target <要望 ID|T001|S1>(繰り返し可)--reason 理由 --condition 新しい条件・版
161
+ ack <P1> --target <ID> --condition 確かめた条件 変更を確かめたことを残す(過去の記録・状態は変えない)
93
162
  Preflight
94
163
  preflight [<要望>] 評価・細分化を実行し、完了まで待つ --engine codex|mock
95
164
  前回の結果とまだ渡していないメモを引き継ぐ
@@ -101,6 +170,10 @@ Preflight
101
170
  Codex / Mock の run は、動いているプロセスに中断を頼み、止まるまで少し待つ。止まらなければ requested)
102
171
  --acknowledge-stopped 動いているか確かめられない run(以前の版・別の環境)を、止まっていることを確かめて中断にする
103
172
  (記録だけ。プロセスやコンテナは止めない)
173
+ clarify [<要望>] 確認事項(ID・確認先・質問・必要な根拠・判断への影響)と回答の状態 --run PF-...
174
+ answer [<要望>] <Q1> 確認事項に回答する(要望に残す。過去の run は書き換えない。再評価は preflight で明示して始める)
175
+ --body 回答|- --by 回答した役割 --on YYYY-MM-DD --source 出典 --grounds 根拠|- --link S1(対応する根拠の記録)
176
+ --answer-json 回答.json|- まとめて / answer [<要望>] <Q1> rm 消す
104
177
  notes [<要望>] メモの一覧(次の Preflight に渡すもの・渡し済み)
105
178
  attach [ls] 要望の添付(PNG / JPEG / xlsx)の一覧。要望は --req(要望の作業ツリーの中なら省略可)
106
179
  attach add <ファイル> 添付を足す --description 説明 --source 出典。次の Preflight を始めるときに run に固定して渡す
package/lib/cli/main.js CHANGED
@@ -4,6 +4,29 @@ import { openProject } from "../core/context.js";
4
4
  import { machineSettingsSource, resolveMachineSettings, SettingsError } from "../core/machineSettings.js";
5
5
  import { progress, resolveRef, resolveRequestId, titleOf } from "../core/ops.js";
6
6
  import { OpRuleError } from "../core/requestOps.js";
7
+ import { AcceptanceInputError } from "../shared/acceptance.js";
8
+ import { RequirementInputError } from "../shared/requirementSource.js";
9
+ import { requirementCommand } from "./requirementCommands.js";
10
+ import { revisitCommand } from "./revisitCommands.js";
11
+ import { retroCommand } from "./retroCommands.js";
12
+ import { metricsCommand } from "./metricsCommands.js";
13
+ import { MetricsError } from "../shared/metrics.js";
14
+ import { RetrospectiveError } from "../shared/retrospective.js";
15
+ /** 進捗の行の見直し候補の印(要望自身・自分のタスク・配下を分ける。無ければ空) */
16
+ function reviewMark(p) {
17
+ const r = p.review;
18
+ if (!r)
19
+ return "";
20
+ const parts = [r.self?.state === "candidate" ? "要望" : "", r.tasks ? `タスク ${r.tasks}` : "", r.below ? `配下 ${r.below}` : ""].filter(Boolean);
21
+ return parts.length ? ` ※見直し候補(${parts.join("・")})` : "";
22
+ }
23
+ import { PremiseInputError } from "../shared/reviewCandidate.js";
24
+ import { BlockInputError } from "../shared/taskBlock.js";
25
+ import { taskReviewCommand } from "./taskReviewCommands.js";
26
+ import { qualityCommand } from "./qualityCommands.js";
27
+ import { QualityInputError } from "../shared/quality.js";
28
+ import { ImprovementError } from "../core/qualityImprovement.js";
29
+ import { TaskReviewRejected } from "../core/taskReview/material.js";
7
30
  import { MilestonesConflictError, ProjectInputError } from "../core/store/workspace.js";
8
31
  import { ReviewCancelRefused, ReviewRejected } from "../core/milestoneReview/service.js";
9
32
  import { ReviewStoreError } from "../core/milestoneReview/store.js";
@@ -18,8 +41,10 @@ import { chatgptCommand } from "./chatgpt.js";
18
41
  import { table } from "./format.js";
19
42
  import { config, currentRequest, init, isAgentChoice, joinProject, locateHere, placeAgents, projectCommand, repoCommand, repoRoot, resolveActor, runnerText, UsageError } from "./project.js";
20
43
  import { HELP } from "./help.js";
44
+ import { guide } from "./guide.js";
45
+ import { agentsText, diagnoseAgents } from "./agentsStatus.js";
21
46
  import { readsOnly } from "./readOnly.js";
22
- import { parse } from "./args.js";
47
+ import { checkRepeatedRepo, parse } from "./args.js";
23
48
  import { Output, bar } from "./output.js";
24
49
  import { requestCommand, milestoneCommand } from "./requestCommands.js";
25
50
  import { taskCommand } from "./taskCommands.js";
@@ -78,6 +103,7 @@ async function main(argv) {
78
103
  }
79
104
  const cwd = process.cwd();
80
105
  const out = new Output(o.json ?? false);
106
+ checkRepeatedRepo(cmd, o);
81
107
  // --force は p3 agents だけ(ほかのコマンドで黙って無視しない)
82
108
  if (o.force && cmd !== "agents")
83
109
  throw new UsageError("--force は p3 agents でだけ使えます");
@@ -97,6 +123,17 @@ async function main(argv) {
97
123
  const source = machineSettingsSource({ cli: { port: o.port, host: o.host } });
98
124
  return serveUntilSignal(await startServer({ allProjects: true, port: settings.serve.port, host: settings.serve.host, static: true, settings: source }));
99
125
  }
126
+ // AI 向けの作業の手順。この CLI に同梱した原本を返すだけで、プロジェクトは決めない(未登録・壊れた定義でも読める)
127
+ if (cmd === "guide") {
128
+ if (args.length)
129
+ throw new UsageError(`guide は位置引数を取りません: ${args.join(" ")}(p3 guide [--json])`);
130
+ const g = { ...guide(), agents: diagnoseAgents(cwd) };
131
+ // 通常の出力は手順の本文だけ(JSON の guide と同じ)。入口に対応が要るときだけ、その要点を標準エラーに出す
132
+ if (!o.json && !g.agents.ok)
133
+ process.stderr.write(`p3: 置いた AI 向けの入口: ${agentsText(g.agents).join("\n")}\n`);
134
+ out.result(g, () => g.guide.trimEnd());
135
+ return 0;
136
+ }
100
137
  // AI 向けの使い方を置く・最新にする。今いるリポジトリのルートに置くだけで、プロジェクトは決めない(データ・個人設定は変えない)
101
138
  if (cmd === "agents") {
102
139
  const [choice, ...rest] = args;
@@ -225,7 +262,7 @@ async function main(argv) {
225
262
  return { col: ctx.ws.tasksOf(rid), rid, tid };
226
263
  };
227
264
  const env = { ctx, out, args, o, actor, current, expectedRev, requestArg, taskArg, split, cwd, target };
228
- const handled = (await taskCommand(cmd, env)) ?? (await preflightCommand(cmd, env));
265
+ const handled = (await taskCommand(cmd, env)) ?? (await taskReviewCommand(cmd, env)) ?? (await preflightCommand(cmd, env)) ?? (await requirementCommand(cmd, env)) ?? (await revisitCommand(cmd, env)) ?? (await retroCommand(cmd, env)) ?? (await metricsCommand(cmd, env));
229
266
  if (handled !== undefined)
230
267
  return handled;
231
268
  switch (cmd) {
@@ -242,13 +279,16 @@ async function main(argv) {
242
279
  // Preflight の担当(AI 向けの手順が読む。読めなければ runner: null と problem。agent と推測しない)
243
280
  const pf = runnerView(ctx.ws.project.preflight);
244
281
  const preflight = { runner: pf.runner, source: pf.source, ...(pf.problem ? { problem: pf.problem } : {}) };
245
- return out.result({ project: target.name ?? null, dataDir: target.dataDir, via: target.via, here: here.repos, branch: here.branch ?? null, actor, request: current ?? null, preflight }, () => [
282
+ // 置いた AI 向けの入口の状態(読むだけ。古くても操作は断らない)
283
+ const agents = diagnoseAgents(cwd);
284
+ return out.result({ project: target.name ?? null, dataDir: target.dataDir, via: target.via, here: here.repos, branch: here.branch ?? null, actor, request: current ?? null, preflight, agents }, () => [
246
285
  `プロジェクト ${target.name ?? "(未登録)"} ${target.dataDir}`,
247
286
  `決まり方 ${target.via}(${VIA_LABEL[target.via]})`,
248
287
  `今いる参照先 ${here.repos.length ? here.repos.join(", ") : "(どの参照先の中でもない。p3 repo ls)"}${here.branch ? ` ブランチ ${here.branch}` : ""}`,
249
288
  `変更者 ${actor}`,
250
289
  `要望 ${current ? `${current} ${titleOf(ctx, current)}` : "(なし)"}`,
251
290
  `Preflight ${runnerText(pf)}`,
291
+ ...agentsText(agents).map((l, i) => (i ? ` ${l}` : `AI の入口 ${l}`)),
252
292
  ].join("\n"));
253
293
  }
254
294
  case "progress": {
@@ -276,13 +316,15 @@ async function main(argv) {
276
316
  : "",
277
317
  p.request.tags.map((t) => `#${t}`).join(" "),
278
318
  // 子のある要望は配下の集計(自分の値とは別)、子は親を添える
279
- `${p.request.title}${p.children.length ? ` [配下 ${p.subtree.done}/${p.subtree.total}・子 ${p.children.length}]` : ""}${p.request.parent ? ` ↑${p.request.parent}` : ""}${p.hierarchyIssues.length ? " ※親子の問題" : ""}`,
319
+ `${p.request.title}${p.blocked ? ` ⏸停止 ${p.blocked}` : ""}${p.children.length ? ` [配下 ${p.subtree.done}/${p.subtree.total}・子 ${p.children.length}${p.subtree.blocked > p.blocked ? `・配下の停止 ${p.subtree.blocked - p.blocked}` : ""}]` : ""}${p.request.parent ? ` ↑${p.request.parent}` : ""}${p.hierarchyIssues.length ? " ※親子の問題" : ""}${reviewMark(p)}`,
280
320
  ]);
281
321
  return `${head}\n${table(rows)}`;
282
322
  })
283
323
  .join("\n\n") || "要望はありません");
284
324
  });
285
325
  }
326
+ case "quality":
327
+ return qualityCommand(env);
286
328
  case "milestone":
287
329
  case "milestones":
288
330
  return milestoneCommand(ctx, out, args, o, actor);
@@ -297,54 +339,92 @@ async function main(argv) {
297
339
  throw new UsageError(`不明なコマンド: ${cmd}(p3 help)`);
298
340
  }
299
341
  }
300
- main(process.argv.slice(2)).then((code) => process.exit(code), (e) => {
342
+ /**
343
+ * 標準出力・標準エラーを書き終えてから終わる。process.exit はパイプへの書き込みを待たないので、大きな出力(--json)を
344
+ * パイプで渡すと途中で切れることがある
345
+ */
346
+ function exit(code) {
347
+ let pending = 2;
348
+ const done = () => {
349
+ if (--pending === 0)
350
+ process.exit(code);
351
+ };
352
+ process.stdout.write("", done);
353
+ process.stderr.write("", done);
354
+ }
355
+ main(process.argv.slice(2)).then((code) => exit(code), (e) => {
301
356
  if (e instanceof ConflictError) {
302
357
  process.stderr.write(`競合: ${e.message}。最新を取得してやり直してください\n`);
303
- process.exit(3);
358
+ return exit(3);
304
359
  }
305
360
  if (e instanceof UserConfigError) {
306
361
  process.stderr.write(`${e.message}\n`);
307
- process.exit(1);
362
+ return exit(1);
308
363
  }
309
364
  if (e instanceof SettingsError) {
310
365
  process.stderr.write(`設定: ${e.message}\n`);
311
- process.exit(1);
366
+ return exit(1);
312
367
  }
313
368
  if (e instanceof ProjectNotResolvedError || e instanceof DataDirError) {
314
369
  process.stderr.write(`${e.message}\n`);
315
- process.exit(1);
370
+ return exit(1);
316
371
  }
317
372
  // リリースノート: 無い → 2、版の競合・既にある → 3、読めない・ID が使えない → 1
318
373
  if (e instanceof ReleaseNoteError) {
319
374
  process.stderr.write(`${e.code === "conflict" ? "競合: " : ""}${e.message}\n`);
320
- process.exit(e.code === "not_found" ? 2 : e.code === "conflict" || e.code === "exists" ? 3 : 1);
375
+ return exit(e.code === "not_found" ? 2 : e.code === "conflict" || e.code === "exists" ? 3 : 1);
376
+ }
377
+ // 指標: 版の競合 → 3、規則に合わない・読めない → 1(何も書いていない)
378
+ if (e instanceof MetricsError) {
379
+ process.stderr.write(`${e.code === "metrics_conflict" ? "競合: " : ""}${e.message}\n`);
380
+ return exit(e.code === "metrics_conflict" ? 3 : 1);
381
+ }
382
+ // 振り返り: 版の競合 → 3、規則に合わない・読めない → 1(何も書いていない)
383
+ if (e instanceof RetrospectiveError) {
384
+ process.stderr.write(`${e.code === "retro_conflict" ? "競合: " : ""}${e.message}\n`);
385
+ return exit(e.code === "retro_conflict" ? 3 : 1);
321
386
  }
322
387
  // 生成を始められない(材料が無い・上限・実行中)。Codex は呼んでいない
323
388
  if (e instanceof GenerationRejected) {
324
389
  process.stderr.write(`${e.message}\n`);
325
- process.exit(1);
390
+ return exit(1);
326
391
  }
327
392
  // 要望の親子: ロックを取れない・子の表示順を読んだ後に子の集合が変わった → 3(読み直してやり直す)、規則に合わない → 1
328
393
  if (e instanceof HierarchyError) {
329
394
  process.stderr.write(`${e.message}\n`);
330
395
  const changedSet = e.code === "child_order_invalid" && (e.detail.reason === "not_child" || e.detail.reason === "missing");
331
- process.exit(e.code === "hierarchy_busy" || changedSet ? 3 : 1);
396
+ return exit(e.code === "hierarchy_busy" || changedSet ? 3 : 1);
332
397
  }
333
398
  // マイルストーンレビュー: 無い → 2、実行中・終わっている・動いている所有者がいる → 3、ほか(目的が無い・上限・ID・読めない)→ 1
334
399
  if (e instanceof ReviewRejected || e instanceof ReviewStoreError || e instanceof ReviewCancelRefused) {
335
400
  process.stderr.write(`${e.message}\n`);
336
401
  const code = e.code;
337
- process.exit(code === "not_found" || code === "unknown_milestone" ? 2 : code === "running" || code === "finished" || code === "owner_alive" || code === "exists" ? 3 : 1);
402
+ return exit(code === "not_found" || code === "unknown_milestone" ? 2 : code === "running" || code === "finished" || code === "owner_alive" || code === "exists" ? 3 : 1);
403
+ }
404
+ // タスクのレビュー: 実行中・材料が変わった → 3、ほか(未完了・比較対象・観点・上限・担当)→ 1
405
+ if (e instanceof TaskReviewRejected) {
406
+ process.stderr.write(`${e.message}\n`);
407
+ return exit(e.code === "running" || e.code === "material_changed" ? 3 : 1);
408
+ }
409
+ // 改善要望: 診断が変わった・登録先がある → 3、無い → 2、ほか → 1
410
+ if (e instanceof ImprovementError) {
411
+ process.stderr.write(`${e.message}\n`);
412
+ return exit(e.code === "not_found" ? 2 : e.code === "diagnosis_changed" || e.code === "existing" || e.code === "closed_existing" ? 3 : 1);
413
+ }
414
+ // 品質基準: 版が違う → 3、規則に合わない・読めない → 1
415
+ if (e instanceof QualityInputError) {
416
+ process.stderr.write(`${e.message}\n`);
417
+ return exit(e.code === "quality_conflict" ? 3 : 1);
338
418
  }
339
419
  // マイルストーンの版が違う(読んだ後に他で変わった)→ 3。何も書いていない
340
420
  if (e instanceof MilestonesConflictError) {
341
421
  process.stderr.write(`競合: ${e.message}\n`);
342
- process.exit(3);
422
+ return exit(3);
343
423
  }
344
424
  if (e instanceof NotFoundError) {
345
425
  process.stderr.write(`見つかりません: ${e.id}\n`);
346
- process.exit(2);
426
+ return exit(2);
347
427
  }
348
- process.stderr.write(`${e instanceof UsageError || e instanceof OpRuleError || e instanceof ProjectInputError ? "" : "エラー: "}${e.message}\n`);
349
- process.exit(1);
428
+ process.stderr.write(`${e instanceof UsageError || e instanceof OpRuleError || e instanceof ProjectInputError || e instanceof AcceptanceInputError || e instanceof RequirementInputError || e instanceof PremiseInputError || e instanceof BlockInputError ? "" : "エラー: "}${e.message}\n`);
429
+ return exit(1);
350
430
  });
@@ -0,0 +1,77 @@
1
+ import { metricScopeOf, metricsReport } from "../core/metrics/index.js";
2
+ import { readManual, recordManual, removeManual } from "../core/metrics/manual.js";
3
+ import { MetricsError, METRIC_STATE_LABEL, METRIC_UNIT_LABEL } from "../shared/metrics.js";
4
+ import { UsageError } from "./project.js";
5
+ /**
6
+ * 開発の指標(定義は core/metrics/definitions.ts)。読むだけ。
7
+ *
8
+ * metrics [--milestone <ID>] プロジェクト全体(既定)か、登録済みのマイルストーンの指標(値・単位・対象・欠損・算出の方法)
9
+ * metrics record <指標> <値> --from YYYY-MM-DD --to YYYY-MM-DD --source 出典 [--unit 通貨] [--milestone ID] [--note メモ] [--rev 版]
10
+ * 人が記録する値(費用・リリース後の不具合)。同じ内容の再送は何もしない。訂正は --rev
11
+ * metrics records 人の記録の全部(範囲を問わない)
12
+ * metrics rm <M1> [--rev 版] 人の記録を消す
13
+ */
14
+ const rowText = (r) => `${r.id} ${r.from}〜${r.to} ${r.value} ${r.unit} 出典: ${r.source}${r.note ? ` メモ: ${r.note}` : ""} (版 ${r.rev}・${r.updatedAt}${r.updatedBy ? `・${r.updatedBy}` : ""})`;
15
+ const recordText = (r) => `${r.metric} ${r.scope === "project" ? "プロジェクト全体" : r.scope} ${rowText(r)}`;
16
+ const valueText = (m) => {
17
+ if (m.rows?.length)
18
+ return m.rows.length === 1 ? `${m.rows[0].value} ${m.rows[0].unit}` : `${m.rows.length} 行(期間・単位ごと。合算しない)`;
19
+ if (m.value === null)
20
+ return METRIC_STATE_LABEL[m.state];
21
+ const v = `${m.value} ${METRIC_UNIT_LABEL[m.unit]}`;
22
+ return m.denominator !== undefined ? `${v} / 基準 ${m.denominator} 件` : v;
23
+ };
24
+ export function formatMetrics(r) {
25
+ const lines = [`開発の指標 範囲: ${r.scopeLabel}`, ` ${r.scopeRule}`, " (改善の材料です。人や AI の成績の評価には使いません)", ""];
26
+ for (const m of r.metrics) {
27
+ lines.push(`${m.label} [${m.id}] ${valueText(m)}${m.kind === "manual" ? " (人の記録)" : ""}`);
28
+ if (m.kind === "manual") {
29
+ for (const r of m.rows ?? [])
30
+ lines.push(` ${rowText(r)}`);
31
+ if (m.recordHint)
32
+ lines.push(` 記録: ${m.recordHint}`);
33
+ }
34
+ else {
35
+ lines.push(` 対象 ${m.targets}・値に入れた ${m.observed}・欠損 ${m.missing}`);
36
+ lines.push(` 内訳: ${m.breakdown.map((b) => `${b.label} ${b.count}`).join("・")}`);
37
+ }
38
+ lines.push(` 算出: ${m.method}`);
39
+ for (const x of m.missingItems.slice(0, 5))
40
+ lines.push(` 欠損: ${x.target} ${x.reason}`);
41
+ if (m.missingItems.length > 5)
42
+ lines.push(` 欠損: ほか ${m.missingItems.length - 5} 件(--json で全部)`);
43
+ }
44
+ if (r.notices.length)
45
+ lines.push("", "知らせ:", ...r.notices.map((n) => ` ${n.target} ${n.message}`));
46
+ lines.push("", `範囲: ${r.scopes.map((s) => (s.scope.kind === "project" ? "(省略)プロジェクト全体" : `--milestone ${s.scope.id}`)).join(" / ")}`);
47
+ return lines.join("\n");
48
+ }
49
+ export async function metricsCommand(cmd, env) {
50
+ if (cmd !== "metrics")
51
+ return undefined;
52
+ const { ctx, out, args, o, actor, expectedRev } = env;
53
+ const sub = args[0];
54
+ if (sub === "record") {
55
+ const [, metric, value] = args;
56
+ if (!metric || value === undefined || args.length > 3)
57
+ throw new UsageError("p3 metrics record <指標> <値> --from YYYY-MM-DD --to YYYY-MM-DD --source 出典 [--unit 通貨] [--milestone ID] [--note メモ] [--rev 版]");
58
+ const r = await recordManual(ctx, { metric, value, scope: o.milestone, from: o.from ?? "", to: o.to ?? "", unit: o.unit, source: o.source ?? "", note: o.note }, { expectedRev, actor });
59
+ return out.result(r, () => `${r.created ? "記録しました" : r.changed ? "訂正しました" : "同じ内容の記録があります(変えていません)"}\n ${recordText(r.record)}`);
60
+ }
61
+ if (sub === "records") {
62
+ const m = await readManual(ctx.ws.dataDir);
63
+ if (m.problem)
64
+ throw new MetricsError(m.problem, "metrics_unreadable");
65
+ return out.result({ records: m.records }, () => (m.records.length ? m.records.map(recordText).join("\n") : "人の記録はありません(p3 metrics record で記録します)"));
66
+ }
67
+ if (sub === "rm" || sub === "remove") {
68
+ if (!args[1] || args.length > 2)
69
+ throw new UsageError("p3 metrics rm <M1> [--rev 版]");
70
+ const r = await removeManual(ctx, args[1], { expectedRev });
71
+ return out.result({ removed: r }, () => `消しました: ${recordText(r)}`);
72
+ }
73
+ if (args.length)
74
+ throw new UsageError(`p3 metrics [--milestone <ID>] | record <指標> <値> ... | records | rm <M1>(知らない引数: ${args.join(" ")})`);
75
+ const r = await metricsReport(ctx, metricScopeOf(ctx, o.milestone));
76
+ return out.result(r, () => formatMetrics(r));
77
+ }
package/lib/cli/output.js CHANGED
@@ -1,9 +1,11 @@
1
+ import { requestRequirementView } from "../shared/requirementSource.js";
1
2
  import { absRef } from "../shared/refs.js";
2
3
  import { relationRole } from "../shared/types.js";
3
4
  import {} from "../core/context.js";
4
5
  import { resolve, titleOf } from "../core/ops.js";
5
6
  import {} from "../core/supersede.js";
6
7
  import { table } from "./format.js";
8
+ import { formatAcceptance, formatBlock, formatCompletionDetail, formatRequirement, formatRework } from "./showView.js";
7
9
  import { taskWork } from "../core/workTargets.js";
8
10
  import { DIRECT_TASK_NOTE, LATER_PREFLIGHT_NOTE } from "../shared/directTask.js";
9
11
  /** CLI の出力(人向けの表と --json)と、表示の部品 */
@@ -26,7 +28,7 @@ export function formatEntity(ctx, item, file) {
26
28
  const lines = [`${head} ${item.title}`, ""];
27
29
  if ("ref" in item)
28
30
  lines.push(` ${"作業先".padEnd(11)} ${workHint(ctx, item).replace(/^作業先: /, "")}`);
29
- const skip = new Set(["id", "ref", "request", "title", "body", "relations", "repo", "record"]);
31
+ const skip = new Set(["id", "ref", "request", "title", "body", "relations", "repo", "record", "acceptanceCriteria", "acceptanceEvidence", "acceptanceSeq", "acceptanceSources", "acceptanceProblems", "block", "blockHistory", "blockProblems", "requirementSources", "requirementSeq", "clarifyAnswers", "requirementProblems", "completionRecords", "completionProblems", "reworkHistory", "reworkProblems"]);
30
32
  for (const [k, v] of Object.entries(item)) {
31
33
  if (skip.has(k) || v === undefined || (Array.isArray(v) && !v.length))
32
34
  continue;
@@ -36,6 +38,22 @@ export function formatEntity(ctx, item, file) {
36
38
  lines.push("", indent(item.body.trim()));
37
39
  if ("record" in item && item.record)
38
40
  lines.push("", "変更の記録:", indent(item.record));
41
+ if ("ref" in item) {
42
+ const blk = formatBlock(item, { history: true });
43
+ if (blk.length)
44
+ lines.push("", ...blk);
45
+ }
46
+ if ("ref" in item)
47
+ lines.push("", ...formatAcceptance(item));
48
+ if (!("ref" in item)) {
49
+ const req = requestRequirementView(item);
50
+ if (req.sources.length || req.answers.length || req.problems.length)
51
+ lines.push("", ...formatRequirement(req));
52
+ }
53
+ if ("ref" in item && (item.reworkHistory?.length || item.reworkProblems?.length))
54
+ lines.push("", ...formatRework(item));
55
+ if (item.completionRecords?.length || item.completionProblems?.length)
56
+ lines.push("", ...formatCompletionDetail(item));
39
57
  if ("ref" in item) {
40
58
  const out = item.relations.map((r) => ` → ${pad(relationRole(r.type, "out"))} ${r.target} ${titleOf(ctx, `${home}/${r.target}`)}`);
41
59
  const inc = [
@@ -303,7 +303,7 @@ function inputMatchLine(rid, run, m) {
303
303
  }
304
304
  return `\n※ ${staleMessage(rid, run.id, m)}`;
305
305
  }
306
- async function pickRun(ctx, rid, runId) {
306
+ export async function pickRun(ctx, rid, runId) {
307
307
  const runs = await ctx.preflight.list(rid);
308
308
  const run = runId ? runs.find((r) => r.id === runId) : runs[0];
309
309
  if (!run)
@@ -348,6 +348,12 @@ function formatRun(ctx, rid, run) {
348
348
  d.title,
349
349
  d.dependsOn.length ? `← ${d.dependsOn.join(",")}` : "",
350
350
  ])));
351
+ // 受け入れ基準(タスク化の前に p3 criteria <D> で直せる)
352
+ for (const d of run.drafts) {
353
+ if (!d.acceptanceCriteria?.length && !d.acceptanceProblems?.length)
354
+ continue;
355
+ lines.push(` ${d.key} の受け入れ基準:`, ...(d.acceptanceCriteria ?? []).map((c) => ` ${c.id} ${c.text}`), ...(d.acceptanceProblems ?? []).map((p) => ` ※読めない: ${p}`));
356
+ }
351
357
  lines.push("", `ファイル: ${relative(process.cwd(), join(ctx.ws.preflight.runDir(rid, run.id), "drafts"))}/`);
352
358
  }
353
359
  if (a?.split) {
@@ -15,6 +15,7 @@ import { normalizeProject } from "../core/store/normalize.js";
15
15
  import { requestWorkstreams } from "../shared/workTarget.js";
16
16
  import { DEFAULT_PREFLIGHT_RUNNER, isPreflightRunner, PREFLIGHT_RUNNERS, RUNNER_LABEL, runnerView } from "../shared/preflightRunner.js";
17
17
  import { DATA_DIR_NAME } from "../core/store/locate.js";
18
+ import { ENTRY_VERSION } from "./guide.js";
18
19
  import { sortMilestones } from "../shared/milestoneOrder.js";
19
20
  import { loadUserConfig, PROJECT_NAME, setProjectNode, updateUserConfig, userConfigPath } from "../core/userConfig.js";
20
21
  /** プロジェクトの初期設定・設定変更、変更者と「今の要望」の判定(CLI) */
@@ -108,7 +109,7 @@ export function currentRequest(ctx, explicit, cwd) {
108
109
  /** init で本体の主なフォルダ(最初に読むもの)の候補にするドキュメントと、フォルダの入口の候補 */
109
110
  const DOC_CANDIDATES = ["docs", "doc", "README.md", "ARCHITECTURE.md", "DESIGN.md", "AGENTS.md", "CLAUDE.md", "CONTRIBUTING.md"];
110
111
  const DOC_ENTRIES = ["README.md", "index.md"];
111
- const AGENTS_MARK = "タスク管理(infodb p3)";
112
+ export const AGENTS_MARK = "タスク管理(infodb p3)";
112
113
  /** AI 向けの使い方を置く先(リポジトリのルートからの相対パス。どれも同じ原本 skills/p3/SKILL.md を写す) */
113
114
  export const AGENT_TARGETS = {
114
115
  claude: { path: ".claude/skills/p3/SKILL.md", agent: "Claude Code" },
@@ -117,10 +118,12 @@ export const AGENT_TARGETS = {
117
118
  /** --agents / p3 agents の選び方(値なしの --agents は both) */
118
119
  export const AGENT_CHOICES = { claude: ["claude"], codex: ["codex"], both: ["claude", "codex"] };
119
120
  export const isAgentChoice = (v) => typeof v === "string" && Object.hasOwn(AGENT_CHOICES, v);
120
- const KINDS = Object.keys(AGENT_TARGETS);
121
+ export const KINDS = Object.keys(AGENT_TARGETS);
122
+ /** 節の入口の版を書く機械可読のコメント(ENTRY_VERSION。見出しの次の行) */
123
+ export const ENTRY_COMMENT = (v) => `<!-- p3-entry-version: ${v} -->`;
121
124
  /**
122
- * AGENTS.md / CLAUDE.md に書く指示(節)。スキルの参照は、置いた先(と既にある先)だけを書く。手順の詳しい版は同梱のスキル
123
- * (skills/p3/SKILL.md)で、役割と終わり方はそちらとそろえる(test/agents.test.ts が確かめる)
125
+ * AGENTS.md / CLAUDE.md に書く指示(節)。入口だけで、手順の本文は CLI(p3 guide)から読ませる。
126
+ * スキルの参照は、置いた先(と既にある先)だけを書く。入口の決まりを変えたら ENTRY_VERSION を上げる(test/agents.test.ts が確かめる)
124
127
  */
125
128
  export function agentsSnippet(kinds) {
126
129
  const list = KINDS.filter((k) => kinds.includes(k));
@@ -128,25 +131,11 @@ export function agentsSnippet(kinds) {
128
131
  return `
129
132
  ## ${AGENTS_MARK}
130
133
 
131
- - 作業の単位は要望。タスクは \`p3\` CLI(入っていなければ \`pnpx @infodb/p3\`)で操作し、\`--json\` で結果を読むこと(データのフォルダを直接編集しない)。
132
- 詳しい手順はスキル ${skills}
133
- - 変更するときは環境変数 \`P3_ACTOR=ai:<エージェント名>\` を付ける
134
- - 操作する要望は \`--req <要望ID>\` で指定する(要望の作業ツリーの中なら省ける)。まず \`p3 whoami --json\` で確かめる(Preflight の担当 \`preflight.runner\` も出る)
135
- - \`whoami\` の \`via\`(プロジェクトの決まり方)が \`cwd\` でなければ(\`dir\` / \`project\` / \`legacy\` / \`only\`)、それ以上 p3 を操作せず、対象のプロジェクトでよいか人に確かめる(推測した \`--project\` / \`--dir\` で避けない。人が指定・確認した後はその対象のまま続ける)
136
- - プロジェクトが無い・未登録のときは \`p3 init\` / \`p3 join\` を自分から実行せず、新しく作る(\`init\`)のか共有されたものに参加する(\`join\`)のかを人に確かめる
137
- - 新しい作業を頼まれたら \`p3 request new "<タイトル>" --body "..."\` で要望を登録し、ID を伝えて終える。
138
- Preflight(\`preflight\`)は自分から始めない(勧めない・尋ねない)。タスク化(\`accept\`)は人が行う(結果を \`p3 drafts\` で読むのと、頼まれたメモの保存 \`--note-only\` はよい)
139
- - Preflight を頼まれたら、担当(\`whoami --json\` の \`preflight.runner\`)で分ける。\`codex\`: 人が \`p3 preflight\` か画面で実行する(AI は \`--prepare\` の無い \`p3 preflight\` をしない)。人がチャットで対象の要望の手元の評価を明示的に頼んだときだけ手元で評価し、「Preflight して」とだけなら、人が実行するのか手元で評価するのかを確かめる。\`agent\`: 人に「Preflight して」と頼まれたら手元で評価する(「このチャットで」は求めない)。\`null\`(読めない): \`agent\` と推測せず \`problem\` を伝え、\`codex\` と同じ扱い。子の要望も同じ。対象の要望が分からなければ確かめる
140
- - 手元の評価: \`p3 preflight <要望ID> --prepare --json\` → 返った指示のファイル(\`instructions\`)を最後まで読み、書くのは返った run の成果物(\`outputs\`)だけ → \`p3 preflight <要望ID> --complete --run <run> --json\` → \`p3 drafts\` の結果を伝えて終える(自分から始めない。タスク化 \`accept\` と着手はしない)
141
- - 着手する前に \`p3 show T003 --brief --json\` で本文・依存とその状態(\`dependencies\`)・置き換えの注意(\`warnings\`)を読む
142
- - 着手する前に、\`--brief --json\` の \`work\`(作業先のリポジトリとブランチ)を見て、そのリポジトリでブランチに入る(作業先なしなら移動しない)
143
- - 着手するときは \`p3 move T003 doing\`。テストを通したら、コミットする前に \`p3 move T003 done --output <今ある成果物(変えたファイルや説明)> --record -\` で完了にする(変更の記録は必須: 何を変えたか・なぜ・入れた決まり・やめたもの を標準入力から Markdown で。まだ無い URL は書かない)
144
- - 要望のタスクを全部終えたら、コミットする前に \`p3 request set <要望ID> status=resolved\`(対応済)にする。完了済(done)・見送り(rejected)とタスクの済み(check)は人が決める
145
- - 子の要望(\`parent\` のある要望)は、親とは別の要望として子ごとのタスクとブランチで作業する(親のタスクにしない)。分割の案の採用(\`accept\`)は人が行う。子の Preflight は親と同じ担当で、頼まれたときだけ(分割の採用・子の作成から自分で評価へ進まない)。親を対応済にするのは、親のタスクと見送り以外の子(\`request show <親> --brief --json\` の \`children\`)が全部終わってから
146
- - データのフォルダがこの作業ツリーの中で git 管理されているなら、要望のフォルダ(\`requests/<要望ID>/\`)の変更も実装と同じコミットに入れる(後のレビューで要望とやったことを精査するため。子なら祖先の要望のフォルダ、親を対応済にするときは子孫の要望のフォルダ(見送りの子など)のまだ入っていない変更も入れ、ほかの要望・関係ない変更は入れない。外・無視・worktree のときは入らないので、移動や \`git add -f\` はしない)。push に失敗したら完了の記録は残し、公開できていないことを伝える。要望のフォルダは、マージするまで要望のブランチにしか無い。既定のブランチに切り替えると、その要望(子なら親の子の一覧からも)が消えたように見えるが、データはブランチにある(作り直したり、別のブランチから写したりしない)
147
- - コミットや PR の URL は後から \`p3 move T003 done --output <URL>\` で足す(完了・記録はそのまま。データをコミットしているなら追記もコミットして push)。複数のリポジトリにまたがるときは最後のタスクに \`--repo-output <参照先>=<PR の URL>\` で全部の PR を残す
148
- - 置き換えられたタスク(\`p3 ls\` の \`※置換\`、\`--json\` の \`superseded\`)からは始めない。\`move\` が \`warnings\` を返したら止めて人に確かめる
149
- - 作業中に新しく必要になった作業は \`p3 new "<タイトル>" --body "..."\` でタスクにする(人への質問はタスクにしない)
134
+ ${ENTRY_COMMENT(ENTRY_VERSION)}
135
+
136
+ - このリポジトリの作業は infodb p3 の要望とタスクで管理する。p3 を操作する前に \`pnpx @infodb/p3 guide --json\` を実行し、返った \`guide\`(作業の手順)を最後まで読んで従う(手順は動いている CLI の版のものが返る。ここには写さない)
137
+ - \`guide\` を取得できなければ(コマンドが無い・エラーになる・JSON が読めない)、p3 を操作しない。出たエラーと呼び方(\`pnpx @infodb/p3 guide --json\`)を人に伝えて終える
138
+ - 同じ入口のスキル: ${skills}
150
139
  `;
151
140
  }
152
141
  /** 両方に置いたときの節(docs/architecture.md に載せる例。test/agents.test.ts が同じことを確かめる) */
@@ -165,7 +154,7 @@ function firstDiffLine(a, b) {
165
154
  return i + 1;
166
155
  }
167
156
  /** 指示の節(見出し「タスク管理(infodb p3)」からその見出しと同じか上の段の次の見出しの前まで。コードの囲みの中は見出しに数えない) */
168
- function findSections(text) {
157
+ export function findSections(text) {
169
158
  const lines = text.split("\n");
170
159
  const heads = [];
171
160
  let fence = false;