specdojo 0.4.1 → 0.4.3

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 (78) hide show
  1. package/CHANGELOG.md +39 -0
  2. package/dist/catalog/build.js +7 -7
  3. package/dist/catalog/generate.js +27 -12
  4. package/dist/commands/init.js +26 -7
  5. package/dist/commands/orchestrator.js +9 -2
  6. package/dist/dashboard/timeline-build.js +4 -151
  7. package/dist/devcontainer/command.js +1 -1
  8. package/dist/devcontainer/scaffold.js +24 -9
  9. package/dist/exec/core.js +4 -0
  10. package/dist/exec/events.js +17 -6
  11. package/dist/exec/plans-core.js +26 -6
  12. package/dist/exec/plans-generation.js +13 -0
  13. package/dist/exec/plans-storage.js +15 -3
  14. package/dist/exec/register.js +64 -6
  15. package/dist/exec/results.js +5 -1
  16. package/dist/exec/strategy.js +4 -0
  17. package/dist/kata/authoring.js +100 -0
  18. package/dist/kata/command.js +52 -2
  19. package/dist/kata/kata.js +55 -12
  20. package/dist/register/approach.js +29 -1
  21. package/dist/register/core.js +3 -2
  22. package/dist/register/create-commands.js +9 -0
  23. package/dist/register/cross-project.js +141 -0
  24. package/dist/register/derivation.js +28 -7
  25. package/dist/register/external-project.js +136 -0
  26. package/dist/register/item.js +26 -5
  27. package/dist/register/register.js +45 -28
  28. package/dist/schedule/strategy-generate-scope.js +2 -1
  29. package/dist/schedule/strategy-profiles.js +3 -0
  30. package/dist/shared/agent-types.js +4 -0
  31. package/dist/shared/catalog-files.js +31 -0
  32. package/dist/shared/lefthook-scaffold.js +177 -0
  33. package/dist/shared/provider-scaffold.js +3 -3
  34. package/dist/shared/specdojo-config.js +130 -6
  35. package/dist/shared/timeline-index.js +125 -0
  36. package/docs/ja/specdojo/exec-templates/xep-recipe-authoring-template.md +45 -0
  37. package/docs/ja/specdojo/exec-templates/xep-rulebook-authoring-template.md +45 -0
  38. package/docs/ja/specdojo/exec-templates/xep-sample-authoring-template.md +45 -0
  39. package/docs/ja/specdojo/exec-templates/xep-template-authoring-template.md +45 -0
  40. package/docs/ja/specdojo/guides/docs-editing-guide.md +32 -0
  41. package/docs/ja/specdojo/guides/docs-structure-guide.md +1 -1
  42. package/docs/ja/specdojo/guides/exec-config-guide.md +13 -6
  43. package/docs/ja/specdojo/guides/kata-guide.md +4 -0
  44. package/docs/ja/specdojo/guides/plan-result-lifecycle-guide.md +4 -2
  45. package/docs/ja/specdojo/guides/quick-start-guide.md +374 -68
  46. package/docs/ja/specdojo/guides/register-operation-guide.md +30 -0
  47. package/docs/ja/specdojo/guides/remote-host-development-guide.md +10 -2
  48. package/docs/ja/specdojo/guides/ryu-guide.md +18 -4
  49. package/docs/ja/specdojo/guides/use-case-guide.md +2 -2
  50. package/docs/ja/specdojo/references/command-reference.md +77 -29
  51. package/docs/ja/specdojo/references/specdojo-config-reference.md +41 -12
  52. package/docs/ja/specdojo/standards/recipe-authoring-standard.md +10 -10
  53. package/docs/ja/specdojo/standards/rulebook-authoring-standard.md +13 -13
  54. package/docs/ja/specdojo/standards/sample-authoring-standard.md +4 -4
  55. package/docs/ja/specdojo/standards/template-authoring-standard.md +4 -4
  56. package/docs/specdojo/schemas/v1/exec-common.schema.yaml +6 -0
  57. package/docs/specdojo/schemas/v1/exec-plan-frontmatter.schema.yaml +6 -6
  58. package/docs/specdojo/schemas/v1/register-item-frontmatter.schema.yaml +21 -4
  59. package/docs/specdojo/schemas/v1/specdojo-config.schema.yaml +34 -0
  60. package/package.json +2 -2
  61. package/templates/antigravity/README.md +1 -1
  62. package/templates/antigravity/settings.global.json +5 -0
  63. package/templates/claude/README.md +11 -8
  64. package/templates/claude/settings.edit.json +10 -1
  65. package/templates/claude/settings.orchestrator.json +90 -0
  66. package/templates/claude/settings.report.json +14 -1
  67. package/templates/claude/settings.review.json +13 -1
  68. package/templates/codex/README.md +7 -5
  69. package/templates/codex/rules/specdojo.rules +48 -0
  70. package/templates/devcontainer/devcontainer.json +1 -4
  71. package/templates/init-agent-members.yaml +3 -3
  72. package/templates/lefthook/tools/install-lefthook.mjs +46 -0
  73. package/templates/lefthook/tools/specdojo-pre-commit.mjs +207 -0
  74. package/templates/opencode/README.md +8 -2
  75. package/templates/opencode/agents/opencode-executor.md +2 -0
  76. package/templates/opencode/agents/opencode-review-executor.md +2 -0
  77. package/templates/opencode/agents/specdojo-orchestrator.md +60 -6
  78. /package/dist/{shared → kata}/yaml-schema-modeline.js +0 -0
