@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.
Files changed (219) hide show
  1. package/README.md +33 -35
  2. package/bin/p3.mjs +3 -2
  3. package/dist/web/assets/CompletionReview-BD7d6Yzt.js +1 -0
  4. package/dist/web/assets/ImprovementDialog-BoAZN1KR.js +1 -0
  5. package/dist/web/assets/Outputs-D-ZouoxF.js +1 -0
  6. package/dist/web/assets/RequestStatus-Bl3fdSbM.js +1 -0
  7. package/dist/web/assets/Tabs-CxeceOL-.js +1 -0
  8. package/dist/web/assets/TagInput-CeAbmGRR.js +1 -0
  9. package/dist/web/assets/TaskDrawer-BCriSnhe.js +6 -0
  10. package/dist/web/assets/_requestId-CZKMe_mC.js +1 -0
  11. package/dist/web/assets/_requestId-Fx4lLkFo.js +1 -0
  12. package/dist/web/assets/appCtx-BdxbkSZa.js +1 -0
  13. package/dist/web/assets/archive-D5IIxcSV.js +1 -0
  14. package/dist/web/assets/board-p6R9KMqd.js +1 -0
  15. package/dist/web/assets/done-BTOF188x.js +1 -0
  16. package/dist/web/assets/draft-BWYpm3PD.js +2 -0
  17. package/dist/web/assets/index-DFbY8NAR.css +2 -0
  18. package/dist/web/assets/index-Dpqi2dcC.js +12 -0
  19. package/dist/web/assets/link-D481whDt.js +1 -0
  20. package/dist/web/assets/metrics-CAzP6V8I.js +1 -0
  21. package/dist/web/assets/new-C65IJJg3.js +1 -0
  22. package/dist/web/assets/outputs-CXqnjSqV.js +1 -0
  23. package/dist/web/assets/preflightInput-ClKwkp8R.js +2 -0
  24. package/dist/web/assets/preload-helper-_dAYMct_.js +1 -0
  25. package/dist/web/assets/{quality-Pu6EISAM.js → quality-RFd-7k3r.js} +1 -1
  26. package/dist/web/assets/release-notes-Dtif8xsQ.js +5 -0
  27. package/dist/web/assets/requestData-SPc36t8Q.js +1 -0
  28. package/dist/web/assets/routes-DJj8CWuk.js +6 -0
  29. package/dist/web/assets/settings-DKJd7CLe.js +1 -0
  30. package/dist/web/assets/ui-CbEOnPnF.js +1 -0
  31. package/dist/web/assets/workTarget-DavxMs-c.js +30 -0
  32. package/dist/web/index.html +6 -4
  33. package/docs/architecture.md +430 -72
  34. package/docs/chatgpt-sign-in.md +2 -2
  35. package/docs/development.md +141 -64
  36. package/docs/feature-inventory.md +139 -0
  37. package/docs/how-to-use.md +389 -31
  38. package/docs/installation.md +261 -147
  39. package/docs/publishing.md +33 -14
  40. package/docs/refactoring.md +332 -0
  41. package/lib/cli/agentsStatus.js +198 -0
  42. package/lib/cli/guide.js +27 -0
  43. package/lib/cli/guide.md +217 -0
  44. package/lib/cli/help.js +45 -7
  45. package/lib/cli/main.js +58 -207
  46. package/lib/cli/project.js +34 -294
  47. package/lib/core/projectRegistry.js +2 -2
  48. package/lib/kit/appInfo.js +13 -0
  49. package/lib/kit/usage.js +27 -0
  50. package/lib/server/api/projectsRoutes.js +5 -5
  51. package/lib/server/server.js +7 -4
  52. package/lib/{cli → tasks/cli}/args.js +73 -9
  53. package/lib/{cli → tasks/cli}/chatgpt.js +1 -1
  54. package/lib/{cli → tasks/cli}/codex.js +1 -1
  55. package/lib/{cli → tasks/cli}/output.js +12 -2
  56. package/lib/{cli → tasks/cli}/preflightCommands.js +1 -1
  57. package/lib/tasks/cli/readOnly.js +75 -0
  58. package/lib/{cli → tasks/cli}/render.js +1 -1
  59. package/lib/{cli → tasks/cli}/requestCommands.js +24 -7
  60. package/lib/tasks/cli/showView.js +279 -0
  61. package/lib/{cli → tasks/cli}/taskCommands.js +55 -21
  62. package/lib/tasks/cli/tasksCli.js +149 -0
  63. package/lib/{core → tasks/core}/context.js +6 -9
  64. package/lib/tasks/core/errorOutcome.js +125 -0
  65. package/lib/{core → tasks/core}/hierarchy.js +1 -1
  66. package/lib/{core → tasks/core}/ops.js +17 -2
  67. package/lib/{core → tasks/core}/preflight/carryover.js +5 -1
  68. package/lib/{core → tasks/core}/preflight/codexEngine.js +36 -28
  69. package/lib/{core → tasks/core}/preflight/diagnose.js +4 -9
  70. package/lib/{core → tasks/core}/preflight/engine.js +9 -0
  71. package/lib/tasks/core/preflight/hostPaths.js +299 -0
  72. package/lib/{core → tasks/core}/preflight/input.js +33 -5
  73. package/lib/{core → tasks/core}/preflight/instructions.js +19 -2
  74. package/lib/{core → tasks/core}/preflight/mockEngine.js +27 -8
  75. package/lib/{core → tasks/core}/preflight/render.js +22 -3
  76. package/lib/{core → tasks/core}/preflight/service.js +86 -11
  77. package/lib/{core → tasks/core}/preflight/uiRender.js +5 -2
  78. package/lib/{core → tasks/core}/requestOps.js +214 -17
  79. package/lib/{core → tasks/core}/reviewRuns.js +127 -22
  80. package/lib/{core → tasks/core}/store/attachments.js +3 -2
  81. package/lib/{core → tasks/core}/store/collection.js +21 -2
  82. package/lib/tasks/core/store/fieldGroups.js +30 -0
  83. package/lib/tasks/core/store/jsonRecord.js +30 -0
  84. package/lib/{core → tasks/core}/store/normalize.js +15 -10
  85. package/lib/{core → tasks/core}/store/noteStore.js +2 -2
  86. package/lib/{core → tasks/core}/store/preflightStore.js +59 -22
  87. package/lib/{core → tasks/core}/store/projectFile.js +1 -1
  88. package/lib/{core → tasks/core}/store/workspace.js +28 -6
  89. package/lib/{core → tasks/core}/userConfig.js +1 -1
  90. package/lib/{core → tasks/core}/workTargets.js +1 -1
  91. package/lib/tasks/features/metrics/cli/metricsCommands.js +77 -0
  92. package/lib/tasks/features/metrics/core/definitions.js +445 -0
  93. package/lib/tasks/features/metrics/core/index.js +112 -0
  94. package/lib/tasks/features/metrics/core/manual.js +179 -0
  95. package/lib/tasks/features/metrics/server/metricsRoutes.js +8 -0
  96. package/lib/tasks/features/metrics/shared/metrics.js +42 -0
  97. package/lib/{core/milestoneReview → tasks/features/milestoneReview/core}/code.js +2 -11
  98. package/lib/{core/milestoneReview → tasks/features/milestoneReview/core}/material.js +5 -6
  99. package/lib/{core/milestoneReview → tasks/features/milestoneReview/core}/review.js +2 -2
  100. package/lib/{core/milestoneReview → tasks/features/milestoneReview/core}/service.js +38 -100
  101. package/lib/{core/milestoneReview → tasks/features/milestoneReview/core}/store.js +3 -3
  102. package/lib/{server/api → tasks/features/milestoneReview/server}/milestoneReviewRoutes.js +7 -13
  103. package/lib/{cli → tasks/features/quality/cli}/qualityCommands.js +36 -11
  104. package/lib/{core → tasks/features/quality/core}/qualityImprovement.js +16 -15
  105. package/lib/tasks/features/records/cli/revisitCommands.js +73 -0
  106. package/lib/tasks/features/records/core/completionRefs.js +46 -0
  107. package/lib/tasks/features/records/core/reviewCandidates.js +76 -0
  108. package/lib/tasks/features/records/shared/completionRecord.js +329 -0
  109. package/lib/tasks/features/records/shared/reviewCandidate.js +313 -0
  110. package/lib/tasks/features/records/shared/reworkHistory.js +86 -0
  111. package/lib/{cli → tasks/features/releaseNotes/cli}/releaseNotesCommands.js +7 -7
  112. package/lib/{core/releaseNotes → tasks/features/releaseNotes/core}/completeRequests.js +5 -6
  113. package/lib/{core/releaseNotes → tasks/features/releaseNotes/core}/generate.js +3 -14
  114. package/lib/{core/releaseNotes → tasks/features/releaseNotes/core}/material.js +3 -4
  115. package/lib/{core/releaseNotes → tasks/features/releaseNotes/core}/service.js +1 -1
  116. package/lib/{core/releaseNotes → tasks/features/releaseNotes/core}/store.js +2 -2
  117. package/lib/{server/api → tasks/features/releaseNotes/server}/releaseNoteRoutes.js +11 -20
  118. package/lib/tasks/features/requirements/cli/requirementCommands.js +289 -0
  119. package/lib/{shared → tasks/features/requirements/shared}/acceptance.js +292 -18
  120. package/lib/tasks/features/requirements/shared/requirementSource.js +635 -0
  121. package/lib/tasks/features/retro/cli/retroCommands.js +106 -0
  122. package/lib/tasks/features/retro/core/retrospective.js +197 -0
  123. package/lib/tasks/features/retro/shared/retrospective.js +286 -0
  124. package/lib/tasks/features/settings/cli/projectSettings.js +245 -0
  125. package/lib/{cli → tasks/features/settings/cli}/userConfig.js +50 -3
  126. package/lib/{core → tasks/features/settings/core}/machineSettingsEdit.js +2 -2
  127. package/lib/{core → tasks/features/settings/core}/repoAdmin.js +3 -3
  128. package/lib/{core → tasks/features/settings/core}/userTheme.js +2 -2
  129. package/lib/{server/api → tasks/features/settings/server}/repoRoutes.js +2 -2
  130. package/lib/{server/api → tasks/features/settings/server}/userThemeRoutes.js +3 -3
  131. package/lib/{cli → tasks/features/taskReview/cli}/taskReviewCommands.js +5 -5
  132. package/lib/{core/taskReview → tasks/features/taskReview/core}/material.js +13 -7
  133. package/lib/{core/taskReview → tasks/features/taskReview/core}/review.js +10 -3
  134. package/lib/{core/taskReview → tasks/features/taskReview/core}/service.js +24 -85
  135. package/lib/{core/taskReview → tasks/features/taskReview/core}/store.js +4 -4
  136. package/lib/{server/api → tasks/features/taskReview/server}/taskReviewRoutes.js +7 -14
  137. package/lib/{server → tasks/server}/api/manifest.js +51 -3
  138. package/lib/{server → tasks/server}/api/routes.js +134 -65
  139. package/lib/tasks/shared/commitRefs.js +10 -0
  140. package/lib/{shared → tasks/shared}/preflightInput.js +1 -1
  141. package/package.json +1 -43
  142. package/skills/p3/SKILL.md +9 -181
  143. package/dist/web/assets/ImprovementDialog-kQaVBGWH.js +0 -1
  144. package/dist/web/assets/Outputs-_nU_p3nu.js +0 -1
  145. package/dist/web/assets/RequestStatus-RG-OVQYY.js +0 -1
  146. package/dist/web/assets/Tabs-ew9i5SKX.js +0 -1
  147. package/dist/web/assets/TagInput-BtlJTF7i.js +0 -1
  148. package/dist/web/assets/TaskDrawer-DW8GyJqI.js +0 -6
  149. package/dist/web/assets/_requestId-6Nb727dD.js +0 -1
  150. package/dist/web/assets/_requestId-BykTgPax.js +0 -1
  151. package/dist/web/assets/appCtx-CxDdXABS.js +0 -1
  152. package/dist/web/assets/archive-Ckh295Xe.js +0 -1
  153. package/dist/web/assets/board-BVAIjK-Y.js +0 -1
  154. package/dist/web/assets/done-BGfA-3MA.js +0 -1
  155. package/dist/web/assets/draft-CfJeyLOl.js +0 -1
  156. package/dist/web/assets/index-CgRU744I.css +0 -2
  157. package/dist/web/assets/index-DacQ0yl4.js +0 -12
  158. package/dist/web/assets/new-DVygWvVc.js +0 -1
  159. package/dist/web/assets/outputs-B6xDsLZf.js +0 -1
  160. package/dist/web/assets/preflightInput-BAeEJYUK.js +0 -2
  161. package/dist/web/assets/preload-helper-DyCqp21K.js +0 -1
  162. package/dist/web/assets/release-notes-CCpzyiNf.js +0 -5
  163. package/dist/web/assets/requestData-D5vBnuMh.js +0 -1
  164. package/dist/web/assets/routes-Q91zvNc0.js +0 -4
  165. package/dist/web/assets/settings-BzRgcmUm.js +0 -1
  166. package/dist/web/assets/workTarget-C9c57JAO.js +0 -30
  167. package/lib/cli/readOnly.js +0 -38
  168. package/lib/cli/showView.js +0 -166
  169. /package/lib/{core/store → kit}/frontmatter.js +0 -0
  170. /package/lib/{core/store → kit}/fsutil.js +0 -0
  171. /package/lib/{cli → tasks/cli}/format.js +0 -0
  172. /package/lib/{core → tasks/core}/chatgpt.js +0 -0
  173. /package/lib/{core → tasks/core}/machineSettings.js +0 -0
  174. /package/lib/{core → tasks/core}/preflight/codexImage.js +0 -0
  175. /package/lib/{core → tasks/core}/preflight/docker.js +0 -0
  176. /package/lib/{core → tasks/core}/preflight/launch.js +0 -0
  177. /package/lib/{core → tasks/core}/preflight/launcher.mjs +0 -0
  178. /package/lib/{core → tasks/core}/preflight/mock-ui.html +0 -0
  179. /package/lib/{core → tasks/core}/preflight/mock-ui.png +0 -0
  180. /package/lib/{core → tasks/core}/preflight/owner.js +0 -0
  181. /package/lib/{core → tasks/core}/preflight/render-image/Dockerfile +0 -0
  182. /package/lib/{core → tasks/core}/preflight/render-image/fonts-ja.conf +0 -0
  183. /package/lib/{core → tasks/core}/preflight/render-image/render.mjs +0 -0
  184. /package/lib/{core → tasks/core}/preflight/split.js +0 -0
  185. /package/lib/{core → tasks/core}/preflight/uiMaterials.js +0 -0
  186. /package/lib/{core → tasks/core}/preflight/wireframe.js +0 -0
  187. /package/lib/{core → tasks/core}/preflight/xlsx.js +0 -0
  188. /package/lib/{core → tasks/core}/redact.js +0 -0
  189. /package/lib/{core → tasks/core}/repoRefs.js +0 -0
  190. /package/lib/{core → tasks/core}/requestStatus.js +0 -0
  191. /package/lib/{core → tasks/core}/store/archivedTasks.js +0 -0
  192. /package/lib/{core → tasks/core}/store/dataWatcher.js +0 -0
  193. /package/lib/{core → tasks/core}/store/locate.js +0 -0
  194. /package/lib/{core → tasks/core}/supersede.js +0 -0
  195. /package/lib/{core/milestoneReview → tasks/features/milestoneReview/core}/mockReviewer.js +0 -0
  196. /package/lib/{shared → tasks/features/milestoneReview/shared}/milestoneReview.js +0 -0
  197. /package/lib/{core → tasks/features/quality/core}/quality.js +0 -0
  198. /package/lib/{shared → tasks/features/quality/shared}/quality.js +0 -0
  199. /package/lib/{shared → tasks/features/quality/shared}/qualityImprovement.js +0 -0
  200. /package/lib/{shared → tasks/features/quality/shared}/qualityTemplates.js +0 -0
  201. /package/lib/{core/releaseNotes → tasks/features/releaseNotes/core}/mockSummarizer.js +0 -0
  202. /package/lib/{core/taskReview → tasks/features/taskReview/core}/mockReviewer.js +0 -0
  203. /package/lib/{core/taskReview → tasks/features/taskReview/core}/paths.js +0 -0
  204. /package/lib/{shared → tasks/features/taskReview/shared}/taskReview.js +0 -0
  205. /package/lib/{server → tasks/server}/api/chatgptRoutes.js +0 -0
  206. /package/lib/{server → tasks/server}/api/local.js +0 -0
  207. /package/lib/{shared → tasks/shared}/dates.js +0 -0
  208. /package/lib/{shared → tasks/shared}/directTask.js +0 -0
  209. /package/lib/{shared → tasks/shared}/hierarchy.js +0 -0
  210. /package/lib/{shared → tasks/shared}/milestoneGoals.js +0 -0
  211. /package/lib/{shared → tasks/shared}/milestoneOrder.js +0 -0
  212. /package/lib/{shared → tasks/shared}/preflightRunner.js +0 -0
  213. /package/lib/{shared → tasks/shared}/refs.js +0 -0
  214. /package/lib/{shared → tasks/shared}/repos.js +0 -0
  215. /package/lib/{shared → tasks/shared}/scopeView.js +0 -0
  216. /package/lib/{shared → tasks/shared}/tags.js +0 -0
  217. /package/lib/{shared → tasks/shared}/taskBlock.js +0 -0
  218. /package/lib/{shared → tasks/shared}/types.js +0 -0
  219. /package/lib/{shared → tasks/shared}/workTarget.js +0 -0
