@infodb/p3 0.12.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 (113) hide show
  1. package/README.md +32 -35
  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-Pu6EISAM.js → quality-RFd-7k3r.js} +1 -1
  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/ui-BGK72r3u.js +1 -0
  28. package/dist/web/assets/workTarget-CySfKyfB.js +30 -0
  29. package/dist/web/index.html +4 -4
  30. package/docs/architecture.md +300 -36
  31. package/docs/development.md +60 -16
  32. package/docs/how-to-use.md +381 -28
  33. package/docs/installation.md +235 -144
  34. package/docs/publishing.md +1 -1
  35. package/lib/cli/agentsStatus.js +197 -0
  36. package/lib/cli/args.js +72 -8
  37. package/lib/cli/guide.js +27 -0
  38. package/lib/cli/guide.md +214 -0
  39. package/lib/cli/help.js +44 -6
  40. package/lib/cli/main.js +76 -20
  41. package/lib/cli/metricsCommands.js +77 -0
  42. package/lib/cli/output.js +12 -2
  43. package/lib/cli/project.js +13 -27
  44. package/lib/cli/qualityCommands.js +33 -8
  45. package/lib/cli/readOnly.js +15 -0
  46. package/lib/cli/requestCommands.js +21 -4
  47. package/lib/cli/requirementCommands.js +288 -0
  48. package/lib/cli/retroCommands.js +106 -0
  49. package/lib/cli/revisitCommands.js +73 -0
  50. package/lib/cli/showView.js +119 -6
  51. package/lib/cli/taskCommands.js +42 -16
  52. package/lib/cli/userConfig.js +47 -0
  53. package/lib/core/completionRefs.js +46 -0
  54. package/lib/core/metrics/definitions.js +434 -0
  55. package/lib/core/metrics/index.js +88 -0
  56. package/lib/core/metrics/manual.js +180 -0
  57. package/lib/core/ops.js +15 -2
  58. package/lib/core/preflight/carryover.js +5 -1
  59. package/lib/core/preflight/codexEngine.js +34 -17
  60. package/lib/core/preflight/diagnose.js +4 -9
  61. package/lib/core/preflight/engine.js +9 -0
  62. package/lib/core/preflight/hostPaths.js +260 -0
  63. package/lib/core/preflight/input.js +33 -5
  64. package/lib/core/preflight/instructions.js +18 -1
  65. package/lib/core/preflight/mockEngine.js +20 -2
  66. package/lib/core/preflight/render.js +22 -3
  67. package/lib/core/preflight/service.js +59 -9
  68. package/lib/core/preflight/uiRender.js +3 -0
  69. package/lib/core/requestOps.js +206 -14
  70. package/lib/core/retrospective.js +208 -0
  71. package/lib/core/reviewCandidates.js +56 -0
  72. package/lib/core/store/collection.js +20 -1
  73. package/lib/core/store/normalize.js +22 -4
  74. package/lib/core/store/preflightStore.js +19 -5
  75. package/lib/core/store/workspace.js +17 -1
  76. package/lib/core/taskReview/material.js +7 -0
  77. package/lib/core/taskReview/review.js +9 -2
  78. package/lib/server/api/manifest.js +51 -3
  79. package/lib/server/api/routes.js +131 -11
  80. package/lib/shared/acceptance.js +258 -18
  81. package/lib/shared/completionRecord.js +327 -0
  82. package/lib/shared/metrics.js +42 -0
  83. package/lib/shared/preflightInput.js +1 -1
  84. package/lib/shared/requirementSource.js +635 -0
  85. package/lib/shared/retrospective.js +286 -0
  86. package/lib/shared/reviewCandidate.js +308 -0
  87. package/lib/shared/reworkHistory.js +81 -0
  88. package/package.json +3 -2
  89. package/skills/p3/SKILL.md +9 -181
  90. package/dist/web/assets/ImprovementDialog-kQaVBGWH.js +0 -1
  91. package/dist/web/assets/Outputs-_nU_p3nu.js +0 -1
  92. package/dist/web/assets/RequestStatus-RG-OVQYY.js +0 -1
  93. package/dist/web/assets/Tabs-ew9i5SKX.js +0 -1
  94. package/dist/web/assets/TagInput-BtlJTF7i.js +0 -1
  95. package/dist/web/assets/TaskDrawer-DW8GyJqI.js +0 -6
  96. package/dist/web/assets/_requestId-6Nb727dD.js +0 -1
  97. package/dist/web/assets/_requestId-BykTgPax.js +0 -1
  98. package/dist/web/assets/appCtx-CxDdXABS.js +0 -1
  99. package/dist/web/assets/archive-Ckh295Xe.js +0 -1
  100. package/dist/web/assets/board-BVAIjK-Y.js +0 -1
  101. package/dist/web/assets/done-BGfA-3MA.js +0 -1
  102. package/dist/web/assets/draft-CfJeyLOl.js +0 -1
  103. package/dist/web/assets/index-CgRU744I.css +0 -2
  104. package/dist/web/assets/index-DacQ0yl4.js +0 -12
  105. package/dist/web/assets/new-DVygWvVc.js +0 -1
  106. package/dist/web/assets/outputs-B6xDsLZf.js +0 -1
  107. package/dist/web/assets/preflightInput-BAeEJYUK.js +0 -2
  108. package/dist/web/assets/preload-helper-DyCqp21K.js +0 -1
  109. package/dist/web/assets/release-notes-CCpzyiNf.js +0 -5
  110. package/dist/web/assets/requestData-D5vBnuMh.js +0 -1
  111. package/dist/web/assets/routes-Q91zvNc0.js +0 -4
  112. package/dist/web/assets/settings-BzRgcmUm.js +0 -1
  113. package/dist/web/assets/workTarget-C9c57JAO.js +0 -30
@@ -1,7 +1,8 @@
1
1
  # 使い方ガイド
2
2
 
3
3
  P3 で要望を1件、作るところから人が確認して閉じるところまで進める手順と、その後に引くためのリファレンス。
