@infodb/p3 0.11.0 → 0.13.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (138) hide show
  1. package/README.md +33 -33
  2. package/dist/web/assets/CompletionReview-gZKZrDu_.js +1 -0
  3. package/dist/web/assets/ImprovementDialog-Dno6dPnG.js +1 -0
  4. package/dist/web/assets/Outputs-BgHalMGb.js +1 -0
  5. package/dist/web/assets/RequestStatus-hZcBUUIu.js +1 -0
  6. package/dist/web/assets/Tabs-C3NmwCc3.js +1 -0
  7. package/dist/web/assets/TagInput-B2b862qn.js +1 -0
  8. package/dist/web/assets/TaskDrawer-4BQBELXa.js +6 -0
  9. package/dist/web/assets/_requestId-BMAG1t3o.js +1 -0
  10. package/dist/web/assets/_requestId-tbg2pA2S.js +1 -0
  11. package/dist/web/assets/archive-DMl6WyOe.js +1 -0
  12. package/dist/web/assets/board-BMTcHKyt.js +1 -0
  13. package/dist/web/assets/done-CL6Nlsua.js +1 -0
  14. package/dist/web/assets/draft-BvGxfD7v.js +2 -0
  15. package/dist/web/assets/index-Dp7Fc4VI.css +2 -0
  16. package/dist/web/assets/index-KdlgMitg.js +12 -0
  17. package/dist/web/assets/metrics-Cu7gJ7Rk.js +1 -0
  18. package/dist/web/assets/new-DTXWHuFO.js +1 -0
  19. package/dist/web/assets/outputs-CXqnjSqV.js +1 -0
  20. package/dist/web/assets/preflightInput-ClKwkp8R.js +2 -0
  21. package/dist/web/assets/preload-helper-oLCrNCwz.js +1 -0
  22. package/dist/web/assets/quality-RFd-7k3r.js +1 -0
  23. package/dist/web/assets/release-notes-Bpdi6RdY.js +5 -0
  24. package/dist/web/assets/requestData-CbFxwW5w.js +1 -0
  25. package/dist/web/assets/routes-BIt8bExF.js +6 -0
  26. package/dist/web/assets/settings-CsCqF_1B.js +1 -0
  27. package/dist/web/assets/taskReview-_WCgnQit.js +1 -0
  28. package/dist/web/assets/ui-BGK72r3u.js +1 -0
  29. package/dist/web/assets/workTarget-CySfKyfB.js +30 -0
  30. package/dist/web/index.html +4 -4
  31. package/docs/architecture.md +610 -33
  32. package/docs/development.md +61 -17
  33. package/docs/how-to-use.md +554 -17
  34. package/docs/installation.md +235 -144
  35. package/docs/publishing.md +1 -1
  36. package/lib/cli/agentsStatus.js +197 -0
  37. package/lib/cli/args.js +111 -2
  38. package/lib/cli/guide.js +27 -0
  39. package/lib/cli/guide.md +214 -0
  40. package/lib/cli/help.js +74 -1
  41. package/lib/cli/main.js +97 -17
  42. package/lib/cli/metricsCommands.js +77 -0
  43. package/lib/cli/output.js +19 -1
  44. package/lib/cli/preflightCommands.js +7 -1
  45. package/lib/cli/project.js +13 -24
  46. package/lib/cli/qualityCommands.js +188 -0
  47. package/lib/cli/readOnly.js +17 -0
  48. package/lib/cli/requestCommands.js +33 -4
  49. package/lib/cli/requirementCommands.js +288 -0
  50. package/lib/cli/retroCommands.js +106 -0
  51. package/lib/cli/revisitCommands.js +73 -0
  52. package/lib/cli/showView.js +183 -4
  53. package/lib/cli/taskCommands.js +341 -20
  54. package/lib/cli/taskReviewCommands.js +178 -0
  55. package/lib/cli/userConfig.js +47 -0
  56. package/lib/core/completionRefs.js +46 -0
  57. package/lib/core/context.js +4 -1
  58. package/lib/core/metrics/definitions.js +434 -0
  59. package/lib/core/metrics/index.js +88 -0
  60. package/lib/core/metrics/manual.js +180 -0
  61. package/lib/core/milestoneReview/material.js +11 -1
  62. package/lib/core/milestoneReview/mockReviewer.js +1 -0
  63. package/lib/core/milestoneReview/review.js +70 -6
  64. package/lib/core/milestoneReview/service.js +29 -93
  65. package/lib/core/milestoneReview/store.js +12 -62
  66. package/lib/core/ops.js +23 -3
  67. package/lib/core/preflight/carryover.js +6 -2
  68. package/lib/core/preflight/codexEngine.js +34 -17
  69. package/lib/core/preflight/diagnose.js +4 -9
  70. package/lib/core/preflight/engine.js +15 -0
  71. package/lib/core/preflight/hostPaths.js +260 -0
  72. package/lib/core/preflight/input.js +33 -5
  73. package/lib/core/preflight/instructions.js +36 -2
  74. package/lib/core/preflight/mockEngine.js +24 -2
  75. package/lib/core/preflight/render.js +22 -3
  76. package/lib/core/preflight/service.js +99 -8
  77. package/lib/core/preflight/uiRender.js +3 -0
  78. package/lib/core/projectRegistry.js +3 -3
  79. package/lib/core/quality.js +21 -0
  80. package/lib/core/qualityImprovement.js +221 -0
  81. package/lib/core/requestOps.js +294 -11
  82. package/lib/core/retrospective.js +208 -0
  83. package/lib/core/reviewCandidates.js +56 -0
  84. package/lib/core/reviewRuns.js +205 -0
  85. package/lib/core/store/archivedTasks.js +74 -0
  86. package/lib/core/store/collection.js +32 -3
  87. package/lib/core/store/normalize.js +35 -2
  88. package/lib/core/store/preflightStore.js +23 -1
  89. package/lib/core/store/projectFile.js +10 -0
  90. package/lib/core/store/workspace.js +49 -3
  91. package/lib/core/taskReview/material.js +459 -0
  92. package/lib/core/taskReview/mockReviewer.js +30 -0
  93. package/lib/core/taskReview/paths.js +15 -0
  94. package/lib/core/taskReview/review.js +312 -0
  95. package/lib/core/taskReview/service.js +187 -0
  96. package/lib/core/taskReview/store.js +214 -0
  97. package/lib/server/api/manifest.js +104 -5
  98. package/lib/server/api/milestoneReviewRoutes.js +4 -3
  99. package/lib/server/api/routes.js +265 -17
  100. package/lib/server/api/taskReviewRoutes.js +66 -0
  101. package/lib/server/server.js +2 -2
  102. package/lib/shared/acceptance.js +618 -0
  103. package/lib/shared/completionRecord.js +327 -0
  104. package/lib/shared/metrics.js +42 -0
  105. package/lib/shared/milestoneReview.js +2 -1
  106. package/lib/shared/preflightInput.js +1 -1
  107. package/lib/shared/quality.js +391 -0
  108. package/lib/shared/qualityImprovement.js +1 -0
  109. package/lib/shared/qualityTemplates.js +31 -0
  110. package/lib/shared/requirementSource.js +635 -0
  111. package/lib/shared/retrospective.js +286 -0
  112. package/lib/shared/reviewCandidate.js +308 -0
  113. package/lib/shared/reworkHistory.js +81 -0
  114. package/lib/shared/taskBlock.js +142 -0
  115. package/lib/shared/taskReview.js +56 -0
  116. package/package.json +3 -2
  117. package/skills/p3/SKILL.md +9 -152
  118. package/dist/web/assets/Outputs-ddwte0jj.js +0 -1
  119. package/dist/web/assets/RequestStatus-Bg1OLbRc.js +0 -1
  120. package/dist/web/assets/Tabs-DTmggzgg.js +0 -1
  121. package/dist/web/assets/TagInput-BHAgjLP7.js +0 -1
  122. package/dist/web/assets/TaskDrawer-Dz_5c2NH.js +0 -3
  123. package/dist/web/assets/_requestId-D9-gtIcG.js +0 -1
  124. package/dist/web/assets/_requestId-DzCNYvqf.js +0 -30
  125. package/dist/web/assets/appCtx-Cm24VpAf.js +0 -1
  126. package/dist/web/assets/board-MCHcZ-PU.js +0 -1
  127. package/dist/web/assets/done-zq10Bt08.js +0 -1
  128. package/dist/web/assets/draft-CfJeyLOl.js +0 -1
  129. package/dist/web/assets/index-Ce0ndpne.js +0 -12
  130. package/dist/web/assets/index-D68mkSnw.css +0 -2
  131. package/dist/web/assets/new-9TKiNT4O.js +0 -1
  132. package/dist/web/assets/preflightInput-BAeEJYUK.js +0 -2
  133. package/dist/web/assets/preload-helper-FBLw7u7x.js +0 -1
  134. package/dist/web/assets/release-notes-hK5XezLW.js +0 -5
  135. package/dist/web/assets/requestData-BnN7mctX.js +0 -1
  136. package/dist/web/assets/routes-usHwrrA0.js +0 -3
  137. package/dist/web/assets/settings-BVZDnL6O.js +0 -1
  138. package/dist/web/assets/workTarget-Cijqq4yH.js +0 -1
