specdojo 0.2.0 → 0.3.0

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 (170) hide show
  1. package/.github/agents/specdojo-orchestrator.md +165 -0
  2. package/CHANGELOG.md +280 -0
  3. package/README.md +143 -30
  4. package/dist/agent-response.js +20 -0
  5. package/dist/agent.js +4 -4
  6. package/dist/build-command.js +28 -8
  7. package/dist/dashboard.js +140 -9
  8. package/dist/devcontainer-command.js +43 -0
  9. package/dist/devcontainer-scaffold.js +165 -0
  10. package/dist/exec-agent-config.js +107 -9
  11. package/dist/exec-agent-git-state.js +18 -0
  12. package/dist/exec-agent-protected-config.js +46 -8
  13. package/dist/exec-evidence.js +254 -11
  14. package/dist/exec-format.js +13 -4
  15. package/dist/exec-handoff.js +336 -0
  16. package/dist/exec-parent-validation.js +317 -43
  17. package/dist/exec-pipeline-state.js +74 -9
  18. package/dist/exec-plans.js +115 -113
  19. package/dist/exec-protection-handoff.js +43 -2
  20. package/dist/exec-provider-scaffold.js +247 -15
  21. package/dist/exec-register-resume.js +65 -19
  22. package/dist/exec-register.js +9 -3
  23. package/dist/exec-repo-integration.js +811 -0
  24. package/dist/exec-repo-trace.js +182 -0
  25. package/dist/exec-reporter.js +613 -132
  26. package/dist/exec-results.js +81 -56
  27. package/dist/exec-run-lock.js +110 -107
  28. package/dist/exec-run.js +1585 -356
  29. package/dist/exec-shared.js +7 -0
  30. package/dist/exec-slot-lock.js +242 -0
  31. package/dist/exec-task-repos.js +415 -0
  32. package/dist/exec-trial.js +51 -25
  33. package/dist/exec-worktree-command.js +87 -43
  34. package/dist/exec-worktree-ops.js +502 -57
  35. package/dist/exec-worktree.js +114 -27
  36. package/dist/exec.js +13 -6
  37. package/dist/grade-result.js +128 -0
  38. package/dist/grade.js +809 -72
  39. package/dist/init-command.js +443 -0
  40. package/dist/job.js +160 -10
  41. package/dist/orchestrator.js +213 -0
  42. package/dist/package-paths.js +19 -1
  43. package/dist/register-event-merge.js +169 -0
  44. package/dist/register-item.js +7 -1
  45. package/dist/register.js +294 -86
  46. package/dist/review-grade.js +252 -0
  47. package/dist/review-plan.js +111 -1
  48. package/dist/review-types.js +40 -1
  49. package/dist/routine.js +72 -5
  50. package/dist/schedule-build.js +2 -2
  51. package/dist/schedule.js +17 -4
  52. package/dist/specdojo-config.js +466 -20
  53. package/dist/specdojo-gitignore.js +135 -0
  54. package/dist/specdojo.js +8 -1
  55. package/dist/viewpoint-document-kinds-check.js +128 -0
  56. package/docs/ja/specdojo/defaults/pm-review-viewpoints.yaml +348 -90
  57. package/docs/ja/specdojo/exec-templates/xep-common-conventions-template.md +51 -17
  58. package/docs/ja/specdojo/exec-templates/xep-fully-guided-template.md +7 -5
  59. package/docs/ja/specdojo/exec-templates/xrp-freeform-template.md +29 -31
  60. package/docs/ja/specdojo/exec-templates/xrp-fully-guided-template.md +34 -55
  61. package/docs/ja/specdojo/exec-templates/xrp-job-template.md +54 -0
  62. package/docs/ja/specdojo/exec-templates/xrp-recipe-guided-template.md +28 -37
  63. package/docs/ja/specdojo/exec-templates/xrp-recipe-maintenance-template.md +29 -34
  64. package/docs/ja/specdojo/exec-templates/xrp-retrofit-template.md +30 -30
  65. package/docs/ja/specdojo/exec-templates/xrp-rulebook-maintenance-template.md +29 -34
  66. package/docs/ja/specdojo/exec-templates/xrp-sample-maintenance-template.md +29 -34
  67. package/docs/ja/specdojo/exec-templates/xrp-template-maintenance-template.md +29 -34
  68. package/docs/ja/specdojo/exec-templates/xrp-template.md +29 -28
  69. package/docs/ja/specdojo/exec-templates/xrr-template.md +11 -9
  70. package/docs/ja/specdojo/guides/docs-editing-guide.md +20 -0
  71. package/docs/ja/specdojo/guides/docs-structure-guide.md +103 -70
  72. package/docs/ja/specdojo/guides/exec-config-guide.md +91 -47
  73. package/docs/ja/specdojo/guides/exec-operation-guide.md +124 -27
  74. package/docs/ja/specdojo/guides/exec-worktree-guide.md +40 -11
  75. package/docs/ja/specdojo/guides/kata-guide.md +4 -4
  76. package/docs/ja/specdojo/guides/orchestrator-operation-guide.md +25 -4
  77. package/docs/ja/specdojo/guides/plan-result-lifecycle-guide.md +1 -1
  78. package/docs/ja/specdojo/guides/practice-system-composition-guide.md +13 -13
  79. package/docs/ja/specdojo/guides/quick-start-guide.md +261 -32
  80. package/docs/ja/specdojo/guides/register-operation-guide.md +31 -14
  81. package/docs/ja/specdojo/guides/release-v0-3-0-migration-guide.md +264 -0
  82. package/docs/ja/specdojo/guides/remote-host-development-guide.md +184 -0
  83. package/docs/ja/specdojo/guides/review-guide.md +195 -158
  84. package/docs/ja/specdojo/guides/routine-operation-guide.md +74 -9
  85. package/docs/ja/specdojo/guides/ryu-guide.md +32 -30
  86. package/docs/ja/specdojo/guides/schedule-design-guide.md +10 -10
  87. package/docs/ja/specdojo/guides/schedule-operation-guide.md +1 -1
  88. package/docs/ja/specdojo/guides/specdojo-overview-guide.md +58 -33
  89. package/docs/ja/specdojo/guides/use-case-guide.md +3 -3
  90. package/docs/ja/specdojo/guides/waza-guide.md +15 -2
  91. package/docs/ja/specdojo/index.md +2 -2
  92. package/docs/ja/specdojo/philosophy/specdojo-philosophy.md +5 -5
  93. package/docs/ja/specdojo/recipes/bps-recipe.md +213 -0
  94. package/docs/ja/specdojo/recipes/pm-members-recipe.md +52 -117
  95. package/docs/ja/specdojo/references/command-reference.md +336 -93
  96. package/docs/ja/specdojo/references/deliverables-reference.md +1 -1
  97. package/docs/ja/specdojo/references/directory-layout-reference.md +13 -9
  98. package/docs/ja/specdojo/references/specdojo-config-reference.md +107 -24
  99. package/docs/ja/specdojo/rulebooks/bps-rulebook.md +132 -220
  100. package/docs/ja/specdojo/rulebooks/br-rulebook.md +6 -44
  101. package/docs/ja/specdojo/rulebooks/cdfd-rulebook.md +2 -0
  102. package/docs/ja/specdojo/rulebooks/dmd-rulebook.md +0 -87
  103. package/docs/ja/specdojo/rulebooks/gl-rulebook.md +61 -39
  104. package/docs/ja/specdojo/rulebooks/ifx-cmd-rulebook.md +0 -87
  105. package/docs/ja/specdojo/rulebooks/ifx-index-rulebook.md +1 -33
  106. package/docs/ja/specdojo/rulebooks/opd-rulebook.md +0 -137
  107. package/docs/ja/specdojo/rulebooks/opr-rulebook.md +0 -247
  108. package/docs/ja/specdojo/rulebooks/otp-rulebook.md +0 -83
  109. package/docs/ja/specdojo/rulebooks/pjr-rulebook.md +4 -2
  110. package/docs/ja/specdojo/rulebooks/pm-members-rulebook.md +78 -150
  111. package/docs/ja/specdojo/rulebooks/pm-roles-rulebook.md +5 -4
  112. package/docs/ja/specdojo/rulebooks/sch-rulebook.md +1 -1
  113. package/docs/ja/specdojo/rulebooks/stsd-mermaid-rulebook.md +0 -11
  114. package/docs/ja/specdojo/rulebooks/stsd-rulebook.md +0 -61
  115. package/docs/ja/specdojo/rulebooks/tml-rulebook.md +2 -47
  116. package/docs/ja/specdojo/samples/bps-sample.md +74 -21
  117. package/docs/ja/specdojo/samples/gl-sample.yaml +17 -1
  118. package/docs/ja/specdojo/samples/ifx-index-sample.yaml +28 -0
  119. package/docs/ja/specdojo/samples/pm-members-sample.yaml +2 -67
  120. package/docs/ja/specdojo/samples/pm-organization-sample.md +8 -7
  121. package/docs/ja/specdojo/samples/pm-raci-sample.md +1 -1
  122. package/docs/ja/specdojo/samples/tml-sample.yaml +40 -0
  123. package/docs/ja/specdojo/standards/document-metadata-standard.md +21 -16
  124. package/docs/ja/specdojo/standards/id-and-file-naming-standard.md +14 -14
  125. package/docs/ja/specdojo/standards/job-definition-standard.md +37 -17
  126. package/docs/ja/specdojo/standards/people-and-organization-definition-standard.md +37 -32
  127. package/docs/ja/specdojo/standards/philosophy-authoring-standard.md +1 -1
  128. package/docs/ja/specdojo/standards/rulebook-authoring-standard.md +21 -11
  129. package/docs/ja/specdojo/templates/agent-members-template.yaml +25 -0
  130. package/docs/ja/specdojo/templates/bps-template.md +91 -0
  131. package/docs/ja/specdojo/templates/pm-members-template.yaml +2 -59
  132. package/docs/specdojo/schemas/v1/agent-members.schema.yaml +76 -0
  133. package/docs/specdojo/schemas/v1/exec-common.schema.yaml +4 -2
  134. package/docs/specdojo/schemas/v1/exec-defaults.schema.yaml +55 -2
  135. package/docs/specdojo/schemas/v1/exec-evidence.schema.yaml +93 -6
  136. package/docs/specdojo/schemas/v1/exec-reporter-output.schema.yaml +27 -78
  137. package/docs/specdojo/schemas/v1/gl.schema.yaml +87 -0
  138. package/docs/specdojo/schemas/v1/grade-result.schema.yaml +33 -0
  139. package/docs/specdojo/schemas/v1/job-run.schema.yaml +27 -0
  140. package/docs/specdojo/schemas/v1/job.schema.yaml +25 -0
  141. package/docs/specdojo/schemas/v1/pipeline-state.schema.yaml +49 -1
  142. package/docs/specdojo/schemas/v1/pm-members.schema.yaml +9 -169
  143. package/docs/specdojo/schemas/v1/pm-review-viewpoints.schema.yaml +100 -10
  144. package/docs/specdojo/schemas/v1/register-item-frontmatter.schema.yaml +13 -0
  145. package/docs/specdojo/schemas/v1/routine-run.schema.yaml +3 -0
  146. package/docs/specdojo/schemas/v1/routine.schema.yaml +7 -0
  147. package/docs/specdojo/schemas/v1/specdojo-config.schema.yaml +110 -0
  148. package/package.json +16 -9
  149. package/templates/antigravity/README.md +60 -0
  150. package/templates/antigravity/agent-members-snippet.yaml +61 -0
  151. package/templates/antigravity/exec-defaults-snippet.yaml +39 -0
  152. package/templates/antigravity/orchestrator.md +157 -0
  153. package/templates/antigravity/settings.global.json +55 -0
  154. package/templates/claude/agents/claude-executor.md +14 -0
  155. package/templates/claude/agents/claude-reporter.md +16 -0
  156. package/templates/claude/agents/specdojo-orchestrator.md +164 -0
  157. package/templates/claude/settings.edit.json +27 -1
  158. package/templates/codex/README.md +5 -4
  159. package/templates/codex/agents/specdojo-orchestrator.toml +165 -0
  160. package/templates/codex/orchestrator.md +157 -0
  161. package/templates/copilot/README.md +7 -5
  162. package/templates/copilot/{pm-members-snippet.yaml → agent-members-snippet.yaml} +4 -2
  163. package/templates/devcontainer/devcontainer.json +27 -0
  164. package/templates/devcontainer/emacs/init.el +88 -0
  165. package/templates/devcontainer/post-create.sh +62 -0
  166. package/templates/init-agent-members.yaml +200 -0
  167. package/templates/init-exec-defaults.yaml +72 -0
  168. package/templates/opencode/agents/specdojo-orchestrator.md +204 -0
  169. package/docs/ja/specdojo/exec-templates/xrp-viewpoint-detail-template.md +0 -7
  170. package/docs/ja/specdojo/exec-templates/xrr-viewpoint-detail-template.md +0 -7