4
- 導入(Docker・ChatGPT の接続・パスの対応)が済んでいる前提で書く。まだなら [導入ガイド](installation.md) から。
4
+ プロジェクトに参加して画面を開くところ([導入ガイド](installation.md) の段階 0)が済んでいる前提で書く。Preflight(2.〜4.)を使うには
5
+ [段階 1](installation.md#段階-1-preflight-を足す) の準備も要る(まだなら [Preflight を通さずにタスクを作る](#preflight-を通さずにタスクを作る) で進められる)。
5
6
 
6
7
  - 前半「1件の要望を最後まで」: 同じ例の要望で、順に手を動かす
7
8
  - 後半「リファレンス」: 状態・データ・画面・CLI の決まり
@@ -117,6 +118,19 @@ p3 notes k7m3x # メモの一覧
117
118
 
118
119
  画面では評価の下のメモ欄に書いて「保存して再実行」。要望の本文そのものを直してもよい(後の「要望の本文を変えたとき」)。
119
120
 
121
+ 評価が ID のある確認事項(Q1, Q2 ...。確認先・質問・必要な根拠・判断への影響)を出したときは、確認事項ごとに **回答** を要望に残せる。
122
+ 回答は元の評価の確認事項との組のまま次の Preflight に渡る(過去の評価は書き換えない)。回答を保存しても評価は自動で始まらないので、
123
+ 保存した後に明示して再評価する。
124
+
125
+ ```bash
126
+ p3 clarify k7m3x # 確認事項と回答の状態(未回答・回答済み・再確認が必要・参照元不明)
127
+ p3 answer k7m3x Q1 --body "税は切り捨て" --by 経理担当 --on 2026-11-10 --source "経理規程 3.2"
128
+ p3 preflight k7m3x # 回答を保存した内容で再評価
129
+ ```
130
+
131
+ ID の無い以前の評価の確認事項には、これまでどおりメモで答える。業務上の正解(計算式・規則・契約など)の出典と根拠を残したいときは、
132
+ 後の「要求の出典と確認」。
133
+
120
134
  ### 5. 案を選んでタスクにする
121
135
 
122
136
  ```bash
@@ -169,7 +183,7 @@ git add .p3/requests/261009-k7m3x && git commit -m "成果物の URL" && git pus
169
183
  - データのフォルダがリポジトリの外・別のリポジトリ・git で無視されているときは、同じコミットには入らない。git の作業ツリー
170
184
  (worktree)で作業していても、データは登録したフォルダ(既定はメインの作業ツリーの `.p3`)に書かれ、その作業ツリーのコミットには
171
185
  入らない。どちらもデータを移したり写したり `git add -f` したりせず、コードとは成果物の URL で結ぶ
172
- - push に失敗しても、完了の記録はそのまま。公開できていないだけなので、直して push し直す
186
+ - push に失敗しても、完了にしたことと記録はそのまま。公開できていないだけなので、直して push し直す
173
187
 
174
188
  - 依存の相手が終わっていないタスクや、置き換えられたタスク(`※置換`)からは始めない
175
189
  - **変更の記録**(`--record`)は、何を変えたか・なぜ・入れた決まり・やめたものを Markdown で短く書く。AI が完了にするときは必須。
@@ -252,7 +266,7 @@ p3 request set k7m3x status=done # 要望を完了済にする(
252
266
  #### Preflight の担当
253
267
 
254
268
  誰が Preflight を実行するかを、プロジェクトで1つ決める(`project.yaml` の `preflight.runner`。`p3 init` で尋ね、Enter・`--yes` は
255
- `codex`)。AI エージェント向けの使い方(スキルと AGENTS.md の節)は `p3 whoami --json` の `preflight.runner` を読んで手順を選ぶ。
269
+ `codex`)。AI エージェント向けの手順(`p3 guide`)は `p3 whoami --json` の `preflight.runner` を読んで分け方を選ぶ。
256
270
 
257
271
  | 担当 | 向いている環境 | Preflight の実行 |
258
272
  | --- | --- | --- |
@@ -385,7 +399,7 @@ p3 accept k7m3x # 人がタスク化
385
399
  - 手元のエージェントにはコンテナの囲いが無い。参照先を読むだけにすること・書き込みを run の成果物に限ることは指示で伝えるだけで、
386
400
  P3 は止められない(エージェントの権限の設定で守る)。どの程度の利用枠を使うかはエージェント側の契約による
387
401
 
388
- **Claude Code のチャットで頼む**: 上の手順は、同梱のスキル(`.claude/skills/p3/SKILL.md`。後の「AI エージェントから使う」)に書いてある。
402
+ **Claude Code のチャットで頼む**: 上の手順は、CLI が返す作業の手順(`p3 guide`。置いたスキル `.claude/skills/p3/SKILL.md` が読ませる入口。後の「AI エージェントから使う」)に書いてある。
389
403
  頼み方はプロジェクトの Preflight の担当(上の「Preflight の担当」)で変わる。エージェントは `p3 whoami --json` で担当を読む。
390
404
 
391
405
  ```text
@@ -398,19 +412,17 @@ p3 accept k7m3x # 人がタスク化
398
412
 
399
413
  - どちらの担当でも、エージェントは評価を取り込んで `p3 drafts` の要約を伝えたところで止まる。タスク化(`accept`)と着手は人が案を
400
414
  確かめてから。要望の登録やタスクの作業のついでに、エージェントから Preflight を始めたり勧めたりはしない。子の要望も同じ
401
- - 担当を変えても、置いたスキルと AGENTS.md の節は置き直さなくてよい(実行のたびに `whoami` で読む)。以前の版のスキルを置いている
402
- リポジトリは、`p3 agents claude|codex|both` で同梱の版との違いを確かめ、最新にするなら選んだ先だけ `--force` で置き換える
403
- (ほかの文は残す。後の「AI エージェントから使う」)
415
+ - 担当を変えても、置いたスキルと AGENTS.md の節は置き直さなくてよい(実行のたびに `whoami` で読む)。以前の版(手順の全文の写し)を
416
+ 置いているリポジトリは、`whoami` の「AI の入口」に古いと出るので、後の「AI エージェントから使う」の移り方で入口に置き換える
404
417
 
405
- - Claude Code はスキルに従って `--prepare` → 指示のファイルを読んで評価し、成果物を書く → `--complete` → `p3 drafts` の要約を返す、
418
+ - Claude Code は手順(`p3 guide`)に従って `--prepare` → 指示のファイルを読んで評価し、成果物を書く → `--complete` → `p3 drafts` の要約を返す、
406
419
  までを同じチャットで行う。タスク化(`accept`)とタスクの着手はしない(人が `p3 drafts` か画面で案を確かめてから `p3 accept`)。
407
420
  明示の依頼が無ければ(要望の登録だけなど)Preflight は始めない
408
421
  - 要るもの: `p3` の CLI を実行できること(Bash)、データのフォルダと参照先を読めること、run のフォルダに書けること。データのフォルダや
409
422
  参照先がリポジトリの外にあるなら、Claude Code に読む場所として足す(`/add-dir <フォルダ>`・起動時の `--add-dir`・設定の
410
423
  `permissions.additionalDirectories`)。足さなければ、外のファイルを読む・書くたびに許可を求められる。参照先に書かせない設定
411
424
  (`permissions.deny` の `Edit(...)` など)にしておくと、指示だけに頼らずに済む
412
- - スキルは、置いた後なら会話の途中でも読み直される。既に古いスキルを置いたプロジェクトは `p3 agents claude` で違いを確かめ、手で
413
- 直していなければ `p3 agents claude --force` で最新にする(後の「AI エージェントから使う」)
425
+ - スキル(入口)は、置いた後なら会話の途中でも読み直される。手順の本文は毎回 CLI から読むので、手順が変わっても置き直さなくてよい
414
426
  - P3 は `claude -p` も API キーも使わない。今の対話セッションでエージェントが調べて書くので、Claude Code の契約の利用枠を使う
415
427
  (無料になるわけではない)。いつもの Codex の Preflight(Docker・ChatGPT)とは別の経路で、どちらで評価した run も同じに読める(エンジンは `local`)
416
428
 
@@ -448,6 +460,12 @@ Preflight は始めたときの内容を固定して評価する。**評価の
448
460
  無く子だけでもよい(見送りの子は対象外)。子に未完了ができると対応済の親は進行中に戻り、完了済の親は変わらず警告が出る([親と子の要望](#親と子の要望))
449
461
  - Preflight で状態が動くのはタスク化の前の要望だけ。進行中・完了の要望を再評価しても状態は変わらない
450
462
 
463
+ **手戻りの履歴**: 済みを外した・基準や証拠を変えて済みが外れた・完了から戻したことは、タスクの `reworkHistory` に履歴として残る
464
+ (`p3 show T003` の「手戻りの履歴」、API のタスクの詳細)。済みの完了タスクを作業中に戻したときは、済みの外れと再開を1件で示す。
465
+ 同じ値の再保存・済みを保ったままの変更・成果物の追記では増えず、再完了・再確認でも消えない。主体は保存した変更者(申告)で、
466
+ ファイルの直接編集からは作らない。この機能より前の解除・再開は推し量らないので、古いタスクは履歴なしのまま読める。履歴を直接編集で
467
+ 読めない値にすると「読めない」と出て、直すまで新しい履歴を足さない(状態の変更は拒まない)。
468
+
451
469
  ### タスクの関係と置き換え
452
470
 
453
471
  関係は同じ要望の中の2つだけで、どちらも Preflight のタスク化が張る(手では張らない)。
@@ -496,21 +514,30 @@ p3 show T003 --archived --req <要望> # 本文・変更の記録・成果物
496
514
  ### 品質基準
497
515
 
498
516
  プロジェクトとして守る最低限の水準(規約・構成・検証・文書・lint など)を、ID の付いた項目として project.yaml に書いておける。
499
- 未設定でも作業は続けられる。
517
+ 未設定でも作業は続けられる。`p3 quality init` は必須ではなく、未設定から `add`・`adopt` をそのまま使える。
500
518
 
501
519
  ```bash
502
520
  p3 quality # 今の設定(未設定・設定済み・読めない)
503
521
  p3 quality templates # 同梱のテンプレート(basic@1 共通の基本 / typescript@1 TypeScript の例)
504
522
  p3 quality template typescript # 中身を見る
505
- p3 quality adopt basic # 写して採用する(編集できる実体になる)。空のまま設定するなら p3 quality init
506
- p3 quality add --text "lint が警告なしで通る" --repo app --command "pnpm lint" --success "終了コード 0" # 機械の検査
507
- p3 quality add --text "画面の文言は用語集に従う" --reference "docs/glossary.md と照らす" # 人の確認
523
+ p3 quality adopt basic # 写して採用する(編集できる実体になる)
524
+ p3 quality add --text "lint が警告なしで通る" --repo app --repo infra --command "pnpm lint" --success "終了コード 0" # 機械の検査(対象 app と infra)
525
+ p3 quality add --text "画面の文言は用語集に従う" --reference "docs/glossary.md と照らす" # 人の確認(対象は全参照先)
508
526
  p3 quality exempt Q2 --reason "小さい CLI なので層が無い" # 適用の除外(理由は必須)。unexempt で戻す
509
- p3 quality set Q5 --repo all # 対象を全部の参照先に戻す / rm Q4 で消す(ID は使い直さない)
527
+ p3 quality set Q5 --repo all # 対象を全参照先に戻す / rm Q4 で消す(ID は使い直さない)
528
+ p3 quality init # 基準を置かないと決めたことを残す(意図して空。設定済みなら何も変えない)
510
529
  ```
511
530
 
512
- - 画面では設定の「品質基準」のタブで、テンプレートの中身を確かめて編集中の一覧へ足し、対象・確認の方法・除外の理由を直して
513
- 「品質基準を保存」。編集中に他で変わったら入力は残し、保存はさせない(「元に戻す」で最新を読む)
531
+ - **対象(`--repo`)**: 繰り返して複数の参照先を指定する(`--repo app --repo infra`。`--repo=app` の形も同じ)。同じ名前は1つにまとめる。
532
+ `add` で省くと全参照先、`set` で省くと今の対象のまま。`all` は全参照先で、個別の名前と一緒には使えない(登録されていない名前と同じく、
533
+ 何も変えずに断る)。`--repo` を繰り返せるのは `quality add` / `set` だけで、作業先を1つだけ取る `new`・`ls` などで繰り返すと断る
534
+
535
+ - 画面では設定の「品質基準」のタブを使う。未設定なら「基準を追加」(自分で書く)か「テンプレートを見る」(中身を確かめて編集中の一覧へ足す)
536
+ から始め、先に「空のまま設定する」は要らない(基準を設けないと決めたときだけ使う)。保存済みの一覧は基準の文が見出しで、項目ごとに
537
+ 対象・確認の方法・適用(除外の理由)・出典(テンプレートか独自か)を並べる。Q1 などの番号は基準の履歴を追う ID で、点数や順位ではない
538
+ (編集・保存で変わらず、消した番号は使い直さない)。設定の版と採用したテンプレートは「設定の版・テンプレートの採用状況」を開いて見る
539
+ - 「品質基準を編集」で文・対象・確認の方法・除外を直して「品質基準を保存」。対象は「全参照先」か「参照先を選ぶ」(複数選べる。選ぶなら
540
+ 1つ以上)。編集中に他で変わったら入力は残し、保存はさせない(「元に戻す」で最新を読む)
514
541
  - P3 はコマンドを実行しない。確認は作業する側(人・AI・CI)が行う。テンプレートは例で、業界の標準への認証ではない
515
542
  - テンプレートに新しい版が出ても採用済みの内容は変わらない。差分は `p3 quality` に出て、`p3 quality upgrade <テンプレート>` で当てる
516
543
  - **タスクへの取り込み**: Preflight のタスク化と `p3 new`・「+ タスクを追加」で、作業先に当てはまる品質基準が `[Q1] …` の受け入れ基準として
@@ -546,9 +573,9 @@ p3 unblock T003 --resolution "形を変えてよい。互換の層は不要" #
546
573
  タスクボードの作業中カードに「⏸ 停止中」・理由・決めてほしいことが出て、「停止中のみ」で止まっているカードだけにできる(列は増えない。
547
574
  「依存待ち」は依存先が未完了の別の印)。進捗は「停止中のみ」で止まっているタスクのある要望だけにし(親は文脈として残り、配下の停止の
548
575
  数が出る)、スケジュールの作業中の印は一時停止の形になる。条件は URL に残る。止まったまま未着手・完了へ動かすと断られ、解除を案内する
549
- - **AI エージェント**(同梱のスキルと AGENTS.md / CLAUDE.md の節)は、続けられなくなったときだけ理由と決めてほしいことを付け、保存できた
576
+ - **AI エージェント**(CLI が返す手順 `p3 guide`)は、続けられなくなったときだけ理由と決めてほしいことを付け、保存できた
550
577
  ことを確かめて人に伝えて作業を終える(止まったまま完了・済み・対応済に進めない)。回答を受けたら解除して再開する(人が先に解除して
551
- いれば履歴の回答を読む)。前に置いたスキル・節は自動では変わらないので、`p3 agents <claude|codex|both>` で違いを確かめ `--force` で更新する
578
+ いれば履歴の回答を読む)
552
579
  - 規則の詳細・保存の形: [architecture.md の止まっている理由](architecture.md#止まっている理由停止)
553
580
 
554
581
  ### 受け入れ基準と証拠
@@ -582,6 +609,43 @@ p3 evidence T004 A2 met --file a2.md # 1項目ずつ(再記録は置き換
582
609
 
583
610
  - 結果は `met`(満たした。本文が要る)/ `unmet`(満たせなかった)/ `unverified`(確かめていない)。証拠は作業した側の申告で、
584
611
  レビューの判定ではない
612
+
613
+ #### 根拠の種類
614
+
615
+ 結果とは別に、どうやって確かめたかを **根拠** として残せる。「満たした」が、検査の結果に基づくのか、読んで確かめたのか、
616
+ 申告だけなのかを、人が「済み」にする前に見分けるため。
617
+
618
+ | 根拠 | 意味 | 一緒に書くもの |
619
+ | --- | --- | --- |
620
+ | 未確認(`unverified`) | まだ確かめていない。結果が `unverified` のときだけ | なし |
621
+ | 申告のみ(`declaration`) | 満たしたと作業した側が申告しただけ(確かめた方法の記録なし) | なし |
622
+ | 読んで確認(`read`) | 作業した側(AI を含む)がコード・資料・画面を読んで確かめた | 読んだものと確かめた内容(`reference`) |
623
+ | 検査結果あり(`machine`) | 作業した側が実行した検査の結果。失敗もそのまま記録できる | コマンド(`command`)・結果(`result`)・対象の参照先とコミット(`target`。未コミットならそう書く) |
624
+
625
+ ```bash
626
+ p3 evidence T004 A1 met "保存して再読み込みしても残る" --basis machine \
627
+ --command "pnpm vitest run test/settings.test.ts" --check-result "終了コード 0(3 件成功)" --target "app:3f2a1c0"
628
+ p3 evidence T004 A2 met "1280 と 375 で確かめた" --basis read --reference "src/Settings.tsx のレイアウトと画面の表示"
629
+ p3 move T004 done --record - --evidence-json evidence.json < record.md # 根拠つきでまとめて
630
+ ```
631
+
632
+ ```json
633
+ [
634
+ { "id": "A1", "result": "met", "evidence": "対象のテストが通った",
635
+ "basis": { "kind": "machine", "command": "pnpm vitest run test/settings.test.ts", "result": "終了コード 0", "target": "app:3f2a1c0" } },
636
+ { "id": "A2", "result": "unverified", "evidence": "375 の端末が無い" }
637
+ ]
638
+ ```
639
+
640
+ - P3 は検査を実行しない。検査結果ありも読んで確認も作業した側の記録で、P3 が確かめたものではない。2つは方法の違いで、どちらが
641
+ 正しいという上下は付けない
642
+ - 根拠を省くと(`--evidence`・Markdown の `--evidence-file`・古い画面)、同じ結果の前の証拠があればその根拠を引き継ぎ、無ければ
643
+ `unverified` は未確認・ほかは申告のみになる。`met` / `unmet` に未確認、`unverified` にほかの根拠は付けられない
644
+ - 根拠を記録する前の古い証拠は書き換えない。表示では「申告のみ(種類未記録)」(`unverified` は「未確認(種類未記録)」)と出る
645
+ - 申告のみの `met` は、不足に「申告のみの met(確かめた方法の記録なし)」と注意で出る。完了・済みは拒まない。`show` の見出しの
646
+ 「満たしたと申告」の数は確かめた数ではなく、根拠ごとの内訳を添える(`--json` の `acceptance.metByBasis`・`declarationOnly`)
647
+ - 人の「済み」は根拠の種類ではなく、タスクごとの最終の確認。タスクの AI レビューの判定は証拠に写さない
648
+ - 根拠を変えると、済みのタスクの済みが外れる(同じ値の再保存では外れない)
585
649
  - 基準の文を変えると、その基準の証拠は「再確認が必要」になり、満たした数に入らない(記録し直す)
586
650
  - 証拠なし・未達・未検証があっても完了・済み・対応済は拒まない。不足は `show` / `criteria` の「不足」、`--json` の
587
651
  `acceptance.shortfalls`、`move ... done` の stderr に出る
@@ -589,10 +653,196 @@ p3 evidence T004 A2 met --file a2.md # 1項目ずつ(再記録は置き換
589
653
  - ファイルを直接編集して読めない値になったら、`show` に「読めない」と出て、直すまで基準・証拠の操作はできない(ほかの更新では元の値が残る)
590
654
  - 証拠は作業した側の申告で、レビューの判定ではない。変更の記録(`--record`)は何を変えたか・なぜ、証拠は基準ごとの確かめた材料
591
655
  - AI エージェントは、着手する前に基準を読み、完了と同時に基準ごとの証拠を残し、未達・未検証を残して完了したら人に伝える
592
- (同梱のスキルと AGENTS.md / CLAUDE.md の節)。前に置いたスキル・節は自動では変わらないので、置いたプロジェクトで
593
- `p3 agents <claude|codex|both>` で違いを確かめ、`--force` で同梱の版にする
656
+ (CLI が返す手順 `p3 guide`)
594
657
  - 規則の詳細: [architecture.md の受け入れ基準と証拠](architecture.md#受け入れ基準と証拠)
595
658
 
659
+ ### 要求の出典と確認
660
+
661
+ 要求そのものが正しいか(例: 請求の計算式が業務の決まりどおりか)は、コードや履歴を読んでも分からない。要望と受け入れ基準に、
662
+ **出典**(誰の要求か・どの資料の版と節か)・**根拠**(業務の担当が承認した計算例・規則や契約の該当箇所など)・**確かめた人**
663
+ (役割名かアクター名)・**確かめた日** を残せる。どれも任意で、書かなくても要望の登録・Preflight・タスク化は今までどおり進む。
664
+ 実装した後の証拠(上の「根拠の種類」)とは別のもの。
665
+
666
+ ```bash
667
+ p3 source k7m3x add --target "消費税の端数は切り捨て" --source "経理規程 第3版 3.2" --grounds - < example.md # 下書き(未確認)
668
+ p3 source k7m3x confirm S1 --by 経理担当 --on 2026-11-10 # 確かめたことを記録する
669
+ p3 source k7m3x # 記録と状態・回答の一覧
670
+ p3 source T004 A1 add --from S1 # 基準ごとの記録(要望の記録を写す。確認は引き継がない)
671
+ p3 source D2 A1 add --source "画面仕様 v2 4章" --run PF-... # タスク案の基準(タスク化するとタスクに写る)
672
+ p3 source k7m3x --sources-json ops.json # 操作をまとめて([{"op":"add","source":"…","basis":"…"}])
673
+ ```
674
+
675
+ | 状態 | 意味 |
676
+ | --- | --- |
677
+ | 未記録 | 出典・根拠の記録が無い |
678
+ | 未確認 | 出典や根拠はあるが、確かめた記録が無い(下書き・確認先が未定でも保存できる) |
679
+ | 確認記録あり | 記録した確認が今の内容に対応している |
680
+ | 再確認が必要 | 確かめた後で、対象(要望の題・本文、基準の文)か記録の対象文・出典・根拠が変わった |
681
+ | 対応先不明 | 記録の基準を消した・写した元の要望の記録が無い |
682
+
683
+ - 確認を記録するには出典・根拠・確かめた人・日(`YYYY-MM-DD`。保存した日では補わない)がそろうことが要る。確かめた人は役割名でよく、
684
+ 氏名・連絡先は求めない。保存した人(変更者)とは別に残る
685
+ - 「確認記録あり」は、申告された確認が今の内容に対応するという意味で、P3 の認証・保証ではない。AI の評価・実装の `met`・
686
+ 人の「済み」では変わらない。回答を保存しただけでも変わらない
687
+ - 変わった確認は履歴に残し、文を元に戻しただけでは確認記録ありに戻らない(もう一度 `confirm` する)
688
+ - 要望の記録と回答は Preflight の評価対象に入る。変えると、その前の評価からはタスク化・子の採用をしない(タグ・期限・状態だけの変更では古くならない)
689
+ - タスクの記録を変えると済みが外れる(同じ値の再保存では外れない)。根拠の不足で完了・済みは拒まない
690
+ - 根拠・回答の無い以前の要望・基準・評価は、移行せずにそのまま読める。ファイルを直接編集して読めない値になったら「読めない」と出て、
691
+ 直すまでその要望の記録の操作と Preflight の開始はできない(ほかの更新では元の値が残る)
692
+ - 回答・出典・根拠は資料で、P3 は中の URL や添付を取りに行かない
693
+ - 規則の詳細: [architecture.md の要求の出典と確認](architecture.md#要求の出典と確認)
694
+
695
+ ### 完了の記録
696
+
697
+ 完了・人の済み・対応済・完了済にしたとき、P3 はそのときの条件の写しを **完了の記録**(`completionRecords`)としてタスク・要望に
698
+ 足す。後で品質基準・受け入れ基準・前提が変わっても、「当時どの条件で完了・確認したか」を今の値と分けて読める。
699
+
700
+ | 契機 | 写すもの |
701
+ | --- | --- |
702
+ | タスクの完了・人の済み | 受け入れ基準(取り込んだ品質基準の版を含む)・証拠と根拠の種類・基準ごとの出典と確認、要望の出典と確認(履歴を含む)、品質基準の状態・版・作業先に当てはまる項目と除外、参照先のコミット |
703
+ | 要望の対応済・完了済 | 題と、題と本文の hash・出典と確認・品質基準の状態と版・判定に使ったタスクと子の要望(ID・rev・状態・その時点の記録 ID)・参照先のコミット |
704
+
705
+ ```bash
706
+ p3 show T003 # 完了の記録(契機・日時・主体・rev・品質・基準と証拠・参照先)
707
+ p3 show T003 --json # item.completionRecords に全部
708
+ ```
709
+
710
+ - 記録は追記だけ。再開・済みの解除でも消えず、再完了・再確認で新しい記録が足される。同じ状態の再保存・成果物の追記では足さない。
711
+ 済みのまま基準・証拠を変えて済みを付け直したら、新しい人の済みの記録になる
712
+ - 人の済みの記録は人の最終確認で、AI の承認ではない。主体(`by`)は保存した変更者をそのまま残す
713
+ - 参照先は、登録された参照先ごとに取得した時点の HEAD のコミットと未コミットの変更(追跡していないファイルを含む)の有無、
714
+ 取得時刻を残す。取れなければ理由(git でない・このマシンのパスなし・パスが無い・取得に失敗)を残し、過去の Preflight の評価から
715
+ 推測して埋めない。このマシンのパスは残さない。参照先のフォルダの中にデータのフォルダがあると、タスクのファイルを書くので
716
+ 未コミットの変更ありになることが多い
717
+ - 複数のファイル(project.yaml・要望・タスク・参照先)を同じ瞬間に固定するものではない。それぞれ書く直前に読んだ値で、参照先は書く少し前に取る
718
+ - 品質基準が読めない・受け入れ基準が読めないときも「読めない」として写し、完了・済みは拒まない
719
+ - 記録は P3 が作る。CLI・API から記録の値を渡しても受け付けない
720
+ - この機能より前に完了したもの・ファイルの直接編集で完了にしたものは「記録なし」のまま(後から補わない)。記録を直接編集で
721
+ 読めない値にすると「読めない」と出て、直すまで新しい記録を足さない(完了・済みは拒まず、足せなかったことを知らせる。
722
+ ほかの更新では元の値が残る)
723
+ - 規則の詳細: [architecture.md の完了の記録](architecture.md#完了の記録)
724
+
725
+ ### 振り返り(Preflight のリスクは起きたか)
726
+
727
+ 要望ごとに、Preflight で心配したリスクが実装の後に起きたかを振り返る。まず、振り返りの対象にする **採用済みの Preflight の run** を人が1つ確定する。
728
+
729
+ ```bash
730
+ p3 retro k7m3x # 確定した対象(リスクの原文)と候補(採用を終えた run と、作ったタスク・子の要望の根拠)
731
+ p3 retro k7m3x confirm PF-... # 対象を確定する
732
+ p3 retro k7m3x confirm PF-... --reason "追加範囲で採用し直した" # 訂正(理由が要る。前の対象も残る)
733
+ ```
734
+
735
+ - 候補は、評価を終えてタスク化を終えた run(作ったタスクと照らす)と、子の要望の採用を終えた run(作った子と照らし、「分割の採用」と出す)。
736
+ 以前の版の記録しかない run は「タスク化(旧記録)」と出す。採用の途中・評価の途中の run、直接作ったタスクだけの要望、見送りの要望は候補にしない
737
+ - 新しく Preflight を実行・採用したり、画面で別の run を開いたりしても、確定した対象は変わらない(変えるには理由をつけて訂正する)
738
+ - 確定したときに、評価の版とリスクの原文を写す。後で run の記録が変わっても、写した原文で振り返る
739
+ - マイルストーンの無い要望でも確定できる
740
+ - 確定した対象のリスクごとに、人が確認した結果を残す(起きた・起きなかった・未確認)。AI の推測だけで「起きた」とはしない
741
+
742
+ ```bash
743
+ p3 retro k7m3x judge 2 --state occurred --facts "CSV の取り込みが壊れ、T001 を再開して直した" --evidence rework:T001:R1
744
+ p3 retro k7m3x judge 1 --state not_occurred --scope "v1 の請求 1 万件で負荷試験(2026-11)" --evidence manual:https://example.com/perf.md
745
+ p3 retro k7m3x judge 3 --state unchecked --evidence review:T002:TR-...:items:0 # 根拠を結び付けるだけ(未確認のまま)
746
+ p3 retro k7m3x judge 2 --state unchecked --reason "R1 は別の原因だった" # 判断を変える・戻すには理由が要る
747
+ ```
748
+
749
+ | 根拠 | 指定 | 結び付けられるもの |
750
+ | --- | --- | --- |
751
+ | タスクの AI レビューの所見 | `review:T002:<run>:<項目>[:<位置>]`(項目は overall・items・quality・unplanned・checks。位置は 0 から) | この要望のタスクのレビューだけ |
752
+ | マイルストーンレビューの所見 | `milestone:<ID>:<run>:<項目>[:<位置>][:<理由>]`(項目は overall・units・quality・unplanned) | 固定した材料でこの要望が直接の対象だったレビューだけ。所見がこの要望を根拠に挙げていなければ(全体の所見など)結び付く理由が要る |
753
+ | 手戻り | `rework:T001:R1` | この要望のタスクの手戻りの履歴([状態](#状態)) |
754
+ | 人が書く参照 | `manual:<参照>` | 成果物・検証の結果など(P3 は中身を確かめない) |
755
+
756
+ - 「起きた」には確認した事実と根拠、「起きなかった」には確認した範囲(何を・いつ・どこまで)と根拠が要る。根拠を結び付けるだけなら未確認のまま
757
+ - 根拠は保存したときの参照先(要望・タスク・run・位置)と抜粋を残す。後でレビューの結果が差し替わった・見つからなくなったら
758
+ 「記録が差し替わった」「今は見つからない」と出し、当時の抜粋は残る。マイルストーンレビューの実行中に材料が変わっていたら、それも出す
759
+ - レビューは参考の記録(AI の成績の評価ではない)で、テストやアプリは動かしていない。結び付けた所見が確認の範囲を超えて「起きた」「起きなかった」を
760
+ 示すとは限らないので、判断は人が範囲と一緒に書く
761
+ - 件数は今の確定した対象のリスクだけを数える(確認の無いリスクは未確認)。対象を訂正しても、前の対象の判断と抜粋は消えずに読める。
762
+ 親子の間でリスクや根拠は引き継がない。振り返りを書かなくても、タスクの完了・要望の対応済は今までどおりできる
763
+ - 同じ要望の続き・やり直しは今までどおり再評価(もう一度 Preflight)を使う。同じ run は二度タスク化できないので、採用し直した run を
764
+ 確定し直す(訂正)。独立した追加の範囲は子の要望にすると、子ごとに評価・採用・振り返りができる。親子にしても、今あるタスクは移らず、
765
+ 過去の採用の記録も割り当て直さない
766
+
767
+ ### 開発の指標
768
+
769
+ 記録から、開発の成果の指標をプロジェクト全体かマイルストーンごとに出す。指標は改善の材料で、人や AI の成績の評価には使わない
770
+ (個人・エージェントごとの値や順位は出さない)。読むだけで、AI は動かさない。
771
+
772
+ ```bash
773
+ p3 metrics # プロジェクト全体(マイルストーンなしの要望を含む)
774
+ p3 metrics --milestone v0.2 # 登録済みのマイルストーンに今直接属する要望だけ
775
+ p3 metrics --json # 値・単位・対象数・欠損数・内訳・算出の方法(API の GET /api/metrics と同じ)
776
+ ```
777
+
778
+ | 指標 | 何から | 値 |
779
+ | --- | --- | --- |
780
+ | 要望の作成から対応済まで・完了済まで | 要望の作成日時と、[完了の記録](#完了の記録)の最初の対応済・完了済 | 到達した要望の経過時間の中央値(時間) |
781
+ | 未達・未検証・証拠なし・再確認が必要・満たしたと申告した受け入れ基準 | 今完了しているタスクの[受け入れ基準と証拠](#受け入れ基準と証拠) | 件数と分母(数えた基準の合計)。満たした基準は根拠の種類(申告のみを含む)の内訳つき |
782
+ | 手戻り | タスクの手戻りの履歴([状態](#状態)の済みの解除・完了からの再開) | 観測できた件数(1操作1件)。契機・手戻りのあったタスク・記録の無いタスクの内訳つき |
783
+ | AI レビューの未達判定・意図しない変更の候補 | 今完了しているタスクの[AI レビュー](#タスクの-ai-レビュー)の、完了した最新の1回 | 「不足」の判定の件数と、意図しない変更の候補の件数(別々の指標)。レビュー済み・レビューなし・所見 0 件のタスク数つき |
784
+
785
+ - 範囲: どちらも見送り・アーカイブの要望は除く。親子の要望はそれぞれ1件で、タスクは今属する要望のマイルストーンで一度だけ数える
786
+ - 値の無い理由を 0 と区別して出す: 対象なし・記録の欠損で出せない・まだ到達していない。記録の無い古い要望(完了の記録より前に対応済・完了済にしたもの)は
787
+ 欠損として数え、更新日時などで推し量らない。対応済を経ずに完了済にした要望は「対応済に未到達」で、0 時間にはしない
788
+ - 基準なしの完了タスクは対象なし、基準・証拠が読めないタスクは欠損(分母に入れない)。読めない要望のファイルは範囲に入るか分からないので知らせる
789
+ - 手戻りは履歴を残すようになってからの分だけで、それより前の手戻りや全期間の完全さは分からない。履歴の無いタスクは「記録が無い」として内訳に出す
790
+ - AI レビューはレビューした時点の所見で、今のコードの状態ではない。同じタスクを何度もレビューしたら、完了時刻の新しい1回だけを数える(同時刻なら run の ID の大きい方)。
791
+ 読めないレビューの記録・完了時刻の無い記録があるタスクはどれを使うか決められないので欠損。「判断できない」と人が確かめる点は未達に数えない。
792
+ 完了タスクのどれにもレビューが無ければ「記録なし」と出し、0 件とは言わない。指標を見てもレビューは実行しない(マイルストーンレビューの所見は今は数えない)
793
+
794
+ 記録から出せない値(費用・リリース後の不具合)は、人が CLI で記録する(画面と API は読むだけ)。
795
+
796
+ ```bash
797
+ p3 metrics record cost 12000 --unit JPY --from 2026-11-01 --to 2026-11-30 --source "AI の利用料の請求書"
798
+ p3 metrics record post_release_defects 0 --from 2026-11-01 --to 2026-12-31 --source "不具合の管理表" --milestone v0.2
799
+ p3 metrics record cost 13000 --unit JPY --from 2026-11-01 --to 2026-11-30 --source "AI の利用料の請求書" --rev 1 # 訂正
800
+ p3 metrics records # 人の記録の全部(範囲を問わない)
801
+ p3 metrics rm M3 --rev 1 # 消す
802
+ ```
803
+
804
+ - 1件は 指標・範囲(`--milestone` を省くとプロジェクト全体)・観測期間・単位 で決まる。同じ内容の再送は何も変えない。値・出典・メモを変える訂正は
805
+ `--rev`(`p3 metrics` で出る版)が要り、無い・他で変わっていれば競合(終了コード 3)で何も書かない
806
+ - 費用は 0 以上の金額で通貨コードごと(`--unit JPY`)、不具合は 0 以上の整数。通貨・期間の違う値は別の行に出し、1つに合算しない。
807
+ プロジェクト全体とマイルストーンの記録も合算しない(マイルストーンに記録した値は全体には出ない)
808
+ - 値 0 の記録は 0、記録の無い指標は「記録なし」。記録は `<データのフォルダ>/metrics/manual.json` に残り、プロジェクトのデータと一緒に共有される
809
+ - 値を記録したマイルストーンは消せない(先に `p3 metrics rm`)。`project.yaml` の直接編集で消えたら、指標に注意が出る
810
+
811
+ - 指標を足すときは `src/core/metrics/definitions.ts` の `METRIC_DEFINITIONS` に1件(ID・名前・単位・何から・対象・算出・欠損の扱いと集計)を足す。
812
+ CLI・API・画面はその並びをそのまま出す
813
+
814
+ ### 見直しが必要(候補)
815
+
816
+ 完了の記録と今の条件を比べ、変わったものがある完了済みを **見直しが必要(候補)** として示す。過去の判断が誤りだったという
817
+ 判定ではなく、「当時の条件から何が変わったか」を見せるだけで、状態・済み・基準・証拠は変えない(自動で再開しない)。
818
+
819
+ ```bash
820
+ p3 revisit --all # 候補の一覧(完了したタスク・対応済・完了済の要望。完了済みも含む)と理由
821
+ p3 ls --all --review # 候補の完了したタスクだけ
822
+ p3 show T003 # 「見直し:」の欄に理由と当時・今の値
823
+ p3 progress --all # 要望の行に「※見直し候補(要望・タスク N・配下 N)」
824
+ p3 premise k7m3x add --target T003 --target S1 --reason "セキュリティ基準の改版" --condition "基準 2026 版"
825
+ p3 premise k7m3x ack P1 --target T003 --condition "2026 版で確かめた" # 変更を確かめたことを残す
826
+ ```
827
+
828
+ | 見る差 | 候補にする | 候補にしない |
829
+ | --- | --- | --- |
830
+ | 品質基準 | 作業先に当てはまる項目の追加・変更・削除・除外、設定済から未設定・読めないへの変化 | 別の作業先だけの変更、設定全体の版だけの違い |
831
+ | 受け入れ基準 | 記録した基準からの追加・文の変更・削除 | |
832
+ | 要求の出典と確認 | 根拠の内容の変更・削除・確認が効かなくなった(タスクは基準が写した元の要望の根拠も) | 関係のない根拠、文の似ている根拠 |
833
+ | 前提の変更 | 人が対象(要望・タスク・要望の根拠の ID)を明示して記録した変更で、その後に確認・再確認が無いもの | 記録していない外部の変化 |
834
+ | 参照先 | | HEAD の更新だけ |
835
+
836
+ - 状態は **記録なし**(この機能より前・直接編集で完了したもの。比べる基点がない)・**比較不能**(記録が読めない)・**差分なし**・
837
+ **見直しが必要(候補)** を分ける。条件の一部が読めないときは、比べられた部分の理由と比べられなかった部分を両方出す
838
+ - 比べる基点は最新の完了の記録。確かめた結果を残すには、もう一度 **済み** にする(済みを外して付け直す)と新しい記録が基点になる。
839
+ 前提の変更だけを確かめたなら `premise ack` で残す。単に候補を消す操作は無く、差が解消されれば(品質基準を戻したなど)候補も消える
840
+ - 要望の候補は要望自身(対応済・完了済のとき)の差。配下のタスク・子の要望の候補は件数として親に出すが、完了していない親自身を候補とはしない
841
+ - 証拠の「再確認が必要」(基準の文を変えた後の証拠)・基準や証拠の編集で済みが外れることとは別のもの。品質基準の差分の取り込み
842
+ (`p3 criteria T003 quality`)は今までどおり明示した操作で、取り込むと基準が変わって済みが外れる
843
+ - 前提の変更の記録は P3 が URL を取りに行ったり、外部の規則を監視したりはしない。人が気づいた変更を記録する
844
+ - 規則の詳細: [architecture.md の見直し候補](architecture.md#見直し候補)
845
+
596
846
  ### タスクの AI レビュー
597
847
 
598
848
  完了したタスクについて、本文・受け入れ基準が成果物(コミットの差分)で満たされているかを、作業したのとは別の Codex のスレッドに
@@ -891,6 +1141,7 @@ p3 render 画面.html --width 1280 # 画面.png ができる(幅 32
891
1141
  | `/requests/<要望>/board` | タスクボード(V 字。ドラッグで列を移動。完了のカードの「✓ 済み」でボードから外す。「+ タスクを追加」で直接作る) |
892
1142
  | `/requests/<要望>/done` | 対応済み(済みにしたタスクと成果物の一覧。要望の「対応済」とは別) |
893
1143
  | `/release-notes` | マイルストーンの管理(既定)・リリースノート(`?tab=notes&m=<マイルストーン>`)・マイルストーンレビュー(`?tab=review`、記録は `&run=<run>`)。下の「リリースノートの画面」 |
1144
+ | `/metrics` | 開発の指標(`?m=<マイルストーン>`。省けばプロジェクト全体)。下の「開発の指標の画面」 |
894
1145
  | `/settings` | 個人(ChatGPT の接続・テーマ)/ プロジェクトの基本 / 参照先(`?tab=personal|project|repos`) |
895
1146
 
896
1147
  要望の中のページでは `?task=T003` でタスク詳細を重ねて開く。どのタブでも、見出しのタイトルの上に要望 ID と「コピー」が出る
@@ -904,6 +1155,49 @@ Clipboard API が無い)ときはそう出るので、ID をクリックして
904
1155
  基準・証拠を変えると済みが外れ、理由が出る。タスク案の詳細(「内容を見る」)でもタスク化の前に基準を直せ、保存していない基準が
905
1156
  ある間はタスク化できない。「+ タスクを追加」でも基準を入れられる。アーカイブの詳細では読むだけ
906
1157
 
1158
+ **根拠(画面)**: 各基準は「結果」と「根拠」を別のラベルで出す(根拠は未確認・申告のみ・読んで確認・検査結果あり。古い証拠は
1159
+ 「申告のみ(種類未記録)」)。読んで確認は読んだもの、検査結果ありはコマンド・検査の結果・対象を添える。上の行に
1160
+ 「満たしたと申告 2/3、うち申告のみ 1(検査結果あり 1)」のように内訳が出る。「証拠を編集」で根拠の種類を選び、読んで確認は
1161
+ 読んだもの、検査結果ありはコマンド・検査の結果・対象(参照先とコミット)を書く(欄がそろうまで保存できない。種類は結果に合うもの
1162
+ だけを選べる)。根拠に触れずに本文だけ直したときは、根拠を送らず前のまま残す。検査結果ありは「作業した側が記録した検査の結果」、
1163
+ 読んで確認は「作業した側(AI を含む)の確認」で、P3 が確かめたものではない。AI のレビューは別の欄で、根拠の選択からは動かさない。
1164
+ 人の済みは根拠の選択肢ではなく、上部に「人が確認済み(最終確認)」か「人の最終確認:未」と出る。済みにした後も未達・申告のみは
1165
+ そのまま出る。進捗では、申告のみの達成があるタスクの数を要望の行に「申告のみ n」と出す(基準の数ではなくタスクの数。子孫の分は
1166
+ 入れない)。印の説明・まとまった印の一覧にも「申告のみ n」が付き、印から(キーボードでも)タスクの詳細を開ける
1167
+
1168
+ **要求の出典と確認(画面)**: 要望の概要の本文の下に「要求の出典と確認(任意)」の折り畳み欄がある(記録があれば開いている)。
1169
+ 記録ごとに状態(未記録・未確認・確認記録あり・再確認が必要・対応先不明)を文字で出し、対象・出典・根拠・確かめた人と日を見せる。
1170
+ 「+ 出典と根拠を追加」「編集」「確認を記録」「削除」で直す(確認には出典と根拠がそろっていること)。新しい要望の画面には入力欄を置かないので、
1171
+ 登録の手数は今までどおり。タスク詳細と案の詳細には「受け入れ基準の出典と確認(任意)」があり(記録が無いうちは畳んである)、基準ごとに
1172
+ 同じ操作ができ、要望の記録を写せる。実装後の証拠・根拠の種類・人の済みとは別の欄で、AI のレビューの判定は確かめた人として写さない。
1173
+ アーカイブしたタスクでは読むだけ。
1174
+
1175
+ **完了時の条件と見直し候補(画面)**: 完了したタスクの詳細には、人の済みの欄の下に見直しの状態が出る。候補なら「見直しが必要(候補)」と
1176
+ 理由ごとの「当時」と「現在」を並べ、記録なし・比較不能はその理由と次に確かめる先を出す(差分なしは短く出すだけ)。その下の「完了時の条件」
1177
+ (畳んである)で記録を選ぶと、契機(完了・人の済み)・日時・主体・品質の状態と版・基準と当時の証拠・要求の根拠・参照先のコミットと取得時刻を
1178
+ 読める。要望の概要には候補のある自分のタスクの件数と「当時と現在を見る」、配下の件数が出る(候補が無ければ欄は出ない)。進捗の「見直し候補のみ」は
1179
+ 完了済み・対応済みの要望も含めて探し、行に「見直し N」(要望自身と自分のタスク)と「配下の見直し N」を分けて出す。対応済みの一覧では済みの
1180
+ タスクに印が付き、押すと詳細が開く。どれも表示するだけで、状態・済みは変わらない。確かめたら済みを付け直すと新しい記録が基点になる
1181
+ (前提の変更の登録と確認は CLI・API で行う)。品質基準の差分の取り込みは今までどおり明示した操作で、済みが外れる注意が出る。
1182
+
1183
+ **リスクの振り返り(画面)**: 要望の概要のいちばん下に「リスクの振り返り」がある。未確定なら、採用を終えた評価の候補(最新の採用済み・
1184
+ タスク化か分割の採用か・作ったタスク・リスクの数)を比べて1つ選び「この評価を振り返る」。上の Preflight の履歴で別の評価を開いても、振り返る評価は
1185
+ 変わらない(「選択外の採用済み評価 N 件」と出る)。確定した後は三状態の件数とリスクごとの状態が出て、「根拠を照合して確認する」で根拠
1186
+ (タスクの AI レビューの所見・マイルストーンレビューの所見・手戻りの履歴・人が書いた参照)を足して確認結果を保存する。保存した確認は
1187
+ 確認者・日時・当時の抜粋・照合の状態(照合済み・記録が差し替わった・今は見つからない)と訂正の履歴を読める。「対象を訂正する」で理由をつけて
1188
+ 別の評価に変えられ、「過去の対象を見る」で前の対象の判断を開ける。他で保存されていれば保存は断られ、入力は残る。候補が無い・見送りの要望は理由が出る。
1189
+
1190
+ **確認事項に答えて再評価する(画面)**: 評価が ID のある確認事項を出したら、評価の下の「確認事項と回答」に確認事項ごとのカード
1191
+ (確認先・質問・対象・必要な根拠・判断への影響・元の評価と ID・回答の状態)が出る。確認先が分からなければ「要望者に確認先を特定してもらう」と出る。
1192
+ 「回答する」で回答・回答した役割・日・出典・根拠・対応する要望の記録を入れて「回答を要望に保存」。過去の評価を見ているときも、回答は今の
1193
+ 要望に残る。保存しても評価は始まらないので、「保存した内容で再評価」(か「もう一度 Preflight」)を押す。保存した後は表示中の評価が
1194
+ 今の要望と違う(要求の根拠・確認事項への回答が変わった)と出て、その評価からはタスク化できない。ID の無い以前の確認事項は、これまでどおり
1195
+ 「メモ欄で答える」。
1196
+
1197
+ - 出典・根拠・回答を入力していて保存していない間は、Preflight の開始とタスク化を止める(保存するか取消する)
1198
+ - 保存の前に他で変わっていたら、入力を残したまま理由を出す(最新を読み込んでからもう一度保存する)
1199
+ - 「確認記録あり」は人の確認の申告で、P3 の保証ではない
1200
+
907
1201
  進捗のスケジュールの記号:
908
1202
 
909
1203
  | 記号 | 意味 |
@@ -917,6 +1211,15 @@ Clipboard API が無い)ときはそう出るので、ID をクリックして
917
1211
 
918
1212
  印をクリックするとタスクの詳細が開く。ズーム(日 / 週 / 月)と「今日」ボタンで動かす。
919
1213
 
1214
+ **開発の指標の画面**(ヘッダーの「開発の指標」): [開発の指標](#開発の指標)を、上の「集計範囲」でプロジェクト全体か登録済みのマイルストーンを選んで見る
1215
+ (URL の `?m=` で開ける)。値・対象・欠損は `p3 metrics` と同じもので、画面では数え直さない。
1216
+
1217
+ - 指標ごとに値と状態(値あり・対象なし・記録なし・記録の欠損で出せない・まだ到達していない)を出すので、「観測できた 0」とほかを見分けられる。
1218
+ 読み込めなければその旨と「もう一度」を出す(登録に無いマイルストーンの URL なら、プロジェクト全体へ戻れる)
1219
+ - 「算出方法と内訳」を開くと、何から・対象・算出・欠損の扱い・内訳・欠損した対象を読める
1220
+ - 人が記録する値は期間・出典・版を出し、「CLI での記録のしかた」に `p3 metrics record` の書き方がある(画面では記録しない)
1221
+ - 「指標を読み込み直す」で、CLI での記録などを取り込む。人・エージェントごとの値や順位は出さない
1222
+
920
1223
  **リリースノートの画面**(ヘッダーの「リリースノート」): タブで「レビュー」「リリースノート」「マイルストーン」を切り替える
921
1224
  (`?tab=review` がレビューのタブ、`?tab=notes` がノートのタブ。無い・ほかの値はマイルストーン(管理)のタブ。タブを移っても `?m=` の選択と、書きかけの入力は残る。
922
1225
  保存していない変更があるタブには ● が付く)。
@@ -997,9 +1300,11 @@ DB は無く、1タスク = 1 Markdown ファイル。人・AI・Codex が直接
997
1300
  attachments/A-.../ 添付
998
1301
  preflight/PF-.../ Preflight の記録(評価対象・評価・タスク案・画面資料・ログ)
999
1302
  task-reviews/T003/TR-.../ タスクの AI レビューの履歴(「タスクの AI レビュー」)
1303
+ retrospective.json 振り返りの記録(「振り返り」)
1000
1304
  .archive/ アーカイブした要望
1001
1305
  release-notes/v0.2.md リリースノート(マイルストーンごとに1件)
1002
1306
  milestone-reviews/v0.2/<run>/ マイルストーンレビューの履歴(「マイルストーンレビュー」)
1307
+ metrics/manual.json 人が記録した指標の値(「開発の指標」)
1003
1308
  ```
1004
1309
 
1005
1310
  タスクファイルの例(`requests/261009-k7m3x/tasks/T003.md`):
@@ -1044,8 +1349,12 @@ updatedBy: ai:claude
1044
1349
  ### AI エージェントから使う
1045
1350
 
1046
1351
  AI にも CLI を使わせる(認証を持たせずに済む)。`p3 init --agents claude|codex|both`(値を省くと both)か、作った後なら
1047
- `p3 agents claude|codex|both` で、`AGENTS.md`(無ければ `CLAUDE.md`、どちらも無ければ `AGENTS.md` を作る)に短い使い方の節を足し、
1048
- 詳しい手順のスキルを選んだ先に置く。どちらにも上の「役割と言葉」の役割が書いてある。置いたファイルはリポジトリに入れて共有する。
1352
+ `p3 agents claude|codex|both` で、AI 向けの **入口** を置く: 選んだ先のスキルと、`AGENTS.md`(無ければ `CLAUDE.md`、どちらも無ければ
1353
+ `AGENTS.md` を作る)の「タスク管理(infodb p3)」の節。置いたファイルはリポジトリに入れて共有する。
1354
+
1355
+ 入口には手順の本文を書かない。入口が AI に指示するのは「p3 を操作する前に `pnpx @infodb/p3 guide --json` を実行し、返った手順を最後まで
1356
+ 読んで従う」「取得できなければ p3 を操作せず、エラーと呼び方を人に伝えて終える」ことだけで、上の「役割と言葉」の役割・終わり方は
1357
+ CLI が返す手順(下の `p3 guide`)にある。CLI が新しくなれば手順も新しくなるので、手順が変わっても置いたファイルを更新しなくてよい。
1049
1358
 
1050
1359
  | 置く場所(リポジトリのルート) | 読む AI |
1051
1360
  | --- | --- |
@@ -1058,8 +1367,38 @@ AI にも CLI を使わせる(認証を持たせずに済む)。`p3 init --a
1058
1367
 
1059
1368
  節のスキルの参照は、選んだ先と、リポジトリに既にある先だけを書く(無い先は書かない)。
1060
1369
 
1061
- **後から置く・最新にする(`p3 agents`)**: 今いるリポジトリのルート(サブフォルダからでも)に、選んだ先だけを扱う。プロジェクトは
1062
- 決めず、データ・個人設定は変えない。選ばなかった先は作らず・変えず・消さない(チームで消した先は戻らない)。置く先は省けない。
1370
+ **作業の手順を CLI から読む(`p3 guide`)**: AI 向けの作業の手順の全文は、動いている CLI に同梱した版を
1371
+ `pnpx @infodb/p3 guide`(`--json` で版つき)で読める。プロジェクトを決めないので、登録していない場所でも読め、データ・個人設定・
1372
+ 置いたファイルは何も変えない(Codex・Docker・npm も呼ばない)。
1373
+
1374
+ | `--json` の項目 | 意味 |
1375
+ | --- | --- |
1376
+ | `schemaVersion` | この JSON の形の版(今は 1) |
1377
+ | `cliVersion` | 手順を返した CLI(パッケージ)の版。最新かどうかは表さない |
1378
+ | `entryVersion` | 置く入口の決まりの版。入口に書くこと(呼び方・読み込みの約束)を変えたときだけ上がり、手順の本文を直しただけでは変わらない |
1379
+ | `guide` | 手順の全文(Markdown)。オプションなしの出力と同じもの |
1380
+ | `agents` | 今いる作業ツリーに置いた入口の状態(下の「置いた入口の状態」。`whoami --json` にも同じものが出る) |
1381
+
1382
+ **置いた入口の状態(`agents`)**: `p3 whoami`(「AI の入口」の行)・`p3 whoami --json`・`p3 guide --json` に、今いる作業ツリーのルートに
1383
+ 置いた入口ごとの状態が出る。読むだけで、古くても操作は断らず、自動で更新もしない。AI は対応が要る状態を見つけたら人に伝え、
1384
+ 自分では `p3 agents` を実行しない(手順に書いてある)。
1385
+
1386
+ | 状態(`status`) | 意味 | 人がすること |
1387
+ | --- | --- | --- |
1388
+ | `current` | 入口の版が同じで、同梱の入口と同じ | なし |
1389
+ | `outdated` | 入口の版が古い・版の無い前の p3 の全文(手順を写していた版) | 差分を確かめ、`pnpx @infodb/p3 agents <先> --force` で入口に置き換える(下の「移り方」) |
1390
+ | `missing` | 節が指しているスキルが無い・スキルはあるのに節が無い | `p3 agents <先>` で置く |
1391
+ | `modified` | 版は同じだが中身が違う(手で直した など) | 直した内容を確かめる(`--force` は直した分を消す) |
1392
+ | `newer` | 入口の版が CLI より新しい | 古い CLI で動いていないか確かめる(`pnpx @infodb/p3` で呼んでいるか・`cliVersion`)。`--force` で戻さない |
1393
+ | `unknown` | 版が読めない・節が複数・見出しになっていない | 手で1つの節に整理する・版の書き方を確かめる |
1394
+ | `unreadable` | ファイルを読めない | 権限・種類を確かめる |
1395
+
1396
+ - 選ばなかった先が無いことは問題にしない(claude だけ・codex だけでもよい)。何も置いていなければ「置かれていません」と出る
1397
+ - 追加の作業ツリー(git worktree)で見たときは、その作業ツリーの入口を調べる。`p3 agents` が書くのはメインの作業ツリーなので、
1398
+ そこで更新・レビュー・コミットしてから、作業ツリーのブランチに取り込む
1399
+
1400
+ **後から置く・最新にする(`p3 agents`)**: 今いるリポジトリのルート(git のメインの作業ツリー。サブフォルダからでも)に、選んだ先だけを
1401
+ 扱う。プロジェクトは決めず、データ・個人設定は変えない。選ばなかった先は作らず・変えず・消さない(チームで消した先は戻らない)。置く先は省けない。
1063
1402
 
1064
1403
  | 今の状態 | `p3 agents <先>` | `p3 agents <先> --force` |
1065
1404
  | --- | --- | --- |
@@ -1073,11 +1412,21 @@ AI にも CLI を使わせる(認証を持たせずに済む)。`p3 init --a
1073
1412
  - 後から片方を足したときは、スキルは置き、節(前の参照のまま)は「保護」になる。両方を指す節にするなら `--force`
1074
1413
  - チームで使うとき: 置いた・最新にした変更(`git diff`)をレビューしてコミットし、push して共有する。ほかの人は pull するだけで
1075
1414
  よい(参加の `p3 join` は AI 向けのファイルを書かない)
1076
- - 新しい版の P3 で手順が変わっても、置いたスキルと節は自動では変わらない(例: 完了をコミットの前にする順番)。`p3 agents <先>` で
1077
- 違いを確かめ、手で直していなければ `--force` で最新にする
1078
1415
  - 以前の版との違い: 以前は `init --agents` で両方に置き、参加(init)のときも置き、登録済みのリポジトリで実行し直すと足りない方を
1079
1416
  置いていた。今は、置く先を選び、参加では置かず、後から置く・最新にするのは `p3 agents` だけ
1080
1417
 
1418
+ **前の版の入口(手順の全文の写し)から移る**: 入口だけにした版より前に置いたスキル・節は、`agents` で `outdated` と出る。移るのは人が1回だけ行う。
1419
+
1420
+ 1. `p3 agents <先>`(`--force` なし)で、同梱の入口との違いを確かめる(何も変えない)
1421
+ 2. 前のスキルや「タスク管理(infodb p3)」の節の中に、プロジェクト固有の決まりを手で書き足していたら、節の外(AGENTS.md の別の見出し)や
1422
+ 別の開発文書へ移す。`--force` は選んだ先のスキルの全文と p3 の節を置き換えるので、残しておくと消える
1423
+ 3. `p3 agents <先> --force` で入口に置き換え、`git diff` をレビューしてコミットする(作業ツリーで使うブランチには取り込む)
1424
+ 4. `p3 whoami` の「AI の入口」が「最新」になったことを確かめる
1425
+
1426
+ **CLI の呼び方と版**: 入口と手順は `pnpx @infodb/p3` で呼ぶ。`pnpm add -g` などで全体に入れた `p3` は、入れ直すまで古い版のまま動くことが
1427
+ ある(手順もその版のものになる)。動いている版は `p3 guide --json` の `cliVersion` で分かる(P3 は npm に最新版を問い合わせない)。
1428
+ `pnpx` が取り直すまでの間(キャッシュ)や、公開から入れるまで待つ日数(`minimumReleaseAge` など)は、使う人の pnpm の設定による。
1429
+
1081
1430
  ブラウザ用の REST API(`/api/...`、自己記述は `GET /api/ai/manifest`)もあるが、ローカルの画面のためのもの。
1082
1431
 
1083
1432
  ### CLI の一覧
@@ -1087,7 +1436,7 @@ AI にも CLI を使わせる(認証を持たせずに済む)。`p3 init --a
1087
1436
  | コマンド | 内容 |
1088
1437
  | --- | --- |
1089
1438
  | `p3 init` / `p3 join` / `p3 project` / `p3 whoami` | 新しく作る / 共有されたものに参加する / 個人設定のプロジェクト / 今の判定 |
1090
- | `p3 config` / `p3 repo` / `p3 user-config` | プロジェクトの設定 / 参照先 / 個人設定(テーマ・マシンごとの設定) |
1439
+ | `p3 config` / `p3 repo` / `p3 user-config` | プロジェクトの設定 / 参照先 / 個人設定(テーマ・マシンごとの設定)。`p3 user-config paths <フォルダ>` は Docker にマウントするときのホストのパスと決め方を見る(変えない。[導入ガイド](installation.md#3-パスを確かめるdevcontainer-のときだけ)) |
1091
1440
  | `p3 progress` | 要望ごとの進捗(マイルストーンごと。`--all` で完了・見送りも) |
1092
1441
  | `p3 milestone ls\|show\|add\|set\|rm\|purpose\|goal` | マイルストーン(目的・予定している機能も) |
1093
1442
  | `p3 milestone review\|reviews\|review-show\|review-cancel` | マイルストーンレビュー |
@@ -1099,6 +1448,10 @@ AI にも CLI を使わせる(認証を持たせずに済む)。`p3 init --a
1099
1448
  | `p3 quality` | 品質基準(テンプレート・採用・追加・変更・除外。[品質基準](#品質基準)) |
1100
1449
  | `p3 block <T>` / `p3 unblock <T>` | 作業中のタスクに止まっている理由を付ける・直す / 解除する([止まっている理由](#止まっている理由)) |
1101
1450
  | `p3 criteria <T>` / `p3 evidence <T>` | 受け入れ基準を見る・足す・直す・消す・並べ替える / 基準ごとの証拠を残す・消す([受け入れ基準と証拠](#受け入れ基準と証拠)) |
1451
+ | `p3 source` / `p3 clarify` / `p3 answer` | 要望と基準の出典と確認 / 評価の確認事項と回答の状態 / 確認事項に回答する([要求の出典と確認](#要求の出典と確認)) |
1452
+ | `p3 retro` | 振り返りの対象(採用済みの Preflight)の確定と候補、リスクの確認(`judge`)([振り返り](#振り返りpreflight-のリスクは起きたか)) |
1453
+ | `p3 metrics` | 開発の指標(到達時間・受け入れ基準・手戻り・AI レビューの所見。プロジェクト全体かマイルストーン)と、人が記録する値(`record`・`records`・`rm`。[開発の指標](#開発の指標)) |
1454
+ | `p3 revisit` / `p3 premise` | 見直しが必要(候補)と理由 / 前提の変更の記録と確認([見直しが必要(候補)](#見直しが必要候補)) |
1102
1455
  | `p3 preflight` / `p3 notes` / `p3 drafts` / `p3 accept` | Preflight の実行(`--note`。手元のエージェントなら `--prepare` / `--complete`。中断は `--cancel --run`)/ メモ / 評価とタスク案 / タスク化 |
1103
1456
  | `p3 attach` / `p3 render` | 添付 / 画面イメージの描画 |
1104
1457
  | `p3 chatgpt` / `p3 codex update` / `p3 serve` | ChatGPT の接続 / Codex のイメージ / 画面(`--all-projects` で登録したプロジェクトを跨ぐ) |