specdojo 0.5.0 → 0.6.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 (93) hide show
  1. package/.github/agents/specdojo-orchestrator.md +2 -0
  2. package/CHANGELOG.md +60 -0
  3. package/dist/catalog/generate.js +144 -13
  4. package/dist/commands/init.js +1 -0
  5. package/dist/deliverable/deliverable.js +77 -4
  6. package/dist/exec/core.js +1 -0
  7. package/dist/exec/parent-validation.js +7 -0
  8. package/dist/exec/plans-core.js +46 -1
  9. package/dist/exec/plans-generation.js +39 -3
  10. package/dist/exec/plans-planning.js +1 -1
  11. package/dist/exec/plans-storage.js +1 -0
  12. package/dist/exec/product-branch-records.js +105 -0
  13. package/dist/exec/product-branches.js +52 -0
  14. package/dist/exec/register-product-message.js +50 -0
  15. package/dist/exec/register.js +6 -0
  16. package/dist/exec/repo-integration-sync.js +4 -2
  17. package/dist/exec/repo-integration.js +41 -4
  18. package/dist/exec/repo-trace.js +2 -0
  19. package/dist/exec/results.js +9 -5
  20. package/dist/exec/run/register-command.js +16 -0
  21. package/dist/exec/run/register-resume.js +11 -1
  22. package/dist/exec/run/register-worktree.js +29 -8
  23. package/dist/exec/run/schedule-prepare.js +7 -3
  24. package/dist/exec/strategy.js +2 -1
  25. package/dist/exec/task-repos.js +78 -16
  26. package/dist/exec/worktree-command.js +2 -2
  27. package/dist/exec/worktree.js +3 -3
  28. package/dist/register/core.js +5 -0
  29. package/dist/register/create-commands.js +54 -2
  30. package/dist/register/deliverable-target.js +24 -17
  31. package/dist/register/event-merge.js +4 -0
  32. package/dist/register/events.js +6 -0
  33. package/dist/register/external-project.js +2 -0
  34. package/dist/register/input.js +168 -0
  35. package/dist/register/item.js +61 -0
  36. package/dist/register/register.js +2 -2
  37. package/dist/register/renumber.js +4 -0
  38. package/dist/register/update.js +6 -0
  39. package/dist/schedule/approach.js +9 -0
  40. package/dist/schedule/strategy-profiles.js +22 -2
  41. package/dist/shared/agent-types.js +4 -1
  42. package/dist/shared/branch-template.js +26 -0
  43. package/dist/shared/commit-message-template.js +38 -0
  44. package/dist/shared/commit-types.js +15 -0
  45. package/dist/shared/specdojo-config.js +35 -4
  46. package/docs/ja/specdojo/exec-templates/xep-draft-template.md +93 -0
  47. package/docs/ja/specdojo/exec-templates/xep-fully-guided-template.md +9 -2
  48. package/docs/ja/specdojo/exec-templates/xep-register-investigate-template.md +2 -0
  49. package/docs/ja/specdojo/exec-templates/xep-register-template.md +2 -0
  50. package/docs/ja/specdojo/exec-templates/xer-human-bootstrap-finalize-template.md +2 -0
  51. package/docs/ja/specdojo/exec-templates/xer-human-draft-template.md +23 -0
  52. package/docs/ja/specdojo/exec-templates/xer-human-finalize-template.md +2 -0
  53. package/docs/ja/specdojo/exec-templates/xrp-fully-guided-template.md +7 -4
  54. package/docs/ja/specdojo/guides/exec-config-guide.md +3 -1
  55. package/docs/ja/specdojo/guides/exec-operation-guide.md +96 -2
  56. package/docs/ja/specdojo/guides/register-operation-guide.md +14 -1
  57. package/docs/ja/specdojo/guides/remote-host-development-guide.md +1 -1
  58. package/docs/ja/specdojo/guides/ryu-guide.md +114 -23
  59. package/docs/ja/specdojo/guides/schedule-design-guide.md +31 -4
  60. package/docs/ja/specdojo/recipes/exec-human-finalize-recipe.md +1 -0
  61. package/docs/ja/specdojo/recipes/tsd-recipe.md +20 -12
  62. package/docs/ja/specdojo/references/command-reference.md +44 -11
  63. package/docs/ja/specdojo/references/specdojo-config-reference.md +69 -8
  64. package/docs/ja/specdojo/rulebooks/dct-rulebook.md +8 -0
  65. package/docs/ja/specdojo/rulebooks/pjr-rulebook.md +4 -0
  66. package/docs/ja/specdojo/rulebooks/sch-rulebook.md +3 -1
  67. package/docs/ja/specdojo/samples/dct-sample.yaml +5 -1
  68. package/docs/ja/specdojo/standards/document-metadata-standard.md +16 -0
  69. package/docs/ja/specdojo/standards/exec-human-finalize-standard.md +1 -0
  70. package/docs/ja/specdojo/standards/guide-authoring-standard.md +2 -1
  71. package/docs/ja/specdojo/standards/philosophy-authoring-standard.md +1 -0
  72. package/docs/ja/specdojo/standards/recipe-authoring-standard.md +2 -1
  73. package/docs/ja/specdojo/standards/rulebook-authoring-standard.md +2 -1
  74. package/docs/ja/specdojo/standards/standard-authoring-standard.md +2 -1
  75. package/docs/ja/specdojo/templates/pjr-change-request-template.md +10 -4
  76. package/docs/ja/specdojo/templates/pjr-issue-template.md +10 -4
  77. package/docs/ja/specdojo/templates/pjr-question-template.md +11 -5
  78. package/docs/ja/specdojo/templates/pjr-risk-template.md +10 -4
  79. package/docs/ja/specdojo/templates/pjr-todo-template.md +10 -4
  80. package/docs/specdojo/schemas/v1/dct.schema.yaml +9 -0
  81. package/docs/specdojo/schemas/v1/exec-common.schema.yaml +2 -1
  82. package/docs/specdojo/schemas/v1/exec-defaults.schema.yaml +1 -0
  83. package/docs/specdojo/schemas/v1/register-events.schema.yaml +3 -0
  84. package/docs/specdojo/schemas/v1/register-item-frontmatter.schema.yaml +35 -0
  85. package/docs/specdojo/schemas/v1/sch-strategy.schema.yaml +1 -0
  86. package/docs/specdojo/schemas/v1/specdojo-config.schema.yaml +40 -2
  87. package/package.json +3 -2
  88. package/templates/antigravity/orchestrator.md +2 -0
  89. package/templates/claude/agents/specdojo-orchestrator.md +2 -0
  90. package/templates/codex/agents/specdojo-orchestrator.toml +2 -0
  91. package/templates/codex/orchestrator.md +2 -0
  92. package/templates/devcontainer/remote-host/specdojo-tmux.sh.sample +14 -8
  93. package/templates/opencode/agents/specdojo-orchestrator.md +2 -0