@@ -0,0 +1,198 @@
1
+ import { execFileSync } from "node:child_process";
2
+ import { readFileSync, statSync } from "node:fs";
3
+ import { join } from "node:path";
4
+ import YAML from "yaml";
5
+ import { ENTRY_VERSION } from "./guide.js";
6
+ import { AGENT_TARGETS, AGENTS_MARK, agentsSnippet, findSections, KINDS, SKILL_SOURCE } from "./project.js";
7
+ import { repoRoot } from "../kit/usage.js";
8
+ const DOCS = ["AGENTS.md", "CLAUDE.md"];
9
+ const SKILL_VERSION_KEY = "p3-entry-version";
10
+ const SECTION_VERSION = /<!--\s*p3-entry-version:\s*(\S*?)\s*-->/;
11
+ const lf = (s) => s.replace(/\r\n?/g, "\n");
12
+ /** 入口の版(正の整数)。読めなければ undefined */
13
+ function parseVersion(v) {
14
+ const s = typeof v === "number" ? String(v) : typeof v === "string" ? v.trim() : "";
15
+ return /^[1-9]\d*$/.test(s) ? Number(s) : undefined;
16
+ }
17
+ /** 今いる git の作業ツリーのルート(git 管理外は今いる場所) */
18
+ function worktreeRoot(cwd) {
19
+ try {
20
+ return execFileSync("git", ["rev-parse", "--show-toplevel"], { cwd, encoding: "utf8", stdio: ["ignore", "pipe", "ignore"] }).trim() || cwd;
21
+ }
22
+ catch {
23
+ return cwd;
24
+ }
25
+ }
26
+ function read(file) {
27
+ try {
28
+ if (statSync(file).isDirectory())
29
+ return { ok: false, missing: false, error: "フォルダになっています" };
30
+ return { ok: true, text: lf(readFileSync(file, "utf8")) };
31
+ }
32
+ catch (e) {
33
+ const code = e.code;
34
+ if (code === "ENOENT" || code === "ENOTDIR")
35
+ return { ok: false, missing: true };
36
+ return { ok: false, missing: false, error: `${code ?? "読めません"}: ${e.message}` };
37
+ }
38
+ }
39
+ function versionStatus(version, same, what) {
40
+ if (version < ENTRY_VERSION)
41
+ return { status: "outdated", reason: `${what}の入口の版 ${version} が、この CLI の版 ${ENTRY_VERSION} より古い` };
42
+ if (version > ENTRY_VERSION)
43
+ return { status: "newer", reason: `${what}の入口の版 ${version} が、この CLI の版 ${ENTRY_VERSION} より新しい(この CLI が古い可能性)` };
44
+ return same ? { status: "current", reason: "同梱の入口と同じ" } : { status: "modified", reason: `入口の版は同じだが、同梱の入口と中身が違う(手で直した可能性)` };
45
+ }
46
+ function diagnoseSkill(root, k, referenced, bundled) {
47
+ const path = AGENT_TARGETS[k].path;
48
+ const base = { path, kind: "skill", target: k };
49
+ const r = read(join(root, path));
50
+ if (!r.ok) {
51
+ if (!r.missing)
52
+ return { ...base, version: null, status: "unreadable", reason: r.error };
53
+ // 節が指していない先は、選ばなかった先として扱う(無くてよい)
54
+ return referenced ? { ...base, version: null, status: "missing", reason: "p3 の節が指しているのに、スキルがありません" } : undefined;
55
+ }
56
+ const fm = /^---\n([\s\S]*?)\n---(?:\n|$)/.exec(r.text);
57
+ let meta;
58
+ try {
59
+ const parsed = fm ? YAML.parse(fm[1]) : undefined;
60
+ meta = parsed && typeof parsed === "object" ? parsed : undefined;
61
+ }
62
+ catch {
63
+ return { ...base, version: null, status: "unknown", reason: "スキルの frontmatter を読めません" };
64
+ }
65
+ const metadata = meta?.metadata && typeof meta.metadata === "object" ? meta.metadata : undefined;
66
+ if (metadata && SKILL_VERSION_KEY in metadata) {
67
+ const v = parseVersion(metadata[SKILL_VERSION_KEY]);
68
+ if (v === undefined)
69
+ return { ...base, version: null, status: "unknown", reason: `入口の版(metadata.${SKILL_VERSION_KEY})が正の整数ではありません` };
70
+ return { ...base, version: v, ...versionStatus(v, r.text === bundled, "スキル") };
71
+ }
72
+ if (meta?.name === "p3")
73
+ return { ...base, version: null, status: "outdated", reason: "入口の版の無い、前の p3 のスキル(手順の全文の写し)" };
74
+ return { ...base, version: null, status: "unknown", reason: "p3 のスキルの形ではありません(name: p3 も入口の版もありません)" };
75
+ }
76
+ /** 節が同梱の入口のどれか(参照するスキルの組み合わせ・見出しの段の違いは許す)と同じか */
77
+ function sameSection(body, level) {
78
+ const subsets = [["claude"], ["codex"], ["claude", "codex"]];
79
+ return subsets.some((kinds) => lf(agentsSnippet(kinds)).replace(/^\n/, "").replace(/^## /, `${"#".repeat(level)} `).trim() === body.trim());
80
+ }
81
+ function diagnoseSections(root, primaryDoc) {
82
+ const entries = [];
83
+ const referenced = new Set();
84
+ for (const doc of DOCS) {
85
+ const r = read(join(root, doc));
86
+ const primary = doc === primaryDoc;
87
+ if (!r.ok) {
88
+ if (!r.missing)
89
+ entries.push({ path: doc, kind: "section", primary, version: null, status: "unreadable", reason: r.error });
90
+ continue;
91
+ }
92
+ const sections = findSections(r.text);
93
+ if (!sections.length) {
94
+ if (r.text.includes(AGENTS_MARK))
95
+ entries.push({ path: doc, kind: "section", primary, version: null, status: "unknown", reason: `「${AGENTS_MARK}」が見出しとして見つかりません` });
96
+ continue;
97
+ }
98
+ if (sections.length > 1) {
99
+ entries.push({ path: doc, kind: "section", primary, version: null, status: "unknown", reason: `「${AGENTS_MARK}」の節が ${sections.length} つあります(どれが p3 の節か決められません)` });
100
+ continue;
101
+ }
102
+ const { start, end, level } = sections[0];
103
+ const body = r.text.split("\n").slice(start, end).join("\n");
104
+ for (const k of KINDS)
105
+ if (body.includes(AGENT_TARGETS[k].path))
106
+ referenced.add(k);
107
+ const m = SECTION_VERSION.exec(body);
108
+ if (!m) {
109
+ entries.push({ path: doc, kind: "section", primary, version: null, status: "outdated", reason: "入口の版の無い、前の p3 の節(手順の要約の写し)" });
110
+ continue;
111
+ }
112
+ const v = parseVersion(m[1]);
113
+ if (v === undefined) {
114
+ entries.push({ path: doc, kind: "section", primary, version: null, status: "unknown", reason: "節の入口の版(p3-entry-version)が正の整数ではありません" });
115
+ continue;
116
+ }
117
+ entries.push({ path: doc, kind: "section", primary, version: v, ...versionStatus(v, sameSection(body, level), "節") });
118
+ }
119
+ return { entries, referenced };
120
+ }
121
+ /** p3 agents に渡す先(置いてある・指しているスキルから。分からなければ選ばせる) */
122
+ function choiceOf(kinds) {
123
+ if (kinds.has("claude") && kinds.has("codex"))
124
+ return "both";
125
+ if (kinds.has("claude"))
126
+ return "claude";
127
+ if (kinds.has("codex"))
128
+ return "codex";
129
+ return "claude|codex|both";
130
+ }
131
+ const CMD = "pnpx @infodb/p3 agents";
132
+ export function diagnoseAgents(cwd) {
133
+ const root = worktreeRoot(cwd);
134
+ const main = repoRoot(cwd);
135
+ const base = { root, ...(main !== root ? { writeRoot: main } : {}), expectedVersion: ENTRY_VERSION };
136
+ try {
137
+ const bundled = lf(readFileSync(SKILL_SOURCE, "utf8"));
138
+ const primaryDoc = DOCS.find((d) => read(join(root, d)).ok) ?? "AGENTS.md";
139
+ const sections = diagnoseSections(root, primaryDoc);
140
+ const skills = KINDS.map((k) => diagnoseSkill(root, k, sections.referenced.has(k), bundled)).filter((e) => !!e);
141
+ const placed = skills.length + sections.entries.length > 0;
142
+ const entries = [...skills, ...sections.entries];
143
+ // スキルはあるのに節がどこにも無い
144
+ if (skills.length && !sections.entries.length) {
145
+ entries.push({ path: primaryDoc, kind: "section", primary: true, version: null, status: "missing", reason: `スキルはあるのに、${primaryDoc} に「${AGENTS_MARK}」の節がありません` });
146
+ }
147
+ const kinds = new Set([...sections.referenced, ...skills.map((s) => s.target)]);
148
+ const choice = choiceOf(kinds);
149
+ const advice = [];
150
+ const has = (s) => entries.some((e) => e.status === s);
151
+ if (!placed)
152
+ advice.push(`AI 向けの入口が置かれていません。置くなら、人が先を選んで ${CMD} claude|codex|both を実行する`);
153
+ if (has("outdated"))
154
+ advice.push(`古い入口があります。人が差分(git diff)を確かめ、p3 の節の中に足したプロジェクト固有の決まりがあれば節の外へ移してから ${CMD} ${choice} --force で更新する`);
155
+ if (has("missing")) {
156
+ const missingSkills = entries.filter((e) => e.status === "missing" && e.kind === "skill").map((e) => e.target);
157
+ advice.push(`足りない入口があります。人が ${CMD} ${missingSkills.length ? choiceOf(new Set(missingSkills)) : choice} で置く(既にある入口は変えません)`);
158
+ }
159
+ if (has("modified"))
160
+ advice.push("入口の版は同じなのに中身が同梱の入口と違うものがあります。手で直した内容を確かめてください(--force は直した内容を消すので、すぐには勧めません)");
161
+ if (has("newer"))
162
+ advice.push("この CLI より新しい入口があります。古い p3 で動いていないか(pnpx @infodb/p3 で呼んでいるか、guide の cliVersion)を確かめてください。--force で古い入口に戻さない");
163
+ if (has("unknown"))
164
+ advice.push("形の分からない入口があります。節が複数なら手で1つの節(見出し「## タスク管理(infodb p3)」)に整理し、版の書き方を確かめてください");
165
+ if (has("unreadable"))
166
+ advice.push("読めない入口があります。ファイルの権限・種類を確かめてください");
167
+ if (base.writeRoot && entries.some((e) => e.status !== "current")) {
168
+ advice.push(`p3 agents が書くのはメインの作業ツリー(${base.writeRoot})です。そこで更新・レビュー・コミットしてから、このブランチに取り込んでください`);
169
+ }
170
+ return { ...base, placed, ok: placed && entries.every((e) => e.status === "current"), entries, advice };
171
+ }
172
+ catch (e) {
173
+ return { ...base, placed: false, ok: false, entries: [], advice: [], problem: `入口を調べられませんでした: ${e.message}` };
174
+ }
175
+ }
176
+ const STATUS_LABEL = {
177
+ current: "最新",
178
+ outdated: "古い",
179
+ missing: "無い",
180
+ modified: "変更あり",
181
+ newer: "CLI より新しい",
182
+ unknown: "形が不明",
183
+ unreadable: "読めない",
184
+ };
185
+ /** 人向けの表示(whoami と guide の通知) */
186
+ export function agentsText(d) {
187
+ if (d.problem)
188
+ return [d.problem];
189
+ if (!d.placed)
190
+ return ["置かれていません", ...d.advice.map((a) => ` → ${a}`)];
191
+ if (d.ok)
192
+ return [`最新(${d.entries.map((e) => e.path).join("・")})`];
193
+ return [
194
+ `対応が必要(入口の版 ${d.expectedVersion})`,
195
+ ...d.entries.filter((e) => e.status !== "current").map((e) => ` ${STATUS_LABEL[e.status]} ${e.path} ${e.reason}`),
196
+ ...d.advice.map((a) => ` → ${a}`),
197
+ ];
198
+ }
@@ -0,0 +1,27 @@
1
+ import { readFileSync } from "node:fs";
2
+ import { fileURLToPath } from "node:url";
3
+ /**
4
+ * AI エージェント向けの作業の手順(`p3 guide`)。原本はこの CLI と一緒に配る guide.md の1つ。
5
+ * 置いたスキルや AGENTS.md の節は入口だけにして、手順の本文は実行中の CLI から読ませる(CLI が新しければ手順も新しい)。
6
+ * プロジェクトを決める前に扱い、データ・個人設定・置いたファイルを読まず変えない。Codex・Docker・npm へも問い合わせない。
7
+ */
8
+ /** guide の JSON の形の版(項目を変えたら上げる) */
9
+ export const GUIDE_SCHEMA_VERSION = 1;
10
+ /**
11
+ * 入口(置いたスキル・節)の決まりの版。起動のしかた・読み込みの約束など、入口に書くことを変えたときだけ上げる。
12
+ * 手順の本文(guide.md)を直しただけでは上げない
13
+ */
14
+ export const ENTRY_VERSION = 1;
15
+ /** 手順の原本(ソースでは src/cli/guide.md、配布物では lib/cli/guide.md。scripts/build-cli.mjs が写す) */
16
+ export const GUIDE_SOURCE = fileURLToPath(new URL("./guide.md", import.meta.url));
17
+ /** この CLI のパッケージ(src/cli・lib/cli のどちらからも2つ上) */
18
+ const PACKAGE_JSON = new URL("../../package.json", import.meta.url);
19
+ /** 実行中のパッケージの版。最新かどうかの判断には使わない */
20
+ export function cliVersion() {
21
+ const v = JSON.parse(readFileSync(PACKAGE_JSON, "utf8")).version;
22
+ return typeof v === "string" ? v : "0.0.0";
23
+ }
24
+ /** 毎回原本を読む(写しを持たない) */
25
+ export function guide() {
26
+ return { schemaVersion: GUIDE_SCHEMA_VERSION, cliVersion: cliVersion(), entryVersion: ENTRY_VERSION, guide: readFileSync(GUIDE_SOURCE, "utf8") };
27
+ }
@@ -0,0 +1,217 @@
1
+ # infodb p3 の作業の手順(AI エージェント向け)
2
+
3
+ この手順は、今動いている p3 の CLI が返したもの(`guide`)で、その版の CLI の動きに合っている。
4
+ このリポジトリの作業は、infodb p3 の **要望** と、要望から生まれた **タスク** で管理する。
5
+ 要望・タスク・Preflight の記録は「データのフォルダ」にファイルで置かれ、人と AI が同じ CLI で操作する。
6
+ データのフォルダのファイルは直接編集しない。必ず CLI を通す。
7
+
8
+ ## CLI の呼び方
9
+
10
+ ```bash
11
+ P3_ACTOR=ai:<エージェント名> pnpx @infodb/p3 <コマンド> [引数] --json
12
+ ```
13
+
14
+ - この手順で `p3 <コマンド>` と書いたものは、**この手順を取得したときと同じ呼び方**(ふつうは `pnpx @infodb/p3`。`npx @infodb/p3` でもよい)で呼ぶ。
15
+ ほかの場所に入っている `p3`(`pnpm add -g` などで入れたもの)に勝手に切り替えない。古い版のままのことがあり、この手順と動きが合わない
16
+ - 最初に `p3 whoami --json` で、操作するプロジェクト・データのフォルダ・決まり方(`via`)・変更者・今の要望・Preflight の担当
17
+ (`preflight.runner`。下の「Preflight を頼まれたとき」)を確かめる。
18
+ 対象のプロジェクトは今いる場所(リポジトリ・作業ツリー)と個人設定から決まる。決まらなければ、出てきた一覧と案内に従って
19
+ `--project <名前>` を付ける(名前を推測で決めない)
20
+ - `via` が `cwd`(今いる場所で決まった)でなければ(`dir` / `project` / `legacy` / `only`)、それ以上 p3 を操作せず、
21
+ 対象のプロジェクトでよいかユーザーに確かめる。特に `only` は登録が1つだけというだけで、p3 を使わないフォルダでも決まる。
22
+ 推測した `--project` や `--dir` を付けて確認を避けない。ユーザーが対象を指定した・確かめた後は、その対象のまま続ける
23
+ - プロジェクトが無い・登録されていない(未登録)ときは、`p3 init`・`p3 join` を自分から実行しない。新しく作る(`init`)のか、
24
+ 共有されたものに参加する(`join`)のかをユーザーに確かめる
25
+ - `P3_ACTOR=ai:<名前>` は変更者の記録。変更するコマンドには必ず付ける
26
+ - 結果は `--json` で読む。人に見せる表はオプションなしの出力でよい
27
+ - 終了コード: 0 成功 / 1 使い方の誤り(メッセージに次にすることが出る)/ 2 見つからない / 3 競合(`show --brief` で読み直してやり直す)
28
+ - 詳細は、作業に使うときは短い出力 `show <要望ID>/T003 --brief --json` / `request show <要望ID> --brief --json` で読む
29
+ (本文・状態・rev・依存とその状態・置き換えの注意・成果物・ブランチだけが出る)
30
+ - 迷ったら `p3 help`
31
+
32
+ ## 置いた入口(スキル・節)の状態
33
+
34
+ このリポジトリに置いた AI 向けの入口(`.claude/skills/p3/SKILL.md`・`.agents/skills/p3/SKILL.md` と、AGENTS.md / CLAUDE.md の
35
+ 「タスク管理(infodb p3)」の節)の状態は、`guide --json` と `whoami --json` の `agents` に出る(今いる作業ツリーのものを読むだけ)。
36
+
37
+ - `agents.ok` が `true` なら何もしない
38
+ - `false` なら、作業を始める前に人に伝える: 入口ごとの `path`・`status`・`reason` と、`advice`(人が行う次の操作)。
39
+ `status` は `outdated`(古い)・`missing`(無い)・`modified`(版は同じで中身が違う)・`newer`(CLI より新しい)・`unknown`(形が不明)・
40
+ `unreadable`(読めない)。`placed` が `false`(どれも置いていない)なら、置くかどうかと先(claude / codex / both)は人が決める
41
+ - 入口のファイルを自分で書き換えない。`p3 agents`(とくに `--force`。手で直した分が消える)を自分で実行しない。更新は人が差分を
42
+ 確かめてから行う。`modified`・`newer`・`unknown` に `--force` を勧めない(`newer` は、この CLI が古い版で動いていないかを人に確かめてもらう)
43
+ - 入口が古いことだけを理由に、頼まれた作業を止めない(この手順は CLI から読んだ最新のもの)
44
+ - `agents.problem` があれば(調べられなかった)、その文を人に伝える。`whoami` のほかの結果はそのまま使ってよい
45
+ - `agents.writeRoot` があれば(今いるのが追加の作業ツリー)、`p3 agents` が書くのはそのメインの作業ツリーで、更新したものをこのブランチに
46
+ 取り込む必要があることも伝える
47
+
48
+ ## 人と AI の役割
49
+
50
+ | 操作 | するのは |
51
+ | --- | --- |
52
+ | 要望の登録(`request new`) | AI も人も |
53
+ | Preflight(評価・細分化。`preflight`) | 担当(`whoami --json` の `preflight.runner`)で決まる。**codex** は人(人がチャットで対象の要望の手元の評価を明示的に頼んだときだけ AI が評価する)、**agent** は人に頼まれた AI(手元で評価する)。どちらも AI から始めない(下の「Preflight を頼まれたとき」) |
54
+ | タスク化(`accept`) | **人だけ** |
55
+ | タスクの着手・完了(`move ... doing` / `done`)と成果物の登録、作業中に見つけたタスクの追加 | AI も人も |
56
+ | 要望を対応済にする(`request set <要望ID> status=resolved`) | 作業を終えた AI(か人) |
57
+ | 要望の完了済(`done`)・見送り(`rejected`)、タスクの済み(`check`) | **人だけ** |
58
+
59
+ ## 要望を登録する(ユーザーから新しい作業を頼まれたとき)
60
+
61
+ 1. `request new "<タイトル>" --body "<背景・やりたいこと・完了条件を箇条書きで>"`(任意で `--area src/web --tag ui --due YYYY-MM-DD --milestone <id>`)
62
+ 2. 登録したら要望 ID をユーザーに伝えて終える。**Preflight(評価・細分化)は自分から始めず、タスク化(`accept`)は人が行う。**
63
+ Preflight を勧めたり、実行してよいか尋ねたりもしない。人に Preflight を頼まれたら、下の「Preflight を頼まれたとき」に従う
64
+ (担当で分ける)。人がタスク化を終えたら、タスクを進める
65
+
66
+ 人が行った Preflight の内容を聞かれたら、`drafts <要望ID>` で評価とタスク案を読んで答えてよい(読むだけ)。
67
+ `drafts` には「調べた範囲」(参照先ごとに読んだか)と「判断の根拠」(確かめた / 推測)も出る。答えるときは、見ていない参照先や
68
+ 推測の根拠に基づく判断であることを伝える。参照先の登録(`repo add` / `repo path`)はユーザーに頼まれたときだけ行う。
69
+ 評価の確認事項への回答を頼まれたら、`clarify <要望ID> --json` で確認事項(ID・確認先・質問・必要な根拠)を読み、ID のある確認事項は
70
+ `answer <要望ID> <Q1> --body "..." --by <回答した役割> --on YYYY-MM-DD` で要望に残す(ID の無い以前の確認事項は
71
+ `preflight <要望ID> --note "..." --note-only` のメモ)。どちらも評価の実行はしない(再評価は人が明示して始める)。
72
+ 要求の出典・根拠の記録(`source`)は、人に頼まれた内容だけを残す。回答元・確かめた人は人が伝えた役割名で書き、氏名・連絡先は書かない。
73
+
74
+ ## Preflight を頼まれたとき(担当で分ける)
75
+
76
+ 誰が Preflight を実行するかは、プロジェクトの担当(`whoami --json` の `preflight.runner`)で決まる。担当は人が
77
+ `p3 init` か `p3 config set preflight.runner=...` で決める(AI は変えない)。
78
+
79
+ - **`codex`**(`preflight` の項目が無い古い p3 も同じ): Preflight は人が `p3 preflight` か画面から実行する(Codex が評価する)。
80
+ AI は `p3 preflight <要望ID>`(`--prepare` の無い通常の実行)をしない。人がチャットで対象の要望を挙げて、手元の評価を明示的に
81
+ 頼んだとき(例: 「要望 261009-k7m3x の Preflight を Claude Code のこのチャットで実行して」)だけ、下の手順で評価する。
82
+ 「Preflight して」とだけ頼まれたら、断らずに、人が `p3 preflight <要望ID>`・画面で実行するのか、このチャットで手元の評価をするのかを確かめる
83
+ - **`agent`**(Codex を使えない環境): 人に Preflight を頼まれたら(「Preflight して」「要望 <ID> の Preflight をして」など。
84
+ 「このチャットで」のような言い方は求めない)、下の手順で手元で評価する。`p3 preflight <要望ID>`(`--prepare` の無い通常の実行)はしない
85
+ - **`runner` が `null`**(担当が読めない。理由は `problem`): `agent` と推測しない。`problem` を人に伝え、`codex` と同じ扱いにする
86
+ - どの担当でも: 要望の登録・タスクの作業・子の要望の作成・分割の採用のついでに自分から始めない(勧めたり、実行してよいか尋ねたりも
87
+ しない)。対象の要望が分からなければ確かめる。子の要望も親と同じ担当・同じ手順。P3 はモデルを呼ばない(`claude -p` や API キーは使わない)
88
+
89
+ 1. `whoami --json` で対象のプロジェクトと担当を確かめ(`via` の扱いは上と同じ)、`request show <要望ID> --brief --json` で頼まれた要望かを確かめる
90
+ 2. 準備: `preflight <要望ID> --prepare --json`(変更なので `P3_ACTOR` を付ける)。評価対象を固定し、`instructions`(指示のファイル)・
91
+ `outputs`(書く成果物)・`run`(PF-...)・`next`(次のコマンド)を返す。始められない(同じ要望の Preflight が待っている・実行中)
92
+ ときは止めて人に伝える(自分の判断で `--cancel` しない。`--acknowledge-stopped` は、人が run の止まっていることを確かめて
93
+ 中断にするよう頼んだときだけ)
94
+ 3. `instructions` のファイルを最後まで読み、その「制約」に従って評価する。指示の長い文はスキルやメモに写さない(P3 が要望ごとに作る)。
95
+ 参照先は読むだけ(変更・git の書き込み・アプリの起動をしない)。書き込むのは `outputs` に挙がった、その run の成果物だけ
96
+ (`assessment.json`・`drafts/`・`children/`・`ui/index.json`・`ui/src/`)。これが「データのフォルダを直接編集しない」の唯一の例外で、
97
+ `run.json`・`instructions.md`・ほかの要望やタスクのファイルは書かない。指示のファイル・添付・参照先が読めなければ、読んだことにせず、
98
+ 評価に未確認として書く(読めない理由も人に伝える)
99
+ 4. 書き終えたら `preflight <要望ID> --complete --run <run> --json`。`code: invalid_result` なら `problems` を直して同じコマンドをやり直す
100
+ (run は待ったまま。ファイルを消して作り直さない)
101
+ 5. `drafts <要望ID>` で取り込んだ評価(判定・確認事項・タスク案か子の案)を読み、要約を人に伝えて終える。**タスク化(`accept`)・タスクの着手はしない**
102
+ (人が案を確かめて採用してから、「タスクを進める」に従う)
103
+ - 人にやめるよう頼まれたら `preflight <要望ID> --cancel --run <run>`
104
+
105
+ ## タスクを進める
106
+
107
+ 作業は **作業先のリポジトリの、要望のブランチ** で行う。タスクごとの作業先とブランチは
108
+ `show <要望ID>/T003 --brief --json` の `work`(`repo`・`branch`)に出る(要望全体は `request show <要望ID> --brief --json` の `branches`)。
109
+
110
+ 1. 作業先に入る: `work.repo` のリポジトリ(場所は `repo ls`)で、`work.branch` に切り替える(無ければ最新の既定のブランチから作る。
111
+ 作業ツリーを使うかどうかと置き場所は任せる)。`work.repo` が `null`(作業先なし: 調査・人の判断など)なら移動は要らない。ブランチの無い
112
+ 作業先(git でないフォルダ)はそのフォルダで作業する。このマシンのパスが未登録(`work.registered` が false)なら、場所をユーザーに
113
+ 聞いて登録してもらい(`repo path <名前> <パス>`)、`whoami` で今の要望と今いる参照先を確かめてから始める
114
+ 2. `ls --req <要望ID>` で一覧、`show <要望ID>/T003 --brief --json` で中身と依存を読む。`dependencies` の `status` が
115
+ `done` でない依存があるタスクから始めない(`null` は相手が見つからない。完了とは扱わず、ユーザーに確かめる)。
116
+ **置き換えられたタスク**(`ls` の `※置換`、`--json` の `superseded` と `warnings`)からは始めない。残っていれば扱いをユーザーに確かめる
117
+ (不要ならユーザーの了承を得て `archive`)。`move` が警告(`warnings`)を返したら、作業を止めてユーザーに伝える
118
+ **受け入れ基準**(`--brief --json` の `item.acceptanceCriteria`。A1, A2, ...)があれば、着手する前に読み、何を確かめれば完了かを
119
+ 決めてから作業する(無いタスクは本文の完了条件で判断する)。`[Q1]` で始まる基準はプロジェクトの品質基準
120
+ (`p3 quality`)から取り込んだもので、確認の方法(検査のコマンドと成功の条件か、人の確認の方法)が書いてある
121
+ 3. 着手: `move T003 doing --req <要望ID>`
122
+ 4. 作業し、プロジェクトのテストを通したら、**コミットする前に** 完了にする:
123
+ `move T003 done --req <要望ID> --output <成果物> --record - < record.md`(成果物が複数あれば `--output` を繰り返す)。
124
+ 成果物は今あるもの(変えたファイル・ドキュメントのパスや短い説明)。まだ無い URL や仮のコミットの SHA は書かない(URL は 8 で足す)。
125
+ **変更の記録(`--record`)は必須**: 何を変えたか(振る舞いの言葉で)・なぜ・入れた決まり・やめたもの を Markdown で短く書く。
126
+ 後の Preflight が経緯を調べるとき、タスクの解析・リリースノートの材料として読む(パスの羅列ではなく、目的と決まりを書く)。
127
+ テストが通っていない・作業が途中のうちは完了にしない。
128
+ **受け入れ基準があるタスクは、完了と同時に基準ごとの証拠と根拠の種類を残す**: `--evidence-json evidence.json`
129
+ (`--record -` と標準入力を取り合うので証拠はファイルで)。項目は `{"id":"A1","result":"met","evidence":"確かめた範囲・省いたこと","basis":{...}}` の並び。
130
+ 結果は `met`(満たした。証拠が要る)/ `unmet`(満たせなかった)/ `unverified`(確かめていない)で、満たせなかった・確かめて
131
+ いない項目はそうと理由を正直に書く(推測で `met` にしない)。証拠は自分の申告で、レビューの判定ではない。
132
+ 根拠(`basis`)は実際にしたことを選ぶ: テスト・コマンドを実行したなら `{"kind":"machine","command":"実行したコマンド","result":"終了コードと結果(失敗もそのまま)","target":"<参照先>:<コミット>(未コミットならそう書く)"}`、
133
+ コード・資料・画面を読んで確かめたなら `{"kind":"read","reference":"読んだものと確かめた内容"}`、どちらでもなければ
134
+ `{"kind":"declaration"}`(申告のみ)、確かめていないなら結果を `unverified` にする(根拠は省ける)。読んだだけのものを検査結果ありにしない。
135
+ Markdown の `--evidence-file evidence.md`(見出し `## A1 met`)も使えるが、根拠は書けず「申告のみ」になる。
136
+ 変更の記録(`--record`)は何を変えたか・なぜ、証拠は基準ごとの確かめた材料で、役割が違う(両方書く)。
137
+ 未達・未検証を残して完了にしたら、そのことと理由をユーザーに伝える(不足があっても完了は拒まれないが、済みにするかは人が決める)。
138
+ 後から証拠を足す・直すなら `evidence <T> <ID> <結果> --file 本文.md --basis machine --command … --check-result … --target …`
139
+ (読んで確かめたなら `--basis read --reference …`)か、`evidence <T> --evidence-json evidence.json`。
140
+ 品質基準の検査は作業する側(あなた)が実行し、証拠には実行したコマンド・参照先とコミット(未コミットならそう書く)・結果・確かめた
141
+ 範囲・省いたならその理由を書く。P3 が実行して確かめたとは書かない(P3 はコマンドを実行しない)。
142
+ **`--json` で完了・再開したら、返った JSON の `completionSkipped`・`reworkSkipped` を見る**: どちらかがあれば、状態は変わったが
143
+ 完了の記録・手戻りの履歴が壊れていて新しい記録を残せていない。直接編集で直さず、要望とタスクの ID とその文をユーザーに伝える
144
+ (記録を残せたように伝えない。無ければ残せている)
145
+ 5. 作業中に見つけた追加の作業は `new "<タイトル>" --req <要望ID> --body "..."` でタスクにする(タスクの関係は Preflight のタスク化が張るもので、手では張らない。順序は本文に書く)
146
+ **進められなくなったら止まっている理由を付けて終える**(安全に続けられる通常の修正・調査の途中では使わない):
147
+ 人の判断や権限が要る・前提が崩れた・直しても調べてもテストが通らず先に進めない、などでこのタスクを続けられなくなったら、
148
+ `block <T> --req <要望ID> --reason "<具体的な理由>" --decision "<人に決めてほしいこと>" --json`(複数行は `--reason -` で標準入力)。
149
+ 人への質問を新しいタスクにする代わりに、今のタスクに付ける。未着手の依存待ちのタスクを作業中にしてまで付けない。
150
+ 返った JSON の `block` で保存できたことを確かめ、要望とタスクの ID・理由・いつから(`since`)・答えてほしいこと・確かめたこと・
151
+ 再開のしかたをユーザーに伝えて、そのタスクの作業を終えて回答を待つ。止まったまま完了・済み・要望の対応済に進めない
152
+ (止まったままは完了へ動かせない)。止まっていることを避けるために基準や証拠を書き換えない。停止の履歴と完了の変更の記録(`record`)は別。
153
+ 保存が競合・失敗したら読み直して結果を確かめ、記録できたと偽らずに伝える(タスクを変え続けて理由を覆い隠さない)
154
+ **回答を受けたら解除して再開する**: `unblock <T> --req <要望ID> --resolution "<回答・解決の内容>"`。人が先に解除していたら、
155
+ `show <T> --json` の停止の履歴で回答を読み、前提が満たされたことを確かめてから再開する。解除だけでは自動で再開しない。
156
+ 新しい理由で止まったら、新しい停止として付ける
157
+ 6. 要望のタスクが全部完了したら(`ls --req <要望ID>` が全部 done、成果物と検証も済み)、コミットする前に要望を **対応済** にする:
158
+ `request set <要望ID> status=resolved --json`。未完了のタスクがあると拒否される(終わらせるか、不要ならユーザーの了承を得て
159
+ `archive`)。拒否をタスクを偽って完了にする・ファイルを直接書き換えるなどで回避しない
160
+ 7. コミットして push する。データのフォルダ(`whoami` の場所)がこの作業ツリーの中にあって git で管理されている(無視されていない)なら、
161
+ **要望のフォルダ(`<データのフォルダ>/requests/<要望ID>/`)の変更も実装と同じコミットに入れる**。要望とタスク・変更の記録が
162
+ コードと一緒に残り、後のレビュー(AI のレビューも)で、コードだけでなく「何を目的に頼まれ、何をしたか」を精査できる。
163
+ 親子でつながる要望のフォルダも、まだコミットに入っていない変更があれば入れる: 子の要望なら**祖先の要望のフォルダ**(分割の採用・
164
+ 子の順・状態は親に残る)、親を対応済にするときは**子孫の要望のフォルダ**(見送りにした子など、実装の無い要望)。それ以外の要望や
165
+ 関係ない変更はまとめて add しない(`git status` でフォルダを確かめてから add する)。データのフォルダが外・別のリポジトリ・git で無視されている、または git の作業ツリー(worktree)で作業して
166
+ いてデータがメインの作業ツリーにあるときは、同じコミットには入らない(データの移動・写し・`git add -f` はしない。記録は p3 に
167
+ 残り、コードとは成果物の URL で結ぶ)。commit・push に失敗したら、完了の記録はそのまま残し、公開できていないことをユーザーに
168
+ 伝えてやり直す(完了を push できたことのように伝えない)。同じコミットに入れた要望のフォルダは、
169
+ マージするまで要望のブランチにしか無い。既定のブランチに切り替えると、その要望(子なら親の子の一覧からも)が消えたように見えるが、
170
+ データはブランチにある(作り直したり、別のブランチから写したりしない。親の詳細には `child_missing` が出る)
171
+ 8. コミットや PR の URL を残すなら、後から `move T003 done --req <要望ID> --output <URL>` で足す(完了・記録・前の成果物はそのまま。
172
+ 完了から戻さない)。要望のフォルダを同じコミットに入れているなら、この追記もコミットして同じブランチに push する(追記のコミット
173
+ 自身の URL は残さなくてよい)。PR はユーザーに確認してから作る(本文に要望 ID とタスクの一覧)。作った PR の URL は最後のタスクに
174
+ 足す。複数のリポジトリにまたがる要望は、関係するリポジトリの PR を全部 `--repo-output <参照先の名前>=<PR の URL>` で最後のタスクに
175
+ 残す(例: `move T005 done --repo-output app=<URL> --repo-output infra=<URL>`。1つのリポジトリなら今までどおり `--output` でよい)。
176
+ マージ・要望の完了済(`done`)は人が行う
177
+ 9. 対応済の後にタスクを足した・完了から戻したときは、要望は自動で進行中に戻る(`--json` の `reopened`)。
178
+ 終えたらもう一度 6 で対応済にする
179
+
180
+ ### 子の要望(大きい要望を分けたもの)
181
+
182
+ - 子の要望(`parent` のある要望)は、親とは別の要望として、子ごとのタスクとブランチで作業する(親のタスクにしない。
183
+ 手順は上と同じ)。親子は `request show <要望ID> --brief --json` の `parent`・`ancestors`・`children` で読む
184
+ - 分割の案(Preflight の子の案)の採用(`accept`)は人が行う。子の Preflight は親と同じく、頼まれたときだけ
185
+ 「Preflight を頼まれたとき」の担当に従う(分割の採用・子の作成から、自分で子の評価へ進まない)
186
+ - 子のタスクを全部終えたら、子を対応済にする(6)。親を対応済にするのは、親のタスクと見送り以外の子(`children`)が
187
+ 全部 対応済か完了済になってから。条件を満たさなければ拒否される(理由が出る)
188
+ - 子にタスクを足す・完了から戻すと、対応済の親も進行中に戻る(`--json` の `reopenedAncestors`)。完了済の親は変わらず
189
+ `warnings`(`ancestor_done`)が出るので、作業を止めて人に伝える
190
+
191
+ ## してはいけないこと
192
+
193
+ - Preflight(`preflight`)を自分から始めない・勧めない。`p3 preflight <要望ID>`(Codex で評価する通常の実行)は人が行い、AI は
194
+ しない。手元の評価(`--prepare` / `--complete`)は、上の「Preflight を頼まれたとき」の担当ごとの条件を満たしたときだけ
195
+ - タスク化(`accept`)をしない(人が行う。Preflight を頼まれたときも、評価の後にタスク化・着手へ進まない)
196
+ - `check`(済み)を付けない。済みは人が成果物を確認して付ける
197
+ - 要望のステータスを `done`(完了済)/ `rejected`(見送り)にしない(人が決める)。AI がするのは作業を終えたときの `resolved`(対応済)まで。
198
+ タスク化で `active` になるのは自動
199
+ - タスクを要望をまたいで動かさない。別の要望の作業なら、その要望にタスクを足すか、新しい要望を提案する
200
+ - データのフォルダ(`p3 whoami` に出る場所)や個人設定(`~/.config/infodb-p3/`)のファイルを直接書き換えない
201
+ (例外は、頼まれた Preflight で `--prepare` が返した run の成果物だけ)
202
+ - 人への質問をタスクにしない(続けられないなら今のタスクに止まっている理由を付ける)
203
+ - 止まっている理由を付けたまま作業を続けたり、完了・済み・対応済に進めたりしない。回答を受けずに自分で解除しない
204
+ - タスクの AI レビュー(`review`)を頼まれずに始めない(Codex を使い、利用者のプランを消費する)。頼まれたら Preflight と同じく担当で
205
+ 分け、`agent` のプロジェクトでも Codex で実行するのは人が明示したときだけ(`--engine codex`)。レビューの結果を理由に済みにしない・
206
+ 基準や証拠を書き換えない(結果は参考の記録で、済みは人が決める)
207
+ - 受け入れ基準を自分で消す・書き換える・並べ替えて、満たしたことにしない(基準を変える必要があれば人に確かめる。済みのタスクの
208
+ 基準・証拠を変えると人の済みが外れる)。確かめていない項目を `met` にしない
209
+ - 要求の出典の確認(`source ... confirm`・`--by` / `--on`)を、人が実際に確かめたと伝えた内容のほかに付けない。AI の評価・テストの
210
+ 結果・レビュー・人の済みを、確かめた人として記録しない(「確認記録あり」は人の確認の申告で、確認先が分からなければ分からないまま残す)
211
+ - 見直しが必要(候補)(`revisit`)を理由に、自分で再開・済みの付け直し・基準の書き換えをしない(候補は人が確かめる材料)。
212
+ 前提の変更の確認(`premise ... ack`)は、人が確かめたと伝えた内容のほかに付けない
213
+
214
+ ## 状況を報告する
215
+
216
+ - 全体: `progress`(マイルストーンごと)。要望の中: `ls --req <要望ID>`
217
+ - 画面はユーザーが `p3 serve` で開く(既定 http://localhost:4310)。CLI の変更はそのまま画面に反映される
package/lib/cli/help.js CHANGED
@@ -1,4 +1,4 @@
1
- import { RELATION_TYPES, REQUEST_STATUSES, relationTypes } from "../shared/types.js";
1
+ import { RELATION_TYPES, REQUEST_STATUSES, relationTypes } from "../tasks/shared/types.js";
2
2
  /** p3 help */
3
3
  export const HELP = `p3(infodb p3)— 要望ごとにフォルダを分けて管理するファイルベースのタスク管理
4
4
 
@@ -13,6 +13,8 @@ export const HELP = `p3(infodb p3)— 要望ごとにフォルダを分け
13
13
  --agents claude|codex|both AI 向けの使い方(スキルと AGENTS.md / CLAUDE.md の節)を置く先(値を省くと both。付けなければ置かない)
14
14
  agents claude|codex|both [--force] AI 向けの使い方を、今いるリポジトリに後から置く・最新にする(選んだ先だけ。データ・個人設定は変えない)
15
15
  違うものは上書きせず知らせる。--force で選んだ先のスキルと p3 の節だけを同梱の版にする(ほかの文は残す)
16
+ guide AI エージェント向けの作業の手順(この CLI に同梱した版)を出す。プロジェクトを決めず、何も変えない
17
+ --json で schemaVersion・cliVersion(実行中の版)・entryVersion(入口の決まりの版)・guide(手順の全文)
16
18
  join 既にあるプロジェクト(共有されたデータのフォルダ)に参加する。個人設定に登録するだけで、データ・リポジトリのファイルは変えない
17
19
  --project 名前 --dir フォルダ(既定はリポジトリのルートの .p3)--repo-name 参照先の名前(共有の定義にあるもの)--yes
18
20
  project [ls | add <名前> <フォルダ> | rm <名前>] 個人設定のプロジェクト
@@ -27,11 +29,15 @@ export const HELP = `p3(infodb p3)— 要望ごとにフォルダを分け
27
29
  codex.effort / codex.ensureImage / preflight.engine / serve.host / serve.port(キー= で消す)
28
30
  set codex.pathMap+=<このマシンのパス>=<Docker デーモンから見たパス> パスの対応を足す
29
31
  set codex.pathMap-=<このマシンのパス> 外す(codex.pathMap= で全部外す)
32
+ paths <このマシンのパス> ... Docker にマウントするときのホストのパスと決め方(DevContainer では自動。変えない)
30
33
  quality 品質基準(project.yaml の quality。未設定・設定済み・読めない)とテンプレートの改版の差分
31
34
  templates / template <id> 同梱のテンプレート(版つきの例。業界の標準への認証ではない)
32
- init 空で設定する / adopt <テンプレート> 写して採用する / upgrade <テンプレート> 改版の差分を当てる
33
- add --text 文 [--repo 名前] (--command コマンド --success 成功の条件 | --reference 確かめ方)
34
- set <Q1> [--text] [--repo 名前|all] [...] / rm <Q1> / exempt <Q1> --reason 理由 / unexempt <Q1>
35
+ 未設定のままでも作業は続けられる(init は必須ではない)。未設定から add / adopt をそのまま使える
36
+ init 意図して空にする(設定済みなら何も変えない)/ adopt <テンプレート> 写して採用する / upgrade <テンプレート> 改版の差分を当てる
37
+ add --text 文 [--repo 名前 ...] (--command コマンド --success 成功の条件 | --reference 確かめ方)
38
+ set <Q1> [--text] [--repo 名前 ...|all] [...] / rm <Q1> / exempt <Q1> --reason 理由 / unexempt <Q1>
39
+ --repo は繰り返して複数の参照先(例: --repo app --repo infra)。add で省くと全参照先、set で省くと対象を変えない。
40
+ all は全参照先で、個別の名前とは一緒に使えない。--repo を繰り返せるのは quality add / set だけ
35
41
  --version <版> で、他で変わっていれば競合(終了コード 3)。P3 はコマンドを実行しない
36
42
  improve [task <要望>/<T> <run> | milestone <ID> <run>] 品質の不足の診断と改善要望の原稿(読むだけ)
37
43
  --key <不足の鍵>... で選ぶ / --register --hash <診断の版> [--title] [--body] [--reopen] で明示して登録する
@@ -56,6 +62,13 @@ export const HELP = `p3(infodb p3)— 要望ごとにフォルダを分け
56
62
  できるか・対象・hash は show で見る。材料が変わっていれば何も変えずに終了コード 3、途中で止まったら非ゼロ
57
63
  例: p3 release-notes generate v0.2 > draft.md → 直す → p3 release-notes save v0.2 --file draft.md
58
64
  p3 release-notes export v0.2 > RELEASE.md
65
+ metrics [--milestone <ID>] 開発の指標(要望の作成から対応済・完了済までの時間、受け入れ基準の未達・未検証・証拠なし・再確認、
66
+ 手戻り、AI レビューの未達判定・意図しない変更の候補)。
67
+ 値・単位・対象・欠損・算出の方法を出す(読むだけ。記録の欠けは 0 にせず欠損と出す。成績の評価には使わない)
68
+ metrics record <指標> <値> 人が記録する値: cost(--unit JPY など通貨ごと)/ post_release_defects(0 以上の整数)
69
+ --from YYYY-MM-DD --to YYYY-MM-DD --source 出典 [--milestone ID(省くと全体)] [--note メモ]
70
+ 同じ指標・範囲・期間・単位の再送は何もしない。値を変える訂正は --rev 版(無い・違えば競合で終了コード 3)
71
+ metrics records / rm <M1> 人の記録の全部 / 消す(--rev 版)
59
72
  whoami 操作するプロジェクト・変更者・今の要望
60
73
  serve [--port] [--host] ブラウザ用のビューアを起動(既定は個人設定の serve.port / serve.host か $P3_PORT / $P3_HOST)
61
74
  --all-projects 個人設定に登録したプロジェクトを跨いで扱う(画面で選ぶ。--project / --dir とは一緒に使えない)
@@ -86,6 +99,7 @@ export const HELP = `p3(infodb p3)— 要望ごとにフォルダを分け
86
99
  タスク(今の要望の中。--req <要望> で指定、要望の作業ツリーの中なら省略可)
87
100
  ls 一覧 --status s1,s2 --area パス -q 語句 --repo <参照先>|none(作業先) --all(全要望)
88
101
  --blocked 止まっているタスクだけ(ほかの条件と AND。--archived とは一緒に使えない)
102
+ --review 見直しが必要(候補)の完了したタスクだけ(ほかの条件と AND)
89
103
  show <T003|要望|語句> 詳細と関係(依存・置き換え)
90
104
  --brief 作業に要る項目だけ(本文・状態・依存とその状態・置き換えの注意・成果物・rev)
91
105
  new <タイトル> --body 本文|- --area a --label l --status --output 成果物(繰り返し可)
@@ -93,13 +107,15 @@ export const HELP = `p3(infodb p3)— 要望ごとにフォルダを分け
93
107
  --criterion 文 受け入れ基準(繰り返し可。ID は A1, A2, ... を振る)
94
108
  set <T003> キー=値 ... title status labels areas outputs repo(空で消す。outputs= はカンマ区切りで置き換える。repo=none は作業先なし)
95
109
  --repo-output <参照先>=<成果物> リポジトリごとの成果物を足す(repoOutputs= で全部外す)
96
- --criterion 文 受け入れ基準を足す / --evidence・--evidence-file 証拠を残す(move と同じ)
110
+ --criterion 文 受け入れ基準を足す / --evidence・--evidence-file・--evidence-json 証拠を残す(move と同じ)
97
111
  move <T003> <ステータス> --output URL・文章・パス(成果物を足す。繰り返し可。カンマで分けない)
98
112
  --repo-output <参照先>=<URL> リポジトリごとの成果物(最後のタスクに全リポジトリの PR を残す)
99
113
  --record 本文|- 変更の記録(何を変えたか・なぜ・入れた決まり・やめたもの。AI が完了にするときは必須。set でも直せる)
100
114
  --evidence <ID>=met|unmet|unverified[:本文] 受け入れ基準ごとの証拠(繰り返し可。met は本文が要る)
101
115
  --evidence-file 証拠.md|- 見出し「## A1 met」ごとの証拠をまとめて(- は --record - と一緒に使えない)
102
- 不足(証拠なし・未達・未検証・基準を変えた後)があっても完了は拒まず、stderr に出す
116
+ --evidence-json 証拠.json|- 根拠つきでまとめて [{"id":"A1","result":"met","evidence":"…","basis":{"kind":"machine",…}}]
117
+ (--evidence と --evidence-file は根拠を書けない: 前の同じ結果の根拠を引き継ぎ、無ければ申告のみ・unverified は未確認)
118
+ 不足(証拠なし・未達・未検証・基準を変えた後・申告のみの met)があっても完了は拒まず、stderr に出す
103
119
  check <T003> [--off] 完了したタスクを人が確認して「済み」にする(--off で外す)
104
120
  block <T003> --reason 理由|- [--decision 決めてほしいこと|-]
105
121
  作業中のタスクに止まっている理由を付ける・内容を直す(状態は作業中のまま。止まった時刻は直しても変えない)
@@ -111,7 +127,10 @@ export const HELP = `p3(infodb p3)— 要望ごとにフォルダを分け
111
127
  add <文>... 足す / edit <ID> <文> 文を変える(記録済みの証拠は再確認が必要になる)
112
128
  rm <ID>... 消す(証拠は残る。ID は使い直さない) / order <ID>... 並べ替える(今の ID を全部)
113
129
  evidence <T003> <ID> <結果> 証拠を残す(再記録は置き換え)。本文は続けて書くか --body 本文|- / --file 本文.md
114
- evidence <T003> --file 証拠.md|- まとめて / evidence <T003> rm <ID>... 消す
130
+ --basis unverified|declaration|read|machine 根拠の種類(作業した側の申告。P3 は検査を実行しない)
131
+ read: --reference 読んだもの / machine: --command コマンド --check-result 結果 --target <参照先>:<コミット>
132
+ evidence <T003> --file 証拠.md|- まとめて / --evidence-json 証拠.json|- 根拠つきでまとめて
133
+ evidence <T003> rm <ID>... 消す
115
134
  済みのタスクの基準・証拠の中身を変えると済みが外れる(同じ値の再保存・成果物の追加では外れない)
116
135
  review <T003> 完了したタスクの AI レビュー(別の Codex のスレッドが、固定した差分と前後のコードを読むだけで基準と比べる。
117
136
  終わるまで待つ。Ctrl-C で取り消す。結果はタスクの状態・済み・基準・証拠を変えない)
@@ -124,7 +143,22 @@ export const HELP = `p3(infodb p3)— 要望ごとにフォルダを分け
124
143
  ls --archived アーカイブしたタスクの一覧(今の要望。読むだけ。壊れたファイルは「読めない」に出す)
125
144
  show <T003> --archived アーカイブしたタスクの詳細(本文・変更の記録・成果物)。通常の ls / show / 進捗には出ない
126
145
  find <語句> 参照・タイトルで探す
146
+ source [<要望>] 要求の出典と確認(任意): 根拠の記録と状態(未記録・未確認・確認記録あり・再確認が必要・対応先不明)・回答
147
+ add --target 対象の要求・前提 --source 出典(役割・資料名・版・節)--grounds 根拠|-(承認された計算例など)
148
+ edit <S1> [同じ項目] / confirm <S1> --by 確かめた役割・アクター --on YYYY-MM-DD / rm <S1>
149
+ (確認には出典・根拠・人・日が要る。題・本文・記録を変えると再確認が必要。記録は申告で P3 の保証ではない)
150
+ source <T003|D1> [<A1> 操作] 受け入れ基準ごとの記録(D1 はタスク案。--run PF-...)。add --from S1 で要望の記録を写す(確認は引き継がない)
151
+ --sources-json 操作.json|- まとめて([{"criterion":"A1","op":"add","source":"…","basis":"…"}])
127
152
 
153
+ retro [<要望>] 振り返り: 対象(確定した採用済みの Preflight とリスクの原文)と候補(採用を終えた run と作ったタスク・子の根拠)
154
+ confirm <run> [--reason 訂正の理由] 対象を確定する(最新の実行・採用では変わらない。訂正は理由が要る。--rev で版)
155
+ judge <番号> --state occurred|not_occurred|unchecked リスクの確認(人の判断)。起きた → --facts 事実、
156
+ 起きなかった → --scope 確認した範囲、どちらも根拠が要る。判断を変える・戻すには --reason
157
+ --evidence review:T001:<run>:<項目>[:<位置>] | milestone:<ID>:<run>:<項目>[:<位置>][:<理由>] | rework:T001:R1 | manual:<参照>
158
+ revisit [<要望>] [--all] 見直しが必要(候補): 完了の記録(完了・済みにしたときの条件)と今の条件の差(品質基準・受け入れ基準・
159
+ 要求の根拠・前提の変更)。完了済みも含む。候補を出すだけで状態・済みは変えない。確かめたら済みにし直す
160
+ premise [<要望>] 前提の変更の一覧 / add --target <要望 ID|T001|S1>(繰り返し可)--reason 理由 --condition 新しい条件・版
161
+ ack <P1> --target <ID> --condition 確かめた条件 変更を確かめたことを残す(過去の記録・状態は変えない)
128
162
  Preflight
129
163
  preflight [<要望>] 評価・細分化を実行し、完了まで待つ --engine codex|mock
130
164
  前回の結果とまだ渡していないメモを引き継ぐ
@@ -136,6 +170,10 @@ Preflight
136
170
  Codex / Mock の run は、動いているプロセスに中断を頼み、止まるまで少し待つ。止まらなければ requested)
137
171
  --acknowledge-stopped 動いているか確かめられない run(以前の版・別の環境)を、止まっていることを確かめて中断にする
138
172
  (記録だけ。プロセスやコンテナは止めない)
173
+ clarify [<要望>] 確認事項(ID・確認先・質問・必要な根拠・判断への影響)と回答の状態 --run PF-...
174
+ answer [<要望>] <Q1> 確認事項に回答する(要望に残す。過去の run は書き換えない。再評価は preflight で明示して始める)
175
+ --body 回答|- --by 回答した役割 --on YYYY-MM-DD --source 出典 --grounds 根拠|- --link S1(対応する根拠の記録)
176
+ --answer-json 回答.json|- まとめて / answer [<要望>] <Q1> rm 消す
139
177
  notes [<要望>] メモの一覧(次の Preflight に渡すもの・渡し済み)
140
178
  attach [ls] 要望の添付(PNG / JPEG / xlsx)の一覧。要望は --req(要望の作業ツリーの中なら省略可)
141
179
  attach add <ファイル> 添付を足す --description 説明 --source 出典。次の Preflight を始めるときに run に固定して渡す