specdojo 0.2.1 → 0.3.1

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 (242) hide show
  1. package/.github/agents/specdojo-orchestrator.md +165 -0
  2. package/CHANGELOG.md +298 -0
  3. package/README.md +92 -42
  4. package/dist/agent-response.js +20 -0
  5. package/dist/agent.js +4 -4
  6. package/dist/build-command.js +28 -8
  7. package/dist/catalog-build-references.js +144 -0
  8. package/dist/catalog-build-render.js +144 -0
  9. package/dist/catalog-build.js +13 -290
  10. package/dist/catalog-generate.js +6 -9
  11. package/dist/catalog-plan-generate.js +2 -2
  12. package/dist/catalog-plan.js +6 -6
  13. package/dist/catalog-scaffold.js +4 -4
  14. package/dist/catalog.js +2 -2
  15. package/dist/dashboard-exec-records.js +105 -0
  16. package/dist/dashboard-routines.js +255 -0
  17. package/dist/dashboard-shared.js +14 -0
  18. package/dist/dashboard-timeline.js +175 -0
  19. package/dist/dashboard.js +31 -444
  20. package/dist/deliverable-trash.js +3 -3
  21. package/dist/devcontainer-command.js +43 -0
  22. package/dist/devcontainer-scaffold.js +165 -0
  23. package/dist/doc-index.js +3 -3
  24. package/dist/exec-agent-config.js +107 -9
  25. package/dist/exec-agent-git-state.js +18 -0
  26. package/dist/exec-agent-protected-config.js +46 -8
  27. package/dist/exec-commands.js +557 -0
  28. package/dist/exec-core.js +457 -0
  29. package/dist/exec-evidence.js +254 -11
  30. package/dist/exec-handoff.js +336 -0
  31. package/dist/exec-parent-validation.js +317 -43
  32. package/dist/exec-pipeline-state.js +74 -9
  33. package/dist/exec-plans-core.js +693 -0
  34. package/dist/exec-plans-generation.js +206 -0
  35. package/dist/exec-plans-storage.js +131 -0
  36. package/dist/exec-plans.js +3 -1016
  37. package/dist/exec-protection-handoff.js +43 -2
  38. package/dist/exec-provider-scaffold.js +247 -15
  39. package/dist/exec-register-resume.js +65 -19
  40. package/dist/exec-register.js +9 -3
  41. package/dist/exec-repo-integration-git.js +23 -0
  42. package/dist/exec-repo-integration-sync.js +264 -0
  43. package/dist/exec-repo-integration.js +534 -0
  44. package/dist/exec-repo-trace.js +182 -0
  45. package/dist/exec-reporter-output.js +206 -0
  46. package/dist/exec-reporter.js +525 -248
  47. package/dist/exec-results.js +103 -71
  48. package/dist/exec-run-agent-pipeline.js +256 -0
  49. package/dist/exec-run-agent.js +531 -0
  50. package/dist/exec-run-in-place.js +541 -0
  51. package/dist/exec-run-job.js +717 -0
  52. package/dist/exec-run-lifecycle-commands.js +522 -0
  53. package/dist/exec-run-lock.js +110 -107
  54. package/dist/exec-run-mode-shared.js +140 -0
  55. package/dist/exec-run-register-command.js +244 -0
  56. package/dist/exec-run-register-core.js +386 -0
  57. package/dist/exec-run-register-mode.js +206 -0
  58. package/dist/exec-run-register-resume.js +393 -0
  59. package/dist/exec-run-register-state.js +322 -0
  60. package/dist/exec-run-register-worktree.js +509 -0
  61. package/dist/exec-run-schedule-mode.js +294 -0
  62. package/dist/exec-run-schedule-prepare.js +353 -0
  63. package/dist/exec-run-schedule-task.js +572 -0
  64. package/dist/exec-run-shared.js +399 -0
  65. package/dist/exec-run.js +11 -4953
  66. package/dist/exec-shared.js +9 -2
  67. package/dist/exec-slot-lock.js +242 -0
  68. package/dist/exec-task-repos.js +415 -0
  69. package/dist/exec-trial-commands.js +558 -0
  70. package/dist/exec-trial-core.js +371 -0
  71. package/dist/exec-trial.js +2 -895
  72. package/dist/exec-worktree-command.js +87 -43
  73. package/dist/exec-worktree-ops-commit.js +707 -0
  74. package/dist/exec-worktree-ops-lifecycle.js +292 -0
  75. package/dist/exec-worktree-ops-merge.js +303 -0
  76. package/dist/exec-worktree-ops.js +3 -847
  77. package/dist/exec-worktree.js +146 -31
  78. package/dist/exec.js +2 -999
  79. package/dist/frontmatter-namespace.js +2 -2
  80. package/dist/grade-apply.js +734 -0
  81. package/dist/grade-command-apply.js +250 -0
  82. package/dist/grade-command-inspect.js +138 -0
  83. package/dist/grade-command-plan.js +101 -0
  84. package/dist/grade-command-shared.js +68 -0
  85. package/dist/grade-core.js +307 -0
  86. package/dist/grade-markdown.js +274 -0
  87. package/dist/grade-pipeline-state.js +184 -0
  88. package/dist/grade-plan.js +507 -0
  89. package/dist/grade-result.js +133 -5
  90. package/dist/grade-target-discovery.js +265 -0
  91. package/dist/grade-targets.js +432 -0
  92. package/dist/grade.js +14 -2451
  93. package/dist/init-command.js +443 -0
  94. package/dist/job-definition.js +670 -0
  95. package/dist/job.js +64 -578
  96. package/dist/kata-command.js +2 -2
  97. package/dist/orchestrator.js +213 -0
  98. package/dist/register-command-types.js +1 -0
  99. package/dist/register-core.js +363 -0
  100. package/dist/register-create-commands.js +245 -0
  101. package/dist/register-event-merge.js +169 -0
  102. package/dist/register-events.js +4 -4
  103. package/dist/register-item.js +13 -7
  104. package/dist/register-maintenance-commands.js +187 -0
  105. package/dist/register-migration.js +268 -0
  106. package/dist/register-renumber.js +314 -0
  107. package/dist/register-transition-commands.js +248 -0
  108. package/dist/register-update.js +230 -0
  109. package/dist/register-views.js +256 -0
  110. package/dist/register.js +175 -1975
  111. package/dist/review-grade.js +252 -0
  112. package/dist/review-plan.js +114 -4
  113. package/dist/review-types.js +40 -1
  114. package/dist/routine-definition.js +401 -0
  115. package/dist/routine.js +73 -402
  116. package/dist/schedule-approach.js +2 -2
  117. package/dist/schedule-build.js +2 -2
  118. package/dist/schedule-strategy-generate-document.js +273 -0
  119. package/dist/schedule-strategy-generate-scope.js +199 -0
  120. package/dist/schedule-strategy-generate.js +9 -473
  121. package/dist/schedule.js +19 -6
  122. package/dist/specdojo-config.js +465 -20
  123. package/dist/specdojo-gitignore.js +135 -0
  124. package/dist/specdojo.js +6 -0
  125. package/dist/viewpoint-document-kinds-check.js +128 -0
  126. package/dist/yaml-pages.js +4 -4
  127. package/dist/yaml.js +28 -0
  128. package/docs/ja/specdojo/defaults/pm-review-viewpoints.yaml +348 -90
  129. package/docs/ja/specdojo/exec-templates/xep-common-conventions-template.md +51 -17
  130. package/docs/ja/specdojo/exec-templates/xep-fully-guided-template.md +7 -5
  131. package/docs/ja/specdojo/exec-templates/xrp-freeform-template.md +29 -31
  132. package/docs/ja/specdojo/exec-templates/xrp-fully-guided-template.md +34 -55
  133. package/docs/ja/specdojo/exec-templates/xrp-job-template.md +54 -0
  134. package/docs/ja/specdojo/exec-templates/xrp-recipe-guided-template.md +28 -37
  135. package/docs/ja/specdojo/exec-templates/xrp-recipe-maintenance-template.md +29 -34
  136. package/docs/ja/specdojo/exec-templates/xrp-retrofit-template.md +30 -30
  137. package/docs/ja/specdojo/exec-templates/xrp-rulebook-maintenance-template.md +29 -34
  138. package/docs/ja/specdojo/exec-templates/xrp-sample-maintenance-template.md +29 -34
  139. package/docs/ja/specdojo/exec-templates/xrp-template-maintenance-template.md +29 -34
  140. package/docs/ja/specdojo/exec-templates/xrp-template.md +29 -28
  141. package/docs/ja/specdojo/exec-templates/xrr-template.md +11 -9
  142. package/docs/ja/specdojo/guides/docs-editing-guide.md +20 -0
  143. package/docs/ja/specdojo/guides/docs-structure-guide.md +103 -70
  144. package/docs/ja/specdojo/guides/exec-config-guide.md +93 -49
  145. package/docs/ja/specdojo/guides/exec-operation-guide.md +124 -27
  146. package/docs/ja/specdojo/guides/exec-worktree-guide.md +40 -11
  147. package/docs/ja/specdojo/guides/kata-guide.md +4 -4
  148. package/docs/ja/specdojo/guides/orchestrator-operation-guide.md +45 -22
  149. package/docs/ja/specdojo/guides/plan-result-lifecycle-guide.md +1 -1
  150. package/docs/ja/specdojo/guides/practice-system-composition-guide.md +13 -13
  151. package/docs/ja/specdojo/guides/quick-start-guide.md +260 -30
  152. package/docs/ja/specdojo/guides/register-operation-guide.md +31 -14
  153. package/docs/ja/specdojo/guides/release-v0-3-0-migration-guide.md +264 -0
  154. package/docs/ja/specdojo/guides/remote-host-development-guide.md +22 -1
  155. package/docs/ja/specdojo/guides/review-guide.md +195 -158
  156. package/docs/ja/specdojo/guides/routine-operation-guide.md +75 -10
  157. package/docs/ja/specdojo/guides/ryu-guide.md +32 -30
  158. package/docs/ja/specdojo/guides/schedule-design-guide.md +10 -10
  159. package/docs/ja/specdojo/guides/schedule-operation-guide.md +1 -1
  160. package/docs/ja/specdojo/guides/specdojo-overview-guide.md +58 -33
  161. package/docs/ja/specdojo/guides/use-case-guide.md +3 -3
  162. package/docs/ja/specdojo/guides/waza-guide.md +15 -2
  163. package/docs/ja/specdojo/index.md +2 -2
  164. package/docs/ja/specdojo/philosophy/specdojo-philosophy.md +5 -5
  165. package/docs/ja/specdojo/recipes/bps-recipe.md +213 -0
  166. package/docs/ja/specdojo/recipes/pm-members-recipe.md +52 -117
  167. package/docs/ja/specdojo/references/command-reference.md +335 -92
  168. package/docs/ja/specdojo/references/deliverables-reference.md +1 -1
  169. package/docs/ja/specdojo/references/directory-layout-reference.md +13 -9
  170. package/docs/ja/specdojo/references/specdojo-config-reference.md +107 -24
  171. package/docs/ja/specdojo/rulebooks/bps-rulebook.md +132 -220
  172. package/docs/ja/specdojo/rulebooks/br-rulebook.md +6 -44
  173. package/docs/ja/specdojo/rulebooks/cdfd-rulebook.md +2 -0
  174. package/docs/ja/specdojo/rulebooks/dmd-rulebook.md +0 -87
  175. package/docs/ja/specdojo/rulebooks/gl-rulebook.md +61 -39
  176. package/docs/ja/specdojo/rulebooks/ifx-cmd-rulebook.md +0 -87
  177. package/docs/ja/specdojo/rulebooks/ifx-index-rulebook.md +1 -33
  178. package/docs/ja/specdojo/rulebooks/opd-rulebook.md +0 -137
  179. package/docs/ja/specdojo/rulebooks/opr-rulebook.md +0 -247
  180. package/docs/ja/specdojo/rulebooks/otp-rulebook.md +0 -83
  181. package/docs/ja/specdojo/rulebooks/pjr-rulebook.md +4 -2
  182. package/docs/ja/specdojo/rulebooks/pm-members-rulebook.md +78 -150
  183. package/docs/ja/specdojo/rulebooks/pm-roles-rulebook.md +5 -4
  184. package/docs/ja/specdojo/rulebooks/sch-rulebook.md +1 -1
  185. package/docs/ja/specdojo/rulebooks/stsd-mermaid-rulebook.md +0 -11
  186. package/docs/ja/specdojo/rulebooks/stsd-rulebook.md +0 -61
  187. package/docs/ja/specdojo/rulebooks/tml-rulebook.md +2 -47
  188. package/docs/ja/specdojo/samples/bps-sample.md +74 -21
  189. package/docs/ja/specdojo/samples/gl-sample.yaml +17 -1
  190. package/docs/ja/specdojo/samples/ifx-index-sample.yaml +28 -0
  191. package/docs/ja/specdojo/samples/pm-members-sample.yaml +2 -67
  192. package/docs/ja/specdojo/samples/pm-organization-sample.md +8 -7
  193. package/docs/ja/specdojo/samples/pm-raci-sample.md +1 -1
  194. package/docs/ja/specdojo/samples/tml-sample.yaml +40 -0
  195. package/docs/ja/specdojo/standards/document-metadata-standard.md +21 -16
  196. package/docs/ja/specdojo/standards/id-and-file-naming-standard.md +14 -14
  197. package/docs/ja/specdojo/standards/job-definition-standard.md +37 -17
  198. package/docs/ja/specdojo/standards/people-and-organization-definition-standard.md +37 -32
  199. package/docs/ja/specdojo/standards/philosophy-authoring-standard.md +1 -1
  200. package/docs/ja/specdojo/standards/rulebook-authoring-standard.md +21 -11
  201. package/docs/ja/specdojo/templates/agent-members-template.yaml +25 -0
  202. package/docs/ja/specdojo/templates/bps-template.md +91 -0
  203. package/docs/ja/specdojo/templates/pm-members-template.yaml +2 -59
  204. package/docs/specdojo/schemas/v1/agent-members.schema.yaml +76 -0
  205. package/docs/specdojo/schemas/v1/exec-common.schema.yaml +4 -2
  206. package/docs/specdojo/schemas/v1/exec-defaults.schema.yaml +55 -2
  207. package/docs/specdojo/schemas/v1/exec-evidence.schema.yaml +93 -6
  208. package/docs/specdojo/schemas/v1/exec-reporter-output.schema.yaml +27 -78
  209. package/docs/specdojo/schemas/v1/gl.schema.yaml +87 -0
  210. package/docs/specdojo/schemas/v1/grade-result.schema.yaml +33 -0
  211. package/docs/specdojo/schemas/v1/job-run.schema.yaml +27 -0
  212. package/docs/specdojo/schemas/v1/job.schema.yaml +25 -0
  213. package/docs/specdojo/schemas/v1/pipeline-state.schema.yaml +49 -1
  214. package/docs/specdojo/schemas/v1/pm-members.schema.yaml +9 -169
  215. package/docs/specdojo/schemas/v1/pm-review-viewpoints.schema.yaml +100 -10
  216. package/docs/specdojo/schemas/v1/register-item-frontmatter.schema.yaml +13 -0
  217. package/docs/specdojo/schemas/v1/routine-run.schema.yaml +3 -0
  218. package/docs/specdojo/schemas/v1/routine.schema.yaml +7 -0
  219. package/docs/specdojo/schemas/v1/specdojo-config.schema.yaml +110 -0
  220. package/package.json +17 -12
  221. package/templates/antigravity/README.md +29 -4
  222. package/templates/antigravity/{pm-members-snippet.yaml → agent-members-snippet.yaml} +8 -2
  223. package/templates/antigravity/exec-defaults-snippet.yaml +10 -7
  224. package/templates/antigravity/orchestrator.md +18 -7
  225. package/templates/antigravity/settings.global.json +55 -0
  226. package/templates/claude/agents/claude-executor.md +14 -0
  227. package/templates/claude/agents/claude-reporter.md +16 -0
  228. package/templates/claude/agents/specdojo-orchestrator.md +18 -7
  229. package/templates/claude/settings.edit.json +27 -1
  230. package/templates/codex/README.md +5 -4
  231. package/templates/codex/agents/specdojo-orchestrator.toml +18 -7
  232. package/templates/codex/orchestrator.md +18 -7
  233. package/templates/copilot/README.md +7 -5
  234. package/templates/copilot/{pm-members-snippet.yaml → agent-members-snippet.yaml} +4 -2
  235. package/templates/devcontainer/devcontainer.json +27 -0
  236. package/templates/devcontainer/emacs/init.el +88 -0
  237. package/templates/devcontainer/post-create.sh +62 -0
  238. package/templates/init-agent-members.yaml +200 -0
  239. package/templates/init-exec-defaults.yaml +74 -0
  240. package/templates/opencode/agents/specdojo-orchestrator.md +18 -7
  241. package/docs/ja/specdojo/exec-templates/xrp-viewpoint-detail-template.md +0 -7
  242. package/docs/ja/specdojo/exec-templates/xrr-viewpoint-detail-template.md +0 -7