@@ -1,7 +1,9 @@
1
+ import { expandBranchTemplate } from "../shared/branch-template.js";
1
2
  import { existsSync, readdirSync, rmdirSync } from "node:fs";
2
3
  import { dirname, resolve } from "node:path";
3
4
  import { getProjectRepos, getProjectSchedulePath, loadConfig, PROJECT_REPO_WORKTREE_DIRNAME, resolveRepoRoot, specdojoRootDir, } from "../shared/specdojo-config.js";
4
- import { ensureExecWorktree, execBranchExists, execWorktreePath, findExecWorktree, generateWorktreeArtifacts, gitOutput, gitResult, installWorktreeDependencies, listRegisteredWorktrees, worktreeNameFromTaskId, } from "./worktree.js";
5
+ import { ensureExecWorktree, execWorktreePath, findExecWorktree, generateWorktreeArtifacts, gitOutput, gitResult, installWorktreeDependencies, listRegisteredWorktrees, worktreeNameFromTaskId, } from "./worktree.js";
6
+ import { assertProductBranchAvailable, existingProductTaskBranch, forgetProductBranch, productBranchExists, productBranchRecords, recordedProductBranch, reserveProductBranch, } from "./product-branch-records.js";
5
7
  // PJR-98G4: 1 つのタスクがプロジェクトリポジトリと宣言済みのプロダクトリポジトリ(`repos`)を
6
8
  // 変更する場合の worktree を扱う。`repos` を持たない project では、ここの関数はどれも空の結果を
7
9
  // 返し、既存の 1 リポジトリ・`<worktree_base>/<task-id>/` 直下の配置を変えない。
