@infodb/p3 0.12.0 → 0.14.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.
- package/README.md +33 -35
- package/bin/p3.mjs +3 -2
- package/dist/web/assets/CompletionReview-BD7d6Yzt.js +1 -0
- package/dist/web/assets/ImprovementDialog-BoAZN1KR.js +1 -0
- package/dist/web/assets/Outputs-D-ZouoxF.js +1 -0
- package/dist/web/assets/RequestStatus-Bl3fdSbM.js +1 -0
- package/dist/web/assets/Tabs-CxeceOL-.js +1 -0
- package/dist/web/assets/TagInput-CeAbmGRR.js +1 -0
- package/dist/web/assets/TaskDrawer-BCriSnhe.js +6 -0
- package/dist/web/assets/_requestId-CZKMe_mC.js +1 -0
- package/dist/web/assets/_requestId-Fx4lLkFo.js +1 -0
- package/dist/web/assets/appCtx-BdxbkSZa.js +1 -0
- package/dist/web/assets/archive-D5IIxcSV.js +1 -0
- package/dist/web/assets/board-p6R9KMqd.js +1 -0
- package/dist/web/assets/done-BTOF188x.js +1 -0
- package/dist/web/assets/draft-BWYpm3PD.js +2 -0
- package/dist/web/assets/index-DFbY8NAR.css +2 -0
- package/dist/web/assets/index-Dpqi2dcC.js +12 -0
- package/dist/web/assets/link-D481whDt.js +1 -0
- package/dist/web/assets/metrics-CAzP6V8I.js +1 -0
- package/dist/web/assets/new-C65IJJg3.js +1 -0
- package/dist/web/assets/outputs-CXqnjSqV.js +1 -0
- package/dist/web/assets/preflightInput-ClKwkp8R.js +2 -0
- package/dist/web/assets/preload-helper-_dAYMct_.js +1 -0
- package/dist/web/assets/{quality-Pu6EISAM.js → quality-RFd-7k3r.js} +1 -1
- package/dist/web/assets/release-notes-Dtif8xsQ.js +5 -0
- package/dist/web/assets/requestData-SPc36t8Q.js +1 -0
- package/dist/web/assets/routes-DJj8CWuk.js +6 -0
- package/dist/web/assets/settings-DKJd7CLe.js +1 -0
- package/dist/web/assets/ui-CbEOnPnF.js +1 -0
- package/dist/web/assets/workTarget-DavxMs-c.js +30 -0
- package/dist/web/index.html +6 -4
- package/docs/architecture.md +430 -72
- package/docs/chatgpt-sign-in.md +2 -2
- package/docs/development.md +141 -64
- package/docs/feature-inventory.md +139 -0
- package/docs/how-to-use.md +389 -31
- package/docs/installation.md +261 -147
- package/docs/publishing.md +33 -14
- package/docs/refactoring.md +332 -0
- package/lib/cli/agentsStatus.js +198 -0
- package/lib/cli/guide.js +27 -0
- package/lib/cli/guide.md +217 -0
- package/lib/cli/help.js +45 -7
- package/lib/cli/main.js +58 -207
- package/lib/cli/project.js +34 -294
- package/lib/core/projectRegistry.js +2 -2
- package/lib/kit/appInfo.js +13 -0
- package/lib/kit/usage.js +27 -0
- package/lib/server/api/projectsRoutes.js +5 -5
- package/lib/server/server.js +7 -4
- package/lib/{cli → tasks/cli}/args.js +73 -9
- package/lib/{cli → tasks/cli}/chatgpt.js +1 -1
- package/lib/{cli → tasks/cli}/codex.js +1 -1
- package/lib/{cli → tasks/cli}/output.js +12 -2
- package/lib/{cli → tasks/cli}/preflightCommands.js +1 -1
- package/lib/tasks/cli/readOnly.js +75 -0
- package/lib/{cli → tasks/cli}/render.js +1 -1
- package/lib/{cli → tasks/cli}/requestCommands.js +24 -7
- package/lib/tasks/cli/showView.js +279 -0
- package/lib/{cli → tasks/cli}/taskCommands.js +55 -21
- package/lib/tasks/cli/tasksCli.js +149 -0
- package/lib/{core → tasks/core}/context.js +6 -9
- package/lib/tasks/core/errorOutcome.js +125 -0
- package/lib/{core → tasks/core}/hierarchy.js +1 -1
- package/lib/{core → tasks/core}/ops.js +17 -2
- package/lib/{core → tasks/core}/preflight/carryover.js +5 -1
- package/lib/{core → tasks/core}/preflight/codexEngine.js +36 -28
- package/lib/{core → tasks/core}/preflight/diagnose.js +4 -9
- package/lib/{core → tasks/core}/preflight/engine.js +9 -0
- package/lib/tasks/core/preflight/hostPaths.js +299 -0
- package/lib/{core → tasks/core}/preflight/input.js +33 -5
- package/lib/{core → tasks/core}/preflight/instructions.js +19 -2
- package/lib/{core → tasks/core}/preflight/mockEngine.js +27 -8
- package/lib/{core → tasks/core}/preflight/render.js +22 -3
- package/lib/{core → tasks/core}/preflight/service.js +86 -11
- package/lib/{core → tasks/core}/preflight/uiRender.js +5 -2
- package/lib/{core → tasks/core}/requestOps.js +214 -17
- package/lib/{core → tasks/core}/reviewRuns.js +127 -22
- package/lib/{core → tasks/core}/store/attachments.js +3 -2
- package/lib/{core → tasks/core}/store/collection.js +21 -2
- package/lib/tasks/core/store/fieldGroups.js +30 -0
- package/lib/tasks/core/store/jsonRecord.js +30 -0
- package/lib/{core → tasks/core}/store/normalize.js +15 -10
- package/lib/{core → tasks/core}/store/noteStore.js +2 -2
- package/lib/{core → tasks/core}/store/preflightStore.js +59 -22
- package/lib/{core → tasks/core}/store/projectFile.js +1 -1
- package/lib/{core → tasks/core}/store/workspace.js +28 -6
- package/lib/{core → tasks/core}/userConfig.js +1 -1
- package/lib/{core → tasks/core}/workTargets.js +1 -1
- package/lib/tasks/features/metrics/cli/metricsCommands.js +77 -0
- package/lib/tasks/features/metrics/core/definitions.js +445 -0
- package/lib/tasks/features/metrics/core/index.js +112 -0
- package/lib/tasks/features/metrics/core/manual.js +179 -0
- package/lib/tasks/features/metrics/server/metricsRoutes.js +8 -0
- package/lib/tasks/features/metrics/shared/metrics.js +42 -0
- package/lib/{core/milestoneReview → tasks/features/milestoneReview/core}/code.js +2 -11
- package/lib/{core/milestoneReview → tasks/features/milestoneReview/core}/material.js +5 -6
- package/lib/{core/milestoneReview → tasks/features/milestoneReview/core}/review.js +2 -2
- package/lib/{core/milestoneReview → tasks/features/milestoneReview/core}/service.js +38 -100
- package/lib/{core/milestoneReview → tasks/features/milestoneReview/core}/store.js +3 -3
- package/lib/{server/api → tasks/features/milestoneReview/server}/milestoneReviewRoutes.js +7 -13
- package/lib/{cli → tasks/features/quality/cli}/qualityCommands.js +36 -11
- package/lib/{core → tasks/features/quality/core}/qualityImprovement.js +16 -15
- package/lib/tasks/features/records/cli/revisitCommands.js +73 -0
- package/lib/tasks/features/records/core/completionRefs.js +46 -0
- package/lib/tasks/features/records/core/reviewCandidates.js +76 -0
- package/lib/tasks/features/records/shared/completionRecord.js +329 -0
- package/lib/tasks/features/records/shared/reviewCandidate.js +313 -0
- package/lib/tasks/features/records/shared/reworkHistory.js +86 -0
- package/lib/{cli → tasks/features/releaseNotes/cli}/releaseNotesCommands.js +7 -7
- package/lib/{core/releaseNotes → tasks/features/releaseNotes/core}/completeRequests.js +5 -6
- package/lib/{core/releaseNotes → tasks/features/releaseNotes/core}/generate.js +3 -14
- package/lib/{core/releaseNotes → tasks/features/releaseNotes/core}/material.js +3 -4
- package/lib/{core/releaseNotes → tasks/features/releaseNotes/core}/service.js +1 -1
- package/lib/{core/releaseNotes → tasks/features/releaseNotes/core}/store.js +2 -2
- package/lib/{server/api → tasks/features/releaseNotes/server}/releaseNoteRoutes.js +11 -20
- package/lib/tasks/features/requirements/cli/requirementCommands.js +289 -0
- package/lib/{shared → tasks/features/requirements/shared}/acceptance.js +292 -18
- package/lib/tasks/features/requirements/shared/requirementSource.js +635 -0
- package/lib/tasks/features/retro/cli/retroCommands.js +106 -0
- package/lib/tasks/features/retro/core/retrospective.js +197 -0
- package/lib/tasks/features/retro/shared/retrospective.js +286 -0
- package/lib/tasks/features/settings/cli/projectSettings.js +245 -0
- package/lib/{cli → tasks/features/settings/cli}/userConfig.js +50 -3
- package/lib/{core → tasks/features/settings/core}/machineSettingsEdit.js +2 -2
- package/lib/{core → tasks/features/settings/core}/repoAdmin.js +3 -3
- package/lib/{core → tasks/features/settings/core}/userTheme.js +2 -2
- package/lib/{server/api → tasks/features/settings/server}/repoRoutes.js +2 -2
- package/lib/{server/api → tasks/features/settings/server}/userThemeRoutes.js +3 -3
- package/lib/{cli → tasks/features/taskReview/cli}/taskReviewCommands.js +5 -5
- package/lib/{core/taskReview → tasks/features/taskReview/core}/material.js +13 -7
- package/lib/{core/taskReview → tasks/features/taskReview/core}/review.js +10 -3
- package/lib/{core/taskReview → tasks/features/taskReview/core}/service.js +24 -85
- package/lib/{core/taskReview → tasks/features/taskReview/core}/store.js +4 -4
- package/lib/{server/api → tasks/features/taskReview/server}/taskReviewRoutes.js +7 -14
- package/lib/{server → tasks/server}/api/manifest.js +51 -3
- package/lib/{server → tasks/server}/api/routes.js +134 -65
- package/lib/tasks/shared/commitRefs.js +10 -0
- package/lib/{shared → tasks/shared}/preflightInput.js +1 -1
- package/package.json +1 -43
- package/skills/p3/SKILL.md +9 -181
- package/dist/web/assets/ImprovementDialog-kQaVBGWH.js +0 -1
- package/dist/web/assets/Outputs-_nU_p3nu.js +0 -1
- package/dist/web/assets/RequestStatus-RG-OVQYY.js +0 -1
- package/dist/web/assets/Tabs-ew9i5SKX.js +0 -1
- package/dist/web/assets/TagInput-BtlJTF7i.js +0 -1
- package/dist/web/assets/TaskDrawer-DW8GyJqI.js +0 -6
- package/dist/web/assets/_requestId-6Nb727dD.js +0 -1
- package/dist/web/assets/_requestId-BykTgPax.js +0 -1
- package/dist/web/assets/appCtx-CxDdXABS.js +0 -1
- package/dist/web/assets/archive-Ckh295Xe.js +0 -1
- package/dist/web/assets/board-BVAIjK-Y.js +0 -1
- package/dist/web/assets/done-BGfA-3MA.js +0 -1
- package/dist/web/assets/draft-CfJeyLOl.js +0 -1
- package/dist/web/assets/index-CgRU744I.css +0 -2
- package/dist/web/assets/index-DacQ0yl4.js +0 -12
- package/dist/web/assets/new-DVygWvVc.js +0 -1
- package/dist/web/assets/outputs-B6xDsLZf.js +0 -1
- package/dist/web/assets/preflightInput-BAeEJYUK.js +0 -2
- package/dist/web/assets/preload-helper-DyCqp21K.js +0 -1
- package/dist/web/assets/release-notes-CCpzyiNf.js +0 -5
- package/dist/web/assets/requestData-D5vBnuMh.js +0 -1
- package/dist/web/assets/routes-Q91zvNc0.js +0 -4
- package/dist/web/assets/settings-BzRgcmUm.js +0 -1
- package/dist/web/assets/workTarget-C9c57JAO.js +0 -30
- package/lib/cli/readOnly.js +0 -38
- package/lib/cli/showView.js +0 -166
- /package/lib/{core/store → kit}/frontmatter.js +0 -0
- /package/lib/{core/store → kit}/fsutil.js +0 -0
- /package/lib/{cli → tasks/cli}/format.js +0 -0
- /package/lib/{core → tasks/core}/chatgpt.js +0 -0
- /package/lib/{core → tasks/core}/machineSettings.js +0 -0
- /package/lib/{core → tasks/core}/preflight/codexImage.js +0 -0
- /package/lib/{core → tasks/core}/preflight/docker.js +0 -0
- /package/lib/{core → tasks/core}/preflight/launch.js +0 -0
- /package/lib/{core → tasks/core}/preflight/launcher.mjs +0 -0
- /package/lib/{core → tasks/core}/preflight/mock-ui.html +0 -0
- /package/lib/{core → tasks/core}/preflight/mock-ui.png +0 -0
- /package/lib/{core → tasks/core}/preflight/owner.js +0 -0
- /package/lib/{core → tasks/core}/preflight/render-image/Dockerfile +0 -0
- /package/lib/{core → tasks/core}/preflight/render-image/fonts-ja.conf +0 -0
- /package/lib/{core → tasks/core}/preflight/render-image/render.mjs +0 -0
- /package/lib/{core → tasks/core}/preflight/split.js +0 -0
- /package/lib/{core → tasks/core}/preflight/uiMaterials.js +0 -0
- /package/lib/{core → tasks/core}/preflight/wireframe.js +0 -0
- /package/lib/{core → tasks/core}/preflight/xlsx.js +0 -0
- /package/lib/{core → tasks/core}/redact.js +0 -0
- /package/lib/{core → tasks/core}/repoRefs.js +0 -0
- /package/lib/{core → tasks/core}/requestStatus.js +0 -0
- /package/lib/{core → tasks/core}/store/archivedTasks.js +0 -0
- /package/lib/{core → tasks/core}/store/dataWatcher.js +0 -0
- /package/lib/{core → tasks/core}/store/locate.js +0 -0
- /package/lib/{core → tasks/core}/supersede.js +0 -0
- /package/lib/{core/milestoneReview → tasks/features/milestoneReview/core}/mockReviewer.js +0 -0
- /package/lib/{shared → tasks/features/milestoneReview/shared}/milestoneReview.js +0 -0
- /package/lib/{core → tasks/features/quality/core}/quality.js +0 -0
- /package/lib/{shared → tasks/features/quality/shared}/quality.js +0 -0
- /package/lib/{shared → tasks/features/quality/shared}/qualityImprovement.js +0 -0
- /package/lib/{shared → tasks/features/quality/shared}/qualityTemplates.js +0 -0
- /package/lib/{core/releaseNotes → tasks/features/releaseNotes/core}/mockSummarizer.js +0 -0
- /package/lib/{core/taskReview → tasks/features/taskReview/core}/mockReviewer.js +0 -0
- /package/lib/{core/taskReview → tasks/features/taskReview/core}/paths.js +0 -0
- /package/lib/{shared → tasks/features/taskReview/shared}/taskReview.js +0 -0
- /package/lib/{server → tasks/server}/api/chatgptRoutes.js +0 -0
- /package/lib/{server → tasks/server}/api/local.js +0 -0
- /package/lib/{shared → tasks/shared}/dates.js +0 -0
- /package/lib/{shared → tasks/shared}/directTask.js +0 -0
- /package/lib/{shared → tasks/shared}/hierarchy.js +0 -0
- /package/lib/{shared → tasks/shared}/milestoneGoals.js +0 -0
- /package/lib/{shared → tasks/shared}/milestoneOrder.js +0 -0
- /package/lib/{shared → tasks/shared}/preflightRunner.js +0 -0
- /package/lib/{shared → tasks/shared}/refs.js +0 -0
- /package/lib/{shared → tasks/shared}/repos.js +0 -0
- /package/lib/{shared → tasks/shared}/scopeView.js +0 -0
- /package/lib/{shared → tasks/shared}/tags.js +0 -0
- /package/lib/{shared → tasks/shared}/taskBlock.js +0 -0
- /package/lib/{shared → tasks/shared}/types.js +0 -0
- /package/lib/{shared → tasks/shared}/workTarget.js +0 -0
package/docs/architecture.md
CHANGED
|
@@ -318,13 +318,14 @@ include: true
|
|
|
318
318
|
- 手元のリポジトリの場所はマシンごとに違うので、プロジェクトのデータではなく個人設定に持たせる
|
|
319
319
|
- **操作するプロジェクトは環境変数では決めない**(同じ人が複数のプロジェクトを行き来するため)。
|
|
320
320
|
`--project <名前>` → 今いる場所(登録したリポジトリ・作業ツリー・データのフォルダの中)→ 登録が1つならそれ、の順で決め、
|
|
321
|
-
決まらなければ登録済みの一覧と選び方を出す(`src/core/store/locate.ts`)
|
|
321
|
+
決まらなければ登録済みの一覧と選び方を出す(`packages/tasks/src/core/store/locate.ts`)
|
|
322
322
|
- プロジェクトを開く共通の入口(`core/context.ts` の `openProject`。CLI も `serve` の `startServer` もここを通る)で、
|
|
323
323
|
データのフォルダと `project.yaml` があるかを確かめる(`locate.ts` の `checkDataDir`)。無ければ空のプロジェクトとして続けず
|
|
324
324
|
`DataDirError`(終了コード 1)。何も作らない。無い(ENOENT)と読めない(権限・入出力)は分けて伝える。`init`(作成)・`join`(参加)と
|
|
325
325
|
`project` は開かないので妨げない。起動した後の切断は、画面の「再読み込み」の `ReloadError`(状態は変えない)が受け持つ
|
|
326
326
|
- 登録が1つだけで決まった(`via: only`)ときは、今いる場所と関係なく当たるので読むだけにする。CLI の入口(`cli/main.ts`)で、
|
|
327
|
-
プロジェクトを開く前に、読むだけの操作(`cli/readOnly.ts` の `readsOnly
|
|
327
|
+
プロジェクトを開く前に、読むだけの操作(`cli/readOnly.ts` の `readsOnly`。載っていない操作・知らないサブコマンドは変える操作として扱う。対象の ID とサブコマンドの見分けは
|
|
328
|
+
各コマンドのハンドラと同じにし、`--sources-json` のように操作の語が無くても書き込みに変わるオプションも見る)以外を止める。
|
|
328
329
|
案内の文は `locate.ts` の `onlyRegistrationNotice`(明示の方法と移る先を示す)
|
|
329
330
|
- 使う人はフォルダや実行パスを意識しない前提で、セットアップは2段階まで・エラーは次にすることを示す、を守る
|
|
330
331
|
- 個人設定に登録していないリポジトリの中の `.p3/` も、今いる場所から上へ辿って読める(`via: legacy`。デモ・テスト・登録前の clone)。
|
|
@@ -382,7 +383,7 @@ include: true
|
|
|
382
383
|
レビューは、保存してあるマイルストーンの目的・予定機能に対して、Codex が参照先のリポジトリのコードと git の履歴を読み、実装が目的を
|
|
383
384
|
果たしているか・目的に無い変更が無いかを確かめる参考の記録(操作は [使い方ガイド](how-to-use.md#マイルストーンレビュー))。所属する
|
|
384
385
|
要望・タスクの記録は実装した人の自己申告として、どこを見るかの手がかりにする(記録の要約で終わらせない)。比較材料の抽出は
|
|
385
|
-
`
|
|
386
|
+
`features/milestoneReview/core/material.ts`(コードの材料は `code.ts`)、履歴は `features/milestoneReview/core/store.ts`、形は `features/milestoneReview/shared/milestoneReview.ts`。
|
|
386
387
|
リリースノートの材料(`releaseNotes/material.ts`)の収録の条件は変えない。
|
|
387
388
|
|
|
388
389
|
- **範囲**: マイルストーンに直接属する要望の全部の状態(見送り・未完了も)。要望の本文、各タスクの本文・状態・変更の記録・成果物の
|
|
@@ -410,7 +411,7 @@ include: true
|
|
|
410
411
|
- **保護**: 履歴のあるマイルストーンは消せず、ID も変えられない(`requestOps.ts` の `checkMilestoneRemoval`)。project.yaml を直接
|
|
411
412
|
編集して定義が消えても、履歴は孤立として一覧・閲覧できる
|
|
412
413
|
- 抽出と履歴の保存は、要望の状態・リリースノート・リリース済みを変えない
|
|
413
|
-
- **実行**(`
|
|
414
|
+
- **実行**(`features/milestoneReview/core/service.ts`・依頼文と確かめ方は `review.ts`): Preflight と同じ Codex の接続の `ask` に、材料を
|
|
414
415
|
取り出したときに読めた参照先を渡し、Preflight と同じく `/workspace/<名前>` に読むだけでマウントする(データのフォルダは渡さない。
|
|
415
416
|
認証・診断・パスの対応・使用量の上限・取消を共有)。Mock は明示したときだけで、失敗しても切り替えない。依頼文では、記録を自己申告
|
|
416
417
|
として手がかりにとどめ、予定機能ごとに実装を読んで判断する・コミットの差分から目的に無い変更を挙げる・書き込みやテストとアプリの
|
|
@@ -434,7 +435,7 @@ include: true
|
|
|
434
435
|
|
|
435
436
|
### リリースノートのデータ
|
|
436
437
|
|
|
437
|
-
マイルストーンごとに1件、`<data>/release-notes/<マイルストーンID>.md` に置く(`
|
|
438
|
+
マイルストーンごとに1件、`<data>/release-notes/<マイルストーンID>.md` に置く(`features/releaseNotes/core/`)。要望のフォルダの外に
|
|
438
439
|
置くのは、複数の要望をまとめるものだから。
|
|
439
440
|
|
|
440
441
|
- **材料**(`releaseNotes/material.ts`): マイルストーンに属する要望(アーカイブしたものは除く)を全部返し、収録するかを決める。
|
|
@@ -488,7 +489,7 @@ include: true
|
|
|
488
489
|
materialization に残してやり直しでも同じにする。今の要望(`cli/project.ts` の `currentRequest`)は、今いる参照先
|
|
489
490
|
(`locateHere`)の割当のブランチ → ブランチ名の要望 ID の順で、パスの中の要望 ID だけでは決めない(detached HEAD では決めない)。
|
|
490
491
|
git のブランチ・作業ツリーは作らない
|
|
491
|
-
- 参照先の登録・変更・削除は `core/repoAdmin.ts` に集め、CLI(`p3 repo`)と設定画面(`/api/repos`・`components/ReposPanel.tsx`)が
|
|
492
|
+
- 参照先の登録・変更・削除は `features/settings/core/repoAdmin.ts` に集め、CLI(`p3 repo`)と設定画面(`/api/repos`・`components/ReposPanel.tsx`)が
|
|
492
493
|
同じものを使う。このマシンのパスは `localOnly` でローカルの画面にだけ返し、変えられるのもローカルの画面(Origin)からだけ。
|
|
493
494
|
パスつきで足すときは、共有の定義を書く前にフォルダかを確かめる
|
|
494
495
|
- 設定画面はほかの画面と同じく画面の横幅いっぱいに使う。入力欄のラベルは短くし、補足は `Field` の `hint` で入力欄の下に出すので、
|
|
@@ -508,16 +509,69 @@ include: true
|
|
|
508
509
|
|
|
509
510
|
### マシンごとの設定と Codex の起動
|
|
510
511
|
|
|
511
|
-
- マシンごとの設定は、項目ごとに CLI の明示 → 環境変数(`P3_*`)→ 個人設定 → 既定値 で決める(`src/core/machineSettings.ts`)。
|
|
512
|
+
- マシンごとの設定は、項目ごとに CLI の明示 → 環境変数(`P3_*`)→ 個人設定 → 既定値 で決める(`packages/tasks/src/core/machineSettings.ts`)。
|
|
512
513
|
CLI と serve・Codex エンジンが同じ解決を使い、`process.env` を個人設定の値で書き換えない。`.env` はどこからも読まない
|
|
513
514
|
(P3 は pnpx などで入れるので、パッケージの場所は利用者が触らない)。項目と環境変数の対照は [導入ガイド](installation.md#設定の決まり) の「設定の決まり」
|
|
514
|
-
- マシンごとの設定の書き換え(`p3 user-config set`。`src/core/machineSettingsEdit.ts`): `キー=値` で書き、`キー=` で消し、
|
|
515
|
+
- マシンごとの設定の書き換え(`p3 user-config set`。`packages/tasks/src/features/settings/core/machineSettingsEdit.ts`): `キー=値` で書き、`キー=` で消し、
|
|
515
516
|
パスの対応は `codex.pathMap+=A=B` / `codex.pathMap-=A` で1件ずつ足し・外す(全部の置き換えは受けない。書き間違いで全部を
|
|
516
517
|
失わないように)。`updateUserConfig` の中で変更を当ててから、環境変数を見ずに `resolveMachineSettings` で確かめ、読めなければ
|
|
517
518
|
何も書かない(テーマを含めて一括)。表示(`describeSettings`)は項目ごとの効いている値と出どころ(環境変数 / 個人設定 / 既定)。
|
|
518
519
|
空の環境変数は既定に戻すので出どころも既定。プロジェクトの登録(projects)は表示しない(`p3 project ls`)
|
|
519
520
|
- パスの対応のエラー(`bind source path does not exist`)には、直し方(`pathMapHowTo`)として設定するコマンド・例・ホストの
|
|
520
521
|
パスの調べ方を添える。共有の記録に残るので、このマシンのパスは例のパスで示す。対応が当たっていたなら行き先の誤りとして案内する
|
|
522
|
+
- **マウントするパスの決め方**(`packages/tasks/src/core/preflight/hostPaths.ts` の `resolveHostPaths`。261115-d0n30): Docker のコンテナに
|
|
523
|
+
マウントするこのマシンのパスを、Docker のデーモンから見たパスに決める。求めた結果は個人設定に書かず、毎回求める。
|
|
524
|
+
ここで Docker に出すのは `docker inspect` だけ(`dockerExec` の時間の上限と取消。引数は配列)で、全部の対象が決まる前にマウントする
|
|
525
|
+
コマンドは出さない。1つでも決まらなければ `ok: false` で、呼ぶ側はコンテナを起こさない
|
|
526
|
+
|
|
527
|
+
| p3 が動いている場所 | 手で書いた対応(`codex.pathMap`)が当たる対象 | 当たらない対象 |
|
|
528
|
+
| --- | --- | --- |
|
|
529
|
+
| コンテナの外(`/proc/self/mountinfo` に自分のコンテナの ID が無く、`/.dockerenv` も無い) | 対応のとおり | 変換しない(`direct`)。Docker Desktop・WSL・リモートの Docker でも、今までどおりそのまま渡す |
|
|
530
|
+
| コンテナの中で、自分のコンテナを確かめられた | 自分のマウントから求めたものと同じならその対応、違えば止める(`conflict`) | 自分のマウントから求める(`auto`)。求められなければ止める |
|
|
531
|
+
| コンテナの中で、自分のコンテナを確かめられない | 対応のとおり(確かめていない印 `verified: false`) | 止める |
|
|
532
|
+
|
|
533
|
+
- 自分のコンテナ: `/proc/self/mountinfo` のうち Docker(と Podman)がコンテナごとに置くもの(`/etc/hostname`・`/etc/hosts`・
|
|
534
|
+
`/etc/resolv.conf`)の元の場所にある 64 桁の ID と、cgroup v1 の docker の行を候補にし、接続先のデーモンの
|
|
535
|
+
`docker inspect --type container` で `Id` が同じものを探す。接続先(`DOCKER_HOST`・`DOCKER_CONTEXT`・選んでいる context)は
|
|
536
|
+
後で `docker run` するときと同じ docker の CLI に任せる(接続先のデーモンに自分が居れば、そのデーモンがコンテナを作る)。
|
|
537
|
+
ホスト名だけ・候補の先頭だけでは決めない。見つからない(`self-not-found`。リモート・別のデーモン)、複数(`self-ambiguous`)、
|
|
538
|
+
inspect のホスト名がこのマシンと違う(`self-mismatch`)、問い合わせの失敗・時間切れ(`inspect-failed`)、ID が分からない
|
|
539
|
+
(`self-unknown`)は自動では決めない
|
|
540
|
+
- マウントの元の照合(261120-ezdk4): 見つけたコンテナの `Type: bind` ごとに、その `Destination`(リンクを辿った先)の mountinfo の
|
|
541
|
+
root が `Source` の末尾と一致しなければ自分と扱わない(`self-mismatch`)。ネットワークを共有する構成(Compose の
|
|
542
|
+
`network_mode: service:X`・`--network container:X`)では、`/etc/hostname` などの元・ホスト名・実行側の inspect の `HostnamePath` が
|
|
543
|
+
共有元 X のものになり、候補もホスト名の照合も X を指す。実機(Linux の Docker Engine 29、cgroup v2、containerd snapshotter)では、
|
|
544
|
+
同じ `Destination` に共有元が別の `Source` を付けていると X の `Source` を黙って選び、正しい手の対応は `conflict` で止まった。
|
|
545
|
+
中からは実行側の ID を得る手がかりが無い(cgroup は `0::/`、inspect に rootfs の snapshot が出ない。得るには接続先のコンテナを一覧する
|
|
546
|
+
しかなく、問い合わせを広げない)ので、自動で実行側を選ぶことはせず、照合で取り違えを見つけて止め、手の対応に任せる。
|
|
547
|
+
root が `/`(ファイルシステムの丸ごとの bind。NFS など)と、mountinfo に無いマウント先は比べない。ホストでシンボリックリンクを
|
|
548
|
+
通した bind(`Source` はリンク、root は実体)も止まる(取り違えより安全な側に倒す。導入ガイドの手順で手で書く)
|
|
549
|
+
- 1つのパスで、一番深いマウントが bind の形(root が `/` でない)なのに見つけたコンテナの `Mounts` に無いときも `self-mismatch`
|
|
550
|
+
(共有元にその `Destination` が無い構成。マウントの種類の問題ではないので、フォルダを移す案内にしない)
|
|
551
|
+
- 1つのパス: 対象の実体(シンボリックリンクを辿った先。無いところは在るところまで辿って残りを足す)を含む **一番深い** マウントを
|
|
552
|
+
mountinfo から選び、そこが inspect の `Mounts` の `Type: bind` の `Destination` のときだけ、その `Source` に残りを足す。
|
|
553
|
+
volume・tmpfs・Docker の知らないマウント(root が `/`)の下(`not-bind`)や、どのマウントの下でもない(コンテナの層。`container-layer`)は、
|
|
554
|
+
親の bind に逃げずに止める。`Source` が `/` で始まらない形(`unsupported-source`)も止める。`Source` は同じデーモンが返した
|
|
555
|
+
もので、同じデーモンにそのまま渡せる(Docker Desktop の中の DevContainer でも、Desktop を見分けて止めることはしない)
|
|
556
|
+
- 手で書いた対応は今までどおり前から順の境界一致(`mapPath`)で、元のパス(実体ではない)に当てる。自動で求めたものと食い違えば
|
|
557
|
+
手の対応で上書きせずに止める(間違った行き先がホストに在ると、違うフォルダをマウントしてしまうため)
|
|
558
|
+
- コンテナの外で変換しないのは、以前からの利用者(Mac の Docker Desktop・WSL で直接動かし、同じパスでマウントできている)を
|
|
559
|
+
止めないため。リモートの Docker を外から使うときも以前と同じくそのまま渡す(要るなら手で書く)
|
|
560
|
+
- 止める理由ごとに次にすること(`nextStep`)を1つ添える: マウントの種類の問題はフォルダを bind の下へ移す、食い違いは手の対応を
|
|
561
|
+
直すか外す、問い合わせの失敗は `docker version`、それ以外は手で対応を書く
|
|
562
|
+
- 使うところ: Preflight(`CodexWorkspaceEngine.runWith`。全部の参照先とデータを、Codex のコンテナを起こす前にまとめて決める)、
|
|
563
|
+
参照先を読む ask(リリースノートの要約・レビュー)、描画(`renderHtml`。実際にマウントする一時の `in`・`out` を、描画の
|
|
564
|
+
コンテナを起こす前に決める。Preflight の後・手元の評価の取り込み・`p3 render` の全部)。同期でパスを変換する口(以前の
|
|
565
|
+
`hostPath`)は持たない(自動で決めたと誤って読まれないように)。手元の評価で原稿が無いとき・Mock・要望とタスクの操作は Docker に
|
|
566
|
+
問い合わせない
|
|
567
|
+
- 決まらないときのエラーと開始のログ(共有の記録)には、対象の名前(参照先 app・データ・描画の原稿)・理由・次にすること・
|
|
568
|
+
決め方(自動 / 手の対応 / 変換なし)だけを書き、このマシンのパス・ホストのパス・自分のコンテナの ID・inspect の中身は書かない。
|
|
569
|
+
実際のパスは、このマシンで `p3 user-config paths <パス>...`(読むだけ。プロジェクトを決める前に動く)で見る。エラーはこの
|
|
570
|
+
コマンドへ案内する
|
|
571
|
+
- 手元の評価の取り込みで個人設定(パスの対応)を読めないときは、空の対応で描かずに、描けなかった理由として残す(評価は残る)
|
|
572
|
+
- `P3_HOST_PATHS=direct` は自動で決めず、コンテナの外と同じに扱う(手で書いた対応だけ)。テスト(`vitest.config.ts`)が、
|
|
573
|
+
テストを動かすマシンが DevContainer かどうかで結果を変えないために使う。自分のコンテナのマウントを使うテストは
|
|
574
|
+
`hostProbe`(`HostPathProbe`)を渡す
|
|
521
575
|
- 旧来の認証の auth.json は、P3 のイメージの中の Codex(`CODEX_HOME=/codex`)で `codex login --device-auth` すれば、ボリュームの
|
|
522
576
|
一番上にでき、そのまま `authVolume`(`volume-subpath=auth.json`)で使える(サインインそのものは人が行う)。`authFile` は Docker のホストのパスで
|
|
523
577
|
渡すので `codex.pathMap` は効かない
|
|
@@ -582,7 +636,7 @@ include: true
|
|
|
582
636
|
`web/lib/theme.ts` が持ち、`system` の間だけ `prefers-color-scheme` の変化を購読する。保存先は個人設定だけで、
|
|
583
637
|
localStorage は使わない。ほかのプロセスでの変更は読み直しで反映する
|
|
584
638
|
- 設定画面のテーマの選択は、選んだらすぐ `PUT /api/user-theme` で保存し、保存できてから画面に反映する
|
|
585
|
-
(`web/lib/themeSave.ts`。保存中に続けて選んだら、終わってから最後の選択だけを保存する。失敗したら保存済みの表示に戻す)。
|
|
639
|
+
(`features/settings/web/lib/themeSave.ts`。保存中に続けて選んだら、終わってから最後の選択だけを保存する。失敗したら保存済みの表示に戻す)。
|
|
586
640
|
- 進捗のスケジュールの狭い画面: 左の一覧の幅を枠の幅から決める(`web/lib/timeline.ts` の `leftWidth`。640px 未満で
|
|
587
641
|
枠の 36%・112〜380px、640px 以上は 380px)。スケジュールの見える幅(`scheduleSpan`)・描く期間の右端・見える範囲の判定・
|
|
588
642
|
今日への移動・ズームの中央の日付は、すべてこの幅から計算する(測る前は幅 0 で、見える幅は負にならない)。行の高さと
|
|
@@ -664,7 +718,7 @@ serve の中で起きたこと(画面からの保存、Preflight の進み具
|
|
|
664
718
|
タブ・ウィンドウに戻ったときの読み直し(POST /api/reload)で取り込む。ファイル監視は補助で、届かないことがある
|
|
665
719
|
(NFS や、Node の再帰的な監視が置き換えて保存したファイルの2回目以降の変更を通知しないことがある)。
|
|
666
720
|
|
|
667
|
-
**データのフォルダの監視**(`src/core/store/dataWatcher.ts`。`Workspace.watch` が1つだけ持ち、通常の serve と `--all-projects` の
|
|
721
|
+
**データのフォルダの監視**(`packages/tasks/src/core/store/dataWatcher.ts`。`Workspace.watch` が1つだけ持ち、通常の serve と `--all-projects` の
|
|
668
722
|
プロジェクトごとに同じものを使う): 補助なので、壊れても serve と実行中の Preflight は止めない。
|
|
669
723
|
|
|
670
724
|
- `fs.promises.watch` は使わない。Node 22 の Linux の再帰監視(JS の実装)は、見ている途中でフォルダが消えると(Preflight が
|
|
@@ -724,6 +778,28 @@ AI エージェントと進める開発を、要望を受ける → 何を作る
|
|
|
724
778
|
| 出す | リリースノート(変更の記録から要約の案を作り、人が直して保存・出力する)、マイルストーンのリリース済みの印、要望の一括完了済 | 要約の案は P3 から呼ぶ Codex(手で書いてもよい)。保存・リリース済み・一括完了は人。マージ・公開・デプロイは利用者の手元と外部の仕組み | `release-notes/<マイルストーンID>.md`(生成した案はメモリの上だけで、保存するまでファイルにならない)、リリース済みは `project.yaml`。公開物は P3 のデータの外 |
|
|
725
779
|
| 振り返って次に活かす | マイルストーンレビュー(目的・予定機能・品質基準に対してコードと履歴を読む参考の記録)、品質の不足からの改善要望の原稿、変更の記録と過去の run を次の Preflight が調べる | レビューは P3 から呼ぶ Codex。改善要望・次の要望は人か手元の AI エージェントが明示して登録する(自動では作らない) | `milestone-reviews/<マイルストーンID>/<run>/`、`quality-improvements.json`、変更の記録は `<要望>/tasks/Txxx.md` |
|
|
726
780
|
|
|
781
|
+
### 代表的な流れと、根拠を追えるということ
|
|
782
|
+
|
|
783
|
+
README の「要求・判断・実装・検証をつなぎ、その根拠を後から追える」は、上の表を1本の流れとして読んだもの。代表的には次のようにつながる。
|
|
784
|
+
|
|
785
|
+
要望 → Preflight → 実装(P3 の外)→ タスクのレビュー → マイルストーンレビュー → 人の判断
|
|
786
|
+
|
|
787
|
+
- **必須の順番ではない**: Preflight もレビューも任意で、要望から直接タスクを作ってもよい([Preflight を通さずにタスクを作る](how-to-use.md#preflight-を通さずにタスクを作る))。
|
|
788
|
+
確かめて作り直す・振り返って要望を足すように行き来し、マイルストーンレビューは何度でも実行できる。状態の遷移でもない
|
|
789
|
+
- **人の判断は最後だけではない**: 案の採用(タスク化)・済み・要望の完了済と見送り・リリースするかを、それぞれの時点で人が決める
|
|
790
|
+
- **確かめる単位が2つある**: タスクのレビューはタスクごとに受け入れ基準と品質基準を見る([タスクの AI レビュー](how-to-use.md#タスクの-ai-レビュー))。
|
|
791
|
+
マイルストーンレビューはマイルストーン全体で、目的と予定機能が果たせたかを見る([マイルストーンレビュー](how-to-use.md#マイルストーンレビュー))
|
|
792
|
+
- **検証の担当**: テスト・動作確認は作業した側が行い、P3 は実行しない。P3 に残るのは作業した側の申告(証拠)と、AI のレビューの参考の記録
|
|
793
|
+
|
|
794
|
+
「根拠を後から追える」は、次のものを後から開いて読めることを指す。
|
|
795
|
+
|
|
796
|
+
- 要望の本文と添付、Preflight の固定した評価対象・判定・確かめた根拠と推測の区別・タスク案
|
|
797
|
+
- タスクの受け入れ基準・成果物(コミットや PR の URL など)・変更の記録・基準ごとの証拠
|
|
798
|
+
- レビューの固定した材料(差分・資料)と結果
|
|
799
|
+
|
|
800
|
+
書かれなかった判断の理由や、P3 の外で起きたこと(テストの出力そのもの・会話)は残らない。正しさを保証するものではなく、確かめるための
|
|
801
|
+
材料を同じ場所にそろえるもの。
|
|
802
|
+
|
|
727
803
|
### P3 が意図して持たないもの
|
|
728
804
|
|
|
729
805
|
- **タスクの作業を AI に実行させる役**(作業の実行・並べての実行・エージェントの割り当て)。作業は利用者が選んだ手元のエージェントで
|
|
@@ -766,27 +842,91 @@ src は5つの層に分け、依存の向きを `test/layers.test.ts` で確か
|
|
|
766
842
|
| Preflight の分割(子の案の検証・子の本文・案の版・採用) | `core/preflight/split.ts`・`core/preflight/service.ts` の `adopt` |
|
|
767
843
|
| 個々の規則(対応済・置き換え・作業先とブランチ・評価対象の比べ方) | `core/requestStatus.ts`・`core/supersede.ts`・`core/workTargets.ts`・`shared/preflightInput.ts` |
|
|
768
844
|
| サーバと画面の両方で使う判定・表示名 | `shared/` |
|
|
845
|
+
| エラーから CLI の終了コード・標準エラーと API の状態・code への対応 | `core/errorOutcome.ts` の `errorOutcome`(CLI は `cliExit`、API の各アプリは `apiError` で写す。契約は `test/errorContract.test.ts`) |
|
|
769
846
|
| 画面の API の失敗の扱い(rev の競合・評価対象の変更・無い) | `web/lib/api.ts` の `failureOf` |
|
|
770
|
-
| リリースノートの本文の下書き(外の変更・削除・読めないときに入力を残す・編集を始めた版で保存) | `web/lib/releaseNoteDraft.ts` |
|
|
847
|
+
| リリースノートの本文の下書き(外の変更・削除・読めないときに入力を残す・編集を始めた版で保存) | `features/releaseNotes/web/lib/releaseNoteDraft.ts` |
|
|
771
848
|
| 読み取り(一覧・参照の解き方・進捗) | `core/ops.ts` |
|
|
772
849
|
| アーカイブしたタスクの読み取り(通常の一覧・集計に混ぜない) | `core/store/archivedTasks.ts` |
|
|
773
850
|
| レビューの実行の記録の共通部分(保存・終わり・回復・取消・遅れた結果の拒否) | `core/reviewRuns.ts` |
|
|
774
|
-
| タスクの AI レビュー(材料・履歴) | `
|
|
775
|
-
| プロジェクトの品質基準(状態・ID の振り方・操作・テンプレートと改版の差分・版) | `shared/quality.ts`・`shared/qualityTemplates.ts`(保存は `core/quality.ts` と `Workspace.writeQuality`) |
|
|
851
|
+
| タスクの AI レビュー(材料・履歴) | `features/taskReview/core/`(`material.ts`・`store.ts`) |
|
|
852
|
+
| プロジェクトの品質基準(状態・ID の振り方・操作・テンプレートと改版の差分・版) | `features/quality/shared/quality.ts`・`features/quality/shared/qualityTemplates.ts`(保存は `features/quality/core/quality.ts` と `Workspace.writeQuality`) |
|
|
776
853
|
| 作業中のタスクの止まっている理由(停止。付ける・直す・解除・履歴・止まったままの移動の拒否・壊れた値の読み方) | `shared/taskBlock.ts`(保存と状態との突き合わせは `core/requestOps.ts` の `updateTask`、集計は `core/ops.ts`) |
|
|
777
|
-
| タスクの受け入れ基準と証拠(ID
|
|
778
|
-
|
|
|
854
|
+
| タスクの受け入れ基準と証拠(ID の振り方・操作・失効・根拠の種類・不足・壊れた値の読み方)と済みの解除 | `features/requirements/shared/acceptance.ts`(済みの解除と保存は `core/requestOps.ts` の `updateTask`) |
|
|
855
|
+
| 要求の出典と確認(根拠の記録・確認の要件と状態・変更での失効・回答・確認事項の読み方・評価の資料)と、壊れた値の読み方 | `features/requirements/shared/requirementSource.ts`(要望の保存は `core/requestOps.ts` の `updateRequirement`・`saveClarifyAnswer`、基準の記録は `features/requirements/shared/acceptance.ts` の `source` 操作、評価対象の固定と比較は `core/preflight/input.ts`) |
|
|
856
|
+
| タスクの手戻りの履歴(済みの解除・完了からの再開の契機・1操作1件・壊れた値) | `features/records/shared/reworkHistory.ts`(保存は `core/requestOps.ts` の `updateTask`) |
|
|
857
|
+
| 要望の振り返り(対象の候補・確定と訂正・記録の読み方) | `features/retro/shared/retrospective.ts`(保存は `features/retro/core/retrospective.ts`) |
|
|
858
|
+
| 開発の指標(定義・対象・算出・欠損の扱い・範囲)と人が記録する値 | `features/metrics/core/definitions.ts` の `METRIC_DEFINITIONS`(範囲と材料は `features/metrics/core/index.ts`、人の記録の保存は `features/metrics/core/manual.ts`、型は `features/metrics/shared/metrics.ts`) |
|
|
859
|
+
| JSON の記録のファイルの読み書き(読むときの扱いを記録ごとに渡す・置き換えで書く) | `core/store/jsonRecord.ts` の `readJsonRecord`・`writeJsonRecord`(記録ごとの扱いの違いは [docs/refactoring.md](refactoring.md) の表) |
|
|
860
|
+
| 要望・タスクの p3 が管理する frontmatter の項目のまとまり(読む・壊れた値の書き戻し・書かない項目・入力から外す項目) | `core/store/fieldGroups.ts` の `TASK_FIELD_GROUPS`・`REQUEST_FIELD_GROUPS`(まとまりごとの検査は各 `shared/*.ts`、書き戻しの仕組みは `core/store/collection.ts` の `keepRaw`) |
|
|
861
|
+
| 要望とそのタスクの保存のロック(別のプロセスとの読み直し・書く・移すの排他) | `core/store/collection.ts` の `lock`・`core/store/workspace.ts` の `requestLock` |
|
|
862
|
+
| 完了の記録(契機・写す条件・ID の振り方・読み方・壊れた値)と参照先の取得 | `features/records/shared/completionRecord.ts`(保存は `core/requestOps.ts` の `createTask`・`updateTask`・`updateRequest`、参照先のコミットの取得は `features/records/core/completionRefs.ts`) |
|
|
863
|
+
| 見直しが必要(候補)の診断(基点・理由の種類・関係の範囲)と前提の変更の記録 | `features/records/shared/reviewCandidate.ts`(読み取り・集計は `features/records/core/reviewCandidates.ts`、前提の変更の保存は `core/requestOps.ts` の `recordPremise`) |
|
|
864
|
+
| リリースノート(材料の規則・保存・出力・要約の生成・要望の一括完了) | `features/releaseNotes/core/`(`material.ts`・`store.ts`・`service.ts`・`generate.ts`・`completeRequests.ts`) |
|
|
779
865
|
| タスクの関係(`depends_on`・`supersedes` だけ。同じ要望の中。Preflight のタスク化だけが張る) | `shared/types.ts` の `RELATION_TYPES`・`core/preflight/service.ts` の `materialize` |
|
|
780
866
|
| プロジェクトを跨ぐ serve(登録の一覧・登録世代・文脈の開閉) | `core/projectRegistry.ts`(API は `server/api/projectsRoutes.ts`) |
|
|
781
867
|
| Preflight を通さずにタスクを作る道の案内(付かないものの言い方・失敗と取消の見分け。取消は `PREFLIGHT_CANCELLED` で残す) | `shared/directTask.ts`(CLI の案内文は `cli/output.ts` の `directTaskHint`) |
|
|
782
868
|
| マイルストーンの表示の順(ID のバージョンの降順。CLI・API・画面の一覧と選ぶ欄。project.yaml の順は変えない) | `shared/milestoneOrder.ts` |
|
|
783
|
-
| マイルストーンレビュー(材料の範囲・履歴の保存・依頼文と結果の確かめ方・実行の排他と回復) | `
|
|
869
|
+
| マイルストーンレビュー(材料の範囲・履歴の保存・依頼文と結果の確かめ方・実行の排他と回復) | `features/milestoneReview/core/`(`material.ts`・`store.ts`・`review.ts`・`service.ts`) |
|
|
784
870
|
| マイルストーンの目的・予定機能(件数・文字数・空・重複・ID の振り方) | `shared/milestoneGoals.ts`(保存の排他と版の照合は `core/store/workspace.ts` の `saveProject`) |
|
|
785
871
|
|
|
786
|
-
CLI は `cli/main.ts
|
|
872
|
+
CLI は `cli/main.ts`(入口: 引数の解釈・プロジェクトの決定・登録が1つだけのときの抑止・serve・help・guide・init・join・agents)、
|
|
873
|
+
`cli/tasksCli.ts`(tasks: プロジェクトを開いた後の振り分けとエラーから終了コードへの対応)と、種類ごとのコマンド(`taskCommands.ts`・
|
|
787
874
|
`requestCommands.ts`・`preflightCommands.ts`)に分ける。大きい画面は、ルートのファイルを組み立てだけにして部品を
|
|
788
875
|
`web/components/<ページ>/` に分ける。
|
|
789
876
|
|
|
877
|
+
## パッケージの構成
|
|
878
|
+
|
|
879
|
+
p3 をいくつかの製品(今の機能の p3-tasks、将来の p3-observer など)を選んで組み合わせる形にするため、リポジトリを pnpm workspace にし、
|
|
880
|
+
コードを 3 つのパッケージに分ける(要望 261119-9d1zk。どの機能をどこに置くかの根拠は [機能の棚卸し](feature-inventory.md) の判断表)。
|
|
881
|
+
|
|
882
|
+
| パッケージ | 中身 | 読み込んでよいもの |
|
|
883
|
+
| --- | --- | --- |
|
|
884
|
+
| 入口 `@infodb/p3`(`packages/p3`) | 配布(`bin/p3.mjs`・npm の `@infodb/p3`・Docker)・CLI の振り分け・help・guide とスキル(置く・診断)・init / join / project・serve の組み立て・画面の外枠(`__root`・プロジェクトの選択) | tasks・kit |
|
|
885
|
+
| `@infodb/p3-tasks`(`packages/tasks`) | 今の p3 の機能(要望・タスク・Preflight・レビュー・振り返り・指標・リリースノート・品質・設定・参照先・保存・画面のページ・API) | kit |
|
|
886
|
+
| `@infodb/p3-kit`(`packages/kit`) | 入口と製品が使う最小限の共通処理 | なし |
|
|
887
|
+
|
|
888
|
+
- 入口は、知っている製品(今は tasks だけ)をはっきり呼んで組み込む。製品を探して読み込む仕組み(プラグインの基盤)は作らない
|
|
889
|
+
- tasks は入口を読み込まない。入口のもの(置いた AI 向けの入口の診断など)が要るときは、入口から値や関数で渡す(`cli/tasksCli.ts` の `TasksRun`)
|
|
890
|
+
- 将来の製品どうしは直接読み込まない。連携が要るなら kit の小さな約束事を通す。p3-observer は名前だけを決め、データは自分のサブフォルダ
|
|
891
|
+
(`.p3/observer/` の想定)だけを持つ(tasks のデータに触れない)
|
|
892
|
+
- 今の `shared` は「画面と Node の両方から読める」という層の規則で、tasks 固有の型が多い。まるごと kit にはしない
|
|
893
|
+
- パッケージの間はパッケージ名(`@infodb/p3-tasks/core/context.ts` のように、そのパッケージの `src` からのパス)で読み、相対パスで別の
|
|
894
|
+
パッケージのファイルを指さない。読むパッケージは manifest に workspace の参照で書く。境界は `test/packageBoundary.test.ts` が確かめる
|
|
895
|
+
(入口 → tasks → kit の一方向・相対パスでの迂回・manifest の宣言・kit の処理に使い手がいること・observer のパッケージがまだ無いこと)。
|
|
896
|
+
層の向き(shared ← core ← server / cli、web → shared)は入口と tasks の `src` の中で同じに分け、パッケージ名で読んだ先も
|
|
897
|
+
`test/layers.test.ts` が照らす
|
|
898
|
+
- 配るのは入口の `@infodb/p3` の1つで、kit・tasks は公開せずにビルドして同梱する(`lib/tasks/`・`lib/kit/`。パッケージ名の import は同梱した先への
|
|
899
|
+
相対パスに書き換える。`scripts/build-cli.mjs`)。利用者から見える名前・コマンド・データの場所・CLI・API・画面は変えない。Docker も同じ中身を使う
|
|
900
|
+
([開発ガイド](development.md#npm-で配る中身))
|
|
901
|
+
- 画面は入口でビルドする。ルート一覧は入口の `__root.tsx` の下に tasks のページのフォルダをそのまま付け(`tsr.config.json` の
|
|
902
|
+
`virtualRouteConfig`)、入口が知っている製品のページだけが入る
|
|
903
|
+
- tasks の中は、層ごとの共通の土台と機能のまとまり(`features/<機能>/{shared,core,cli,server,web}`)に分ける。機能の中身はその機能・組み立ての場所・
|
|
904
|
+
入口の層と画面の組み合わせだけが読み、機能の core どうしと循環は禁止(`test/featureBoundary.test.ts`)。配置・規則・まとめた仕組みと残した理由・前後の
|
|
905
|
+
計測は [docs/refactoring.md](refactoring.md)
|
|
906
|
+
- 製品ごとの設計: tasks の設計と規則はこの文書の残りの節(作業の単位・Preflight・受け入れ基準など)。kit は下の「kit の中身と使い手」。
|
|
907
|
+
p3-observer は名前を予約しただけで、パッケージも設計もまだ無い(作るときは `packages/observer` に置き、データは `.p3/observer/` だけを持つ)
|
|
908
|
+
|
|
909
|
+
**機能(棚卸しの ID)ごとの置き場所**(パスは各パッケージの `src` からの相対。入口なら `packages/p3/src/`、tasks なら `packages/tasks/src/`)
|
|
910
|
+
|
|
911
|
+
| 棚卸し | 置き場所 | 分け方・今の置き方 |
|
|
912
|
+
| --- | --- | --- |
|
|
913
|
+
| F01 起動・振り分け・help・静的配信 | 入口 | `bin/p3.mjs`・`cli/main.ts`・`cli/help.ts`・`server/server.ts`。tasks のコマンドは `cli/tasksCli.ts` の `runTasksCommand`、終了コードは `reportError` を呼ぶ |
|
|
914
|
+
| F02 配布物の確認 | 入口 | `scripts/verify-*.mjs`・`scripts/check-browser.ts`・`docs/publishing.md` |
|
|
915
|
+
| F03 AI 向けの入口・guide・診断 | 入口 | `cli/project.ts`(置く)・`cli/guide.ts`・`cli/agentsStatus.ts`・`skills/`。手順の本文 `cli/guide.md` は tasks の運用の手順だが、`p3 guide` が同梱の原本を返すので当面は入口と一緒に置く |
|
|
916
|
+
| F04 登録・参加・プロジェクトの決定・読む/書くの判定 | 分ける | 入口: `cli/project.ts`(init・join・project)。tasks: `features/settings/cli/projectSettings.ts`(`config`・`repo`・変更者・今いる参照先・今の要望)・`cli/readOnly.ts`(コマンドごとの読む/書く。入口が呼ぶ)・`core/store/locate.ts`(決め方とデータの検査。入口が呼ぶ) |
|
|
917
|
+
| F05 個人設定・マシンごとの設定・変更者 | tasks(kit の候補) | `core/userConfig.ts`・`core/machineSettings*.ts`・`features/settings/cli/userConfig.ts`。Codex の設定・テーマ・パスの対応と同じファイルで扱っているので、今の既定値・出どころ・保存を変えないために当面は tasks。2 つ目の製品が個人設定を使うときに、入出力だけを kit に分ける |
|
|
918
|
+
| F06 置き換え書き込み・ロック・frontmatter | kit | `fsutil.ts`・`frontmatter.ts`(`packages/kit/src/`)。今は tasks(要望・タスク・run・指標・設定の保存)が使い、将来の製品の保存も使う見込み。採番・正規化・アーカイブは tasks |
|
|
919
|
+
| F07 serve・プロジェクトの切り替え・ナビゲーション・テーマ・表示部品 | 分ける | 入口: `server/server.ts`・`server/api/projectsRoutes.ts`・`core/projectRegistry.ts`・`web/{main,Boot,App,router}.tsx`・`web/routes/__root.tsx`・`web/components/{ProjectSwitcher,ProjectChooser}.tsx`。tasks: API(`server/api/routes.ts` ほか)・ページ・`server/api/local.ts`。表示部品 `web/components/ui.tsx` とテーマ(`ThemePanel`・`features/settings/core/userTheme.ts`・`features/settings/server/userThemeRoutes.ts`)は、設定画面(tasks のページ)が使うので当面は tasks に置き、入口が読み込む。2 つ目の製品が使うときに kit に移す |
|
|
920
|
+
| F08 変更の監視・通知・読み直し | tasks | `core/store/dataWatcher.ts`(`Workspace` が使う)・`server/api/routes.ts` の `/events`・`/reload`。プロジェクトを跨ぐ通知は入口の `projectsRoutes.ts`。監視の仕組みを製品で共有するのは 2 つ目の製品が出てから |
|
|
921
|
+
| F09 AI 向けの API の説明 | tasks | `server/api/manifest.ts`。入口の `projectsRoutes.ts` も同じ説明を返す |
|
|
922
|
+
| F10〜F25・F27 | tasks | 判断表の根拠のパスのまま |
|
|
923
|
+
| F26 AI 接続・実行環境 | tasks(暫定) | `cli/{codex,chatgpt}.ts`・`core/chatgpt.ts`・`core/preflight/{codexEngine,docker,hostPaths}.ts`。入口は `codex`・`chatgpt`・`render` のコマンドをプロジェクトを決める前に tasks の関数で動かす |
|
|
924
|
+
| F28 独立した観測 | なし | パッケージの名前(observer)だけを予約する |
|
|
925
|
+
|
|
926
|
+
**kit の中身と使い手**(`packages/kit/src/`): `usage.ts`(使い方の誤り `UsageError`・パスの展開・git の小物。入口と tasks が使う)、
|
|
927
|
+
`appInfo.ts`(動いている p3 の版。入口が起動のときに渡し、tasks が Codex に名乗る版として読む)、`fsutil.ts`・`frontmatter.ts`(置き換え書き込み・
|
|
928
|
+
ロック・frontmatter。tasks が使う。将来の製品の保存も使う見込み)。使い手のいない処理を先回りして kit に置かない。
|
|
929
|
+
|
|
790
930
|
## サーバに置かない理由
|
|
791
931
|
|
|
792
932
|
1. **Codex の置き場所が決まらない。** サーバ側で Codex を動かすと共有アカウントになる(OpenAI の規約上も避けたい)。
|
|
@@ -804,7 +944,7 @@ CLI は `cli/main.ts`(振り分け・プロジェクトと変更者の決定
|
|
|
804
944
|
認証情報は各自の ChatGPT の接続か `auth.json`(個人の場所に置き、プロジェクトには置かない)。
|
|
805
945
|
- 結果は戻り値ではなく **ファイル**(要望のフォルダの `preflight/<RUN>/assessment.json`, `drafts/*.md`)。
|
|
806
946
|
同期すればチームの全員が同じ評価とタスク案を見られる。誰が実行したかは `run.json` とタスクの `updatedBy` に残る。
|
|
807
|
-
- 画面資料(`preflight/<RUN>/ui/`)もファイル契約にする(`src/core/preflight/uiMaterials.ts`)。AI(Codex・手元の
|
|
947
|
+
- 画面資料(`preflight/<RUN>/ui/`)もファイル契約にする(`packages/tasks/src/core/preflight/uiMaterials.ts`)。AI(Codex・手元の
|
|
808
948
|
エージェント)は画面の原稿(`ui/src/U1.html` …)と `ui/index.json` を書き、P3 が原稿を描画のコンテナで PNG にして `ui/index.json` に
|
|
809
949
|
書き足す([画面イメージの描画のイメージ](#画面イメージの描画のイメージ)。AI は画像を作らない)。P3 は取り込む前に確かめて `run.json` の `ui` に記録する。画像の形式と大きさは拡張子ではなく
|
|
810
950
|
中身から読み、配信のときも同じ確かめ方をもう一度する(取り込んだ後に差し替えられた画像は返さない)。画像は
|
|
@@ -847,7 +987,7 @@ CLI は `cli/main.ts`(振り分け・プロジェクトと変更者の決定
|
|
|
847
987
|
追加で許す保証ではない。コマンドの実行は禁止していない。参照先は読むだけのマウントで書けない。データのフォルダ(`/data`)は
|
|
848
988
|
書けるマウントなので、「run の中だけ」は指示と事後の警告で守っている(書き込みを run に閉じ込める囲いは今は無い)。
|
|
849
989
|
画面イメージの描画は、この Codex のコンテナではなく別のコンテナで行う
|
|
850
|
-
- 指示(制約 = Codex の `developerInstructions` と、依頼文)は `src/core/preflight/instructions.ts` の1か所で作る。評価の観点・
|
|
990
|
+
- 指示(制約 = Codex の `developerInstructions` と、依頼文)は `packages/tasks/src/core/preflight/instructions.ts` の1か所で作る。評価の観点・
|
|
851
991
|
履歴の調べ方・分割・出力の形・画面の原稿の書き方の原本はここだけに置き、エンジンごとに複製しない。実行環境ごとに違うのは
|
|
852
992
|
パスと「何が強制されているか」だけで、`InstructionEnv` として注入する:
|
|
853
993
|
- `containerEnv`(Codex): 参照先は `/workspace/<mount>`、データは `/data`。書き込みは run の配下だけ、と指示する
|
|
@@ -868,7 +1008,7 @@ CLI は `cli/main.ts`(振り分け・プロジェクトと変更者の決定
|
|
|
868
1008
|
プロセスと、落ちたプロセスが残した run」)
|
|
869
1009
|
- 取り込みは成果物を先に確かめ(`localProblems`)、問題があれば run を変えずに断る(`local.rejected` を数えるだけ)。通ったら画面の
|
|
870
1010
|
原稿を描き、通常と同じ `ingest`・`finish` で完了にする。取り込みも取消も `lastPreflight` は変えない
|
|
871
|
-
- **実行しているプロセスと、落ちたプロセスが残した run**(`src/core/preflight/owner.ts`、`service.ts` の `busy`・`recoverRequest`・
|
|
1011
|
+
- **実行しているプロセスと、落ちたプロセスが残した run**(`packages/tasks/src/core/preflight/owner.ts`、`service.ts` の `busy`・`recoverRequest`・
|
|
872
1012
|
`recover`・`finishLocked`): serve・CLI が途中で落ちると、codex / mock の run は `running` のまま残る。以前は開始から 35 分たったら
|
|
873
1013
|
落ちたものとみなして始め直せたが、生きている長い実行と重なりうるうえ、画面からは何分たっても始め直せなかったのでやめた
|
|
874
1014
|
- 記録: 始めるとき(`open`)に `run.json` の `owner` と `before`(始める前の要望のステータス)を残す。`owner` は `instance`(ローカルの
|
|
@@ -900,7 +1040,7 @@ CLI は `cli/main.ts`(振り分け・プロジェクトと変更者の決定
|
|
|
900
1040
|
|
|
901
1041
|
要望のタイトルと本文は、Preflight の前後・実行中・完了済を含め、いつでも書き換えられる(`p3 request set --body` / `title=`、
|
|
902
1042
|
API の PATCH。`rev` で楽観ロック)。書き換えても状態・既存のタスク・過去の run は変えない。そのかわり、古い評価からはタスク化しない
|
|
903
|
-
(`src/core/preflight/input.ts`)。
|
|
1043
|
+
(`packages/tasks/src/core/preflight/input.ts`)。
|
|
904
1044
|
|
|
905
1045
|
- **固定**: Preflight を始めるとき、要望をディスクから読み直し(監視していない外部の編集も取り込む)、タイトルと本文を
|
|
906
1046
|
`run.json` の `input` に固定する。人が読む `request.md` とエンジンに渡す要望も同じ内容にする。実行中に要望が書き換えられても、
|
|
@@ -920,6 +1060,11 @@ API の PATCH。`rev` で楽観ロック)。書き換えても状態・既存
|
|
|
920
1060
|
- **再評価**: いつもどおり前回の結果とメモを引き継ぎ、前回の評価のあとでタイトル・本文が変わっていれば、`carryover.md` に
|
|
921
1061
|
「前回の評価のあとで変わった要望」として前回の時点の内容を書く。評価の基準は今の要望で、前回の評価・案・メモとの食い違いは
|
|
922
1062
|
確認事項に入れさせる。白紙の再評価や履歴の消去は作らない(前回を引き継がせたくなければ、メモでそう書く)
|
|
1063
|
+
- **要求の出典と確認**: 要望の根拠の記録(`requirementSources`)と確認事項への回答(`clarifyAnswers`)も `input.requirement` に固定し、
|
|
1064
|
+
`request.md`(本文の後に P3 が固定した資料として)とエンジンへの依頼文に同じ内容を入れる。比べるときは記録の日時・保存者を除いた中身で、
|
|
1065
|
+
変われば `changed` に `requirement`。`input.requirement` の無い以前の run は、今の要望にも記録・回答が無ければ同じとみなし、あれば変わった
|
|
1066
|
+
とみなす。固定した値が壊れていれば unknown(以前の run は書き換えない)。子の要望の hash(`inputHash`)にも、記録・回答があるときだけ足す
|
|
1067
|
+
(無ければ以前と同じ値)。今の要望の記録・回答が読めなければ Preflight を始めない
|
|
923
1068
|
- **限界**: 比べるのは「始めたとき」と「タスク化の直前」。タスク化の途中に別のプロセスが本文を書き換えることまでは排他しない
|
|
924
1069
|
(同じ要望を同時に触るときの調整は、これまでどおり人が行う)
|
|
925
1070
|
- **戻し方**: 古い評価でタスク化したいときは、要望を評価した時点の内容(`request.md`)に戻す。今の内容でよければ再評価する
|
|
@@ -928,10 +1073,53 @@ API の PATCH。`rev` で楽観ロック)。書き換えても状態・既存
|
|
|
928
1073
|
いなければ baseRev を進め、変わっていれば競合として知らせる)。未保存のタイトル・本文がある間は Preflight の実行とタスク化を止める。
|
|
929
1074
|
タスク化の 409 は `code` で分ける(`stale_input` はサーバの理由をそのまま、`rev_conflict` は置き換えの候補の読み直し)
|
|
930
1075
|
|
|
1076
|
+
### 要求の出典と確認
|
|
1077
|
+
|
|
1078
|
+
外部の評価(課題 B)への対応: 要求そのものが間違っている場合、リポジトリと履歴を読んでも正解は分からない。Preflight には無理に正解を
|
|
1079
|
+
出させず、根拠が足りないことと誰に何を確かめるかを示させ、実装から独立した正解の根拠を人が残せるようにする(`features/requirements/shared/requirementSource.ts`)。
|
|
1080
|
+
|
|
1081
|
+
- **持ち物**: 要望の `requirementSources`(`[{id: S1, target?, source?, basis?, confirmed?, history?, recordedAt, recordedBy}]`)・`requirementSeq`・
|
|
1082
|
+
`clarifyAnswers`。タスクとタスク案の `acceptanceSources`(同じ記録に `criterionId`。基準の中ではなく別に持つので、id と text で基準を組み直す
|
|
1083
|
+
旧画面・旧 CLI の編集でも消えない)。どれも任意で、無いのは未記録。既存の品質基準の出典(`quality`)・実装後の証拠の `basis`・AI の調べた箇所
|
|
1084
|
+
(`PreflightAssessment.evidence`)とは別のもの
|
|
1085
|
+
- **確認**: `confirmed` は確かめた人(役割名・アクター名の文字列)・日(利用者が書く `YYYY-MM-DD`)と、確認したときの対象文・出典・根拠・
|
|
1086
|
+
対象(要望の題と本文、基準の文)の hash を固定する。確認の記録には出典・根拠・人・日が要る(下書きは要らない)。保存の操作者(`recordedBy`・
|
|
1087
|
+
`updatedBy`)は業務上の確認者と別に残す
|
|
1088
|
+
- **状態**(共通関数 `sourceState`・`overallState`): 未記録 / 未確認 / 確認記録あり / 再確認が必要 / 対応先不明。保存するたび(要望の題・本文、
|
|
1089
|
+
記録、基準の文の変更)に、確認したときと違う確認を `history` へ移す(`settleSources`)。だから文を元に戻しても確認記録ありに戻らない。
|
|
1090
|
+
直接編集で中身だけ変えた場合も、比べると違うので再確認が必要と出る。基準を消した記録・写した元の無い記録は対応先不明として残す
|
|
1091
|
+
- **ID**: 記録の ID(`S1, S2, ...`)は消した ID を使い直さない。要望は振った最後の番号を `requirementSeq`、タスクとタスク案は
|
|
1092
|
+
`acceptanceSourceSeq`(基準をまたいでタスク・案で1つ)に残し、p3 が書く(PATCH・操作の入力からは上書きしない)。同じ操作の中で足して
|
|
1093
|
+
消したなど中身が同じでも番号が進めば番号だけを書き、済み・完了の記録・手戻りは中身の変化として扱わない。タスク化は案の番号を引き継ぐ
|
|
1094
|
+
(写さなかった記録の番号も使わない)。案の更新は読み直し・競合の確認・採番・保存を同じロック(案ごと)の中で行う。壊れた番号は
|
|
1095
|
+
`acceptanceProblems` に理由を出し、根拠の操作を断り、関係のない更新ではファイルの元の値のまま書き戻す(壊れた根拠と、置き換えない
|
|
1096
|
+
壊れた基準も同じ)。案の更新の応答は、保存したファイルを再読込と同じ規則(`PreflightStore.loadDraft`。中は `loadDrafts` と同じ
|
|
1097
|
+
`draftOf`)で読み直したもので、更新した直後と再読込で、読めた基準・根拠・採番と理由(各1回)が同じになる。基準を置き換えれば古い
|
|
1098
|
+
基準の理由は消え、根拠・採番の理由は直すまで残る(タスク化は理由を添えて断る)。261120-0pys5
|
|
1099
|
+
番号を残す前の旧データは、今ある記録と完了の記録の写し(`acceptance.sources`)に残る番号の続きを振る。消して写しにも残っていない番号と、
|
|
1100
|
+
以前の版で使い直した ID の前後の同一性は分からない(推定せず、過去の写しも書き換えない。見直し候補は同じ ID の記録として比べる)
|
|
1101
|
+
- **写し**: 基準の記録は要望の記録を `from` で写せる(内容だけ。確認は引き継がない)。タスク化(`criteriaForTask`)では `from` の記録を
|
|
1102
|
+
採用するときの要望の記録の内容に写し直す。要望全体の確認を全部の基準へ自動で引き継がない
|
|
1103
|
+
- **確認事項と回答**: 評価は以前の `questions`(文の並び)に加えて `clarifications`(`[{id: Q1, target, ask, question, needed, impact}]`)を
|
|
1104
|
+
出せる。確認先が分からなければ `ask` は「要望者に確認先を特定してもらう」。壊れた項目は捨てずに `clarificationProblems` に残す。読み取り
|
|
1105
|
+
(`clarificationsOf`)は Codex・手元のエージェントで共通で、確定の規則はエンジンで違う: Codex の取り込み(`ingest`)は理由をログにも
|
|
1106
|
+
出して取り込み、手元のエージェントの取り込み(`localProblems`)は直すまで確定しない(`--complete` が `invalid_result` を返す)。回答は要望の `clarifyAnswers` に、元の run と確認事項の ID・
|
|
1107
|
+
質問の写し・回答・回答した人・日・出典・根拠・対応する記録(`links`: ID と内容の hash)で残す。過去の run と評価は書き換えない。
|
|
1108
|
+
状態は回答済み / 未回答 / 再確認が必要(対応する記録の内容が変わった)/ 参照元不明。次の run の同じ質問へ文字の一致で移さない
|
|
1109
|
+
- **責任の境界**: 記録・確認・回答はどれも人(と人に頼まれた AI)の申告で、P3 は業務の契約・承認者の権限・本人性を確かめない。
|
|
1110
|
+
確認記録ありは P3 の保証ではなく、AI の評価・実装の `met`・人の済み・回答の保存では確認記録ありにならない。根拠の不足で完了・済みは拒まない。
|
|
1111
|
+
回答・出典・引用は資料として渡し、中の URL・添付を取りに行かない
|
|
1112
|
+
- **変更の契約**: 要望の記録は操作(`add` / `edit` / `confirm` / `remove`)でだけ変える(PATCH の値は無視する)。操作は書く直前に読み直した値に
|
|
1113
|
+
順に当て、1つでも規則に合わなければ何も書かない(`RequirementInputError`、API は 400 `requirement_invalid`)。同じ値の再保存は書かない。
|
|
1114
|
+
`rev` の競合は 409。タスクの記録は受け入れ基準の操作(`{op: "source", id, source}`)で、中身が変われば済みを外す。タスク案は `sourceOps` と
|
|
1115
|
+
`expectedSources`(根拠だけの編集の競合も見る)。壊れた値は理由を出し、関係のない更新では元の値のまま書き戻す(要望は `keepRaw`、
|
|
1116
|
+
タスクは受け入れ基準と同じ、タスク案は元の値を書き戻す)
|
|
1117
|
+
- **評価の資料**: 上の「評価対象の固定」。タスクの AI レビューの材料にも、基準ごとの記録と状態を入れる(材料の hash に入る)
|
|
1118
|
+
|
|
931
1119
|
### 置き換えられたタスク
|
|
932
1120
|
|
|
933
1121
|
再評価でタスク化すると、新しい案が同じ要望の古いタスクを置き換える(`supersedes`)ことがある。
|
|
934
|
-
タスクの状態は 未着手 / 作業中 / 完了 の3つのままにし、置き換えは関係として扱う(`src/core/supersede.ts`)。
|
|
1122
|
+
タスクの状態は 未着手 / 作業中 / 完了 の3つのままにし、置き換えは関係として扱う(`packages/tasks/src/core/supersede.ts`)。
|
|
935
1123
|
|
|
936
1124
|
- **タスク化で知らせる候補**: **採用した** 案の `supersedes` のうち、同じ要望にある未完了(未着手・作業中)のタスク。
|
|
937
1125
|
不採用の案だけにあるもの・完了したタスク・無いタスクは候補にしない。
|
|
@@ -973,28 +1161,168 @@ API の PATCH。`rev` で楽観ロック)。書き換えても状態・既存
|
|
|
973
1161
|
- 復元・編集・アーカイブした要望の中のタスクの閲覧はしない。過去に保存したレビュー・リリースノート・git の履歴は消さない
|
|
974
1162
|
要望の詳細と タスクの GET は印 `superseded` を返す。
|
|
975
1163
|
|
|
1164
|
+
### 手戻りの履歴と保存のロック
|
|
1165
|
+
|
|
1166
|
+
タスクの済みの解除と完了からの再開を `reworkHistory`(`[{id: R1, at, by, rev, cause, unchecked, reopened, from, to}]`。追記だけ)に残す
|
|
1167
|
+
(`features/records/shared/reworkHistory.ts`)。後で「Preflight で心配したことが手戻りになったか」を追うときの材料にする。
|
|
1168
|
+
|
|
1169
|
+
- `updateTask` が、書く直前に読み直した値と保存する値(状態・済み。完了から戻すと済みも外れる)を比べて決め、状態と同じ1回の書き込みに入れる。
|
|
1170
|
+
`cause` は `reopen`(完了から戻した)・`explicit`(済みを外すと明示した)・`acceptance`(基準・証拠・基準の根拠の中身が変わって済みが外れた)。
|
|
1171
|
+
済みの完了を戻した1操作は `unchecked` と `reopened` の両方を持つ1件
|
|
1172
|
+
- 同じ値の再保存・済みを保ったままの変更・成果物の追記では足さない。履歴の値は CLI・API から受け付けない。直接編集からは作らず、過去の分は補わない
|
|
1173
|
+
- 壊れた履歴は `reworkProblems` と `keepRaw` で元の値を残し、新しい履歴は足さずに `reworkSkipped` で知らせる(状態の変更は拒まない。
|
|
1174
|
+
CLI の `move`・`set` は標準エラーと `--json` の結果の両方、API の PATCH は結果)
|
|
1175
|
+
|
|
1176
|
+
**保存のロック**: 要望とそのタスクの更新・作成・アーカイブは、要望ごとのロック(`requests/.locks/<要望ID>.lock`。要望のフォルダの外なので、
|
|
1177
|
+
アーカイブで一緒に動かない)の中で、読み直してから書く・移す。別のプロセスのタスクの更新と、タスク・要望のアーカイブが重なっても、
|
|
1178
|
+
先に移したなら後の更新は「無い」になり、移した後のファイルを書き戻さない(先に更新したなら、その履歴ごと移る)。
|
|
1179
|
+
ロックは同じマシンのプロセスの間だけ。異常終了で残ったロックは 60 秒で古いものとして取り直す(30 秒待っても取れなければ失敗にし、やり直せる)。
|
|
1180
|
+
ロックの順は、親子の操作のロック(`.hierarchy.lock`)→ 要望のロック。要望のロックの中で別の要望・タスクのロックは取らない
|
|
1181
|
+
|
|
1182
|
+
### 振り返り
|
|
1183
|
+
|
|
1184
|
+
外部の評価への対応: 蓄積した記録で開発を振り返る一例として、Preflight で心配したリスクが実装の後に起きたかを追う(`features/retro/shared/retrospective.ts`)。
|
|
1185
|
+
P3 は AI の実装を動かさず、成績も測らない。
|
|
1186
|
+
|
|
1187
|
+
- **記録**: 要望のフォルダの `retrospective.json`(`{version, targets: [...]}`)。要望と一緒にアーカイブ・共有する。保存は要望のロック
|
|
1188
|
+
(`requestLock`)の中で読み直して `version` を照らし(違えば `retro_conflict`)、1 上げて書く。ロックの中で要望が無ければ書かない(アーカイブの後に作り直さない)。
|
|
1189
|
+
壊れていれば空とみなさず `retro_unreadable`
|
|
1190
|
+
- **候補**(`retroCandidates`): `status: completed` で評価のある run のうち、`materialization.done`(`created` のタスクが今ある・アーカイブ済み・無いを照らす)、
|
|
1191
|
+
`adoption.done`(`reserved` の子の `splitFrom` が `<run>/<案>` で親がこの要望かを照らす)、`materialization` の無い `materialized`(旧記録)。
|
|
1192
|
+
途中の採用は候補にしない。見送りの要望は候補なし。並びは run の新しい順で、先頭が `latest`
|
|
1193
|
+
- **確定**(`confirmTarget`): 候補の run だけ。`assessmentVersion`(評価の内容の hash)・リスクの位置と原文・採用の根拠・確定者と日時を写した `V<n>` を追記する。
|
|
1194
|
+
2件目からは訂正の理由(`reason`)が要り、前の対象を `replaces` に残す。同じ run と同じ評価の版は確定し直さない。今の対象は最後の1件
|
|
1195
|
+
- 対象は人の明示の操作でだけ変わる(Preflight の実行・タスク化・分割の採用・画面の run の切り替えでは変えない)。入口: CLI の `retro`、
|
|
1196
|
+
API の `GET /api/requests/:rid/retrospective`・`POST .../retrospective/target`・`POST .../retrospective/judgments`
|
|
1197
|
+
- **リスクの確認**(`addJudgment`): `judgments` に `J<n>`(対象 ID・リスクの位置・原文の写し・状態・事実・範囲・根拠・理由・日時・主体)を追記する。
|
|
1198
|
+
リスクは対象 ID と位置で見分ける(同文のリスクも別)。今の確認は対象とリスクの最後の1件。`occurred` は事実と根拠、`not_occurred` は範囲と根拠が要り、
|
|
1199
|
+
`unchecked` は根拠を結び付けるだけ。決めた確認(`unchecked` 以外)を変えるには理由が要る。今の対象のリスクだけに足せ、件数(`riskCounts`)も今の対象だけ
|
|
1200
|
+
- **根拠**(`features/retro/core/retrospective.ts` の `resolveEvidence`): 保存するときに今の記録と照らし、参照先と抜粋(1000 文字まで)と結果の版を写す。
|
|
1201
|
+
タスクレビューはこの要望のタスク(今の・アーカイブ)の完了した run の `overall`・`items`・`quality`・`unplanned`・`checks` の位置。
|
|
1202
|
+
マイルストーンレビューは固定した材料(`input.requests`)にこの要望が直接あるものだけで、所見の `evidence` に要望 ID か `<要望ID>/T…` が無ければ
|
|
1203
|
+
結び付く理由が要る(実行中の材料の変更 `inputChanged` も写す)。手戻りはタスクの `reworkHistory` の ID。人の参照は確かめない
|
|
1204
|
+
- **照合**(`checkEvidence`): 読むたびに、保存した参照先で今の記録を引き、結果の版が同じなら `ok`、違えば `changed`、無ければ `missing`。
|
|
1205
|
+
要望の付け替え・タスクのアーカイブの後も、保存した要望 ID・タスク ID で引く。親子の間で確認や根拠は継承しない
|
|
1206
|
+
|
|
1207
|
+
### 開発の指標
|
|
1208
|
+
|
|
1209
|
+
外部の評価への対応: AI 開発の成果をコードの量ではなく、到達の時間・品質(手戻り・基準の未達)などで振り返る材料として、記録から指標を出す。
|
|
1210
|
+
P3 は AI の実装を動かして測らない。成績の評価・順位には使わない。
|
|
1211
|
+
|
|
1212
|
+
- **定義**: `features/metrics/core/definitions.ts` の `METRIC_DEFINITIONS` の1か所。各定義は ID・名前・単位・出典・対象・算出・欠損の扱いと `compute(input)`。
|
|
1213
|
+
CLI の `metrics`・API の `GET /api/metrics` は `features/metrics/core/index.ts` の `metricsReport` を通り、同じ値を返す
|
|
1214
|
+
- **範囲**: プロジェクト全体(所属なし・登録に無いマイルストーンの要望を含む)か、`project.yaml` に登録したマイルストーンに今直接属する要望。
|
|
1215
|
+
見送り・アーカイブの要望は除く。タスクは要望の直下だけ。読めない要望は `notices`
|
|
1216
|
+
- **値の状態**: `ok`・`no_targets`(対象なし)・`no_data`(欠損だけ)・`not_reached`(まだ到達していない)・`unrecorded`(記録なし)。値は `ok` のときだけで、ほかは `null`(0 にしない)
|
|
1217
|
+
- **到達時間**: 要望の `createdAt` から `completionRecords` の最初の `request_resolved`・`request_done` までの中央値。記録・日時が読めない・逆転・
|
|
1218
|
+
今の状態から到達済みと分かるのに記録が無いものは欠損。完了済の記録だけで対応済の記録が無いものは直接の遷移(対応済に未到達)、
|
|
1219
|
+
記録の1つも無い完了済は「到達したか分からない」(欠損)。`updatedAt`・`doneAt` で推し量らない
|
|
1220
|
+
- **受け入れ基準**: 今完了しているタスクの今の基準を `acceptanceStatus` で照らす。分母は数えた基準の合計。基準なしは対象なし、`acceptanceProblems` と
|
|
1221
|
+
読めないタスクのファイルは欠損、対応する基準の無い証拠は分母の外。5つの基準の指標は、1回のレポートの材料(`MetricsInput`)ごとに1回だけ
|
|
1222
|
+
集計した結果を使う(`sharedCriteria`。材料に結んだ `WeakMap` で、レポートの外へは持ち越さない)
|
|
1223
|
+
- **手戻り**: タスクの `reworkHistory` の件数(同じタスクの同じ `rev` は1件)。`reworkProblems` と読めないタスクのファイルは欠損、履歴の無いタスクは内訳の
|
|
1224
|
+
「記録が無い」。履歴より前は分からない(観測の始まりを保存していないので、全期間の完全さは保証しない)
|
|
1225
|
+
- **タスクレビュー**: 今完了しているタスクごとに、`selectTaskReview` で完了した run を1件選ぶ(`finishedAt` の新しい順、同時刻は run ID の大きい方。
|
|
1226
|
+
読めない記録・`finishedAt` の無い完了の run があれば欠損)。選んだ結果の `items` の `missing` と `unplanned` を別の指標に数える。`undetermined`・`checks` は
|
|
1227
|
+
内訳だけ。レビューの無いタスクばかりなら `unrecorded`。読むのは `taskReviews.list`・`get` だけで、run を作らない。マイルストーンレビューの所見は今後の候補。
|
|
1228
|
+
読み取りはタスクごと(一覧・選択・結果の取得)に並行に行い、同時に読む数は1回のレポートの全部の要望で1つの上限(`REVIEW_READ_CONCURRENCY`)に
|
|
1229
|
+
収める。結果は要望 ID とタスク ID に結び、集計は読み終わった順ではなく要望・タスクの順で行う(欠損の明細の並びも同じ)
|
|
1230
|
+
- **人が記録する値**(`kind: manual`。定義の `manual` に値の規則): `features/metrics/core/manual.ts`。`<data>/metrics/manual.json`(`{version: 1, seq, records}`)に持ち、
|
|
1231
|
+
`metrics/.manual.lock` のロックの中で読み直してから置き換えで書く。識別は指標・範囲(`project` かマイルストーン ID)・期間・単位で、同じ内容は書かない。
|
|
1232
|
+
値・出典・メモの訂正は記録の `rev` を照らす(渡さない・違えば `metrics_conflict`)。訂正の `updatedBy` はその訂正の主体で、主体を記録できない
|
|
1233
|
+
訂正では省く(前の更新者を残すと、その人が訂正したように読めるため)。`createdBy`・`createdAt` は作ったときのまま。同じ内容の再送と競合は
|
|
1234
|
+
更新者・更新日時・版を変えない。壊れたファイルは空とみなさず `metrics_unreadable`(読む側は欠損と `notices`)。
|
|
1235
|
+
表示は範囲が一致する記録だけを期間・単位ごとの `rows` に出し、範囲の間・通貨・期間をまたいで合算しない(`value` は1行のときだけ)。書くのは CLI だけ。
|
|
1236
|
+
記録のあるマイルストーンは `checkMilestoneRemoval` で消さず、登録に無いマイルストーンへの記録は `manual_orphan`
|
|
1237
|
+
|
|
1238
|
+
### 完了の記録
|
|
1239
|
+
|
|
1240
|
+
タスクの完了(`task_done`)・人の済み(`task_checked`)・要望の対応済(`request_resolved`)・完了済(`request_done`)のとき、
|
|
1241
|
+
そのときの条件の写しを `completionRecords` に追記する(`features/records/shared/completionRecord.ts`)。今の値(`doneAt`・`checkedAt` は再開で消える)とは別に持ち、
|
|
1242
|
+
後から「当時どの条件で完了・確認したか」を比べる材料にする。
|
|
1243
|
+
|
|
1244
|
+
- 状態と同じ更新(同じ rev)で同じファイルに書く。片方だけが保存されることはない。`expectedRev` の競合では何も書かない
|
|
1245
|
+
- 契機は書く直前に読み直した値と書いた後の値から決める(`taskTriggers`・`requestTriggers`)。タスクは完了でないものが完了になったら
|
|
1246
|
+
`task_done`、完了で済みが付いたら `task_checked`(済みのまま基準・証拠・基準の根拠を変えて済みを付け直したときも足す)。
|
|
1247
|
+
同じ状態の再保存・成果物の追記・済みの付け直しでは足さない。再開・済みの解除でも消さない
|
|
1248
|
+
- 写す値は、同じ操作で変えた基準・証拠を当てた後のもの。品質は完了したときの最新の値(設定全体の版・作業先に当てはまる項目と除外)で、
|
|
1249
|
+
取り込んだときの版は基準の `quality.version` に残る。要望の記録は題と `requestSubject`(題と本文の hash)を持ち、本文は写さない
|
|
1250
|
+
- 要望の記録の `tasks`・`children` は判定に使った直下のタスクと子の要望(ID・rev・状態・その時点の最新の記録 ID)。子だけの親も子の記録から辿れる
|
|
1251
|
+
- 参照先は書く前(ロックの外)に `features/records/core/completionRefs.ts` が取る: `git rev-parse HEAD` と、参照先のフォルダに限った `git status --porcelain`。
|
|
1252
|
+
状態は `ok`・`not_git`・`unregistered`・`missing`・`notdir`・`failed` で、理由にはこのマシンのパスを入れない。完了になりうる更新
|
|
1253
|
+
(状態を完了にする・済みを付ける・対応済・完了済にする)のときだけ取る。Preflight の評価対象にはコミットの固定が無いので、run から補わない
|
|
1254
|
+
- 入口: `createTask`(完了で作る)・`updateTask`(CLI の move・set・check、API の PATCH、品質の取り込み)・`updateRequest`(CLI の request set、
|
|
1255
|
+
API の PATCH、マイルストーンの一括完了)。どれも記録の値を受け付けず(`completionRecords` は捨てる)、P3 が作る
|
|
1256
|
+
- 記録の無い古いデータは補わない。読めない記録は `completionProblems` にして `keepRaw` で元の値を書き戻し、新しい記録は足さない
|
|
1257
|
+
(状態は変え、`completionSkipped` で知らせる。CLI の `move`・`set` は標準エラーと `--json` の結果の両方、API の PATCH は結果)。読めない品質・基準・根拠は `problems` として写し、完了は拒まない
|
|
1258
|
+
- ファイルの並びでは最後(`updatedBy` の後)に書く。人が読む項目を上に残すため
|
|
1259
|
+
- 一覧(進捗・タスクの一覧)にも今は全部が載る(要望・タスクの値をそのまま返すため)。進捗のタスクの印は記録を載せず、見直しの状態だけを持つ
|
|
1260
|
+
|
|
1261
|
+
### 見直し候補
|
|
1262
|
+
|
|
1263
|
+
外部の評価(課題 C)への対応: 過去に正しいと判断したものが、仕様や環境の変化で正しくなくなることがある。判断を間違いと決めつけず、
|
|
1264
|
+
当時の条件(完了の記録)と今の条件の差を「見直しが必要(候補)」として示す(`features/records/shared/reviewCandidate.ts`)。状態は増やさない。
|
|
1265
|
+
|
|
1266
|
+
- **基点**: タスク・要望の最新の完了の記録。人がもう一度済み・完了にすれば新しい記録が基点になる。記録が無い・読めないときは
|
|
1267
|
+
`no_record`・`unreadable` で、差分なし(`none`)とも候補(`candidate`)とも分ける
|
|
1268
|
+
- **対象**: 完了したタスク(済みの有無を問わない)と、対応済・完了済の要望自身。要望の詳細・進捗には配下の候補の件数(`tasks`・`below`)を
|
|
1269
|
+
添えるが、親自身を候補にはしない。`below` は子孫の要望自身とそのタスクを1回ずつ数える。アーカイブは見ない。件数の内訳は
|
|
1270
|
+
`self`(要望自身の概要。対応済・完了済のときだけ)・`tasks`(自分の候補のタスク)・`below`(子孫の要望自身の候補と子孫の候補のタスク)
|
|
1271
|
+
- **進捗での共有**: 進捗(`progress`)は1回の呼び出しの中で診断を使い回す(`reviewMemo`。タスクは要望 ID を含む `ref`、要望自身は要望 ID で引き、
|
|
1272
|
+
診断が無いことも覚える)。タスク行の状態と、全部の要望の `self`・`tasks`・`below` が同じ結果を使い、各タスクと各要望自身の診断は1回だけになる。
|
|
1273
|
+
呼び出しをまたいでは持たない(次の進捗ではその時点の条件で診断し直す)。261120-89k52
|
|
1274
|
+
- **品質**: `standardsFor` で作業先に当てはまる項目を当時(記録の `quality.standards`)と今で比べる(`quality_added`・`quality_changed`
|
|
1275
|
+
(`standardHash`)・`quality_removed`・`quality_exempted`)。設定全体の版(`qualityVersion`)の違いだけでは候補にしない。
|
|
1276
|
+
今が未設定・読めないなら `quality_state`、当時が読めないなら比べない。要望の記録は項目を写さないので、要望自身は状態だけを比べる:
|
|
1277
|
+
設定済 → 未設定、または今が読めない(当時が設定済・未設定のどちらでも。比べられない部分も返す)だけを `quality_state` にし、
|
|
1278
|
+
未設定 → 設定(品質基準の初回設定)は理由にしない。後から品質基準を導入しただけで、対応済・完了済の要望が一括して候補になるのを避けるため。
|
|
1279
|
+
完了したタスクは未設定で完了していても(記録に項目が無い)、今の作業先に当てはまる項目を `quality_added` にする(作業先なしのタスクは
|
|
1280
|
+
全体適用の項目)。そのため初回設定の後は、候補のタスクを持つ要望が配下の件数(`tasks`)で進捗の「見直し候補のみ」に残る
|
|
1281
|
+
- **基準と根拠**: 基準は ID で比べる(`criterion_added`・`criterion_changed`・`criterion_removed`)。基準ごとの根拠は (基準 ID, 記録 ID)、
|
|
1282
|
+
基準が写した要望の根拠(`from`)は当時の元と今の元を比べる(`source_changed`・`source_removed`・`source_unconfirmed`)。要望自身は要望の根拠の全部
|
|
1283
|
+
- **前提の変更**: 要望の `premiseChanges`(`[{id: P1, targets, reason, condition, at, by, acks?}]`。追記だけ)。対象は要望 ID・この要望の
|
|
1284
|
+
タスク ID・要望の根拠の ID で、記録するときに有るものだけ。基点より後の変更で、対象に変更より後の確認(`acks`)が無いものを `premise_changed`
|
|
1285
|
+
にする。タスクはタスク ID と、基準が写した要望の根拠の ID の変更を見る。要望自身は要望 ID と要望の根拠の ID。既存の `source` 操作で表せる
|
|
1286
|
+
根拠の変更は、根拠の差として自動で出る(前提の変更は外部の変化を表すときに使う)
|
|
1287
|
+
- 理由は同じ種類と対象で1件にする。各理由は当時(`was`)・今(`now`)の短い値と関係する対象(`related`)を持つ。`then` は Promise と
|
|
1288
|
+
取り違えられるので使わない
|
|
1289
|
+
- 診断は読み込んだ値だけで行い、ファイルを書かず git も実行しない(参照先のコミットは比べない)。入口: CLI の `revisit`・`ls --review`・`show`・
|
|
1290
|
+
`progress`、API の `GET /api/revisit`・`?review=true`・要望とタスクの詳細の `review`・進捗の `review`
|
|
1291
|
+
- 証拠の「再確認が必要」(`stale`)・基準や証拠の明示の編集による済みの解除とは別の意味として残す
|
|
1292
|
+
|
|
976
1293
|
### 受け入れ基準と証拠
|
|
977
1294
|
|
|
978
1295
|
タスクは任意で **受け入れ基準**(`acceptanceCriteria: [{id, text}]`。何を満たせば完了か)を持ち、作業した側は基準ごとに
|
|
979
1296
|
**証拠**(`acceptanceEvidence: [{criterionId, criterionText, result, evidence, recordedAt, recordedBy}]`)を残す。規則は
|
|
980
|
-
`shared/acceptance.ts` の1か所で、CLI(`new --criterion`・`criteria`・`evidence`・`set` / `move` の `--evidence`)と API
|
|
1297
|
+
`features/requirements/shared/acceptance.ts` の1か所で、CLI(`new --criterion`・`criteria`・`evidence`・`set` / `move` の `--evidence`)と API
|
|
981
1298
|
(POST の `criteria`、PATCH の `acceptance` の操作)は同じ操作を `core/requestOps.ts` に渡すだけ。
|
|
982
1299
|
|
|
983
1300
|
- **ID**: 足すときに `A1, A2, ...` を振る。並べ替え・文言の変更で振り直さず、消した ID も使い直さない(振った最後の番号を
|
|
984
1301
|
`acceptanceSeq` に残す)。基準・証拠は操作でだけ変え、PATCH の `acceptanceCriteria` などをそのまま書く道は持たない
|
|
985
1302
|
- **証拠は申告**: 結果は `met` / `unmet` / `unverified`。`met` は本文が要る(空は入力の誤り)。未記録(証拠なし)と未検証は分ける。
|
|
986
1303
|
これは作業した側の申告で、レビューの判定ではない(AI のレビューを足すときも、その判定は証拠とは別の型で持ち、証拠を書き換えない)
|
|
1304
|
+
- **根拠の種類**: 証拠は任意の `basis` を持つ(`{kind: unverified}` 未確認 / `{kind: declaration}` 申告のみ / `{kind: read, reference}`
|
|
1305
|
+
読んで確認 / `{kind: machine, command, result, target}` 検査結果あり)。結果と別の軸で、どれも作業した側の申告(P3 は実行しない。
|
|
1306
|
+
read と machine に正しさの上下は付けない。人の済みはタスクの `checkedAt` で、basis に human は作らない。AI レビューの判定は写さない)。
|
|
1307
|
+
型・ラベル・組み合わせ(met / unmet に未確認は不可、unverified は未確認だけ)・古い値の解釈・内訳・変更の比較は `features/requirements/shared/acceptance.ts`。
|
|
1308
|
+
根拠を省いた record は、同じ結果の前の証拠の根拠を引き継ぎ、無ければ unverified は未確認・ほかは申告のみ(古い CLI・画面の更新を
|
|
1309
|
+
妨げず、古い証拠を同じ値で保存し直しても根拠を足さない)。保存した値に basis が無い古い証拠は書き換えず、読むときだけ
|
|
1310
|
+
unverified は未確認、ほかは「申告のみ(種類未記録)」と解釈する(本文から推し量って格上げしない)。`acceptanceStatus` の `met` は
|
|
1311
|
+
「満たしたと申告した数」のままで、有効な met の根拠ごとの件数 `metByBasis` と申告のみの基準 `declarationOnly` を足す(stale・orphan は
|
|
1312
|
+
入れない)。申告のみの met は shortfalls に注意として出すが、完了・済みは拒まない。進捗の `TaskMark.evidence` は `evidenceSummary`
|
|
1313
|
+
の小さな概要(件数と読めない値の有無。本文・コマンドは載せない)。CLI は `evidence` の `--basis` と項目、まとめては `--evidence-json`
|
|
1314
|
+
(Markdown の `--evidence-file` と同時には使えない)
|
|
987
1315
|
- **失効と消した基準**: 証拠は記録したときの基準の文言を写して持つ。文言を変えた基準の証拠は「再確認が必要」として達成に数えない。
|
|
988
1316
|
基準を消しても証拠は「対応する基準のない証拠」として残す。再記録はその ID の証拠を置き換える(同じ値なら記録の日時も変えない)。
|
|
989
1317
|
履歴は持たない
|
|
990
1318
|
- **完了を拒まない**: 基準なし・証拠なし・未達・未検証でも、完了・済み・対応済は今までどおり(状態も要望の判定も増やさない)。
|
|
991
1319
|
不足は `acceptance.shortfalls`(show・API の GET)と `move ... done` の stderr で読めるようにするだけ。AI の完了に変更の記録が要る
|
|
992
1320
|
CLI の決まりは変えず、API には広げない
|
|
993
|
-
- **済みの解除**:
|
|
1321
|
+
- **済みの解除**: 済みのタスクの基準・証拠の中身(並び・文言・結果・証拠・根拠)が変わったら済みを外し、`checkCleared` に理由を返す。
|
|
994
1322
|
同じ値の再保存・成果物の追加・同じ操作で済みを付け直すときは外さない。未完了へ戻すと外れるのは今までどおり
|
|
995
1323
|
- **今の値に当てる**: 操作は書く直前に読み直したファイルの値に当て、1つでも規則に合わなければ何も書かない(`rev` を渡せば競合も分かる)
|
|
996
1324
|
- **Preflight のタスク案**: 案(`drafts/D*.md`)も `acceptanceCriteria` を持つ。Codex・手元のエージェントは文の並びで書き、
|
|
997
|
-
P3 が読むときに A1, A2, ... を振る(`shared/acceptance.ts` の `readDraftCriteria`)。読めない基準は案の `acceptanceProblems`
|
|
1325
|
+
P3 が読むときに A1, A2, ... を振る(`features/requirements/shared/acceptance.ts` の `readDraftCriteria`)。読めない基準は案の `acceptanceProblems`
|
|
998
1326
|
(案のファイルには書かない)に出し、手元の結果の取り込み(`--complete`)では直せる問題として断る。Codex の run では案に残して
|
|
999
1327
|
ログに出し、その案はタスク化を断る(直せば消える)。人の編集は並び全体の置き換えで、編集を始めたときの基準
|
|
1000
1328
|
(`expectedCriteria`)と今の基準が違えば題と同じく 409 で書かない(同じ題のまま他で基準が変わっても上書きしない)。
|
|
@@ -1029,18 +1357,18 @@ quality:
|
|
|
1029
1357
|
- **状態**: `quality` が無ければ未設定、あれば設定済み(意図して空でもよい)、読めない値(重複した ID・理由の無い除外・確認の方法の
|
|
1030
1358
|
欠け)があれば invalid。invalid は未設定として扱い、ファイルの値は消さず、操作は断って直し方を示す。知らない参照先は警告だけ
|
|
1031
1359
|
- **上限**: 100 件、文 1000・コマンド 500・成功の条件 500・確かめ方 1000・除外の理由 500 文字
|
|
1032
|
-
- **書き方**: `core/quality.ts` の操作(init・adopt・upgrade・add・replace・edit・remove・exempt・unexempt)を `Workspace.writeQuality` が
|
|
1360
|
+
- **書き方**: `features/quality/core/quality.ts` の操作(init・adopt・upgrade・add・replace・edit・remove・exempt・unexempt)を `Workspace.writeQuality` が
|
|
1033
1361
|
project.yaml のロックの中で、読み直した最新の値に当て、`quality` の項目だけを書く(コメント・ほかの項目は残す)。設定の保存
|
|
1034
1362
|
(PUT /api/project・`p3 config`)・参照先の保存・マイルストーンの保存は `quality` を書かないので、無関係な保存で品質基準は消えない
|
|
1035
1363
|
- **版**: 品質だけの中身の hash(`qualityVersion`)。操作に版を渡すと、違えば `quality_conflict`(API 409・CLI 終了コード 3)で何も書かない
|
|
1036
|
-
- **テンプレート**(`shared/qualityTemplates.ts`): 版つきの例(共通の基本・TypeScript の例)で、業界の標準への認証ではない。採用すると
|
|
1364
|
+
- **テンプレート**(`features/quality/shared/qualityTemplates.ts`): 版つきの例(共通の基本・TypeScript の例)で、業界の標準への認証ではない。採用すると
|
|
1037
1365
|
編集できる実体として写し、出典(`source`)を残す。テンプレートが改版しても採用済みの内容は変わらず、差分(足す・変わる・消える)
|
|
1038
1366
|
を見て `upgrade` で明示して当てる
|
|
1039
1367
|
- P3 はコマンドを実行しない・依存を入れない。確認の方法は CI・手元の作業・外の自動化のどれでもよく、特定の製品・フォルダを必須にしない
|
|
1040
1368
|
|
|
1041
1369
|
### 品質の改善要望
|
|
1042
1370
|
|
|
1043
|
-
品質の不足から改善要望を作る(`core/qualityImprovement.ts`。形は `shared/qualityImprovement.ts`)。
|
|
1371
|
+
品質の不足から改善要望を作る(`features/quality/core/qualityImprovement.ts`。形は `features/quality/shared/qualityImprovement.ts`)。
|
|
1044
1372
|
|
|
1045
1373
|
- **診断**(読むだけ): 出典は品質基準の設定(`project`)・タスクのレビューの1回分・マイルストーンレビューの1回分。不足を
|
|
1046
1374
|
unset(未設定)/ invalid(読めない設定)/ violated(レビューで確かめた違反)/ undetermined(判断できない)/ exempt(理由つきの除外)に
|
|
@@ -1111,8 +1439,8 @@ blockHistory: # 履歴(追記だけ。before / after はその
|
|
|
1111
1439
|
### タスクの AI レビュー(材料)
|
|
1112
1440
|
|
|
1113
1441
|
完了したタスクの本文・受け入れ基準に対して、比較対象の変更が基準を満たしているかを、作業したのとは別の Codex のスレッドに
|
|
1114
|
-
読むだけで確かめさせる参考の記録。作業した AI の能力・成績の評価ではない。材料は `
|
|
1115
|
-
(何も書かない。保存は別)。形は `shared/taskReview.ts`。
|
|
1442
|
+
読むだけで確かめさせる参考の記録。作業した AI の能力・成績の評価ではない。材料は `features/taskReview/core/material.ts` が固定する
|
|
1443
|
+
(何も書かない。保存は別)。形は `features/taskReview/shared/taskReview.ts`。
|
|
1116
1444
|
|
|
1117
1445
|
- **対象**: 保存してある完了したタスク(済みも再実行できる)。無い(404)・未完了(`not_done`)・アーカイブ(`archived`)は断る
|
|
1118
1446
|
- **タスクの材料**: 本文・受け入れ基準・作業した側の証拠(基準ごとの今の状態 `evidenceStates`、読めない値)・変更の記録・成果物・
|
|
@@ -1168,7 +1496,7 @@ blockHistory: # 履歴(追記だけ。before / after はその
|
|
|
1168
1496
|
|
|
1169
1497
|
### タスクの AI レビュー(履歴と実行)
|
|
1170
1498
|
|
|
1171
|
-
履歴は要望のフォルダの中に置く(`
|
|
1499
|
+
履歴は要望のフォルダの中に置く(`features/taskReview/core/store.ts`)。要望をアーカイブすれば一緒に動き、タスクをアーカイブしても残って読める。
|
|
1172
1500
|
|
|
1173
1501
|
```text
|
|
1174
1502
|
requests/<要望ID>/task-reviews/<タスクID>/<run>/input.json 固定した材料(作ったら変えない)
|
|
@@ -1189,7 +1517,7 @@ requests/<要望ID>/task-reviews/.locks/<タスクID>.lock 状態を変
|
|
|
1189
1517
|
|
|
1190
1518
|
### タスクの AI レビュー(実行)
|
|
1191
1519
|
|
|
1192
|
-
`
|
|
1520
|
+
`features/taskReview/core/service.ts`(CLI の `p3 review`・API の `/requests/:rid/tasks/:tid/reviews` が呼ぶ)。依頼文と結果の確かめ方は `review.ts`。
|
|
1193
1521
|
|
|
1194
1522
|
- **頼む先**: Preflight と同じ Codex の接続(`CodexWorkspaceEngine.ask`。認証・パスの対応・診断・時間と使用量の上限・取消を共有)。
|
|
1195
1523
|
毎回新しいスレッドで、作業したスレッドは再開しない。マウントするのは run の材料のフォルダ(`/workspace/material`)だけで、
|
|
@@ -1213,7 +1541,7 @@ requests/<要望ID>/task-reviews/.locks/<タスクID>.lock 状態を変
|
|
|
1213
1541
|
### リリースノートの要約(生成の境界)
|
|
1214
1542
|
|
|
1215
1543
|
マイルストーンのリリースノートの機能の要約は、Preflight と同じ Codex の接続(個人設定・認証・イメージの確かめ・起動の診断)で頼む
|
|
1216
|
-
(`CodexWorkspaceEngine.ask`、`
|
|
1544
|
+
(`CodexWorkspaceEngine.ask`、`features/releaseNotes/core/generate.ts`)。Preflight の評価・タスク化は行わない。
|
|
1217
1545
|
|
|
1218
1546
|
- **渡すもの**: 始めるときに固定した材料([リリースノートのデータ](#リリースノートのデータ))のうち、マイルストーンのタイトルと、
|
|
1219
1547
|
収録する要望とタスクの ID・タイトル・変更の記録だけを依頼文に入れる。要望やタスクの本文・成果物・参照先・データのフォルダは
|
|
@@ -1256,12 +1584,12 @@ package.json では公開版の版の範囲(`^0.2.0` など)で指定し、
|
|
|
1256
1584
|
- いつもの Preflight: 既定の1日より古ければ作り直す(個人設定 `codex.ensureImage: false` か `P3_CODEX_ENSURE_IMAGE=0` で止める)
|
|
1257
1585
|
- 強制更新(`p3 codex update`): `maxAgeMs` を -∞ にして、作った日時によらず作り直す。プロジェクト・認証を決める前に動き、
|
|
1258
1586
|
個人設定の自動更新の停止(`codex.ensureImage: false`)とも関係しない。前に `docker version` でデーモンを確かめ、
|
|
1259
|
-
失敗した段(docker が無い / デーモン / 作成 / 版の取得)ごとに次にすることを出す(`src/core/preflight/codexImage.ts`)
|
|
1587
|
+
失敗した段(docker が無い / デーモン / 作成 / 版の取得)ごとに次にすることを出す(`packages/tasks/src/core/preflight/codexImage.ts`)
|
|
1260
1588
|
- テストは偽の docker(`test/fixtures/fake-docker.mjs`)で行い、本物の Docker では次で確かめる:
|
|
1261
1589
|
`XDG_CONFIG_HOME=$(mktemp -d) p3 codex update --json`(未登録・未認証のままでよい)
|
|
1262
1590
|
- P3 は `ensureImage` そのものは呼ばない(inspect・build・版の確認のどれにも待つ時間の上限が無く、取消も受けないため)。同じ判定と
|
|
1263
1591
|
ビルドを、同梱の `DOCKER_CONTEXT` と `parseCreated` を使って `codexImage.ts` で行う(Dockerfile は写さない)
|
|
1264
|
-
- **Docker の待ち時間の上限と後片付け**(`src/core/preflight/docker.ts`): 以前は版の確認のコンテナ(`codex --version`)が版を出した後も
|
|
1592
|
+
- **Docker の待ち時間の上限と後片付け**(`packages/tasks/src/core/preflight/docker.ts`): 以前は版の確認のコンテナ(`codex --version`)が版を出した後も
|
|
1265
1593
|
終わらず、Preflight がそれを待って止まったことがある(2026-11-03)。P3 が動かす docker の操作には上限があり、時間切れ・中止では
|
|
1266
1594
|
docker の CLI を止め、P3 が名前を付けて起こしたコンテナはそのコンテナだけを `docker rm -f <名前>` で消す(`docker ps` の全部や
|
|
1267
1595
|
イメージ名では消さない)
|
|
@@ -1291,8 +1619,8 @@ llmcs の変更を P3 で使うには、llmcs 側で新しい版を公開し、P
|
|
|
1291
1619
|
|
|
1292
1620
|
### 画面イメージの描画のイメージ
|
|
1293
1621
|
|
|
1294
|
-
画面イメージの描画(`src/core/preflight/render.ts`)は、Codex のイメージ(llmcs の Dockerfile)とは別に、P3 が持つ
|
|
1295
|
-
Dockerfile(`src/core/preflight/render-image/`)で作る。llmcs の Dockerfile は変えない。将来 llmcs のイメージに
|
|
1622
|
+
画面イメージの描画(`packages/tasks/src/core/preflight/render.ts`)は、Codex のイメージ(llmcs の Dockerfile)とは別に、P3 が持つ
|
|
1623
|
+
Dockerfile(`packages/tasks/src/core/preflight/render-image/`)で作る。llmcs の Dockerfile は変えない。将来 llmcs のイメージに
|
|
1296
1624
|
Playwright が入っても、それだけでは描画の安全の条件(ネットワークなし・認証情報なし・リポジトリなし・原稿は読むだけ)を
|
|
1297
1625
|
満たさないので、描画は別のコンテナで行う。
|
|
1298
1626
|
|
|
@@ -1306,7 +1634,7 @@ Playwright が入っても、それだけでは描画の安全の条件(ネッ
|
|
|
1306
1634
|
- 原稿は描く前に確かめる(`render.ts` の `checkHtml`): 使えるのは `<style>` の CSS・`data:` の画像とフォント・ページの中の `#id`。
|
|
1307
1635
|
スクリプト・`on*` 属性・`javascript:`・外のファイルや通信を指す参照(`http(s):`・`file:`・相対パス・`@import`)・
|
|
1308
1636
|
`iframe` / `object` / `embed` / `link` / `base` / `meta http-equiv` は断る。幅は 320〜2560 px、原稿は 2MB まで、高さ 16384 px を超える
|
|
1309
|
-
ところは切る。DevContainer
|
|
1637
|
+
ところは切る。DevContainer の中からは、出力先の一時のフォルダもホストのフォルダ(bind)の下にある必要がある(パスは自動で決める。マウントするパスの決め方)
|
|
1310
1638
|
- 日本語のフォントは Debian の `fonts-noto-cjk`(SIL Open Font License 1.1)。イメージの中にだけ入り、P3 の配布物には含めない
|
|
1311
1639
|
- Playwright の依存(`--with-deps`)で WenQuanYi Zen Hei(中国語の字形)も入り、fontconfig ではそれが総称の既定に先に来る。
|
|
1312
1640
|
`fonts-ja.conf`(`/etc/fonts/conf.d/99-p3-ja.conf` に置く)で、総称(`sans-serif`・`system-ui`・`serif`・`monospace`)と、
|
|
@@ -1344,7 +1672,7 @@ Playwright が入っても、それだけでは描画の安全の条件(ネッ
|
|
|
1344
1672
|
ドキュメントは古いまま残ることがあるので、今のコードと食い違えば今のコードを正として評価・タスク案を作らせ、見つけた食い違いは
|
|
1345
1673
|
黙って片方に合わせず、すべてリスクか確認事項に書かせる(`instructions.ts` の「やること」。過去の記録と今のコードの食い違いも同じ扱い)。
|
|
1346
1674
|
`preflight.instructions` にはプロジェクト固有の評価の観点・制約を書く。どちらも Codex への指示に加わる。
|
|
1347
|
-
`preflight.runner`(`codex` / `agent`。`src/shared/preflightRunner.ts`)は Preflight の担当で、AI 向けの手順が `whoami --json` の
|
|
1675
|
+
`preflight.runner`(`codex` / `agent`。`packages/tasks/src/shared/preflightRunner.ts`)は Preflight の担当で、AI 向けの手順が `whoami --json` の
|
|
1348
1676
|
`preflight` から読む方針(評価のエンジン・run の `engine` とは別。P3 の実行の仕方は変えない)。未設定は `codex`、読めない値は
|
|
1349
1677
|
`invalidRunner` に残して担当を決めない(保存しても消さない。`config set preflight.runner=` で直す)。保存(`saveProject`)は
|
|
1350
1678
|
`preflight` を項目ごとに重ねるので、観点だけ・担当だけの更新(以前の API の形 `{ instructions }` も)で、もう片方は消えない。
|
|
@@ -1370,41 +1698,71 @@ Playwright が入っても、それだけでは描画の安全の条件(ネッ
|
|
|
1370
1698
|
ファイル内容のハッシュによる楽観ロックに変えれば、`rev` をファイルに書かずに済む。要望単位で人が排他するので優先度は低い(今後)
|
|
1371
1699
|
3. **git を使わないメンバー。** 閲覧だけなら、静的な HTML に書き出して共有する(`p3 export`、今後)
|
|
1372
1700
|
|
|
1373
|
-
## AI エージェントへの指示(`p3 init --agents` / `p3 agents`
|
|
1374
|
-
|
|
1375
|
-
|
|
1376
|
-
|
|
1377
|
-
|
|
1378
|
-
|
|
1379
|
-
`
|
|
1380
|
-
|
|
1381
|
-
|
|
1382
|
-
`p3
|
|
1383
|
-
|
|
1701
|
+
## AI エージェントへの指示(`p3 init --agents` / `p3 agents` で置く入口)
|
|
1702
|
+
|
|
1703
|
+
各プロジェクトに置くのは **入口** だけにし、手順の本文は実行中の CLI から読ませる(`p3 guide`)。置いたファイルは人が更新しないと
|
|
1704
|
+
古いまま残る(原本を変えても届かない)が、CLI は `pnpx @infodb/p3` で新しいものが使われるので、手順は CLI の版に合ったものになる。
|
|
1705
|
+
|
|
1706
|
+
- 入口は2つ。同梱のスキル(原本は `skills/p3/SKILL.md` の1つ。選んだ先(`claude` は `.claude/skills/p3/SKILL.md`(Claude Code)、
|
|
1707
|
+
`codex` は `.agents/skills/p3/SKILL.md`(Codex))に同じものを写す。置き先の一覧は `packages/p3/src/cli/project.ts` の `AGENT_TARGETS`、
|
|
1708
|
+
選び方は `AGENT_CHOICES`。個人のスキルの場所には置かない)と、AGENTS.md(無ければ CLAUDE.md)の「タスク管理(infodb p3)」の節
|
|
1709
|
+
(`packages/p3/src/cli/project.ts` の `agentsSnippet`。スキルの参照は、選んだ先と既にある先だけを書く。下は両方のときの `AGENTS_SNIPPET`)
|
|
1710
|
+
- 入口に書くのは、いつ使うか(スキルの `description`)・`pnpx @infodb/p3 guide --json` の `guide` を最後まで読んで従うこと・取得
|
|
1711
|
+
できなければ p3 を操作せずエラーと呼び方を人に伝えて終えることだけ。入口の古さの伝え方・`whoami` での対象の確かめ方・更新の
|
|
1712
|
+
しかたは手順(guide)の側に書く
|
|
1713
|
+
- 入口の版(`ENTRY_VERSION`。`packages/p3/src/cli/guide.ts`。正の整数)を、スキルは frontmatter の `metadata.p3-entry-version`(Agent Skills の
|
|
1714
|
+
`metadata` は文字列の対応なので `"1"`)、節は見出しの次の行のコメント `<!-- p3-entry-version: 1 -->` に持たせる。入口に書くこと
|
|
1715
|
+
(呼び方・読み込みの約束)を変えたときだけ上げ、手順の本文の改訂では上げない。JSON の `schemaVersion`・CLI の `cliVersion` とは別
|
|
1716
|
+
- 置き先を覚えておく共有の設定は持たない(参加の `join` は置かず、置く・最新にするのは人が明示する `p3 agents` だけなので、消した先が
|
|
1717
|
+
戻らない)。既にあるスキル・節は上書きせず、`--force` で選んだ先のスキルと p3 の節だけを同梱の版にする(節の前後の文は残す。
|
|
1718
|
+
節が複数・見出しになっていなければ変えずに手で整理してもらう)。書く先はメインの作業ツリー(`repoRoot`)
|
|
1719
|
+
- 検査(`test/agents.test.ts`): 入口は版・取得の指示・止まり方を持ち、手順の本文を写していない(短い)こと。手順の決まり(役割・
|
|
1720
|
+
終わり方)は guide の原本に掛ける。下の写しは `AGENTS_SNIPPET` と同じ
|
|
1384
1721
|
|
|
1385
1722
|
```markdown
|
|
1386
1723
|
## タスク管理(infodb p3)
|
|
1387
1724
|
|
|
1388
|
-
|
|
1389
|
-
|
|
1390
|
-
-
|
|
1391
|
-
-
|
|
1392
|
-
-
|
|
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 "..."` でタスクにする(人への質問はタスクにしない)
|
|
1725
|
+
<!-- p3-entry-version: 1 -->
|
|
1726
|
+
|
|
1727
|
+
- このリポジトリの作業は infodb p3 の要望とタスクで管理する。p3 を操作する前に `pnpx @infodb/p3 guide --json` を実行し、返った `guide`(作業の手順)を最後まで読んで従う(手順は動いている CLI の版のものが返る。ここには写さない)
|
|
1728
|
+
- `guide` を取得できなければ(コマンドが無い・エラーになる・JSON が読めない)、p3 を操作しない。出たエラーと呼び方(`pnpx @infodb/p3 guide --json`)を人に伝えて終える
|
|
1729
|
+
- 同じ入口のスキル: `.claude/skills/p3/SKILL.md`(Claude Code)・`.agents/skills/p3/SKILL.md`(Codex)。中身は同じ
|
|
1410
1730
|
```
|
|
1731
|
+
|
|
1732
|
+
### 置いた入口の診断(`agents`)
|
|
1733
|
+
|
|
1734
|
+
`whoami --json` と `guide --json` は、同じ診断(`packages/p3/src/cli/agentsStatus.ts` の `diagnoseAgents`)を `agents` に返す。読むだけで、
|
|
1735
|
+
古くても操作を断らず、書き換えもしない(更新は人が `p3 agents` で行う。AI は伝えるだけ。手順の「置いた入口の状態」)。
|
|
1736
|
+
|
|
1737
|
+
- 調べるのは今いる git の作業ツリーのルート(git 管理外は今いる場所)の、両方のスキルと AGENTS.md / CLAUDE.md の両方の節だけ
|
|
1738
|
+
(全リポジトリ・個人のスキルの場所は見ない)。追加の作業ツリーで調べたときは、書く先(メインの作業ツリー)を `writeRoot` に出し、
|
|
1739
|
+
更新したものをそのブランチへ取り込むよう案内する
|
|
1740
|
+
- 形: `{ root, writeRoot?, expectedVersion, placed, ok, entries: [{ path, kind, target?, primary?, version, status, reason }], advice, problem? }`。
|
|
1741
|
+
`primary` は節が `p3 agents` の書く文書(AGENTS.md があればそれ)か、ほかで見つかった節か
|
|
1742
|
+
- 状態: `current`(版が同じで同梱の入口と同じ。改行の違い・見出しの段・節の参照するスキルの組み合わせは許す)・`outdated`(版が小さい・
|
|
1743
|
+
版の無い前の p3 の全文)・`missing`・`modified`(版は同じで中身が違う。手で直した可能性を正常と断定しない)・`newer`(CLI より新しい版)・
|
|
1744
|
+
`unknown`(版が読めない・節が複数・見出しでない・p3 のスキルの形でない)・`unreadable`
|
|
1745
|
+
- 欠けた片方を必須にしない: スキルは、節が参照している・既にあるものだけを調べる(無ければ `missing`)。スキルはあるのに節がどこにも
|
|
1746
|
+
無ければ節を `missing`。何も無ければ `placed: false` で、人が先を選んで置くよう案内する
|
|
1747
|
+
- 案内(`advice`): `outdated` は差分を確かめてから `--force`、`modified`・`newer`・`unknown` には `--force` を勧めない(`newer` は古い CLI で
|
|
1748
|
+
動いていないかを確かめる)。実行している版はローカルの `cliVersion` で示し、最新版の照会や起動経路の推測で古い全体インストールと断定しない
|
|
1749
|
+
- 診断が失敗しても `problem` に入れて返し、`whoami` の対象の情報や guide の本文は隠さない。通常の出力では、`whoami` は「AI の入口」の
|
|
1750
|
+
行に、`guide` は対応が要るときだけ標準エラーに要点と次の操作を出す
|
|
1751
|
+
|
|
1752
|
+
### 作業の手順(`p3 guide`)
|
|
1753
|
+
|
|
1754
|
+
置いたスキル・節は人が更新しないと古いまま残るので、手順の本文は実行中の CLI から読めるようにする(`packages/p3/src/cli/guide.ts`)。
|
|
1755
|
+
|
|
1756
|
+
- 原本は CLI と一緒に配る `packages/p3/src/cli/guide.md` の1つ(配布物では `scripts/build-cli.mjs` が写した `lib/cli/guide.md`)。毎回この原本を
|
|
1757
|
+
読んで返し、写しを持たない。オプションなしは本文、`--json` は `{ schemaVersion, cliVersion, entryVersion, guide, agents }`(`agents` は上の診断)
|
|
1758
|
+
- `schemaVersion` は JSON の形の版(`GUIDE_SCHEMA_VERSION`)。`cliVersion` は同梱の `package.json` の版で、最新かどうかの判断には
|
|
1759
|
+
使わない(npm に問い合わせない)。`entryVersion`(`ENTRY_VERSION`。正の整数)は入口(置いたスキル・節)の決まりの版で、起動の
|
|
1760
|
+
しかた・読み込みの約束など入口に書くことを変えたときだけ上げる。手順の本文を直しただけでは上げない
|
|
1761
|
+
- プロジェクトを決める前に扱う(`cli/main.ts`。`agents` と同じ位置)。未登録・登録が複数・壊れた個人設定や `project.yaml` でも
|
|
1762
|
+
共通の手順を返す。対象の確かめ方(`whoami` と `via`)は手順の中に書き、`guide` 自身は対象を推測して操作しない
|
|
1763
|
+
- 読むだけ(`cli/readOnly.ts`)。データ・個人設定・置いたファイルを変えず、Codex・Docker・npm を呼ばない(`test/guide.test.ts`)
|
|
1764
|
+
- 手順の呼び方は `pnpx @infodb/p3` を先にし、手順の中の `p3 <コマンド>` は「手順を取得したときと同じ呼び方」と決める
|
|
1765
|
+
(全体に入れた古い `p3` へ切り替えさせない)
|
|
1766
|
+
- 決まり(役割・終わり方)の検査は `test/agents.test.ts` が原本に掛ける。配布物で同じ原本と版を返すことは
|
|
1767
|
+
`test/pack.test.ts` と `scripts/verify-pack.mjs`
|
|
1768
|
+
|