specdojo 0.2.0 → 0.3.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 (170) hide show
  1. package/.github/agents/specdojo-orchestrator.md +165 -0
  2. package/CHANGELOG.md +280 -0
  3. package/README.md +143 -30
  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/dashboard.js +140 -9
  8. package/dist/devcontainer-command.js +43 -0
  9. package/dist/devcontainer-scaffold.js +165 -0
  10. package/dist/exec-agent-config.js +107 -9
  11. package/dist/exec-agent-git-state.js +18 -0
  12. package/dist/exec-agent-protected-config.js +46 -8
  13. package/dist/exec-evidence.js +254 -11
  14. package/dist/exec-format.js +13 -4
  15. package/dist/exec-handoff.js +336 -0
  16. package/dist/exec-parent-validation.js +317 -43
  17. package/dist/exec-pipeline-state.js +74 -9
  18. package/dist/exec-plans.js +115 -113
  19. package/dist/exec-protection-handoff.js +43 -2
  20. package/dist/exec-provider-scaffold.js +247 -15
  21. package/dist/exec-register-resume.js +65 -19
  22. package/dist/exec-register.js +9 -3
  23. package/dist/exec-repo-integration.js +811 -0
  24. package/dist/exec-repo-trace.js +182 -0
  25. package/dist/exec-reporter.js +613 -132
  26. package/dist/exec-results.js +81 -56
  27. package/dist/exec-run-lock.js +110 -107
  28. package/dist/exec-run.js +1585 -356
  29. package/dist/exec-shared.js +7 -0
  30. package/dist/exec-slot-lock.js +242 -0
  31. package/dist/exec-task-repos.js +415 -0
  32. package/dist/exec-trial.js +51 -25
  33. package/dist/exec-worktree-command.js +87 -43
  34. package/dist/exec-worktree-ops.js +502 -57
  35. package/dist/exec-worktree.js +114 -27
  36. package/dist/exec.js +13 -6
  37. package/dist/grade-result.js +128 -0
  38. package/dist/grade.js +809 -72
  39. package/dist/init-command.js +443 -0
  40. package/dist/job.js +160 -10
  41. package/dist/orchestrator.js +213 -0
  42. package/dist/package-paths.js +19 -1
  43. package/dist/register-event-merge.js +169 -0
  44. package/dist/register-item.js +7 -1
  45. package/dist/register.js +294 -86
  46. package/dist/review-grade.js +252 -0
  47. package/dist/review-plan.js +111 -1
  48. package/dist/review-types.js +40 -1
  49. package/dist/routine.js +72 -5
  50. package/dist/schedule-build.js +2 -2
  51. package/dist/schedule.js +17 -4
  52. package/dist/specdojo-config.js +466 -20
  53. package/dist/specdojo-gitignore.js +135 -0
  54. package/dist/specdojo.js +8 -1
  55. package/dist/viewpoint-document-kinds-check.js +128 -0
  56. package/docs/ja/specdojo/defaults/pm-review-viewpoints.yaml +348 -90
  57. package/docs/ja/specdojo/exec-templates/xep-common-conventions-template.md +51 -17
  58. package/docs/ja/specdojo/exec-templates/xep-fully-guided-template.md +7 -5
  59. package/docs/ja/specdojo/exec-templates/xrp-freeform-template.md +29 -31
  60. package/docs/ja/specdojo/exec-templates/xrp-fully-guided-template.md +34 -55
  61. package/docs/ja/specdojo/exec-templates/xrp-job-template.md +54 -0
  62. package/docs/ja/specdojo/exec-templates/xrp-recipe-guided-template.md +28 -37
  63. package/docs/ja/specdojo/exec-templates/xrp-recipe-maintenance-template.md +29 -34
  64. package/docs/ja/specdojo/exec-templates/xrp-retrofit-template.md +30 -30
  65. package/docs/ja/specdojo/exec-templates/xrp-rulebook-maintenance-template.md +29 -34
  66. package/docs/ja/specdojo/exec-templates/xrp-sample-maintenance-template.md +29 -34
  67. package/docs/ja/specdojo/exec-templates/xrp-template-maintenance-template.md +29 -34
  68. package/docs/ja/specdojo/exec-templates/xrp-template.md +29 -28
  69. package/docs/ja/specdojo/exec-templates/xrr-template.md +11 -9
  70. package/docs/ja/specdojo/guides/docs-editing-guide.md +20 -0
  71. package/docs/ja/specdojo/guides/docs-structure-guide.md +103 -70
  72. package/docs/ja/specdojo/guides/exec-config-guide.md +91 -47
  73. package/docs/ja/specdojo/guides/exec-operation-guide.md +124 -27
  74. package/docs/ja/specdojo/guides/exec-worktree-guide.md +40 -11
  75. package/docs/ja/specdojo/guides/kata-guide.md +4 -4
  76. package/docs/ja/specdojo/guides/orchestrator-operation-guide.md +25 -4
  77. package/docs/ja/specdojo/guides/plan-result-lifecycle-guide.md +1 -1
  78. package/docs/ja/specdojo/guides/practice-system-composition-guide.md +13 -13
  79. package/docs/ja/specdojo/guides/quick-start-guide.md +261 -32
  80. package/docs/ja/specdojo/guides/register-operation-guide.md +31 -14
  81. package/docs/ja/specdojo/guides/release-v0-3-0-migration-guide.md +264 -0
  82. package/docs/ja/specdojo/guides/remote-host-development-guide.md +184 -0
  83. package/docs/ja/specdojo/guides/review-guide.md +195 -158
  84. package/docs/ja/specdojo/guides/routine-operation-guide.md +74 -9
  85. package/docs/ja/specdojo/guides/ryu-guide.md +32 -30
  86. package/docs/ja/specdojo/guides/schedule-design-guide.md +10 -10
  87. package/docs/ja/specdojo/guides/schedule-operation-guide.md +1 -1
  88. package/docs/ja/specdojo/guides/specdojo-overview-guide.md +58 -33
  89. package/docs/ja/specdojo/guides/use-case-guide.md +3 -3
  90. package/docs/ja/specdojo/guides/waza-guide.md +15 -2
  91. package/docs/ja/specdojo/index.md +2 -2
  92. package/docs/ja/specdojo/philosophy/specdojo-philosophy.md +5 -5
  93. package/docs/ja/specdojo/recipes/bps-recipe.md +213 -0
  94. package/docs/ja/specdojo/recipes/pm-members-recipe.md +52 -117
  95. package/docs/ja/specdojo/references/command-reference.md +336 -93
  96. package/docs/ja/specdojo/references/deliverables-reference.md +1 -1
  97. package/docs/ja/specdojo/references/directory-layout-reference.md +13 -9
  98. package/docs/ja/specdojo/references/specdojo-config-reference.md +107 -24
  99. package/docs/ja/specdojo/rulebooks/bps-rulebook.md +132 -220
  100. package/docs/ja/specdojo/rulebooks/br-rulebook.md +6 -44
  101. package/docs/ja/specdojo/rulebooks/cdfd-rulebook.md +2 -0
  102. package/docs/ja/specdojo/rulebooks/dmd-rulebook.md +0 -87
  103. package/docs/ja/specdojo/rulebooks/gl-rulebook.md +61 -39
  104. package/docs/ja/specdojo/rulebooks/ifx-cmd-rulebook.md +0 -87
  105. package/docs/ja/specdojo/rulebooks/ifx-index-rulebook.md +1 -33
  106. package/docs/ja/specdojo/rulebooks/opd-rulebook.md +0 -137
  107. package/docs/ja/specdojo/rulebooks/opr-rulebook.md +0 -247
  108. package/docs/ja/specdojo/rulebooks/otp-rulebook.md +0 -83
  109. package/docs/ja/specdojo/rulebooks/pjr-rulebook.md +4 -2
  110. package/docs/ja/specdojo/rulebooks/pm-members-rulebook.md +78 -150
  111. package/docs/ja/specdojo/rulebooks/pm-roles-rulebook.md +5 -4
  112. package/docs/ja/specdojo/rulebooks/sch-rulebook.md +1 -1
  113. package/docs/ja/specdojo/rulebooks/stsd-mermaid-rulebook.md +0 -11
  114. package/docs/ja/specdojo/rulebooks/stsd-rulebook.md +0 -61
  115. package/docs/ja/specdojo/rulebooks/tml-rulebook.md +2 -47
  116. package/docs/ja/specdojo/samples/bps-sample.md +74 -21
  117. package/docs/ja/specdojo/samples/gl-sample.yaml +17 -1
  118. package/docs/ja/specdojo/samples/ifx-index-sample.yaml +28 -0
  119. package/docs/ja/specdojo/samples/pm-members-sample.yaml +2 -67
  120. package/docs/ja/specdojo/samples/pm-organization-sample.md +8 -7
  121. package/docs/ja/specdojo/samples/pm-raci-sample.md +1 -1
  122. package/docs/ja/specdojo/samples/tml-sample.yaml +40 -0
  123. package/docs/ja/specdojo/standards/document-metadata-standard.md +21 -16
  124. package/docs/ja/specdojo/standards/id-and-file-naming-standard.md +14 -14
  125. package/docs/ja/specdojo/standards/job-definition-standard.md +37 -17
  126. package/docs/ja/specdojo/standards/people-and-organization-definition-standard.md +37 -32
  127. package/docs/ja/specdojo/standards/philosophy-authoring-standard.md +1 -1
  128. package/docs/ja/specdojo/standards/rulebook-authoring-standard.md +21 -11
  129. package/docs/ja/specdojo/templates/agent-members-template.yaml +25 -0
  130. package/docs/ja/specdojo/templates/bps-template.md +91 -0
  131. package/docs/ja/specdojo/templates/pm-members-template.yaml +2 -59
  132. package/docs/specdojo/schemas/v1/agent-members.schema.yaml +76 -0
  133. package/docs/specdojo/schemas/v1/exec-common.schema.yaml +4 -2
  134. package/docs/specdojo/schemas/v1/exec-defaults.schema.yaml +55 -2
  135. package/docs/specdojo/schemas/v1/exec-evidence.schema.yaml +93 -6
  136. package/docs/specdojo/schemas/v1/exec-reporter-output.schema.yaml +27 -78
  137. package/docs/specdojo/schemas/v1/gl.schema.yaml +87 -0
  138. package/docs/specdojo/schemas/v1/grade-result.schema.yaml +33 -0
  139. package/docs/specdojo/schemas/v1/job-run.schema.yaml +27 -0
  140. package/docs/specdojo/schemas/v1/job.schema.yaml +25 -0
  141. package/docs/specdojo/schemas/v1/pipeline-state.schema.yaml +49 -1
  142. package/docs/specdojo/schemas/v1/pm-members.schema.yaml +9 -169
  143. package/docs/specdojo/schemas/v1/pm-review-viewpoints.schema.yaml +100 -10
  144. package/docs/specdojo/schemas/v1/register-item-frontmatter.schema.yaml +13 -0
  145. package/docs/specdojo/schemas/v1/routine-run.schema.yaml +3 -0
  146. package/docs/specdojo/schemas/v1/routine.schema.yaml +7 -0
  147. package/docs/specdojo/schemas/v1/specdojo-config.schema.yaml +110 -0
  148. package/package.json +16 -9
  149. package/templates/antigravity/README.md +60 -0
  150. package/templates/antigravity/agent-members-snippet.yaml +61 -0
  151. package/templates/antigravity/exec-defaults-snippet.yaml +39 -0
  152. package/templates/antigravity/orchestrator.md +157 -0
  153. package/templates/antigravity/settings.global.json +55 -0
  154. package/templates/claude/agents/claude-executor.md +14 -0
  155. package/templates/claude/agents/claude-reporter.md +16 -0
  156. package/templates/claude/agents/specdojo-orchestrator.md +164 -0
  157. package/templates/claude/settings.edit.json +27 -1
  158. package/templates/codex/README.md +5 -4
  159. package/templates/codex/agents/specdojo-orchestrator.toml +165 -0
  160. package/templates/codex/orchestrator.md +157 -0
  161. package/templates/copilot/README.md +7 -5
  162. package/templates/copilot/{pm-members-snippet.yaml → agent-members-snippet.yaml} +4 -2
  163. package/templates/devcontainer/devcontainer.json +27 -0
  164. package/templates/devcontainer/emacs/init.el +88 -0
  165. package/templates/devcontainer/post-create.sh +62 -0
  166. package/templates/init-agent-members.yaml +200 -0
  167. package/templates/init-exec-defaults.yaml +72 -0
  168. package/templates/opencode/agents/specdojo-orchestrator.md +204 -0
  169. package/docs/ja/specdojo/exec-templates/xrp-viewpoint-detail-template.md +0 -7
  170. package/docs/ja/specdojo/exec-templates/xrr-viewpoint-detail-template.md +0 -7