@@ -0,0 +1,245 @@
1
+ import { existsSync, mkdirSync } from "node:fs";
2
+ import { join } from "node:path";
3
+ import { inlineCodeAnglePlaceholders } from "./exec-shared.js";
4
+ import { appendRegisterEvent, buildRegisterEvent, registerEventFilePath, } from "./register-events.js";
5
+ import { nowUtcTimestamp } from "./register-date.js";
6
+ import { CELL_NONE, CELL_TODO, REMOVE_REGISTER_ITEM_FIELD, VALID_PRIORITIES, VALID_STATUSES, VALID_TYPES, } from "./register-item.js";
7
+ import { resolveSpecdojoTemplatePath } from "./template-resolution.js";
8
+ export function registerCreateCommands(reg, dependencies) {
9
+ const { addProjectOption, addRegisterCommitOptions, atomicWriteFile, buildRegisterItemContent, derivedTopicNeedsWarning, generateDerivedViewFiles, loadRegisterItems, parseRegisterTimestampOption, planRegisterItem, printCommandError, printDerivedTopicWarning, registerEventActor, registerTopicPattern, resolveRegisterPaths, runRegisterMutation, slugify, writeDerivedViews, } = dependencies;
10
+ // --- scaffold ---
11
+ const scaffoldCmd = reg
12
+ .command("scaffold")
13
+ .description("Initialize the register directory and generate its views");
14
+ addProjectOption(scaffoldCmd);
15
+ scaffoldCmd.option("--dry-run", "Print generated content to stdout without writing", false);
16
+ scaffoldCmd.action((opts) => {
17
+ try {
18
+ const paths = resolveRegisterPaths(opts);
19
+ if (opts.dryRun) {
20
+ for (const view of generateDerivedViewFiles(paths, "all")) {
21
+ process.stdout.write(`=== ${view.path} ===\n${view.content}\n\n`);
22
+ }
23
+ return;
24
+ }
25
+ mkdirSync(paths.projectRegisterPath, { recursive: true });
26
+ process.stdout.write(`Created: ${paths.projectRegisterPath}/\n`);
27
+ for (const view of writeDerivedViews(paths, "all")) {
28
+ process.stdout.write(`Generated: ${view.path}\n`);
29
+ }
30
+ }
31
+ catch (error) {
32
+ printCommandError(error);
33
+ }
34
+ });
35
+ // --- add ---
36
+ const addCmd = reg.command("add").description("Add a new item to pjr-index.md");
37
+ addProjectOption(addCmd);
38
+ addCmd.requiredOption("--type <type>", `Item type: ${VALID_TYPES.join(" | ")}`);
39
+ addCmd.requiredOption("--title <title>", "Short title for the item");
40
+ addCmd.option("--description <text>", "Description shown in the list", "_TODO_");
41
+ addCmd.option("--priority <priority>", `Priority: ${VALID_PRIORITIES.join(" | ")}`, "medium");
42
+ addCmd.option("--status <status>", `Status: ${VALID_STATUSES.join(" | ")}`, "open");
43
+ addCmd.option("--owner <owner>", "Owner or role", "_TODO_");
44
+ addCmd.option("--registered <datetime>", "Registration date-time (RFC 3339 with time zone, or _TODO_; defaults to now in UTC)");
45
+ addCmd.option("--due <date>", "Due date (YYYY-MM-DD, -, or _TODO_)", "_TODO_");
46
+ addCmd.option("--completed <datetime>", "Completion date-time (RFC 3339 with time zone, or -)", "-");
47
+ addCmd.option("--conclusion <text>", "Conclusion or resolution summary", "-");
48
+ addCmd.option("--id <id>", "Display ID (e.g., PJR-0061); auto-incremented if omitted");
49
+ addCmd.option("--topic <topic>", "Topic slug for ticket filename; derived from --title if omitted");
50
+ addCmd.option("--by <actor>", "Actor recorded in the append-only register event");
51
+ addCmd.option("--reason <text>", "Reason recorded in the append-only register event");
52
+ addCmd.option("--force", "Overwrite existing ticket file", false);
53
+ addCmd.option("--dry-run", "Print the generated item file without writing", false);
54
+ addRegisterCommitOptions(addCmd);
55
+ addCmd.action(async (opts) => {
56
+ await runRegisterMutation("add", opts, ({ paths, assertCommitTargetsClean }) => {
57
+ const explicitTopic = opts.topic?.trim();
58
+ const topic = explicitTopic || slugify(opts.title);
59
+ const warnAboutDerivedTopic = explicitTopic === undefined && derivedTopicNeedsWarning(opts.title, topic);
60
+ if (!registerTopicPattern.test(topic)) {
61
+ throw new Error(`Invalid topic: "${topic}". Must use lowercase letters, numbers, and single hyphens`);
62
+ }
63
+ const registeredAt = parseRegisterTimestampOption(opts.registered, "registered", CELL_TODO);
64
+ const completedAt = parseRegisterTimestampOption(opts.completed, "completed", CELL_NONE);
65
+ const fields = {
66
+ type: opts.type,
67
+ title: opts.title,
68
+ description: opts.description,
69
+ priority: opts.priority,
70
+ status: opts.status,
71
+ owner: opts.owner,
72
+ registeredAt: registeredAt ?? nowUtcTimestamp(),
73
+ due: opts.due,
74
+ completedAt: completedAt ?? CELL_NONE,
75
+ conclusion: opts.conclusion,
76
+ };
77
+ const templatePath = resolveSpecdojoTemplatePath(`pjr-${opts.type}-template.md`);
78
+ const { assignedId: displayId, ticketFilename } = planRegisterItem({
79
+ existingIds: loadRegisterItems(paths).map((view) => view.id),
80
+ explicitId: opts.id?.trim() || undefined,
81
+ fields,
82
+ topic,
83
+ });
84
+ const ticketPath = join(paths.projectRegisterPath, ticketFilename);
85
+ const content = buildRegisterItemContent({
86
+ projectId: paths.projectId,
87
+ displayId,
88
+ topic,
89
+ fields,
90
+ templatePath,
91
+ });
92
+ const addEvent = buildRegisterEvent({
93
+ afterContent: content,
94
+ filename: ticketFilename,
95
+ timeZone: paths.registerDateTimeZone,
96
+ action: "add",
97
+ actor: registerEventActor(opts),
98
+ reason: opts.reason?.trim() || "item added",
99
+ });
100
+ if (!addEvent)
101
+ throw new Error(`Failed to build add event for ${displayId}`);
102
+ if (opts.dryRun) {
103
+ process.stdout.write(`Would create ${ticketPath}:\n${content}\n`);
104
+ process.stdout.write(`Would create ${registerEventFilePath(paths.projectRegisterPath, displayId)}:\n` +
105
+ `${appendRegisterEvent(undefined, addEvent)}\n`);
106
+ if (warnAboutDerivedTopic)
107
+ printDerivedTopicWarning(topic);
108
+ return { id: displayId, title: opts.title };
109
+ }
110
+ if (!opts.force && existsSync(ticketPath)) {
111
+ throw new Error(`Item file already exists (use --force to overwrite): ${ticketPath}`);
112
+ }
113
+ const eventPath = registerEventFilePath(paths.projectRegisterPath, displayId);
114
+ assertCommitTargetsClean([ticketPath, eventPath]);
115
+ if (!opts.force && existsSync(eventPath)) {
116
+ throw new Error(`Register event file already exists (use --force to overwrite): ${eventPath}`);
117
+ }
118
+ mkdirSync(paths.projectRegisterPath, { recursive: true });
119
+ atomicWriteFile(ticketPath, content);
120
+ atomicWriteFile(eventPath, appendRegisterEvent(undefined, addEvent));
121
+ process.stdout.write(`Created: ${ticketPath} (added ${displayId})\n`);
122
+ process.stdout.write(`Created: ${eventPath}\n`);
123
+ if (existsSync(paths.pjrIndexPath)) {
124
+ for (const view of writeDerivedViews(paths, "all")) {
125
+ process.stdout.write(`Generated: ${view.path}\n`);
126
+ }
127
+ }
128
+ if (warnAboutDerivedTopic)
129
+ printDerivedTopicWarning(topic);
130
+ return { id: displayId, title: opts.title };
131
+ });
132
+ });
133
+ }
134
+ export function registerUpdateCommand(reg, dependencies) {
135
+ const { addProjectOption, addRegisterCommitOptions, applyItemUpdate, assertRegisterItemCommitTargetsClean, loadItemForUpdate, planRetopic, registerEventActor, registerTopicPattern, retopicPjrItem, runRegisterMutation, ticketTopicFromFilename, } = dependencies;
136
+ // --- update ---
137
+ const updateCmd = reg.command("update").description("Update fields of a register item");
138
+ addProjectOption(updateCmd);
139
+ updateCmd.requiredOption("--id <id>", "Item ID (PJR-XXXX)");
140
+ updateCmd.option("--title <title>", "Update title");
141
+ updateCmd.option("--description <text>", "Update description");
142
+ updateCmd.option("--priority <priority>", `Update priority: ${VALID_PRIORITIES.join(" | ")}`);
143
+ updateCmd.option("--owner <owner>", "Update owner or role");
144
+ updateCmd.option("--due <date>", "Update due date (YYYY-MM-DD, -, or _TODO_)");
145
+ updateCmd.option("--conclusion <text>", "Update conclusion or use - to remove it");
146
+ updateCmd.option("--block-reason <text>", "Update the waiting reason or use - to remove it");
147
+ updateCmd.option("--topic <topic>", "Update the topic slug in the ticket filename and document ID");
148
+ updateCmd.option("--by <actor>", "Actor recorded in the append-only register event");
149
+ updateCmd.option("--reason <text>", "Reason recorded in the append-only register event");
150
+ updateCmd.option("--dry-run", "Print change without writing", false);
151
+ addRegisterCommitOptions(updateCmd);
152
+ updateCmd.action(async (opts) => {
153
+ await runRegisterMutation("update", opts, (context) => {
154
+ const { paths } = context;
155
+ const view = loadItemForUpdate(paths, opts.id);
156
+ const item = view.item;
157
+ const hasUpdates = [
158
+ "title",
159
+ "description",
160
+ "priority",
161
+ "owner",
162
+ "due",
163
+ "conclusion",
164
+ "blockReason",
165
+ "topic",
166
+ ].some((key) => opts[key] !== undefined);
167
+ if (!hasUpdates) {
168
+ throw new Error("At least one field option must be specified (--title, --description, --priority, --owner, --due, --conclusion, --block-reason, --topic)");
169
+ }
170
+ if (opts.priority !== undefined &&
171
+ !VALID_PRIORITIES.includes(opts.priority)) {
172
+ throw new Error(`Invalid priority: "${opts.priority}". Must be one of: ${VALID_PRIORITIES.join(", ")}`);
173
+ }
174
+ if (opts.due !== undefined && !/^(\d{4}-\d{2}-\d{2}|-|_TODO_)$/.test(opts.due)) {
175
+ throw new Error(`Invalid due: "${opts.due}". Must be YYYY-MM-DD, -, or _TODO_`);
176
+ }
177
+ const topic = opts.topic?.trim();
178
+ if (topic !== undefined && !registerTopicPattern.test(topic)) {
179
+ throw new Error(`Invalid topic: "${topic}". Must use lowercase letters, numbers, and single hyphens`);
180
+ }
181
+ const blockReason = opts.blockReason?.trim();
182
+ if (blockReason !== undefined && blockReason === "") {
183
+ throw new Error("Block reason must not be empty; use - to remove it");
184
+ }
185
+ if (blockReason !== undefined && blockReason !== "-" && item.status !== "waiting") {
186
+ throw new Error(`Cannot set block reason for ${item.id}: status is "${item.status}" (expected "waiting"). Use - to remove it.`);
187
+ }
188
+ const blockReasonUpdates = blockReason === undefined
189
+ ? undefined
190
+ : {
191
+ block_reason: blockReason === "-"
192
+ ? REMOVE_REGISTER_ITEM_FIELD
193
+ : inlineCodeAnglePlaceholders(blockReason),
194
+ };
195
+ const updated = {
196
+ ...item,
197
+ ...(opts.title !== undefined ? { title: opts.title } : {}),
198
+ ...(opts.description !== undefined ? { description: opts.description } : {}),
199
+ ...(opts.priority !== undefined ? { priority: opts.priority } : {}),
200
+ ...(opts.owner !== undefined ? { owner: opts.owner } : {}),
201
+ ...(opts.due !== undefined ? { due: opts.due } : {}),
202
+ ...(opts.conclusion !== undefined ? { conclusion: opts.conclusion } : {}),
203
+ };
204
+ const currentTopic = view.ticketFilename
205
+ ? ticketTopicFromFilename(opts.id, view.ticketFilename)
206
+ : undefined;
207
+ if (topic !== undefined && topic !== currentTopic) {
208
+ const retopicPlan = planRetopic(paths, opts.id, topic);
209
+ context.assertCommitTargetsClean([
210
+ retopicPlan.ticketRename.from,
211
+ ...retopicPlan.writes.map((write) => write.path),
212
+ registerEventFilePath(paths.projectRegisterPath, item.id),
213
+ ]);
214
+ retopicPjrItem({
215
+ paths,
216
+ id: opts.id,
217
+ topic,
218
+ updated,
219
+ dryRun: opts.dryRun,
220
+ ...(blockReasonUpdates ? { fieldUpdates: blockReasonUpdates } : {}),
221
+ ...(opts.title !== undefined ? { title: opts.title } : {}),
222
+ ...(opts.description !== undefined ? { description: opts.description } : {}),
223
+ actor: registerEventActor(opts),
224
+ reason: opts.reason?.trim() || "",
225
+ });
226
+ return { id: item.id, title: updated.title };
227
+ }
228
+ assertRegisterItemCommitTargetsClean(context, view);
229
+ applyItemUpdate({
230
+ paths,
231
+ view,
232
+ updated,
233
+ dryRun: opts.dryRun,
234
+ action: "fields updated",
235
+ ...(opts.title !== undefined ? { title: opts.title } : {}),
236
+ ...(opts.description !== undefined ? { description: opts.description } : {}),
237
+ ...(blockReasonUpdates ? { fieldUpdates: blockReasonUpdates } : {}),
238
+ eventAction: "update",
239
+ eventActor: registerEventActor(opts),
240
+ eventReason: opts.reason?.trim() || "fields updated",
241
+ });
242
+ return { id: item.id, title: updated.title };
243
+ });
244
+ });
245
+ }
@@ -0,0 +1,169 @@
1
+ // 統合 merge で登録簿の記帳ファイルが競合したときの解決処理。イベントファイルは追記型の記録なので、
2
+ // 両側のイベントの和集合(同一 id は 1 件)を時刻順に並べ、`previous_event_id` の連鎖を張り直す。
3
+ // 個票は exec branch 側を基準にし、統合先だけにあるイベントが変えたフィールドのうち、frontmatter の
4
+ // 単純な値へ写せるもの(type / priority / owner / due)だけをイベントから再構築する。
5
+ import { readRegisterEventsFromContent, serializeRegisterEvents, } from "./register-events.js";
6
+ import { applyRegisterItemFields, CELL_NONE, CELL_TODO, REMOVE_REGISTER_ITEM_FIELD, } from "./register-item.js";
7
+ function hasStatusChange(event) {
8
+ return event.changes.some((change) => change.field === "status");
9
+ }
10
+ // 両側とも古い順に並んでいる前提で、時刻順を保って 1 本にまとめる。同じ id は exec branch 側
11
+ // (theirs)の内容を採用して 1 件にする。同時刻の別イベントは、直前に出力したイベントを参照して
12
+ // いる側を優先し、判断できなければ統合先(ours)を先にする。
13
+ function interleaveEvents(ours, theirs) {
14
+ const theirsById = new Map(theirs.map((event) => [event.id, event]));
15
+ const emitted = new Set();
16
+ const merged = [];
17
+ let oursIndex = 0;
18
+ let theirsIndex = 0;
19
+ const emit = (event) => {
20
+ emitted.add(event.id);
21
+ merged.push(theirsById.get(event.id) ?? event);
22
+ };
23
+ while (oursIndex < ours.length || theirsIndex < theirs.length) {
24
+ const left = ours[oursIndex];
25
+ const right = theirs[theirsIndex];
26
+ if (left && emitted.has(left.id)) {
27
+ oursIndex += 1;
28
+ continue;
29
+ }
30
+ if (right && emitted.has(right.id)) {
31
+ theirsIndex += 1;
32
+ continue;
33
+ }
34
+ if (!left || !right) {
35
+ const next = left ?? right;
36
+ if (!next)
37
+ break;
38
+ emit(next);
39
+ if (left)
40
+ oursIndex += 1;
41
+ else
42
+ theirsIndex += 1;
43
+ continue;
44
+ }
45
+ if (left.id === right.id) {
46
+ emit(right);
47
+ oursIndex += 1;
48
+ theirsIndex += 1;
49
+ continue;
50
+ }
51
+ const lastId = merged.at(-1)?.id;
52
+ const takeRight = right.ts < left.ts ||
53
+ (right.ts === left.ts &&
54
+ right.previous_event_id === lastId &&
55
+ left.previous_event_id !== lastId);
56
+ if (takeRight) {
57
+ emit(right);
58
+ theirsIndex += 1;
59
+ }
60
+ else {
61
+ emit(left);
62
+ oursIndex += 1;
63
+ }
64
+ }
65
+ return merged;
66
+ }
67
+ // 和集合で並べたイベントの連鎖を張り直す。統合先だけにある状態を変えないイベント(`update` など)は、
68
+ // 並べ替え後の直前の状態を引き継ぐ。状態遷移の連続性が崩れる場合(統合先だけに状態遷移がある
69
+ // など)は、和集合では解決できないとして理由を返す。
70
+ function relinkEvents(events, oursOnlyIds, source) {
71
+ const relinked = [];
72
+ let previous;
73
+ for (const original of events) {
74
+ const event = { ...original };
75
+ delete event.previous_event_id;
76
+ if (previous) {
77
+ event.previous_event_id = previous.id;
78
+ if (oursOnlyIds.has(event.id) && !hasStatusChange(event)) {
79
+ event.from_status = previous.to_status;
80
+ event.to_status = previous.to_status;
81
+ }
82
+ if (event.from_status !== previous.to_status) {
83
+ return (`${source}: event ${event.id} starts at ${event.from_status ?? "null"} ` +
84
+ `but follows ${previous.to_status} after the union`);
85
+ }
86
+ }
87
+ else if (event.from_status !== null) {
88
+ return `${source}: first event ${event.id} after the union is not an add event`;
89
+ }
90
+ relinked.push(event);
91
+ previous = event;
92
+ }
93
+ return relinked;
94
+ }
95
+ // 統合先(ours)と exec branch(theirs)のイベントファイルを和集合で合わせる。
96
+ export function unionRegisterEventLogs(oursContent, theirsContent, source) {
97
+ let ours;
98
+ let theirs;
99
+ try {
100
+ ours = readRegisterEventsFromContent(oursContent, `${source} (ours)`);
101
+ theirs = readRegisterEventsFromContent(theirsContent, `${source} (theirs)`);
102
+ }
103
+ catch (error) {
104
+ return { ok: false, reason: error instanceof Error ? error.message : String(error) };
105
+ }
106
+ const theirsIds = new Set(theirs.map((event) => event.id));
107
+ const oursOnlyIds = new Set(ours.filter((event) => !theirsIds.has(event.id)).map((event) => event.id));
108
+ const relinked = relinkEvents(interleaveEvents(ours, theirs), oursOnlyIds, source);
109
+ if (typeof relinked === "string")
110
+ return { ok: false, reason: relinked };
111
+ return {
112
+ ok: true,
113
+ content: serializeRegisterEvents(relinked),
114
+ events: relinked,
115
+ oursOnlyIds,
116
+ };
117
+ }
118
+ // イベントの変更値を個票 frontmatter の値へ写す。本文(title / description)、状態遷移に伴う
119
+ // フィールド(status / block_reason / conclusion / completed)、表示用に暦日へ変換された
120
+ // registered は、イベントから元の値を復元できないため対象外とする。
121
+ function fieldUpdateFromChange(change) {
122
+ const value = change.to.trim();
123
+ const isUnset = value === "" || value === CELL_NONE || value === CELL_TODO;
124
+ switch (change.field) {
125
+ case "type":
126
+ return isUnset ? undefined : { item_type: value };
127
+ case "priority":
128
+ return isUnset ? undefined : { priority: value };
129
+ case "owner":
130
+ return { owner: isUnset ? null : value };
131
+ case "due":
132
+ return {
133
+ due_on: value === CELL_TODO
134
+ ? REMOVE_REGISTER_ITEM_FIELD
135
+ : value === CELL_NONE || value === ""
136
+ ? null
137
+ : value,
138
+ };
139
+ default:
140
+ return undefined;
141
+ }
142
+ }
143
+ // exec branch 側の個票へ、統合先だけにあるイベントの変更を反映する。同じフィールドを後から
144
+ // exec branch 側のイベントが変えている場合は、後の変更(exec branch 側)を残す。
145
+ export function rebuildRegisterTicketFromEvents(theirsTicketContent, events, oursOnlyIds) {
146
+ const lastWriter = new Map();
147
+ for (const event of events) {
148
+ for (const change of event.changes) {
149
+ lastWriter.set(change.field, { oursOnly: oursOnlyIds.has(event.id), change });
150
+ }
151
+ }
152
+ let updates = {};
153
+ const appliedFields = [];
154
+ for (const [field, writer] of lastWriter) {
155
+ if (!writer.oursOnly)
156
+ continue;
157
+ const update = fieldUpdateFromChange(writer.change);
158
+ if (!update)
159
+ continue;
160
+ updates = { ...updates, ...update };
161
+ appliedFields.push(field);
162
+ }
163
+ if (appliedFields.length === 0)
164
+ return { content: theirsTicketContent, appliedFields };
165
+ return {
166
+ content: applyRegisterItemFields(theirsTicketContent, updates),
167
+ appliedFields: appliedFields.sort(),
168
+ };
169
+ }
@@ -3,7 +3,7 @@
3
3
  import { createHash, randomUUID } from "node:crypto";
