specdojo 0.4.3 → 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 (49) hide show
  1. package/.github/agents/specdojo-orchestrator.md +2 -0
  2. package/CHANGELOG.md +18 -0
  3. package/dist/catalog/build.js +8 -6
  4. package/dist/docs/doc-index.js +11 -0
  5. package/dist/exec/plans-core.js +11 -0
  6. package/dist/exec/plans-generation.js +1 -1
  7. package/dist/exec/register.js +47 -14
  8. package/dist/exec/run/in-place.js +7 -4
  9. package/dist/exec/run/register-core.js +10 -2
  10. package/dist/exec/run/register-worktree.js +4 -1
  11. package/dist/exec/task-repos.js +11 -0
  12. package/dist/kata/authoring.js +60 -14
  13. package/dist/kata/command.js +40 -28
  14. package/dist/kata/kata.js +26 -12
  15. package/dist/register/approach.js +13 -12
  16. package/dist/register/authoring-sources.js +132 -0
  17. package/dist/register/core.js +4 -3
  18. package/dist/register/create-commands.js +77 -10
  19. package/dist/register/events.js +2 -0
  20. package/dist/register/external-project.js +11 -1
  21. package/dist/register/item.js +37 -5
  22. package/dist/register/renumber.js +3 -3
  23. package/dist/shared/text.js +3 -1
  24. package/docs/ja/specdojo/exec-templates/xep-recipe-authoring-template.md +7 -7
  25. package/docs/ja/specdojo/exec-templates/xep-rulebook-authoring-template.md +7 -7
  26. package/docs/ja/specdojo/exec-templates/xep-sample-authoring-template.md +7 -7
  27. package/docs/ja/specdojo/exec-templates/xep-template-authoring-template.md +7 -7
  28. package/docs/ja/specdojo/guides/docs-structure-guide.md +1 -1
  29. package/docs/ja/specdojo/guides/kata-guide.md +6 -2
  30. package/docs/ja/specdojo/guides/practice-system-composition-guide.md +4 -0
  31. package/docs/ja/specdojo/guides/quick-start-guide.md +5 -3
  32. package/docs/ja/specdojo/references/command-reference.md +30 -25
  33. package/docs/ja/specdojo/references/specdojo-config-reference.md +1 -1
  34. package/docs/ja/specdojo/rulebooks/dct-rulebook.md +2 -1
  35. package/docs/ja/specdojo/standards/id-and-file-naming-standard.md +4 -0
  36. package/docs/ja/specdojo/standards/recipe-authoring-standard.md +3 -3
  37. package/docs/ja/specdojo/standards/rulebook-authoring-standard.md +2 -2
  38. package/docs/ja/specdojo/standards/sample-authoring-standard.md +4 -4
  39. package/docs/ja/specdojo/standards/template-authoring-standard.md +3 -3
  40. package/docs/specdojo/schemas/v1/exec-plan-frontmatter.schema.yaml +4 -3
  41. package/docs/specdojo/schemas/v1/exec-result-frontmatter.schema.yaml +3 -3
  42. package/docs/specdojo/schemas/v1/register-events.schema.yaml +1 -0
  43. package/docs/specdojo/schemas/v1/register-item-frontmatter.schema.yaml +31 -3
  44. package/package.json +12 -11
  45. package/templates/antigravity/orchestrator.md +2 -0
  46. package/templates/claude/agents/specdojo-orchestrator.md +2 -0
  47. package/templates/codex/agents/specdojo-orchestrator.toml +2 -0
  48. package/templates/codex/orchestrator.md +2 -0
  49. package/templates/opencode/agents/specdojo-orchestrator.md +2 -0
@@ -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
+ }
@@ -241,9 +241,9 @@ export function generatePjrId(existingIds, nextCandidate = defaultPjrCandidate,
241
241
  }