@@ -69,6 +71,7 @@ export function resolveProductRepos(rootDir, project, integrationBranches) {
69
71
  name: repo.name,
70
72
  repoRoot: resolveRepoRoot(rootDir, repo),
71
73
  ...(integrationBranch ? { integrationBranch } : {}),
74
+ ...(repo.branch_template ? { branchTemplate: repo.branch_template } : {}),
72
75
  ...(repo.integration_strategy ? { integrationStrategy: repo.integration_strategy } : {}),
73
76
  install: repo.setup?.install ?? true,
74
77
  build: repo.setup?.build ?? true,
@@ -156,18 +159,35 @@ export function productIntegrationTarget(product) {
156
159
  return product.integrationBranch ?? currentBranchOrNull(product.repoRoot) ?? "HEAD";
157
160
  }
158
161
  const skip = () => undefined;
162
+ export function preflightProductBranches(products, taskId) {
163
+ for (const product of products) {
164
+ if (!existsSync(product.repoRoot)) {
165
+ throw new Error(`Product repository "${product.name}" does not exist: ${product.repoRoot} (check repos[].path)`);
166
+ }
167
+ assertProductBranchAvailable(product.repoRoot, taskId, productBranchForTask(product, taskId));
168
+ }
169
+ }
170
+ /** Reserve every name before recording register start or creating any product worktree. */
171
+ export function reserveProductBranches(products, taskId) {
172
+ preflightProductBranches(products, taskId);
173
+ for (const product of products) {
174
+ reserveProductBranch(product.repoRoot, taskId, productBranchForTask(product, taskId), productIntegrationTarget(product));
175
+ }
176
+ }
159
177
  /**
160
178
  * Create (or reuse) `<worktree_base>/<task-name>/<repo>/` for every product repository. A new
161
179
  * exec branch starts from the declared `integration_branch` (or the repository's current branch)
162
180
  * because the checkpoint commit belongs to the project repository only.
163
181
  */
164
182
  export function ensureProductWorktrees(opts) {
183
+ reserveProductBranches(opts.products, opts.taskId);
165
184
  return opts.products.map((product) => {
166
185
  if (!existsSync(product.repoRoot)) {
167
186
  throw new Error(`Product repository "${product.name}" does not exist: ${product.repoRoot} (check repos[].path)`);
168
187
  }
188
+ const branch = productBranchForTask(product, opts.taskId);
169
189
  const generate = product.build ? (opts.generateArtifacts ?? generateWorktreeArtifacts) : skip;
170
- const existing = findExecWorktree(product.repoRoot, opts.taskId);
190
+ const existing = findExecWorktree(product.repoRoot, opts.taskId, branch);
171
191
  if (existing) {
172
192
  // Same as the project worktree on reuse: dependencies stay, generated files are rebuilt.
173
193
  generate(existing.path);
@@ -178,6 +198,7 @@ export function ensureProductWorktrees(opts) {
178
198
  worktreeBase: opts.worktreeBase,
179
199
  taskId: opts.taskId,
180
200
  repoDirName: product.name,
201
+ branch,
181
202
  startPoint: productIntegrationTarget(product),
182
203
  installDependencies: product.install
183
204
  ? (opts.installDependencies ?? installWorktreeDependencies)
@@ -198,12 +219,33 @@ function toProductWorktree(product, worktree) {
198
219
  ...(product.integrationStrategy ? { integrationStrategy: product.integrationStrategy } : {}),
199
220
  };
200
221
  }
222
+ /** Recorded names survive template/topic changes and do not depend on a branch prefix. */
223
+ export function productBranchForTask(product, taskId, reuseRecorded = true) {
224
+ const separator = taskId.indexOf(":");
225
+ const project = separator >= 0 ? taskId.slice(0, separator) : "";
226
+ const id = separator >= 0 ? taskId.slice(separator + 1) : taskId;
227
+ return (product.branch ??
228
+ (reuseRecorded ? recordedProductBranch(product.repoRoot, taskId) : undefined) ??
229
+ (product.branchTemplate
230
+ ? expandBranchTemplate(product.branchTemplate, {
231
+ project,
232
+ id,
233
+ topic: id.toLowerCase(),
234
+ type: "feat",
235
+ scope: "",
236
+ title: id,
237
+ })
238
+ : `exec/${worktreeNameFromTaskId(taskId)}`));
239
+ }
201
240
  /** Registered product worktrees of a task (repositories without one are omitted). */
202
241
  export function findProductWorktrees(products, taskId) {
203
242
  return products.flatMap((product) => {
204
243
  if (!existsSync(product.repoRoot))
205
244
  return [];
206
- const found = findExecWorktree(product.repoRoot, taskId);
245
+ const branch = existingProductTaskBranch(product.repoRoot, taskId);
246
+ if (!branch)
247
+ return [];
248
+ const found = findExecWorktree(product.repoRoot, taskId, branch);
207
249
  return found ? [toProductWorktree(product, found)] : [];
208
250
  });
209
251
  }
@@ -315,6 +357,7 @@ export function removeProductWorktrees(params) {
315
357
  // keep Git's safe `-d` so unintegrated product work is never deleted.
316
358
  const flag = isMergedIntoTarget(product) ? "-D" : "-d";
317
359
  gitOutput(product.repoRoot, ["branch", flag, product.branch]);
360
+ forgetProductBranch(product.repoRoot, product.branch);
318
361
  }
319
362
  }
320
363
  }
@@ -339,12 +382,14 @@ export function removeEmptyTaskDirectory(worktree) {
339
382
  */
340
383
  export function discardStaleProductWorktrees(products, taskId) {
341
384
  // A retained branch is product-side review work, not abandoned scheduler residue.
342
- // Check every product before removing anything, including a previous task's project worktree.
343
385
  for (const product of products) {
386
+ if (!existsSync(product.repoRoot))
387
+ continue;
388
+ const branch = existingProductTaskBranch(product.repoRoot, taskId);
344
389
  if (product.integrationStrategy === "branch-only" &&
345
- existsSync(product.repoRoot) &&
346
- execBranchExists(product.repoRoot, taskId)) {
347
- throw new Error(`${product.name}: retained exec branch exec/${worktreeNameFromTaskId(taskId)} already exists; ` +
390
+ branch &&
391
+ productBranchExists(product.repoRoot, branch)) {
392
+ throw new Error(`${product.name}: retained exec branch ${branch} already exists; ` +
348
393
  `resume the existing run or finish product-side review and rename/remove the branch before a fresh run`);
349
394
  }
350
395
  }
@@ -352,19 +397,20 @@ export function discardStaleProductWorktrees(products, taskId) {
352
397
  for (const product of products) {
353
398
  if (!existsSync(product.repoRoot))
354
399
  continue;
355
- const existing = findExecWorktree(product.repoRoot, taskId);
356
- if (!existing && !execBranchExists(product.repoRoot, taskId))
400
+ const branch = existingProductTaskBranch(product.repoRoot, taskId);
401
+ if (!branch)
357
402
  continue;
403
+ const existing = findExecWorktree(product.repoRoot, taskId, branch);
358
404
  if (existing) {
359
405
  if (resolve(product.repoRoot) === resolve(existing.path)) {
360
- throw new Error(`Refusing to discard the main checkout of ${product.name} as stale residue: ${existing.branch}`);
406
+ throw new Error(`Refusing to discard the main checkout of ${product.name} as stale residue: ${branch}`);
361
407
  }
362
408
  gitOutput(product.repoRoot, ["worktree", "remove", "--force", existing.path]);
363
409
  }
364
- const branch = `exec/${worktreeNameFromTaskId(taskId)}`;
365
- if (execBranchExists(product.repoRoot, taskId)) {
410
+ if (productBranchExists(product.repoRoot, branch)) {
366
411
  gitOutput(product.repoRoot, ["branch", "-D", branch]);
367
412
  }
413
+ forgetProductBranch(product.repoRoot, branch);
368
414
  discarded.push(`${product.name}:${branch}`);
369
415
  }
370
416
  return discarded;
@@ -379,14 +425,25 @@ export function listOrphanedProductExecBranches(products, projectId) {
379
425
  .map((worktree) => worktree.branch)
380
426
  .filter((branch) => !!branch));
381
427
  const target = productIntegrationTarget(product);
382
- return gitOutput(product.repoRoot, [
428
+ const legacyBranches = gitOutput(product.repoRoot, [
383
429
  "for-each-ref",
384
430
  "--format=%(refname:short)",
385
431
  "refs/heads/exec/",
386
432
  ])
387
433
  .split(/\r?\n/)
388
434
  .map((branch) => branch.trim())
389
- .filter((branch) => branch.startsWith(prefix) && !checkedOut.has(branch))
435
+ .filter((branch) => branch.startsWith(prefix));
436
+ const records = productBranchRecords(product.repoRoot);
437
+ const owned = records
438
+ .filter((record) => record.taskId.startsWith(`${projectId}:`))
439
+ .map((record) => record.branch);
440
+ return [
441
+ ...new Set([
442
+ ...owned,
443
+ ...legacyBranches.filter((branch) => !records.some((record) => record.branch === branch)),
444
+ ]),
445
+ ]
446
+ .filter((branch) => !checkedOut.has(branch) && productBranchExists(product.repoRoot, branch))
390
447
  .sort()
391
448
  .map((branch) => ({
392
449
  repo: product.name,
@@ -395,7 +452,7 @@ export function listOrphanedProductExecBranches(products, projectId) {
395
452
  }));
396
453
  });
397
454
  }
398
- /** Delete merged orphan exec branches of product repositories with Git's safe `-d`. */
455
+ /** Delete only orphan branches verified as merged into the product's integration target. */
399
456
  export function pruneOrphanedProductExecBranches(params) {
400
457
  const orphaned = listOrphanedProductExecBranches(params.products, params.projectId);
401
458
  for (const item of orphaned) {
@@ -405,7 +462,12 @@ export function pruneOrphanedProductExecBranches(params) {
405
462
  if (!product)
406
463
  continue;
407
464
  try {
408
- gitOutput(product.repoRoot, ["branch", "-d", item.branch]);
465
+ // The main checkout's HEAD need not be the integration target. Recheck that target
466
+ // before using -D, just as removeProductWorktrees does for a non-orphan branch.
467
+ if (!isMergedIntoTarget({ ...product, branch: item.branch }))
468
+ continue;
469
+ gitOutput(product.repoRoot, ["branch", "-D", item.branch]);
470
+ forgetProductBranch(product.repoRoot, item.branch);
409
471
  }
410
472
  catch (error) {
411
473
  throw new Error(`Failed to delete merged orphaned exec branch ${item.repo}:${item.branch}; ` +
@@ -8,7 +8,7 @@ import { activateResolvedProjectPaths, resolveProjectPaths } from "./project.js"
8
8
  import { agentGitStateViolation, captureAgentGitStateAcrossRepos, changedAgentGitStateAcrossRepos, qualifiedGitStateFields, } from "./agent-git-state.js";
9
9
  import { agentProtectedConfigViolation, captureAgentProtectedConfigAcrossRepos, changedAgentProtectedConfigAcrossRepos, qualifiedRepoPaths, } from "./agent-protected-config.js";
10
10
  import { recordGitStateBlockAcrossRepos, recordProtectedConfigBlockAcrossRepos, } from "./protection-handoff.js";
11
- import { configuredProductRepos, missingProductWorktrees, plannedProjectWorktreePath, pruneOrphanedProductExecBranches, productRepoEnvironment, withAgentExtraRoots, withoutInheritedRepoEnvironment, withProductRepoPrompt, withProductWorktrees, } from "./task-repos.js";
11
+ import { configuredProductRepos, missingProductWorktrees, plannedProjectWorktreePath, productBranchForTask, pruneOrphanedProductExecBranches, productRepoEnvironment, withAgentExtraRoots, withoutInheritedRepoEnvironment, withProductRepoPrompt, withProductWorktrees, } from "./task-repos.js";
12
12
  import { resolveAgentMember } from "../shared/specdojo-config.js";
13
13
  import { buildTaskPhaseMap, loadPrompt, loadRosterForExecutionPath, resolveTaskPhaseContext, selectCandidates, } from "./run/run.js";
14
14
  import { buildScheduleIndex } from "./schedule/schedule.js";
@@ -147,7 +147,7 @@ async function prepare(opts) {
147
147
  name: product.name,
148
148
  repoRoot: product.repoRoot,
149
149
  path: resolve(base, name, product.name),
150
- branch,
150
+ branch: productBranchForTask(product, worktreeTaskId),
151
151
  created: false,
152
152
  })),
153
153
  }
@@ -43,9 +43,9 @@ export function listRegisteredWorktrees(repoRoot) {
43
43
  pushCurrent();
44
44
  return result;
45
45
  }
46
- export function findExecWorktree(repoRoot, taskId) {
46
+ export function findExecWorktree(repoRoot, taskId, branchOverride) {
47
47
  const name = worktreeNameFromTaskId(taskId);
48
- const branch = `exec/${name}`;
48
+ const branch = branchOverride ?? `exec/${name}`;
49
49
  const registered = listRegisteredWorktrees(repoRoot).find((item) => item.branch === branch);
50
50
  if (!registered)
51
51
  return null;
@@ -251,7 +251,7 @@ export function ensureExecWorktree(opts) {
251
251
  throw new Error(`Worktree base must be outside the repository: ${opts.worktreeBase}`);
252
252
  }
253
253
  const name = worktreeNameFromTaskId(opts.taskId);
254
- const branch = `exec/${name}`;
254
+ const branch = opts.branch ?? `exec/${name}`;
255
255
  const worktreePath = execWorktreePath(opts.worktreeBase, opts.taskId, opts.repoDirName);
256
256
  const registered = listRegisteredWorktrees(repoRoot);
257
257
  const registeredAtPath = registered.find((item) => item.path === worktreePath);
@@ -1,3 +1,4 @@
1
+ import { setRegisterInput } from "./input.js";
1
2
  import { randomInt, randomUUID } from "node:crypto";
2
3
  import { existsSync, mkdirSync, readdirSync, readFileSync, renameSync, unlinkSync, writeFileSync, } from "node:fs";
3
4
  import { basename, dirname, join, resolve } from "node:path";
@@ -362,6 +363,8 @@ export function buildRegisterItemContent(opts) {
362
363
  if (!isPlaceholderCell(opts.fields.description)) {
363
364
  content = setRegisterItemDescription(content, opts.fields.description);
364
365
  }
366
+ if (opts.fields.inputs !== undefined)
367
+ content = setRegisterInput(content, opts.fields.inputs);
365
368
  return applyRegisterItemFields(content, registerItemFieldsFromItem({
366
369
  id: opts.displayId,
367
370
  status: opts.fields.status,
@@ -384,5 +387,7 @@ export function buildRegisterItemContent(opts) {
384
387
  ...(opts.fields.sources ? { sources: opts.fields.sources } : {}),
385
388
  ...(opts.fields.derivedFrom ? { derivedFrom: opts.fields.derivedFrom } : {}),
386
389
  ...(opts.fields.dependsOn ? { dependsOn: opts.fields.dependsOn } : {}),
390
+ ...(opts.fields.commitType ? { commitType: opts.fields.commitType } : {}),
391
+ ...(opts.fields.commitScope ? { commitScope: opts.fields.commitScope } : {}),
387
392
  }));
388
393
  }
@@ -1,10 +1,11 @@
1
+ import { normalizeRegisterInput } from "./input.js";
1
2
  import { existsSync, mkdirSync } from "node:fs";
2
3
  import { join } from "node:path";
3
4
  import { inlineCodeAnglePlaceholders } from "../shared/text.js";
4
5
  import { APPROACHES } from "../shared/agent-types.js";
5
6
  import { appendRegisterEvent, buildRegisterEvent, registerEventFilePath } from "./events.js";
6
7
  import { nowUtcTimestamp } from "./date.js";
7
- import { readRegisterItemContent, CELL_NONE, CELL_TODO, REMOVE_REGISTER_ITEM_FIELD, VALID_PRIORITIES, VALID_DIFFICULTIES, VALID_STATUSES, VALID_TYPES, } from "./item.js";
8
+ import { readRegisterItemContent, CELL_NONE, CELL_TODO, REMOVE_REGISTER_ITEM_FIELD, VALID_PRIORITIES, VALID_DIFFICULTIES, VALID_STATUSES, VALID_TYPES, VALID_COMMIT_TYPES, COMMIT_SCOPE_RE, } from "./item.js";
8
9
  import { resolveSpecdojoTemplatePath } from "../docs/template-resolution.js";
9
10
  import { validateRegisterApproachTargetsForProject } from "./approach.js";
10
11
  import { normalizeDependsOn, validateRegisterDependencies } from "./dependency.js";
@@ -76,6 +77,7 @@ export function registerCreateCommands(reg, dependencies) {
76
77
  addCmd.requiredOption("--type <type>", `Item type: ${VALID_TYPES.join(" | ")}`);
77
78
  addCmd.option("--track <track>", "Track governed by an epic (required for epic)");
78
79
  addCmd.requiredOption("--title <title>", "Short title for the item");
80
+ addCmd.option("--input <text>", "Premise recorded in the ticket (repeatable)", collectTarget);
79
81
  addCmd.option("--description <text>", "Description shown in the list", "_TODO_");
80
82
  addCmd.option("--priority <priority>", `Priority: ${VALID_PRIORITIES.join(" | ")}`, "medium");
81
83
  addCmd.option("--difficulty <difficulty>", `Difficulty: ${VALID_DIFFICULTIES.join(" | ")}`);
@@ -92,6 +94,8 @@ export function registerCreateCommands(reg, dependencies) {
92
94
  addCmd.option("--source <ref>", "Read-only exemplar for *-authoring (repeatable: doc id, path, or <repo>:<path>)", collectTarget);
93
95
  addCmd.option("--from <item-id>", "Register item this item derives from (repeatable)", collectTarget);
94
96
  addCmd.option("--depends-on <item-id>", "Predecessor item ID (repeatable; use - to remove)", collectTarget);
97
+ addCmd.option("--commit-type <type>", `Conventional Commits type: ${VALID_COMMIT_TYPES.join(" | ")}`);
98
+ addCmd.option("--commit-scope <scope>", "Conventional Commits scope");
95
99
  addCmd.option("--id <id>", "Display ID (e.g., PJR-0061); auto-incremented if omitted");
96
100
  addCmd.option("--topic <topic>", "Topic slug for ticket filename; derived from --title if omitted");
97
101
  addCmd.option("--by <actor>", "Actor recorded in the append-only register event");
@@ -121,6 +125,14 @@ export function registerCreateCommands(reg, dependencies) {
121
125
  !VALID_DIFFICULTIES.includes(opts.difficulty)) {
122
126
  throw new Error(`Invalid difficulty: "${opts.difficulty}". Must be one of: ${VALID_DIFFICULTIES.join(", ")}`);
123
127
  }
128
+ if (opts.commitType !== undefined &&
129
+ !VALID_COMMIT_TYPES.includes(opts.commitType)) {
130
+ throw new Error(`Invalid commit type: "${opts.commitType}". Must be one of: ${VALID_COMMIT_TYPES.join(", ")}`);
131
+ }
132
+ const commitScope = opts.commitScope?.trim();
133
+ if (commitScope !== undefined && !COMMIT_SCOPE_RE.test(commitScope)) {
134
+ throw new Error(`Invalid commit scope: "${commitScope}". Must match ${COMMIT_SCOPE_RE}`);
135
+ }
124
136
  if (opts.target?.some((target) => target.trim() === "-")) {
125
137
  throw new Error("--target - is only valid with register update");
126
138
  }
@@ -150,6 +162,7 @@ export function registerCreateCommands(reg, dependencies) {
150
162
  type: opts.type,
151
163
  title: opts.title,
152
164
  description: opts.description,
165
+ inputs: normalizeRegisterInput(opts.input),
153
166
  priority: opts.priority,
154
167
  ...(opts.difficulty !== undefined ? { difficulty: opts.difficulty } : {}),
155
168
  status: opts.status,
@@ -165,6 +178,8 @@ export function registerCreateCommands(reg, dependencies) {
165
178
  ? { targetRulebook: opts.targetRulebook.trim() }
166
179
  : {}),
167
180
  ...(sources !== undefined ? { sources } : {}),
181
+ ...(opts.commitType !== undefined ? { commitType: opts.commitType } : {}),
182
+ ...(commitScope !== undefined ? { commitScope } : {}),
168
183
  };
169
184
  const templatePath = resolveSpecdojoTemplatePath(`pjr-${opts.type}-template.md`);
170
185
  const { assignedId: displayId, ticketFilename } = planRegisterItem({
@@ -256,9 +271,12 @@ export function registerUpdateCommand(reg, dependencies) {
256
271
  updateCmd.option("--target-rulebook <doc-id>", "Replace deliverable rulebook id; use - to remove");
257
272
  updateCmd.option("--approach <approach>", `Update execution approach (${APPROACHES.join(" | ")}; use - to remove)`);
258
273
  updateCmd.option("--target <target>", "Replace target document ids (repeatable; legacy authoring exemplars may follow; use - to remove)", collectTarget);
274
+ updateCmd.option("--input <text>", "Replace ticket premises (repeatable; use - to remove)", collectTarget);
259
275
  updateCmd.option("--source <ref>", "Replace read-only *-authoring exemplars (repeatable; use - to remove)", collectTarget);
260
276
  updateCmd.option("--from <item-id>", "Replace source register item IDs (repeatable; use - to remove)", collectTarget);
261
277
  updateCmd.option("--depends-on <item-id>", "Replace predecessor IDs (repeatable; use - to remove)", collectTarget);
278
+ updateCmd.option("--commit-type <type>", `Update Conventional Commits type (${VALID_COMMIT_TYPES.join(" | ")}; use - to remove)`);
279
+ updateCmd.option("--commit-scope <scope>", "Update Conventional Commits scope; use - to remove");
262
280
  updateCmd.option("--topic <topic>", "Update the topic slug in the ticket filename and document ID");
263
281
  updateCmd.option("--by <actor>", "Actor recorded in the append-only register event");
264
282
  updateCmd.option("--reason <text>", "Reason recorded in the append-only register event");
@@ -283,14 +301,17 @@ export function registerUpdateCommand(reg, dependencies) {
283
301
  "approach",
284
302
  "target",
285
303
  "source",
304
+ "input",
286
305
  "targetPath",
287
306
  "targetRulebook",
288
307
  "from",
289
308
  "dependsOn",
309
+ "commitType",
310
+ "commitScope",
290
311
  "topic",
291
312
  ].some((key) => opts[key] !== undefined);
292
313
  if (!hasUpdates) {
293
- throw new Error("At least one field option must be specified (--track, --title, --description, --priority, --difficulty, --owner, --due, --conclusion, --block-reason, --autopilot, --approach, --target, --source, --from, --depends-on, --topic)");
314
+ throw new Error("At least one field option must be specified (--track, --title, --description, --priority, --difficulty, --owner, --due, --conclusion, --block-reason, --autopilot, --approach, --target, --source, --input, --from, --depends-on, --commit-type, --commit-scope, --topic)");
294
315
  }
295
316
  if (opts.priority !== undefined &&
296
317
  !VALID_PRIORITIES.includes(opts.priority)) {
@@ -304,6 +325,15 @@ export function registerUpdateCommand(reg, dependencies) {
304
325
  if (opts.due !== undefined && !/^(\d{4}-\d{2}-\d{2}|-|_TODO_)$/.test(opts.due)) {
305
326
  throw new Error(`Invalid due: "${opts.due}". Must be YYYY-MM-DD, -, or _TODO_`);
306
327
  }
328
+ if (opts.commitType !== undefined &&
329
+ opts.commitType !== "-" &&
330
+ !VALID_COMMIT_TYPES.includes(opts.commitType)) {
331
+ throw new Error(`Invalid commit type: "${opts.commitType}". Must be one of: ${VALID_COMMIT_TYPES.join(", ")}, -`);
332
+ }
333
+ const commitScope = opts.commitScope?.trim();
334
+ if (commitScope !== undefined && commitScope !== "-" && !COMMIT_SCOPE_RE.test(commitScope)) {
335
+ throw new Error(`Invalid commit scope: "${commitScope}". Must match ${COMMIT_SCOPE_RE}, or -`);
336
+ }
307
337
  const topic = opts.topic?.trim();
308
338
  if (topic !== undefined && !registerTopicPattern.test(topic)) {
309
339
  throw new Error(`Invalid topic: "${topic}". Must use lowercase letters, numbers, and single hyphens`);
@@ -436,11 +466,23 @@ export function registerUpdateCommand(reg, dependencies) {
436
466
  derived_from: nextDerivedFrom ?? REMOVE_REGISTER_ITEM_FIELD,
437
467
  }
438
468
  : {}),
469
+ ...(opts.commitType !== undefined
470
+ ? {
471
+ commit_type: opts.commitType === "-" ? REMOVE_REGISTER_ITEM_FIELD : opts.commitType,
472
+ }
473
+ : {}),
474
+ ...(commitScope !== undefined
475
+ ? {
476
+ commit_scope: commitScope === "-" ? REMOVE_REGISTER_ITEM_FIELD : commitScope,
477
+ }
478
+ : {}),
439
479
  };
440
480
  const track = opts.track === undefined ? item.track : opts.track.trim();
441
481
  validateRegisterTrack(paths.projectId, item.type, track);
482
+ const inputs = normalizeRegisterInput(opts.input, true);
442
483
  const updated = {
443
484
  ...item,
485
+ ...(inputs !== undefined ? { inputs } : {}),
444
486
  ...(track !== undefined ? { track } : {}),
445
487
  ...(opts.title !== undefined ? { title: opts.title } : {}),
446
488
  ...(opts.description !== undefined ? { description: opts.description } : {}),
@@ -451,9 +493,17 @@ export function registerUpdateCommand(reg, dependencies) {
451
493
  ...(opts.owner !== undefined ? { owner: opts.owner } : {}),
452
494
  ...(opts.due !== undefined ? { due: opts.due } : {}),
453
495
  ...(opts.conclusion !== undefined ? { conclusion: opts.conclusion } : {}),
496
+ ...(opts.commitType !== undefined && opts.commitType !== "-"
497
+ ? { commitType: opts.commitType }
498
+ : {}),
499
+ ...(commitScope !== undefined && commitScope !== "-" ? { commitScope } : {}),
454
500
  };
455
501
  if (opts.difficulty === "-")
456
502
  delete updated.difficulty;
503
+ if (opts.commitType === "-")
504
+ delete updated.commitType;
505
+ if (commitScope === "-")
506
+ delete updated.commitScope;
457
507
  if (opts.autopilot !== undefined) {
458
508
  if (opts.autopilot === "-")
459
509
  delete updated.autopilot;
@@ -517,6 +567,7 @@ export function registerUpdateCommand(reg, dependencies) {
517
567
  id: opts.id,
518
568
  topic,
519
569
  updated,
570
+ ...(inputs !== undefined ? { inputs } : {}),
520
571
  dryRun: opts.dryRun,
521
572
  ...(blockReasonUpdates ||
522
573
  autopilotUpdates ||
@@ -541,6 +592,7 @@ export function registerUpdateCommand(reg, dependencies) {
541
592
  paths,
542
593
  view,
543
594
  updated,
595
+ ...(inputs !== undefined ? { inputs } : {}),
544
596
  dryRun: opts.dryRun,
545
597
  action: "fields updated",
546
598
  ...(opts.title !== undefined ? { title: opts.title } : {}),
@@ -10,6 +10,7 @@ import { loadConfig } from "../shared/specdojo-config.js";
10
10
  import { parsePracticeId } from "../shared/practice-id.js";
11
11
  import { load } from "../shared/yaml.js";
12
12
  export const CATALOG_LESS_APPROACHES = [
13
+ "draft",
13
14
  "fully-guided",
14
15
  "recipe-guided",
15
16
  "freeform",
@@ -47,6 +48,28 @@ export function validateDeliverablePath(root, value) {
47
48
  }
48
49
  return path;
49
50
  }
51
+ export function validateDeliverableTargetPath(repoRoot, targetId, targetPath, docIndexEntries) {
52
+ const entries = docIndexEntries ?? collectDocIndexEntries(resolve(repoRoot, "docs"), repoRoot);
53
+ const indexed = entries[targetId]?.replace(/:\d+$/, "");
54
+ const indexedPath = indexed ? relative(repoRoot, resolve(repoRoot, indexed)) : undefined;
55
+ if (!targetPath && !indexedPath) {
56
+ throw new Error(`Target ${targetId} is not indexed; specify --target-path and --target-rulebook (catalog_path is not configured)`);
57
+ }
58
+ const path = validateDeliverablePath(repoRoot, targetPath ?? indexedPath ?? "");
59
+ if (indexedPath && path !== validateDeliverablePath(repoRoot, indexedPath)) {
60
+ throw new Error(`--target-path conflicts with the indexed document ${targetId}: ${indexedPath}`);
61
+ }
62
+ const absolute = resolve(repoRoot, path);
63
+ const existing = existsSync(absolute);
64
+ const fm = existing ? metadata(absolute) : {};
65
+ if (existing && fm.id !== targetId) {
66
+ throw new Error(`--target-path is occupied by another document: ${path} (expected ${targetId})`);
67
+ }
68
+ if (AUTHORING_KINDS.includes(fm.type)) {
69
+ throw new Error(`Target ${targetId} is a kata, not a deliverable`);
70
+ }
71
+ return path;
72
+ }
50
73
  export function resolveRegisterDeliverableTarget(opts) {
51
74
  if (opts.catalogPath) {
52
75
  try {
@@ -65,26 +88,10 @@ export function resolveRegisterDeliverableTarget(opts) {
65
88
  throw new Error(`Approach "${opts.approach}" requires a deliverable target from the project catalog (catalog_path)`);
66
89
  }
67
90
  const entries = collectDocIndexEntries(resolve(opts.repoRoot, "docs"), opts.repoRoot);
68
- const indexed = entries[opts.targetId]?.replace(/:\d+$/, "");
69
- const indexedPath = indexed
70
- ? relative(opts.repoRoot, resolve(opts.repoRoot, indexed))
71
- : undefined;
72
- if (!opts.targetPath && !indexedPath) {
73
- throw new Error(`Target ${opts.targetId} is not indexed; specify --target-path and --target-rulebook (catalog_path is not configured)`);
74
- }
75
- const path = validateDeliverablePath(opts.repoRoot, opts.targetPath ?? indexedPath ?? "");
76
- if (indexedPath && path !== validateDeliverablePath(opts.repoRoot, indexedPath)) {
77
- throw new Error(`--target-path conflicts with the indexed document ${opts.targetId}: ${indexedPath}`);
78
- }
91
+ const path = validateDeliverableTargetPath(opts.repoRoot, opts.targetId, opts.targetPath, entries);
79
92
  const absolute = resolve(opts.repoRoot, path);
80
93
  const existing = existsSync(absolute);
81
94
  const fm = existing ? metadata(absolute) : {};
82
- if (existing && fm.id !== opts.targetId) {
83
- throw new Error(`--target-path is occupied by another document: ${path} (expected ${opts.targetId})`);
84
- }
85
- if (AUTHORING_KINDS.includes(fm.type)) {
86
- throw new Error(`Target ${opts.targetId} is a kata, not a deliverable`);
87
- }
88
95
  const declaredRulebook = typeof fm.rulebook === "string" ? fm.rulebook : undefined;
89
96
  if (opts.targetRulebook && declaredRulebook && opts.targetRulebook !== declaredRulebook) {
90
97
  throw new Error(`--target-rulebook conflicts with specdojo.rulebook of ${opts.targetId}: ${declaredRulebook}`);
@@ -180,6 +180,10 @@ function fieldUpdateFromChange(change) {
180
180
  : value === "approved"
181
181
  ? { autopilot: "approved" }
182
182
  : undefined;
183
+ case "commit_type":
184
+ return isUnset ? { commit_type: REMOVE_REGISTER_ITEM_FIELD } : { commit_type: value };
185
+ case "commit_scope":
186
+ return isUnset ? { commit_scope: REMOVE_REGISTER_ITEM_FIELD } : { commit_scope: value };
183
187
  default:
184
188
  return undefined;
185
189
  }
@@ -12,6 +12,7 @@ export const REGISTER_EVENT_FIELDS = [
12
12
  "status",
13
13
  "title",
14
14
  "description",
15
+ "input",
15
16
  "type",
16
17
  "track",
17
18
  "priority",
@@ -30,6 +31,8 @@ export const REGISTER_EVENT_FIELDS = [
30
31
  "derived_from",
31
32
  "depends_on",
32
33
  "autopilot",
34
+ "commit_type",
35
+ "commit_scope",
33
36
  ];
34
37
  export const REGISTER_EVENT_ACTIONS = [
35
38
  "add",
@@ -70,6 +73,7 @@ export function registerEventFieldValues(content, filename, timeZone) {
70
73
  status: item.status,
71
74
  title: item.title,
72
75
  description: item.description,
76
+ input: item.inputs?.length ? JSON.stringify(item.inputs) : CELL_NONE,
73
77
  type: item.type,
74
78
  track: item.track ?? CELL_NONE,
75
79
  priority: item.priority,
@@ -88,6 +92,8 @@ export function registerEventFieldValues(content, filename, timeZone) {
88
92
  derived_from: item.derivedFrom ? JSON.stringify(item.derivedFrom) : CELL_NONE,
89
93
  depends_on: item.dependsOn ? JSON.stringify(item.dependsOn) : CELL_NONE,
90
94
  autopilot: item.autopilot ?? CELL_NONE,
95
+ commit_type: item.commitType ?? CELL_NONE,
96
+ commit_scope: item.commitScope ?? CELL_NONE,
91
97
  };
92
98
  }
93
99
  function isUnsetFieldValue(value) {
@@ -44,6 +44,8 @@ export function buildExternalRegisterAddArgs(alias, externalProject, opts) {
44
44
  addValue(args, "--difficulty", opts.difficulty);
45
45
  addValue(args, "--registered", opts.registered);
46
46
  addValue(args, "--approach", opts.approach);
47
+ for (const input of opts.input ?? [])
48
+ addValue(args, "--input", input);
47
49
  for (const target of opts.target ?? [])
48
50
  addValue(args, "--target", target);
49
51
  for (const source of opts.source ?? [])