@@ -1,12 +1,62 @@
1
- import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
2
- import { dirname, join, resolve } from "node:path";
1
+ import { existsSync, mkdirSync, readFileSync, statSync, writeFileSync } from "node:fs";
2
+ import { basename, dirname, isAbsolute, join, posix, relative, resolve } from "node:path";
3
3
  import dotenv from "dotenv";
4
4
  import yaml from "js-yaml";
5
+ import Ajv2020Module from "ajv/dist/2020.js";
5
6
  import { runProviderScaffold, specdojoPackageRootDir } from "./exec-provider-scaffold.js";
7
+ import { ensureGitignore, formatGitignoreReport, gitignorePatternsForLayouts, } from "./specdojo-gitignore.js";
6
8
  /** Default IANA time zone for register date derivation when run.register_date_timezone is unset. */
7
9
  export const DEFAULT_REGISTER_DATE_TIMEZONE = "UTC";
8
10
  export const SPECDOJO_CONFIG_REFERENCE_URL = "https://specdojo.github.io/specdojo/ja/specdojo/references/specdojo-config-reference.html";
11
+ export const REPO_NAME_PATTERN = /^[a-z0-9-]+$/;
12
+ /**
13
+ * Directory name of the project repository worktree under `<worktree_base>/<task-id>/` when the
14
+ * project declares `repos`. Product worktrees sit beside it as `<task-id>/<repo-name>/`, so a
15
+ * repository must not use this name.
16
+ */
17
+ export const PROJECT_REPO_WORKTREE_DIRNAME = "project";
18
+ function readTextFileOrNull(path) {
19
+ try {
20
+ return readFileSync(path, "utf8");
21
+ }
22
+ catch {
23
+ return null;
24
+ }
25
+ }
26
+ /**
27
+ * True when `rootDir` is the project worktree of a multi-repository exec task, i.e.
28
+ * `<worktree_base>/<task-name>/project/` checked out on `exec/<task-name>`. Detected from the
29
+ * linked worktree's `.git` file and HEAD only (no git process), so it is cheap enough to run on
30
+ * every config load.
31
+ */
32
+ export function isMultiRepoProjectWorktree(rootDir) {
33
+ const root = resolve(rootDir);
34
+ if (basename(root) !== PROJECT_REPO_WORKTREE_DIRNAME)
35
+ return false;
36
+ const dotGit = join(root, ".git");
37
+ if (!existsSync(dotGit) || statSync(dotGit).isDirectory())
38
+ return false;
39
+ const gitdirLine = readTextFileOrNull(dotGit)
40
+ ?.split(/\r?\n/)
41
+ .find((line) => line.startsWith("gitdir:"));
42
+ if (!gitdirLine)
43
+ return false;
44
+ const gitdir = resolve(root, gitdirLine.slice("gitdir:".length).trim());
45
+ const head = readTextFileOrNull(join(gitdir, "HEAD"))?.trim();
46
+ return head === `ref: refs/heads/exec/${basename(dirname(root))}`;
47
+ }
48
+ /**
49
+ * Absolute root of a declared repository. Normally `path` is resolved from the SpecDojo root.
50
+ * Inside the project worktree of a multi-repository exec task, the repository is the sibling
51
+ * worktree `<task-name>/<repo-name>/`, so `path` (written for the main checkout) is not used.
52
+ */
53
+ export function resolveRepoRoot(rootDir, repo) {
54
+ if (isMultiRepoProjectWorktree(rootDir))
55
+ return join(dirname(resolve(rootDir)), repo.name);
56
+ return resolve(rootDir, repo.path);
57
+ }
9
58
  export const DEFAULT_PROJECT_CONTEXT = ["prj-overview"];