@@ -0,0 +1,197 @@
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, repoRoot, SKILL_SOURCE } from "./project.js";
7
+ const DOCS = ["AGENTS.md", "CLAUDE.md"];
8
+ const SKILL_VERSION_KEY = "p3-entry-version";
9
+ const SECTION_VERSION = /<!--\s*p3-entry-version:\s*(\S*?)\s*-->/;
10
+ const lf = (s) => s.replace(/\r\n?/g, "\n");
11
+ /** 入口の版(正の整数)。読めなければ undefined */
12
+ function parseVersion(v) {
13
+ const s = typeof v === "number" ? String(v) : typeof v === "string" ? v.trim() : "";
14
+ return /^[1-9]\d*$/.test(s) ? Number(s) : undefined;
15
+ }
16
+ /** 今いる git の作業ツリーのルート(git 管理外は今いる場所) */
17
+ function worktreeRoot(cwd) {
18
+ try {
19
+ return execFileSync("git", ["rev-parse", "--show-toplevel"], { cwd, encoding: "utf8", stdio: ["ignore", "pipe", "ignore"] }).trim() || cwd;
20
+ }
21
+ catch {
22
+ return cwd;
23
+ }
24
+ }
25
+ function read(file) {
26
+ try {
27
+ if (statSync(file).isDirectory())
28
+ return { ok: false, missing: false, error: "フォルダになっています" };
29
+ return { ok: true, text: lf(readFileSync(file, "utf8")) };
30
+ }
31
+ catch (e) {
32
+ const code = e.code;
33
+ if (code === "ENOENT" || code === "ENOTDIR")
34
+ return { ok: false, missing: true };
35
+ return { ok: false, missing: false, error: `${code ?? "読めません"}: ${e.message}` };
36
+ }
37
+ }
38
+ function versionStatus(version, same, what) {
39
+ if (version < ENTRY_VERSION)
40
+ return { status: "outdated", reason: `${what}の入口の版 ${version} が、この CLI の版 ${ENTRY_VERSION} より古い` };
41
+ if (version > ENTRY_VERSION)
42
+ return { status: "newer", reason: `${what}の入口の版 ${version} が、この CLI の版 ${ENTRY_VERSION} より新しい(この CLI が古い可能性)` };
43
+ return same ? { status: "current", reason: "同梱の入口と同じ" } : { status: "modified", reason: `入口の版は同じだが、同梱の入口と中身が違う(手で直した可能性)` };
44
+ }
45
+ function diagnoseSkill(root, k, referenced, bundled) {
46
+ const path = AGENT_TARGETS[k].path;
47
+ const base = { path, kind: "skill", target: k };
48
+ const r = read(join(root, path));
49
+ if (!r.ok) {
50
+ if (!r.missing)
51
+ return { ...base, version: null, status: "unreadable", reason: r.error };
52
+ // 節が指していない先は、選ばなかった先として扱う(無くてよい)
53
+ return referenced ? { ...base, version: null, status: "missing", reason: "p3 の節が指しているのに、スキルがありません" } : undefined;
54
+ }
55
+ const fm = /^---\n([\s\S]*?)\n---(?:\n|$)/.exec(r.text);
56
+ let meta;
57
+ try {
58
+ const parsed = fm ? YAML.parse(fm[1]) : undefined;
59
+ meta = parsed && typeof parsed === "object" ? parsed : undefined;
60
+ }
61
+ catch {
62
+ return { ...base, version: null, status: "unknown", reason: "スキルの frontmatter を読めません" };
63
+ }
64
+ const metadata = meta?.metadata && typeof meta.metadata === "object" ? meta.metadata : undefined;
65
+ if (metadata && SKILL_VERSION_KEY in metadata) {
66
+ const v = parseVersion(metadata[SKILL_VERSION_KEY]);
67
+ if (v === undefined)
68
+ return { ...base, version: null, status: "unknown", reason: `入口の版(metadata.${SKILL_VERSION_KEY})が正の整数ではありません` };
69
+ return { ...base, version: v, ...versionStatus(v, r.text === bundled, "スキル") };
70
+ }
71
+ if (meta?.name === "p3")
72
+ return { ...base, version: null, status: "outdated", reason: "入口の版の無い、前の p3 のスキル(手順の全文の写し)" };
73
+ return { ...base, version: null, status: "unknown", reason: "p3 のスキルの形ではありません(name: p3 も入口の版もありません)" };
74
+ }
75
+ /** 節が同梱の入口のどれか(参照するスキルの組み合わせ・見出しの段の違いは許す)と同じか */
76
+ function sameSection(body, level) {
77
+ const subsets = [["claude"], ["codex"], ["claude", "codex"]];
78
+ return subsets.some((kinds) => lf(agentsSnippet(kinds)).replace(/^\n/, "").replace(/^## /, `${"#".repeat(level)} `).trim() === body.trim());
79
+ }
80
+ function diagnoseSections(root, primaryDoc) {
81
+ const entries = [];
82
+ const referenced = new Set();
83
+ for (const doc of DOCS) {
84
+ const r = read(join(root, doc));
85
+ const primary = doc === primaryDoc;
86
+ if (!r.ok) {
87
+ if (!r.missing)
88
+ entries.push({ path: doc, kind: "section", primary, version: null, status: "unreadable", reason: r.error });
89
+ continue;
90
+ }
91
+ const sections = findSections(r.text);
92
+ if (!sections.length) {
93
+ if (r.text.includes(AGENTS_MARK))
94
+ entries.push({ path: doc, kind: "section", primary, version: null, status: "unknown", reason: `「${AGENTS_MARK}」が見出しとして見つかりません` });
95
+ continue;
96
+ }
97
+ if (sections.length > 1) {
98
+ entries.push({ path: doc, kind: "section", primary, version: null, status: "unknown", reason: `「${AGENTS_MARK}」の節が ${sections.length} つあります(どれが p3 の節か決められません)` });
99
+ continue;
100
+ }
101
+ const { start, end, level } = sections[0];
102
+ const body = r.text.split("\n").slice(start, end).join("\n");
103
+ for (const k of KINDS)
104
+ if (body.includes(AGENT_TARGETS[k].path))
105
+ referenced.add(k);
106
+ const m = SECTION_VERSION.exec(body);
107
+ if (!m) {
108
+ entries.push({ path: doc, kind: "section", primary, version: null, status: "outdated", reason: "入口の版の無い、前の p3 の節(手順の要約の写し)" });
109
+ continue;
110
+ }
111
+ const v = parseVersion(m[1]);
112
+ if (v === undefined) {
113
+ entries.push({ path: doc, kind: "section", primary, version: null, status: "unknown", reason: "節の入口の版(p3-entry-version)が正の整数ではありません" });
114
+ continue;
115
+ }
116
+ entries.push({ path: doc, kind: "section", primary, version: v, ...versionStatus(v, sameSection(body, level), "節") });
117
+ }
118
+ return { entries, referenced };
119
+ }
120
+ /** p3 agents に渡す先(置いてある・指しているスキルから。分からなければ選ばせる) */
121
+ function choiceOf(kinds) {
122
+ if (kinds.has("claude") && kinds.has("codex"))
123
+ return "both";
124
+ if (kinds.has("claude"))
125
+ return "claude";
126
+ if (kinds.has("codex"))
127
+ return "codex";
128
+ return "claude|codex|both";
129
+ }
130
+ const CMD = "pnpx @infodb/p3 agents";
131
+ export function diagnoseAgents(cwd) {
132
+ const root = worktreeRoot(cwd);
133
+ const main = repoRoot(cwd);
134
+ const base = { root, ...(main !== root ? { writeRoot: main } : {}), expectedVersion: ENTRY_VERSION };
135
+ try {
136
+ const bundled = lf(readFileSync(SKILL_SOURCE, "utf8"));
137
+ const primaryDoc = DOCS.find((d) => read(join(root, d)).ok) ?? "AGENTS.md";
138
+ const sections = diagnoseSections(root, primaryDoc);
139
+ const skills = KINDS.map((k) => diagnoseSkill(root, k, sections.referenced.has(k), bundled)).filter((e) => !!e);
140
+ const placed = skills.length + sections.entries.length > 0;
141
+ const entries = [...skills, ...sections.entries];
142
+ // スキルはあるのに節がどこにも無い
143
+ if (skills.length && !sections.entries.length) {
144
+ entries.push({ path: primaryDoc, kind: "section", primary: true, version: null, status: "missing", reason: `スキルはあるのに、${primaryDoc} に「${AGENTS_MARK}」の節がありません` });
145
+ }
146
+ const kinds = new Set([...sections.referenced, ...skills.map((s) => s.target)]);
147
+ const choice = choiceOf(kinds);
148
+ const advice = [];
149
+ const has = (s) => entries.some((e) => e.status === s);
150
+ if (!placed)
151
+ advice.push(`AI 向けの入口が置かれていません。置くなら、人が先を選んで ${CMD} claude|codex|both を実行する`);
152
+ if (has("outdated"))
153
+ advice.push(`古い入口があります。人が差分(git diff)を確かめ、p3 の節の中に足したプロジェクト固有の決まりがあれば節の外へ移してから ${CMD} ${choice} --force で更新する`);
154
+ if (has("missing")) {
155
+ const missingSkills = entries.filter((e) => e.status === "missing" && e.kind === "skill").map((e) => e.target);
156
+ advice.push(`足りない入口があります。人が ${CMD} ${missingSkills.length ? choiceOf(new Set(missingSkills)) : choice} で置く(既にある入口は変えません)`);
157
+ }
158
+ if (has("modified"))
159
+ advice.push("入口の版は同じなのに中身が同梱の入口と違うものがあります。手で直した内容を確かめてください(--force は直した内容を消すので、すぐには勧めません)");
160
+ if (has("newer"))
161
+ advice.push("この CLI より新しい入口があります。古い p3 で動いていないか(pnpx @infodb/p3 で呼んでいるか、guide の cliVersion)を確かめてください。--force で古い入口に戻さない");
162
+ if (has("unknown"))
163
+ advice.push("形の分からない入口があります。節が複数なら手で1つの節(見出し「## タスク管理(infodb p3)」)に整理し、版の書き方を確かめてください");
164
+ if (has("unreadable"))
165
+ advice.push("読めない入口があります。ファイルの権限・種類を確かめてください");
166
+ if (base.writeRoot && entries.some((e) => e.status !== "current")) {
167
+ advice.push(`p3 agents が書くのはメインの作業ツリー(${base.writeRoot})です。そこで更新・レビュー・コミットしてから、このブランチに取り込んでください`);
168
+ }
169
+ return { ...base, placed, ok: placed && entries.every((e) => e.status === "current"), entries, advice };
170
+ }
171
+ catch (e) {
172
+ return { ...base, placed: false, ok: false, entries: [], advice: [], problem: `入口を調べられませんでした: ${e.message}` };
173
+ }
174
+ }
175
+ const STATUS_LABEL = {
176
+ current: "最新",
177
+ outdated: "古い",
178
+ missing: "無い",
179
+ modified: "変更あり",
180
+ newer: "CLI より新しい",
181
+ unknown: "形が不明",
182
+ unreadable: "読めない",
183
+ };
184
+ /** 人向けの表示(whoami と guide の通知) */
185
+ export function agentsText(d) {
186
+ if (d.problem)
187
+ return [d.problem];
188
+ if (!d.placed)
189
+ return ["置かれていません", ...d.advice.map((a) => ` → ${a}`)];
190
+ if (d.ok)
191
+ return [`最新(${d.entries.map((e) => e.path).join("・")})`];
192
+ return [
193
+ `対応が必要(入口の版 ${d.expectedVersion})`,
194
+ ...d.entries.filter((e) => e.status !== "current").map((e) => ` ${STATUS_LABEL[e.status]} ${e.path} ${e.reason}`),
195
+ ...d.advice.map((a) => ` → ${a}`),
196
+ ];
197
+ }
package/lib/cli/args.js CHANGED
@@ -3,6 +3,7 @@ import { readFile } from "node:fs/promises";
3
3
  import { basename, resolve as resolvePath } from "node:path";
4
4
  import { parseArgs } from "node:util";
5
5
  import { ATTACHMENT_LIMITS, AttachmentError, inspectAttachment } from "../core/store/attachments.js";
6
+ import { cleanBasis, EVIDENCE_BASIS_KINDS, isEvidenceBasisKind, parseEvidenceArg, parseEvidenceFile, parseEvidenceJson } from "../shared/acceptance.js";
6
7
  import { TASK_STATUSES, isTaskStatus } from "../shared/types.js";
7
8
  import {} from "../core/context.js";
8
9
  import { repoArg } from "../core/workTargets.js";
@@ -37,13 +38,41 @@ const OPTIONS = {
37
38
  off: { type: "boolean" },
38
39
  body: { type: "string" },
39
40
  record: { type: "string" },
41
+ criterion: { type: "string", multiple: true },
42
+ evidence: { type: "string", multiple: true },
43
+ "evidence-file": { type: "string" },
44
+ "evidence-json": { type: "string" },
45
+ basis: { type: "string" },
46
+ "check-result": { type: "string" },
47
+ target: { type: "string", multiple: true },
48
+ reason: { type: "string" },
49
+ text: { type: "string" },
50
+ command: { type: "string" },
51
+ success: { type: "string" },
52
+ reference: { type: "string" },
53
+ quality: { type: "string" },
54
+ key: { type: "string", multiple: true },
55
+ hash: { type: "string" },
56
+ register: { type: "boolean" },
57
+ reopen: { type: "boolean" },
58
+ decision: { type: "string" },
59
+ resolution: { type: "string" },
60
+ blocked: { type: "boolean" },
61
+ review: { type: "boolean" },
62
+ condition: { type: "string" },
63
+ state: { type: "string" },
64
+ facts: { type: "string" },
65
+ scope: { type: "string" },
66
+ viewpoint: { type: "string" },
67
+ preview: { type: "boolean" },
40
68
  note: { type: "string" },
41
69
  engine: { type: "string" },
42
70
  run: { type: "string" },
43
71
  only: { type: "string" },
44
72
  skip: { type: "string" },
45
73
  name: { type: "string" },
46
- repo: { type: "string" },
74
+ // 繰り返せるのは MULTI_REPO_COMMANDS だけ(ほかは checkRepeatedRepo が断る。後勝ちで黙って成功させない)
75
+ repo: { type: "string", multiple: true },
47
76
  description: { type: "string" },
48
77
  instructions: { type: "string" },
49
78
  "preflight-runner": { type: "string" },
@@ -56,6 +85,7 @@ const OPTIONS = {
56
85
  complete: { type: "boolean" },
57
86
  cancel: { type: "boolean" },
58
87
  "archive-superseded": { type: "boolean" },
88
+ archived: { type: "boolean" },
59
89
  paste: { type: "boolean" },
60
90
  "no-browser": { type: "boolean" },
61
91
  forget: { type: "boolean" },
@@ -70,8 +100,34 @@ const OPTIONS = {
70
100
  version: { type: "string" },
71
101
  file: { type: "string" },
72
102
  "based-on": { type: "string" },
103
+ // 要求の根拠と確認事項への回答(p3 source / clarify / answer)
104
+ by: { type: "string" },
105
+ on: { type: "string" },
106
+ from: { type: "string" },
107
+ to: { type: "string" },
108
+ unit: { type: "string" },
109
+ grounds: { type: "string" },
110
+ link: { type: "string", multiple: true },
111
+ "sources-json": { type: "string" },
112
+ "answer-json": { type: "string" },
73
113
  };
74
- export const parse = (argv) => parseArgs({ args: joinValues(argv), options: OPTIONS, allowPositionals: true });
114
+ /**
115
+ * 引数を読む。--repo は全部を repos に、1つだけのときは repo にも入れる(繰り返したときの repo は undefined。
116
+ * 繰り返してよいかは checkRepeatedRepo で確かめる)
117
+ */
118
+ export function parse(argv) {
119
+ const { values, positionals } = parseArgs({ args: joinValues(argv), options: OPTIONS, allowPositionals: true });
120
+ const { repo: repos, ...rest } = values;
121
+ return { positionals, values: { ...rest, repos, repo: repos?.length === 1 ? repos[0] : undefined } };
122
+ }
123
+ /** --repo を繰り返して複数の参照先を渡せるコマンド(品質基準の対象。ほかは作業先などの1つだけを取る) */
124
+ const MULTI_REPO_COMMANDS = new Set(["quality"]);
125
+ /** --repo を繰り返せないコマンドで繰り返したら断る(最後の1つだけで黙って成功させない) */
126
+ export function checkRepeatedRepo(cmd, o) {
127
+ if ((o.repos?.length ?? 0) > 1 && !MULTI_REPO_COMMANDS.has(cmd)) {
128
+ throw new UsageError(`p3 ${cmd} の --repo は1つだけ指定できます(指定: ${o.repos.join(", ")})。--repo を繰り返して複数の参照先を指定できるのは p3 quality add / set だけです`);
129
+ }
130
+ }
75
131
  /** `--body "- 箇条書き"` のように値が - で始まっても受け取れるよう、`--body=...` の形にまとめる */
76
132
  function joinValues(argv) {
77
133
  const out = [];
@@ -148,6 +204,59 @@ export function date(v) {
148
204
  throw new UsageError(`日付は YYYY-MM-DD: ${v}`);
149
205
  return v;
150
206
  }
207
+ /**
208
+ * set / move / evidence の証拠の入力を操作にする:
209
+ * --evidence <ID>=<結果>[:本文] を繰り返す(根拠は省いた扱い)/ --evidence-file <Markdown>|-(同じ)/ --evidence-json <JSON>|-(根拠つき)
210
+ * --evidence-file と --evidence-json は一緒に使えない。- は標準入力で、--record - / --body - とは取り合うので一緒に使えない
211
+ */
212
+ export function evidenceOps(o) {
213
+ const ops = (o.evidence ?? []).map(parseEvidenceArg);
214
+ const md = o["evidence-file"];
215
+ const json = o["evidence-json"];
216
+ if (md !== undefined && json !== undefined)
217
+ throw new UsageError("--evidence-file(Markdown)と --evidence-json(JSON)はどちらか一方です");
218
+ const file = md ?? json;
219
+ if (file !== undefined) {
220
+ const flag = md !== undefined ? "--evidence-file" : "--evidence-json";
221
+ if (file === "-" && (o.record === "-" || o.body === "-"))
222
+ throw new UsageError(`標準入力(-)は ${flag} と --record / --body のどちらか一方だけに使えます(もう一方はファイルか文字で渡してください)`);
223
+ let src;
224
+ try {
225
+ src = file === "-" ? readFileSync(0, "utf8") : readFileSync(resolvePath(process.cwd(), file), "utf8");
226
+ }
227
+ catch {
228
+ throw new UsageError(`証拠のファイルが読めません: ${file}`);
229
+ }
230
+ ops.push(...(md !== undefined ? parseEvidenceFile(src) : parseEvidenceJson(src)));
231
+ }
232
+ const dup = ops.map((x) => (x.op === "record" ? x.id : "")).find((id, i, a) => id && a.indexOf(id) !== i);
233
+ if (dup)
234
+ throw new UsageError(`${dup} の証拠が2回指定されています`);
235
+ return ops;
236
+ }
237
+ /**
238
+ * evidence <タスク> <ID> <結果> の根拠(--basis 種類 と、read は --reference、machine は --command・--check-result・--target)。
239
+ * 省けば undefined(根拠を省いた扱い)。種類に合わない項目・種類なしの項目は断る(黙って捨てない)
240
+ */
241
+ export function basisFromOptions(o) {
242
+ const given = { reference: o.reference, command: o.command, result: o["check-result"], target: o.target?.length ? o.target : undefined };
243
+ const names = { reference: "--reference", command: "--command", result: "--check-result", target: "--target" };
244
+ const present = Object.keys(given).filter((k) => given[k] !== undefined);
245
+ if (o.basis === undefined) {
246
+ if (present.length)
247
+ throw new UsageError(`${present.map((k) => names[k]).join("・")} を使うときは --basis(${EVIDENCE_BASIS_KINDS.join("|")})も指定してください`);
248
+ return undefined;
249
+ }
250
+ if (!isEvidenceBasisKind(o.basis))
251
+ throw new UsageError(`--basis は ${EVIDENCE_BASIS_KINDS.join(" / ")} のどれかです: ${o.basis}`);
252
+ const allowed = { unverified: [], declaration: [], read: ["reference"], machine: ["command", "result", "target"] };
253
+ const extra = present.filter((k) => !allowed[o.basis].includes(k));
254
+ if (extra.length)
255
+ throw new UsageError(`--basis ${o.basis} には ${extra.map((k) => names[k]).join("・")} を使いません`);
256
+ if ((given.target?.length ?? 0) > 1)
257
+ throw new UsageError("--target は1つだけ指定できます");
258
+ return cleanBasis({ kind: o.basis, reference: given.reference, command: given.command, result: given.result, target: given.target?.[0] });
259
+ }
151
260
  export function readBody(v) {
152
261
  if (v === undefined)
153
262
  return "";
@@ -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,214 @@
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
+ 5. 作業中に見つけた追加の作業は `new "<タイトル>" --req <要望ID> --body "..."` でタスクにする(タスクの関係は Preflight のタスク化が張るもので、手では張らない。順序は本文に書く)
143
+ **進められなくなったら止まっている理由を付けて終える**(安全に続けられる通常の修正・調査の途中では使わない):
144
+ 人の判断や権限が要る・前提が崩れた・直しても調べてもテストが通らず先に進めない、などでこのタスクを続けられなくなったら、
145
+ `block <T> --req <要望ID> --reason "<具体的な理由>" --decision "<人に決めてほしいこと>" --json`(複数行は `--reason -` で標準入力)。
146
+ 人への質問を新しいタスクにする代わりに、今のタスクに付ける。未着手の依存待ちのタスクを作業中にしてまで付けない。
147
+ 返った JSON の `block` で保存できたことを確かめ、要望とタスクの ID・理由・いつから(`since`)・答えてほしいこと・確かめたこと・
148
+ 再開のしかたをユーザーに伝えて、そのタスクの作業を終えて回答を待つ。止まったまま完了・済み・要望の対応済に進めない
149
+ (止まったままは完了へ動かせない)。止まっていることを避けるために基準や証拠を書き換えない。停止の履歴と完了の変更の記録(`record`)は別。
150
+ 保存が競合・失敗したら読み直して結果を確かめ、記録できたと偽らずに伝える(タスクを変え続けて理由を覆い隠さない)
151
+ **回答を受けたら解除して再開する**: `unblock <T> --req <要望ID> --resolution "<回答・解決の内容>"`。人が先に解除していたら、
152
+ `show <T> --json` の停止の履歴で回答を読み、前提が満たされたことを確かめてから再開する。解除だけでは自動で再開しない。
153
+ 新しい理由で止まったら、新しい停止として付ける
154
+ 6. 要望のタスクが全部完了したら(`ls --req <要望ID>` が全部 done、成果物と検証も済み)、コミットする前に要望を **対応済** にする:
155
+ `request set <要望ID> status=resolved --json`。未完了のタスクがあると拒否される(終わらせるか、不要ならユーザーの了承を得て
156
+ `archive`)。拒否をタスクを偽って完了にする・ファイルを直接書き換えるなどで回避しない
157
+ 7. コミットして push する。データのフォルダ(`whoami` の場所)がこの作業ツリーの中にあって git で管理されている(無視されていない)なら、
158
+ **要望のフォルダ(`<データのフォルダ>/requests/<要望ID>/`)の変更も実装と同じコミットに入れる**。要望とタスク・変更の記録が
159
+ コードと一緒に残り、後のレビュー(AI のレビューも)で、コードだけでなく「何を目的に頼まれ、何をしたか」を精査できる。
160
+ 親子でつながる要望のフォルダも、まだコミットに入っていない変更があれば入れる: 子の要望なら**祖先の要望のフォルダ**(分割の採用・
161
+ 子の順・状態は親に残る)、親を対応済にするときは**子孫の要望のフォルダ**(見送りにした子など、実装の無い要望)。それ以外の要望や
162
+ 関係ない変更はまとめて add しない(`git status` でフォルダを確かめてから add する)。データのフォルダが外・別のリポジトリ・git で無視されている、または git の作業ツリー(worktree)で作業して
163
+ いてデータがメインの作業ツリーにあるときは、同じコミットには入らない(データの移動・写し・`git add -f` はしない。記録は p3 に
164
+ 残り、コードとは成果物の URL で結ぶ)。commit・push に失敗したら、完了の記録はそのまま残し、公開できていないことをユーザーに
165
+ 伝えてやり直す(完了を push できたことのように伝えない)。同じコミットに入れた要望のフォルダは、
166
+ マージするまで要望のブランチにしか無い。既定のブランチに切り替えると、その要望(子なら親の子の一覧からも)が消えたように見えるが、
167
+ データはブランチにある(作り直したり、別のブランチから写したりしない。親の詳細には `child_missing` が出る)
168
+ 8. コミットや PR の URL を残すなら、後から `move T003 done --req <要望ID> --output <URL>` で足す(完了・記録・前の成果物はそのまま。
169
+ 完了から戻さない)。要望のフォルダを同じコミットに入れているなら、この追記もコミットして同じブランチに push する(追記のコミット
170
+ 自身の URL は残さなくてよい)。PR はユーザーに確認してから作る(本文に要望 ID とタスクの一覧)。作った PR の URL は最後のタスクに
171
+ 足す。複数のリポジトリにまたがる要望は、関係するリポジトリの PR を全部 `--repo-output <参照先の名前>=<PR の URL>` で最後のタスクに
172
+ 残す(例: `move T005 done --repo-output app=<URL> --repo-output infra=<URL>`。1つのリポジトリなら今までどおり `--output` でよい)。
173
+ マージ・要望の完了済(`done`)は人が行う
174
+ 9. 対応済の後にタスクを足した・完了から戻したときは、要望は自動で進行中に戻る(`--json` の `reopened`)。
175
+ 終えたらもう一度 6 で対応済にする
176
+
177
+ ### 子の要望(大きい要望を分けたもの)
178
+
179
+ - 子の要望(`parent` のある要望)は、親とは別の要望として、子ごとのタスクとブランチで作業する(親のタスクにしない。
180
+ 手順は上と同じ)。親子は `request show <要望ID> --brief --json` の `parent`・`ancestors`・`children` で読む
181
+ - 分割の案(Preflight の子の案)の採用(`accept`)は人が行う。子の Preflight は親と同じく、頼まれたときだけ
182
+ 「Preflight を頼まれたとき」の担当に従う(分割の採用・子の作成から、自分で子の評価へ進まない)
183
+ - 子のタスクを全部終えたら、子を対応済にする(6)。親を対応済にするのは、親のタスクと見送り以外の子(`children`)が
184
+ 全部 対応済か完了済になってから。条件を満たさなければ拒否される(理由が出る)
185
+ - 子にタスクを足す・完了から戻すと、対応済の親も進行中に戻る(`--json` の `reopenedAncestors`)。完了済の親は変わらず
186
+ `warnings`(`ancestor_done`)が出るので、作業を止めて人に伝える
187
+
188
+ ## してはいけないこと
189
+
190
+ - Preflight(`preflight`)を自分から始めない・勧めない。`p3 preflight <要望ID>`(Codex で評価する通常の実行)は人が行い、AI は
191
+ しない。手元の評価(`--prepare` / `--complete`)は、上の「Preflight を頼まれたとき」の担当ごとの条件を満たしたときだけ
192
+ - タスク化(`accept`)をしない(人が行う。Preflight を頼まれたときも、評価の後にタスク化・着手へ進まない)
193
+ - `check`(済み)を付けない。済みは人が成果物を確認して付ける
194
+ - 要望のステータスを `done`(完了済)/ `rejected`(見送り)にしない(人が決める)。AI がするのは作業を終えたときの `resolved`(対応済)まで。
195
+ タスク化で `active` になるのは自動
196
+ - タスクを要望をまたいで動かさない。別の要望の作業なら、その要望にタスクを足すか、新しい要望を提案する
197
+ - データのフォルダ(`p3 whoami` に出る場所)や個人設定(`~/.config/infodb-p3/`)のファイルを直接書き換えない
198
+ (例外は、頼まれた Preflight で `--prepare` が返した run の成果物だけ)
199
+ - 人への質問をタスクにしない(続けられないなら今のタスクに止まっている理由を付ける)
200
+ - 止まっている理由を付けたまま作業を続けたり、完了・済み・対応済に進めたりしない。回答を受けずに自分で解除しない
201
+ - タスクの AI レビュー(`review`)を頼まれずに始めない(Codex を使い、利用者のプランを消費する)。頼まれたら Preflight と同じく担当で
202
+ 分け、`agent` のプロジェクトでも Codex で実行するのは人が明示したときだけ(`--engine codex`)。レビューの結果を理由に済みにしない・
203
+ 基準や証拠を書き換えない(結果は参考の記録で、済みは人が決める)
204
+ - 受け入れ基準を自分で消す・書き換える・並べ替えて、満たしたことにしない(基準を変える必要があれば人に確かめる。済みのタスクの
205
+ 基準・証拠を変えると人の済みが外れる)。確かめていない項目を `met` にしない
206
+ - 要求の出典の確認(`source ... confirm`・`--by` / `--on`)を、人が実際に確かめたと伝えた内容のほかに付けない。AI の評価・テストの
207
+ 結果・レビュー・人の済みを、確かめた人として記録しない(「確認記録あり」は人の確認の申告で、確認先が分からなければ分からないまま残す)
208
+ - 見直しが必要(候補)(`revisit`)を理由に、自分で再開・済みの付け直し・基準の書き換えをしない(候補は人が確かめる材料)。
209
+ 前提の変更の確認(`premise ... ack`)は、人が確かめたと伝えた内容のほかに付けない
210
+
211
+ ## 状況を報告する
212
+
213
+ - 全体: `progress`(マイルストーンごと)。要望の中: `ls --req <要望ID>`
214
+ - 画面はユーザーが `p3 serve` で開く(既定 http://localhost:4310)。CLI の変更はそのまま画面に反映される