package/dist/register.js CHANGED
@@ -1,8 +1,11 @@
1
1
  import { randomInt, randomUUID } from "node:crypto";
2
- import { existsSync, mkdirSync, readFileSync, renameSync, unlinkSync, writeFileSync, } from "node:fs";
2
+ import { existsSync, mkdirSync, readdirSync, readFileSync, renameSync, unlinkSync, writeFileSync, } from "node:fs";
3
3
  import { basename, dirname, join, relative, resolve, sep } from "node:path";
4
- import fg from "fast-glob";
5
- import { getProjectRegisterPath, loadConfig, loadEnv, specdojoRootDir } from "./specdojo-config.js";
4
+ import { getProjectExecutionPath, getProjectRegisterPath, loadConfig, loadEnv, specdojoRootDir, } from "./specdojo-config.js";
5
+ import { execLifecyclePoolPath } from "./exec-run-lock.js";
6
+ import { CrossProcessMutex } from "./exec-slot-lock.js";
7
+ import { repoRelative, stageCommitTargets, worktreeStatusPaths } from "./exec-worktree-ops.js";
8
+ import { gitOutput, gitResult } from "./exec-worktree.js";
6
9
  import { normalizeRegisterTimestamp, nowUtcTimestamp, REGISTER_TIMESTAMP_RE, resolveRegisterDateTimeZone, timestampFromDateInTimeZone, } from "./register-date.js";