59
+ export const DEFAULT_AGENT_MEMBERS_PATH = ".specdojo/agent-members.yaml";
10
60
  function findUpward(startDir, name) {
11
61
  let currentDir = resolve(startDir);
12
62
  while (true) {
@@ -28,6 +78,10 @@ export function specdojoRootDir() {
28
78
  return dirname(gitMarker);
29
79
  return process.cwd();
30
80
  }
81
+ /** Default worktree directory beside the repository, derived from its directory name. */
82
+ export function defaultWorktreeBase(rootDir = specdojoRootDir()) {
83
+ return `../${basename(resolve(rootDir))}-worktrees`;
84
+ }
31
85
  export function loadEnv() {
32
86
  // Load .env from the repository root if present.
33
87
  // Safe if missing.
@@ -88,20 +142,258 @@ export function getProjectContext(project) {
88
142
  ? [...DEFAULT_PROJECT_CONTEXT]
89
143
  : [...project.project_context];
90
144
  }
145
+ export function getProjectRepos(project) {
146
+ return project.repos ? project.repos.map((repo) => ({ ...repo })) : [];
147
+ }
148
+ function isRecord(value) {
149
+ return typeof value === "object" && value !== null && !Array.isArray(value);
150
+ }
151
+ const REPO_KEYS = new Set(["name", "path", "integration_branch", "setup"]);
152
+ const REPO_SETUP_KEYS = new Set(["install", "build"]);
153
+ /**
154
+ * Validate `projects.<projectId>.repos`. Returns one message per problem (empty when valid) so
155
+ * loadConfig can report every misconfigured repository at once. `path` is resolved from
156
+ * `rootDir` (the SpecDojo root) and must exist.
157
+ */
158
+ export function validateProjectRepos(projectId, project, projectIds, rootDir) {
159
+ const repos = project.repos;
160
+ if (repos === undefined)
161
+ return [];
162
+ const where = `projects.${projectId}.repos`;
163
+ if (!Array.isArray(repos))
164
+ return [`${where} must be an array`];
165
+ const errors = [];
166
+ const seen = new Map();
167
+ repos.forEach((repo, index) => {
168
+ const at = `${where}[${index}]`;
169
+ if (!isRecord(repo)) {
170
+ errors.push(`${at} must be an object with name and path`);
171
+ return;
172
+ }
173
+ for (const key of Object.keys(repo).sort()) {
174
+ if (!REPO_KEYS.has(key))
175
+ errors.push(`${at}: unknown key "${key}"`);
176
+ }
177
+ const name = repo.name;
178
+ if (typeof name !== "string" || !REPO_NAME_PATTERN.test(name)) {
179
+ errors.push(`${at}.name must match ${String(REPO_NAME_PATTERN)} (got ${JSON.stringify(name)})`);
180
+ }
181
+ else if (name === PROJECT_REPO_WORKTREE_DIRNAME) {
182
+ errors.push(`${at}.name "${name}" is reserved: the project repository worktree uses ` +
183
+ `<worktree_base>/<task-id>/${PROJECT_REPO_WORKTREE_DIRNAME}/`);
184
+ }
185
+ else {
186
+ const firstIndex = seen.get(name);
187
+ if (firstIndex !== undefined) {
188
+ errors.push(`${at}.name "${name}" duplicates ${where}[${firstIndex}].name`);
189
+ }
190
+ else {
191
+ seen.set(name, index);
192
+ }
193
+ if (projectIds.includes(name)) {
194
+ errors.push(`${at}.name "${name}" collides with project id "${name}"; ` +
195
+ `"${name}:<...>" in targets would be ambiguous between a repository path and a doc id`);
196
+ }
197
+ }
198
+ const path = repo.path;
199
+ if (typeof path !== "string" || path.trim().length === 0) {
200
+ errors.push(`${at}.path must be a non-empty string`);
201
+ }
202
+ else if (isAbsolute(path)) {
203
+ errors.push(`${at}.path must be relative to the SpecDojo root (got absolute "${path}")`);
204
+ }
205
+ else {
206
+ const absolutePath = typeof name === "string" && REPO_NAME_PATTERN.test(name)
207
+ ? resolveRepoRoot(rootDir, { name, path })
208
+ : resolve(rootDir, path);
209
+ if (!existsSync(absolutePath)) {
210
+ errors.push(`${at}.path "${path}" does not exist (resolved to ${absolutePath})`);
211
+ }
212
+ else if (!statSync(absolutePath).isDirectory()) {
213
+ errors.push(`${at}.path "${path}" is not a directory (resolved to ${absolutePath})`);
214
+ }
215
+ }
216
+ if (repo.integration_branch !== undefined &&
217
+ !isOmittedOrNonEmptyString(repo.integration_branch)) {
218
+ errors.push(`${at}.integration_branch must be a non-empty string when present`);
219
+ }
220
+ const setup = repo.setup;
221
+ if (setup !== undefined) {
222
+ if (!isRecord(setup)) {
223
+ errors.push(`${at}.setup must be an object ({ install?: boolean, build?: boolean })`);
224
+ }
225
+ else {
226
+ for (const [key, value] of Object.entries(setup).sort(([a], [b]) => a.localeCompare(b))) {
227
+ if (!REPO_SETUP_KEYS.has(key))
228
+ errors.push(`${at}.setup: unknown key "${key}"`);
229
+ else if (typeof value !== "boolean")
230
+ errors.push(`${at}.setup.${key} must be a boolean`);
231
+ }
232
+ }
233
+ }
234
+ });
235
+ return errors;
236
+ }
237
+ /**
238
+ * Resolve a `targets` / `paths` value. The value is a repository path only when the prefix
239
+ * before the first `:` is a declared repository name; any other value (including doc ids such as
240
+ * `prj-0001:foo` and un-prefixed values) is returned unchanged as `project`.
241
+ */
242
+ export function resolveRepoQualifiedRef(value, repos) {
243
+ const trimmed = value.trim();
244
+ const separator = trimmed.indexOf(":");
245
+ if (separator <= 0)
246
+ return { kind: "project", value: trimmed };
247
+ const prefix = trimmed.slice(0, separator);
248
+ if (!repos.some((repo) => repo.name === prefix))
249
+ return { kind: "project", value: trimmed };
250
+ const rawPath = trimmed.slice(separator + 1).replaceAll("\\", "/");
251
+ if (rawPath.trim().length === 0) {
252
+ throw new Error(`Invalid repository path "${value}": the path after "${prefix}:" is empty`);
253
+ }
254
+ if (posix.isAbsolute(rawPath) || /^[A-Za-z]:\//.test(rawPath)) {
255
+ throw new Error(`Invalid repository path "${value}": the path must be relative to repository "${prefix}"`);
256
+ }
257
+ const normalized = posix.normalize(rawPath).replace(/\/+$/, "");
258
+ if (normalized === ".." || normalized.startsWith("../")) {
259
+ throw new Error(`Invalid repository path "${value}": the path escapes repository "${prefix}"`);
260
+ }
261
+ return { kind: "repo", repo: prefix, path: normalized === "" ? "." : normalized };
262
+ }
263
+ /**
264
+ * Resolve a `<repo>:<path>` value to an absolute path under the declared repository. Returns
265
+ * null for values that are not repository-qualified so callers keep their current handling.
266
+ */
267
+ export function resolveRepoQualifiedPath(rootDir, project, value) {
268
+ const repos = getProjectRepos(project);
269
+ const ref = resolveRepoQualifiedRef(value, repos);
270
+ if (ref.kind !== "repo")
271
+ return null;
272
+ const repo = repos.find((candidate) => candidate.name === ref.repo);
273
+ if (!repo)
274
+ return null;
275
+ return {
276
+ repo: ref.repo,
277
+ path: ref.path,
278
+ absolutePath: resolve(resolveRepoRoot(rootDir, repo), ref.path),
279
+ };
280
+ }
91
281
  export function loadMemberRoster(baseDir, project) {
92
282
  const membersPath = getProjectMembersPath(project);
93
- if (!membersPath)
283
+ let humanRoster;
284
+ let humanFullPath;
285
+ if (membersPath) {
286
+ humanFullPath = resolve(baseDir, membersPath);
287
+ if (!existsSync(humanFullPath)) {
288
+ throw new Error(`members_path not found: ${humanFullPath}`);
289
+ }
290
+ const parsed = readYamlFile(humanFullPath);
291
+ if (!parsed || !Array.isArray(parsed.members)) {
292
+ throw new Error(`Invalid members file: ${humanFullPath} (expected { members: [...] })`);
293
+ }
294
+ const legacyAgent = parsed.members.find((member) => member?.type === "agent");
295
+ if (legacyAgent) {
296
+ throw new Error(`Invalid members file: ${humanFullPath}: agent '${legacyAgent.nickname ?? "<unknown>"}' ` +
297
+ `must be moved to ${resolve(baseDir, configuredAgentMembersPath(baseDir))}. ` +
298
+ `Run: specdojo config migrate-members --dry-run`);
299
+ }
300
+ validateMemberFile("pm-members.schema.yaml", humanFullPath, parsed);
301
+ humanRoster = parsed;
302
+ }
303
+ const agentMembersPath = configuredAgentMembersPath(baseDir);
304
+ const agentFullPath = resolve(baseDir, agentMembersPath);
305
+ let agentRoster;
306
+ if (existsSync(agentFullPath)) {
307
+ agentRoster = readYamlFile(agentFullPath);
308
+ if (!agentRoster || !Array.isArray(agentRoster.members)) {
309
+ throw new Error(`Invalid agent members file: ${agentFullPath} (expected { members: [...] })`);
310
+ }
311
+ const human = agentRoster.members.find((member) => member?.type === "human");
312
+ if (human) {
313
+ throw new Error(`Invalid agent members file: ${agentFullPath}: human '${human.nickname ?? "<unknown>"}' is not allowed`);
314
+ }
315
+ validateMemberFile("agent-members.schema.yaml", agentFullPath, agentRoster);
316
+ }
317
+ if (!humanRoster && !agentRoster)
94
318
  return null;
95
- const fullPath = resolve(baseDir, membersPath);
96
- if (!existsSync(fullPath)) {
97
- throw new Error(`members_path not found: ${fullPath}`);
319
+ const membersWithSources = [
320
+ ...(humanRoster?.members.map((member) => ({ member, source: humanFullPath })) ?? []),
321
+ ...(agentRoster?.members.map((member) => ({ member, source: agentFullPath })) ?? []),
322
+ ];
323
+ const seen = new Map();
324
+ for (const { member, source } of membersWithSources) {
325
+ const previousSource = seen.get(member.nickname);
326
+ if (previousSource) {
327
+ throw new Error(`Duplicate member nickname '${member.nickname}' across ${previousSource} and ${source}`);
328
+ }
329
+ seen.set(member.nickname, source);
98
330
  }
99
- const raw = readFileSync(fullPath, "utf8");
100
- const parsed = yaml.load(raw);
101
- if (!parsed || !Array.isArray(parsed.members)) {
102
- throw new Error(`Invalid members file: ${fullPath} (expected { members: [...] })`);
331
+ const members = membersWithSources.map(({ member }) => member);
332
+ if (humanRoster)
333
+ return { ...humanRoster, members };
334
+ return { version: agentRoster?.version ?? 1, members };
335
+ }
336
+ const Ajv2020 = Ajv2020Module.default;
337
+ const memberSchemaValidators = new Map();
338
+ function readYamlFile(path) {
339
+ try {
340
+ return yaml.load(readFileSync(path, "utf8"));
341
+ }
342
+ catch (error) {
343
+ throw new Error(`Invalid YAML: ${path}: ${error instanceof Error ? error.message : String(error)}`);
344
+ }
345
+ }
346
+ function memberSchemaValidator(schemaName) {
347
+ const schemaDir = join(specdojoPackageRootDir(), "docs", "specdojo", "schemas", "v1");
348
+ const cacheKey = `${schemaDir}/${schemaName}`;
349
+ const cached = memberSchemaValidators.get(cacheKey);
350
+ if (cached)
351
+ return cached;
352
+ const ajv = new Ajv2020({ allErrors: true, strict: false });
353
+ ajv.addFormat("email", /^[^\s@]+@[^\s@]+\.[^\s@]+$/);
354
+ for (const entry of ["exec-common.schema.yaml", "pm-members.schema.yaml"]) {
355
+ if (entry === schemaName)
356
+ continue;
357
+ const path = join(schemaDir, entry);
358
+ if (existsSync(path))
359
+ ajv.addSchema(readYamlFile(path), entry);
360
+ }
361
+ const validator = ajv.compile(readYamlFile(join(schemaDir, schemaName)));
362
+ memberSchemaValidators.set(cacheKey, validator);
363
+ return validator;
364
+ }
365
+ function validateMemberFile(schemaName, path, value) {
366
+ const validate = memberSchemaValidator(schemaName);
367
+ if (validate(value))
368
+ return;
369
+ const details = (validate.errors ?? [])
370
+ .map((error) => `${error.instancePath || "/"} ${error.message ?? "is invalid"}`)
371
+ .join("; ");
372
+ throw new Error(`Schema validation failed: ${path}: ${details}`);
373
+ }
374
+ function dumpMemberFile(path, schemaName, value) {
375
+ const schemaPath = join(specdojoPackageRootDir(), "docs", "specdojo", "schemas", "v1", schemaName);
376
+ const schemaRef = relative(dirname(path), schemaPath).replaceAll("\\", "/");
377
+ return (`# yaml-language-server: $schema=${schemaRef}\n` +
378
+ yaml.dump(value, { lineWidth: 100, noRefs: true }));
379
+ }
380
+ function configuredAgentMembersPath(baseDir) {
381
+ const configPath = resolve(baseDir, ".specdojo", "specdojo.config.json");
382
+ if (!existsSync(configPath))
383
+ return DEFAULT_AGENT_MEMBERS_PATH;
384
+ const parsed = JSON.parse(readFileSync(configPath, "utf8"));
385
+ const configured = parsed.agent_members_path?.trim() || DEFAULT_AGENT_MEMBERS_PATH;
386
+ assertProtectedAgentMembersPath(configured, configPath);
387
+ return configured;
388
+ }
389
+ function assertProtectedAgentMembersPath(path, source) {
390
+ const normalized = path.replaceAll("\\", "/");
391
+ if (isAbsolute(path) ||
392
+ !normalized.startsWith(".specdojo/") ||
393
+ normalized.includes("../") ||
394
+ !/\.ya?ml$/i.test(normalized)) {
395
+ throw new Error(`Invalid agent_members_path in ${source}: expected a repository-relative YAML path under .specdojo/`);
103
396
  }
104
- return parsed;
105
397
  }
106
398
  export function assertValidActor(actor, roster) {
107
399
  if (!roster)
@@ -109,7 +401,7 @@ export function assertValidActor(actor, roster) {
109
401
  const known = roster.members.map((m) => m.nickname);
110
402
  if (!known.includes(actor)) {
111
403
  throw new Error(`Unknown actor: "${actor}". Must be one of: ${known.join(", ")}\n` +
112
- `Register the nickname in members_path file before use.`);
404
+ `Register a human in members_path or an agent in agent_members_path before use.`);
113
405
  }
114
406
  }
115
407
  function isOmittedOrNonEmptyString(value) {
@@ -145,6 +437,12 @@ export function loadConfig() {
145
437
  if (!parsed || parsed.version !== 1 || typeof parsed.projects !== "object") {
146
438
  throw new Error(`Invalid .specdojo/specdojo.config.json: expected { version: 1, projects: { ... } }`);
147
439
  }
440
+ if (parsed.agent_members_path !== undefined) {
441
+ if (!isOmittedOrNonEmptyString(parsed.agent_members_path)) {
442
+ throw new Error(`Invalid .specdojo/specdojo.config.json: agent_members_path must be a non-empty string`);
443
+ }
444
+ assertProtectedAgentMembersPath(parsed.agent_members_path, configPath);
445
+ }
148
446
  for (const [projectId, project] of Object.entries(parsed.projects)) {
149
447
  if (!isValidProjectConfig(project)) {
150
448
  throw new Error(`Invalid .specdojo/specdojo.config.json: projects.${projectId} must omit ` +
@@ -152,6 +450,15 @@ export function loadConfig() {
152
450
  `and project_context must be a string[] when present`);
153
451
  }
154
452
  }
453
+ const projectIds = Object.keys(parsed.projects);
454
+ const rootDir = dirname(dirname(configPath));
455
+ const repoErrors = projectIds
456
+ .sort()
457
+ .flatMap((projectId) => validateProjectRepos(projectId, parsed.projects[projectId], projectIds, rootDir));
458
+ if (repoErrors.length > 0) {
459
+ throw new Error(`Invalid .specdojo/specdojo.config.json (${configPath}):\n` +
460
+ repoErrors.map((message) => ` - ${message}`).join("\n"));
461
+ }
155
462
  return { configPath, config: parsed };
156
463
  }
157
464
  export function writeConfig(config) {
@@ -159,19 +466,51 @@ export function writeConfig(config) {
159
466
  mkdirSync(dirname(configPath), { recursive: true });
160
467
  writeFileSync(configPath, JSON.stringify(config, null, 2) + "\n", "utf8");
161
468
  }
469
+ // Resolve the repo-root-relative paths whose generated/ outputs must stay untracked.
470
+ // members/roles/viewpoints are single files, so they never hold a generated/ directory.
471
+ export function projectGitignoreLayout(project) {
472
+ const projectPaths = [
473
+ getProjectCatalogPath(project),
474
+ getProjectSchedulePath(project),
475
+ getProjectExecutionPath(project),
476
+ getProjectTimelinePath(project),
477
+ getProjectRegisterPath(project),
478
+ getProjectRoutinesPath(project),
479
+ getProjectJobsPath(project),
480
+ ].filter((path) => path !== undefined);
481
+ return {
482
+ basePath: project.base_path,
483
+ projectPaths,
484
+ executionPath: getProjectExecutionPath(project),
485
+ };
486
+ }
487
+ function writeGitignoreForConfig(config, dryRun) {
488
+ const layouts = Object.keys(config.projects)
489
+ .sort()
490
+ .map((id) => projectGitignoreLayout(config.projects[id]));
491
+ const result = ensureGitignore(specdojoRootDir(), gitignorePatternsForLayouts(layouts), {
492
+ dryRun,
493
+ });
494
+ process.stdout.write(formatGitignoreReport(result, dryRun));
495
+ }
162
496
  export function registerConfigCommands(program) {
163
497
  const cfg = program
164
498
  .command("config")
165
499
  .description("Config helpers (.specdojo/specdojo.config.json)");
166
500
  cfg
167
501
  .command("init")
168
- .description("Create .specdojo/specdojo.config.json template (does not overwrite existing)")
169
- .action(() => {
502
+ .description("Create .specdojo/specdojo.config.json template (does not overwrite existing) " +
503
+ "and add the lines excluding specdojo outputs to .gitignore")
504
+ .option("--dry-run", "Show the planned config and .gitignore lines without writing", false)
505
+ .action((opts) => {
506
+ const dryRun = !!opts.dryRun;
170
507
  const { configPath, config } = loadConfig();
171
508
  if (config) {
172
509
  process.stdout.write(`Already exists: ${configPath}\n`);
510
+ writeGitignoreForConfig(config, dryRun);
173
511
  return;
174
512
  }
513
+ const worktreeBase = defaultWorktreeBase();
175
514
  const template = {
176
515
  version: 1,
177
516
  current_project: "prj-0001",
@@ -181,26 +520,51 @@ export function registerConfigCommands(program) {
181
520
  project_register_path: "controls/project-register",
182
521
  project_context: ["prj-overview"],
183
522
  run: {
184
- worktree_base: "../app1-worktrees",
523
+ worktree_base: worktreeBase,
185
524
  },
186
525
  },
187
526
  },
188
527
  };
189
- writeConfig(template);
190
- process.stdout.write(`Created: ${configPath}\n`);
528
+ if (dryRun) {
529
+ process.stdout.write(`Would create (dry-run): ${configPath}\n`);
530
+ }
531
+ else {
532
+ writeConfig(template);
533
+ process.stdout.write(`Created: ${configPath}\n`);
534
+ }
535
+ writeGitignoreForConfig(template, dryRun);
536
+ if (dryRun)
537
+ return;
191
538
  process.stdout.write("Next steps:\n" +
192
539
  " 1. Keep this repository beside the product repository as app1-specdojo/.\n" +
193
- " 2. Review the project ID and paths; worktrees default to ../app1-worktrees.\n" +
540
+ ` 2. Review the project ID and paths; worktrees default to ${worktreeBase}.\n` +
194
541
  " 3. Optional agent setup: npx specdojo config scaffold --provider <name>\n" +
195
542
  " 4. Create a register: npx specdojo register scaffold --project prj-0001\n" +
196
- ` 5. Before using catalog or schedule, add the required paths: ${SPECDOJO_CONFIG_REFERENCE_URL}\n`);
543
+ ` 5. Before using catalog or schedule, add the required paths: ${SPECDOJO_CONFIG_REFERENCE_URL}\n` +
544
+ ' 6. To let tasks change the product repository, declare it under "repos" ' +
545
+ '(e.g. { "name": "app1", "path": "../app1" }) and write targets/paths as app1:<path>.\n');
546
+ });
547
+ cfg
548
+ .command("migrate-members")
549
+ .description("Move agent entries from project pm-members.yaml files to protected agent members")
550
+ .option("--project <projectId>", "Migrate only one project (default: all configured projects)")
551
+ .option("--dry-run", "Show planned changes without writing", false)
552
+ .action((opts) => {
553
+ try {
554
+ migrateAgentMembers({ projectId: opts.project, dryRun: !!opts.dryRun });
555
+ }
556
+ catch (error) {
557
+ process.stderr.write(`${error instanceof Error ? error.message : String(error)}\n`);
558
+ process.exitCode = 1;
559
+ }
197
560
  });
198
561
  cfg
199
562
  .command("scaffold")
200
563
  .description("Scaffold agent/settings templates for a provider")
201
- .requiredOption("--provider <name>", "Provider template to copy (claude|codex|copilot|opencode)")
564
+ .requiredOption("--provider <name>", "Provider template to copy (antigravity|claude|codex|copilot|opencode)")
202
565
  .option("--force", "Overwrite existing files", false)
203
566
  .option("--dry-run", "Show planned files without writing", false)
567
+ .option("--global", "Merge provider permissions into user-level settings (currently antigravity only)", false)
204
568
  .action(async (opts) => {
205
569
  try {
206
570
  await runProviderScaffold(String(opts.provider), {
@@ -208,6 +572,7 @@ export function registerConfigCommands(program) {
208
572
  repoRoot: specdojoRootDir(),
209
573
  force: !!opts.force,
210
574
  dryRun: !!opts.dryRun,
575
+ global: !!opts.global,
211
576
  });
212
577
  }
213
578
  catch (error) {
@@ -217,6 +582,87 @@ export function registerConfigCommands(program) {
217
582
  }
218
583
  });
219
584
  }
585
+ export function migrateAgentMembers(options) {
586
+ const rootDir = options.rootDir ? resolve(options.rootDir) : specdojoRootDir();
587
+ const configPath = join(rootDir, ".specdojo", "specdojo.config.json");
588
+ if (!existsSync(configPath))
589
+ throw new Error(`No config found: ${configPath}`);
590
+ const config = JSON.parse(readFileSync(configPath, "utf8"));
591
+ const projectEntries = options.projectId
592
+ ? [[options.projectId, config.projects[options.projectId]]]
593
+ : Object.entries(config.projects);
594
+ if (options.projectId && !config.projects[options.projectId]) {
595
+ throw new Error(`Unknown project: ${options.projectId}`);
596
+ }
597
+ const agentRelPath = config.agent_members_path?.trim() || DEFAULT_AGENT_MEMBERS_PATH;
598
+ assertProtectedAgentMembersPath(agentRelPath, configPath);
599
+ const agentPath = resolve(rootDir, agentRelPath);
600
+ let existingAgents = { version: 1, members: [] };
601
+ if (existsSync(agentPath)) {
602
+ existingAgents = readYamlFile(agentPath);
603
+ validateMemberFile("agent-members.schema.yaml", agentPath, existingAgents);
604
+ }
605
+ const agentNicknames = new Set(existingAgents.members.map((member) => member.nickname));
606
+ const moved = [];
607
+ const updates = [];
608
+ for (const [projectId, project] of projectEntries) {
609
+ if (!project)
610
+ continue;
611
+ const relPath = getProjectMembersPath(project);
612
+ if (!relPath)
613
+ throw new Error(`projects.${projectId}.members_path is required`);
614
+ const path = resolve(rootDir, relPath);
615
+ if (!existsSync(path))
616
+ throw new Error(`members_path not found: ${path}`);
617
+ const roster = readYamlFile(path);
618
+ if (!roster || !Array.isArray(roster.members)) {
619
+ throw new Error(`Invalid members file: ${path} (expected { members: [...] })`);
620
+ }
621
+ const humans = roster.members.filter((member) => member.type !== "agent");
622
+ const agents = roster.members.filter((member) => member.type === "agent");
623
+ const humanNicknames = new Set();
624
+ for (const human of humans) {
625
+ if (humanNicknames.has(human.nickname)) {
626
+ throw new Error(`Duplicate human nickname '${human.nickname}' while migrating ${path}`);
627
+ }
628
+ humanNicknames.add(human.nickname);
629
+ }
630
+ for (const agent of agents) {
631
+ if (agentNicknames.has(agent.nickname)) {
632
+ throw new Error(`Duplicate agent nickname '${agent.nickname}' while migrating ${path}`);
633
+ }
634
+ agentNicknames.add(agent.nickname);
635
+ moved.push(agent);
636
+ }
637
+ const humanRoster = { ...roster, members: humans };
638
+ validateMemberFile("pm-members.schema.yaml", path, humanRoster);
639
+ updates.push({ path, roster: humanRoster, count: agents.length });
640
+ }
641
+ const mergedAgents = {
642
+ version: existingAgents.version || 1,
643
+ members: [...existingAgents.members, ...moved],
644
+ };
645
+ validateMemberFile("agent-members.schema.yaml", agentPath, mergedAgents);
646
+ for (const update of updates) {
647
+ for (const human of update.roster.members) {
648
+ if (agentNicknames.has(human.nickname)) {
649
+ throw new Error(`Duplicate member nickname '${human.nickname}' across ${update.path} and ${agentPath}`);
650
+ }
651
+ }
652
+ }
653
+ const verb = options.dryRun ? "Would move" : "Moved";
654
+ for (const update of updates) {
655
+ process.stdout.write(`${verb} ${update.count} agent member(s) from ${update.path}\n`);
656
+ }
657
+ process.stdout.write(`${options.dryRun ? "Would write" : "Wrote"} ${mergedAgents.members.length} agent member(s) to ${agentPath}\n`);
658
+ if (options.dryRun)
659
+ return;
660
+ for (const update of updates) {
661
+ writeFileSync(update.path, dumpMemberFile(update.path, "pm-members.schema.yaml", update.roster), "utf8");
662
+ }
663
+ mkdirSync(dirname(agentPath), { recursive: true });
664
+ writeFileSync(agentPath, dumpMemberFile(agentPath, "agent-members.schema.yaml", mergedAgents), "utf8");
665
+ }
220
666
  export function registerProjectCommands(program) {
221
667
  const pj = program.command("project").description("Project registry commands");
222
668
  pj.command("list")