242
242
  export function formatTableRow(item) {
243
243
  // frontmatter・本文由来を問わず、表へ展開する全セルを同じ規則で無害化する。
244
- // 列区切りの `|`、強調記号、改行をエスケープし、山括弧プレースホルダを
245
- // インラインコード化する。既存コードスパンは変換処理が保持するため、再生成しても
246
- // 二重に囲まれない。
244
+ // 列区切りの `|`、強調記号、改行をエスケープし、素の URL を autolink、山括弧
245
+ // プレースホルダをインラインコード化する。既存の Markdown 記法は変換処理が保持するため、
246
+ // 再生成しても二重に囲まれない。
247
247
  const cells = [
248
248
  item.id,
249
249
  item.status,
@@ -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
@@ -98,6 +99,29 @@ export function ticketRefCell(filename) {
98
99
  }
99
100
  // Markdown のコードスパン。コードとして明示された内容は、表セルでも著者の記法を保持する。
100
101
  const MARKDOWN_CODE_SPAN = /(`+)[\s\S]*?\1/g;
102
+ // URL の囲みを適用しない Markdown の範囲。コードスパン、山括弧、リンク(shortcut / reference
103
+ // link を含む)は著者がすでに選んだ記法として保持する。
104
+ const MARKDOWN_URL_PROTECTED_SPAN = /(`+)[\s\S]*?\1|<[^<>\r\n]*>|!?\[[^\]\r\n]*\](?:\([^\r\n)]*\)|\[[^\]\r\n]*\])?/g;
105
+ // 全角の閉じ括弧・句読点と半角の閉じ括弧は URL の直後に続く本文として扱う。
106
+ // ASCII の句読点は query に使えるため一度 URL 候補へ含め、末尾にあるものだけ戻す。
107
+ const BARE_HTTP_URL = /https?:\/\/[^\s<>"'`)]}〉》」』】〕〗〙〛。、,!?;:…)\]}]+/g;
108
+ const TRAILING_ASCII_URL_PUNCTUATION = /[.,;:!?]+$/;
109
+ function encloseBareHttpUrls(text) {
110
+ const encloseSegment = (segment) => segment.replace(BARE_HTTP_URL, (candidate) => {
111
+ const trailing = candidate.match(TRAILING_ASCII_URL_PUNCTUATION)?.[0] ?? "";
112
+ const url = trailing ? candidate.slice(0, -trailing.length) : candidate;
113
+ return url ? `<${url}>${trailing}` : candidate;
114
+ });
115
+ let result = "";
116
+ let lastIndex = 0;
117
+ for (const match of text.matchAll(MARKDOWN_URL_PROTECTED_SPAN)) {
118
+ const start = match.index ?? 0;
119
+ result += encloseSegment(text.slice(lastIndex, start));
120
+ result += match[0];
121
+ lastIndex = start + match[0].length;
122
+ }
123
+ return result + encloseSegment(text.slice(lastIndex));
124
+ }
101
125
  // コードスパン外の未エスケープな強調記号をエスケープする。
102
126
  // 記号の直前に偶数個のバックスラッシュがある場合は Markdown 上で未エスケープなので、
103
127
  // バックスラッシュを 1 個加える。奇数個なら既にエスケープ済みとして保持する。
@@ -107,7 +131,10 @@ function escapeTableCellEmphasis(text) {
107
131
  });
108
132
  let result = "";
109
133
  let lastIndex = 0;
