specdojo 0.4.4 → 0.4.5

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 (28) hide show
  1. package/CHANGELOG.md +6 -0
  2. package/dist/exec/plans-core.js +11 -0
  3. package/dist/exec/plans-generation.js +1 -1
  4. package/dist/exec/register.js +47 -14
  5. package/dist/exec/run/in-place.js +7 -4
  6. package/dist/exec/run/register-core.js +10 -2
  7. package/dist/exec/run/register-worktree.js +4 -1
  8. package/dist/exec/task-repos.js +11 -0
  9. package/dist/register/approach.js +13 -12
  10. package/dist/register/authoring-sources.js +132 -0
  11. package/dist/register/core.js +1 -0
  12. package/dist/register/create-commands.js +77 -10
  13. package/dist/register/events.js +2 -0
  14. package/dist/register/external-project.js +11 -1
  15. package/dist/register/item.js +6 -0
  16. package/dist/register/renumber.js +3 -3
  17. package/docs/ja/specdojo/exec-templates/xep-recipe-authoring-template.md +7 -7
  18. package/docs/ja/specdojo/exec-templates/xep-rulebook-authoring-template.md +7 -7
  19. package/docs/ja/specdojo/exec-templates/xep-sample-authoring-template.md +7 -7
  20. package/docs/ja/specdojo/exec-templates/xep-template-authoring-template.md +7 -7
  21. package/docs/ja/specdojo/guides/kata-guide.md +3 -1
  22. package/docs/ja/specdojo/guides/quick-start-guide.md +4 -2
  23. package/docs/ja/specdojo/references/command-reference.md +29 -24
  24. package/docs/specdojo/schemas/v1/exec-plan-frontmatter.schema.yaml +4 -3
  25. package/docs/specdojo/schemas/v1/exec-result-frontmatter.schema.yaml +3 -3
  26. package/docs/specdojo/schemas/v1/register-events.schema.yaml +1 -0
  27. package/docs/specdojo/schemas/v1/register-item-frontmatter.schema.yaml +31 -3
  28. package/package.json +4 -3
package/CHANGELOG.md CHANGED
@@ -2,6 +2,12 @@
2
2
 
3
3
  SpecDojo の利用者に影響する変更を記録します。
4
4
 
5
+ ## [0.4.5] - 2026-10-24
6
+
7
+ ### 追加機能
8
+
9
+ - kata authoring の手本を `register add` / `register update` の繰り返し可能な `--source` で指定できるようにしました。文書索引の doc id、プロジェクトリポジトリのファイル・ディレクトリ・glob、`repos` で宣言したプロダクトリポジトリの `<repo>:<path>` を使え、カタログがない project でも authoring plan を生成できます(PJR-ZV60)。
10
+
5
11
  ## [0.4.4] - 2026-10-24
6
12
 
7
13
  ### 変更
@@ -149,6 +149,17 @@ export function resolveDeliverableByDocId(catalogPath, projectId, targetId) {
149
149
  }
150
150
  return matches[0];
151
151
  }
152
+ /** Resolve a project-repository-relative file path to its catalog entry, if any. */
153
+ export function findDeliverableByPath(catalogPath, targetPath) {
154
+ const normalized = targetPath.replaceAll("\\", "/").replace(/^\/+/, "");
155
+ const matches = resolvedDeliverablesInCatalog(catalogPath).filter((target) => target.info.resolvedPath.replaceAll("\\", "/").replace(/^\/+/, "") === normalized);
156
+ if (matches.length > 1) {
157
+ throw new Error(`ambiguous catalog deliverable target for path ${targetPath}: ${matches
158
+ .map((match) => match.localId)
159
+ .join(", ")}`);
160
+ }
161
+ return matches[0] ?? null;
162
+ }
152
163
  // A kata may be declared by zero, one, or several deliverables. Only a unique declaration is
153
164
  // used as the maintenance plan's evidence context; otherwise the explicitly targeted kata remains
154
165
  // executable without selecting an arbitrary deliverable.
@@ -65,7 +65,7 @@ function buildEditPlanMarkdown(template, task, deliverable, roleMap, vpMap, proj
65
65
  _AUTHORING_STANDARD_ID_: planOverrides?.authoring?.standardId ?? MISSING,
66
66
  _AUTHORING_STANDARD_PATH_: planOverrides?.authoring?.standardPath ?? MISSING,
67
67
  _AUTHORING_EXEMPLARS_: planOverrides?.authoring?.exemplars
68
- .map((example) => `- \`${example.id}\`: ${example.name}(\`${example.path}\`、現在の参照: \`${example.currentReference}\`)`)
68
+ .map((example) => `- \`${example.id}\`: ${example.name}(\`${example.path}\`、${example.catalog ? "現在の参照" : "参照更新"}: \`${example.currentReference}\`)`)
69
69
  .join("\n") || "- なし(kata だけを新規作成する)",
70
70
  };
71
71
  const body = expandTemplate(template, values);
@@ -1,9 +1,9 @@
1
1
  import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
2
- import { extname, join, relative, resolve } from "node:path";
2
+ import { basename, extname, join, relative, resolve } from "node:path";
3
3
  import { findRegisterItem, loadRegisterItems, PJR_ID_RE, resolveRegisterPaths, TERMINAL_STATUSES_SET, VALID_PRIORITIES, VALID_STATUSES, VALID_TYPES, } from "../register/register.js";
4
4
  import { execTemplatePath, injectCommonConventions, MISSING, registerGradeFindingsText, } from "./plans.js";
5
5
  import { generateRegisterApproachPlan } from "./plans-generation.js";
6
- import { findUniqueDeliverableForKataTarget, resolveDeliverableByDocId, } from "./plans-core.js";
6
+ import { findUniqueDeliverableForKataTarget, findDeliverableByPath, resolveDeliverableByDocId, } from "./plans-core.js";
7
7
  import { collectDocIndexEntries } from "../docs/doc-index.js";
8
8
  import { loadRulebookRefs, resolveKataRefs } from "../kata/kata.js";
9
9
  import { authoredKataPath, authoringKind, authoringStandardId, authoringStandardPath, } from "../kata/authoring.js";
@@ -11,7 +11,9 @@ import { validateRegisterApproachTargets } from "../register/approach.js";
11
11
  import { buildSpecdojoFrontmatter } from "../docs/frontmatter-namespace.js";
12
12
  import { escapeMarkdownInline, expandTemplate, inlineCodeAnglePlaceholders, stripTerminalControlSequences, } from "./shared.js";
13
13
  import { formatMarkdownFile } from "./format.js";
14
- import { specdojoRootDir } from "../shared/specdojo-config.js";
14
+ import { loadConfig, specdojoRootDir } from "../shared/specdojo-config.js";
15
+ import { resolveAuthoringSources, } from "../register/authoring-sources.js";
16
+ import { repoEnvironmentVariableName } from "./task-repos.js";
15
17
  const EDIT_TYPES = new Set(["todo", "issue", "change-request"]);
16
18
  const INVESTIGATE_TYPES = new Set(["question", "risk"]);