7
10
  import { inlineCodeAnglePlaceholders } from "./exec-shared.js";
8
11
  import { createGitTimestampResolver, planRegisterTimestampMigration, summarizeTimestampMigration, } from "./register-migrate-timestamps.js";
@@ -11,7 +14,7 @@ import { parseSpecdojoDocument } from "./frontmatter-namespace.js";
11
14
  import { resolveSpecdojoTemplatePath } from "./template-resolution.js";
12
15
  import { collectRegisterHistoryEvents, formatRegisterHistoryEvents } from "./register-history.js";
13
16
  import { appendRegisterEvent, buildRegisterEvent, deterministicRegisterEventId, readEmbeddedRegisterEvents, readRegisterEventsFromContent, registerEventFilePath, removeEmbeddedRegisterEvents, serializeRegisterEvents, validateRegisterEventDocs, } from "./register-events.js";
14
- import { applyRegisterItemFields, CELL_NONE, CELL_TODO, compareRegisterItemIds, formatRegisterItemFields, isPlaceholderCell, loadRegisterItemDocs, PJR_ID_ALPHABET, PJR_ID_RE, prependRegisterItemDescription, readRegisterItemContent, registerItemFieldsFromItem, setRegisterItemDescription, setRegisterItemTitle, TERMINAL_STATUSES_SET, ticketRefCell, toDisplayItem, validateRegisterItemDocs, VALID_PRIORITIES, VALID_STATUSES, VALID_TYPES, } from "./register-item.js";
17
+ import { applyRegisterItemFields, CELL_NONE, CELL_TODO, compareRegisterItemIds, formatRegisterItemFields, isPlaceholderCell, loadRegisterItemDocs, PJR_ID_ALPHABET, PJR_ID_RE, prependRegisterItemDescription, readRegisterItemContent, REMOVE_REGISTER_ITEM_FIELD, registerItemFieldsFromItem, setRegisterItemDescription, setRegisterItemTitle, TERMINAL_STATUSES_SET, ticketRefCell, toDisplayItem, validateRegisterItemDocs, VALID_PRIORITIES, VALID_STATUSES, VALID_TYPES, } from "./register-item.js";
15
18
  // 登録項目の型・enum・ID 書式は register-item.ts が正本。従来どおり register.js からも
16
19
  // 参照できるよう再輸出する。
17
20
  export { PJR_ID_ALPHABET, PJR_ID_RE, TERMINAL_STATUSES_SET, VALID_PRIORITIES, VALID_STATUSES, VALID_TYPES, };
@@ -30,6 +33,27 @@ function atomicWriteFile(path, content) {
30
33
  unlinkSync(temporary);
31
34
  }
32
35
  }