110
- for (const match of text.matchAll(MARKDOWN_CODE_SPAN)) {
134
+ // URL 内の `*` / `_` は URL の一部なので変えない。bare URL はこの処理より先に
135
+ // autolink 化されるが、Markdown link のリンク先にある URL も同じ規則で保持する。
136
+ const protectedSpan = new RegExp(`${MARKDOWN_CODE_SPAN.source}|${BARE_HTTP_URL.source}`, "g");
137
+ for (const match of text.matchAll(protectedSpan)) {
111
138
  const start = match.index ?? 0;
112
139
  result += escapeSegment(text.slice(lastIndex, start));
113
140
  result += match[0];
@@ -115,9 +142,9 @@ function escapeTableCellEmphasis(text) {
115
142
  }
116
143
  return result + escapeSegment(text.slice(lastIndex));
117
144
  }
118
- // 表セルへ埋め込むために1行化し、列区切りの `|` と強調記号の `*` / `_` を
119
- // エスケープする。既存コードスパンとエスケープ済みの記号は保持し、複数回の呼び出しに
120
- // 対して冪等にする。
145
+ // 表セルへ埋め込むために1行化し、素の HTTP(S) URL を autolink にしてから、列区切りの
146
+ // `|` と強調記号の `*` / `_` をエスケープする。既存コードスパン、Markdown link、
147
+ // autolink、エスケープ済みの記号は保持し、複数回の呼び出しに対して冪等にする。
121
148
  export function toCell(text) {
122
149
  if (typeof text !== "string")
123
150
  return "";
@@ -126,7 +153,7 @@ export function toCell(text) {
126
153
  .replace(/\s+/g, " ")
127
154
  .replace(/(?<!\\)((\\\\)*)\|/g, "$1\\|")
128
155
  .trim();
129
- return escapeTableCellEmphasis(normalized);
156
+ return escapeTableCellEmphasis(encloseBareHttpUrls(normalized));
130
157
  }
131
158
  // H1(`# PJR-XXXX タイトル`)からタイトルを導出する。表示 ID の接頭辞は取り除く。
132
159
  export function titleFromBody(body, id) {
@@ -192,6 +219,9 @@ export function readRegisterItemContent(content, filename) {
192
219
  const targets = Array.isArray(fields.targets)
193
220
  ? fields.targets.filter((entry) => typeof entry === "string" && entry.trim() !== "")
194
221
  : undefined;
222
+ const sources = Array.isArray(fields.sources)
223
+ ? fields.sources.filter((entry) => typeof entry === "string" && entry.trim() !== "")
224
+ : undefined;
195
225
  const approach = asString(fields.approach);
196
226
  const derivedFrom = Array.isArray(fields.derived_from)
197
227
  ? fields.derived_from.filter((entry) => typeof entry === "string" && entry.trim() !== "")
@@ -217,6 +247,7 @@ export function readRegisterItemContent(content, filename) {
217
247
  ticket: ticketRefCell(filename),
218
248
  ...(approach ? { approach } : {}),
219
249
  ...(targets && targets.length > 0 ? { targets } : {}),
250
+ ...(sources && sources.length > 0 ? { sources } : {}),
220
251
  ...(derivedFrom && derivedFrom.length > 0 ? { derivedFrom } : {}),
221
252
  ...(autopilot ? { autopilot } : {}),
222
253
  };
@@ -341,6 +372,7 @@ export function registerItemFieldsFromItem(item) {
341
372
  : inlineCodeAnglePlaceholders(item.conclusion.trim()),
342
373
  ...(item.approach ? { approach: item.approach } : {}),
343
374
  ...(item.targets && item.targets.length > 0 ? { targets: item.targets } : {}),
375
+ ...(item.sources && item.sources.length > 0 ? { sources: item.sources } : {}),
344
376
  ...(item.derivedFrom && item.derivedFrom.length > 0 ? { derived_from: item.derivedFrom } : {}),
345
377
  ...(item.autopilot ? { autopilot: item.autopilot } : {}),
346
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);
@@ -80,7 +80,9 @@ function replaceOutsideMarkdownCodeSpans(text, replace) {
80
80
  // ドットを含めるのは `dct-<domain>.yaml` のような拡張子付きの参照を分断しないためだが、
81
81
  // 文末の句点を巻き込まないよう、末尾のドットはコードスパンの外へ戻す。
82
82
  export function inlineCodeAnglePlaceholders(text) {
83
- const placeholder = /[A-Za-z0-9._-]*(?:<[^<>\r\n]+>[A-Za-z0-9._-]*)+/g;
83
+ // HTTP(S) autolink は Markdown として既に安全な山括弧記法なので、プレースホルダとして
84
+ // code span 化しない。register の表セルで bare URL を囲んだ後も autolink を保持する。
85
+ const placeholder = /[A-Za-z0-9._-]*(?:<(?!https?:\/\/)[^<>\r\n]+>[A-Za-z0-9._-]*)+/g;
84
86
  const wrapToken = (token) => {
85
87
  const trailing = token.match(/\.+$/)?.[0] ?? "";
86
88
  const body = trailing ? token.slice(0, -trailing.length) : token;
@@ -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_