specdojo 0.4.5 → 0.4.7

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 (101) hide show
  1. package/.github/agents/specdojo-orchestrator.md +4 -4
  2. package/CHANGELOG.md +41 -0
  3. package/dist/catalog/document-target.js +75 -0
  4. package/dist/commands/agent.js +2 -80
  5. package/dist/commands/init.js +33 -7
  6. package/dist/devcontainer/scaffold.js +5 -1
  7. package/dist/exec/agent-config.js +28 -16
  8. package/dist/exec/agent-plan.js +108 -0
  9. package/dist/exec/commands.js +3 -3
  10. package/dist/exec/evidence.js +35 -3
  11. package/dist/exec/grade-checkpoint.js +12 -0
  12. package/dist/exec/pipeline-state.js +1 -0
  13. package/dist/exec/plans-core.js +11 -67
  14. package/dist/exec/plans-generation.js +22 -5
  15. package/dist/exec/project.js +4 -1
  16. package/dist/exec/register-resume.js +8 -4
  17. package/dist/exec/register.js +66 -5
  18. package/dist/exec/reporter.js +8 -1
  19. package/dist/exec/results.js +1 -1
  20. package/dist/exec/run/agent-pipeline.js +7 -5
  21. package/dist/exec/run/agent.js +14 -1
  22. package/dist/exec/run/lifecycle-commands.js +2 -0
  23. package/dist/exec/run/register-resume.js +2 -0
  24. package/dist/exec/run/register-state.js +4 -1
  25. package/dist/exec/run/register-worktree.js +8 -1
  26. package/dist/exec/run/schedule-prepare.js +7 -1
  27. package/dist/exec/worktree-command.js +8 -1
  28. package/dist/exec/worktree-ops-lifecycle.js +4 -2
  29. package/dist/exec/worktree-ops-merge.js +40 -1
  30. package/dist/grade/apply.js +7 -5
  31. package/dist/grade/command-inspect.js +2 -1
  32. package/dist/grade/command-run.js +39 -0
  33. package/dist/grade/grade.js +3 -1
  34. package/dist/grade/markdown.js +4 -4
  35. package/dist/grade/pipeline-state.js +8 -6
  36. package/dist/grade/plan.js +8 -6
  37. package/dist/grade/run.js +307 -0
  38. package/dist/grade/target-discovery.js +1 -1
  39. package/dist/grade/targets.js +44 -22
  40. package/dist/kata/command.js +54 -9
  41. package/dist/register/approach.js +16 -0
  42. package/dist/register/core.js +2 -0
  43. package/dist/register/create-commands.js +57 -7
  44. package/dist/register/deliverable-target.js +215 -0
  45. package/dist/register/events.js +4 -0
  46. package/dist/register/external-project.js +18 -7
  47. package/dist/register/item.js +8 -0
  48. package/dist/register/views.js +3 -0
  49. package/dist/review/grade.js +19 -17
  50. package/dist/shared/agent-plan.js +1 -0
  51. package/dist/shared/git.js +3 -2
  52. package/dist/shared/lefthook-scaffold.js +5 -22
  53. package/dist/shared/markdownlint-scaffold.js +67 -0
  54. package/dist/shared/provider-scaffold.js +7 -5
  55. package/dist/shared/slidev-scaffold.js +102 -0
  56. package/dist/shared/specdojo-config.js +9 -3
  57. package/dist/specdojo.js +5 -1
  58. package/docs/ja/specdojo/exec-templates/xep-register-template.md +5 -4
  59. package/docs/ja/specdojo/exec-templates/xrp-freeform-template.md +2 -2
  60. package/docs/ja/specdojo/exec-templates/xrp-fully-guided-template.md +2 -2
  61. package/docs/ja/specdojo/exec-templates/xrp-recipe-guided-template.md +2 -2
  62. package/docs/ja/specdojo/exec-templates/xrp-recipe-maintenance-template.md +2 -2
  63. package/docs/ja/specdojo/exec-templates/xrp-retrofit-template.md +2 -2
  64. package/docs/ja/specdojo/exec-templates/xrp-rulebook-maintenance-template.md +2 -2
  65. package/docs/ja/specdojo/exec-templates/xrp-sample-maintenance-template.md +2 -2
  66. package/docs/ja/specdojo/exec-templates/xrp-template-maintenance-template.md +2 -2
  67. package/docs/ja/specdojo/exec-templates/xrp-template.md +2 -2
  68. package/docs/ja/specdojo/guides/exec-config-guide.md +81 -19
  69. package/docs/ja/specdojo/guides/exec-operation-guide.md +4 -0
  70. package/docs/ja/specdojo/guides/kata-guide.md +108 -1
  71. package/docs/ja/specdojo/guides/orchestrator-operation-guide.md +6 -6
  72. package/docs/ja/specdojo/guides/plan-result-lifecycle-guide.md +3 -1
  73. package/docs/ja/specdojo/guides/quick-start-guide.md +22 -2
  74. package/docs/ja/specdojo/guides/register-operation-guide.md +2 -0
  75. package/docs/ja/specdojo/guides/remote-host-development-guide.md +15 -1
  76. package/docs/ja/specdojo/guides/review-guide.md +2 -2
  77. package/docs/ja/specdojo/guides/ryu-guide.md +12 -0
  78. package/docs/ja/specdojo/references/command-reference.md +178 -62
  79. package/docs/ja/specdojo/references/specdojo-config-reference.md +31 -8
  80. package/docs/ja/specdojo/rulebooks/pjr-rulebook.md +28 -22
  81. package/docs/specdojo/schemas/v1/exec-evidence.schema.yaml +17 -1
  82. package/docs/specdojo/schemas/v1/grade-pipeline-state.schema.yaml +1 -1
  83. package/docs/specdojo/schemas/v1/register-events.schema.yaml +2 -0
  84. package/docs/specdojo/schemas/v1/register-item-frontmatter.schema.yaml +33 -1
  85. package/docs/specdojo/schemas/v1/specdojo-config.schema.yaml +16 -3
  86. package/package.json +5 -5
  87. package/templates/antigravity/orchestrator.md +4 -4
  88. package/templates/claude/README.md +2 -0
  89. package/templates/claude/agents/specdojo-orchestrator.md +4 -4
  90. package/templates/codex/README.md +38 -9
  91. package/templates/codex/agents/codex-executor.toml +1 -1
  92. package/templates/codex/agents/codex-expert-executor.toml +1 -1
  93. package/templates/codex/agents/codex-expert-review-executor.toml +1 -1
  94. package/templates/codex/agents/codex-review-executor.toml +1 -1
  95. package/templates/codex/agents/specdojo-orchestrator.toml +5 -5
  96. package/templates/codex/orchestrator.md +4 -4
  97. package/templates/devcontainer/devcontainer.json +1 -0
  98. package/templates/init-agent-members.yaml +131 -16
  99. package/templates/opencode/README.md +118 -14
  100. package/templates/opencode/agents/specdojo-orchestrator.md +5 -5
  101. package/templates/opencode/opencode.json +25 -0
