specdojo 0.4.0 → 0.4.2

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (93) hide show
  1. package/.github/agents/specdojo-orchestrator.md +61 -2
  2. package/CHANGELOG.md +65 -0
  3. package/README.md +8 -7
  4. package/dist/commands/init.js +88 -15
  5. package/dist/commands/night-orchestrator.js +287 -0
  6. package/dist/commands/orchestrator.js +10 -3
  7. package/dist/dashboard/timeline-build.js +4 -151
  8. package/dist/devcontainer/command.js +3 -1
  9. package/dist/devcontainer/scaffold.js +166 -5
  10. package/dist/exec/agent-config.js +60 -2
  11. package/dist/exec/events.js +17 -6
  12. package/dist/exec/parent-validation.js +14 -0
  13. package/dist/exec/pipeline-state.js +13 -0
  14. package/dist/exec/plans-core.js +16 -5
  15. package/dist/exec/plans-storage.js +11 -3
  16. package/dist/exec/register.js +23 -1
  17. package/dist/exec/repo-integration.js +1 -1
  18. package/dist/exec/reporter.js +113 -13
  19. package/dist/exec/results.js +36 -14
  20. package/dist/exec/run/agent-pipeline.js +3 -0
  21. package/dist/exec/run/agent.js +40 -5
  22. package/dist/exec/run/job.js +2 -2
  23. package/dist/exec/run/lifecycle-commands.js +2 -2
  24. package/dist/exec/run/register-command.js +23 -4
  25. package/dist/exec/run/register-core.js +17 -0
  26. package/dist/exec/run/register-mode.js +39 -16
  27. package/dist/exec/run/register-post-review.js +420 -0
  28. package/dist/exec/run/register-resume.js +27 -11
  29. package/dist/exec/run/register-worktree.js +66 -2
  30. package/dist/exec/run/run.js +1 -1
  31. package/dist/exec/run/shared.js +22 -24
  32. package/dist/exec/task-repos.js +102 -15
  33. package/dist/kata/kata.js +1 -1
  34. package/dist/register/core.js +17 -4
  35. package/dist/register/create-commands.js +62 -6
  36. package/dist/register/cross-project.js +134 -0
  37. package/dist/register/derivation.js +28 -7
  38. package/dist/register/event-merge.js +13 -1
  39. package/dist/register/events.js +4 -0
  40. package/dist/register/item.js +35 -5
  41. package/dist/register/migration.js +1 -0
  42. package/dist/register/register.js +47 -30
  43. package/dist/schedule/strategy-generate-scope.js +2 -1
  44. package/dist/shared/catalog-files.js +31 -0
  45. package/dist/shared/git.js +45 -15
  46. package/dist/shared/lefthook-scaffold.js +177 -0
  47. package/dist/shared/provider-scaffold.js +3 -2
  48. package/dist/shared/specdojo-config.js +87 -17
  49. package/dist/shared/text.js +4 -1
  50. package/dist/shared/timeline-index.js +125 -0
  51. package/dist/shared/workspace-scaffold.js +69 -0
  52. package/docs/ja/specdojo/exec-templates/xep-common-conventions-template.md +2 -1
  53. package/docs/ja/specdojo/exec-templates/xep-register-template.md +2 -0
  54. package/docs/ja/specdojo/exec-templates/xrp-register-post-run-template.md +46 -0
  55. package/docs/ja/specdojo/guides/branch-workflow-guide.md +34 -1
  56. package/docs/ja/specdojo/guides/docs-structure-guide.md +2 -0
  57. package/docs/ja/specdojo/guides/exec-config-guide.md +79 -11
  58. package/docs/ja/specdojo/guides/exec-operation-guide.md +39 -1
  59. package/docs/ja/specdojo/guides/orchestrator-operation-guide.md +9 -3
  60. package/docs/ja/specdojo/guides/plan-result-lifecycle-guide.md +4 -2
  61. package/docs/ja/specdojo/guides/quick-start-guide.md +31 -6
  62. package/docs/ja/specdojo/guides/register-operation-guide.md +54 -0
  63. package/docs/ja/specdojo/guides/remote-host-development-guide.md +52 -6
  64. package/docs/ja/specdojo/guides/specdojo-overview-guide.md +1 -1
  65. package/docs/ja/specdojo/guides/waza-guide.md +1 -1
  66. package/docs/ja/specdojo/references/command-reference.md +138 -64
  67. package/docs/ja/specdojo/references/specdojo-config-reference.md +41 -12
  68. package/docs/ja/specdojo/rulebooks/pjr-rulebook.md +5 -2
  69. package/docs/specdojo/schemas/v1/exec-defaults.schema.yaml +92 -18
  70. package/docs/specdojo/schemas/v1/exec-evidence.schema.yaml +6 -1
  71. package/docs/specdojo/schemas/v1/pipeline-state.schema.yaml +12 -0
  72. package/docs/specdojo/schemas/v1/register-events.schema.yaml +2 -0
  73. package/docs/specdojo/schemas/v1/register-item-frontmatter.schema.yaml +21 -0
  74. package/docs/specdojo/schemas/v1/specdojo-config.schema.yaml +40 -0
  75. package/package.json +17 -17
  76. package/templates/antigravity/README.md +1 -1
  77. package/templates/antigravity/orchestrator.md +61 -2
  78. package/templates/claude/agents/specdojo-orchestrator.md +61 -2
  79. package/templates/codex/README.md +17 -0
  80. package/templates/codex/agents/specdojo-orchestrator.toml +61 -2
  81. package/templates/codex/orchestrator.md +61 -2
  82. package/templates/devcontainer/devcontainer.json +3 -0
  83. package/templates/devcontainer/post-create.sh +15 -7
  84. package/templates/devcontainer/remote-host/specdojo-tmux.sh.sample +38 -5
  85. package/templates/devcontainer/remote-host/ssh-config.sample +3 -0
  86. package/templates/devcontainer/vim/vimrc +37 -0
  87. package/templates/init-agent-members.yaml +6 -6
  88. package/templates/init-exec-defaults.yaml +20 -1
  89. package/templates/lefthook/tools/install-lefthook.mjs +46 -0
  90. package/templates/lefthook/tools/specdojo-pre-commit.mjs +207 -0
  91. package/templates/opencode/README.md +6 -1
  92. package/templates/opencode/agents/specdojo-orchestrator.md +62 -3
  93. /package/dist/{shared → kata}/yaml-schema-modeline.js +0 -0