4
4
  import { existsSync, readdirSync, readFileSync } from "node:fs";
5
5
  import { join } from "node:path";
6
- import yaml from "js-yaml";
6
+ import { dump, load } from "./yaml.js";
7
7
  import { CELL_NONE, displayIdFromTicketFilename, readRegisterItemContent, readSpecdojoFields, toDisplayItem, updateSpecdojoFields, VALID_STATUSES, } from "./register-item.js";
8
8
  import { isUtcIsoSeconds, nowUtcIsoSeconds } from "./exec-shared.js";
9
9
  export const REGISTER_EVENTS_DIRNAME = "events";
@@ -188,7 +188,7 @@ export function validateRegisterEventShape(value, source) {
188
188
  export function readRegisterEventsFromContent(content, source) {
189
189
  let parsed;
190
190
  try {
191
- parsed = yaml.load(content);
191
+ parsed = load(content);
192
192
  }
193
193
  catch (error) {
194
194
  const detail = error instanceof Error ? error.message : String(error);
@@ -206,10 +206,10 @@ export function readRegisterEventsFromContent(content, source) {
206
206
  return events;
207
207
  }
208
208
  export function serializeRegisterEvents(events) {
209
- return `${REGISTER_EVENTS_SCHEMA_MODELINE}\n${yaml.dump([...events], {
209
+ return `${REGISTER_EVENTS_SCHEMA_MODELINE}\n${dump([...events], {
210
210
  lineWidth: -1,
211
211
  noRefs: true,
212
- quotingType: '"',
212
+ quoteStyle: "double",
213
213
  })}`;
214
214
  }
215
215
  export function appendRegisterEvent(content, event) {
@@ -5,7 +5,7 @@
5
5
  // 表示 ID・タイトル・説明は frontmatter に重複させず、`id` / H1 / 本文から導出する。
6
6
  import { existsSync, readdirSync, readFileSync } from "node:fs";
7
7
  import { join } from "node:path";
8
- import yaml from "js-yaml";
8
+ import { dump, load } from "./yaml.js";
9
9
  import { inlineCodeAnglePlaceholders } from "./exec-shared.js";
10
10
  import { registerDateFromTimestamp } from "./register-date.js";
11
11
  export const VALID_STATUSES = [
@@ -64,6 +64,7 @@ const SPECDOJO_KEY_ORDER = [
64
64
  "completed_at",
65
65
  "block_reason",
66
66
  "conclusion",
67
+ "targets",
67
68
  ];
68
69
  // ================================
69
70
  // Derivation helpers
@@ -147,7 +148,7 @@ export function readRegisterItemContent(content, filename) {
147
148
  if (match) {
148
149
  let parsed;
149
150
  try {
150
- parsed = yaml.load(match[1]);
151
+ parsed = load(match[1]);
151
152
  }
152
153
  catch {
153
154
  parsed = undefined;
@@ -155,6 +156,9 @@ export function readRegisterItemContent(content, filename) {
155
156
  if (isRecord(parsed) && isRecord(parsed.specdojo))
156
157
  fields = parsed.specdojo;
157
158
  }
159
+ const targets = Array.isArray(fields.targets)
160
+ ? fields.targets.filter((entry) => typeof entry === "string" && entry.trim() !== "")
161
+ : undefined;
158
162
  const item = {
159
163
  id,
160
164
  status: asString(fields.item_status) ?? "open",
@@ -171,6 +175,7 @@ export function readRegisterItemContent(content, filename) {
171
175
  completedAt: asString(fields.completed_at) ?? CELL_NONE,
172
176
  conclusion: asString(fields.conclusion) ?? CELL_NONE,
173
177
  ticket: ticketRefCell(filename),
178
+ ...(targets && targets.length > 0 ? { targets } : {}),
174
179
  };
175
180
  return {
176
181
  id,
@@ -239,7 +244,7 @@ export function validateRegisterItemDocs(projectRegisterPath) {
239
244
  let frontmatterId;
240
245
  if (match) {
241
246
  try {
242
- const parsed = yaml.load(match[1]);
247
+ const parsed = load(match[1]);
243
248
  if (isRecord(parsed) && isRecord(parsed.specdojo)) {
244
249
  frontmatterId = asString(parsed.specdojo.id);
245
250
  }
@@ -318,7 +323,7 @@ export function updateSpecdojoFields(content, mutate) {
318
323
  const fields = { ...parsed.specdojo };
319
324
  mutate(fields);
320
325
  const document = { ...parsed, specdojo: orderSpecdojoKeys(fields) };
321
- const dumped = yaml.dump(document, { lineWidth: -1, noRefs: true, quotingType: '"' });
326
+ const dumped = dump(document, { lineWidth: -1, noRefs: true, quoteStyle: "double" });
322
327
  return `---\n${dumped}---\n${match[2] ?? ""}`;
323
328
  }
324
329
  // 個票 frontmatter の `specdojo:` 名前空間を、イベント検証などの読み取り用途へ返す。
@@ -337,7 +342,7 @@ export function readSpecdojoFields(content) {
337
342
  function parseFrontmatterDocument(frontmatter) {
338
343
  let parsed;
339
344
  try {
340
- parsed = yaml.load(frontmatter);
345
+ parsed = load(frontmatter);
341
346
  }
342
347
  catch (error) {
343
348
  const detail = error instanceof Error ? error.message : String(error);
@@ -371,7 +376,7 @@ export function readRegisterItemLegacyDates(content) {
371
376
  return {};
372
377
  let parsed;
373
378
  try {
374
- parsed = yaml.load(match[1]);
379
+ parsed = load(match[1]);
375
380
  }
376
381
  catch {
377
382
  return {};
@@ -402,7 +407,8 @@ export function setRegisterItemTitle(content, title) {
402
407
  throw new Error("H1 heading not found in register item file");
403
408
  }
404
409
  const idPrefix = heading[1].match(/^(PJR-[0-9A-Za-z]{4})\s+/);
405
- const replacement = idPrefix ? `# ${idPrefix[1]} ${title}` : `# ${title}`;
410
+ const safeTitle = inlineCodeAnglePlaceholders(title);
411
+ const replacement = idPrefix ? `# ${idPrefix[1]} ${safeTitle}` : `# ${safeTitle}`;
406
412
  return content.replace(/^#\s+.+$/m, () => replacement);
407
413
  }
408
414
  // 説明の導出元(最初の `##` 見出し直後の段落)を差し替える。段落が無い場合は見出し直後へ挿入する。