17
19
  export function registerItemCategory(itemType) {
@@ -302,6 +304,26 @@ function indexedDocumentPath(targetId) {
302
304
  const withoutLine = indexed.replace(/:\d+$/, "");
303
305
  return relative(repoRoot, resolve(repoRoot, withoutLine)).replace(/\\/g, "/");
304
306
  }
307
+ function authoringSourcePlanPath(source) {
308
+ return source.repo ? `$${repoEnvironmentVariableName(source.repo)}/${source.path}` : source.path;
309
+ }
310
+ function catalogSource(catalogPath, projectId, source) {
311
+ if (!catalogPath || source.repo)
312
+ return null;
313
+ if (source.documentId) {
314
+ try {
315
+ return resolveDeliverableByDocId(catalogPath, projectId, source.documentId);
316
+ }
317
+ catch (error) {
318
+ if (error instanceof Error &&
319
+ error.message.startsWith("catalog deliverable target not found")) {
320
+ return null;
321
+ }
322
+ throw error;
323
+ }
324
+ }
325
+ return findDeliverableByPath(catalogPath, source.path);
326
+ }
305
327
  export async function generateRegisterPlan(opts) {
306
328
  const { item } = opts;
307
329
  const category = requireRunnableRegisterItem(item);
@@ -313,6 +335,7 @@ export async function generateRegisterPlan(opts) {
313
335
  ...(opts.catalogPath ? { catalogPath: opts.catalogPath } : {}),
314
336
  approach: item.approach,
315
337
  targets: item.targets,
338
+ sources: item.sources,
316
339
  });
317
340
  const [targetId] = item.targets ?? [];
318
341
  if (!targetId)
@@ -323,14 +346,22 @@ export async function generateRegisterPlan(opts) {
323
346
  let refs;
324
347
  let authoring;
325
348
  if (newKataKind) {
326
- const examples = (item.targets ?? []).slice(1).map((exampleId) => {
327
- if (!opts.catalogPath) {
328
- throw new Error(`Register item ${item.id} approach requires catalog_path to resolve ${exampleId}.`);
329
- }
330
- const resolved = resolveDeliverableByDocId(opts.catalogPath, opts.projectId, exampleId).info;
331
- const rulebookId = resolved.deliverable.rulebook;
349
+ const sourceRefs = [...(item.targets ?? []).slice(1), ...(item.sources ?? [])];
350
+ const project = loadConfig(specdojoRootDir()).config?.projects[opts.projectId] ?? {};
351
+ const resolvedSources = resolveAuthoringSources({
352
+ repoRoot: specdojoRootDir(),
353
+ project,
354
+ sources: sourceRefs,
355
+ });
356
+ const examples = resolvedSources.map((source) => {
357
+ const catalogEntry = catalogSource(opts.catalogPath, opts.projectId, source);
358
+ const resolved = catalogEntry?.info;
359
+ const rulebookId = resolved?.deliverable.rulebook;
332
360
  let currentReference;
333
- if (newKataKind === "rulebook") {
361
+ if (!resolved) {
362
+ currentReference = "カタログ外のため参照の付け替え対象外";
363
+ }
364
+ else if (newKataKind === "rulebook") {
334
365
  currentReference = rulebookId ?? "未記入";
335
366
  }
336
367
  else if (!rulebookId ||
@@ -345,11 +376,13 @@ export async function generateRegisterPlan(opts) {
345
376
  ? declaredReference.join(", ")
346
377
  : (declaredReference ?? "未記入");
347
378
  }
379
+ const planPath = authoringSourcePlanPath(source);
348
380
  return {
349
- id: exampleId,
350
- name: resolved.deliverable.name,
351
- path: resolved.resolvedPath,
381
+ id: source.documentId ?? (source.repo ? `${source.repo}:${source.path}` : source.path),
382
+ name: resolved?.deliverable.name ?? basename(source.path),
383
+ path: planPath,
352
384
  currentReference,
385
+ catalog: resolved !== undefined,
353
386
  };
354
387
  });
355
388
  const exemplarExtension = extname(examples[0]?.path ?? "").slice(1);
@@ -396,7 +429,7 @@ export async function generateRegisterPlan(opts) {
396
429
  description: item.description,
397
430
  ...(item.owner && item.owner !== "-" && item.owner !== "_TODO_" ? { owner: item.owner } : {}),
398
431
  approach: item.approach,
399
- targets: item.targets ?? [],
432
+ targets: targetId ? [targetId] : [],
400
433
  deliverable,
401
434
  ...(refs ? { refs } : {}),
402
435
  ...(authoring ? { authoring } : {}),
@@ -20,6 +20,7 @@ import { pinnedExecutor, pinnedReporter, resolvePinnedRateLimitRunOptions, resol
20
20
  import { appendParentValidationsToExecutorEvidence, buildExecutorPrompt, executorRequirements, expandPromptRefs, extractBlockReason, loadRosterForExecutionPath, reportProtectionHandoffRecord, resolveReporterAgentCandidates, runWithRetry, } from "./agent.js";
21
21
  import { gradeBeforeReviewPlan } from "./schedule-prepare.js";
22
22
  import { pipelineRecoveryMeta, spawnBlock, spawnClaim, spawnComplete } from "./mode-shared.js";
23
+ import { configuredProductCheckouts, productRepoEnvironment, withoutInheritedRepoEnvironment, withAgentExtraRoots, } from "../task-repos.js";
23
24
  // Resolve the agent command and the actor for an in-place run, ignoring task state. Unlike the
24
25
  // worktree flow, this never requires the task to be claimable. The actor is derived the same way
25
26
  // as the worktree path (`prepareTask`): explicit --by wins, otherwise the resolved member's
@@ -102,15 +103,17 @@ export function resolveInPlaceAgentPipeline(task, roster, opts, source) {
102
103
  }
103
104
  return undefined;
104
105
  }
105
- export async function spawnAgentInPlace(command, prompt, cwd, schedulePath, executionPath, resultPath) {
106
+ export async function spawnAgentInPlace(command, prompt, cwd, schedulePath, executionPath, resultPath, provider) {
106
107
  const protectedConfigBefore = captureAgentProtectedConfigSnapshot(cwd);
107
108
  const gitStateBefore = captureAgentGitStateSnapshot(cwd);
108
- const child = spawn(command, {
109
+ const products = configuredProductCheckouts(schedulePath);
110
+ const child = spawn(withAgentExtraRoots(command, provider, products.map((product) => product.path)), {
109
111
  cwd,
110
112
  env: {
111
- ...gitEnvironment(),
113
+ ...withoutInheritedRepoEnvironment(gitEnvironment()),
112
114
  SPECDOJO_SCHEDULE_PATH: schedulePath,
113
115
  SPECDOJO_EXECUTION_PATH: executionPath,
116
+ ...productRepoEnvironment(cwd, products),
114
117
  },
115
118
  shell: true,
116
119
  stdio: ["pipe", "inherit", "inherit"],
@@ -518,7 +521,7 @@ export async function runInPlaceMode(opts) {
518
521
  }
519
522
  }
520
523
  else {
521
- exitCode = await spawnAgentInPlace(command, prompt, repoRoot, schedulePath, executionPath, resultPath);
524
+ exitCode = await spawnAgentInPlace(command, prompt, repoRoot, schedulePath, executionPath, resultPath, provider);
522
525
  }
523
526
  // Some agents (notably `claude -p`) exit 0 even when they conclude they are blocked: a
524
527
  // permission-denied tool call is fed back as a tool error and the model ends its turn
@@ -14,6 +14,8 @@ import { expandPromptRefs } from "./agent.js";
14
14
  import { runAgentPipeline } from "./agent-pipeline.js";
15
15
  import { spawnAgentInPlace } from "./in-place.js";
16
16
  import { commitSubject, repoRelativePath, spawnSelf } from "./mode-shared.js";
17
+ import { isAuthoringApproach } from "../../kata/authoring.js";
18
+ import { configuredProductCheckouts } from "../task-repos.js";
17
19
  // CLI choices are the highest-priority layer. A difficulty route only supplies omitted stage and
18
20
  // recovery options; without a matching route the historical priority-based selection is kept.
19
21
  export function applyRegisterDifficultyRouting(item, opts, execDefaults) {
@@ -254,6 +256,9 @@ export async function runSingleRegisterItem(context, opts, pjrId) {
254
256
  const { command, actor } = pipelineAgents
255
257
  ? { command: pipelineAgents.executor.command, actor: pipelineAgents.executor.actor }
256
258
  : resolveRegisterCommand(item, context.roster, opts, context.execDefaults);
259
+ const resolvedProvider = pipelineAgents
260
+ ? pipelineAgents.executor.provider
261
+ : resolveAgentMember(context.roster, actor)?.provider;
257
262
  const stem = buildInPlaceStem(pjrId.toLowerCase());
258
263
  // ID単位 commit のため、この項目が変更を生じる前の作業ツリー状態を記録する。
259
264
  const preexisting = context.registerCommit ? worktreeStatusPaths(repoRoot) : [];
@@ -285,7 +290,9 @@ export async function runSingleRegisterItem(context, opts, pjrId) {
285
290
  startedAt: new Date().toISOString(),
286
291
  stem,
287
292
  ...(item.approach ? { approach: item.approach } : {}),
288
- ...(item.targets && item.targets.length > 0 ? { targets: item.targets } : {}),
293
+ ...(item.targets && item.targets.length > 0
294
+ ? { targets: isAuthoringApproach(item.approach) ? item.targets.slice(0, 1) : item.targets }
295
+ : {}),
289
296
  });
290
297
  const resultScaffold = readResultFrontmatterSnapshot(resultPath);
291
298
  process.stdout.write(`Register item: ${item.id} — ${item.title} [${item.type}]\n`);
@@ -314,6 +321,7 @@ export async function runSingleRegisterItem(context, opts, pjrId) {
314
321
  resultPath,
315
322
  registerPaths: registerReporterManagedPaths(registerPaths),
316
323
  execDefaults: context.execDefaults,
324
+ productWorktrees: configuredProductCheckouts(schedulePath),
317
325
  providerConcurrencyGate: context.providerConcurrencyGate,
318
326
  executorRateLimitOptions: opts.executorBy
319
327
  ? resolvePinnedRateLimitRunOptions(opts, context.execDefaults, context.roster, "executor", pipelineAgents.executor)
@@ -331,7 +339,7 @@ export async function runSingleRegisterItem(context, opts, pjrId) {
331
339
  }
332
340
  else {
333
341
  process.stdout.write(`Running ${item.id} in place: ${command}\n`);
334
- exitCode = await spawnAgentInPlace(command, prompt, repoRoot, schedulePath, executionPath, resultPath);
342
+ exitCode = await spawnAgentInPlace(command, prompt, repoRoot, schedulePath, executionPath, resultPath, resolvedProvider);
335
343
  }
336
344
  // in-place 実行と同じ補助判定: agent が result 必須節を埋めずに終了コード 0 で
337
345
  // 終わった場合は block として扱う(runInPlaceMode と同じ理由)。pipeline モードでは
@@ -12,6 +12,7 @@ import { commitProductWorktrees, integrateTaskRepositories, projectMergeBlockers
12
12
  import { productIntegrationTrace, recordResultTrace, refsTrailer, registerProjectMergeMessage, traceKey, withCommitTrailers, } from "../repo-trace.js";
13
13
  import { pipelineStateLocation, readPipelineState } from "../pipeline-state.js";
14
14
  import { findResumableRegisterRun } from "../register-resume.js";
15
+ import { isAuthoringApproach } from "../../kata/authoring.js";
15
16
  import { resolvePinnedRateLimitRunOptions, rateLimitRecoveryReason, } from "./shared.js";
16
17
  import { agentEnvironment, expandPromptRefs, extractBlockReason, pathInsideWorktree, reportProductWorktrees, runWithRetry, } from "./agent.js";
17
18
  import { runAgentPipeline } from "./agent-pipeline.js";
@@ -464,7 +465,9 @@ export async function runSingleRegisterItemWorktree(context, opts, pjrId, lifecy
464
465
  startedAt: new Date().toISOString(),
465
466
  stem,
466
467
  ...(item.approach ? { approach: item.approach } : {}),
467
- ...(item.targets && item.targets.length > 0 ? { targets: item.targets } : {}),
468
+ ...(item.targets && item.targets.length > 0
469
+ ? { targets: isAuthoringApproach(item.approach) ? item.targets.slice(0, 1) : item.targets }
470
+ : {}),
468
471
  });
469
472
  const resultScaffold = readResultFrontmatterSnapshot(resultPath);
470
473
  process.stdout.write(`Register item: ${item.id} — ${item.title} [${item.type}]\n`);
@@ -92,6 +92,17 @@ export function configuredProductRepos(schedulePath, integrationBranches) {
92
92
  }
93
93
  return [];
94
94
  }
95
+ /** Declared product repositories represented as their current in-place checkouts. */
96
+ export function configuredProductCheckouts(schedulePath) {
97
+ return configuredProductRepos(schedulePath).map((product) => ({
98
+ name: product.name,
99
+ repoRoot: product.repoRoot,
100
+ path: product.repoRoot,
101
+ branch: productIntegrationTarget(product),
102
+ created: false,
103
+ ...(product.integrationBranch ? { integrationBranch: product.integrationBranch } : {}),
104
+ }));
105
+ }
95
106
  /**
96
107
  * Run-scoped `--integration-branch` values recorded in the run checkpoint (`integration_branches`).
97
108
  * Only explicit overrides are recorded, so a run without the option keeps resolving its targets
@@ -4,10 +4,11 @@ import { collectResolvedDeliverables, loadCatalogDocs } from "../catalog/build.j
4
4
  import { resolveBasePath } from "../catalog/paths.js";
5
5
  import { collectDocIndexEntries } from "../docs/doc-index.js";
6
6
  import { readSpecdojoNamespace } from "../docs/frontmatter-namespace.js";
7
- import { getProjectCatalogPath, loadConfig, specdojoRootDir } from "../shared/specdojo-config.js";
7
+ import { getProjectCatalogPath, loadConfig, specdojoRootDir, } from "../shared/specdojo-config.js";
8
8
  import { APPROACHES } from "../shared/agent-types.js";
9
9
  import { load } from "../shared/yaml.js";
10
10
  import { assertAuthorableKataId, authoredKataExists, authoringKind } from "../kata/authoring.js";
11
+ import { resolveAuthoringSources } from "./authoring-sources.js";
11
12
  const MAINTENANCE_TARGET_KIND = {
12
13
  "rulebook-maintenance": "rulebook",
13
14
  "recipe-maintenance": "recipe",
@@ -70,6 +71,7 @@ function targetDocumentType(path) {
70
71
  export function validateRegisterApproachTargets(opts) {
71
72
  const approachText = opts.approach?.trim();
72
73
  const targets = [...new Set((opts.targets ?? []).map((target) => target.trim()).filter(Boolean))];
74
+ const sources = [...new Set((opts.sources ?? []).map((source) => source.trim()).filter(Boolean))];
73
75
  let approach;
74
76
  if (approachText !== undefined) {
75
77
  if (!APPROACHES.includes(approachText)) {
@@ -84,6 +86,9 @@ export function validateRegisterApproachTargets(opts) {
84
86
  throw new Error(`Approach "${approach}" requires the new kata id as the first --target`);
85
87
  }
86
88
  }
89
+ if (sources.length > 0 && !authoringKind(approach)) {
90
+ throw new Error("--source is only valid with a *-authoring approach");
91
+ }
87
92
  if (!approach && !opts.validateTargetsWithoutApproach)
88
93
  return;
89
94
  if (targets.length === 0)
@@ -99,7 +104,7 @@ export function validateRegisterApproachTargets(opts) {
99
104
  }
100
105
  const authoringTargetKind = authoringKind(approach);
101
106
  if (authoringTargetKind) {
102
- const [kataId, ...exampleIds] = targets;
107
+ const [kataId, ...legacySources] = targets;
103
108
  if (!kataId) {
104
109
  throw new Error(`Approach "${approach}" requires the new kata id as the first --target`);
105
110
  }
@@ -107,17 +112,11 @@ export function validateRegisterApproachTargets(opts) {
107
112
  if (entries[kataId] || authoredKataExists(kataId, opts.repoRoot)) {
108
113
  throw new Error(`Kata id ${kataId} already exists; use ${authoringTargetKind}-maintenance instead`);
109
114
  }
110
- if (exampleIds.length === 0)
115
+ const sourceRefs = [...new Set([...legacySources, ...sources])];
116
+ if (sourceRefs.length === 0)
111
117
  return;
112
- if (!opts.catalogPath) {
113
- throw new Error(`Approach "${approach}" requires catalog_path to resolve exemplar deliverables`);
114
- }
115
- const deliverableDocIds = catalogDeliverableDocIds(opts.catalogPath, opts.repoRoot, opts.projectId);
116
- for (const exampleId of exampleIds) {
117
- if (!deliverableDocIds.has(exampleId)) {
118
- throw new Error(`Approach "${approach}" requires every --target after the first to be a catalog deliverable, but ${exampleId} is not one`);
119
- }
120
- }
118
+ const project = opts.project ?? loadConfig(opts.repoRoot).config?.projects[opts.projectId] ?? {};
119
+ resolveAuthoringSources({ repoRoot: opts.repoRoot, project, sources: sourceRefs });
121
120
  return;
122
121
  }
123
122
  const expectedKind = MAINTENANCE_TARGET_KIND[approach];
@@ -155,6 +154,8 @@ export function validateRegisterApproachTargetsForProject(opts) {
155
154
  ...(catalogPath ? { catalogPath: resolve(repoRoot, catalogPath) } : {}),
156
155
  ...(opts.approach !== undefined ? { approach: opts.approach } : {}),
157
156
  ...(opts.targets !== undefined ? { targets: opts.targets } : {}),
157
+ ...(opts.sources !== undefined ? { sources: opts.sources } : {}),
158
+ project,
158
159
  ...(opts.validateTargetsWithoutApproach !== undefined
159
160
  ? { validateTargetsWithoutApproach: opts.validateTargetsWithoutApproach }
160
161
  : {}),
@@ -0,0 +1,132 @@
1
+ import { existsSync, realpathSync, statSync } from "node:fs";
2
+ import { extname, isAbsolute, posix, relative, resolve, sep } from "node:path";
3
+ import { globSync } from "tinyglobby";
4
+ import { collectDocIndexEntries } from "../docs/doc-index.js";
5
+ import { getProjectRepos, resolveRepoQualifiedRef, resolveRepoRoot, } from "../shared/specdojo-config.js";
6
+ // A bounded source set keeps generated plans reviewable and prevents a broad glob from handing an
7
+ // executor an unexpectedly large read scope. The limit applies after directory/glob expansion and
8
+ // duplicate removal, across all --source values.
9
+ export const MAX_AUTHORING_SOURCE_FILES = 100;
10
+ function normalizedRelativePath(value, label) {
11
+ const slashPath = value.trim().replaceAll("\\", "/");
12
+ if (!slashPath)
13
+ throw new Error(`${label} must not be empty`);
14
+ if (posix.isAbsolute(slashPath) || isAbsolute(slashPath) || /^[A-Za-z]:\//.test(slashPath)) {
15
+ throw new Error(`${label} must be relative: ${value}`);
16
+ }
17
+ const normalized = posix.normalize(slashPath).replace(/^\.\//, "").replace(/\/+$/, "");
18
+ if (!normalized || normalized === "." || normalized === ".." || normalized.startsWith("../")) {
19
+ throw new Error(`${label} escapes its repository root: ${value}`);
20
+ }
21
+ return normalized;
22
+ }
23
+ function assertInsideRoot(root, path, ref) {
24
+ const realRoot = realpathSync(root);
25
+ const realPath = realpathSync(path);
26
+ const fromRoot = relative(realRoot, realPath);
27
+ if (fromRoot === ".." || fromRoot.startsWith(`..${sep}`) || isAbsolute(fromRoot)) {
28
+ throw new Error(`Authoring source resolves outside its repository: ${ref}`);
29
+ }
30
+ }
31
+ function expandPath(root, rawPath, ref) {
32
+ if (!existsSync(root) || !statSync(root).isDirectory()) {
33
+ throw new Error(`Repository root for authoring source does not exist: ${ref}`);
34
+ }
35
+ const normalized = normalizedRelativePath(rawPath, `Authoring source path "${ref}"`);
36
+ const exact = resolve(root, normalized);
37
+ let paths;
38
+ if (existsSync(exact)) {
39
+ assertInsideRoot(root, exact, ref);
40
+ if (statSync(exact).isDirectory()) {
41
+ paths = globSync("**/*", {
42
+ cwd: exact,
43
+ onlyFiles: true,
44
+ dot: false,
45
+ followSymbolicLinks: false,
46
+ ignore: ["**/.git/**", "**/node_modules/**"],
47
+ }).map((entry) => posix.join(normalized, entry.replaceAll("\\", "/")));
48
+ }
49
+ else {
50
+ paths = [normalized];
51
+ }
52
+ }
53
+ else {
54
+ paths = globSync(normalized, {
55
+ cwd: root,
56
+ onlyFiles: true,
57
+ dot: false,
58
+ followSymbolicLinks: false,
59
+ ignore: ["**/.git/**", "**/node_modules/**"],
60
+ }).map((entry) => entry.replaceAll("\\", "/"));
61
+ }
62
+ const sorted = [...new Set(paths)].sort();
63
+ if (sorted.length === 0) {
64
+ throw new Error(`Authoring source did not match any files: ${ref}`);
65
+ }
66
+ for (const path of sorted)
67
+ assertInsideRoot(root, resolve(root, path), ref);
68
+ return sorted;
69
+ }
70
+ function looksLikeProjectPath(ref) {
71
+ const normalized = ref.replaceAll("\\", "/");
72
+ return normalized.includes("/") || extname(posix.basename(normalized)) !== "";
73
+ }
74
+ function indexedDocumentPath(repoRoot, ref) {
75
+ const indexed = collectDocIndexEntries(resolve(repoRoot, "docs"), repoRoot)[ref];
76
+ if (!indexed) {
77
+ throw new Error(`Authoring source document id is not resolvable via the document index: ${ref}`);
78
+ }
79
+ const withoutLine = indexed.replace(/:\d+$/, "");
80
+ const absolute = resolve(repoRoot, withoutLine);
81
+ if (!existsSync(absolute) || !statSync(absolute).isFile()) {
82
+ throw new Error(`Authoring source document does not exist: ${ref} (${withoutLine})`);
83
+ }
84
+ assertInsideRoot(repoRoot, absolute, ref);
85
+ return relative(repoRoot, absolute).replaceAll("\\", "/");
86
+ }
87
+ function configuredRepo(project, name) {
88
+ const repo = getProjectRepos(project).find((candidate) => candidate.name === name);
89
+ if (!repo)
90
+ throw new Error(`Unknown product repository in authoring source: ${name}`);
91
+ return repo;
92
+ }
93
+ export function resolveAuthoringSources(opts) {
94
+ const refs = [...new Set(opts.sources.map((source) => source.trim()).filter(Boolean))];
95
+ const repos = getProjectRepos(opts.project);
96
+ const resolved = [];
97
+ const seen = new Set();
98
+ const append = (source) => {
99
+ const key = `${source.repo ?? "project"}:${source.path}`;
100
+ if (seen.has(key))
101
+ return;
102
+ seen.add(key);
103
+ resolved.push(source);
104
+ if (resolved.length > MAX_AUTHORING_SOURCE_FILES) {
105
+ throw new Error(`Authoring sources expand to more than ${MAX_AUTHORING_SOURCE_FILES} files; narrow the directory or pattern`);
106
+ }
107
+ };
108
+ for (const ref of refs) {
109
+ const qualified = resolveRepoQualifiedRef(ref, repos);
110
+ if (qualified.kind === "repo") {
111
+ const repo = configuredRepo(opts.project, qualified.repo);
112
+ const root = resolveRepoRoot(opts.repoRoot, repo);
113
+ for (const path of expandPath(root, qualified.path, ref)) {
114
+ append({ ref, kind: "repo-path", repo: qualified.repo, path });
115
+ }
116
+ continue;
117
+ }
118
+ if (looksLikeProjectPath(ref)) {
119
+ for (const path of expandPath(opts.repoRoot, ref, ref)) {
120
+ append({ ref, kind: "project-path", path });
121
+ }
122
+ continue;
123
+ }
124
+ append({
125
+ ref,
126
+ kind: "document",
127
+ path: indexedDocumentPath(opts.repoRoot, ref),
128
+ documentId: ref,
129
+ });
130
+ }
131
+ return resolved;
132
+ }
@@ -377,6 +377,7 @@ export function buildRegisterItemContent(opts) {
377
377
  ticket: "-",
378
378
  ...(opts.fields.approach ? { approach: opts.fields.approach } : {}),
379
379
  ...(opts.fields.targets ? { targets: opts.fields.targets } : {}),
380
+ ...(opts.fields.sources ? { sources: opts.fields.sources } : {}),
380
381
  ...(opts.fields.derivedFrom ? { derivedFrom: opts.fields.derivedFrom } : {}),
381
382
  }));
382
383
  }
@@ -9,6 +9,7 @@ import { resolveSpecdojoTemplatePath } from "../docs/template-resolution.js";
9
9
  import { validateRegisterApproachTargetsForProject } from "./approach.js";
10
10
  import { normalizeDerivedFrom, validateDerivedFrom } from "./derivation.js";
11
11
  import { delegateExternalRegisterAdd } from "./external-project.js";
12
+ import { isAuthoringApproach } from "../kata/authoring.js";
12
13
  function collectTarget(value, previous = []) {
13
14
  return [...previous, value];
14
15
  }
@@ -25,6 +26,21 @@ function normalizedTargets(values) {
25
26
  throw new Error("--target must contain a document id");
26
27
  return targets;
27
28
  }
29
+ function normalizedSources(values, allowRemove = false) {
30
+ if (values === undefined)
31
+ return undefined;
32
+ const sources = [...new Set(values.map((value) => value.trim()).filter(Boolean))];
33
+ if (sources.includes("-")) {
34
+ if (!allowRemove)
35
+ throw new Error("--source - is only valid with register update");
36
+ if (sources.length !== 1)
37
+ throw new Error("--source - cannot be combined with other sources");
38
+ return undefined;
39
+ }
40
+ if (sources.length === 0)
41
+ throw new Error("--source must contain a reference");
42
+ return sources;
43
+ }
28
44
  export function registerCreateCommands(reg, dependencies) {
29
45
  const { addProjectOption, addRegisterCommitOptions, atomicWriteFile, buildRegisterItemContent, derivedTopicNeedsWarning, generateDerivedViewFiles, loadRegisterItems, parseRegisterTimestampOption, planRegisterItem, printCommandError, printDerivedTopicWarning, registerEventActor, registerTopicPattern, resolveRegisterPaths, runRegisterMutation, slugify, writeDerivedViews, } = dependencies;
30
46
  // --- scaffold ---
@@ -67,7 +83,8 @@ export function registerCreateCommands(reg, dependencies) {
67
83
  addCmd.option("--completed <datetime>", "Completion date-time (RFC 3339 with time zone, or -)", "-");
68
84
  addCmd.option("--conclusion <text>", "Conclusion or resolution summary", "-");
69
85
  addCmd.option("--approach <approach>", `Execution approach: ${APPROACHES.join(" | ")}`);
70
- addCmd.option("--target <doc-id>", "Target document id (repeatable; approach requires exactly one)", collectTarget);
86
+ addCmd.option("--target <doc-id>", "Target document id (repeatable; authoring accepts legacy exemplar targets after the first)", collectTarget);
87
+ addCmd.option("--source <ref>", "Read-only exemplar for *-authoring (repeatable: doc id, path, or <repo>:<path>)", collectTarget);
71
88
  addCmd.option("--from <item-id>", "Register item this item derives from (repeatable)", collectTarget);
72
89
  addCmd.option("--id <id>", "Display ID (e.g., PJR-0061); auto-incremented if omitted");
73
90
  addCmd.option("--topic <topic>", "Topic slug for ticket filename; derived from --title if omitted");
@@ -101,12 +118,20 @@ export function registerCreateCommands(reg, dependencies) {
101
118
  if (opts.target?.some((target) => target.trim() === "-")) {
102
119
  throw new Error("--target - is only valid with register update");
103
120
  }
104
- const targets = normalizedTargets(opts.target);
121
+ const rawTargets = normalizedTargets(opts.target);
122
+ const authoring = isAuthoringApproach(opts.approach);
123
+ const legacySources = authoring ? (rawTargets ?? []).slice(1) : [];
124
+ const targets = authoring ? rawTargets?.slice(0, 1) : rawTargets;
125
+ const explicitSources = normalizedSources(opts.source);
126
+ const sources = legacySources.length > 0 || explicitSources
127
+ ? [...new Set([...legacySources, ...(explicitSources ?? [])])]
128
+ : undefined;
105
129
  validateRegisterApproachTargetsForProject({
106
130
  projectId: paths.projectId,
107
131
  ...(opts.approach !== undefined ? { approach: opts.approach } : {}),
108
- ...(targets !== undefined ? { targets } : {}),
109
- validateTargetsWithoutApproach: opts.target !== undefined,
132
+ ...(rawTargets !== undefined ? { targets: rawTargets } : {}),
133
+ ...(explicitSources !== undefined ? { sources: explicitSources } : {}),
134
+ validateTargetsWithoutApproach: opts.target !== undefined || opts.source !== undefined,
110
135
  });
111
136
  const fields = {
112
137
  type: opts.type,
@@ -122,6 +147,7 @@ export function registerCreateCommands(reg, dependencies) {
122
147
  conclusion: opts.conclusion,
123
148
  ...(opts.approach !== undefined ? { approach: opts.approach } : {}),
124
149
  ...(targets !== undefined ? { targets } : {}),
150
+ ...(sources !== undefined ? { sources } : {}),
125
151
  };
126
152
  const templatePath = resolveSpecdojoTemplatePath(`pjr-${opts.type}-template.md`);
127
153
  const { assignedId: displayId, ticketFilename } = planRegisterItem({
@@ -204,7 +230,8 @@ export function registerUpdateCommand(reg, dependencies) {
204
230
  updateCmd.option("--block-reason <text>", "Update the waiting reason or use - to remove it");
205
231
  updateCmd.option("--autopilot <approval>", "Night orchestrator approval: approved, or - to revoke");
206
232
  updateCmd.option("--approach <approach>", `Update execution approach (${APPROACHES.join(" | ")}; use - to remove)`);
207
- updateCmd.option("--target <doc-id>", "Replace target document ids (repeatable; use - to remove)", collectTarget);
233
+ updateCmd.option("--target <doc-id>", "Replace target document ids (repeatable; legacy authoring exemplars may follow; use - to remove)", collectTarget);
234
+ updateCmd.option("--source <ref>", "Replace read-only *-authoring exemplars (repeatable; use - to remove)", collectTarget);
208
235
  updateCmd.option("--from <item-id>", "Replace source register item IDs (repeatable; use - to remove)", collectTarget);
209
236
  updateCmd.option("--topic <topic>", "Update the topic slug in the ticket filename and document ID");
210
237
  updateCmd.option("--by <actor>", "Actor recorded in the append-only register event");
@@ -228,11 +255,12 @@ export function registerUpdateCommand(reg, dependencies) {
228
255
  "autopilot",
229
256
  "approach",
230
257
  "target",
258
+ "source",
231
259
  "from",
232
260
  "topic",
233
261
  ].some((key) => opts[key] !== undefined);
234
262
  if (!hasUpdates) {
235
- throw new Error("At least one field option must be specified (--title, --description, --priority, --difficulty, --owner, --due, --conclusion, --block-reason, --autopilot, --approach, --target, --from, --topic)");
263
+ throw new Error("At least one field option must be specified (--title, --description, --priority, --difficulty, --owner, --due, --conclusion, --block-reason, --autopilot, --approach, --target, --source, --from, --topic)");
236
264
  }
237
265
  if (opts.priority !== undefined &&
238
266
  !VALID_PRIORITIES.includes(opts.priority)) {
@@ -280,7 +308,31 @@ export function registerUpdateCommand(reg, dependencies) {
280
308
  : opts.approach.trim() === "-"
281
309
  ? undefined
282
310
  : opts.approach.trim();
283
- const nextTargets = opts.target === undefined ? item.targets : normalizedTargets(opts.target);
311
+ const authoring = isAuthoringApproach(nextApproach);
312
+ const providedTargets = opts.target === undefined ? undefined : normalizedTargets(opts.target);
313
+ const providedLegacySources = authoring ? (providedTargets ?? []).slice(1) : [];
314
+ const nextTargets = opts.target === undefined
315
+ ? authoring
316
+ ? item.targets?.slice(0, 1)
317
+ : item.targets
318
+ : authoring
319
+ ? providedTargets?.slice(0, 1)
320
+ : providedTargets;
321
+ const existingSources = [
322
+ ...(isAuthoringApproach(item.approach) ? (item.targets ?? []).slice(1) : []),
323
+ ...(item.sources ?? []),
324
+ ];
325
+ const explicitSources = opts.source === undefined ? undefined : normalizedSources(opts.source, true);
326
+ const nextSources = authoring
327
+ ? opts.source !== undefined
328
+ ? [...new Set([...providedLegacySources, ...(explicitSources ?? [])])]
329
+ : providedLegacySources.length > 0
330
+ ? [...new Set(providedLegacySources)]
331
+ : [...new Set(existingSources)]
332
+ : opts.source !== undefined
333
+ ? explicitSources
334
+ : item.sources;
335
+ const normalizedNextSources = nextSources && nextSources.length > 0 ? nextSources : undefined;
284
336
  const nextDerivedFrom = opts.from === undefined
285
337
  ? item.derivedFrom
286
338
  : normalizeDerivedFrom(opts.from, { allowRemove: true });
@@ -293,8 +345,12 @@ export function registerUpdateCommand(reg, dependencies) {
293
345
  projectId: paths.projectId,
294
346
  ...(nextApproach !== undefined ? { approach: nextApproach } : {}),
295
347
  ...(nextTargets !== undefined ? { targets: nextTargets } : {}),
296
- validateTargetsWithoutApproach: opts.target !== undefined,
348
+ ...(normalizedNextSources !== undefined ? { sources: normalizedNextSources } : {}),
349
+ validateTargetsWithoutApproach: opts.target !== undefined || opts.source !== undefined,
297
350
  });
351
+ const shouldUpdateTargets = opts.target !== undefined ||
352
+ (authoring && opts.source !== undefined && (item.targets?.length ?? 0) > 1);
353
+ const shouldUpdateSources = opts.source !== undefined || (authoring && providedLegacySources.length > 0);
298
354
  const approachTargetUpdates = {
299
355
  ...(opts.difficulty !== undefined
300
356
  ? {
@@ -306,11 +362,16 @@ export function registerUpdateCommand(reg, dependencies) {
306
362
  approach: nextApproach === undefined ? REMOVE_REGISTER_ITEM_FIELD : nextApproach,
307
363
  }
308
364
  : {}),
309
- ...(opts.target !== undefined
365
+ ...(shouldUpdateTargets
310
366
  ? {
311
367
  targets: nextTargets ?? REMOVE_REGISTER_ITEM_FIELD,
312
368
  }
313
369
  : {}),
370
+ ...(shouldUpdateSources
371
+ ? {
372
+ sources: normalizedNextSources ?? REMOVE_REGISTER_ITEM_FIELD,
373
+ }
374
+ : {}),
314
375
  ...(opts.from !== undefined
315
376
  ? {
316
377
  derived_from: nextDerivedFrom ?? REMOVE_REGISTER_ITEM_FIELD,
@@ -343,12 +404,18 @@ export function registerUpdateCommand(reg, dependencies) {
343
404
  else
344
405
  updated.approach = nextApproach;
345
406
  }
346
- if (opts.target !== undefined) {
407
+ if (shouldUpdateTargets) {
347
408
  if (nextTargets === undefined)
348
409
  delete updated.targets;
349
410
  else
350
411
  updated.targets = nextTargets;
351
412
  }
413
+ if (shouldUpdateSources) {
414
+ if (normalizedNextSources === undefined)
415
+ delete updated.sources;
416
+ else
417
+ updated.sources = normalizedNextSources;
418
+ }
352
419
  if (opts.from !== undefined) {
353
420
  if (nextDerivedFrom === undefined)
354
421
  delete updated.derivedFrom;
@@ -23,6 +23,7 @@ export const REGISTER_EVENT_FIELDS = [
23
23
  "block_reason",
24
24
  "approach",
25
25
  "targets",
26
+ "sources",
26
27
  "derived_from",
27
28
  "autopilot",
28
29
  ];
@@ -76,6 +77,7 @@ export function registerEventFieldValues(content, filename, timeZone) {
76
77
  block_reason: parsed.blockReason,
77
78
  approach: item.approach ?? CELL_NONE,
78
79
  targets: item.targets ? JSON.stringify(item.targets) : CELL_NONE,
80
+ sources: item.sources ? JSON.stringify(item.sources) : CELL_NONE,
79
81
  derived_from: item.derivedFrom ? JSON.stringify(item.derivedFrom) : CELL_NONE,
80
82
  autopilot: item.autopilot ?? CELL_NONE,
81
83
  };
@@ -3,6 +3,7 @@ import { existsSync } from "node:fs";
3
3
  import { join } from "node:path";
4
4
  import { loadConfig, resolveExternalProjectRoot, specdojoRootDir, } from "../shared/specdojo-config.js";
5
5
  export const MINIMUM_EXTERNAL_REGISTER_VERSION = "0.4.2";
6
+ export const MINIMUM_EXTERNAL_SOURCE_VERSION = "0.4.5";
6
7
  function addValue(args, flag, value) {
7
8
  if (value !== undefined)
8
9
  args.push(flag, value);
@@ -44,6 +45,8 @@ export function buildExternalRegisterAddArgs(alias, externalProject, opts) {
44
45
  addValue(args, "--approach", opts.approach);
45
46
  for (const target of opts.target ?? [])
46
47
  addValue(args, "--target", target);
48
+ for (const source of opts.source ?? [])
49
+ addValue(args, "--source", source);
47
50
  for (const source of opts.from ?? []) {
48
51
  addValue(args, "--from", rewriteExternalDerivedFrom(source, alias, externalProject.project_id));
49
52
  }
@@ -66,8 +69,11 @@ function versionParts(version) {
66
69
  return [Number(match[1]), Number(match[2]), Number(match[3])];
67
70
  }
68
71
  export function supportsExternalRegister(version) {
72
+ return versionAtLeast(version, MINIMUM_EXTERNAL_REGISTER_VERSION);
73
+ }
74
+ function versionAtLeast(version, required) {
69
75
  const actual = versionParts(version);
70
- const minimum = versionParts(MINIMUM_EXTERNAL_REGISTER_VERSION);
76
+ const minimum = versionParts(required);
71
77
  if (!actual || !minimum)
72
78
  return false;
73
79
  for (let index = 0; index < actual.length; index += 1) {
@@ -122,6 +128,10 @@ export function delegateExternalRegisterAdd(opts, run = spawnSync) {
122
128
  throw new Error(`External project ${alias} uses SpecDojo ${version || "with an unknown version"}; ` +
123
129
  `${MINIMUM_EXTERNAL_REGISTER_VERSION} or newer is required for cross-project register add.`);
124
130
  }
131
+ if ((opts.source?.length ?? 0) > 0 && !versionAtLeast(version, MINIMUM_EXTERNAL_SOURCE_VERSION)) {
132
+ throw new Error(`External project ${alias} uses SpecDojo ${version}; ` +
133
+ `${MINIMUM_EXTERNAL_SOURCE_VERSION} or newer is required for --source.`);
134
+ }
125
135
  const result = run(executable, buildExternalRegisterAddArgs(alias, externalProject, opts), {
126
136
  cwd: repoRoot,
127
137
  encoding: "utf8",
@@ -70,6 +70,7 @@ const SPECDOJO_KEY_ORDER = [
70
70
  "autopilot",
71
71
  "approach",
72
72
  "targets",
73
+ "sources",
73
74
  ];
74
75
  // ================================
75
76
  // Derivation helpers
@@ -218,6 +219,9 @@ export function readRegisterItemContent(content, filename) {
218
219
  const targets = Array.isArray(fields.targets)
219
220
  ? fields.targets.filter((entry) => typeof entry === "string" && entry.trim() !== "")
220
221
  : undefined;
222
+ const sources = Array.isArray(fields.sources)
223
+ ? fields.sources.filter((entry) => typeof entry === "string" && entry.trim() !== "")
224
+ : undefined;
221
225
  const approach = asString(fields.approach);
222
226
  const derivedFrom = Array.isArray(fields.derived_from)
223
227
  ? fields.derived_from.filter((entry) => typeof entry === "string" && entry.trim() !== "")
@@ -243,6 +247,7 @@ export function readRegisterItemContent(content, filename) {
243
247
  ticket: ticketRefCell(filename),
244
248
  ...(approach ? { approach } : {}),
245
249
  ...(targets && targets.length > 0 ? { targets } : {}),
250
+ ...(sources && sources.length > 0 ? { sources } : {}),
246
251
  ...(derivedFrom && derivedFrom.length > 0 ? { derivedFrom } : {}),
247
252
  ...(autopilot ? { autopilot } : {}),
248
253
  };
@@ -367,6 +372,7 @@ export function registerItemFieldsFromItem(item) {
367
372
  : inlineCodeAnglePlaceholders(item.conclusion.trim()),
368
373
  ...(item.approach ? { approach: item.approach } : {}),
369
374
  ...(item.targets && item.targets.length > 0 ? { targets: item.targets } : {}),
375
+ ...(item.sources && item.sources.length > 0 ? { sources: item.sources } : {}),
370
376
  ...(item.derivedFrom && item.derivedFrom.length > 0 ? { derived_from: item.derivedFrom } : {}),
371
377
  ...(item.autopilot ? { autopilot: item.autopilot } : {}),
372
378
  };
@@ -60,13 +60,13 @@ export function renumberTicketContent(content, fromId, toId, topic) {
60
60
  return updated;
61
61
  }
62
62
  // 他文書からの参照リンク(wikilink `[[<docId>|...]]`)と
63
- // exec plan / result の `targets` に含まれる doc id を新しい doc id へ置き換える。
63
+ // exec plan / result の `targets` と個票の `sources` に含まれる doc id を新しい doc id へ置き換える。
64
64
  export function renumberReferences(content, fromDocId, toDocId) {
65
65
  if (!content.includes(fromDocId))
66
66
  return { content, changed: false };
67
67
  return { content: content.split(fromDocId).join(toDocId), changed: true };
68
68
  }
69
- // `derived_from` は文書 ID ではなく表示 ID を保持するため、通常の wikilink / targets の
69
+ // `derived_from` は文書 ID ではなく表示 ID を保持するため、通常の wikilink / targets / sources の
70
70
  // 置換とは分けて frontmatter の配列だけを更新する。同一 project の短縮形と、別 project
71
71
  // から参照する project 修飾形の両方を対象にする。
72
72
  function renumberDerivedFromReferences(content, filename, sourceProjectId, fromId, toId) {
@@ -256,7 +256,7 @@ export function planRenumber(paths, fromId, toId) {
256
256
  if (hasIndexRow) {
257
257
  writes.push({ path: paths.pjrIndexPath, content: newIndexContent });
258
258
  }
259
- // 参照リンク・targets・derived_from の付け替え(doc id を持つ個票がある場合のみ)。
259
+ // 参照リンク・targets・sources・derived_from の付け替え(doc id を持つ個票がある場合のみ)。
260
260
  if (fromDocId && toDocId) {
261
261
  const root = specdojoRootDir();
262
262
  const referenceFiles = findMarkdownReferenceFiles(root);
@@ -14,21 +14,21 @@ _PHASE_DESCRIPTION_
14
14
  - 記述標準: [[_AUTHORING_STANDARD_ID_|執筆標準]](`_AUTHORING_STANDARD_PATH_`)
15
15
  - result: `_RESULT_REF_`
16
16
 
17
- 手本にする既存成果物:
17
+ 手本にするファイル:
18
18
 
19
19
  _AUTHORING_EXEMPLARS_
20
20
 
21
- 手本の成果物は読み取り専用であり、成果物そのものを変更しない。手本がない場合は、記述標準と対象領域の慣行だけを根拠に実践の型を作る。
21
+ 手本ファイルは読み取り専用であり、プロジェクトリポジトリとプロダクトリポジトリのどちらにあっても変更しない。手本がない場合は、記述標準と対象領域の慣行だけを根拠に実践の型を作る。
22
22
 
23
23
  ## 3. 進め方
24
24
 
25
- 1. 記述標準と手本の成果物を実際に読み、複数の成果物に再利用できる規則・問い・完成例・雛形を抽出する。
25
+ 1. 記述標準と手本ファイルを実際に読み、複数の成果物に再利用できる規則・問い・完成例・雛形を抽出する。
26
26
  2. `_AUTHORING_KATA_PATH_` に `_AUTHORING_KATA_ID_` を持つ `_AUTHORING_KATA_KIND_` を新規作成する。frontmatter の `status` は `draft` とし、`ready` へ変更しない。
27
27
  3. 手本の内容を丸写しせず、プロジェクト固有の値を一般化する。手本同士が矛盾する場合は、共通部分と差異を分け、判断できない点を result の申し送りへ記録する。
28
- 4. 手本ごとに、作った種類の参照が `undecided` または未記入なら `_AUTHORING_KATA_ID_` へ更新する。rulebook は成果物カタログの `rulebook`、recipe / sample / template は成果物が参照する rulebook frontmatter の同名フィールドを正本とする。
29
- 5. 参照がすでに別の kata を指す場合は上書きせず、その成果物 ID・既存参照・新しい kata ID を result の申し送りへ記録する。`not-needed` も意図的な判断として上書きしない。
28
+ 4. 手本のうち成果物カタログに載っているものだけ、作った種類の参照が `undecided` または未記入なら `_AUTHORING_KATA_ID_` へ更新する。カタログ外の文書とプロダクトリポジトリのファイルは読み取り専用の手本にとどめ、参照を付け替えない。rulebook は成果物カタログの `rulebook`、recipe / sample / template は成果物が参照する rulebook frontmatter の同名フィールドを正本とする。
29
+ 5. カタログ成果物の参照がすでに別の kata を指す場合は上書きせず、その成果物 ID・既存参照・新しい kata ID を result の申し送りへ記録する。`not-needed` も意図的な判断として上書きしない。
30
30
  recipe / sample / template の作成時に、手本の rulebook 自体が `undecided`・未記入・`not-needed` で参照先を記録できない場合は、別種の kata を同時作成せず、付け替え不能として result へ記録する。
31
- 6. 新しい kata と参照の更新だけを変更対象とし、手本の成果物本文は変更しない。
31
+ 6. 新しい kata と参照の更新だけを変更対象とし、手本ファイルは変更しない。
32
32
 
33
33
  ## 4. 完了手順
34
34
 
@@ -39,7 +39,7 @@ _AUTHORING_EXEMPLARS_
39
39
  ## 5. 異常終了の条件
40
40
 
41
41
  - 新しい id が既に存在する、対象種別と id の末尾が一致しない、手本を解決できない、または検査が未解消の場合は異常終了する。
42
- - 手本の成果物本文へ変更が生じた場合は元に戻し、解消できなければ異常終了する。
42
+ - 手本ファイル(プロダクトリポジトリを含む)へ変更が生じた場合は元に戻し、commit の対象に含めない。解消できなければ異常終了する。
43
43
  - agent 自身は登録簿の状態を変更しない。
44
44
 
45
45
  _COMMON_CONVENTIONS_
@@ -14,21 +14,21 @@ _PHASE_DESCRIPTION_
14
14
  - 記述標準: [[_AUTHORING_STANDARD_ID_|執筆標準]](`_AUTHORING_STANDARD_PATH_`)
15
15
  - result: `_RESULT_REF_`
16
16
 
17
- 手本にする既存成果物:
17
+ 手本にするファイル:
18
18
 
19
19
  _AUTHORING_EXEMPLARS_
20
20
 
21
- 手本の成果物は読み取り専用であり、成果物そのものを変更しない。手本がない場合は、記述標準と対象領域の慣行だけを根拠に実践の型を作る。
21
+ 手本ファイルは読み取り専用であり、プロジェクトリポジトリとプロダクトリポジトリのどちらにあっても変更しない。手本がない場合は、記述標準と対象領域の慣行だけを根拠に実践の型を作る。
22
22
 
23
23
  ## 3. 進め方
24
24
 
25
- 1. 記述標準と手本の成果物を実際に読み、複数の成果物に再利用できる規則・問い・完成例・雛形を抽出する。
25
+ 1. 記述標準と手本ファイルを実際に読み、複数の成果物に再利用できる規則・問い・完成例・雛形を抽出する。
26
26
  2. `_AUTHORING_KATA_PATH_` に `_AUTHORING_KATA_ID_` を持つ `_AUTHORING_KATA_KIND_` を新規作成する。frontmatter の `status` は `draft` とし、`ready` へ変更しない。
27
27
  3. 手本の内容を丸写しせず、プロジェクト固有の値を一般化する。手本同士が矛盾する場合は、共通部分と差異を分け、判断できない点を result の申し送りへ記録する。
28
- 4. 手本ごとに、作った種類の参照が `undecided` または未記入なら `_AUTHORING_KATA_ID_` へ更新する。rulebook は成果物カタログの `rulebook`、recipe / sample / template は成果物が参照する rulebook frontmatter の同名フィールドを正本とする。
29
- 5. 参照がすでに別の kata を指す場合は上書きせず、その成果物 ID・既存参照・新しい kata ID を result の申し送りへ記録する。`not-needed` も意図的な判断として上書きしない。
28
+ 4. 手本のうち成果物カタログに載っているものだけ、作った種類の参照が `undecided` または未記入なら `_AUTHORING_KATA_ID_` へ更新する。カタログ外の文書とプロダクトリポジトリのファイルは読み取り専用の手本にとどめ、参照を付け替えない。rulebook は成果物カタログの `rulebook`、recipe / sample / template は成果物が参照する rulebook frontmatter の同名フィールドを正本とする。
29
+ 5. カタログ成果物の参照がすでに別の kata を指す場合は上書きせず、その成果物 ID・既存参照・新しい kata ID を result の申し送りへ記録する。`not-needed` も意図的な判断として上書きしない。
30
30
  recipe / sample / template の作成時に、手本の rulebook 自体が `undecided`・未記入・`not-needed` で参照先を記録できない場合は、別種の kata を同時作成せず、付け替え不能として result へ記録する。
31
- 6. 新しい kata と参照の更新だけを変更対象とし、手本の成果物本文は変更しない。
31
+ 6. 新しい kata と参照の更新だけを変更対象とし、手本ファイルは変更しない。
32
32
 
33
33
  ## 4. 完了手順
34
34
 
@@ -39,7 +39,7 @@ _AUTHORING_EXEMPLARS_
39
39
  ## 5. 異常終了の条件
40
40
 
41
41
  - 新しい id が既に存在する、対象種別と id の末尾が一致しない、手本を解決できない、または検査が未解消の場合は異常終了する。
42
- - 手本の成果物本文へ変更が生じた場合は元に戻し、解消できなければ異常終了する。
42
+ - 手本ファイル(プロダクトリポジトリを含む)へ変更が生じた場合は元に戻し、commit の対象に含めない。解消できなければ異常終了する。
43
43
  - agent 自身は登録簿の状態を変更しない。
44
44
 
45
45
  _COMMON_CONVENTIONS_
@@ -14,21 +14,21 @@ _PHASE_DESCRIPTION_
14
14
  - 記述標準: [[_AUTHORING_STANDARD_ID_|執筆標準]](`_AUTHORING_STANDARD_PATH_`)
15
15
  - result: `_RESULT_REF_`
16
16
 
17
- 手本にする既存成果物:
17
+ 手本にするファイル:
18
18
 
19
19
  _AUTHORING_EXEMPLARS_
20
20
 
21
- 手本の成果物は読み取り専用であり、成果物そのものを変更しない。手本がない場合は、記述標準と対象領域の慣行だけを根拠に実践の型を作る。
21
+ 手本ファイルは読み取り専用であり、プロジェクトリポジトリとプロダクトリポジトリのどちらにあっても変更しない。手本がない場合は、記述標準と対象領域の慣行だけを根拠に実践の型を作る。
22
22
 
23
23
  ## 3. 進め方
24
24
 
25
- 1. 記述標準と手本の成果物を実際に読み、複数の成果物に再利用できる規則・問い・完成例・雛形を抽出する。
25
+ 1. 記述標準と手本ファイルを実際に読み、複数の成果物に再利用できる規則・問い・完成例・雛形を抽出する。
26
26
  2. `_AUTHORING_KATA_PATH_` に `_AUTHORING_KATA_ID_` を持つ `_AUTHORING_KATA_KIND_` を新規作成する。frontmatter の `status` は `draft` とし、`ready` へ変更しない。
27
27
  3. 手本の内容を丸写しせず、プロジェクト固有の値を一般化する。手本同士が矛盾する場合は、共通部分と差異を分け、判断できない点を result の申し送りへ記録する。
28
- 4. 手本ごとに、作った種類の参照が `undecided` または未記入なら `_AUTHORING_KATA_ID_` へ更新する。rulebook は成果物カタログの `rulebook`、recipe / sample / template は成果物が参照する rulebook frontmatter の同名フィールドを正本とする。
29
- 5. 参照がすでに別の kata を指す場合は上書きせず、その成果物 ID・既存参照・新しい kata ID を result の申し送りへ記録する。`not-needed` も意図的な判断として上書きしない。
28
+ 4. 手本のうち成果物カタログに載っているものだけ、作った種類の参照が `undecided` または未記入なら `_AUTHORING_KATA_ID_` へ更新する。カタログ外の文書とプロダクトリポジトリのファイルは読み取り専用の手本にとどめ、参照を付け替えない。rulebook は成果物カタログの `rulebook`、recipe / sample / template は成果物が参照する rulebook frontmatter の同名フィールドを正本とする。
29
+ 5. カタログ成果物の参照がすでに別の kata を指す場合は上書きせず、その成果物 ID・既存参照・新しい kata ID を result の申し送りへ記録する。`not-needed` も意図的な判断として上書きしない。
30
30
  recipe / sample / template の作成時に、手本の rulebook 自体が `undecided`・未記入・`not-needed` で参照先を記録できない場合は、別種の kata を同時作成せず、付け替え不能として result へ記録する。
31
- 6. 新しい kata と参照の更新だけを変更対象とし、手本の成果物本文は変更しない。
31
+ 6. 新しい kata と参照の更新だけを変更対象とし、手本ファイルは変更しない。
32
32
 
33
33
  ## 4. 完了手順
34
34
 
@@ -39,7 +39,7 @@ _AUTHORING_EXEMPLARS_
39
39
  ## 5. 異常終了の条件
40
40
 
41
41
  - 新しい id が既に存在する、対象種別と id の末尾が一致しない、手本を解決できない、または検査が未解消の場合は異常終了する。
42
- - 手本の成果物本文へ変更が生じた場合は元に戻し、解消できなければ異常終了する。
42
+ - 手本ファイル(プロダクトリポジトリを含む)へ変更が生じた場合は元に戻し、commit の対象に含めない。解消できなければ異常終了する。
43
43
  - agent 自身は登録簿の状態を変更しない。
44
44
 
45
45
  _COMMON_CONVENTIONS_
@@ -14,21 +14,21 @@ _PHASE_DESCRIPTION_
14
14
  - 記述標準: [[_AUTHORING_STANDARD_ID_|執筆標準]](`_AUTHORING_STANDARD_PATH_`)
15
15
  - result: `_RESULT_REF_`
16
16
 
17
- 手本にする既存成果物:
17
+ 手本にするファイル:
18
18
 
19
19
  _AUTHORING_EXEMPLARS_
20
20
 
21
- 手本の成果物は読み取り専用であり、成果物そのものを変更しない。手本がない場合は、記述標準と対象領域の慣行だけを根拠に実践の型を作る。
21
+ 手本ファイルは読み取り専用であり、プロジェクトリポジトリとプロダクトリポジトリのどちらにあっても変更しない。手本がない場合は、記述標準と対象領域の慣行だけを根拠に実践の型を作る。
22
22
 
23
23
  ## 3. 進め方
24
24
 
25
- 1. 記述標準と手本の成果物を実際に読み、複数の成果物に再利用できる規則・問い・完成例・雛形を抽出する。
25
+ 1. 記述標準と手本ファイルを実際に読み、複数の成果物に再利用できる規則・問い・完成例・雛形を抽出する。
26
26
  2. `_AUTHORING_KATA_PATH_` に `_AUTHORING_KATA_ID_` を持つ `_AUTHORING_KATA_KIND_` を新規作成する。frontmatter の `status` は `draft` とし、`ready` へ変更しない。
27
27
  3. 手本の内容を丸写しせず、プロジェクト固有の値を一般化する。手本同士が矛盾する場合は、共通部分と差異を分け、判断できない点を result の申し送りへ記録する。
28
- 4. 手本ごとに、作った種類の参照が `undecided` または未記入なら `_AUTHORING_KATA_ID_` へ更新する。rulebook は成果物カタログの `rulebook`、recipe / sample / template は成果物が参照する rulebook frontmatter の同名フィールドを正本とする。
29
- 5. 参照がすでに別の kata を指す場合は上書きせず、その成果物 ID・既存参照・新しい kata ID を result の申し送りへ記録する。`not-needed` も意図的な判断として上書きしない。
28
+ 4. 手本のうち成果物カタログに載っているものだけ、作った種類の参照が `undecided` または未記入なら `_AUTHORING_KATA_ID_` へ更新する。カタログ外の文書とプロダクトリポジトリのファイルは読み取り専用の手本にとどめ、参照を付け替えない。rulebook は成果物カタログの `rulebook`、recipe / sample / template は成果物が参照する rulebook frontmatter の同名フィールドを正本とする。
29
+ 5. カタログ成果物の参照がすでに別の kata を指す場合は上書きせず、その成果物 ID・既存参照・新しい kata ID を result の申し送りへ記録する。`not-needed` も意図的な判断として上書きしない。
30
30
  recipe / sample / template の作成時に、手本の rulebook 自体が `undecided`・未記入・`not-needed` で参照先を記録できない場合は、別種の kata を同時作成せず、付け替え不能として result へ記録する。
31
- 6. 新しい kata と参照の更新だけを変更対象とし、手本の成果物本文は変更しない。
31
+ 6. 新しい kata と参照の更新だけを変更対象とし、手本ファイルは変更しない。
32
32
 
33
33
  ## 4. 完了手順
34
34
 
@@ -39,7 +39,7 @@ _AUTHORING_EXEMPLARS_
39
39
  ## 5. 異常終了の条件
40
40
 
41
41
  - 新しい id が既に存在する、対象種別と id の末尾が一致しない、手本を解決できない、または検査が未解消の場合は異常終了する。
42
- - 手本の成果物本文へ変更が生じた場合は元に戻し、解消できなければ異常終了する。
42
+ - 手本ファイル(プロダクトリポジトリを含む)へ変更が生じた場合は元に戻し、commit の対象に含めない。解消できなければ異常終了する。
43
43
  - agent 自身は登録簿の状態を変更しない。
44
44
 
45
45
  _COMMON_CONVENTIONS_
@@ -65,7 +65,9 @@ template は、記述する部分を _TODO_ などのプレースホルダとし
65
65
 
66
66
  要否は初回の `bootstrap` で判断します。`undecided` の型は、必要なら項目を省略したうえで必要な型を成果物と一緒に整備し、不要なら `not-needed` へ更新します。既存の型を廃止する、または `not-needed` を必要へ変更する場合は、成果物の実績・繰り返し発生したレビュー指摘・schema の表現範囲を根拠として rulebook frontmatter の宣言も同時に更新します。
67
67
 
68
- 成果物と型を一組で初めて作るときは `bootstrap` を使います。成果物がすでにあり、そこから再利用可能な型だけを新しく起こすとき、または手本なしで型だけを作るときは `rulebook-authoring` / `recipe-authoring` / `sample-authoring` / `template-authoring` を使います。authoring では手本の成果物本文を変更せず、該当参照が `undecided` または未記入の場合だけ新しい kata ID へ更新します。
68
+ 成果物と型を一組で初めて作るときは `bootstrap` を使います。成果物がすでにあり、そこから再利用可能な型だけを新しく起こすとき、または手本なしで型だけを作るときは `rulebook-authoring` / `recipe-authoring` / `sample-authoring` / `template-authoring` を使います。authoring では `--target` に新しい kata ID、繰り返し可能な `--source` に読み取り専用の手本を指定します。手本は文書索引で解決できる doc id、プロジェクトリポジトリの相対パス、または project の `repos` に宣言した `<repo>:<path>` です。パスにはファイル、ディレクトリ、glob を指定できます。展開後の手本は重複を除いて 100 ファイルまでです。広すぎるパターンによる読み取り範囲と plan の肥大化を抑えるため、超過時は起票・実行を停止します。
69
+
70
+ `<repo>` が `repos[].name` と一致する値はプロダクトリポジトリのパスとして扱います。それ以外で `/` または拡張子を含む値はプロジェクトリポジトリのパス、残りは doc id として文書索引で解決します。いずれの形も手本が見つからなければ停止します。成果物カタログは必須ではありません。手本がカタログ成果物で、その kata 参照が `undecided` または未記入の場合だけ新しい kata ID へ更新します。カタログ外とプロダクトリポジトリの手本は変更せず、参照も付け替えません。互換性のため、新しい kata ID に続く 2 個目以降の `--target` も `--source` と同じ手本として受け付けます。
69
71
 
70
72
  利用者が作る kata はリポジトリ単位の `kata_authority` を使い、`docs/ja/specdojo/{rulebooks,recipes,samples,templates}/<kata_authority>/` に置きます。たとえば `customer:payment-rulebook` の配置は `docs/ja/specdojo/rulebooks/customer/payment-rulebook.md` です。`specdojo:` は SpecDojo 本体専用であり、利用者リポジトリでは新規作成できません。これにより、同じリポジトリの複数 project で型を共有しながら、将来追加される同名の同梱 kata と衝突しません。
71
73
 
@@ -645,14 +645,16 @@ npx specdojo register add \
645
645
  --difficulty hard \
646
646
  --approach rulebook-authoring \
647
647
  --target <kata-authority>:<name>-rulebook \
648
- --target <deliverable-doc-id>
648
+ --source <deliverable-doc-id>
649
649
  npx specdojo exec run \
650
650
  --project <project-id> \
651
651
  --register <PJR-ID> \
652
652
  --worktree
653
653
  ```
654
654
 
655
- 1 件目の `--target` は新しい kata ID、2 件目以降は任意の手本成果物です。成果物も型もまだない初期立ち上げには `bootstrap` を使います。手本なしで kata だけを作る場合は 2 件目以降を省略します。recipe / sample / template では `approach` と ID の末尾を同じ種類へ置き換えます。
655
+ `--target` は新しい kata ID、`--source` は任意の読み取り専用の手本です。`--source` は繰り返し指定でき、文書索引の doc id、プロジェクトリポジトリの相対パス、`repos` に宣言した `<repo>:<path>` を受け付けます。パスにはファイル、ディレクトリ、`*.md` などの glob を書けます。たとえば `--source docs/ja/lessons/01-chase/README.md` や `--source 'coderdojo-lessons:lessons/**/*.md'` の形です。カタログがない project でも使えますが、手本が見つからない場合と展開後に 100 ファイルを超える場合は停止します。互換性のため、2 個目以降の `--target` も手本として引き続き受け付けます。
656
+
657
+ 成果物も型もまだない初期立ち上げには `bootstrap` を使います。手本なしで kata だけを作る場合は `--source` を省略します。recipe / sample / template では `approach` と ID の末尾を同じ種類へ置き換えます。手本がカタログ成果物で該当参照が `undecided` または未記入の場合だけ参照を新しい kata ID へ更新し、カタログ外とプロダクトリポジトリの手本は変更しません。
656
658
 
657
659
  ### 3.10. 統合後にreviewのagentへ確かめさせる
658
660
 
@@ -382,33 +382,34 @@ specdojo schedule strategy generate \
382
382
 
383
383
  主要オプション:
384
384
 
385
- | オプション | 用途 | 対象 |
386
- | ------------------------- | ------------------------------------------------------------- | ------------------------------------------------ |
387
- | `--to <PJR-ID>` | 移動先の PJR-ID を指定する | `renumber` |
388
- | `--registered <datetime>` | 起票日時(タイムゾーン付き RFC 3339)。省略時は実行時刻 | `add` |
389
- | `--completed <datetime>` | 完了・却下日時(タイムゾーン付き RFC 3339)。省略時は実行時刻 | `close` / `reject` |
390
- | `--by <actor>` | 名簿または予約一覧の actor を追記型 event に記録する | `add` / 更新 / 遷移コマンド |
391
- | `--reason <text>` | event の理由を記録(`wait` では `block_reason` も更新) | `add` / 更新 / 遷移コマンド |
392
- | `--conclusion <text>` | 終端時の結論を記録・更新(`update` では `-` で削除) | `add` / `update` / 終端コマンド |
393
- | `--block-reason <text>` | `waiting` の理由を更新(`-` で削除) | `update` |
394
- | `--approach <approach>` | 個票の進め方を指定(`update` では `-` で削除) | `add` / `update` |
395
- | `--target <doc-id>` | 対象文書 ID を指定(繰り返し可、`update` では `-` で削除) | `add` / `update` |
396
- | `--topic <slug>` | 個票ファイル名と文書 ID の論点部分を指定・更新する | `add` / `update` |
397
- | `--commit` | `register lifecycle` 枠内で記帳・再生成・commitを行う | `add` / `update` / `renumber` / 遷移 |
398
- | `-m, --message <message>` | `--commit` のcommitメッセージを上書きする | `add` / `update` / `renumber` / 遷移 |
399
- | `--dry-run` | 書き込みを行わず変更対象を表示する | `add` / `update` / `renumber` / 遷移 / `migrate` |
400
- | `--since <date>` | 対象コミットの開始日(`YYYY-MM-DD`、当日を含む) | `history` |
401
- | `--until <date>` | 対象コミットの終了日(`YYYY-MM-DD`、当日を含む) | `history` |
402
- | `--id <PJR-ID...>` | 出力する項目を限定する(空白・カンマ区切りで複数可) | `history` |
403
- | `--status-only` | 追加・削除・状態遷移だけを出力する | `history` |
404
- | `--limit <count>` | 走査するコミット数の上限 | `history` |
405
- | `--json` | イベントを JSON で出力する | `history` |
385
+ | オプション | 用途 | 対象 |
386
+ | ------------------------- | ------------------------------------------------------------------- | ------------------------------------------------ |
387
+ | `--to <PJR-ID>` | 移動先の PJR-ID を指定する | `renumber` |
388
+ | `--registered <datetime>` | 起票日時(タイムゾーン付き RFC 3339)。省略時は実行時刻 | `add` |
389
+ | `--completed <datetime>` | 完了・却下日時(タイムゾーン付き RFC 3339)。省略時は実行時刻 | `close` / `reject` |
390
+ | `--by <actor>` | 名簿または予約一覧の actor を追記型 event に記録する | `add` / 更新 / 遷移コマンド |
391
+ | `--reason <text>` | event の理由を記録(`wait` では `block_reason` も更新) | `add` / 更新 / 遷移コマンド |
392
+ | `--conclusion <text>` | 終端時の結論を記録・更新(`update` では `-` で削除) | `add` / `update` / 終端コマンド |
393
+ | `--block-reason <text>` | `waiting` の理由を更新(`-` で削除) | `update` |
394
+ | `--approach <approach>` | 個票の進め方を指定(`update` では `-` で削除) | `add` / `update` |
395
+ | `--target <doc-id>` | 対象文書 ID を指定(繰り返し可、`update` では `-` で削除) | `add` / `update` |
396
+ | `--source <ref>` | kata authoring の手本を指定(繰り返し可、`update` では `-` で削除) | `add` / `update` |
397
+ | `--topic <slug>` | 個票ファイル名と文書 ID の論点部分を指定・更新する | `add` / `update` |
398
+ | `--commit` | `register lifecycle` 枠内で記帳・再生成・commitを行う | `add` / `update` / `renumber` / 遷移 |
399
+ | `-m, --message <message>` | `--commit` のcommitメッセージを上書きする | `add` / `update` / `renumber` / 遷移 |
400
+ | `--dry-run` | 書き込みを行わず変更対象を表示する | `add` / `update` / `renumber` / 遷移 / `migrate` |
401
+ | `--since <date>` | 対象コミットの開始日(`YYYY-MM-DD`、当日を含む) | `history` |
402
+ | `--until <date>` | 対象コミットの終了日(`YYYY-MM-DD`、当日を含む) | `history` |
403
+ | `--id <PJR-ID...>` | 出力する項目を限定する(空白・カンマ区切りで複数可) | `history` |
404
+ | `--status-only` | 追加・削除・状態遷移だけを出力する | `history` |
405
+ | `--limit <count>` | 走査するコミット数の上限 | `history` |
406
+ | `--json` | イベントを JSON で出力する | `history` |
406
407
 
407
408
  `register add` は個票 Frontmatter の `registered_at`(起票日時)を、`register close` / `register reject` は `completed_at`(完了・却下日時)を自動記入します。値は UTC の RFC 3339・秒精度(例: `2026-08-09T14:08:51Z`)で、OS / コンテナの `TZ` 環境変数には依存しません。`register reopen` は `completed_at` を削除します。
408
409
 
409
410
  `register` の `--by` は、project の `pm-members.yaml` にある人の nickname、`.specdojo/agent-members.yaml` にある agent の nickname または alias、予約 actor の `SpecDojo`・`specdojo-orchestrator`・`night-orchestrator` だけを受け付けます。agent alias は実体名で event に記録し、未知の値は書き込み前に拒否します。省略時は `SpecDojo` です。決定・承認では `PO` などの Role code や予約 actor ではなく、本人の nickname を指定します。
410
411
 
411
- `--approach` を指定する場合、通常は `--target` が 1 件だけ必須です。成果物を作成・修正する approach の対象は成果物カタログの doc id で解決するため、まだ文書がない成果物も指定できます。kata maintenance の対象は文書索引で解決し、approach に対応する kata 種別との一致も書き込み前に検証します。kata authoring だけは、1 件目を新しい kata ID、2 件目以降を任意の手本成果物 ID とします。
412
+ `--approach` を指定する場合、通常は `--target` が 1 件だけ必須です。成果物を作成・修正する approach の対象は成果物カタログの doc id で解決するため、まだ文書がない成果物も指定できます。kata maintenance の対象は文書索引で解決し、approach に対応する kata 種別との一致も書き込み前に検証します。kata authoring は `--target` を新しい kata ID、`--source` を 0 件以上の読み取り専用の手本とします。互換性のため、2 個目以降の `--target` も `--source` と同じ手本として扱います。
412
413
 
413
414
  `item_type: note` は `open` のまま更新する記録です。`register close` / `register reject` / `register defer` は終了コード 1 で拒否し、対応・回答・判断が必要な場合は `todo` / `question` / `decision` など目的に合う別の `item_type` で起票するよう案内します。本文の追記や修正には `register update` を使用できます。
414
415
 
@@ -418,9 +419,13 @@ specdojo schedule strategy generate \
418
419
 
419
420
  `register add --from <ID>` は、起票の元になった登録項目を個票 Frontmatter の `derived_from` へ記録します。`--from` は複数回指定でき、同じ project の項目は `PJR-XXXX`、別 project の項目は `<project-id>:PJR-XXXX` を使います。自己参照、未設定の project、存在しない項目は書き込み前に拒否します。別 project の項目は、その project の `integration_branch`(省略時は `project/<project-id>/develop`)の Git tree を読んで存在を確認します。`register update --from <ID>` は一覧を置換し、`--from -` で削除します。`register build` は `generated/pjr-derived-items.md` を生成し、元の項目から派生先を逆引きできるようにします。decision から todo を起票するときも、この関係を追跡先として使います。
420
421
 
421
- `external_projects` に宣言した別名を `register add --project <別名> --commit` へ渡すと、相手のリポジトリの `node_modules/.bin/specdojo` を起動し、宣言した実 project ID で起票します。相手の登録簿の形式、名簿、`integration_branch`、commit は相手の CLI に任せ、呼び出し元は相手のファイルを直接変更しません。`--from <別名>:PJR-XXXX` は相手へ `<実 project ID>:PJR-XXXX` として渡すため、相手の CLI が存在を検証し、`derived_from` にも実 project ID が残ります。
422
+ `external_projects` に宣言した別名を `register add --project <別名> --commit` へ渡すと、相手のリポジトリの `node_modules/.bin/specdojo` を起動し、宣言した実 project ID で起票します。相手の登録簿の形式、名簿、`integration_branch`、commit は相手の CLI に任せ、呼び出し元は相手のファイルを直接変更しません。`--from <別名>:PJR-XXXX` は相手へ `<実 project ID>:PJR-XXXX` として渡すため、相手の CLI が存在を検証し、`derived_from` にも実 project ID が残ります。別 project への起票で `--source` を使う場合、相手の SpecDojo は 0.4.5 以上である必要があります。
422
423
 
423
- `register add --approach <approach> --target <doc-id>` は、個票 Frontmatter に進め方と対象を書きます。成果物を作成・修正する進め方は成果物カタログにある文書を、`rulebook-maintenance` などの保守の進め方は名前に対応する kata 種別を対象にし、対象は 1 件だけです。`rulebook-authoring` / `recipe-authoring` / `sample-authoring` / `template-authoring` は、1 件目を新しい kata ID、2 件目以降を手本にするカタログ成果物 ID とします。新しい ID の authority、種類別の末尾、既存 ID との重複、手本の存在を起票時と実行時に検証します。既存 ID には対応する `*-maintenance` を使います。手本の該当参照が `undecided` または未記入なら同じ実行で新 ID へ更新し、別 ID または `not-needed` なら上書きせず result へ申し送ります。`approach` を指定しない `--target` は複数回指定でき、従来どおり変更網羅検証の対象宣言として使えます。`register update` でも同じ検証を行います。
424
+ `register add --approach <approach> --target <doc-id>` は、個票 Frontmatter に進め方と対象を書きます。成果物を作成・修正する進め方は成果物カタログにある文書を、`rulebook-maintenance` などの保守の進め方は名前に対応する kata 種別を対象にし、対象は 1 件だけです。`rulebook-authoring` / `recipe-authoring` / `sample-authoring` / `template-authoring` は `--target` に新しい kata ID、繰り返し可能な `--source` に手本を指定し、個票 Frontmatter の `sources` へ保存します。
425
+
426
+ `--source` は次の順で解釈します。コロンの前が対象 project の `repos[].name` と一致すれば `<repo>:<path>`、一致せず値に `/` または拡張子があればプロジェクトリポジトリのパス、残りは文書索引で解決する doc id です。パスはファイル、ディレクトリ、glob を受け付けます。ディレクトリと glob はファイルへ展開し、重複を除いた合計が 100 件を超えると停止します。この上限は広すぎるパターンによる読み取り範囲と plan の肥大化を防ぐためです。プロダクトリポジトリの手本は plan に `$SPECDOJO_REPO_<NAME>/<path>` として載ります。カタログは必須ではなく、いずれの形も見つからなければ起票時と実行時に理由を示して停止します。
427
+
428
+ 新しい ID の authority、種類別の末尾、既存 ID との重複も起票時と実行時に検証します。既存 ID には対応する `*-maintenance` を使います。手本がカタログ成果物で、該当参照が `undecided` または未記入なら同じ実行で新 ID へ更新します。別 ID または `not-needed` なら上書きせず result へ申し送り、カタログ外とプロダクトリポジトリの手本は変更も参照更新もしません。互換性のため、新しい kata ID に続く 2 個目以降の `--target` も `--source` と同じ手本として受け付けます。`approach` を指定しない `--target` は複数回指定でき、従来どおり変更網羅検証の対象宣言として使えます。`register update` でも同じ検証を行います。
424
429
 
425
430
  kata authoring は register 専用です。Schedule の task は対象成果物を起点にするため、「新しい kata ID + 0 件以上の手本」という target 契約を損なわずに表現できません。strategy の phase に指定した場合は plan 生成時に停止します。
426
431
 
@@ -113,9 +113,10 @@ properties:
113
113
  Doc ids of the documents this task targets. Existing documents are resolvable via the
114
114
  doc index. For deliverable work, the first entry is the target deliverable and subsequent
115
115
  entries are reference materials the approach may modify or confirm. For *-authoring
116
- register tasks, the first entry is an intentionally not-yet-existing kata id and
117
- subsequent entries are read-only exemplar deliverables. Unresolvable reference materials
118
- are omitted.
116
+ register tasks, the entry is an intentionally not-yet-existing kata id; read-only
117
+ exemplars are carried in the register item's sources and rendered as paths in the plan
118
+ body. Plans created before sources was introduced may retain exemplar doc ids after the
119
+ first target. Unresolvable reference materials are omitted.
119
120
 
120
121
  paths:
121
122
  type: array
@@ -139,6 +139,6 @@ properties:
139
139
  minLength: 1
140
140
  minItems: 1
141
141
  description: >
142
- Doc ids of the documents this task targets, carried with the same rules as the
143
- plan frontmatter targets (first entry: target deliverable, then reference
144
- materials the approach may modify or confirm).
142
+ Doc ids of the documents this task targets, carried with the same rules as the plan
143
+ frontmatter targets. Authoring results carry the new kata id; read-only exemplar sources
144
+ are described in the plan body instead of becoming change-coverage targets.
@@ -58,6 +58,7 @@ $defs:
58
58
  - block_reason
59
59
  - approach
60
60
  - targets
61
+ - sources
61
62
  - derived_from
62
63
  - autopilot
63
64
  from:
@@ -70,6 +70,21 @@ properties:
70
70
  targets:
71
71
  type: array
72
72
  maxItems: 1
73
+ - if:
74
+ required:
75
+ - sources
76
+ properties:
77
+ sources: true
78
+ then:
79
+ required:
80
+ - approach
81
+ properties:
82
+ approach:
83
+ enum:
84
+ - rulebook-authoring
85
+ - recipe-authoring
86
+ - sample-authoring
87
+ - template-authoring
73
88
  - type: object
74
89
  required:
75
90
  - rulebook
@@ -199,9 +214,9 @@ properties:
199
214
  approach:
200
215
  $ref: "#/$defs/Approach"
201
216
  description: >
202
- Execution approach. Authoring approaches use the first target as the new kata id
203
- and any remaining targets as exemplar deliverables. Other approaches require one
204
- compatible document id.
217
+ Execution approach. Authoring approaches use the target as the new kata id and
218
+ sources as read-only exemplars. For compatibility, additional targets are also
219
+ accepted as exemplar sources. Other approaches require one compatible document id.
205
220
 
206
221
  targets:
207
222
  type: array
@@ -218,6 +233,19 @@ properties:
218
233
  coverage validation works for register-originated plans. Omit the
219
234
  key when the target documents are unknown or not applicable.
220
235
 
236
+ sources:
237
+ type: array
238
+ items:
239
+ type: string
240
+ minLength: 1
241
+ minItems: 1
242
+ uniqueItems: true
243
+ description: >
244
+ Read-only exemplars for a kata authoring approach. Each value is a document id, a
245
+ project-repository-relative path, or <repo>:<path> for a repository declared in
246
+ projects.<id>.repos. Paths may name files, directories, or glob patterns. Omit the
247
+ key when the authoring task has no exemplar.
248
+
221
249
  $defs:
222
250
  ItemType:
223
251
  type: string
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "specdojo",
3
- "version": "0.4.4",
3
+ "version": "0.4.5",
4
4
  "description": "A dojo for Spec-Dō, the way of specification: decide with a register, write specs and designs with kata, and keep sharpening them with AI.",
5
5
  "license": "MIT",
6
6
  "author": "naoji3x",
@@ -101,7 +101,8 @@
101
101
  "validate:schema:glossary": "node packages/docs-lint/bin/specdojo-docs-lint.js glossary-references",
102
102
  "validate:catalog": "tsx src/specdojo.ts catalog validate",
103
103
  "validate:history-links": "node packages/docs-lint/bin/specdojo-docs-lint.js history-links",
104
- "check": "npm run typecheck && npm run lint:ts && npm run lint:md && npm run lint:fm && npm run validate:schema && npm run validate:catalog && npm run validate:history-links && npm test",
104
+ "check": "npm run typecheck && npm run lint:ts && npm run check:src-imports && npm run lint:md && npm run lint:fm && npm run validate:schema && npm run validate:catalog && npm run validate:history-links && npm test",
105
+ "check:src-imports": "node tools/check-src-imports-in-dependencies.mjs",
105
106
  "dc:ps": "docker ps --format \"table {{.Names}}\\t{{.Image}}\\t{{.Status}}\"",
106
107
  "dc:name": "bash -lc 'docker ps --format \"{{.Names}}\\t{{.Image}}\" | awk \"\\$2 ~ /^vsc-specdojo/ {print \\$1; exit}\"'",
107
108
  "dc:bash": "bash -lc 'name=$(docker ps --format \"{{.Names}}\\t{{.Image}}\" | awk \"\\$2 ~ /^vsc-specdojo/ {print \\$1; exit}\"); [ -n \"$name\" ] && docker exec -it --detach-keys=\"ctrl-]\" -e LANG=C.UTF-8 -e LC_ALL=C.UTF-8 -u node \"$name\" bash -lc \"cd /workspaces/specdojo-workspace/specdojo && exec bash\" || echo \"matching container not found\"'",
@@ -123,6 +124,7 @@
123
124
  "js-yaml": "^5.4.3",
124
125
  "prettier": "^3.8.4",
125
126
  "remark-parse": "^11.0.0",
127
+ "tinyglobby": "^0.2.17",
126
128
  "unified": "^11.0.5"
127
129
  },
128
130
  "devDependencies": {
@@ -145,7 +147,6 @@
145
147
  "remark-lint": "^10.0.1",
146
148
  "remark-mdx": "^3.1.1",
147
149
  "remark-stringify": "^11.0.0",
148
- "tinyglobby": "^0.2.17",
149
150
  "tsx": "^4.22.4",
150
151
  "typescript": "^6.0.3",
151
152
  "typescript-eslint": "^8.61.0",