36
+ export function findMarkdownReferenceFiles(root) {
37
+ const markdownFiles = [];
38
+ const docsJaPath = join(resolve(root), "docs", "ja");
39
+ function walk(directory) {
40
+ for (const entry of readdirSync(directory, { withFileTypes: true })) {
41
+ if (entry.name.startsWith("."))
42
+ continue;
43
+ const entryPath = join(directory, entry.name);
44
+ if (entry.isDirectory()) {
45
+ if (entry.name !== "generated")
46
+ walk(entryPath);
47
+ }
48
+ else if (entry.isFile() && entry.name.endsWith(".md")) {
49
+ markdownFiles.push(entryPath);
50
+ }
51
+ }
52
+ }
53
+ if (existsSync(docsJaPath))
54
+ walk(docsJaPath);
55
+ return markdownFiles.sort((left, right) => left.localeCompare(right));
56
+ }
33
57
  function prepareRegisterEventFile(projectRegisterPath, displayId, event) {
34
58
  const eventPath = registerEventFilePath(projectRegisterPath, displayId);
35
59
  const content = existsSync(eventPath) ? readFileSync(eventPath, "utf8") : undefined;
@@ -84,6 +108,7 @@ export function resolveRegisterPaths(opts) {
84
108
  return {
85
109
  projectId,
86
110
  projectRegisterPath: absRegisterPath,
111
+ executionPath: resolve(baseDir, getProjectExecutionPath(project)),
87
112
  pjrIndexPath: join(absRegisterPath, "pjr-index.md"),
88
113
  generatedPath: join(absRegisterPath, "generated"),
89
114
  controlsGeneratedPath: join(dirname(absRegisterPath), "generated"),
@@ -275,6 +300,24 @@ function slugify(text) {
275
300
  .replace(/-+/g, "-")
276
301
  .replace(/^-|-$/g, "") || "item");
277
302
  }
303
+ // 日本語主体のタイトルから ASCII の断片だけを topic にすると、個票名から内容を
304
+ // 推測できなくなる。区切り記号は数えず、文字・数字の過半が非 ASCII で、抽出できた
305
+ // ASCII 語が 1 語だけの場合を「意味を失う可能性がある既定 topic」とみなす。
306
+ function derivedTopicNeedsWarning(title, topic) {
307
+ const asciiWords = title.match(/[a-z0-9]+/giu) ?? [];
308
+ if (topic === "item" && asciiWords.length === 0)
309
+ return true;
310
+ if (asciiWords.length !== 1)
311
+ return false;
312
+ const lettersAndNumbers = [...title].filter((char) => /[\p{L}\p{N}]/u.test(char));
313
+ const asciiCount = lettersAndNumbers.filter((char) => /[a-z0-9]/iu.test(char)).length;
314
+ return lettersAndNumbers.length - asciiCount > asciiCount;
315
+ }
316
+ function printDerivedTopicWarning(topic) {
317
+ process.stdout.write(`Warning: derived topic "${topic}" may not describe the title. ` +
318
+ "Specify --topic with a lowercase, hyphen-separated English slug, or change it later " +
319
+ "with register update --topic.\n");
320
+ }
278
321
  // ================================
279
322
  // Ticket Generation
280
323
  // ================================
@@ -296,7 +339,8 @@ function generateTicket(opts) {
296
339
  content = content.replace(/_PJR-XXXX_/g, opts.displayId);
297
340
  // Replace type-specific title placeholder
298
341
  const titlePh = getTitlePlaceholder(opts.type);
299
- content = content.replace(new RegExp(titlePh.replace(/[.*+?^${}()|[\]\\]/g, "\\$&"), "g"), opts.title);
342
+ const safeTitle = inlineCodeAnglePlaceholders(opts.title);
343
+ content = content.replace(new RegExp(titlePh.replace(/[.*+?^${}()|[\]\\]/g, "\\$&"), "g"), safeTitle);
300
344
  return content;
301
345
  }
302
346
  // 個票の完成形(テンプレート展開 + 説明の反映 + 登録項目 frontmatter)を組み立てる。
@@ -861,6 +905,15 @@ function loadItemForUpdate(paths, id, guard) {
861
905
  }
862
906
  return view;
863
907
  }
908
+ // note は未対応項目ではなく、open のまま更新し続ける記録である。終端操作による書き込みを
909
+ // 始める前に共通ガードを通し、対応・回答・判断が必要な場合は別項目の起票へ誘導する。
910
+ function assertTerminalOperationAllowed(item, command) {
911
+ if (item.type !== "note")
912
+ return;
913
+ throw new Error(`Cannot ${command} ${item.id}: item type "note" is non-terminal and must remain open. ` +
914
+ `Create a todo, question, decision, or another appropriate item type when action, ` +
915
+ `an answer, or a decision is required.`);
916
+ }
864
917
  // 更新後の項目値を個票 frontmatter へ書き戻す。未移行(source: index)の項目は、
865
918
  // 行から読んだ値も含めて全フィールドを書き込み、その場で個票正本へ移行する。
866
919
  // タイトル・説明は frontmatter に持たないため、H1 と概要段落を書き換える。
@@ -872,6 +925,9 @@ function applyItemUpdate(opts) {
872
925
  const label = opts.action ?? `→ ${opts.updated.status}`;
873
926
  const updates = {
874
927
  ...registerItemFieldsFromItem(opts.updated),
928
+ // block_reason は waiting の現在値にだけ属する。waiting 以外への遷移や、
929
+ // stale な個票に対する更新では削除し、削除前の値は event の差分へ残す。
930
+ ...(opts.updated.status === "waiting" ? {} : { block_reason: REMOVE_REGISTER_ITEM_FIELD }),
875
931
  ...opts.fieldUpdates,
876
932
  };
877
933
  if (opts.dryRun) {
@@ -1146,9 +1202,7 @@ export function planRetopic(paths, id, topic) {
1146
1202
  },
1147
1203
  ];
1148
1204
  const root = specdojoRootDir();
1149
- const referenceFiles = fg
1150
- .sync("docs/ja/**/*.md", { cwd: root, absolute: true, ignore: ["**/generated/**"] })
1151
- .sort((a, b) => a.localeCompare(b));
1205
+ const referenceFiles = findMarkdownReferenceFiles(root);
1152
1206
  for (const absPath of referenceFiles) {
1153
1207
  if (absPath === view.ticketPath)
1154
1208
  continue;
@@ -1181,7 +1235,11 @@ export function retopicPjrItem(opts) {
1181
1235
  if (opts.description !== undefined) {
1182
1236
  ticketWrite.content = setRegisterItemDescription(ticketWrite.content, opts.description);
1183
1237
  }
1184
- ticketWrite.content = applyRegisterItemFields(ticketWrite.content, registerItemFieldsFromItem(opts.updated));
1238
+ ticketWrite.content = applyRegisterItemFields(ticketWrite.content, {
1239
+ ...registerItemFieldsFromItem(opts.updated),
1240
+ ...(opts.updated.status === "waiting" ? {} : { block_reason: REMOVE_REGISTER_ITEM_FIELD }),
1241
+ ...opts.fieldUpdates,
1242
+ });
1185
1243
  if (opts.dryRun) {
1186
1244
  process.stdout.write(`Would change topic for ${opts.id}: ${plan.fromTopic} → ${opts.topic}\n`);
1187
1245
  process.stdout.write(` Rename: ${plan.ticketRename.from} → ${plan.ticketRename.to}\n`);
@@ -1274,9 +1332,7 @@ export function planRenumber(paths, fromId, toId) {
1274
1332
  // 参照リンク・targets の付け替え(doc id を持つ個票がある場合のみ)。
1275
1333
  if (fromDocId && toDocId) {
1276
1334
  const root = specdojoRootDir();
1277
- const referenceFiles = fg
1278
- .sync("docs/ja/**/*.md", { cwd: root, absolute: true, ignore: ["**/generated/**"] })
1279
- .sort((a, b) => a.localeCompare(b));
1335
+ const referenceFiles = findMarkdownReferenceFiles(root);
1280
1336
  for (const absPath of referenceFiles) {
1281
1337
  if (absPath === paths.pjrIndexPath)
1282
1338
  continue;
@@ -1386,6 +1442,117 @@ export function printCommandError(error) {
1386
1442
  function addProjectOption(cmd) {
1387
1443
  return cmd.option("--project <projectId>", "Project id in specdojo.config.json");
1388
1444
  }
1445
+ function assertRegisterItemCommitTargetsClean(context, view) {
1446
+ if (!view.ticketPath)
1447
+ return;
1448
+ context.assertCommitTargetsClean([
1449
+ view.ticketPath,
1450
+ registerEventFilePath(context.paths.projectRegisterPath, view.id),
1451
+ ]);
1452
+ }
1453
+ function addRegisterCommitOptions(cmd) {
1454
+ return cmd
1455
+ .option("--commit", "Take the register lifecycle lock, rebuild views, and commit only this command's changes", false)
1456
+ .option("-m, --message <message>", "Override the register commit message");
1457
+ }
1458
+ const REGISTER_COMMIT_SUBJECT_MAX_LENGTH = 100;
1459
+ const REGISTER_COMMIT_STABILIZATION_ATTEMPTS = 3;
1460
+ function defaultRegisterCommitMessage(command, result) {
1461
+ const prefix = `docs(register ${result.id}): ${command} `;
1462
+ const flatTitle = result.title.replace(/\s+/g, " ").trim();
1463
+ const subject = `${prefix}${flatTitle}`;
1464
+ if (subject.length <= REGISTER_COMMIT_SUBJECT_MAX_LENGTH)
1465
+ return subject;
1466
+ return `${subject.slice(0, REGISTER_COMMIT_SUBJECT_MAX_LENGTH - 1)}…`;
1467
+ }
1468
+ function rebuildRegisterViews(paths) {
1469
+ const validation = validateRegisterItemDocs(paths.projectRegisterPath);
1470
+ const eventErrors = validateRegisterEventDocs(paths.projectRegisterPath, paths.registerDateTimeZone);
1471
+ if (validation.errors.length > 0 || eventErrors.length > 0) {
1472
+ throw new Error(`Invalid register item files:\n${[...validation.errors, ...eventErrors].join("\n")}`);
1473
+ }
1474
+ writeDerivedViews(paths, "all");
1475
+ }
1476
+ function isGeneratedRegisterPath(repoRoot, paths, path) {
1477
+ const normalized = path.replaceAll("\\", "/");
1478
+ const generatedPrefixes = [paths.generatedPath, paths.controlsGeneratedPath].map((target) => `${repoRelative(repoRoot, target)}/`);
1479
+ return (normalized === ".specdojo/doc-index.json" ||
1480
+ generatedPrefixes.some((prefix) => normalized.startsWith(prefix)));
1481
+ }
1482
+ function commitRegisterMutation(repoRoot, paths, command, result, preexisting, message) {
1483
+ const changed = worktreeStatusPaths(repoRoot).filter((path) => !preexisting.has(path) && !isGeneratedRegisterPath(repoRoot, paths, path));
1484
+ if (changed.length === 0) {
1485
+ process.stdout.write(`No register changes to commit for ${result.id}.\n`);
1486
+ return;
1487
+ }
1488
+ stageCommitTargets(repoRoot, changed);
1489
+ const staged = gitResult(repoRoot, ["diff", "--cached", "--quiet", "--", ...changed]);
1490
+ if (staged.status === 0) {
1491
+ process.stdout.write(`No register changes to commit for ${result.id}.\n`);
1492
+ return;
1493
+ }
1494
+ if (staged.status !== 1)
1495
+ throw new Error("Failed to inspect staged register changes.");
1496
+ const commitMessage = message?.trim() || defaultRegisterCommitMessage(command, result);
1497
+ if (commitMessage === "")
1498
+ throw new Error("Register commit message must not be empty");
1499
+ gitOutput(repoRoot, ["commit", "-m", commitMessage, "--", ...changed]);
1500
+ for (let attempt = 0; attempt < REGISTER_COMMIT_STABILIZATION_ATTEMPTS; attempt++) {
1501
+ const remaining = worktreeStatusPaths(repoRoot).filter((path) => changed.includes(path));
1502
+ if (remaining.length === 0) {
1503
+ const sha = gitOutput(repoRoot, ["rev-parse", "--short", "HEAD"]).trim();
1504
+ process.stdout.write(`Committed: ${sha} (${result.id})\n`);
1505
+ return;
1506
+ }
1507
+ stageCommitTargets(repoRoot, remaining);
1508
+ gitOutput(repoRoot, ["commit", "--amend", "--no-edit", "--", ...remaining]);
1509
+ }
1510
+ const remaining = worktreeStatusPaths(repoRoot).filter((path) => changed.includes(path));
1511
+ if (remaining.length === 0) {
1512
+ const sha = gitOutput(repoRoot, ["rev-parse", "--short", "HEAD"]).trim();
1513
+ process.stdout.write(`Committed: ${sha} (${result.id})\n`);
1514
+ return;
1515
+ }
1516
+ throw new Error(`Register commit incomplete: target paths remained dirty after hook stabilization:\n` +
1517
+ remaining.map((path) => ` ${path}`).join("\n"));
1518
+ }
1519
+ async function runRegisterMutation(command, opts, mutate) {
1520
+ try {
1521
+ const paths = resolveRegisterPaths(opts);
1522
+ if (!opts.commit || opts.dryRun) {
1523
+ mutate({ paths, assertCommitTargetsClean: () => undefined });
1524
+ return;
1525
+ }
1526
+ const repoRoot = specdojoRootDir();
1527
+ if (!paths.executionPath) {
1528
+ throw new Error(`Execution path is not configured for project ${paths.projectId}`);
1529
+ }
1530
+ const mutex = new CrossProcessMutex(execLifecyclePoolPath(paths.executionPath), {
1531
+ actor: registerEventActor(opts),
1532
+ label: `register ${command}`,
1533
+ }, {
1534
+ onWait: () => process.stdout.write("Waiting for the register lifecycle lock held by another operation\n"),
1535
+ });
1536
+ await mutex.runExclusive(() => {
1537
+ const preexisting = new Set(worktreeStatusPaths(repoRoot));
1538
+ const assertCommitTargetsClean = (targets) => {
1539
+ const overlapping = targets
1540
+ .map((target) => repoRelative(repoRoot, target))
1541
+ .filter((target) => preexisting.has(target));
1542
+ if (overlapping.length === 0)
1543
+ return;
1544
+ throw new Error(`Cannot use --commit because register targets already have uncommitted changes:\n` +
1545
+ overlapping.map((path) => ` ${path}`).join("\n"));
1546
+ };
1547
+ const result = mutate({ paths, assertCommitTargetsClean });
1548
+ rebuildRegisterViews(paths);
1549
+ commitRegisterMutation(repoRoot, paths, command, result, preexisting, opts.message);
1550
+ });
1551
+ }
1552
+ catch (error) {
1553
+ printCommandError(error);
1554
+ }
1555
+ }
1389
1556
  // CLI で明示された日時オプションを UTC の秒精度へ正規化する。未指定は undefined を返し、
1390
1557
  // 呼び出し側の既定値(実行時刻・プレースホルダ)へ委ねる。
1391
1558
  function parseRegisterTimestampOption(value, label, placeholder) {
@@ -1621,10 +1788,12 @@ export function registerRegisterCommands(program) {
1621
1788
  addCmd.option("--reason <text>", "Reason recorded in the append-only register event");
1622
1789
  addCmd.option("--force", "Overwrite existing ticket file", false);
1623
1790
  addCmd.option("--dry-run", "Print the generated item file without writing", false);
1624
- addCmd.action((opts) => {
1625
- try {
1626
- const paths = resolveRegisterPaths(opts);
1627
- const topic = opts.topic?.trim() || slugify(opts.title);
1791
+ addRegisterCommitOptions(addCmd);
1792
+ addCmd.action(async (opts) => {
1793
+ await runRegisterMutation("add", opts, ({ paths, assertCommitTargetsClean }) => {
1794
+ const explicitTopic = opts.topic?.trim();
1795
+ const topic = explicitTopic || slugify(opts.title);
1796
+ const warnAboutDerivedTopic = explicitTopic === undefined && derivedTopicNeedsWarning(opts.title, topic);
1628
1797
  if (!REGISTER_TOPIC_RE.test(topic)) {
1629
1798
  throw new Error(`Invalid topic: "${topic}". Must use lowercase letters, numbers, and single hyphens`);
1630
1799
  }
@@ -1673,12 +1842,15 @@ export function registerRegisterCommands(program) {
1673
1842
  process.stdout.write(`Would create ${ticketPath}:\n${content}\n`);
1674
1843
  process.stdout.write(`Would create ${registerEventFilePath(paths.projectRegisterPath, displayId)}:\n` +
1675
1844
  `${appendRegisterEvent(undefined, addEvent)}\n`);
1676
- return;
1845
+ if (warnAboutDerivedTopic)
1846
+ printDerivedTopicWarning(topic);
1847
+ return { id: displayId, title: opts.title };
1677
1848
  }
1678
1849
  if (!opts.force && existsSync(ticketPath)) {
1679
1850
  throw new Error(`Item file already exists (use --force to overwrite): ${ticketPath}`);
1680
1851
  }
1681
1852
  const eventPath = registerEventFilePath(paths.projectRegisterPath, displayId);
1853
+ assertCommitTargetsClean([ticketPath, eventPath]);
1682
1854
  if (!opts.force && existsSync(eventPath)) {
1683
1855
  throw new Error(`Register event file already exists (use --force to overwrite): ${eventPath}`);
1684
1856
  }
@@ -1692,10 +1864,10 @@ export function registerRegisterCommands(program) {
1692
1864
  process.stdout.write(`Generated: ${view.path}\n`);
1693
1865
  }
1694
1866
  }
1695
- }
1696
- catch (error) {
1697
- printCommandError(error);
1698
- }
1867
+ if (warnAboutDerivedTopic)
1868
+ printDerivedTopicWarning(topic);
1869
+ return { id: displayId, title: opts.title };
1870
+ });
1699
1871
  });
1700
1872
  // --- close ---
1701
1873
  const closeCmd = reg.command("close").description("Set item status to done or decided");
@@ -1707,11 +1879,14 @@ export function registerRegisterCommands(program) {
1707
1879
  closeCmd.option("--by <actor>", "Actor recorded in the append-only register event");
1708
1880
  closeCmd.option("--reason <text>", "Reason recorded in the append-only register event");
1709
1881
  closeCmd.option("--dry-run", "Print change without writing", false);
1710
- closeCmd.action((opts) => {
1711
- try {
1712
- const paths = resolveRegisterPaths(opts);
1882
+ addRegisterCommitOptions(closeCmd);
1883
+ closeCmd.action(async (opts) => {
1884
+ await runRegisterMutation("close", opts, (context) => {
1885
+ const { paths } = context;
1713
1886
  const view = loadItemForUpdate(paths, opts.id, "require-active");
1714
1887
  const item = view.item;
1888
+ assertTerminalOperationAllowed(item, "close");
1889
+ assertRegisterItemCommitTargetsClean(context, view);
1715
1890
  const targetStatus = opts.status ?? (["decision", "question"].includes(item.type) ? "decided" : "done");
1716
1891
  if (targetStatus !== "done" && targetStatus !== "decided") {
1717
1892
  throw new Error(`--status must be "done" or "decided" for the close command`);
@@ -1736,10 +1911,8 @@ export function registerRegisterCommands(program) {
1736
1911
  eventReason: opts.reason?.trim() || opts.conclusion?.trim() || `closed as ${targetStatus}`,
1737
1912
  });
1738
1913
  updateTicketStatusForItem({ paths, item, targetStatus: "ready", dryRun: opts.dryRun });
1739
- }
1740
- catch (error) {
1741
- printCommandError(error);
1742
- }
1914
+ return { id: item.id, title: item.title };
1915
+ });
1743
1916
  });
1744
1917
  // --- reject ---
1745
1918
  const rejectCmd = reg.command("reject").description("Set item status to rejected");
@@ -1750,11 +1923,14 @@ export function registerRegisterCommands(program) {
1750
1923
  rejectCmd.option("--by <actor>", "Actor recorded in the append-only register event");
1751
1924
  rejectCmd.option("--reason <text>", "Reason recorded in the append-only register event");
1752
1925
  rejectCmd.option("--dry-run", "Print change without writing", false);
1753
- rejectCmd.action((opts) => {
1754
- try {
1755
- const paths = resolveRegisterPaths(opts);
1926
+ addRegisterCommitOptions(rejectCmd);
1927
+ rejectCmd.action(async (opts) => {
1928
+ await runRegisterMutation("reject", opts, (context) => {
1929
+ const { paths } = context;
1756
1930
  const view = loadItemForUpdate(paths, opts.id, "require-active");
1757
1931
  const item = view.item;
1932
+ assertTerminalOperationAllowed(item, "reject");
1933
+ assertRegisterItemCommitTargetsClean(context, view);
1758
1934
  const completedAt = parseRegisterTimestampOption(opts.completed, "completed", CELL_NONE) ?? nowUtcTimestamp();
1759
1935
  if (completedAt === CELL_NONE) {
1760
1936
  throw new Error(`Invalid completed: "${opts.completed}". A rejection date-time is required`);
@@ -1775,10 +1951,8 @@ export function registerRegisterCommands(program) {
1775
1951
  eventReason: opts.reason?.trim() || opts.conclusion?.trim() || "item rejected",
1776
1952
  });
1777
1953
  updateTicketStatusForItem({ paths, item, targetStatus: "deprecated", dryRun: opts.dryRun });
1778
- }
1779
- catch (error) {
1780
- printCommandError(error);
1781
- }
1954
+ return { id: item.id, title: item.title };
1955
+ });
1782
1956
  });
1783
1957
  // --- defer ---
1784
1958
  const deferCmd = reg.command("defer").description("Set item status to deferred");
@@ -1788,11 +1962,14 @@ export function registerRegisterCommands(program) {
1788
1962
  deferCmd.option("--by <actor>", "Actor recorded in the append-only register event");
1789
1963
  deferCmd.option("--reason <text>", "Reason recorded in the append-only register event");
1790
1964
  deferCmd.option("--dry-run", "Print change without writing", false);
1791
- deferCmd.action((opts) => {
1792
- try {
1793
- const paths = resolveRegisterPaths(opts);
1965
+ addRegisterCommitOptions(deferCmd);
1966
+ deferCmd.action(async (opts) => {
1967
+ await runRegisterMutation("defer", opts, (context) => {
1968
+ const { paths } = context;
1794
1969
  const view = loadItemForUpdate(paths, opts.id, "require-active");
1795
1970
  const item = view.item;
1971
+ assertTerminalOperationAllowed(item, "defer");
1972
+ assertRegisterItemCommitTargetsClean(context, view);
1796
1973
  const updated = {
1797
1974
  ...item,
1798
1975
  status: "deferred",
@@ -1807,10 +1984,8 @@ export function registerRegisterCommands(program) {
1807
1984
  eventActor: registerEventActor(opts),
1808
1985
  eventReason: opts.reason?.trim() || opts.conclusion?.trim() || "item deferred",
1809
1986
  });
1810
- }
1811
- catch (error) {
1812
- printCommandError(error);
1813
- }
1987
+ return { id: item.id, title: item.title };
1988
+ });
1814
1989
  });
1815
1990
  // --- reopen ---
1816
1991
  const reopenCmd = reg.command("reopen").description("Reopen a terminal-status item");
@@ -1820,11 +1995,13 @@ export function registerRegisterCommands(program) {
1820
1995
  reopenCmd.option("--by <actor>", "Actor recorded in the append-only register event");
1821
1996
  reopenCmd.option("--reason <text>", "Reason recorded in the append-only register event");
1822
1997
  reopenCmd.option("--dry-run", "Print change without writing", false);
1823
- reopenCmd.action((opts) => {
1824
- try {
1825
- const paths = resolveRegisterPaths(opts);
1998
+ addRegisterCommitOptions(reopenCmd);
1999
+ reopenCmd.action(async (opts) => {
2000
+ await runRegisterMutation("reopen", opts, (context) => {
2001
+ const { paths } = context;
1826
2002
  const view = loadItemForUpdate(paths, opts.id, "require-terminal");
1827
2003
  const item = view.item;
2004
+ assertRegisterItemCommitTargetsClean(context, view);
1828
2005
  const validReopenStatuses = ["open", "in-progress", "waiting", "review"];
1829
2006
  if (!validReopenStatuses.includes(opts.status)) {
1830
2007
  throw new Error(`--status must be one of: ${validReopenStatuses.join(", ")}`);
@@ -1840,10 +2017,8 @@ export function registerRegisterCommands(program) {
1840
2017
  eventActor: registerEventActor(opts),
1841
2018
  eventReason: opts.reason?.trim() || `reopened as ${opts.status}`,
1842
2019
  });
1843
- }
1844
- catch (error) {
1845
- printCommandError(error);
1846
- }
2020
+ return { id: item.id, title: item.title };
2021
+ });
1847
2022
  });
1848
2023
  // --- start ---
1849
2024
  const startCmd = reg.command("start").description("Set item status to in-progress");
@@ -1852,11 +2027,13 @@ export function registerRegisterCommands(program) {
1852
2027
  startCmd.option("--by <actor>", "Actor recorded in the append-only register event");
1853
2028
  startCmd.option("--reason <text>", "Reason recorded in the append-only register event");
1854
2029
  startCmd.option("--dry-run", "Print change without writing", false);
1855
- startCmd.action((opts) => {
1856
- try {
1857
- const paths = resolveRegisterPaths(opts);
2030
+ addRegisterCommitOptions(startCmd);
2031
+ startCmd.action(async (opts) => {
2032
+ await runRegisterMutation("start", opts, (context) => {
2033
+ const { paths } = context;
1858
2034
  const view = loadItemForUpdate(paths, opts.id, "require-active");
1859
2035
  const item = view.item;
2036
+ assertRegisterItemCommitTargetsClean(context, view);
1860
2037
  const updated = { ...item, status: "in-progress" };
1861
2038
  applyItemUpdate({
1862
2039
  paths,
@@ -1867,10 +2044,8 @@ export function registerRegisterCommands(program) {
1867
2044
  eventActor: registerEventActor(opts),
1868
2045
  eventReason: opts.reason?.trim() || "work started",
1869
2046
  });
1870
- }
1871
- catch (error) {
1872
- printCommandError(error);
1873
- }
2047
+ return { id: item.id, title: item.title };
2048
+ });
1874
2049
  });
1875
2050
  // --- wait ---
1876
2051
  const waitCmd = reg.command("wait").description("Set item status to waiting");
@@ -1880,14 +2055,16 @@ export function registerRegisterCommands(program) {
1880
2055
  waitCmd.option("--conclusion <text>", "Deprecated alias for --reason");
1881
2056
  waitCmd.option("--by <actor>", "Actor recorded in the append-only register event");
1882
2057
  waitCmd.option("--dry-run", "Print change without writing", false);
1883
- waitCmd.action((opts) => {
1884
- try {
2058
+ addRegisterCommitOptions(waitCmd);
2059
+ waitCmd.action(async (opts) => {
2060
+ await runRegisterMutation("wait", opts, (context) => {
1885
2061
  if (opts.reason !== undefined && opts.conclusion !== undefined) {
1886
2062
  throw new Error("Specify only one of --reason or --conclusion");
1887
2063
  }
1888
- const paths = resolveRegisterPaths(opts);
2064
+ const { paths } = context;
1889
2065
  const view = loadItemForUpdate(paths, opts.id, "require-active");
1890
2066
  const item = view.item;
2067
+ assertRegisterItemCommitTargetsClean(context, view);
1891
2068
  const reason = (opts.reason ?? opts.conclusion)?.trim();
1892
2069
  if (reason !== undefined && reason === "") {
1893
2070
  throw new Error("Waiting reason must not be empty");
@@ -1908,10 +2085,8 @@ export function registerRegisterCommands(program) {
1908
2085
  eventActor: registerEventActor(opts),
1909
2086
  eventReason: reason || "item waiting",
1910
2087
  });
1911
- }
1912
- catch (error) {
1913
- printCommandError(error);
1914
- }
2088
+ return { id: item.id, title: item.title };
2089
+ });
1915
2090
  });
1916
2091
  // --- review ---
1917
2092
  const reviewCmd = reg.command("review").description("Set item status to review");
@@ -1920,11 +2095,13 @@ export function registerRegisterCommands(program) {
1920
2095
  reviewCmd.option("--by <actor>", "Actor recorded in the append-only register event");
1921
2096
  reviewCmd.option("--reason <text>", "Reason recorded in the append-only register event");
1922
2097
  reviewCmd.option("--dry-run", "Print change without writing", false);
1923
- reviewCmd.action((opts) => {
1924
- try {
1925
- const paths = resolveRegisterPaths(opts);
2098
+ addRegisterCommitOptions(reviewCmd);
2099
+ reviewCmd.action(async (opts) => {
2100
+ await runRegisterMutation("review", opts, (context) => {
2101
+ const { paths } = context;
1926
2102
  const view = loadItemForUpdate(paths, opts.id, "require-active");
1927
2103
  const item = view.item;
2104
+ assertRegisterItemCommitTargetsClean(context, view);
1928
2105
  const updated = { ...item, status: "review" };
1929
2106
  applyItemUpdate({
1930
2107
  paths,
@@ -1935,10 +2112,8 @@ export function registerRegisterCommands(program) {
1935
2112
  eventActor: registerEventActor(opts),
1936
2113
  eventReason: opts.reason?.trim() || "ready for review",
1937
2114
  });
1938
- }
1939
- catch (error) {
1940
- printCommandError(error);
1941
- }
2115
+ return { id: item.id, title: item.title };
2116
+ });
1942
2117
  });
1943
2118
  // --- update ---
1944
2119
  const updateCmd = reg.command("update").description("Update fields of a register item");
@@ -1950,13 +2125,15 @@ export function registerRegisterCommands(program) {
1950
2125
  updateCmd.option("--owner <owner>", "Update owner or role");
1951
2126
  updateCmd.option("--due <date>", "Update due date (YYYY-MM-DD, -, or _TODO_)");
1952
2127
  updateCmd.option("--conclusion <text>", "Update conclusion or use - to remove it");
2128
+ updateCmd.option("--block-reason <text>", "Update the waiting reason or use - to remove it");
1953
2129
  updateCmd.option("--topic <topic>", "Update the topic slug in the ticket filename and document ID");
1954
2130
  updateCmd.option("--by <actor>", "Actor recorded in the append-only register event");
1955
2131
  updateCmd.option("--reason <text>", "Reason recorded in the append-only register event");
1956
2132
  updateCmd.option("--dry-run", "Print change without writing", false);
1957
- updateCmd.action((opts) => {
1958
- try {
1959
- const paths = resolveRegisterPaths(opts);
2133
+ addRegisterCommitOptions(updateCmd);
2134
+ updateCmd.action(async (opts) => {
2135
+ await runRegisterMutation("update", opts, (context) => {
2136
+ const { paths } = context;
1960
2137
  const view = loadItemForUpdate(paths, opts.id);
1961
2138
  const item = view.item;
1962
2139
  const hasUpdates = [
@@ -1966,10 +2143,11 @@ export function registerRegisterCommands(program) {
1966
2143
  "owner",
1967
2144
  "due",
1968
2145
  "conclusion",
2146
+ "blockReason",
1969
2147
  "topic",
1970
2148
  ].some((k) => opts[k] !== undefined);
1971
2149
  if (!hasUpdates) {
1972
- throw new Error("At least one field option must be specified (--title, --description, --priority, --owner, --due, --conclusion, --topic)");
2150
+ throw new Error("At least one field option must be specified (--title, --description, --priority, --owner, --due, --conclusion, --block-reason, --topic)");
1973
2151
  }
1974
2152
  if (opts.priority !== undefined &&
1975
2153
  !VALID_PRIORITIES.includes(opts.priority)) {
@@ -1982,6 +2160,20 @@ export function registerRegisterCommands(program) {
1982
2160
  if (topic !== undefined && !REGISTER_TOPIC_RE.test(topic)) {
1983
2161
  throw new Error(`Invalid topic: "${topic}". Must use lowercase letters, numbers, and single hyphens`);
1984
2162
  }
2163
+ const blockReason = opts.blockReason?.trim();
2164
+ if (blockReason !== undefined && blockReason === "") {
2165
+ throw new Error("Block reason must not be empty; use - to remove it");
2166
+ }
2167
+ if (blockReason !== undefined && blockReason !== "-" && item.status !== "waiting") {
2168
+ throw new Error(`Cannot set block reason for ${item.id}: status is "${item.status}" (expected "waiting"). Use - to remove it.`);
2169
+ }
2170
+ const blockReasonUpdates = blockReason === undefined
2171
+ ? undefined
2172
+ : {
2173
+ block_reason: blockReason === "-"
2174
+ ? REMOVE_REGISTER_ITEM_FIELD
2175
+ : inlineCodeAnglePlaceholders(blockReason),
2176
+ };
1985
2177
  const updated = {
1986
2178
  ...item,
1987
2179
  ...(opts.title !== undefined ? { title: opts.title } : {}),
@@ -1995,19 +2187,27 @@ export function registerRegisterCommands(program) {
1995
2187
  ? ticketTopicFromFilename(opts.id, view.ticketFilename)
1996
2188
  : undefined;
1997
2189
  if (topic !== undefined && topic !== currentTopic) {
2190
+ const retopicPlan = planRetopic(paths, opts.id, topic);
2191
+ context.assertCommitTargetsClean([
2192
+ retopicPlan.ticketRename.from,
2193
+ ...retopicPlan.writes.map((write) => write.path),
2194
+ registerEventFilePath(paths.projectRegisterPath, item.id),
2195
+ ]);
1998
2196
  retopicPjrItem({
1999
2197
  paths,
2000
2198
  id: opts.id,
2001
2199
  topic,
2002
2200
  updated,
2003
2201
  dryRun: opts.dryRun,
2202
+ ...(blockReasonUpdates ? { fieldUpdates: blockReasonUpdates } : {}),
2004
2203
  ...(opts.title !== undefined ? { title: opts.title } : {}),
2005
2204
  ...(opts.description !== undefined ? { description: opts.description } : {}),
2006
2205
  actor: registerEventActor(opts),
2007
2206
  reason: opts.reason?.trim() || "",
2008
2207
  });
2009
- return;
2208
+ return { id: item.id, title: updated.title };
2010
2209
  }
2210
+ assertRegisterItemCommitTargetsClean(context, view);
2011
2211
  applyItemUpdate({
2012
2212
  paths,
2013
2213
  view,
@@ -2016,14 +2216,13 @@ export function registerRegisterCommands(program) {
2016
2216
  action: "fields updated",
2017
2217
  ...(opts.title !== undefined ? { title: opts.title } : {}),
2018
2218
  ...(opts.description !== undefined ? { description: opts.description } : {}),
2219
+ ...(blockReasonUpdates ? { fieldUpdates: blockReasonUpdates } : {}),
2019
2220
  eventAction: "update",
2020
2221
  eventActor: registerEventActor(opts),
2021
2222
  eventReason: opts.reason?.trim() || "fields updated",
2022
2223
  });
2023
- }
2024
- catch (error) {
2025
- printCommandError(error);
2026
- }
2224
+ return { id: item.id, title: updated.title };
2225
+ });
2027
2226
  });
2028
2227
  // --- migrate ---
2029
2228
  const migrateCmd = reg
@@ -2180,9 +2379,20 @@ export function registerRegisterCommands(program) {
2180
2379
  renumberCmd.option("--by <actor>", "Actor recorded in the append-only register event");
2181
2380
  renumberCmd.option("--reason <text>", "Reason recorded in the append-only register event");
2182
2381
  renumberCmd.option("--dry-run", "Print planned changes without writing", false);
2183
- renumberCmd.action((opts) => {
2184
- try {
2185
- const paths = resolveRegisterPaths(opts);
2382
+ addRegisterCommitOptions(renumberCmd);
2383
+ renumberCmd.action(async (opts) => {
2384
+ await runRegisterMutation("renumber", opts, (context) => {
2385
+ const { paths } = context;
2386
+ const source = loadItemForUpdate(paths, opts.id);
2387
+ const renumberPlan = planRenumber(paths, opts.id, opts.to);
2388
+ context.assertCommitTargetsClean([
2389
+ ...(renumberPlan.ticketRename
2390
+ ? [renumberPlan.ticketRename.from, renumberPlan.ticketRename.to]
2391
+ : []),
2392
+ ...renumberPlan.writes.map((write) => write.path),
2393
+ registerEventFilePath(paths.projectRegisterPath, opts.id),
2394
+ registerEventFilePath(paths.projectRegisterPath, opts.to),
2395
+ ]);
2186
2396
  renumberPjrItem({
2187
2397
  paths,
2188
2398
  fromId: opts.id,
@@ -2191,9 +2401,7 @@ export function registerRegisterCommands(program) {
2191
2401
  actor: registerEventActor(opts),
2192
2402
  reason: opts.reason,
2193
2403
  });
2194
- }
2195
- catch (error) {
2196
- printCommandError(error);
2197
- }
2404
+ return { id: opts.to, title: source.item.title };
2405
+ });
2198
2406
  });
2199
2407
  }