@@ -82,6 +82,8 @@ export function registerCreateCommands(reg, dependencies) {
82
82
  addCmd.option("--due <date>", "Due date (YYYY-MM-DD, -, or _TODO_)", "_TODO_");
83
83
  addCmd.option("--completed <datetime>", "Completion date-time (RFC 3339 with time zone, or -)", "-");
84
84
  addCmd.option("--conclusion <text>", "Conclusion or resolution summary", "-");
85
+ addCmd.option("--target-path <path>", "Repository-relative deliverable file path");
86
+ addCmd.option("--target-rulebook <doc-id>", "Deliverable rulebook id (new id for bootstrap)");
85
87
  addCmd.option("--approach <approach>", `Execution approach: ${APPROACHES.join(" | ")}`);
86
88
  addCmd.option("--target <doc-id>", "Target document id (repeatable; authoring accepts legacy exemplar targets after the first)", collectTarget);
87
89
  addCmd.option("--source <ref>", "Read-only exemplar for *-authoring (repeatable: doc id, path, or <repo>:<path>)", collectTarget);
@@ -129,6 +131,10 @@ export function registerCreateCommands(reg, dependencies) {
129
131
  validateRegisterApproachTargetsForProject({
130
132
  projectId: paths.projectId,
131
133
  ...(opts.approach !== undefined ? { approach: opts.approach } : {}),
134
+ ...(opts.targetPath !== undefined ? { targetPath: opts.targetPath.trim() } : {}),
135
+ ...(opts.targetRulebook !== undefined
136
+ ? { targetRulebook: opts.targetRulebook.trim() }
137
+ : {}),
132
138
  ...(rawTargets !== undefined ? { targets: rawTargets } : {}),
133
139
  ...(explicitSources !== undefined ? { sources: explicitSources } : {}),
134
140
  validateTargetsWithoutApproach: opts.target !== undefined || opts.source !== undefined,
@@ -147,6 +153,10 @@ export function registerCreateCommands(reg, dependencies) {
147
153
  conclusion: opts.conclusion,
148
154
  ...(opts.approach !== undefined ? { approach: opts.approach } : {}),
149
155
  ...(targets !== undefined ? { targets } : {}),
156
+ ...(opts.targetPath !== undefined ? { targetPath: opts.targetPath.trim() } : {}),
157
+ ...(opts.targetRulebook !== undefined
158
+ ? { targetRulebook: opts.targetRulebook.trim() }
159
+ : {}),
150
160
  ...(sources !== undefined ? { sources } : {}),
151
161
  };
152
162
  const templatePath = resolveSpecdojoTemplatePath(`pjr-${opts.type}-template.md`);
@@ -229,6 +239,8 @@ export function registerUpdateCommand(reg, dependencies) {
229
239
  updateCmd.option("--conclusion <text>", "Update conclusion or use - to remove it");
230
240
  updateCmd.option("--block-reason <text>", "Update the waiting reason or use - to remove it");
231
241
  updateCmd.option("--autopilot <approval>", "Night orchestrator approval: approved, or - to revoke");
242
+ updateCmd.option("--target-path <path>", "Replace deliverable path; use - to remove");
243
+ updateCmd.option("--target-rulebook <doc-id>", "Replace deliverable rulebook id; use - to remove");
232
244
  updateCmd.option("--approach <approach>", `Update execution approach (${APPROACHES.join(" | ")}; use - to remove)`);
233
245
  updateCmd.option("--target <doc-id>", "Replace target document ids (repeatable; legacy authoring exemplars may follow; use - to remove)", collectTarget);
234
246
  updateCmd.option("--source <ref>", "Replace read-only *-authoring exemplars (repeatable; use - to remove)", collectTarget);
@@ -256,6 +268,8 @@ export function registerUpdateCommand(reg, dependencies) {
256
268
  "approach",
257
269
  "target",
258
270
  "source",
271
+ "targetPath",
272
+ "targetRulebook",
259
273
  "from",
260
274
  "topic",
261
275
  ].some((key) => opts[key] !== undefined);
@@ -303,6 +317,16 @@ export function registerUpdateCommand(reg, dependencies) {
303
317
  : {
304
318
  autopilot: opts.autopilot === "-" ? REMOVE_REGISTER_ITEM_FIELD : "approved",
305
319
  };
320
+ const nextTargetPath = opts.targetPath === undefined
321
+ ? item.targetPath
322
+ : opts.targetPath.trim() === "-"
323
+ ? undefined
324
+ : opts.targetPath.trim();
325
+ const nextTargetRulebook = opts.targetRulebook === undefined
326
+ ? item.targetRulebook
327
+ : opts.targetRulebook.trim() === "-"
328
+ ? undefined
329
+ : opts.targetRulebook.trim();
306
330
  const nextApproach = opts.approach === undefined
307
331
  ? item.approach
308
332
  : opts.approach.trim() === "-"
@@ -341,17 +365,31 @@ export function registerUpdateCommand(reg, dependencies) {
341
365
  itemId: item.id,
342
366
  derivedFrom: nextDerivedFrom,
343
367
  });
344
- validateRegisterApproachTargetsForProject({
345
- projectId: paths.projectId,
346
- ...(nextApproach !== undefined ? { approach: nextApproach } : {}),
347
- ...(nextTargets !== undefined ? { targets: nextTargets } : {}),
348
- ...(normalizedNextSources !== undefined ? { sources: normalizedNextSources } : {}),
349
- validateTargetsWithoutApproach: opts.target !== undefined || opts.source !== undefined,
350
- });
368
+ if (opts.approach !== undefined ||
369
+ opts.target !== undefined ||
370
+ opts.source !== undefined ||
371
+ opts.targetPath !== undefined ||
372
+ opts.targetRulebook !== undefined) {
373
+ validateRegisterApproachTargetsForProject({
374
+ projectId: paths.projectId,
375
+ ...(nextTargetPath !== undefined ? { targetPath: nextTargetPath } : {}),
376
+ ...(nextTargetRulebook !== undefined ? { targetRulebook: nextTargetRulebook } : {}),
377
+ ...(nextApproach !== undefined ? { approach: nextApproach } : {}),
378
+ ...(nextTargets !== undefined ? { targets: nextTargets } : {}),
379
+ ...(normalizedNextSources !== undefined ? { sources: normalizedNextSources } : {}),
380
+ validateTargetsWithoutApproach: opts.target !== undefined || opts.source !== undefined,
381
+ });
382
+ }
351
383
  const shouldUpdateTargets = opts.target !== undefined ||
352
384
  (authoring && opts.source !== undefined && (item.targets?.length ?? 0) > 1);
353
385
  const shouldUpdateSources = opts.source !== undefined || (authoring && providedLegacySources.length > 0);
354
386
  const approachTargetUpdates = {
387
+ ...(opts.targetPath !== undefined
388
+ ? { target_path: nextTargetPath ?? REMOVE_REGISTER_ITEM_FIELD }
389
+ : {}),
390
+ ...(opts.targetRulebook !== undefined
391
+ ? { target_rulebook: nextTargetRulebook ?? REMOVE_REGISTER_ITEM_FIELD }
392
+ : {}),
355
393
  ...(opts.difficulty !== undefined
356
394
  ? {
357
395
  difficulty: opts.difficulty === "-" ? REMOVE_REGISTER_ITEM_FIELD : opts.difficulty,
@@ -398,6 +436,18 @@ export function registerUpdateCommand(reg, dependencies) {
398
436
  else
399
437
  updated.autopilot = "approved";
400
438
  }
439
+ if (opts.targetPath !== undefined) {
440
+ if (nextTargetPath === undefined)
441
+ delete updated.targetPath;
442
+ else
443
+ updated.targetPath = nextTargetPath;
444
+ }
445
+ if (opts.targetRulebook !== undefined) {
446
+ if (nextTargetRulebook === undefined)
447
+ delete updated.targetRulebook;
448
+ else
449
+ updated.targetRulebook = nextTargetRulebook;
450
+ }
401
451
  if (opts.approach !== undefined) {
402
452
  if (nextApproach === undefined)
403
453
  delete updated.approach;
@@ -0,0 +1,215 @@
1
+ import { existsSync, readFileSync, realpathSync, statSync } from "node:fs";
2
+ import { dirname, isAbsolute, relative, resolve } from "node:path";
3
+ import { collectDocIndexEntries } from "../docs/doc-index.js";
4
+ import { specdojoReferencePath } from "../docs/template-resolution.js";
5
+ import { readSpecdojoNamespace } from "../docs/frontmatter-namespace.js";
6
+ import { resolveDeliverableByDocId } from "../catalog/document-target.js";
7
+ import { KATA_MISSING, resolveKataDocumentPathIfExists } from "../kata/kata.js";
8
+ import { AUTHORING_KINDS } from "../kata/authoring.js";
9
+ import { loadConfig } from "../shared/specdojo-config.js";
10
+ import { parsePracticeId } from "../shared/practice-id.js";
11
+ import { load } from "../shared/yaml.js";
12
+ export const CATALOG_LESS_APPROACHES = [
13
+ "fully-guided",
14
+ "recipe-guided",
15
+ "freeform",
16
+ "retrofit",
17
+ "bootstrap",
18
+ "finalize",
19
+ "bootstrap-finalize",
20
+ ];
21
+ function metadata(path) {
22
+ const text = readFileSync(path, "utf8");
23
+ if (/\.mdx?$/.test(path))
24
+ return readSpecdojoNamespace(text);
25
+ const parsed = load(text);
26
+ return (parsed?.specdojo ?? parsed ?? {});
27
+ }
28
+ // Resolve the nearest existing ancestor as well, so symlink parents cannot escape the repository.
29
+ export function validateDeliverablePath(root, value) {
30
+ if (!value.trim() || isAbsolute(value) || /^[a-z]:/i.test(value) || value.includes("\\")) {
31
+ throw new Error(`--target-path must be a repository-relative path: ${value}`);
32
+ }
33
+ const absolute = resolve(root, value);
34
+ const path = relative(root, absolute).replaceAll("\\", "/");
35
+ if (!path || path === ".." || path.startsWith("../")) {
36
+ throw new Error(`--target-path points outside the repository: ${value}`);
37
+ }
38
+ let ancestor = absolute;
39
+ while (!existsSync(ancestor))
40
+ ancestor = dirname(ancestor);
41
+ const physical = relative(realpathSync(root), realpathSync(ancestor));
42
+ if (physical === ".." || physical.startsWith("../") || isAbsolute(physical)) {
43
+ throw new Error(`--target-path points outside the repository through a symlink: ${value}`);
44
+ }
45
+ if (existsSync(absolute) && !statSync(absolute).isFile()) {
46
+ throw new Error(`--target-path must name a file: ${value}`);
47
+ }
48
+ return path;
49
+ }
50
+ export function resolveRegisterDeliverableTarget(opts) {
51
+ if (opts.catalogPath) {
52
+ try {
53
+ const resolved = resolveDeliverableByDocId(opts.catalogPath, opts.projectId, opts.targetId, opts.repoRoot);
54
+ return { info: resolved.info, catalogless: false };
55
+ }
56
+ catch (error) {
57
+ if (!(error instanceof Error) ||
58
+ !error.message.startsWith("catalog deliverable target not found"))
59
+ throw error;
60
+ if (!opts.targetPath || !opts.targetRulebook)
61
+ throw error;
62
+ }
63
+ }
64
+ if (!CATALOG_LESS_APPROACHES.includes(opts.approach)) {
65
+ throw new Error(`Approach "${opts.approach}" requires a deliverable target from the project catalog (catalog_path)`);
66
+ }
67
+ const entries = collectDocIndexEntries(resolve(opts.repoRoot, "docs"), opts.repoRoot);
68
+ const indexed = entries[opts.targetId]?.replace(/:\d+$/, "");
69
+ const indexedPath = indexed
70
+ ? relative(opts.repoRoot, resolve(opts.repoRoot, indexed))
71
+ : undefined;
72
+ if (!opts.targetPath && !indexedPath) {
73
+ throw new Error(`Target ${opts.targetId} is not indexed; specify --target-path and --target-rulebook (catalog_path is not configured)`);
74
+ }
75
+ const path = validateDeliverablePath(opts.repoRoot, opts.targetPath ?? indexedPath ?? "");
76
+ if (indexedPath && path !== validateDeliverablePath(opts.repoRoot, indexedPath)) {
77
+ throw new Error(`--target-path conflicts with the indexed document ${opts.targetId}: ${indexedPath}`);
78
+ }
79
+ const absolute = resolve(opts.repoRoot, path);
80
+ const existing = existsSync(absolute);
81
+ const fm = existing ? metadata(absolute) : {};
82
+ if (existing && fm.id !== opts.targetId) {
83
+ throw new Error(`--target-path is occupied by another document: ${path} (expected ${opts.targetId})`);
84
+ }
85
+ if (AUTHORING_KINDS.includes(fm.type)) {
86
+ throw new Error(`Target ${opts.targetId} is a kata, not a deliverable`);
87
+ }
88
+ const declaredRulebook = typeof fm.rulebook === "string" ? fm.rulebook : undefined;
89
+ if (opts.targetRulebook && declaredRulebook && opts.targetRulebook !== declaredRulebook) {
90
+ throw new Error(`--target-rulebook conflicts with specdojo.rulebook of ${opts.targetId}: ${declaredRulebook}`);
91
+ }
92
+ const rulebook = opts.targetRulebook ?? declaredRulebook;
93
+ if (!existing && (!opts.targetPath || !opts.targetRulebook)) {
94
+ throw new Error(`New deliverable ${opts.targetId} requires --target-path and --target-rulebook`);
95
+ }
96
+ if (!rulebook)
97
+ throw new Error(`Target ${opts.targetId} requires --target-rulebook or specdojo.rulebook`);
98
+ if ((opts.approach === "finalize" || opts.approach === "bootstrap-finalize") && !existing) {
99
+ throw new Error(`Approach "${opts.approach}" requires an existing deliverable: ${opts.targetId}`);
100
+ }
101
+ const refs = {
102
+ rulebook: KATA_MISSING,
103
+ recipe: KATA_MISSING,
104
+ sample: KATA_MISSING,
105
+ template: KATA_MISSING,
106
+ };
107
+ const kataIds = [];
108
+ const kataTargets = [];
109
+ const findKata = (kind, id) => {
110
+ const entry = entries[id]?.replace(/:\d+$/, "");
111
+ if (entry) {
112
+ const absolutePath = resolve(opts.repoRoot, entry);
113
+ if (kind !== "sample" && metadata(absolutePath).type !== kind)
114
+ throw new Error(`Kata ${id} must have type ${kind}`);
115
+ return specdojoReferencePath(absolutePath, { repositoryRoot: opts.repoRoot });
116
+ }
117
+ for (const extension of kind === "rulebook" || kind === "recipe"
118
+ ? ["md"]
119
+ : ["md", "yaml", "yml", "json"]) {
120
+ const found = resolveKataDocumentPathIfExists(kind, id, extension, {
121
+ repositoryRoot: opts.repoRoot,
122
+ });
123
+ if (found &&
124
+ metadata(found).id === id &&
125
+ (kind === "sample" || metadata(found).type === kind))
126
+ return specdojoReferencePath(found, { repositoryRoot: opts.repoRoot });
127
+ }
128
+ return undefined;
129
+ };
130
+ if (opts.approach === "bootstrap") {
131
+ if (!opts.targetPath || !opts.targetRulebook)
132
+ throw new Error("Catalog-less bootstrap requires --target-path and --target-rulebook");
133
+ const authority = loadConfig(opts.repoRoot).config?.kata_authority;
134
+ if (!authority)
135
+ throw new Error("Catalog-less bootstrap requires kata_authority in specdojo.config.json");
136
+ const parsed = parsePracticeId(rulebook);
137
+ if (parsed.authority !== authority || !/^[a-z0-9][a-z0-9-]*-rulebook$/.test(parsed.localId)) {
138
+ throw new Error(`Bootstrap rulebook must use kata_authority ${authority} and end with -rulebook: ${rulebook}`);
139
+ }
140
+ if (findKata("rulebook", rulebook))
141
+ throw new Error(`Bootstrap requires a new rulebook id; ${rulebook} already exists`);
142
+ const stem = parsed.localId.slice(0, -"-rulebook".length);
143
+ for (const kind of AUTHORING_KINDS) {
144
+ const id = `${authority}:${stem}-${kind}`;
145
+ const proposedPath = `docs/ja/specdojo/${kind}s/${authority}/${stem}-${kind}.md`;
146
+ validateDeliverablePath(opts.repoRoot, proposedPath);
147
+ // Do not reuse somebody else's kata when the generated id/path collides.
148
+ if (entries[id] || existsSync(resolve(opts.repoRoot, proposedPath)) || findKata(kind, id)) {
149
+ throw new Error(`Bootstrap kata id or path already exists: ${id} (${proposedPath})`);
150
+ }
151
+ refs[kind] = proposedPath;
152
+ kataIds.push(id);
153
+ kataTargets.push({ id, path: proposedPath });
154
+ }
155
+ }
156
+ else {
157
+ const missing = [];
158
+ const rulebookPath = !["none", "not-needed", "undecided"].includes(rulebook)
159
+ ? findKata("rulebook", rulebook)
160
+ : undefined;
161
+ if (rulebookPath) {
162
+ refs.rulebook = rulebookPath;
163
+ kataIds.push(rulebook);
164
+ kataTargets.push({ id: rulebook, path: rulebookPath });
165
+ }
166
+ else if (opts.approach !== "freeform")
167
+ missing.push("rulebook");
168
+ const rb = rulebookPath ? metadata(resolve(opts.repoRoot, rulebookPath)) : {};
169
+ for (const kind of ["recipe", "sample", "template"]) {
170
+ const declaration = rb[kind];
171
+ const ids = Array.isArray(declaration) ? declaration : [declaration];
172
+ const notNeeded = declaration === "not-needed";
173
+ const required = (opts.approach === "fully-guided" && !notNeeded) ||
174
+ (opts.approach === "recipe-guided" && kind === "recipe") ||
175
+ (opts.approach === "bootstrap-finalize" && !notNeeded);
176
+ let resolvedAny = false;
177
+ for (const id of ids) {
178
+ if (typeof id !== "string" || ["none", "not-needed", "undecided"].includes(id))
179
+ continue;
180
+ const found = findKata(kind, id);
181
+ if (found) {
182
+ if (!resolvedAny)
183
+ refs[kind] = found;
184
+ resolvedAny = true;
185
+ kataIds.push(id);
186
+ kataTargets.push({ id, path: found });
187
+ }
188
+ else if (required)
189
+ missing.push(`${kind} (${id})`);
190
+ }
191
+ if (required && !resolvedAny)
192
+ missing.push(kind);
193
+ }
194
+ if (missing.length)
195
+ throw new Error(`Approach "${opts.approach}" is missing kata: ${[...new Set(missing)].join(", ")}`);
196
+ }
197
+ return {
198
+ catalogless: true,
199
+ refs,
200
+ kataIds,
201
+ kataTargets,
202
+ info: {
203
+ catalogless: true,
204
+ resolvedPath: path,
205
+ deliverable: {
206
+ local_id: opts.targetId.split(":").pop(),
207
+ name: opts.targetId,
208
+ kind: "work",
209
+ overview: "個票の概要・完了条件を参照する。",
210
+ path,
211
+ rulebook,
212
+ },
213
+ },
214
+ };
215
+ }
@@ -24,6 +24,8 @@ export const REGISTER_EVENT_FIELDS = [
24
24
  "approach",
25
25
  "targets",
26
26
  "sources",
27
+ "target_path",
28
+ "target_rulebook",
27
29
  "derived_from",
28
30
  "autopilot",
29
31
  ];
@@ -77,6 +79,8 @@ export function registerEventFieldValues(content, filename, timeZone) {
77
79
  block_reason: parsed.blockReason,
78
80
  approach: item.approach ?? CELL_NONE,
79
81
  targets: item.targets ? JSON.stringify(item.targets) : CELL_NONE,
82
+ target_path: item.targetPath ?? CELL_NONE,
83
+ target_rulebook: item.targetRulebook ?? CELL_NONE,
80
84
  sources: item.sources ? JSON.stringify(item.sources) : CELL_NONE,
81
85
  derived_from: item.derivedFrom ? JSON.stringify(item.derivedFrom) : CELL_NONE,
82
86
  autopilot: item.autopilot ?? CELL_NONE,
@@ -1,5 +1,5 @@
1
1
  import { spawnSync } from "node:child_process";
2
- import { existsSync } from "node:fs";
2
+ import { existsSync, readFileSync } 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";
@@ -84,11 +84,22 @@ function versionAtLeast(version, required) {
84
84
  }
85
85
  function targetSpecdojoExecutable(repoRoot) {
86
86
  const executable = join(repoRoot, "node_modules", ".bin", process.platform === "win32" ? "specdojo.cmd" : "specdojo");
87
- if (!existsSync(executable)) {
88
- throw new Error(`External project repository does not have SpecDojo installed: ${executable}. ` +
89
- `Install specdojo ${MINIMUM_EXTERNAL_REGISTER_VERSION} or newer in that repository.`);
87
+ if (existsSync(executable))
88
+ return { command: executable, args: [] };
89
+ const packagePath = join(repoRoot, "package.json");
90
+ if (existsSync(packagePath)) {
91
+ const pkg = JSON.parse(readFileSync(packagePath, "utf8"));
92
+ if (pkg && typeof pkg === "object" && "name" in pkg && pkg.name === "specdojo") {
93
+ const entrypoint = join(repoRoot, "dist", "specdojo.js");
94
+ if (!existsSync(entrypoint)) {
95
+ throw new Error(`External SpecDojo repository has not been built: ${entrypoint}. ` +
96
+ "Run npm run build in that repository.");
97
+ }
98
+ return { command: process.execPath, args: [entrypoint] };
99
+ }
90
100
  }
91
- return executable;
101
+ throw new Error(`External project repository does not have SpecDojo installed: ${executable}. ` +
102
+ `Install specdojo ${MINIMUM_EXTERNAL_REGISTER_VERSION} or newer in that repository.`);
92
103
  }
93
104
  /**
94
105
  * Delegate `register add` when `--project` names an external-project alias.
@@ -110,7 +121,7 @@ export function delegateExternalRegisterAdd(opts, run = spawnSync) {
110
121
  }
111
122
  const repoRoot = resolveExternalProjectRoot(rootDir, externalProject);
112
123
  const executable = targetSpecdojoExecutable(repoRoot);
113
- const versionResult = run(executable, ["--version"], {
124
+ const versionResult = run(executable.command, [...executable.args, "--version"], {
114
125
  cwd: repoRoot,
115
126
  encoding: "utf8",
116
127
  stdio: ["ignore", "pipe", "pipe"],
@@ -132,7 +143,7 @@ export function delegateExternalRegisterAdd(opts, run = spawnSync) {
132
143
  throw new Error(`External project ${alias} uses SpecDojo ${version}; ` +
133
144
  `${MINIMUM_EXTERNAL_SOURCE_VERSION} or newer is required for --source.`);
134
145
  }
135
- const result = run(executable, buildExternalRegisterAddArgs(alias, externalProject, opts), {
146
+ const result = run(executable.command, [...executable.args, ...buildExternalRegisterAddArgs(alias, externalProject, opts)], {
136
147
  cwd: repoRoot,
137
148
  encoding: "utf8",
138
149
  stdio: "inherit",
@@ -71,6 +71,8 @@ const SPECDOJO_KEY_ORDER = [
71
71
  "approach",
72
72
  "targets",
73
73
  "sources",
74
+ "target_path",
75
+ "target_rulebook",
74
76
  ];
75
77
  // ================================
76
78
  // Derivation helpers
@@ -246,6 +248,10 @@ export function readRegisterItemContent(content, filename) {
246
248
  conclusion: asString(fields.conclusion) ?? CELL_NONE,
247
249
  ticket: ticketRefCell(filename),
248
250
  ...(approach ? { approach } : {}),
251
+ ...(asString(fields.target_path) ? { targetPath: asString(fields.target_path) } : {}),
252
+ ...(asString(fields.target_rulebook)
253
+ ? { targetRulebook: asString(fields.target_rulebook) }
254
+ : {}),
249
255
  ...(targets && targets.length > 0 ? { targets } : {}),
250
256
  ...(sources && sources.length > 0 ? { sources } : {}),
251
257
  ...(derivedFrom && derivedFrom.length > 0 ? { derivedFrom } : {}),
@@ -371,6 +377,8 @@ export function registerItemFieldsFromItem(item) {
371
377
  ? null
372
378
  : inlineCodeAnglePlaceholders(item.conclusion.trim()),
373
379
  ...(item.approach ? { approach: item.approach } : {}),
380
+ ...(item.targetPath ? { target_path: item.targetPath } : {}),
381
+ ...(item.targetRulebook ? { target_rulebook: item.targetRulebook } : {}),
374
382
  ...(item.targets && item.targets.length > 0 ? { targets: item.targets } : {}),
375
383
  ...(item.sources && item.sources.length > 0 ? { sources: item.sources } : {}),
376
384
  ...(item.derivedFrom && item.derivedFrom.length > 0 ? { derived_from: item.derivedFrom } : {}),
@@ -47,7 +47,10 @@ export function injectViewSlots(content, slots) {
47
47
  }
48
48
  // グループ(状態別・優先度別・担当者別など)を `### <chapter>.<n>. <label>` 見出し付きの
49
49
  // テーブル群へ整形する。章見出しラベルは template 側が持つため、ここでは番号と値のみ扱う。
50
+ // 項目がない場合は空文字列を差し込むと前後の空行が重なり MD012 に当たるため、「該当なし」を書く。
50
51
  function renderGroupedTables(groups, chapter, heading) {
52
+ if (groups.length === 0)
53
+ return "該当なし";
51
54
  return groups
52
55
  .map((group, index) => [
53
56
  `### ${chapter}.${index + 1}. ${group.label}`,
@@ -2,8 +2,8 @@ import { spawn } from "node:child_process";
2
2
  import { existsSync, readFileSync } from "node:fs";
3
3
  import { join } from "node:path";
4
4
  import { gitEnvironment } from "../shared/git-environment.js";
5
+ import { fileURLToPath } from "node:url";
5
6
  import { gradeContentHash, gradeFindingDisplayMessage, gradeResultPathForDocument, parseGradeResult, } from "../shared/grade-result.js";
6
- export const REVIEW_GRADE_SCRIPT = join("tools", "grade", "run-per-document.sh");
7
7
  function errorMessage(error) {
8
8
  return error instanceof Error ? error.message : String(error);
9
9
  }
@@ -59,10 +59,10 @@ export function reviewGradeFreshness(opts) {
59
59
  }
60
60
  /**
61
61
  * Decide whether the runner grades the subject before the review plan is written. A fresh grade is
62
- * reused; an unresolved subject or a repository without the grade pipeline cannot be graded.
62
+ * reused; an unresolved subject cannot be graded.
63
63
  */
64
64
  export function decideReviewGradeAction(opts) {
65
- const { freshness, scriptAvailable, dryRun } = opts;
65
+ const { freshness, dryRun } = opts;
66
66
  if (freshness.state === "fresh")
67
67
  return { run: false, outcome: { action: "skipped" } };
68
68
  if (freshness.state === "unresolved") {
@@ -70,15 +70,6 @@ export function decideReviewGradeAction(opts) {
70
70
  }
71
71
  if (dryRun)
72
72
  return { run: false, outcome: { action: "not-run", detail: "dry-run のため実行しない" } };
73
- if (!scriptAvailable) {
74
- return {
75
- run: false,
76
- outcome: {
77
- action: "not-run",
78
- detail: `grade の実行スクリプトがリポジトリにない: ${REVIEW_GRADE_SCRIPT.split("\\").join("/")}`,
79
- },
80
- };
81
- }
82
73
  return { run: true };
83
74
  }
84
75
  export function reviewGradeRunId(taskId, now) {
@@ -91,7 +82,8 @@ export function reviewGradeRunId(taskId, now) {
91
82
  }
92
83
  export function reviewGradeArgs(opts) {
93
84
  const args = [
94
- REVIEW_GRADE_SCRIPT.split("\\").join("/"),
85
+ "grade",
86
+ "run",
95
87
  "--run-id",
96
88
  opts.runId,
97
89
  "--project",
@@ -103,6 +95,10 @@ export function reviewGradeArgs(opts) {
103
95
  if (opts.target === "kata")
104
96
  args.push("--kind", "all");
105
97
  args.push("--path", opts.subjectPath);
98
+ if (opts.by)
99
+ args.push("--by", opts.by);
100
+ if (opts.execDefaultsPath)
101
+ args.push("--exec-defaults", opts.execDefaultsPath);
106
102
  return args;
107
103
  }
108
104
  const defaultInvoke = (command, args, cwd) => new Promise((resolvePromise) => {
@@ -140,7 +136,6 @@ export async function ensureReviewGrade(opts) {
140
136
  });
141
137
  const decision = decideReviewGradeAction({
142
138
  freshness,
143
- scriptAvailable: existsSync(join(opts.repoRoot, REVIEW_GRADE_SCRIPT)),
144
139
  dryRun: opts.dryRun,
145
140
  });
146
141
  if (!decision.run)
@@ -151,21 +146,28 @@ export async function ensureReviewGrade(opts) {
151
146
  projectId: opts.projectId,
152
147
  target: opts.target,
153
148
  subjectPath: opts.subjectPath,
149
+ by: opts.by,
150
+ execDefaultsPath: opts.execDefaultsPath,
154
151
  });
155
152
  const invoke = opts.invoke ?? defaultInvoke;
156
153
  try {
157
- const { exitCode, stderr } = await invoke("bash", args, opts.repoRoot);
154
+ // Resolve the entrypoint from this package, never from the consumer repository.
155
+ const javascript = fileURLToPath(new URL("../specdojo.js", import.meta.url));
156
+ const entryArgs = existsSync(javascript)
157
+ ? [javascript]
158
+ : ["--import", "tsx", fileURLToPath(new URL("../specdojo.ts", import.meta.url))];
159
+ const { exitCode, stderr } = await invoke(process.execPath, [...entryArgs, ...args], opts.repoRoot);
158
160
  if (exitCode === 0)
159
161
  return { action: "executed", runId };
160
162
  const reason = lastLine(stderr);
161
163
  return {
162
164
  action: "failed",
163
165
  runId,
164
- detail: `exit ${exitCode}${reason ? `: ${reason}` : ""}`,
166
+ detail: `${opts.subjectPath}: exit ${exitCode}${reason ? `: ${reason}` : ""}`,
165
167
  };
166
168
  }
167
169
  catch (error) {
168
- return { action: "failed", runId, detail: errorMessage(error) };
170
+ return { action: "failed", runId, detail: `${opts.subjectPath}: ${errorMessage(error)}` };
169
171
  }
170
172
  }
171
173
  function outcomeLine(outcome) {
@@ -0,0 +1 @@
1
+ export {};
@@ -232,8 +232,9 @@ export function summarizeGitHookFailure(output) {
232
232
  // parallel: true の lefthook は成功した step の出力も並べるため、最初の step 見出しが
233
233
  // 失敗した step とは限らない。末尾の summary で失敗印(🥊 など)が付いた step を優先する。
234
234
  const failedSteps = lines
235
- .map((line) => line.match(/^(?:🥊|✗|✘|✕|❌)️?\s*([^\s(]+)/u)?.[1])
236
- .filter((name) => name !== undefined && name !== "lefthook");
235
+ // step 名には空白や括弧を含む description も使われる。末尾の所要時間だけを除く。
236
+ .map((line) => line.match(/^(?:🥊|✗|✘|✕|❌)️?\s*(.+?)(?:\s+\([\d.]+\s+seconds?\))?$/u)?.[1])
237
+ .filter((name) => name !== undefined && !/^lefthook(?:\s|$)/u.test(name));
237
238
  const selected = stepHeaders.find((header) => failedSteps.includes(header.step)) ?? stepHeaders[0];
238
239
  const step = selected?.step ?? failedSteps[0] ?? "";
239
240
  const stepIndex = selected?.index ?? -1;
@@ -1,26 +1,12 @@
1
1
  import { existsSync } from "node:fs";
2
2
  import { copyFile, mkdir, readFile, writeFile } from "node:fs/promises";
3
3
  import path from "node:path";
4
+ import { writeMarkdownlintConfigs } from "./markdownlint-scaffold.js";
4
5
  const REQUIRED_DEV_DEPENDENCIES = ["lefthook", "prettier", "markdownlint-cli"];
5
6
  const REQUIRED_SCRIPTS = {
6
7
  prepare: "node tools/install-lefthook.mjs",
7
8
  "pre-commit": "lefthook run pre-commit",
8
9
  };
9
- const MARKDOWNLINT_CONFIG_FILES = [
10
- ".markdownlint.jsonc",
11
- ".markdownlint.json",
12
- ".markdownlint.yaml",
13
- ".markdownlint.yml",
14
- ".markdownlintrc",
15
- ];
16
- const MARKDOWNLINT_CONFIG = `${JSON.stringify({
17
- MD013: false,
18
- MD024: false,
19
- MD033: false,
20
- MD036: false,
21
- MD041: false,
22
- MD060: false,
23
- }, null, 2)}\n`;
24
10
  const MARKDOWNLINT_IGNORE = [".claude/agents/", ".github/agents/", ".opencode/agents/", ""].join("\n");
25
11
  function isRecord(value) {
26
12
  return typeof value === "object" && value !== null && !Array.isArray(value);
@@ -151,14 +137,11 @@ async function writeScaffoldFile(sourcePath, destinationPath, destinationLabel,
151
137
  process.stdout.write(`Written: ${destinationLabel}\n`);
152
138
  }
153
139
  async function writeMarkdownlintScaffold(opts) {
154
- const existingConfig = MARKDOWNLINT_CONFIG_FILES.find((filename) => existsSync(path.join(opts.repoRoot, filename)));
155
- if (existingConfig) {
156
- process.stdout.write(`Skipped (markdownlint config already exists): ${existingConfig}\n`);
140
+ if (opts.slidevKataPatterns?.length) {
141
+ process.stdout.write(`Planned Slidev .markdownlintignore entries:\n${opts.slidevKataPatterns.join("\n")}\n`);
157
142
  }
158
- else {
159
- await writeScaffoldFile(undefined, path.join(opts.repoRoot, ".markdownlint.jsonc"), ".markdownlint.jsonc", MARKDOWNLINT_CONFIG, { force: false, dryRun: opts.dryRun });
160
- }
161
- await writeScaffoldFile(undefined, path.join(opts.repoRoot, ".markdownlintignore"), ".markdownlintignore", MARKDOWNLINT_IGNORE, { force: false, dryRun: opts.dryRun });
143
+ await writeMarkdownlintConfigs(opts);
144
+ await writeScaffoldFile(undefined, path.join(opts.repoRoot, ".markdownlintignore"), ".markdownlintignore", MARKDOWNLINT_IGNORE + (opts.slidevKataPatterns ?? []).map((pattern) => `${pattern}\n`).join(""), { force: false, dryRun: opts.dryRun });
162
145
  }
163
146
  export async function runLefthookScaffold(opts) {
164
147
  const templateTools = path.join(opts.packageRoot, "templates", "lefthook", "tools");