@@ -17,11 +17,22 @@ export function execDocId(projectId, prefix, localBase) {
17
17
  const localId = `${prefix}-${localBase.toLowerCase()}`;
18
18
  return projectId ? `${projectId}:${localId}` : localId;
19
19
  }
20
- // In-place plan/result share one unique stem (`<slug>-<UTC>-<rand>`) so each run keeps a
21
- // distinct file and id (no doc-index collision) and the result name is derivable from the
22
- // plan. Mirrors the done/ archive naming convention (tsForFilenameUtc + randomHex).
23
- export function buildInPlaceStem(slug) {
24
- return `${slug}-${tsForFilenameUtc(nowUtcIsoSeconds())}-${randomHex(2)}`;
20
+ const issuedInPlaceStems = new Set();
21
+ // In-place plan/result share one unique stem (`<slug>-<UTC>-<rand>[-<sequence>]`) so each
22
+ // run keeps a distinct file and id (no doc-index collision) and the result name is derivable
23
+ // from the plan. The sequence is only used if the random source repeats within this process.
24
+ export function buildInPlaceStem(slug, dependencies = {}) {
25
+ const now = dependencies.now ?? nowUtcIsoSeconds;
26
+ const makeRandomHex = dependencies.randomHex ?? randomHex;
27
+ const base = `${slug}-${tsForFilenameUtc(now())}-${makeRandomHex(4)}`;
28
+ let stem = base;
29
+ let sequence = 1;
30
+ while (issuedInPlaceStems.has(stem)) {
31
+ stem = `${base}-${sequence}`;
32
+ sequence += 1;
33
+ }
34
+ issuedInPlaceStems.add(stem);
35
+ return stem;
25
36
  }
26
37
  // Recover the shared stem from a plan path: `.../exec/plans/<stem>-plan.md` → `<stem>`.
27
38
  // Used when re-running `--plan <path>` so the tied result is overwritten in place.
@@ -265,7 +276,8 @@ export function gradeFindingTargetPath(approach, deliverable, refs) {
265
276
  }
266
277
  // grade の --target。実践の型メンテナンス系は実践の型そのものを評価対象にする。
267
278
  export function gradeTargetKind(approach) {
268
- return approach === "rulebook-maintenance" ||
279
+ return approach?.endsWith("-authoring") ||
280
+ approach === "rulebook-maintenance" ||
269
281
  approach === "recipe-maintenance" ||
270
282
  approach === "sample-maintenance" ||
271
283
  approach === "template-maintenance"
@@ -332,6 +344,10 @@ export function deliverableDependsOn(deliverable, projectId, catalogPath) {
332
344
  }
333
345
  const PROJECT_CONTEXT_EXCLUDED_APPROACHES = new Set([
334
346
  "cross-deliverable-dedup",
347
+ "rulebook-authoring",
348
+ "recipe-authoring",
349
+ "sample-authoring",
350
+ "template-authoring",
335
351
  "rulebook-maintenance",
336
352
  "recipe-maintenance",
337
353
  "sample-maintenance",
@@ -438,6 +454,10 @@ function refDocIdFromPath(refPath) {
438
454
  // approach ごとに、成果物に加えて変更・確定の対象になる実践の型の種別。
439
455
  const TARGET_REF_KINDS = {
440
456
  bootstrap: ["rulebook", "recipe", "sample", "template"],
457
+ "rulebook-authoring": ["rulebook"],
458
+ "recipe-authoring": ["recipe"],
459
+ "sample-authoring": ["sample"],
460
+ "template-authoring": ["template"],
441
461
  "bootstrap-finalize": ["rulebook", "recipe", "sample", "template"],
442
462
  "rulebook-maintenance": ["rulebook"],
443
463
  "recipe-maintenance": ["recipe"],
@@ -4,6 +4,7 @@ import { DEFAULT_PROJECT_CONTEXT } from "../shared/specdojo-config.js";
4
4
  import { resolveDeliverableSchemaRef, resolveKataRefs } from "../kata/kata.js";
5
5
  import { formatMarkdownFile } from "./format.js";
6
6
  import { expandTemplate } from "./shared.js";
7
+ import { isAuthoringApproach } from "../kata/authoring.js";
7
8
  import { MISSING, applicableReviewCriteria, crossDeliverableTargetDetails, deliverableDependsOn, deliverableName, deliverableOverview, deliverablePath, doneCriteriaChecklist, doneCriteriaGoals, doneCriteriaItems, execDocId, findDeliverableInfo, frontmatter, gradeFindingsText, gradeFindingTargetPath, gradeResultRef, gradeTargetKind, implementationEvidence, injectCommonConventions, kataRefState, loadPlanTemplate, loadRoles, loadViewpoints, ownerRoleFields, phaseDescriptionText, projectContextSection, repoRelativePath, reviewDoneCriteriaRows, reviewGradeSummaryText, rulebookIncludesText, targetDocIds, targetDocIdsForTask, } from "./plans-core.js";
8
9
  function buildEditPlanMarkdown(template, task, deliverable, roleMap, vpMap, projectId, catalogPath, projectContext, resultRef, stem, crossDeliverables = new Map(), planOverrides) {
9
10
  const cpm = task.cpm;
@@ -58,6 +59,14 @@ function buildEditPlanMarkdown(template, task, deliverable, roleMap, vpMap, proj
58
59
  _DONE_CRITERIA_ITEMS_: doneCriteriaItems(criteria),
59
60
  _GRADE_FINDINGS_: gradeFindingsText(projectId, gradeFindingTargetPath(task.approach, deliverable, refs)),
60
61
  _TARGET_DELIVERABLES_: crossDeliverableTargetDetails(projectId, task.target_local_ids ?? [], crossDeliverables, catalogPath),
62
+ _AUTHORING_KATA_ID_: planOverrides?.authoring?.id ?? MISSING,
63
+ _AUTHORING_KATA_KIND_: planOverrides?.authoring?.kind ?? MISSING,
64
+ _AUTHORING_KATA_PATH_: planOverrides?.authoring?.path ?? MISSING,
65
+ _AUTHORING_STANDARD_ID_: planOverrides?.authoring?.standardId ?? MISSING,
66
+ _AUTHORING_STANDARD_PATH_: planOverrides?.authoring?.standardPath ?? MISSING,
67
+ _AUTHORING_EXEMPLARS_: planOverrides?.authoring?.exemplars
68
+ .map((example) => `- \`${example.id}\`: ${example.name}(\`${example.path}\`、現在の参照: \`${example.currentReference}\`)`)
69
+ .join("\n") || "- なし(kata だけを新規作成する)",
61
70
  };
62
71
  const body = expandTemplate(template, values);
63
72
  if (!planOverrides?.additionalConditions)
@@ -123,6 +132,9 @@ function buildReviewPlanMarkdown(template, task, deliverable, criteria, vpMap, p
123
132
  }
124
133
  async function writeTaskPlan(ctx, task, override) {
125
134
  const mode = task.mode ?? "edit";
135
+ if (isAuthoringApproach(task.approach) && override?.origin !== "register") {
136
+ throw new Error(`Approach ${task.approach} is register-only because schedule targets cannot express a new kata id followed by exemplar deliverables`);
137
+ }
126
138
  const localId = task.local_id;
127
139
  const targetLocalIds = [...new Set(task.target_local_ids ?? [])];
128
140
  const crossDeliverables = new Map();
@@ -220,6 +232,7 @@ export async function generateRegisterApproachPlan(opts) {
220
232
  origin: "register",
221
233
  targets: opts.targets,
222
234
  ...(opts.refs ? { refs: opts.refs } : {}),
235
+ ...(opts.authoring ? { authoring: opts.authoring } : {}),
223
236
  additionalConditions: opts.additionalConditions,
224
237
  ...(opts.outPath ? { outPath: opts.outPath } : {}),
225
238
  stem: opts.stem,
@@ -5,7 +5,7 @@ import { nowUtcIsoSeconds, randomHex, tsForFilenameUtc } from "./shared.js";
5
5
  import { readSpecdojoNamespace } from "../docs/frontmatter-namespace.js";
6
6
  import { gradeFindingDisplayMessage, gradeResultPathForDocument, readGradeResultForDocument, } from "../shared/grade-result.js";
7
7
  import { lookupDocIndex } from "../docs/doc-index.js";
8
- export function archivePlan(opts) {
8
+ export function archivePlan(opts, dependencies = {}) {
9
9
  const plansDir = join(opts.executionPath, "exec", "plans");
10
10
  const from = join(plansDir, `${opts.slug}-plan.md`);
11
11
  if (!existsSync(from))
@@ -16,8 +16,16 @@ export function archivePlan(opts) {
16
16
  }
17
17
  const doneDir = join(plansDir, "done");
18
18
  mkdirSync(doneDir, { recursive: true });
19
- const stamp = tsForFilenameUtc(nowUtcIsoSeconds());
20
- const to = join(doneDir, `${opts.slug}-${stamp}-${randomHex(2)}-plan.md`);
19
+ const now = dependencies.now ?? nowUtcIsoSeconds;
20
+ const makeRandomHex = dependencies.randomHex ?? randomHex;
21
+ const stamp = tsForFilenameUtc(now());
22
+ const base = `${opts.slug}-${stamp}-${makeRandomHex(4)}`;
23
+ let sequence = 0;
24
+ let to = join(doneDir, `${base}-plan.md`);
25
+ while (existsSync(to)) {
26
+ sequence += 1;
27
+ to = join(doneDir, `${base}-${sequence}-plan.md`);
28
+ }
21
29
  renameSync(from, to);
22
30
  return { from, to, deleted: false };
23
31
  }
@@ -35,6 +43,10 @@ const PLAN_APPROACHES = [
35
43
  "recipe-guided",
36
44
  "freeform",
37
45
  "bootstrap",
46
+ "rulebook-authoring",
47
+ "recipe-authoring",
48
+ "sample-authoring",
49
+ "template-authoring",
38
50
  "retrofit",
39
51
  "cross-deliverable-dedup",
40
52
  "rulebook-maintenance",
@@ -1,11 +1,13 @@
1
1
  import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
2
- import { join, relative, resolve } from "node:path";
2
+ import { 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
6
  import { findUniqueDeliverableForKataTarget, resolveDeliverableByDocId, } from "./plans-core.js";
7
7
  import { collectDocIndexEntries } from "../docs/doc-index.js";
8
- import { resolveKataRefs } from "../kata/kata.js";
8
+ import { loadRulebookRefs, resolveKataRefs } from "../kata/kata.js";
9
+ import { authoredKataPath, authoringKind, authoringStandardId, authoringStandardPath, } from "../kata/authoring.js";
10
+ import { validateRegisterApproachTargets } from "../register/approach.js";
9
11
  import { buildSpecdojoFrontmatter } from "../docs/frontmatter-namespace.js";
10
12
  import { escapeMarkdownInline, expandTemplate, inlineCodeAnglePlaceholders, stripTerminalControlSequences, } from "./shared.js";
11
13
  import { formatMarkdownFile } from "./format.js";
@@ -305,14 +307,69 @@ export async function generateRegisterPlan(opts) {
305
307
  const category = requireRunnableRegisterItem(item);
306
308
  const ticketPath = ticketPathFromItem(item, opts.registerPaths.projectRegisterPath);
307
309
  if (item.approach) {
310
+ validateRegisterApproachTargets({
311
+ repoRoot: specdojoRootDir(),
312
+ projectId: opts.projectId,
313
+ ...(opts.catalogPath ? { catalogPath: opts.catalogPath } : {}),
314
+ approach: item.approach,
315
+ targets: item.targets,
316
+ });
308
317
  const [targetId] = item.targets ?? [];
309
- if (!targetId || (item.targets?.length ?? 0) !== 1) {
310
- throw new Error(`Register item ${item.id} approach requires exactly one target document id.`);
311
- }
318
+ if (!targetId)
319
+ throw new Error(`Register item ${item.id} approach requires a target.`);
320
+ const newKataKind = authoringKind(item.approach);
312
321
  const maintenanceKind = MAINTENANCE_TARGET_KIND[item.approach];
313
322
  let deliverable = null;
314
323
  let refs;
315
- if (maintenanceKind) {
324
+ let authoring;
325
+ 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;
332
+ let currentReference;
333
+ if (newKataKind === "rulebook") {
334
+ currentReference = rulebookId ?? "未記入";
335
+ }
336
+ else if (!rulebookId ||
337
+ rulebookId === "undecided" ||
338
+ rulebookId === "not-needed" ||
339
+ rulebookId === "none") {
340
+ currentReference = `rulebook が ${rulebookId ?? "未記入"} のため参照を更新できない`;
341
+ }
342
+ else {
343
+ const declaredReference = loadRulebookRefs(rulebookId)[newKataKind];
344
+ currentReference = Array.isArray(declaredReference)
345
+ ? declaredReference.join(", ")
346
+ : (declaredReference ?? "未記入");
347
+ }
348
+ return {
349
+ id: exampleId,
350
+ name: resolved.deliverable.name,
351
+ path: resolved.resolvedPath,
352
+ currentReference,
353
+ };
354
+ });
355
+ const exemplarExtension = extname(examples[0]?.path ?? "").slice(1);
356
+ const authoredExtension = (newKataKind === "sample" || newKataKind === "template") &&
357
+ (exemplarExtension === "yaml" || exemplarExtension === "json")
358
+ ? exemplarExtension
359
+ : "md";
360
+ const kataPath = authoredKataPath(targetId, newKataKind, authoredExtension);
361
+ refs = { rulebook: MISSING, recipe: MISSING, sample: MISSING, template: MISSING };
362
+ refs[newKataKind] = kataPath;
363
+ authoring = {
364
+ id: targetId,
365
+ kind: newKataKind,
366
+ path: kataPath,
367
+ standardId: authoringStandardId(newKataKind),
368
+ standardPath: authoringStandardPath(newKataKind),
369
+ exemplars: examples,
370
+ };
371
+ }
372
+ else if (maintenanceKind) {
316
373
  deliverable = opts.catalogPath
317
374
  ? findUniqueDeliverableForKataTarget(opts.catalogPath, targetId, maintenanceKind)
318
375
  : null;
@@ -342,6 +399,7 @@ export async function generateRegisterPlan(opts) {
342
399
  targets: item.targets ?? [],
343
400
  deliverable,
344
401
  ...(refs ? { refs } : {}),
402
+ ...(authoring ? { authoring } : {}),
345
403
  additionalConditions: [
346
404
  registerCompletionConditions(item, ticketPath),
347
405
  registerAutopilotConstraints(item),
@@ -160,7 +160,7 @@ async function supersedePriorResults(resultsDir, taskId, nextResultPath, superse
160
160
  const APPROACH_SECTION_WITH_APPROACH = [
161
161
  "## 4. 進め方と実践の型の適用",
162
162
  "",
163
- "_TODO_: `approach` に従ってどう進めたか、その進め方の中で実践の型(rulebook / recipe / sample / template)をどう適用したかを記入する(`fully-guided` で rulebook / recipe / sample / template をどう使い分けたか、`recipe-guided` で recipe のみを基準にした内容、`freeform` で実践の型より優先した実例やプロジェクト文脈、`retrofit` で実際に参照した実装パス・抽出した現在動作・反映/新設判断・未反映の乖離・未確認範囲、`rulebook-maintenance` などの maintenance 系で見直した実践の型とその根拠、など)。実践の型を基準にしなかった場合は、その判断と代わりに根拠にした内容も記入する。複数文書間に矛盾があり rulebook を正として判断した箇所、参照範囲から外れていた文書とその代わりに根拠にした内容があれば、あわせて記録する。",
163
+ "_TODO_: `approach` に従ってどう進めたか、その進め方の中で実践の型(rulebook / recipe / sample / template)をどう適用したかを記入する(`fully-guided` で rulebook / recipe / sample / template をどう使い分けたか、`recipe-guided` で recipe のみを基準にした内容、`freeform` で実践の型より優先した実例やプロジェクト文脈、`retrofit` で実際に参照した実装パス・抽出した現在動作・反映/新設判断・未反映の乖離・未確認範囲、`rulebook-authoring` などの authoring 系で手本から一般化した内容・変更しなかった手本・参照の付け替えまたは見送り、`rulebook-maintenance` などの maintenance 系で見直した実践の型とその根拠、など)。実践の型を基準にしなかった場合は、その判断と代わりに根拠にした内容も記入する。複数文書間に矛盾があり rulebook を正として判断した箇所、参照範囲から外れていた文書とその代わりに根拠にした内容があれば、あわせて記録する。",
164
164
  ].join("\n");
165
165
  const APPROACH_SECTION_WITHOUT_APPROACH = [
166
166
  "## 4. 進め方",
@@ -774,6 +774,10 @@ export function parseResultTaskIdentity(resultContent) {
774
774
  "recipe-guided",
775
775
  "freeform",
776
776
  "bootstrap",
777
+ "rulebook-authoring",
778
+ "recipe-authoring",
779
+ "sample-authoring",
780
+ "template-authoring",
777
781
  "retrofit",
778
782
  "cross-deliverable-dedup",
779
783
  "rulebook-maintenance",
@@ -8,6 +8,10 @@ function isApproach(value) {
8
8
  value === "recipe-guided" ||
9
9
  value === "freeform" ||
10
10
  value === "bootstrap" ||
11
+ value === "rulebook-authoring" ||
12
+ value === "recipe-authoring" ||
13
+ value === "sample-authoring" ||
14
+ value === "template-authoring" ||
11
15
  value === "retrofit" ||
12
16
  value === "cross-deliverable-dedup" ||
13
17
  value === "rulebook-maintenance" ||
@@ -0,0 +1,100 @@
1
+ import { existsSync, readFileSync } from "node:fs";
2
+ import { extname, join, resolve } from "node:path";
3
+ import { readSpecdojoNamespace } from "../docs/frontmatter-namespace.js";
4
+ import { getKataAuthority, isSpecdojoSourceRepository, loadConfig, specdojoRootDir, } from "../shared/specdojo-config.js";
5
+ import { parsePracticeId, practiceLocalId } from "../shared/practice-id.js";
6
+ import { load } from "../shared/yaml.js";
7
+ import { resolveSpecdojoReferencePathIfExists } from "../docs/template-resolution.js";
8
+ export const KATA_AUTHORING_BASE = "docs/ja/kata";
9
+ export const AUTHORING_KINDS = ["rulebook", "recipe", "sample", "template"];
10
+ const KIND_DIR = {
11
+ rulebook: "rulebooks",
12
+ recipe: "recipes",
13
+ sample: "samples",
14
+ template: "templates",
15
+ };
16
+ const AUTHORING_KIND_BY_APPROACH = {
17
+ "rulebook-authoring": "rulebook",
18
+ "recipe-authoring": "recipe",
19
+ "sample-authoring": "sample",
20
+ "template-authoring": "template",
21
+ };
22
+ export function authoringKind(approach) {
23
+ return approach ? AUTHORING_KIND_BY_APPROACH[approach] : undefined;
24
+ }
25
+ export function isAuthoringApproach(approach) {
26
+ return (approach !== undefined &&
27
+ Object.prototype.hasOwnProperty.call(AUTHORING_KIND_BY_APPROACH, approach));
28
+ }
29
+ export function kataKindDirectory(kind, local = false) {
30
+ return local ? `${KATA_AUTHORING_BASE}/${KIND_DIR[kind]}` : `docs/ja/specdojo/${KIND_DIR[kind]}`;
31
+ }
32
+ export function authoredKataPath(id, kind, extension = "md") {
33
+ const specdojoOwned = parsePracticeId(id).authority === "specdojo";
34
+ const directory = kataKindDirectory(kind, !specdojoOwned);
35
+ return `${directory}/${practiceLocalId(id)}.${extension}`;
36
+ }
37
+ export function configuredKataAuthority(rootDir = specdojoRootDir()) {
38
+ return getKataAuthority(loadConfig(rootDir).config, rootDir);
39
+ }
40
+ export function assertAuthorableKataId(id, kind, rootDir = specdojoRootDir()) {
41
+ const parsed = parsePracticeId(id);
42
+ const expectedSuffix = `-${kind}`;
43
+ if (!parsed.localId.endsWith(expectedSuffix)) {
44
+ throw new Error(`Kata id ${id} must end with ${expectedSuffix} for ${kind}-authoring`);
45
+ }
46
+ if (!parsed.authority) {
47
+ throw new Error(`Kata id ${id} must include a repository authority`);
48
+ }
49
+ if (parsed.authority === "specdojo") {
50
+ if (!isSpecdojoSourceRepository(rootDir)) {
51
+ throw new Error(`Kata authority "specdojo" is reserved for the SpecDojo repository; use ${configuredKataAuthority(rootDir)}:${parsed.localId}`);
52
+ }
53
+ }
54
+ else {
55
+ const expected = configuredKataAuthority(rootDir);
56
+ if (parsed.authority !== expected) {
57
+ throw new Error(`Kata id ${id} must use this repository's kata_authority "${expected}"`);
58
+ }
59
+ }
60
+ }
61
+ function dataFileId(path) {
62
+ try {
63
+ const content = readFileSync(path, "utf8");
64
+ const extension = extname(path).toLowerCase();
65
+ if (extension === ".md" || extension === ".mdx") {
66
+ const id = readSpecdojoNamespace(content).id;
67
+ return typeof id === "string" ? id : undefined;
68
+ }
69
+ const parsed = extension === ".json" ? JSON.parse(content) : load(content);
70
+ if (!parsed || typeof parsed !== "object" || Array.isArray(parsed))
71
+ return undefined;
72
+ const id = parsed.id;
73
+ return typeof id === "string" ? id : undefined;
74
+ }
75
+ catch {
76
+ return undefined;
77
+ }
78
+ }
79
+ export function authoredKataExists(id, rootDir = specdojoRootDir()) {
80
+ const localId = practiceLocalId(id);
81
+ for (const kind of AUTHORING_KINDS) {
82
+ const extensions = kind === "rulebook" || kind === "recipe" ? ["md"] : ["md", "yaml", "yml", "json"];
83
+ for (const local of [true, false]) {
84
+ const directory = resolve(rootDir, kataKindDirectory(kind, local));
85
+ for (const extension of extensions) {
86
+ const candidate = join(directory, `${localId}.${extension}`);
87
+ if (existsSync(candidate) && dataFileId(candidate) === id)
88
+ return true;
89
+ }
90
+ }
91
+ }
92
+ return false;
93
+ }
94
+ export function authoringStandardId(kind) {
95
+ return `specdojo:${kind}-authoring-standard`;
96
+ }
97
+ export function authoringStandardPath(kind) {
98
+ const path = `docs/ja/specdojo/standards/${kind}-authoring-standard.md`;
99
+ return resolveSpecdojoReferencePathIfExists(path) ?? path;
100
+ }
@@ -3,6 +3,9 @@ import { basename, dirname, extname, join, relative, resolve } from "node:path";
3
3
  import { load } from "../shared/yaml.js";
4
4
  import { readSpecdojoNamespace } from "../docs/frontmatter-namespace.js";
5
5
  import { specdojoResourceCandidates, } from "../docs/template-resolution.js";
6
+ import { getKataAuthority, loadConfig, specdojoRootDir } from "../shared/specdojo-config.js";
7
+ import { parsePracticeId } from "../shared/practice-id.js";
8
+ import { AUTHORING_KINDS, kataKindDirectory } from "./authoring.js";
6
9
  export const KATA_RESOURCE_KINDS = [
7
10
  "rulebook",
8
11
  "standard",
@@ -121,6 +124,51 @@ function enumerateConfig(config, roots) {
121
124
  };
122
125
  });
123
126
  }
127
+ function enumerateAuthoredResources(roots) {
128
+ const repositoryRoot = roots.repositoryRoot ?? specdojoRootDir();
129
+ const configuredAuthority = getKataAuthority(loadConfig(repositoryRoot).config, repositoryRoot);
130
+ return AUTHORING_KINDS.flatMap((kind) => {
131
+ const relativeDir = kataKindDirectory(kind, true);
132
+ const absoluteDir = resolve(repositoryRoot, relativeDir);
133
+ return relativeFiles(absoluteDir).flatMap((filePath) => {
134
+ const resolvedPath = resolve(absoluteDir, filePath);
135
+ const id = resourceId(resolvedPath);
136
+ let authority;
137
+ try {
138
+ authority = parsePracticeId(id).authority;
139
+ }
140
+ catch {
141
+ return [];
142
+ }
143
+ if (authority !== configuredAuthority)
144
+ return [];
145
+ return [
146
+ {
147
+ id,
148
+ kind,
149
+ ejectable: false,
150
+ relativePath: normalizeRelativePath(join(relativeDir, filePath)),
151
+ repositoryPath: resolvedPath,
152
+ resolvedPath,
153
+ source: "repository",
154
+ state: "ejected",
155
+ difference: "-",
156
+ },
157
+ ];
158
+ });
159
+ });
160
+ }
161
+ function specdojoOwnedResource(resource) {
162
+ if (resource.kind === "standard")
163
+ return true;
164
+ try {
165
+ const authority = parsePracticeId(resource.id).authority;
166
+ return authority === undefined || authority === "specdojo";
167
+ }
168
+ catch {
169
+ return true;
170
+ }
171
+ }
124
172
  const ALL_LIST_KINDS = [...KATA_RESOURCE_KINDS, ...KATA_REFERENCED_KINDS];
125
173
  function assertKind(kind) {
126
174
  if (kind === undefined)
@@ -136,10 +184,12 @@ export function listKataResources(options = {}) {
136
184
  const configs = options.all || (kind !== undefined && !isEjectableKind(kind))
137
185
  ? RESOURCE_KINDS
138
186
  : EJECTABLE_KINDS;
139
- return configs
187
+ const bundledAndOverrides = configs
140
188
  .filter((config) => kind === undefined || config.kind === kind)
141
189
  .flatMap((config) => enumerateConfig(config, options.roots ?? {}))
142
- .sort((first, second) => first.kind.localeCompare(second.kind) ||
190
+ .filter(specdojoOwnedResource);
191
+ const authored = enumerateAuthoredResources(options.roots ?? {}).filter((resource) => kind === undefined || resource.kind === kind);
192
+ return [...bundledAndOverrides, ...authored].sort((first, second) => first.kind.localeCompare(second.kind) ||
143
193
  first.relativePath.localeCompare(second.relativePath));
144
194
  }
145
195
  function localId(id) {
package/dist/kata/kata.js CHANGED
@@ -1,9 +1,11 @@
1
1
  import { existsSync, readFileSync } from "node:fs";
2
+ import { resolve } from "node:path";
2
3
  import { specdojoRootDir } from "../shared/specdojo-config.js";
3
4
  import { readSpecdojoNamespace } from "../docs/frontmatter-namespace.js";
4
- import { practiceLocalId } from "../shared/practice-id.js";
5
+ import { parsePracticeId, practiceLocalId } from "../shared/practice-id.js";
6
+ import { authoredKataPath, configuredKataAuthority } from "./authoring.js";
5
7
  import { resolveSpecdojoPathIfExists, resolveSpecdojoReferencePathIfExists, specdojoResourceCandidates, } from "../docs/template-resolution.js";
6
- import { readYamlSchemaModelineRef } from "../shared/yaml-schema-modeline.js";
8
+ import { readYamlSchemaModelineRef } from "./yaml-schema-modeline.js";
7
9
  // 実践の型(rulebook / recipe / sample / template)の解決を 1 か所に集約する。
8
10
  // plan 生成(明示パスの注入)と validate(参照先の存在確認)の両方から使う。
9
11
  const MISSING = "_MISSING_";
@@ -16,7 +18,11 @@ const KIND_DIR = {
16
18
  template: "templates",
17
19
  };
18
20
  function rulebookFsPath(rulebookId) {
19
- const relativePath = `${DOCS_BASE}/rulebooks/${practiceLocalId(rulebookId)}.md`;
21
+ const relativePath = practiceRepoPath("rulebook", rulebookId, "md");
22
+ const authority = parsePracticeId(rulebookId).authority;
23
+ if (authority && authority !== "specdojo") {
24
+ return resolve(specdojoRootDir(), relativePath);
25
+ }
20
26
  return (resolveSpecdojoPathIfExists(relativePath) ??
21
27
  specdojoResourceCandidates(relativePath).repositoryPath);
22
28
  }
@@ -53,14 +59,53 @@ function formatExt(targetFormat) {
53
59
  // Canonical repo-root-relative path (no leading slash): the agent opens these files
54
60
  // from the run CWD (repo root or worktree root).
55
61
  function repoPath(kind, id, ext) {
56
- return `${DOCS_BASE}/${KIND_DIR[kind]}/${practiceLocalId(id)}.${ext}`;
62
+ return practiceRepoPath(kind, id, ext);
63
+ }
64
+ function isSpecdojoResourceId(id) {
65
+ const authority = parsePracticeId(id).authority;
66
+ return !authority || authority === "specdojo";
67
+ }
68
+ function kataReferencePath(relativePath, id) {
69
+ if (!isSpecdojoResourceId(id))
70
+ return relativePath;
71
+ return resolveSpecdojoReferencePathIfExists(relativePath) ?? relativePath;
72
+ }
73
+ function kataFsPath(relativePath, id) {
74
+ if (!isSpecdojoResourceId(id))
75
+ return resolve(specdojoRootDir(), relativePath);
76
+ return (resolveSpecdojoPathIfExists(relativePath) ??
77
+ specdojoResourceCandidates(relativePath).repositoryPath);
78
+ }
79
+ function practiceRepoPath(kind, id, ext, rootDir = specdojoRootDir()) {
80
+ const authority = parsePracticeId(id).authority;
81
+ const directory = kind === "rulebook" ? "rulebooks" : KIND_DIR[kind];
82
+ if (authority && authority !== "specdojo") {
83
+ if (authority !== configuredKataAuthority(rootDir)) {
84
+ return `${KATA_UNRESOLVABLE_BASE}/${directory}/${practiceLocalId(id)}.${ext}`;
85
+ }
86
+ return authoredKataPath(id, kind).replace(/\.md$/, `.${ext}`);
87
+ }
88
+ return `${DOCS_BASE}/${directory}/${practiceLocalId(id)}.${ext}`;
89
+ }
90
+ const KATA_UNRESOLVABLE_BASE = ".specdojo/unresolvable-kata";
91
+ export function resolveKataDocumentPathIfExists(kind, id, extension, roots = {}) {
92
+ const repositoryRoot = roots.repositoryRoot ?? specdojoRootDir();
93
+ const authority = parsePracticeId(id).authority;
94
+ if (authority && authority !== "specdojo") {
95
+ if (authority !== configuredKataAuthority(repositoryRoot))
96
+ return undefined;
97
+ const relativePath = practiceRepoPath(kind, id, extension, repositoryRoot);
98
+ const absolutePath = resolve(repositoryRoot, relativePath);
99
+ return existsSync(absolutePath) ? absolutePath : undefined;
100
+ }
101
+ return resolveSpecdojoPathIfExists(practiceRepoPath(kind, id, extension, repositoryRoot), roots);
57
102
  }
58
103
  // 宣言 ID は拡張子を持たないため、対象形式を優先しつつ実在する例外形式も解決する。
59
104
  // dct-index の YAML 正本に対する Markdown 生成ビュー template などが該当する。
60
105
  function declaredRefExt(kind, id, preferredExt) {
61
106
  const candidates = kind === "recipe" ? ["md"] : [preferredExt, "md", "yaml", "json"];
62
107
  for (const ext of [...new Set(candidates)]) {
63
- if (resolveSpecdojoPathIfExists(repoPath(kind, id, ext)))
108
+ if (resolveKataDocumentPathIfExists(kind, id, ext))
64
109
  return ext;
65
110
  }
66
111
  return preferredExt;
@@ -75,7 +120,7 @@ function resolveRef(kind, declaredId, ext) {
75
120
  }
76
121
  if (primaryId) {
77
122
  const relativePath = repoPath(kind, primaryId, declaredRefExt(kind, primaryId, ext));
78
- return resolveSpecdojoReferencePathIfExists(relativePath) ?? relativePath;
123
+ return kataReferencePath(relativePath, primaryId);
79
124
  }
80
125
  return MISSING;
81
126
  }
@@ -93,8 +138,7 @@ export function resolveKataRefs(rulebookId, targetKind) {
93
138
  const fm = usableRulebookId ? loadRulebookRefs(usableRulebookId) : {};
94
139
  return {
95
140
  rulebook: usableRulebookId
96
- ? (resolveSpecdojoReferencePathIfExists(rulebookRepoPath(usableRulebookId)) ??
97
- rulebookRepoPath(usableRulebookId))
141
+ ? kataReferencePath(rulebookRepoPath(usableRulebookId), usableRulebookId)
98
142
  : MISSING,
99
143
  recipe: usableRulebookId ? resolveRef("recipe", fm.recipe, "md") : MISSING,
100
144
  sample: usableRulebookId
@@ -107,7 +151,7 @@ export function resolveKataRefs(rulebookId, targetKind) {
107
151
  }
108
152
  // rulebook の repo 相対パス(先頭スラッシュ無し)。
109
153
  function rulebookRepoPath(rulebookId) {
110
- return `${DOCS_BASE}/rulebooks/${practiceLocalId(rulebookId)}.md`;
154
+ return practiceRepoPath("rulebook", rulebookId, "md");
111
155
  }
112
156
  // 主 rulebook の frontmatter `includes` から、併せて適用する rulebook の宣言順・重複除去済み
113
157
  // ID 一覧を返す。自己参照は除外する。単一段のみ(include 先の include はたどらない)。
@@ -135,7 +179,7 @@ export function resolveIncludedRulebooks(rulebookId) {
135
179
  }
136
180
  return declaredIncludeIds(rulebookId)
137
181
  .filter((id) => existsSync(rulebookFsPath(id)))
138
- .map((id) => resolveSpecdojoReferencePathIfExists(rulebookRepoPath(id)) ?? rulebookRepoPath(id));
182
+ .map((id) => kataReferencePath(rulebookRepoPath(id), id));
139
183
  }
140
184
  // validate 用: 主 rulebook が宣言する include の一覧(実在に関わらず)。
141
185
  // 自己参照フラグ付きで返し、呼び出し側で存在・種別を検査する。
@@ -175,8 +219,7 @@ export function declaredKata(rulebookId) {
175
219
  out.push({
176
220
  kind,
177
221
  id,
178
- fsPath: resolveSpecdojoPathIfExists(relativePath) ??
179
- specdojoResourceCandidates(relativePath).repositoryPath,
222
+ fsPath: kataFsPath(relativePath, id),
180
223
  });
181
224
  }
182
225
  };
@@ -7,6 +7,7 @@ import { readSpecdojoNamespace } from "../docs/frontmatter-namespace.js";
7
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
+ import { assertAuthorableKataId, authoredKataExists, authoringKind } from "../kata/authoring.js";
10
11
  const MAINTENANCE_TARGET_KIND = {
11
12
  "rulebook-maintenance": "rulebook",
12
13
  "recipe-maintenance": "recipe",
@@ -75,9 +76,13 @@ export function validateRegisterApproachTargets(opts) {
75
76
  throw new Error(`Invalid approach: "${approachText}". Must be one of: ${APPROACHES.join(", ")}`);
76
77
  }
77
78
  approach = approachText;
78
- if (targets.length !== 1) {
79
+ const kind = authoringKind(approach);
80
+ if (!kind && targets.length !== 1) {
79
81
  throw new Error(`Approach "${approach}" requires exactly one --target doc id (received ${targets.length})`);
80
82
  }
83
+ if (kind && targets.length < 1) {
84
+ throw new Error(`Approach "${approach}" requires the new kata id as the first --target`);
85
+ }
81
86
  }
82
87
  if (!approach && !opts.validateTargetsWithoutApproach)
83
88
  return;
@@ -92,6 +97,29 @@ export function validateRegisterApproachTargets(opts) {
92
97
  }
93
98
  return;
94
99
  }
100
+ const authoringTargetKind = authoringKind(approach);
101
+ if (authoringTargetKind) {
102
+ const [kataId, ...exampleIds] = targets;
103
+ if (!kataId) {
104
+ throw new Error(`Approach "${approach}" requires the new kata id as the first --target`);
105
+ }
106
+ assertAuthorableKataId(kataId, authoringTargetKind, opts.repoRoot);
107
+ if (entries[kataId] || authoredKataExists(kataId, opts.repoRoot)) {
108
+ throw new Error(`Kata id ${kataId} already exists; use ${authoringTargetKind}-maintenance instead`);
109
+ }
110
+ if (exampleIds.length === 0)
111
+ 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
+ }
121
+ return;
122
+ }
95
123
  const expectedKind = MAINTENANCE_TARGET_KIND[approach];
96
124
  const [targetId] = targets;
97
125
  if (expectedKind) {
@@ -241,8 +241,9 @@ export function generatePjrId(existingIds, nextCandidate = defaultPjrCandidate,
241
241
  }
242
242
  export function formatTableRow(item) {
243
243
  // frontmatter・本文由来を問わず、表へ展開する全セルを同じ規則で無害化する。
244
- // 列区切りの `|` と改行をエスケープし、山括弧プレースホルダをインラインコード化する。
245
- // 既存コードスパンは変換処理が保持するため、再生成しても二重に囲まれない。
244
+ // 列区切りの `|`、強調記号、改行をエスケープし、山括弧プレースホルダを
245
+ // インラインコード化する。既存コードスパンは変換処理が保持するため、再生成しても
246
+ // 二重に囲まれない。
246
247
  const cells = [
247
248
  item.id,
248
249
  item.status,