@@ -0,0 +1,177 @@
1
+ import { existsSync } from "node:fs";
2
+ import { copyFile, mkdir, readFile, writeFile } from "node:fs/promises";
3
+ import path from "node:path";
4
+ const REQUIRED_DEV_DEPENDENCIES = ["lefthook", "prettier", "markdownlint-cli"];
5
+ const REQUIRED_SCRIPTS = {
6
+ prepare: "node tools/install-lefthook.mjs",
7
+ "pre-commit": "lefthook run pre-commit",
8
+ };
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
+ const MARKDOWNLINT_IGNORE = [".claude/agents/", ".github/agents/", ".opencode/agents/", ""].join("\n");
25
+ function isRecord(value) {
26
+ return typeof value === "object" && value !== null && !Array.isArray(value);
27
+ }
28
+ function hasConfiguredPath(config, key) {
29
+ return Object.values(config.projects).some((project) => !!project[key]?.trim());
30
+ }
31
+ export function renderLefthookConfig(config) {
32
+ const commands = [
33
+ " prettier:",
34
+ ' glob: "*.{md,yaml,yml}"',
35
+ " run: node tools/specdojo-pre-commit.mjs prettier {staged_files}",
36
+ " stage_fixed: true",
37
+ "",
38
+ " markdownlint:",
39
+ ' glob: "*.md"',
40
+ " run: node tools/specdojo-pre-commit.mjs markdownlint {staged_files}",
41
+ ];
42
+ if (hasConfiguredPath(config, "project_register_path")) {
43
+ commands.push("", " register-build:", " run: node tools/specdojo-pre-commit.mjs register-build", " stage_fixed: true");
44
+ }
45
+ if (hasConfiguredPath(config, "catalog_path")) {
46
+ commands.push("", " catalog-validate:", " run: node tools/specdojo-pre-commit.mjs catalog-validate");
47
+ }
48
+ return [
49
+ "# Generated by SpecDojo. Re-run `specdojo config scaffold --lefthook --force` to refresh.",
50
+ "pre-commit:",
51
+ " parallel: false",
52
+ " commands:",
53
+ ...commands,
54
+ "",
55
+ ].join("\n");
56
+ }
57
+ function detectIndent(content) {
58
+ const match = content.match(/^([\t ]+)\S/m);
59
+ if (!match)
60
+ return 2;
61
+ return match[1].includes("\t") ? "\t" : match[1].length;
62
+ }
63
+ function parsePackageJson(content, packageJsonPath) {
64
+ let value;
65
+ try {
66
+ value = JSON.parse(content);
67
+ }
68
+ catch (error) {
69
+ const message = error instanceof Error ? error.message : String(error);
70
+ throw new Error(`Invalid JSON in ${packageJsonPath}: ${message}`);
71
+ }
72
+ if (!isRecord(value))
73
+ throw new Error(`Invalid JSON in ${packageJsonPath}: expected an object`);
74
+ return value;
75
+ }
76
+ async function requiredDependencyVersions(packageRoot) {
77
+ const sourcePath = path.join(packageRoot, "package.json");
78
+ const source = parsePackageJson(await readFile(sourcePath, "utf8"), sourcePath);
79
+ // prettier is a runtime dependency of SpecDojo itself, so versions are resolved from both fields.
80
+ const dependencies = {
81
+ ...(isRecord(source.dependencies) ? source.dependencies : {}),
82
+ ...(isRecord(source.devDependencies) ? source.devDependencies : {}),
83
+ };
84
+ return Object.fromEntries(REQUIRED_DEV_DEPENDENCIES.map((name) => {
85
+ const version = dependencies[name];
86
+ if (typeof version !== "string") {
87
+ throw new Error(`SpecDojo package.json (${sourcePath}) does not declare dependency or devDependency: ${name}`);
88
+ }
89
+ return [name, version];
90
+ }));
91
+ }
92
+ async function updatePackageJson(opts) {
93
+ const packageJsonPath = path.join(opts.repoRoot, "package.json");
94
+ const requiredDependencies = await requiredDependencyVersions(opts.packageRoot);
95
+ if (!existsSync(packageJsonPath)) {
96
+ process.stdout.write("Skipped package.json update (package.json not found). Add these entries after creating it:\n" +
97
+ `${JSON.stringify({ scripts: REQUIRED_SCRIPTS, devDependencies: requiredDependencies }, null, 2)}\n`);
98
+ return;
99
+ }
100
+ const content = await readFile(packageJsonPath, "utf8");
101
+ const packageJson = parsePackageJson(content, packageJsonPath);
102
+ if (packageJson.scripts !== undefined && !isRecord(packageJson.scripts)) {
103
+ throw new Error(`Invalid ${packageJsonPath}: scripts must be an object`);
104
+ }
105
+ if (packageJson.dependencies !== undefined && !isRecord(packageJson.dependencies)) {
106
+ throw new Error(`Invalid ${packageJsonPath}: dependencies must be an object`);
107
+ }
108
+ if (packageJson.devDependencies !== undefined && !isRecord(packageJson.devDependencies)) {
109
+ throw new Error(`Invalid ${packageJsonPath}: devDependencies must be an object`);
110
+ }
111
+ const scripts = isRecord(packageJson.scripts) ? packageJson.scripts : {};
112
+ const dependencies = isRecord(packageJson.dependencies) ? packageJson.dependencies : {};
113
+ const devDependencies = isRecord(packageJson.devDependencies) ? packageJson.devDependencies : {};
114
+ const scriptAdditions = Object.fromEntries(Object.entries(REQUIRED_SCRIPTS).filter(([name]) => !Object.hasOwn(scripts, name)));
115
+ const dependencyAdditions = Object.fromEntries(Object.entries(requiredDependencies).filter(([name]) => !Object.hasOwn(dependencies, name) && !Object.hasOwn(devDependencies, name)));
116
+ const additions = { scripts: scriptAdditions, devDependencies: dependencyAdditions };
117
+ process.stdout.write(`Planned package.json additions:\n${JSON.stringify(additions, null, 2)}\n`);
118
+ for (const name of Object.keys(REQUIRED_SCRIPTS)) {
119
+ if (Object.hasOwn(scripts, name)) {
120
+ process.stdout.write(`Skipped (script already exists): ${name} in package.json\n`);
121
+ }
122
+ }
123
+ for (const name of REQUIRED_DEV_DEPENDENCIES) {
124
+ if (Object.hasOwn(dependencies, name) || Object.hasOwn(devDependencies, name)) {
125
+ process.stdout.write(`Skipped (dependency already exists): ${name} in package.json\n`);
126
+ }
127
+ }
128
+ if (opts.dryRun ||
129
+ (Object.keys(scriptAdditions).length === 0 && Object.keys(dependencyAdditions).length === 0)) {
130
+ return;
131
+ }
132
+ packageJson.scripts = { ...scripts, ...scriptAdditions };
133
+ packageJson.devDependencies = { ...devDependencies, ...dependencyAdditions };
134
+ await writeFile(packageJsonPath, `${JSON.stringify(packageJson, null, detectIndent(content))}\n`, "utf8");
135
+ process.stdout.write("Updated: package.json\n");
136
+ }
137
+ async function writeScaffoldFile(sourcePath, destinationPath, destinationLabel, content, opts) {
138
+ if (existsSync(destinationPath) && !opts.force) {
139
+ process.stdout.write(`Skipped (already exists): ${destinationLabel}\n`);
140
+ return;
141
+ }
142
+ if (opts.dryRun) {
143
+ process.stdout.write(`[dry-run] would write: ${destinationLabel}\n`);
144
+ return;
145
+ }
146
+ await mkdir(path.dirname(destinationPath), { recursive: true });
147
+ if (sourcePath)
148
+ await copyFile(sourcePath, destinationPath);
149
+ else
150
+ await writeFile(destinationPath, content ?? "", "utf8");
151
+ process.stdout.write(`Written: ${destinationLabel}\n`);
152
+ }
153
+ 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`);
157
+ }
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 });
162
+ }
163
+ export async function runLefthookScaffold(opts) {
164
+ const templateTools = path.join(opts.packageRoot, "templates", "lefthook", "tools");
165
+ await writeScaffoldFile(undefined, path.join(opts.repoRoot, "lefthook.yml"), "lefthook.yml", renderLefthookConfig(opts.config), opts);
166
+ await writeMarkdownlintScaffold(opts);
167
+ for (const filename of ["install-lefthook.mjs", "specdojo-pre-commit.mjs"]) {
168
+ await writeScaffoldFile(path.join(templateTools, filename), path.join(opts.repoRoot, "tools", filename), `tools/${filename}`, undefined, opts);
169
+ }
170
+ await updatePackageJson(opts);
171
+ if (!opts.dryRun) {
172
+ process.stdout.write("Next steps:\n" +
173
+ " 1. Run npm install and review the package.json additions shown above.\n" +
174
+ " 2. Run node tools/install-lefthook.mjs if an existing prepare script was kept.\n" +
175
+ " 3. Stage and commit lefthook.yml, markdownlint settings, tools/, and package.json.\n");
176
+ }
177
+ }
@@ -12,10 +12,11 @@ export const ORCHESTRATOR_NPM_SCRIPTS = {
12
12
  "orch:sonnet": "specdojo orchestrator launch --provider claude -- --agent specdojo-orchestrator --model sonnet",
13
13
  },
14
14
  codex: {
15
- "orch:codex": 'specdojo orchestrator launch --provider codex -- "$(cat .specdojo/codex/orchestrator.md)"',
15
+ "orch:sol": 'specdojo orchestrator launch --provider codex -- -m gpt-5.6-sol "$(cat .specdojo/codex/orchestrator.md)"',
16
+ "orch:terra": 'specdojo orchestrator launch --provider codex -- -m gpt-5.6-terra "$(cat .specdojo/codex/orchestrator.md)"',
16
17
  },
17
18
  antigravity: {
18
- "orch:agy": 'specdojo orchestrator launch --provider antigravity -- --add-dir "$(pwd)" -i "$(cat .specdojo/antigravity/orchestrator.md)"',
19
+ "orch:flash": 'specdojo orchestrator launch --provider antigravity -- --add-dir "$(pwd)" --model gemini-3.8-flash-high -i "$(cat .specdojo/antigravity/orchestrator.md)"',
19
20
  },
20
21
  opencode: {
21
22
  "orch:opencode": "specdojo orchestrator launch --provider opencode -- --agent specdojo-orchestrator",
@@ -4,6 +4,8 @@ import dotenv from "dotenv";
4
4
  import { dump, load } from "./yaml.js";
5
5
  import Ajv2020Module from "ajv/dist/2020.js";
6
6
  import { runProviderScaffold, specdojoPackageRootDir } from "./provider-scaffold.js";
7
+ import { runWorkspaceScaffold } from "./workspace-scaffold.js";
8
+ import { runLefthookScaffold } from "./lefthook-scaffold.js";
7
9
  import { ensureGitignore, formatGitignoreReport, gitignorePatternsForLayouts, } from "./specdojo-gitignore.js";
8
10
  /** Default IANA time zone for register date derivation when run.register_date_timezone is unset. */
9
11
  export const DEFAULT_REGISTER_DATE_TIMEZONE = "UTC";
@@ -56,6 +58,14 @@ export function resolveRepoRoot(rootDir, repo) {
56
58
  return resolve(rootDir, repo.path);
57
59
  }
58
60
  export const DEFAULT_PROJECT_CONTEXT = ["prj-overview"];
61
+ // Register events also have a small set of product-owned actors that do not represent a
62
+ // roster member. Keep this list closed: accepting arbitrary strings would make the audit log
63
+ // impossible to trace back to either a person, an agent, or a known SpecDojo component.
64
+ export const RESERVED_REGISTER_ACTORS = [
65
+ "SpecDojo",
66
+ "specdojo-orchestrator",
67
+ "night-orchestrator",
68
+ ];
59
69
  // Resolve either a concrete agent nickname or a backward-compatible alias to the concrete
60
70
  // member. Alias validity is checked while loading the roster, but keep the traversal guarded so
61
71
  // callers and tests that construct a roster directly cannot loop forever on malformed input.
@@ -83,6 +93,32 @@ export function resolveAgentMember(roster, nickname) {
83
93
  }
84
94
  return undefined;
85
95
  }
96
+ export function resolveRegisterActor(actor, roster) {
97
+ const normalized = actor.trim();
98
+ if (!normalized) {
99
+ throw new Error("Register event actor must not be empty");
100
+ }
101
+ if (RESERVED_REGISTER_ACTORS.includes(normalized))
102
+ return normalized;
103
+ const agent = resolveAgentMember(roster, normalized);
104
+ if (agent)
105
+ return agent.nickname;
106
+ const humans = roster?.members.filter((member) => member.type === "human" && member.nickname === normalized) ??
107
+ [];
108
+ if (humans.length === 1)
109
+ return humans[0].nickname;
110
+ if (humans.length > 1) {
111
+ throw new Error(`Duplicate human actor nickname in members_path: ${normalized}`);
112
+ }
113
+ const rosterNames = [
114
+ ...(roster?.members.map((member) => member.nickname) ?? []),
115
+ ...(roster?.aliases?.map((alias) => alias.nickname) ?? []),
116
+ ];
117
+ const accepted = [...new Set([...rosterNames, ...RESERVED_REGISTER_ACTORS])].sort();
118
+ throw new Error(`Unknown register actor: "${normalized}". Use a human nickname from members_path, ` +
119
+ `an agent nickname or alias from agent_members_path, or a reserved actor: ` +
120
+ accepted.join(", "));
121
+ }
86
122
  export const DEFAULT_AGENT_MEMBERS_PATH = ".specdojo/agent-members.yaml";
87
123
  function findUpward(startDir, name) {
88
124
  let currentDir = resolve(startDir);
@@ -109,13 +145,13 @@ export function specdojoRootDir() {
109
145
  export function defaultWorktreeBase(rootDir = specdojoRootDir()) {
110
146
  return `../${basename(resolve(rootDir))}-worktrees`;
111
147
  }
112
- export function loadEnv() {
148
+ export function loadEnv(rootDir = specdojoRootDir()) {
113
149
  // Load .env from the repository root if present.
114
150
  // Safe if missing.
115
- dotenv.config({ path: resolve(specdojoRootDir(), ".env"), quiet: true });
151
+ dotenv.config({ path: resolve(rootDir, ".env"), quiet: true });
116
152
  }
117
- export function defaultConfigPath() {
118
- return join(specdojoRootDir(), ".specdojo", "specdojo.config.json");
153
+ export function defaultConfigPath(rootDir = specdojoRootDir()) {
154
+ return join(resolve(rootDir), ".specdojo", "specdojo.config.json");
119
155
  }
120
156
  // Join a project document path with the project's base_path, returning a repo-root-relative path.
121
157
  // An empty/undefined base_path leaves the path unchanged (full backward compatibility).
@@ -500,6 +536,8 @@ function isValidProjectConfig(project) {
500
536
  return false;
501
537
  if (!isOmittedOrNonEmptyString(candidate.execution_path))
502
538
  return false;
539
+ if (!isOmittedOrNonEmptyString(candidate.integration_branch))
540
+ return false;
503
541
  if (candidate.project_context !== undefined &&
504
542
  (!Array.isArray(candidate.project_context) ||
505
543
  !candidate.project_context.every((ref) => typeof ref === "string" && ref.trim().length > 0))) {
@@ -507,9 +545,9 @@ function isValidProjectConfig(project) {
507
545
  }
508
546
  return true;
509
547
  }
510
- export function loadConfig() {
511
- loadEnv();
512
- const configPath = defaultConfigPath();
548
+ export function loadConfig(configRootDir = specdojoRootDir()) {
549
+ loadEnv(configRootDir);
550
+ const configPath = defaultConfigPath(configRootDir);
513
551
  if (!existsSync(configPath)) {
514
552
  return { configPath, config: null };
515
553
  }
@@ -527,7 +565,7 @@ export function loadConfig() {
527
565
  for (const [projectId, project] of Object.entries(parsed.projects)) {
528
566
  if (!isValidProjectConfig(project)) {
529
567
  throw new Error(`Invalid .specdojo/specdojo.config.json: projects.${projectId} must omit ` +
530
- `schedule_path/execution_path or set them to non-empty strings, ` +
568
+ `schedule_path/execution_path/integration_branch or set them to non-empty strings, ` +
531
569
  `and project_context must be a string[] when present`);
532
570
  }
533
571
  }
@@ -641,20 +679,52 @@ export function registerConfigCommands(program) {
641
679
  });
642
680
  cfg
643
681
  .command("scaffold")
644
- .description("Scaffold agent/settings templates for a provider")
645
- .requiredOption("--provider <name>", "Provider template to copy (antigravity|claude|codex|copilot|opencode)")
682
+ .description("Scaffold provider settings, a VS Code multi-root workspace, or Git hooks")
683
+ .option("--provider <name>", "Provider template to copy (antigravity|claude|codex|copilot|opencode)")
684
+ .option("--workspace", "Generate VS Code multi-root workspace (<project-id>.code-workspace) from repos config", false)
685
+ .option("--lefthook", "Generate pre-commit hooks for SpecDojo repositories", false)
686
+ .option("--project <id>", "Target project ID for workspace scaffolding (defaults to current_project)")
646
687
  .option("--force", "Overwrite existing files", false)
647
688
  .option("--dry-run", "Show planned files without writing", false)
648
689
  .option("--global", "Merge provider permissions into user-level settings (currently antigravity only)", false)
649
690
  .action(async (opts) => {
650
691
  try {
651
- await runProviderScaffold(String(opts.provider), {
652
- packageRoot: specdojoPackageRootDir(),
653
- repoRoot: specdojoRootDir(),
654
- force: !!opts.force,
655
- dryRun: !!opts.dryRun,
656
- global: !!opts.global,
657
- });
692
+ if (!opts.provider && !opts.workspace && !opts.lefthook) {
693
+ throw new Error("Specify --provider <name>, --workspace, or --lefthook to scaffold.");
694
+ }
695
+ if (opts.global && !opts.provider) {
696
+ throw new Error("--global requires --provider antigravity");
697
+ }
698
+ if (opts.provider) {
699
+ await runProviderScaffold(String(opts.provider), {
700
+ packageRoot: specdojoPackageRootDir(),
701
+ repoRoot: specdojoRootDir(),
702
+ force: !!opts.force,
703
+ dryRun: !!opts.dryRun,
704
+ global: !!opts.global,
705
+ });
706
+ }
707
+ if (opts.workspace) {
708
+ await runWorkspaceScaffold({
709
+ repoRoot: specdojoRootDir(),
710
+ projectId: opts.project ? String(opts.project) : undefined,
711
+ force: !!opts.force,
712
+ dryRun: !!opts.dryRun,
713
+ });
714
+ }
715
+ if (opts.lefthook) {
716
+ const { configPath, config } = loadConfig();
717
+ if (!config) {
718
+ throw new Error(`No config found: ${configPath}. Run specdojo config init first.`);
719
+ }
720
+ await runLefthookScaffold({
721
+ packageRoot: specdojoPackageRootDir(),
722
+ repoRoot: specdojoRootDir(),
723
+ config,
724
+ force: !!opts.force,
725
+ dryRun: !!opts.dryRun,
726
+ });
727
+ }
658
728
  }
659
729
  catch (error) {
660
730
  const message = error instanceof Error ? error.message : String(error);
@@ -45,7 +45,10 @@ export function expandTemplate(template, values) {
45
45
  // `: _PLACEHOLDER_` の空白が行末に残る。生成 plan は prettier の整形対象外
46
46
  // (.prettierignore)で checkpoint commit 時に markdownlint の MD009 が直接効くため、
47
47
  // ここで行末の空白を取り除く。
48
- return result.replace(/[ \t]+$/gm, "");
48
+ // 置換値が空のとき(夜間の承認の印がない register 個票の _AUTOPILOT_CONSTRAINTS_、
49
+ // agent の Job の _JOB_EXECUTION_、保守系の _PROJECT_CONTEXT_ など)、前後の空行が重なって
50
+ // MD012 で checkpoint commit が止まるため、2 行以上続く空行を 1 行にまとめる(PJR-283N)。
51
+ return result.replace(/[ \t]+$/gm, "").replace(/\n{3,}/g, "\n\n");
49
52
  }
50
53
  // 登録簿の自由記述(title / description 列など)を Markdown 本文へ埋め込む際の安全化。
51
54
  // `register_date_timezone` のようなアンダースコア入り識別子や `_TODO_` / `_ASSUMPTION_` が、
@@ -0,0 +1,125 @@
1
+ import { readYaml } from "./fs.js";
2
+ import { normalizeDateOnly } from "./time.js";
3
+ const CATALOG_STATUSES = ["not_started", "draft", "primary"];
4
+ function isRecord(value) {
5
+ return typeof value === "object" && value !== null && !Array.isArray(value);
6
+ }
7
+ function readStringArray(value, field, errors) {
8
+ if (value === undefined)
9
+ return [];
10
+ if (!Array.isArray(value)) {
11
+ errors.push(`${field}: must be an array of strings`);
12
+ return [];
13
+ }
14
+ const result = [];
15
+ for (const item of value) {
16
+ if (typeof item !== "string" || item.trim().length === 0) {
17
+ errors.push(`${field}: must contain non-empty strings only`);
18
+ continue;
19
+ }
20
+ result.push(item);
21
+ }
22
+ return result;
23
+ }
24
+ function parseTrack(raw, index, errors) {
25
+ const where = `tracks[${index}]`;
26
+ if (!isRecord(raw)) {
27
+ errors.push(`${where}: must be an object`);
28
+ return null;
29
+ }
30
+ const track = raw.track;
31
+ if (typeof track !== "string" || track.trim().length === 0) {
32
+ errors.push(`${where}.track: required non-empty string`);
33
+ return null;
34
+ }
35
+ const domains = readStringArray(raw.domains, `${where}.domains`, errors);
36
+ if (domains.length === 0)
37
+ errors.push(`${where}.domains: required non-empty array`);
38
+ const catalogStatus = raw.catalog_status;
39
+ if (typeof catalogStatus !== "string" ||
40
+ !CATALOG_STATUSES.includes(catalogStatus)) {
41
+ errors.push(`${where}.catalog_status: must be one of ${CATALOG_STATUSES.join(" | ")}`);
42
+ return null;
43
+ }
44
+ const order = raw.order;
45
+ if (typeof order !== "number" || !Number.isInteger(order) || order < 1) {
46
+ errors.push(`${where}.order: must be an integer >= 1`);
47
+ return null;
48
+ }
49
+ if (raw.depends_on === undefined) {
50
+ errors.push(`${where}.depends_on: required (use [] when there is no prerequisite)`);
51
+ }
52
+ const dependsOn = readStringArray(raw.depends_on, `${where}.depends_on`, errors);
53
+ const estimate = raw.catalog_duration_estimate_days;
54
+ if (estimate !== undefined && (typeof estimate !== "number" || estimate <= 0)) {
55
+ errors.push(`${where}.catalog_duration_estimate_days: must be a number > 0`);
56
+ }
57
+ const parallelGroup = raw.parallel_group;
58
+ if (parallelGroup !== undefined && typeof parallelGroup !== "string") {
59
+ errors.push(`${where}.parallel_group: must be a string`);
60
+ }
61
+ const note = raw.note;
62
+ if (note !== undefined && typeof note !== "string") {
63
+ errors.push(`${where}.note: must be a string`);
64
+ }
65
+ return {
66
+ track,
67
+ domains,
68
+ catalog_status: catalogStatus,
69
+ ...(typeof estimate === "number" ? { catalog_duration_estimate_days: estimate } : {}),
70
+ order,
71
+ ...(typeof parallelGroup === "string" ? { parallel_group: parallelGroup } : {}),
72
+ depends_on: dependsOn,
73
+ ...(typeof note === "string" ? { note } : {}),
74
+ };
75
+ }
76
+ export function loadTimelineIndex(filePath) {
77
+ const errors = [];
78
+ const parsed = readYaml(filePath);
79
+ if (!isRecord(parsed)) {
80
+ throw new Error(`${filePath}: invalid or empty YAML`);
81
+ }
82
+ const projectId = parsed.project_id;
83
+ if (typeof projectId !== "string" || projectId.trim().length === 0) {
84
+ errors.push(`project_id: required non-empty string`);
85
+ }
86
+ if (!Array.isArray(parsed.tracks) || parsed.tracks.length === 0) {
87
+ errors.push(`tracks: required non-empty array`);
88
+ return {
89
+ index: {
90
+ id: typeof parsed.id === "string" ? parsed.id : "",
91
+ project_id: typeof projectId === "string" ? projectId : "",
92
+ status: typeof parsed.status === "string" ? parsed.status : "",
93
+ tracks: [],
94
+ },
95
+ errors,
96
+ };
97
+ }
98
+ const tracks = [];
99
+ parsed.tracks.forEach((raw, index) => {
100
+ const track = parseTrack(raw, index, errors);
101
+ if (track)
102
+ tracks.push(track);
103
+ });
104
+ // 計画開始日は YYYY-MM-DD に正規化する。不正な値はエラーとして報告し、未設定とみなす。
105
+ let plannedStartDate;
106
+ if (parsed.planned_start_date !== undefined && parsed.planned_start_date !== null) {
107
+ const normalized = normalizeDateOnly(parsed.planned_start_date);
108
+ if (!normalized) {
109
+ errors.push("planned_start_date: must be a YYYY-MM-DD date");
110
+ }
111
+ else {
112
+ plannedStartDate = normalized;
113
+ }
114
+ }
115
+ return {
116
+ index: {
117
+ id: typeof parsed.id === "string" ? parsed.id : "",
118
+ project_id: typeof projectId === "string" ? projectId : "",
119
+ status: typeof parsed.status === "string" ? parsed.status : "",
120
+ tracks,
121
+ ...(plannedStartDate !== undefined ? { planned_start_date: plannedStartDate } : {}),
122
+ },
123
+ errors,
124
+ };
125
+ }
@@ -0,0 +1,69 @@
1
+ import { existsSync, readFileSync, writeFileSync } from "node:fs";
2
+ import { basename, join, resolve } from "node:path";
3
+ import { specdojoRootDir } from "./specdojo-config.js";
4
+ export function buildWorkspaceData(repoName, repos) {
5
+ return {
6
+ folders: [
7
+ { name: repoName, path: "." },
8
+ ...repos.map((repo) => ({ name: repo.name, path: repo.path })),
9
+ ],
10
+ };
11
+ }
12
+ export function renderWorkspaceContent(repoName, repos) {
13
+ const data = buildWorkspaceData(repoName, repos);
14
+ return `${JSON.stringify(data, null, 2)}\n`;
15
+ }
16
+ export async function runWorkspaceScaffold(options = {}) {
17
+ const repoRoot = options.repoRoot ? resolve(options.repoRoot) : specdojoRootDir();
18
+ const configPath = join(repoRoot, ".specdojo", "specdojo.config.json");
19
+ if (!existsSync(configPath)) {
20
+ throw new Error(`No config found: ${configPath}`);
21
+ }
22
+ let config;
23
+ try {
24
+ config = JSON.parse(readFileSync(configPath, "utf8"));
25
+ }
26
+ catch (error) {
27
+ throw new Error(`Failed to parse config: ${configPath}: ${error instanceof Error ? error.message : String(error)}`);
28
+ }
29
+ const projectId = options.projectId || config.current_project;
30
+ if (!projectId) {
31
+ throw new Error("No current_project configured. Specify --project <id>.");
32
+ }
33
+ const project = config.projects?.[projectId];
34
+ if (!project) {
35
+ throw new Error(`Unknown project: ${projectId}`);
36
+ }
37
+ if (!project.repos || project.repos.length === 0) {
38
+ throw new Error(`Project '${projectId}' has no 'repos' configured in ${configPath}. Declare 'repos' in the project configuration before scaffolding a multi-root workspace.`);
39
+ }
40
+ const repoName = basename(repoRoot);
41
+ const fileName = `${projectId}.code-workspace`;
42
+ const filePath = join(repoRoot, fileName);
43
+ if (existsSync(filePath) && !options.force) {
44
+ if (options.dryRun) {
45
+ process.stdout.write(`[dry-run] skipped: ${fileName} already exists (use --force to overwrite)\n`);
46
+ }
47
+ else {
48
+ process.stdout.write(`Skipped (already exists): ${fileName}\n`);
49
+ }
50
+ return {
51
+ status: "skipped",
52
+ relativePath: fileName,
53
+ absolutePath: filePath,
54
+ };
55
+ }
56
+ const content = renderWorkspaceContent(repoName, project.repos);
57
+ if (options.dryRun) {
58
+ process.stdout.write(`[dry-run] would write: ${fileName}\n`);
59
+ }
60
+ else {
61
+ writeFileSync(filePath, content, "utf8");
62
+ process.stdout.write(`Written: ${fileName}\n`);
63
+ }
64
+ return {
65
+ status: "written",
66
+ relativePath: fileName,
67
+ absolutePath: filePath,
68
+ };
69
+ }
@@ -17,6 +17,7 @@
17
17
  - 検査を実行する前に、リポジトリの `package.json`、`.specdojo/specdojo.config.json`、hook 設定(`lefthook.yml` など)を読み、本共通規約の詳細にある検査表の適用条件で、実行する検査を決める。
18
18
  - 適用条件を満たさない検査は実行せず、executor evidence の validations に `not_applicable` と非適用の理由を `reason` へ記録する。適用される検査が 1 つもない場合も同じく、該当する検査ごとに `not_applicable` と理由を記録する。
19
19
  - `not_run` は、適用される検査を実行できたのに実行しなかった場合だけに使う。runner は `not_run` を検証失敗として扱い、タスクを先へ進めない。
20
+ - `pipeline.parent_validations` に設定された検査は executor evidence の validations に含めなくてよい。executor が同じ検査を `not_run` または `not_applicable` として含めても、同じリポジトリで実行した親 runner の結果を正とする。
20
21
  - YAML 成果物を編集した場合、対応 schema `_SCHEMA_REF_` に従って記述する。`package.json` に `validate:schema:file` script がある場合だけ、`npm run validate:schema:file -- --schema _SCHEMA_REF_ --data <対象ファイル>` で schema 検査を実施する。適用した検査でエラーが出た場合は修正してから完了とする。
21
22
 
22
23
  <!-- plan-essentials:end -->
@@ -30,7 +31,7 @@
30
31
  - 編集・書き込みが作業ディレクトリ外(`external_directory`)として拒否された場合、原因はパス指定の誤り(誤った絶対パス・ディレクトリ名の取り違え)である。bash の heredoc などへ回避的に切り替えず、相対パスに直したうえで同じ編集ツールで再実行する。
31
32
  - 作業用のファイル(編集用スクリプト、検証用の一時データなど)はリポジトリの外(一時ディレクトリ)または worktree の `tmp/` 配下に置き、終了前に削除する。使い捨てのファイルを最上位に作らない。`tmp/` 配下のファイルは commit の対象から除外される。
32
33
  - 整形・静的検査は、この plan の完了手順または本共通規約で明示されたコマンドを実行する。変更対象に必要な test、build、schema 検証は、plan に個別記載がなくても実行してよい。同じ test script では対象限定と全件を同一 executor run 内で連続実行せず、どちらか一方に絞る。下表、plan、またはプロジェクト標準が全件 test を求める場合は、全件を1回だけ実行して対象限定の実行を省く。この制約は executor が sandbox 内で実行する test script の回数に対するものであり、親検証に設定された ID のコマンドは対象外である(親 runner が別途実行する)。実行したコマンド・対象・結果は result に記録する。
33
- - executor / reporter pipeline で親 runner の検証が設定されている場合、executor は設定済み ID に対応するコマンドを sandbox 内で実行せず、executor 終了後に親 runner が固定許可リストから実行して evidence へ追記する。`validate-schema` は `npm run validate:schema`、`test-unit` は `npm run test:unit`、`test-integration` は `npm run test:integration` に対応する。executor は親検証と同じコマンドの対象限定版も追加せず、二重実行しない。
34
+ - executor / reporter pipeline で親 runner の検証が設定されている場合、executor は設定済み ID に対応するコマンドを sandbox 内で実行せず、executor 終了後に親 runner が固定許可リストから実行して evidence へ追記する。`validate-schema` は `npm run validate:schema`、`test-unit` は `npm run test:unit`、`test-integration` は `npm run test:integration` に対応する。executor は親検証と同じコマンドの対象限定版も追加せず、二重実行しない。executor が親検証のコマンドを validations に含めた場合も、同じリポジトリで実行された親 runner の結果を正とし、executor の `not_run` / `not_applicable` は pipeline を失敗させない。
34
35
  - 適用条件の判定と `not_applicable` / `not_run` の使い分けは、要点に記した規則に従う。誤って `not_run` と記録しても、npm script・依存 package の不在、または SpecDojo サブコマンドの設定上の非適用を runner が機械的に確定できる場合は適用外として扱われるが、この救済を前提に記録を省略しない。
35
36
  - 依存パッケージの有無は、対象リポジトリの `package.json` の `dependencies` / `devDependencies` と、リポジトリに固定された package manager の設定を基準に判断する。`npx` が未導入パッケージをネットワークから一時取得できることは、導入済みとはみなさない。設定ファイルがない、壊れているなどの理由で適用条件を確定できない検査は実行せず、validations に `not_applicable` として理由と次の確認事項を記録する。
36
37
  - `npm init` が `package.json` に入れる仮の `test` script(`echo "Error: no test specified" && exit 1` と、引用符の有無・種類や空白だけが違う変種)は、常に失敗する仮置きであり、`test` script がないものとみなす。`npm test` は実行せず、validations に `not_applicable` と、仮の script である旨を `reason` に記録する。runner も同じ判断で `not_applicable` を受け付ける。本物の test script がある場合は適用される。
@@ -32,6 +32,8 @@ _GRADE_FINDINGS_
32
32
 
33
33
  plan に展開された finding は、message と同じ viewpoint ID の判定根拠に照らして解消する。未解消、根拠不足、または判断不能の場合は、理由と次のアクションを result に記録する。grade result サイドカーは再評価時に更新されるため、本タスクでは直接編集しない。
34
34
 
35
+ _AUTOPILOT_CONSTRAINTS_
36
+
35
37
  ## 4. 完了手順
36
38
 
37
39
  1. 「進め方」に従って対応を完了する。
@@ -0,0 +1,46 @@
1
+ _FRONTMATTER_
2
+
3
+ # Register Post-run Review Plan: _ITEM_ID_ _ITEM_TITLE_
4
+
5
+ ## 1. このフェーズで行うこと
6
+
7
+ `exec run --register` が統合した変更を読み取り専用で確認し、登録項目を自動で close できるかを判定する。
8
+
9
+ この review は成果物の grade ではなく、登録項目の完了判定である。grade サイドカーの有無や鮮度は判定条件にしない。verdict は `complete`、`complete-with-findings`、`incomplete` のいずれかにする。
10
+
11
+ ## 2. 確認対象
12
+
13
+ - 登録項目: `_ITEM_PATH_`
14
+ - edit plan: `_EDIT_PLAN_REF_`
15
+ - edit result: `_EDIT_RESULT_REF_`
16
+ - executor evidence: `_EDIT_EVIDENCE_REF_`
17
+ - 統合前 commit: `_BASE_COMMIT_`
18
+ - 統合後 commit: `_OUTPUT_COMMIT_`
19
+ - review result: `_RESULT_REF_`
20
+
21
+ ## 3. 完了条件
22
+
23
+ 1. 登録項目の「完了条件」を edit result、統合差分、検証結果と照合している。
24
+ 2. `_BASE_COMMIT_.._OUTPUT_COMMIT_` の差分に対象外の変更が混入していない。
25
+ 3. edit result と executor evidence に、完了を妨げる失敗、未実施の必須検証、未解消の申し送りがない。
26
+ 4. 完了条件を満たす場合は `complete`、軽微な finding を残して完了できる場合は `complete-with-findings`、未充足・根拠不足・検証失敗がある場合は `incomplete` とする。
27
+ 5. review executor は、確認のための読み取り専用コマンドだけを実行し、成果物、登録項目、edit plan/result を変更しない。
28
+
29
+ ## 4. 判断手順
30
+
31
+ 1. 登録項目の概要と完了条件、edit plan、edit result を読む。
32
+ 2. `git diff --stat _BASE_COMMIT_.._OUTPUT_COMMIT_` と `git diff --name-status _BASE_COMMIT_.._OUTPUT_COMMIT_` を実行し、必要に応じて同じ範囲の差分本文を読む。
33
+ 3. executor evidence がある場合は、変更一覧、検証結果、block 理由、申し送りを確認する。`_EDIT_EVIDENCE_REF_` が `-` の場合は、edit result と差分から確認できる範囲を判断根拠に明記する。
34
+ 4. 個票の各完了条件について、満たした根拠または未充足事項を具体的に記録する。
35
+ 5. result の「評価結果の確認」には、この review では grade を使わず、edit の検証結果を確認したことを書く。
36
+
37
+ ## 5. 完了手順
38
+
39
+ 1. review result の全セクションを埋める。
40
+ 2. `decision` に `complete`、`complete-with-findings`、`incomplete` のいずれかを記録する。
41
+ 3. verdict にかかわらず、review 自体を完了できた場合は終了コード 0 とする。
42
+
43
+ ## 6. 異常終了の条件
44
+
45
+ - 登録項目、edit plan/result、または統合差分を読めず review 自体を完了できない場合は終了コード 1 とする。
46
+ - review executor は review result を含むファイルを編集しない。result の記入は reporter が行う。