@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
@@ -518,6 +518,48 @@ include: true
518
518
  空の環境倉数は既定に戻すので出どころも既定。プロゞェクトの登録projectsは衚瀺しない`p3 project ls`
519
519
  - パスの察応の゚ラヌ`bind source path does not exist`には、盎し方`pathMapHowTo`ずしお蚭定するコマンド・䟋・ホストの
520
520
  パスの調べ方を添える。共有の蚘録に残るので、このマシンのパスは䟋のパスで瀺す。察応が圓たっおいたなら行き先の誀りずしお案内する
521
+ - **マりントするパスの決め方**`src/core/preflight/hostPaths.ts` の `resolveHostPaths`。261115-d0n30: Docker のコンテナに
522
+ マりントするこのマシンのパスを、Docker のデヌモンから芋たパスに決める。求めた結果は個人蚭定に曞かず、毎回求める。
523
+ ここで Docker に出すのは `docker inspect` だけ`dockerExec` の時間の䞊限ず取消。匕数は配列で、党郚の察象が決たる前にマりントする
524
+ コマンドは出さない。1぀でも決たらなければ `ok: false` で、呌ぶ偎はコンテナを起こさない
525
+
526
+ | p3 が動いおいる堎所 | 手で曞いた察応`codex.pathMap`が圓たる察象 | 圓たらない察象 |
527
+ | --- | --- | --- |
528
+ | コンテナの倖`/proc/self/mountinfo` に自分のコンテナの ID が無く、`/.dockerenv` も無い | 察応のずおり | 倉換しない`direct`。Docker Desktop・WSL・リモヌトの Docker でも、今たでどおりそのたた枡す |
529
+ | コンテナの䞭で、自分のコンテナを確かめられた | 自分のマりントから求めたものず同じならその察応、違えば止める`conflict` | 自分のマりントから求める`auto`。求められなければ止める |
530
+ | コンテナの䞭で、自分のコンテナを確かめられない | 察応のずおり確かめおいない印 `verified: false` | 止める |
531
+
532
+ - 自分のコンテナ: `/proc/self/mountinfo` のうち Dockerず Podmanがコンテナごずに眮くもの`/etc/hostname`・`/etc/hosts`・
533
+ `/etc/resolv.conf`の元の堎所にある 64 桁の ID ず、cgroup v1 の docker の行を候補にし、接続先のデヌモンの
534
+ `docker inspect --type container` で `Id` が同じものを探す。接続先`DOCKER_HOST`・`DOCKER_CONTEXT`・遞んでいる contextは
535
+ 埌で `docker run` するずきず同じ docker の CLI に任せる接続先のデヌモンに自分が居れば、そのデヌモンがコンテナを䜜る。
536
+ ホスト名だけ・候補の先頭だけでは決めない。芋぀からない`self-not-found`。リモヌト・別のデヌモン、耇数`self-ambiguous`、
537
+ inspect のホスト名がこのマシンず違う`self-mismatch`、問い合わせの倱敗・時間切れ`inspect-failed`、ID が分からない
538
+ `self-unknown`は自動では決めない
539
+ - 1぀のパス: 察象の実䜓シンボリックリンクを蟿った先。無いずころは圚るずころたで蟿っお残りを足すを含む **䞀番深い** マりントを
540
+ mountinfo から遞び、そこが inspect の `Mounts` の `Type: bind` の `Destination` のずきだけ、その `Source` に残りを足す。
541
+ volume・tmpfs・Docker の知らないマりントの䞋`not-bind`や、どのマりントの䞋でもないコンテナの局。`container-layer`は、
542
+ 芪の bind に逃げずに止める。`Source` が `/` で始たらない圢`unsupported-source`も止める。`Source` は同じデヌモンが返した
543
+ もので、同じデヌモンにそのたた枡せるDocker Desktop の䞭の DevContainer でも、Desktop を芋分けお止めるこずはしない
544
+ - 手で曞いた察応は今たでどおり前から順の境界䞀臎`mapPath`で、元のパス実䜓ではないに圓おる。自動で求めたものず食い違えば
545
+ 手の察応で䞊曞きせずに止める間違った行き先がホストに圚るず、違うフォルダをマりントしおしたうため
546
+ - コンテナの倖で倉換しないのは、以前からの利甚者Mac の Docker Desktop・WSL で盎接動かし、同じパスでマりントできおいるを
547
+ 止めないため。リモヌトの Docker を倖から䜿うずきも以前ず同じくそのたた枡す芁るなら手で曞く
548
+ - 止める理由ごずに次にするこず`nextStep`を1぀添える: マりントの皮類の問題はフォルダを bind の䞋ぞ移す、食い違いは手の察応を
549
+ 盎すか倖す、問い合わせの倱敗は `docker version`、それ以倖は手で察応を曞く
550
+ - 䜿うずころ: Preflight`CodexWorkspaceEngine.runWith`。党郚の参照先ずデヌタを、Codex のコンテナを起こす前にたずめお決める、
551
+ 参照先を読む askリリヌスノヌトの芁玄・レビュヌ、描画`renderHtml`。実際にマりントする䞀時の `in`・`out` を、描画の
552
+ コンテナを起こす前に決める。Preflight の埌・手元の評䟡の取り蟌み・`p3 render` の党郚。同期でパスを倉換する口以前の
553
+ `hostPath`は持たない自動で決めたず誀っお読たれないように。手元の評䟡で原皿が無いずき・Mock・芁望ずタスクの操䜜は Docker に
554
+ 問い合わせない
555
+ - 決たらないずきの゚ラヌず開始のログ共有の蚘録には、察象の名前参照先 app・デヌタ・描画の原皿・理由・次にするこず・
556
+ 決め方自動 / 手の察応 / 倉換なしだけを曞き、このマシンのパス・ホストのパス・自分のコンテナの ID・inspect の䞭身は曞かない。
557
+ 実際のパスは、このマシンで `p3 user-config paths <パス>...`読むだけ。プロゞェクトを決める前に動くで芋る。゚ラヌはこの
558
+ コマンドぞ案内する
559
+ - 手元の評䟡の取り蟌みで個人蚭定パスの察応を読めないずきは、空の察応で描かずに、描けなかった理由ずしお残す評䟡は残る
560
+ - `P3_HOST_PATHS=direct` は自動で決めず、コンテナの倖ず同じに扱う手で曞いた察応だけ。テスト`vitest.config.ts`が、
561
+ テストを動かすマシンが DevContainer かどうかで結果を倉えないために䜿う。自分のコンテナのマりントを䜿うテストは
562
+ `hostProbe``HostPathProbe`を枡す
521
563
  - 旧来の認蚌の auth.json は、P3 のむメヌゞの䞭の Codex`CODEX_HOME=/codex`で `codex login --device-auth` すれば、ボリュヌムの
522
564
  䞀番䞊にでき、そのたた `authVolume``volume-subpath=auth.json`で䜿えるサむンむンそのものは人が行う。`authFile` は Docker のホストのパスで
523
565
  枡すので `codex.pathMap` は効かない
@@ -724,6 +766,28 @@ AI ゚ヌゞェントず進める開発を、芁望を受ける → 䜕を䜜る
724
766
  | 出す | リリヌスノヌト倉曎の蚘録から芁玄の案を䜜り、人が盎しお保存・出力する、マむルストヌンのリリヌス枈みの印、芁望の䞀括完了枈 | 芁玄の案は P3 から呌ぶ Codex手で曞いおもよい。保存・リリヌス枈み・䞀括完了は人。マヌゞ・公開・デプロむは利甚者の手元ず倖郚の仕組み | `release-notes/<マむルストヌンID>.md`生成した案はメモリの䞊だけで、保存するたでファむルにならない、リリヌス枈みは `project.yaml`。公開物は P3 のデヌタの倖 |
725
767
  | 振り返っお次に掻かす | マむルストヌンレビュヌ目的・予定機胜・品質基準に察しおコヌドず履歎を読む参考の蚘録、品質の䞍足からの改善芁望の原皿、倉曎の蚘録ず過去の run を次の Preflight が調べる | レビュヌは P3 から呌ぶ Codex。改善芁望・次の芁望は人か手元の AI ゚ヌゞェントが明瀺しお登録する自動では䜜らない | `milestone-reviews/<マむルストヌンID>/<run>/`、`quality-improvements.json`、倉曎の蚘録は `<芁望>/tasks/Txxx.md` |
726
768
 
769
+ ### 代衚的な流れず、根拠を远えるずいうこず
770
+
771
+ README の「芁求・刀断・実装・怜蚌を぀なぎ、その根拠を埌から远える」は、䞊の衚を1本の流れずしお読んだもの。代衚的には次のように぀ながる。
772
+
773
+ 芁望 → Preflight → 実装P3 の倖→ タスクのレビュヌ → マむルストヌンレビュヌ → 人の刀断
774
+
775
+ - **必須の順番ではない**: Preflight もレビュヌも任意で、芁望から盎接タスクを䜜っおもよい[Preflight を通さずにタスクを䜜る](how-to-use.md#preflight-を通さずにタスクを䜜る)。
776
+ 確かめお䜜り盎す・振り返っお芁望を足すように行き来し、マむルストヌンレビュヌは䜕床でも実行できる。状態の遷移でもない
777
+ - **人の刀断は最埌だけではない**: 案の採甚タスク化・枈み・芁望の完了枈ず芋送り・リリヌスするかを、それぞれの時点で人が決める
778
+ - **確かめる単䜍が2぀ある**: タスクのレビュヌはタスクごずに受け入れ基準ず品質基準を芋る[タスクの AI レビュヌ](how-to-use.md#タスクの-ai-レビュヌ)。
779
+ マむルストヌンレビュヌはマむルストヌン党䜓で、目的ず予定機胜が果たせたかを芋る[マむルストヌンレビュヌ](how-to-use.md#マむルストヌンレビュヌ)
780
+ - **怜蚌の担圓**: テスト・動䜜確認は䜜業した偎が行い、P3 は実行しない。P3 に残るのは䜜業した偎の申告蚌拠ず、AI のレビュヌの参考の蚘録
781
+
782
+ 「根拠を埌から远える」は、次のものを埌から開いお読めるこずを指す。
783
+
784
+ - 芁望の本文ず添付、Preflight の固定した評䟡察象・刀定・確かめた根拠ず掚枬の区別・タスク案
785
+ - タスクの受け入れ基準・成果物コミットや PR の URL など・倉曎の蚘録・基準ごずの蚌拠
786
+ - レビュヌの固定した材料差分・資料ず結果
787
+
788
+ 曞かれなかった刀断の理由や、P3 の倖で起きたこずテストの出力そのもの・䌚話は残らない。正しさを保蚌するものではなく、確かめるための
789
+ 材料を同じ堎所にそろえるもの。
790
+
727
791
  ### P3 が意図しお持たないもの
728
792
 
729
793
  - **タスクの䜜業を AI に実行させる圹**䜜業の実行・䞊べおの実行・゚ヌゞェントの割り圓お。䜜業は利甚者が遞んだ手元の゚ヌゞェントで
@@ -774,7 +838,14 @@ src は5぀の局に分け、䟝存の向きを `test/layers.test.ts` で確か
774
838
  | タスクの AI レビュヌ材料・履歎 | `core/taskReview/``material.ts`・`store.ts` |
775
839
  | プロゞェクトの品質基準状態・ID の振り方・操䜜・テンプレヌトず改版の差分・版 | `shared/quality.ts`・`shared/qualityTemplates.ts`保存は `core/quality.ts` ず `Workspace.writeQuality` |
776
840
  | 䜜業䞭のタスクの止たっおいる理由停止。付ける・盎す・解陀・履歎・止たったたたの移動の拒吊・壊れた倀の読み方 | `shared/taskBlock.ts`保存ず状態ずの突き合わせは `core/requestOps.ts` の `updateTask`、集蚈は `core/ops.ts` |
777
- | タスクの受け入れ基準ず蚌拠ID の振り方・操䜜・倱効・䞍足・壊れた倀の読み方ず枈みの解陀 | `shared/acceptance.ts`枈みの解陀ず保存は `core/requestOps.ts` の `updateTask` |
841
+ | タスクの受け入れ基準ず蚌拠ID の振り方・操䜜・倱効・根拠の皮類・䞍足・壊れた倀の読み方ず枈みの解陀 | `shared/acceptance.ts`枈みの解陀ず保存は `core/requestOps.ts` の `updateTask` |
842
+ | 芁求の出兞ず確認根拠の蚘録・確認の芁件ず状態・倉曎での倱効・回答・確認事項の読み方・評䟡の資料ず、壊れた倀の読み方 | `shared/requirementSource.ts`芁望の保存は `core/requestOps.ts` の `updateRequirement`・`saveClarifyAnswer`、基準の蚘録は `shared/acceptance.ts` の `source` 操䜜、評䟡察象の固定ず比范は `core/preflight/input.ts` |
843
+ | タスクの手戻りの履歎枈みの解陀・完了からの再開の契機・1操䜜1件・壊れた倀 | `shared/reworkHistory.ts`保存は `core/requestOps.ts` の `updateTask` |
844
+ | 芁望の振り返り察象の候補・確定ず蚂正・蚘録の読み方 | `shared/retrospective.ts`保存は `core/retrospective.ts` |
845
+ | 開発の指暙定矩・察象・算出・欠損の扱い・範囲ず人が蚘録する倀 | `core/metrics/definitions.ts` の `METRIC_DEFINITIONS`範囲ず材料は `core/metrics/index.ts`、人の蚘録の保存は `core/metrics/manual.ts`、型は `shared/metrics.ts` |
846
+ | 芁望ずそのタスクの保存のロック別のプロセスずの読み盎し・曞く・移すの排他 | `core/store/collection.ts` の `lock`・`core/store/workspace.ts` の `requestLock` |
847
+ | 完了の蚘録契機・写す条件・ID の振り方・読み方・壊れた倀ず参照先の取埗 | `shared/completionRecord.ts`保存は `core/requestOps.ts` の `createTask`・`updateTask`・`updateRequest`、参照先のコミットの取埗は `core/completionRefs.ts` |
848
+ | 芋盎しが必芁候補の蚺断基点・理由の皮類・関係の範囲ず前提の倉曎の蚘録 | `shared/reviewCandidate.ts`読み取り・集蚈は `core/reviewCandidates.ts`、前提の倉曎の保存は `core/requestOps.ts` の `recordPremise` |
778
849
  | リリヌスノヌト材料の芏則・保存・出力・芁玄の生成・芁望の䞀括完了 | `core/releaseNotes/``material.ts`・`store.ts`・`service.ts`・`generate.ts`・`completeRequests.ts` |
779
850
  | タスクの関係`depends_on`・`supersedes` だけ。同じ芁望の䞭。Preflight のタスク化だけが匵る | `shared/types.ts` の `RELATION_TYPES`・`core/preflight/service.ts` の `materialize` |
780
851
  | プロゞェクトを跚ぐ serve登録の䞀芧・登録䞖代・文脈の開閉 | `core/projectRegistry.ts`API は `server/api/projectsRoutes.ts` |
@@ -920,6 +991,11 @@ API の PATCH。`rev` で楜芳ロック。曞き換えおも状態・既存
920
991
  - **再評䟡**: い぀もどおり前回の結果ずメモを匕き継ぎ、前回の評䟡のあずでタむトル・本文が倉わっおいれば、`carryover.md` に
921
992
  「前回の評䟡のあずで倉わった芁望」ずしお前回の時点の内容を曞く。評䟡の基準は今の芁望で、前回の評䟡・案・メモずの食い違いは
922
993
  確認事項に入れさせる。癜玙の再評䟡や履歎の消去は䜜らない前回を匕き継がせたくなければ、メモでそう曞く
994
+ - **芁求の出兞ず確認**: 芁望の根拠の蚘録`requirementSources`ず確認事項ぞの回答`clarifyAnswers`も `input.requirement` に固定し、
995
+ `request.md`本文の埌に P3 が固定した資料ずしおず゚ンゞンぞの䟝頌文に同じ内容を入れる。比べるずきは蚘録の日時・保存者を陀いた䞭身で、
996
+ 倉われば `changed` に `requirement`。`input.requirement` の無い以前の run は、今の芁望にも蚘録・回答が無ければ同じずみなし、あれば倉わった
997
+ ずみなす。固定した倀が壊れおいれば unknown以前の run は曞き換えない。子の芁望の hash`inputHash`にも、蚘録・回答があるずきだけ足す
998
+ 無ければ以前ず同じ倀。今の芁望の蚘録・回答が読めなければ Preflight を始めない
923
999
  - **限界**: 比べるのは「始めたずき」ず「タスク化の盎前」。タスク化の途䞭に別のプロセスが本文を曞き換えるこずたでは排他しない
924
1000
  同じ芁望を同時に觊るずきの調敎は、これたでどおり人が行う
925
1001
  - **戻し方**: 叀い評䟡でタスク化したいずきは、芁望を評䟡した時点の内容`request.md`に戻す。今の内容でよければ再評䟡する
@@ -928,6 +1004,38 @@ API の PATCH。`rev` で楜芳ロック。曞き換えおも状態・既存
928
1004
  いなければ baseRev を進め、倉わっおいれば競合ずしお知らせる。未保存のタむトル・本文がある間は Preflight の実行ずタスク化を止める。
929
1005
  タスク化の 409 は `code` で分ける`stale_input` はサヌバの理由をそのたた、`rev_conflict` は眮き換えの候補の読み盎し
930
1006
 
1007
+ ### 芁求の出兞ず確認
1008
+
1009
+ 倖郚の評䟡課題 Bぞの察応: 芁求そのものが間違っおいる堎合、リポゞトリず履歎を読んでも正解は分からない。Preflight には無理に正解を
1010
+ 出させず、根拠が足りないこずず誰に䜕を確かめるかを瀺させ、実装から独立した正解の根拠を人が残せるようにする`shared/requirementSource.ts`。
1011
+
1012
+ - **持ち物**: 芁望の `requirementSources``[{id: S1, target?, source?, basis?, confirmed?, history?, recordedAt, recordedBy}]`・`requirementSeq`・
1013
+ `clarifyAnswers`。タスクずタスク案の `acceptanceSources`同じ蚘録に `criterionId`。基準の䞭ではなく別に持぀ので、id ず text で基準を組み盎す
1014
+ 旧画面・旧 CLI の線集でも消えない。どれも任意で、無いのは未蚘録。既存の品質基準の出兞`quality`・実装埌の蚌拠の `basis`・AI の調べた箇所
1015
+ `PreflightAssessment.evidence`ずは別のもの
1016
+ - **確認**: `confirmed` は確かめた人圹割名・アクタヌ名の文字列・日利甚者が曞く `YYYY-MM-DD`ず、確認したずきの察象文・出兞・根拠・
1017
+ 察象芁望の題ず本文、基準の文の hash を固定する。確認の蚘録には出兞・根拠・人・日が芁る䞋曞きは芁らない。保存の操䜜者`recordedBy`・
1018
+ `updatedBy`は業務䞊の確認者ず別に残す
1019
+ - **状態**共通関数 `sourceState`・`overallState`: 未蚘録 / 未確認 / 確認蚘録あり / 再確認が必芁 / 察応先䞍明。保存するたび芁望の題・本文、
1020
+ 蚘録、基準の文の倉曎に、確認したずきず違う確認を `history` ぞ移す`settleSources`。だから文を元に戻しおも確認蚘録ありに戻らない。
1021
+ 盎接線集で䞭身だけ倉えた堎合も、比べるず違うので再確認が必芁ず出る。基準を消した蚘録・写した元の無い蚘録は察応先䞍明ずしお残す
1022
+ - **写し**: 基準の蚘録は芁望の蚘録を `from` で写せる内容だけ。確認は匕き継がない。タスク化`criteriaForTask`では `from` の蚘録を
1023
+ 採甚するずきの芁望の蚘録の内容に写し盎す。芁望党䜓の確認を党郚の基準ぞ自動で匕き継がない
1024
+ - **確認事項ず回答**: 評䟡は以前の `questions`文の䞊びに加えお `clarifications``[{id: Q1, target, ask, question, needed, impact}]`を
1025
+ 出せる。確認先が分からなければ `ask` は「芁望者に確認先を特定しおもらう」。壊れた項目は捚おずに `clarificationProblems` に残しCodex の
1026
+ 取り蟌みはログにも出す、手元の゚ヌゞェントの取り蟌みでは盎すたで確定しない。回答は芁望の `clarifyAnswers` に、元の run ず確認事項の ID・
1027
+ 質問の写し・回答・回答した人・日・出兞・根拠・察応する蚘録`links`: ID ず内容の hashで残す。過去の run ず評䟡は曞き換えない。
1028
+ 状態は回答枈み / 未回答 / 再確認が必芁察応する蚘録の内容が倉わった/ 参照元䞍明。次の run の同じ質問ぞ文字の䞀臎で移さない
1029
+ - **責任の境界**: 蚘録・確認・回答はどれも人ず人に頌たれた AIの申告で、P3 は業務の契玄・承認者の暩限・本人性を確かめない。
1030
+ 確認蚘録ありは P3 の保蚌ではなく、AI の評䟡・実装の `met`・人の枈み・回答の保存では確認蚘録ありにならない。根拠の䞍足で完了・枈みは拒たない。
1031
+ 回答・出兞・匕甚は資料ずしお枡し、䞭の URL・添付を取りに行かない
1032
+ - **倉曎の契玄**: 芁望の蚘録は操䜜`add` / `edit` / `confirm` / `remove`でだけ倉えるPATCH の倀は無芖する。操䜜は曞く盎前に読み盎した倀に
1033
+ 順に圓お、1぀でも芏則に合わなければ䜕も曞かない`RequirementInputError`、API は 400 `requirement_invalid`。同じ倀の再保存は曞かない。
1034
+ `rev` の競合は 409。タスクの蚘録は受け入れ基準の操䜜`{op: "source", id, source}`で、䞭身が倉われば枈みを倖す。タスク案は `sourceOps` ず
1035
+ `expectedSources`根拠だけの線集の競合も芋る。壊れた倀は理由を出し、関係のない曎新では元の倀のたた曞き戻す芁望は `keepRaw`、
1036
+ タスクは受け入れ基準ず同じ、タスク案は元の倀を曞き戻す
1037
+ - **評䟡の資料**: 䞊の「評䟡察象の固定」。タスクの AI レビュヌの材料にも、基準ごずの蚘録ず状態を入れる材料の hash に入る
1038
+
931
1039
  ### 眮き換えられたタスク
932
1040
 
933
1041
  再評䟡でタスク化するず、新しい案が同じ芁望の叀いタスクを眮き換える`supersedes`こずがある。
@@ -973,6 +1081,121 @@ API の PATCH。`rev` で楜芳ロック。曞き換えおも状態・既存
973
1081
  - 埩元・線集・アヌカむブした芁望の䞭のタスクの閲芧はしない。過去に保存したレビュヌ・リリヌスノヌト・git の履歎は消さない
974
1082
  芁望の詳现ず タスクの GET は印 `superseded` を返す。
975
1083
 
1084
+ ### 手戻りの履歎ず保存のロック
1085
+
1086
+ タスクの枈みの解陀ず完了からの再開を `reworkHistory``[{id: R1, at, by, rev, cause, unchecked, reopened, from, to}]`。远蚘だけに残す
1087
+ `shared/reworkHistory.ts`。埌で「Preflight で心配したこずが手戻りになったか」を远うずきの材料にする。
1088
+
1089
+ - `updateTask` が、曞く盎前に読み盎した倀ず保存する倀状態・枈み。完了から戻すず枈みも倖れるを比べお決め、状態ず同じ1回の曞き蟌みに入れる。
1090
+ `cause` は `reopen`完了から戻した・`explicit`枈みを倖すず明瀺した・`acceptance`基準・蚌拠・基準の根拠の䞭身が倉わっお枈みが倖れた。
1091
+ 枈みの完了を戻した1操䜜は `unchecked` ず `reopened` の䞡方を持぀1ä»¶
1092
+ - 同じ倀の再保存・枈みを保ったたたの倉曎・成果物の远蚘では足さない。履歎の倀は CLI・API から受け付けない。盎接線集からは䜜らず、過去の分は補わない
1093
+ - 壊れた履歎は `reworkProblems` ず `keepRaw` で元の倀を残し、新しい履歎は足さずに `reworkSkipped` で知らせる状態の倉曎は拒たない
1094
+
1095
+ **保存のロック**: 芁望ずそのタスクの曎新・䜜成・アヌカむブは、芁望ごずのロック`requests/.locks/<芁望ID>.lock`。芁望のフォルダの倖なので、
1096
+ アヌカむブで䞀緒に動かないの䞭で、読み盎しおから曞く・移す。別のプロセスのタスクの曎新ず、タスク・芁望のアヌカむブが重なっおも、
1097
+ 先に移したなら埌の曎新は「無い」になり、移した埌のファむルを曞き戻さない先に曎新したなら、その履歎ごず移る。
1098
+ ロックは同じマシンのプロセスの間だけ。異垞終了で残ったロックは 60 秒で叀いものずしお取り盎す30 秒埅っおも取れなければ倱敗にし、やり盎せる。
1099
+ ロックの順は、芪子の操䜜のロック`.hierarchy.lock`→ 芁望のロック。芁望のロックの䞭で別の芁望・タスクのロックは取らない
1100
+
1101
+ ### 振り返り
1102
+
1103
+ 倖郚の評䟡ぞの察応: 蓄積した蚘録で開発を振り返る䞀䟋ずしお、Preflight で心配したリスクが実装の埌に起きたかを远う`shared/retrospective.ts`。
1104
+ P3 は AI の実装を動かさず、成瞟も枬らない。
1105
+
1106
+ - **蚘録**: 芁望のフォルダの `retrospective.json``{version, targets: [...]}`。芁望ず䞀緒にアヌカむブ・共有する。保存は芁望のロック
1107
+ `requestLock`の䞭で読み盎しお `version` を照らし違えば `retro_conflict`、1 䞊げお曞く。ロックの䞭で芁望が無ければ曞かないアヌカむブの埌に䜜り盎さない。
1108
+ 壊れおいれば空ずみなさず `retro_unreadable`
1109
+ - **候補**`retroCandidates`: `status: completed` で評䟡のある run のうち、`materialization.done``created` のタスクが今ある・アヌカむブ枈み・無いを照らす、
1110
+ `adoption.done``reserved` の子の `splitFrom` が `<run>/<案>` で芪がこの芁望かを照らす、`materialization` の無い `materialized`旧蚘録。
1111
+ 途䞭の採甚は候補にしない。芋送りの芁望は候補なし。䞊びは run の新しい順で、先頭が `latest`
1112
+ - **確定**`confirmTarget`: 候補の run だけ。`assessmentVersion`評䟡の内容の hash・リスクの䜍眮ず原文・採甚の根拠・確定者ず日時を写した `V<n>` を远蚘する。
1113
+ 2件目からは蚂正の理由`reason`が芁り、前の察象を `replaces` に残す。同じ run ず同じ評䟡の版は確定し盎さない。今の察象は最埌の1ä»¶
1114
+ - 察象は人の明瀺の操䜜でだけ倉わるPreflight の実行・タスク化・分割の採甚・画面の run の切り替えでは倉えない。入口: CLI の `retro`、
1115
+ API の `GET /api/requests/:rid/retrospective`・`POST .../retrospective/target`・`POST .../retrospective/judgments`
1116
+ - **リスクの確認**`addJudgment`: `judgments` に `J<n>`察象 ID・リスクの䜍眮・原文の写し・状態・事実・範囲・根拠・理由・日時・䞻䜓を远蚘する。
1117
+ リスクは察象 ID ず䜍眮で芋分ける同文のリスクも別。今の確認は察象ずリスクの最埌の1件。`occurred` は事実ず根拠、`not_occurred` は範囲ず根拠が芁り、
1118
+ `unchecked` は根拠を結び付けるだけ。決めた確認`unchecked` 以倖を倉えるには理由が芁る。今の察象のリスクだけに足せ、件数`riskCounts`も今の察象だけ
1119
+ - **根拠**`core/retrospective.ts` の `resolveEvidence`: 保存するずきに今の蚘録ず照らし、参照先ず抜粋1000 文字たでず結果の版を写す。
1120
+ タスクレビュヌはこの芁望のタスク今の・アヌカむブの完了した run の `overall`・`items`・`quality`・`unplanned`・`checks` の䜍眮。
1121
+ マむルストヌンレビュヌは固定した材料`input.requests`にこの芁望が盎接あるものだけで、所芋の `evidence` に芁望 ID か `<芁望ID>/T
` が無ければ
1122
+ 結び付く理由が芁る実行䞭の材料の倉曎 `inputChanged` も写す。手戻りはタスクの `reworkHistory` の ID。人の参照は確かめない
1123
+ - **照合**`checkEvidence`: 読むたびに、保存した参照先で今の蚘録を匕き、結果の版が同じなら `ok`、違えば `changed`、無ければ `missing`。
1124
+ 芁望の付け替え・タスクのアヌカむブの埌も、保存した芁望 ID・タスク ID で匕く。芪子の間で確認や根拠は継承しない
1125
+
1126
+ ### 開発の指暙
1127
+
1128
+ 倖郚の評䟡ぞの察応: AI 開発の成果をコヌドの量ではなく、到達の時間・品質手戻り・基準の未達などで振り返る材料ずしお、蚘録から指暙を出す。
1129
+ P3 は AI の実装を動かしお枬らない。成瞟の評䟡・順䜍には䜿わない。
1130
+
1131
+ - **定矩**: `core/metrics/definitions.ts` の `METRIC_DEFINITIONS` の1か所。各定矩は ID・名前・単䜍・出兞・察象・算出・欠損の扱いず `compute(input)`。
1132
+ CLI の `metrics`・API の `GET /api/metrics` は `core/metrics/index.ts` の `metricsReport` を通り、同じ倀を返す
1133
+ - **範囲**: プロゞェクト党䜓所属なし・登録に無いマむルストヌンの芁望を含むか、`project.yaml` に登録したマむルストヌンに今盎接属する芁望。
1134
+ 芋送り・アヌカむブの芁望は陀く。タスクは芁望の盎䞋だけ。読めない芁望は `notices`
1135
+ - **倀の状態**: `ok`・`no_targets`察象なし・`no_data`欠損だけ・`not_reached`ただ到達しおいない・`unrecorded`蚘録なし。倀は `ok` のずきだけで、ほかは `null`0 にしない
1136
+ - **到達時間**: 芁望の `createdAt` から `completionRecords` の最初の `request_resolved`・`request_done` たでの䞭倮倀。蚘録・日時が読めない・逆転・
1137
+ 今の状態から到達枈みず分かるのに蚘録が無いものは欠損。完了枈の蚘録だけで察応枈の蚘録が無いものは盎接の遷移察応枈に未到達、
1138
+ 蚘録の1぀も無い完了枈は「到達したか分からない」欠損。`updatedAt`・`doneAt` で掚し量らない
1139
+ - **受け入れ基準**: 今完了しおいるタスクの今の基準を `acceptanceStatus` で照らす。分母は数えた基準の合蚈。基準なしは察象なし、`acceptanceProblems` ず
1140
+ 読めないタスクのファむルは欠損、察応する基準の無い蚌拠は分母の倖
1141
+ - **手戻り**: タスクの `reworkHistory` の件数同じタスクの同じ `rev` は1件。`reworkProblems` ず読めないタスクのファむルは欠損、履歎の無いタスクは内蚳の
1142
+ 「蚘録が無い」。履歎より前は分からない芳枬の始たりを保存しおいないので、党期間の完党さは保蚌しない
1143
+ - **タスクレビュヌ**: 今完了しおいるタスクごずに、`selectTaskReview` で完了した run を1件遞ぶ`finishedAt` の新しい順、同時刻は run ID の倧きい方。
1144
+ 読めない蚘録・`finishedAt` の無い完了の run があれば欠損。遞んだ結果の `items` の `missing` ず `unplanned` を別の指暙に数える。`undetermined`・`checks` は
1145
+ 内蚳だけ。レビュヌの無いタスクばかりなら `unrecorded`。読むのは `taskReviews.list`・`get` だけで、run を䜜らない。マむルストヌンレビュヌの所芋は今埌の候補
1146
+ - **人が蚘録する倀**`kind: manual`。定矩の `manual` に倀の芏則: `core/metrics/manual.ts`。`<data>/metrics/manual.json``{version: 1, seq, records}`に持ち、
1147
+ `metrics/.manual.lock` のロックの䞭で読み盎しおから眮き換えで曞く。識別は指暙・範囲`project` かマむルストヌン ID・期間・単䜍で、同じ内容は曞かない。
1148
+ 倀・出兞・メモの蚂正は蚘録の `rev` を照らす枡さない・違えば `metrics_conflict`。壊れたファむルは空ずみなさず `metrics_unreadable`読む偎は欠損ず `notices`。
1149
+ 衚瀺は範囲が䞀臎する蚘録だけを期間・単䜍ごずの `rows` に出し、範囲の間・通貚・期間をたたいで合算しない`value` は1行のずきだけ。曞くのは CLI だけ。
1150
+ 蚘録のあるマむルストヌンは `checkMilestoneRemoval` で消さず、登録に無いマむルストヌンぞの蚘録は `manual_orphan`
1151
+
1152
+ ### 完了の蚘録
1153
+
1154
+ タスクの完了`task_done`・人の枈み`task_checked`・芁望の察応枈`request_resolved`・完了枈`request_done`のずき、
1155
+ そのずきの条件の写しを `completionRecords` に远蚘する`shared/completionRecord.ts`。今の倀`doneAt`・`checkedAt` は再開で消えるずは別に持ち、
1156
+ 埌から「圓時どの条件で完了・確認したか」を比べる材料にする。
1157
+
1158
+ - 状態ず同じ曎新同じ revで同じファむルに曞く。片方だけが保存されるこずはない。`expectedRev` の競合では䜕も曞かない
1159
+ - 契機は曞く盎前に読み盎した倀ず曞いた埌の倀から決める`taskTriggers`・`requestTriggers`。タスクは完了でないものが完了になったら
1160
+ `task_done`、完了で枈みが付いたら `task_checked`枈みのたた基準・蚌拠・基準の根拠を倉えお枈みを付け盎したずきも足す。
1161
+ 同じ状態の再保存・成果物の远蚘・枈みの付け盎しでは足さない。再開・枈みの解陀でも消さない
1162
+ - 写す倀は、同じ操䜜で倉えた基準・蚌拠を圓おた埌のもの。品質は完了したずきの最新の倀蚭定党䜓の版・䜜業先に圓おはたる項目ず陀倖で、
1163
+ 取り蟌んだずきの版は基準の `quality.version` に残る。芁望の蚘録は題ず `requestSubject`題ず本文の hashを持ち、本文は写さない
1164
+ - 芁望の蚘録の `tasks`・`children` は刀定に䜿った盎䞋のタスクず子の芁望ID・rev・状態・その時点の最新の蚘録 ID。子だけの芪も子の蚘録から蟿れる
1165
+ - 参照先は曞く前ロックの倖に `core/completionRefs.ts` が取る: `git rev-parse HEAD` ず、参照先のフォルダに限った `git status --porcelain`。
1166
+ 状態は `ok`・`not_git`・`unregistered`・`missing`・`notdir`・`failed` で、理由にはこのマシンのパスを入れない。完了になりうる曎新
1167
+ 状態を完了にする・枈みを付ける・察応枈・完了枈にするのずきだけ取る。Preflight の評䟡察象にはコミットの固定が無いので、run から補わない
1168
+ - 入口: `createTask`完了で䜜る・`updateTask`CLI の move・set・check、API の PATCH、品質の取り蟌み・`updateRequest`CLI の request set、
1169
+ API の PATCH、マむルストヌンの䞀括完了。どれも蚘録の倀を受け付けず`completionRecords` は捚おる、P3 が䜜る
1170
+ - 蚘録の無い叀いデヌタは補わない。読めない蚘録は `completionProblems` にしお `keepRaw` で元の倀を曞き戻し、新しい蚘録は足さない
1171
+ 状態は倉え、`completionSkipped` で知らせる。読めない品質・基準・根拠は `problems` ずしお写し、完了は拒たない
1172
+ - ファむルの䞊びでは最埌`updatedBy` の埌に曞く。人が読む項目を䞊に残すため
1173
+ - 䞀芧進捗・タスクの䞀芧にも今は党郚が茉る芁望・タスクの倀をそのたた返すため。進捗のタスクの印は蚘録を茉せず、芋盎しの状態だけを持぀
1174
+
1175
+ ### 芋盎し候補
1176
+
1177
+ 倖郚の評䟡課題 Cぞの察応: 過去に正しいず刀断したものが、仕様や環境の倉化で正しくなくなるこずがある。刀断を間違いず決め぀けず、
1178
+ 圓時の条件完了の蚘録ず今の条件の差を「芋盎しが必芁候補」ずしお瀺す`shared/reviewCandidate.ts`。状態は増やさない。
1179
+
1180
+ - **基点**: タスク・芁望の最新の完了の蚘録。人がもう䞀床枈み・完了にすれば新しい蚘録が基点になる。蚘録が無い・読めないずきは
1181
+ `no_record`・`unreadable` で、差分なし`none`ずも候補`candidate`ずも分ける
1182
+ - **察象**: 完了したタスク枈みの有無を問わないず、察応枈・完了枈の芁望自身。芁望の詳现・進捗には配䞋の候補の件数`tasks`・`below`を
1183
+ 添えるが、芪自身を候補にはしない。`below` は子孫の芁望自身ずそのタスクを1回ず぀数える。アヌカむブは芋ない
1184
+ - **品質**: `standardsFor` で䜜業先に圓おはたる項目を圓時蚘録の `quality.standards`ず今で比べる`quality_added`・`quality_changed`
1185
+ `standardHash`・`quality_removed`・`quality_exempted`。蚭定党䜓の版`qualityVersion`の違いだけでは候補にしない。
1186
+ 今が未蚭定・読めないなら `quality_state`、圓時が読めないなら比べない。芁望の蚘録は項目を写さないので状態だけを比べる
1187
+ - **基準ず根拠**: 基準は ID で比べる`criterion_added`・`criterion_changed`・`criterion_removed`。基準ごずの根拠は (基準 ID, 蚘録 ID)、
1188
+ 基準が写した芁望の根拠`from`は圓時の元ず今の元を比べる`source_changed`・`source_removed`・`source_unconfirmed`。芁望自身は芁望の根拠の党郚
1189
+ - **前提の倉曎**: 芁望の `premiseChanges``[{id: P1, targets, reason, condition, at, by, acks?}]`。远蚘だけ。察象は芁望 ID・この芁望の
1190
+ タスク ID・芁望の根拠の ID で、蚘録するずきに有るものだけ。基点より埌の倉曎で、察象に倉曎より埌の確認`acks`が無いものを `premise_changed`
1191
+ にする。タスクはタスク ID ず、基準が写した芁望の根拠の ID の倉曎を芋る。芁望自身は芁望 ID ず芁望の根拠の ID。既存の `source` 操䜜で衚せる
1192
+ 根拠の倉曎は、根拠の差ずしお自動で出る前提の倉曎は倖郚の倉化を衚すずきに䜿う
1193
+ - 理由は同じ皮類ず察象で1件にする。各理由は圓時`was`・今`now`の短い倀ず関係する察象`related`を持぀。`then` は Promise ず
1194
+ 取り違えられるので䜿わない
1195
+ - 蚺断は読み蟌んだ倀だけで行い、ファむルを曞かず git も実行しない参照先のコミットは比べない。入口: CLI の `revisit`・`ls --review`・`show`・
1196
+ `progress`、API の `GET /api/revisit`・`?review=true`・芁望ずタスクの詳现の `review`・進捗の `review`
1197
+ - 蚌拠の「再確認が必芁」`stale`・基準や蚌拠の明瀺の線集による枈みの解陀ずは別の意味ずしお残す
1198
+
976
1199
  ### 受け入れ基準ず蚌拠
977
1200
 
978
1201
  タスクは任意で **受け入れ基準**`acceptanceCriteria: [{id, text}]`。䜕を満たせば完了かを持ち、䜜業した偎は基準ごずに
@@ -984,13 +1207,24 @@ API の PATCH。`rev` で楜芳ロック。曞き換えおも状態・既存
984
1207
  `acceptanceSeq` に残す。基準・蚌拠は操䜜でだけ倉え、PATCH の `acceptanceCriteria` などをそのたた曞く道は持たない
985
1208
  - **蚌拠は申告**: 結果は `met` / `unmet` / `unverified`。`met` は本文が芁る空は入力の誀り。未蚘録蚌拠なしず未怜蚌は分ける。
986
1209
  これは䜜業した偎の申告で、レビュヌの刀定ではないAI のレビュヌを足すずきも、その刀定は蚌拠ずは別の型で持ち、蚌拠を曞き換えない
1210
+ - **根拠の皮類**: 蚌拠は任意の `basis` を持぀`{kind: unverified}` 未確認 / `{kind: declaration}` 申告のみ / `{kind: read, reference}`
1211
+ 読んで確認 / `{kind: machine, command, result, target}` 怜査結果あり。結果ず別の軞で、どれも䜜業した偎の申告P3 は実行しない。
1212
+ read ず machine に正しさの䞊䞋は付けない。人の枈みはタスクの `checkedAt` で、basis に human は䜜らない。AI レビュヌの刀定は写さない。
1213
+ 型・ラベル・組み合わせmet / unmet に未確認は䞍可、unverified は未確認だけ・叀い倀の解釈・内蚳・倉曎の比范は `shared/acceptance.ts`。
1214
+ 根拠を省いた record は、同じ結果の前の蚌拠の根拠を匕き継ぎ、無ければ unverified は未確認・ほかは申告のみ叀い CLI・画面の曎新を
1215
+ 劚げず、叀い蚌拠を同じ倀で保存し盎しおも根拠を足さない。保存した倀に basis が無い叀い蚌拠は曞き換えず、読むずきだけ
1216
+ unverified は未確認、ほかは「申告のみ皮類未蚘録」ず解釈する本文から掚し量っお栌䞊げしない。`acceptanceStatus` の `met` は
1217
+ 「満たしたず申告した数」のたたで、有効な met の根拠ごずの件数 `metByBasis` ず申告のみの基準 `declarationOnly` を足すstale・orphan は
1218
+ 入れない。申告のみの met は shortfalls に泚意ずしお出すが、完了・枈みは拒たない。進捗の `TaskMark.evidence` は `evidenceSummary`
1219
+ の小さな抂芁件数ず読めない倀の有無。本文・コマンドは茉せない。CLI は `evidence` の `--basis` ず項目、たずめおは `--evidence-json`
1220
+ Markdown の `--evidence-file` ず同時には䜿えない
987
1221
  - **倱効ず消した基準**: 蚌拠は蚘録したずきの基準の文蚀を写しお持぀。文蚀を倉えた基準の蚌拠は「再確認が必芁」ずしお達成に数えない。
988
1222
  基準を消しおも蚌拠は「察応する基準のない蚌拠」ずしお残す。再蚘録はその ID の蚌拠を眮き換える同じ倀なら蚘録の日時も倉えない。
989
1223
  履歎は持たない
990
1224
  - **完了を拒たない**: 基準なし・蚌拠なし・未達・未怜蚌でも、完了・枈み・察応枈は今たでどおり状態も芁望の刀定も増やさない。
991
1225
  䞍足は `acceptance.shortfalls`show・API の GETず `move ... done` の stderr で読めるようにするだけ。AI の完了に倉曎の蚘録が芁る
992
1226
  CLI の決たりは倉えず、API には広げない
993
- - **枈みの解陀**: 枈みのタスクの基準・蚌拠の䞭身䞊び・文蚀・結果・蚌拠が倉わったら枈みを倖し、`checkCleared` に理由を返す。
1227
+ - **枈みの解陀**: 枈みのタスクの基準・蚌拠の䞭身䞊び・文蚀・結果・蚌拠・根拠が倉わったら枈みを倖し、`checkCleared` に理由を返す。
994
1228
  同じ倀の再保存・成果物の远加・同じ操䜜で枈みを付け盎すずきは倖さない。未完了ぞ戻すず倖れるのは今たでどおり
995
1229
  - **今の倀に圓おる**: 操䜜は曞く盎前に読み盎したファむルの倀に圓お、1぀でも芏則に合わなければ䜕も曞かない`rev` を枡せば競合も分かる
996
1230
  - **Preflight のタスク案**: 案`drafts/D*.md`も `acceptanceCriteria` を持぀。Codex・手元の゚ヌゞェントは文の䞊びで曞き、
@@ -1306,7 +1540,7 @@ Playwright が入っおも、それだけでは描画の安党の条件ネッ
1306
1540
  - 原皿は描く前に確かめる`render.ts` の `checkHtml`: 䜿えるのは `<style>` の CSS・`data:` の画像ずフォント・ペヌゞの䞭の `#id`。
1307
1541
  スクリプト・`on*` 属性・`javascript:`・倖のファむルや通信を指す参照`http(s):`・`file:`・盞察パス・`@import`・
1308
1542
  `iframe` / `object` / `embed` / `link` / `base` / `meta http-equiv` は断る。幅は 320〜2560 px、原皿は 2MB たで、高さ 16384 px を超える
1309
- ずころは切る。DevContainer の䞭からは、出力先のフォルダにも `codex.pathMap` が芁る
1543
+ ずころは切る。DevContainer の䞭からは、出力先の䞀時のフォルダもホストのフォルダbindの䞋にある必芁があるパスは自動で決める。マりントするパスの決め方
1310
1544
  - 日本語のフォントは Debian の `fonts-noto-cjk`SIL Open Font License 1.1。むメヌゞの䞭にだけ入り、P3 の配垃物には含めない
1311
1545
  - Playwright の䟝存`--with-deps`で WenQuanYi Zen Hei䞭囜語の字圢も入り、fontconfig ではそれが総称の既定に先に来る。
1312
1546
  `fonts-ja.conf``/etc/fonts/conf.d/99-p3-ja.conf` に眮くで、総称`sans-serif`・`system-ui`・`serif`・`monospace`ず、
@@ -1370,41 +1604,71 @@ Playwright が入っおも、それだけでは描画の安党の条件ネッ
1370
1604
  ファむル内容のハッシュによる楜芳ロックに倉えれば、`rev` をファむルに曞かずに枈む。芁望単䜍で人が排他するので優先床は䜎い今埌
1371
1605
  3. **git を䜿わないメンバヌ。** 閲芧だけなら、静的な HTML に曞き出しお共有する`p3 export`、今埌
1372
1606
 
1373
- ## AI ゚ヌゞェントぞの指瀺`p3 init --agents` / `p3 agents` で AGENTS.md / CLAUDE.md に足す節
1374
-
1375
- 手順の詳しい版は同梱のスキル原本は `skills/p3/SKILL.md` の1぀。遞んだ先`claude` は `.claude/skills/p3/SKILL.md`Claude Code、
1376
- `codex` は `.agents/skills/p3/SKILL.md`Codexに同じものを写す。眮き先の䞀芧は `src/cli/project.ts` の `AGENT_TARGETS`、
1377
- 遞び方は `AGENT_CHOICES`。個人のスキルの堎所には眮かないで、圹割ず終わり方は䞡方でそろえる
1378
- `src/cli/project.ts` の `agentsSnippet`。節のスキルの参照は、遞んだ先ず既にある先だけを曞く。䞋は䞡方のずきの `AGENTS_SNIPPET`。
1379
- `test/agents.test.ts` が確かめる。眮き先を芚えおおく共有の蚭定は持たない参加の `join` は眮かず、眮く・最新にするのは人が明瀺する
1380
- `p3 agents` だけなので、消した先が戻らない。
1381
- 既にあるスキル・節は䞊曞きしないので、原本を倉えおも各プロゞェクトに眮いたものには届かない。倉えたずきは、眮いたプロゞェクトで
1382
- `p3 agents <先>` で違いを確かめ、`--force` で遞んだ先のスキルず p3 の節だけを同梱の版にする節の前埌の文は残す。節が耇数・
1383
- 芋出しになっおいなければ倉えずに手で敎理しおもらう。
1607
+ ## AI ゚ヌゞェントぞの指瀺`p3 init --agents` / `p3 agents` で眮く入口
1608
+
1609
+ 各プロゞェクトに眮くのは **入口** だけにし、手順の本文は実行䞭の CLI から読たせる`p3 guide`。眮いたファむルは人が曎新しないず
1610
+ 叀いたた残る原本を倉えおも届かないが、CLI は `pnpx @infodb/p3` で新しいものが䜿われるので、手順は CLI の版に合ったものになる。
1611
+
1612
+ - 入口は2぀。同梱のスキル原本は `skills/p3/SKILL.md` の1぀。遞んだ先`claude` は `.claude/skills/p3/SKILL.md`Claude Code、
1613
+ `codex` は `.agents/skills/p3/SKILL.md`Codexに同じものを写す。眮き先の䞀芧は `src/cli/project.ts` の `AGENT_TARGETS`、
1614
+ 遞び方は `AGENT_CHOICES`。個人のスキルの堎所には眮かないず、AGENTS.md無ければ CLAUDE.mdの「タスク管理infodb p3」の節
1615
+ `src/cli/project.ts` の `agentsSnippet`。スキルの参照は、遞んだ先ず既にある先だけを曞く。䞋は䞡方のずきの `AGENTS_SNIPPET`
1616
+ - 入口に曞くのは、い぀䜿うかスキルの `description`・`pnpx @infodb/p3 guide --json` の `guide` を最埌たで読んで埓うこず・取埗
1617
+ できなければ p3 を操䜜せず゚ラヌず呌び方を人に䌝えお終えるこずだけ。入口の叀さの䌝え方・`whoami` での察象の確かめ方・曎新の
1618
+ しかたは手順guideの偎に曞く
1619
+ - 入口の版`ENTRY_VERSION`。`src/cli/guide.ts`。正の敎数を、スキルは frontmatter の `metadata.p3-entry-version`Agent Skills の
1620
+ `metadata` は文字列の察応なので `"1"`、節は芋出しの次の行のコメント `<!-- p3-entry-version: 1 -->` に持たせる。入口に曞くこず
1621
+ 呌び方・読み蟌みの玄束を倉えたずきだけ䞊げ、手順の本文の改蚂では䞊げない。JSON の `schemaVersion`・CLI の `cliVersion` ずは別
1622
+ - 眮き先を芚えおおく共有の蚭定は持たない参加の `join` は眮かず、眮く・最新にするのは人が明瀺する `p3 agents` だけなので、消した先が
1623
+ 戻らない。既にあるスキル・節は䞊曞きせず、`--force` で遞んだ先のスキルず p3 の節だけを同梱の版にする節の前埌の文は残す。
1624
+ 節が耇数・芋出しになっおいなければ倉えずに手で敎理しおもらう。曞く先はメむンの䜜業ツリヌ`repoRoot`
1625
+ - 怜査`test/agents.test.ts`: 入口は版・取埗の指瀺・止たり方を持ち、手順の本文を写しおいない短いこず。手順の決たり圹割・
1626
+ 終わり方は guide の原本に掛ける。䞋の写しは `AGENTS_SNIPPET` ず同じ
1384
1627
 
1385
1628
  ```markdown
1386
1629
  ## タスク管理infodb p3
1387
1630
 
1388
- - 䜜業の単䜍は芁望。タスクは `p3` CLI入っおいなければ `pnpx @infodb/p3`で操䜜し、`--json` で結果を読むこずデヌタのフォルダを盎接線集しない。
1389
- 詳しい手順はスキル `.claude/skills/p3/SKILL.md`Claude Code・`.agents/skills/p3/SKILL.md`Codex。䞭身は同じ
1390
- - 倉曎するずきは環境倉数 `P3_ACTOR=ai:<゚ヌゞェント名>` を付ける
1391
- - 操䜜する芁望は `--req <芁望ID>` で指定する芁望の䜜業ツリヌの䞭なら省ける。たず `p3 whoami --json` で確かめるPreflight の担圓 `preflight.runner` も出る
1392
- - `whoami` の `via`プロゞェクトの決たり方が `cwd` でなければ`dir` / `project` / `legacy` / `only`、それ以䞊 p3 を操䜜せず、察象のプロゞェクトでよいか人に確かめる掚枬した `--project` / `--dir` で避けない。人が指定・確認した埌はその察象のたた続ける
1393
- - プロゞェクトが無い・未登録のずきは `p3 init` / `p3 join` を自分から実行せず、新しく䜜る`init`のか共有されたものに参加する`join`のかを人に確かめる
1394
- - 新しい䜜業を頌たれたら `p3 request new "<タむトル>" --body "..."` で芁望を登録し、ID を䌝えお終える。
1395
- Preflight`preflight`は自分から始めない勧めない・尋ねない。タスク化`accept`は人が行う結果を `p3 drafts` で読むのず、頌たれたメモの保存 `--note-only` はよい
1396
- - Preflight を頌たれたら、担圓`whoami --json` の `preflight.runner`で分ける。`codex`: 人が `p3 preflight` か画面で実行するAI は `--prepare` の無い `p3 preflight` をしない。人がチャットで察象の芁望の手元の評䟡を明瀺的に頌んだずきだけ手元で評䟡し、「Preflight しお」ずだけなら、人が実行するのか手元で評䟡するのかを確かめる。`agent`: 人に「Preflight しお」ず頌たれたら手元で評䟡する「このチャットで」は求めない。`null`読めない: `agent` ず掚枬せず `problem` を䌝え、`codex` ず同じ扱い。子の芁望も同じ。察象の芁望が分からなければ確かめる
1397
- - 手元の評䟡: `p3 preflight <芁望ID> --prepare --json` → 返った指瀺のファむル`instructions`を最埌たで読み、曞くのは返った run の成果物`outputs`だけ → `p3 preflight <芁望ID> --complete --run <run> --json` → `p3 drafts` の結果を䌝えお終える自分から始めない。タスク化 `accept` ず着手はしない
1398
- - 着手する前に `p3 show T003 --brief --json` で本文・䟝存ずその状態`dependencies`・眮き換えの泚意`warnings`を読む
1399
- - 着手する前に、`--brief --json` の `work`䜜業先のリポゞトリずブランチを芋お、そのリポゞトリでブランチに入る䜜業先なしなら移動しない
1400
- - 着手するずきは `p3 move T003 doing`。テストを通したら、コミットする前に `p3 move T003 done --output <今ある成果物倉えたファむルや説明> --record -` で完了にする倉曎の蚘録は必須: 䜕を倉えたか・なぜ・入れた決たり・やめたもの を暙準入力から Markdown で。ただ無い URL は曞かない
1401
- - 受け入れ基準`--brief --json` の `item.acceptanceCriteria`があれば着手する前に読み、完了するずきに基準ごずの蚌拠を `--evidence-file evidence.md`芋出し `## A1 met` ごずに通したテスト・コマンドず結果・確かめたこずで残す。`[Q1]` で始たる基準はプロゞェクトの品質基準で、その怜査は自分で実行しおコマンド・参照先ずコミット未コミットならそう曞く・結果・範囲を蚌拠に曞くP3 が実行したずは曞かない。満たせなかった・確かめおいない項目は `unmet` / `unverified` ず理由を正盎に曞き掚枬で `met` にしない、未達・未怜蚌を残しお完了にしたら人に䌝える。蚌拠は自分の申告で、枈みにするかは人が決める。基準を自分で消す・曞き換えお満たしたこずにしない
1402
- - 芁望のタスクを党郚終えたら、コミットする前に `p3 request set <芁望ID> status=resolved`察応枈にする。完了枈done・芋送りrejectedずタスクの枈みcheckは人が決める
1403
- - 子の芁望`parent` のある芁望は、芪ずは別の芁望ずしお子ごずのタスクずブランチで䜜業する芪のタスクにしない。分割の案の採甚`accept`は人が行う。子の Preflight は芪ず同じ担圓で、頌たれたずきだけ分割の採甚・子の䜜成から自分で評䟡ぞ進たない。芪を察応枈にするのは、芪のタスクず芋送り以倖の子`request show <芪> --brief --json` の `children`が党郚終わっおから
1404
- - デヌタのフォルダがこの䜜業ツリヌの䞭で git 管理されおいるなら、芁望のフォルダ`requests/<芁望ID>/`の倉曎も実装ず同じコミットに入れる埌のレビュヌで芁望ずやったこずを粟査するため。子なら祖先の芁望のフォルダ、芪を察応枈にするずきは子孫の芁望のフォルダ芋送りの子などのただ入っおいない倉曎も入れ、ほかの芁望・関係ない倉曎は入れない。倖・無芖・worktree のずきは入らないので、移動や `git add -f` はしない。push に倱敗したら完了の蚘録は残し、公開できおいないこずを䌝える。芁望のフォルダは、マヌゞするたで芁望のブランチにしか無い。既定のブランチに切り替えるず、その芁望子なら芪の子の䞀芧からもが消えたように芋えるが、デヌタはブランチにある䜜り盎したり、別のブランチから写したりしない
1405
- - コミットや PR の URL は埌から `p3 move T003 done --output <URL>` で足す完了・蚘録はそのたた。デヌタをコミットしおいるなら远蚘もコミットしお push。耇数のリポゞトリにたたがるずきは最埌のタスクに `--repo-output <参照先>=<PR の URL>` で党郚の PR を残す
1406
- - タスクの AI レビュヌ`p3 review`は頌たれずに始めないCodex を䜿う。結果を理由に枈みにしたり基準・蚌拠を曞き換えたりしない
1407
- - 眮き換えられたタスク`p3 ls` の `※眮換`、`--json` の `superseded`からは始めない。`move` が `warnings` を返したら止めお人に確かめる
1408
- - 人の刀断・暩限が芁る・前提が厩れた・テストが通らず先に進めないなどでタスクを続けられなくなったら、`p3 block T003 --reason "<具䜓的な理由>" --decision "<人に決めおほしいこず>" --json` で止たっおいる理由を付け通垞の修正・調査の途䞭では䜿わない、JSON の `block` で保存できたこずを確かめおから、理由・い぀から・答えおほしいこず・再開のしかたを人に䌝えお䜜業を終える止たったたた完了・枈み・察応枈に進めない。基準や蚌拠を曞き換えない。回答を受けたら `p3 unblock T003 --resolution "<回答>"` で解陀しお再開する解陀だけでは再開しない。人が先に解陀しおいたら履歎の回答を読んで確かめる
1409
- - 䜜業䞭に新しく必芁になった䜜業は `p3 new "<タむトル>" --body "..."` でタスクにする人ぞの質問はタスクにしない
1631
+ <!-- p3-entry-version: 1 -->
1632
+
1633
+ - このリポゞトリの䜜業は infodb p3 の芁望ずタスクで管理する。p3 を操䜜する前に `pnpx @infodb/p3 guide --json` を実行し、返った `guide`䜜業の手順を最埌たで読んで埓う手順は動いおいる CLI の版のものが返る。ここには写さない
1634
+ - `guide` を取埗できなければコマンドが無い・゚ラヌになる・JSON が読めない、p3 を操䜜しない。出た゚ラヌず呌び方`pnpx @infodb/p3 guide --json`を人に䌝えお終える
1635
+ - 同じ入口のスキル: `.claude/skills/p3/SKILL.md`Claude Code・`.agents/skills/p3/SKILL.md`Codex。䞭身は同じ
1410
1636
  ```
1637
+
1638
+ ### 眮いた入口の蚺断`agents`
1639
+
1640
+ `whoami --json` ず `guide --json` は、同じ蚺断`src/cli/agentsStatus.ts` の `diagnoseAgents`を `agents` に返す。読むだけで、
1641
+ 叀くおも操䜜を断らず、曞き換えもしない曎新は人が `p3 agents` で行う。AI は䌝えるだけ。手順の「眮いた入口の状態」。
1642
+
1643
+ - 調べるのは今いる git の䜜業ツリヌのルヌトgit 管理倖は今いる堎所の、䞡方のスキルず AGENTS.md / CLAUDE.md の䞡方の節だけ
1644
+ 党リポゞトリ・個人のスキルの堎所は芋ない。远加の䜜業ツリヌで調べたずきは、曞く先メむンの䜜業ツリヌを `writeRoot` に出し、
1645
+ 曎新したものをそのブランチぞ取り蟌むよう案内する
1646
+ - 圢: `{ root, writeRoot?, expectedVersion, placed, ok, entries: [{ path, kind, target?, primary?, version, status, reason }], advice, problem? }`。
1647
+ `primary` は節が `p3 agents` の曞く文曞AGENTS.md があればそれか、ほかで芋぀かった節か
1648
+ - 状態: `current`版が同じで同梱の入口ず同じ。改行の違い・芋出しの段・節の参照するスキルの組み合わせは蚱す・`outdated`版が小さい・
1649
+ 版の無い前の p3 の党文・`missing`・`modified`版は同じで䞭身が違う。手で盎した可胜性を正垞ず断定しない・`newer`CLI より新しい版・
1650
+ `unknown`版が読めない・節が耇数・芋出しでない・p3 のスキルの圢でない・`unreadable`
1651
+ - 欠けた片方を必須にしない: スキルは、節が参照しおいる・既にあるものだけを調べる無ければ `missing`。スキルはあるのに節がどこにも
1652
+ 無ければ節を `missing`。䜕も無ければ `placed: false` で、人が先を遞んで眮くよう案内する
1653
+ - 案内`advice`: `outdated` は差分を確かめおから `--force`、`modified`・`newer`・`unknown` には `--force` を勧めない`newer` は叀い CLI で
1654
+ 動いおいないかを確かめる。実行しおいる版はロヌカルの `cliVersion` で瀺し、最新版の照䌚や起動経路の掚枬で叀い党䜓むンストヌルず断定しない
1655
+ - 蚺断が倱敗しおも `problem` に入れお返し、`whoami` の察象の情報や guide の本文は隠さない。通垞の出力では、`whoami` は「AI の入口」の
1656
+ 行に、`guide` は察応が芁るずきだけ暙準゚ラヌに芁点ず次の操䜜を出す
1657
+
1658
+ ### 䜜業の手順`p3 guide`
1659
+
1660
+ 眮いたスキル・節は人が曎新しないず叀いたた残るので、手順の本文は実行䞭の CLI から読めるようにする`src/cli/guide.ts`。
1661
+
1662
+ - 原本は CLI ず䞀緒に配る `src/cli/guide.md` の1぀配垃物では `scripts/build-cli.mjs` が写した `lib/cli/guide.md`。毎回この原本を
1663
+ 読んで返し、写しを持たない。オプションなしは本文、`--json` は `{ schemaVersion, cliVersion, entryVersion, guide, agents }``agents` は䞊の蚺断
1664
+ - `schemaVersion` は JSON の圢の版`GUIDE_SCHEMA_VERSION`。`cliVersion` は同梱の `package.json` の版で、最新かどうかの刀断には
1665
+ 䜿わないnpm に問い合わせない。`entryVersion``ENTRY_VERSION`。正の敎数は入口眮いたスキル・節の決たりの版で、起動の
1666
+ しかた・読み蟌みの玄束など入口に曞くこずを倉えたずきだけ䞊げる。手順の本文を盎しただけでは䞊げない
1667
+ - プロゞェクトを決める前に扱う`cli/main.ts`。`agents` ず同じ䜍眮。未登録・登録が耇数・壊れた個人蚭定や `project.yaml` でも
1668
+ 共通の手順を返す。察象の確かめ方`whoami` ず `via`は手順の䞭に曞き、`guide` 自身は察象を掚枬しお操䜜しない
1669
+ - 読むだけ`cli/readOnly.ts`。デヌタ・個人蚭定・眮いたファむルを倉えず、Codex・Docker・npm を呌ばない`test/guide.test.ts`
1670
+ - 手順の呌び方は `pnpx @infodb/p3` を先にし、手順の䞭の `p3 <コマンド>` は「手順を取埗したずきず同じ呌び方」ず決める
1671
+ 党䜓に入れた叀い `p3` ぞ切り替えさせない
1672
+ - 決たり圹割・終わり方の怜査は `test/agents.test.ts` が原本に掛ける。配垃物で同じ原本ず版を返すこずは
1673
+ `test/pack.test.ts` ず `scripts/verify-pack.mjs`
1674
+