specdojo 0.3.1 → 0.4.1

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 (260) hide show
  1. package/.github/agents/specdojo-orchestrator.md +61 -2
  2. package/CHANGELOG.md +90 -0
  3. package/README.md +85 -25
  4. package/dist/{catalog-build-references.js → catalog/build-references.js} +4 -4
  5. package/dist/catalog/build-render.js +32 -0
  6. package/dist/{catalog-build.js → catalog/build.js} +9 -9
  7. package/dist/{catalog.js → catalog/catalog.js} +10 -10
  8. package/dist/{catalog-generate.js → catalog/generate.js} +8 -8
  9. package/dist/catalog/paths.js +1 -0
  10. package/dist/{catalog-plan-generate.js → catalog/plan-generate.js} +4 -4
  11. package/dist/{catalog-plan.js → catalog/plan.js} +4 -4
  12. package/dist/{catalog-scaffold.js → catalog/scaffold.js} +3 -3
  13. package/dist/{agent.js → commands/agent.js} +11 -11
  14. package/dist/{build-command.js → commands/build.js} +2 -2
  15. package/dist/{init-command.js → commands/init.js} +168 -45
  16. package/dist/commands/night-orchestrator.js +287 -0
  17. package/dist/{orchestrator.js → commands/orchestrator.js} +12 -5
  18. package/dist/{watch.js → commands/watch.js} +3 -3
  19. package/dist/{dashboard-timeline.js → dashboard/dashboard-timeline.js} +2 -2
  20. package/dist/{dashboard.js → dashboard/dashboard.js} +11 -10
  21. package/dist/{dashboard-exec-records.js → dashboard/exec-records.js} +2 -2
  22. package/dist/{dashboard-routines.js → dashboard/routines.js} +6 -5
  23. package/dist/{dashboard-shared.js → dashboard/shared.js} +1 -1
  24. package/dist/{timeline-build.js → dashboard/timeline-build.js} +2 -1
  25. package/dist/{timeline.js → dashboard/timeline.js} +1 -1
  26. package/dist/{deliverable.js → deliverable/deliverable.js} +5 -5
  27. package/dist/{deliverable-trash.js → deliverable/trash.js} +5 -5
  28. package/dist/{devcontainer-command.js → devcontainer/command.js} +8 -4
  29. package/dist/devcontainer/scaffold.js +418 -0
  30. package/dist/{doc-index.js → docs/doc-index.js} +1 -1
  31. package/dist/{frontmatter-namespace.js → docs/frontmatter-namespace.js} +1 -1
  32. package/dist/{index-command.js → docs/index-command.js} +1 -1
  33. package/dist/docs/template-resolution.js +1 -0
  34. package/dist/{viewpoint-document-kinds-check.js → docs/viewpoint-document-kinds-check.js} +1 -1
  35. package/dist/{yaml-pages-command.js → docs/yaml-pages-command.js} +1 -1
  36. package/dist/{yaml-pages.js → docs/yaml-pages.js} +2 -2
  37. package/dist/{exec-agent-config.js → exec/agent-config.js} +92 -5
  38. package/dist/{exec-agent-git-state.js → exec/agent-git-state.js} +1 -1
  39. package/dist/{exec-agent-protected-config.js → exec/agent-protected-config.js} +1 -1
  40. package/dist/{exec-commands.js → exec/commands.js} +22 -18
  41. package/dist/{exec-core.js → exec/core.js} +11 -11
  42. package/dist/{exec-events.js → exec/events.js} +2 -2
  43. package/dist/{exec-evidence.js → exec/evidence.js} +11 -6
  44. package/dist/exec/exec.js +2 -0
  45. package/dist/exec/format.js +1 -0
  46. package/dist/{exec-handoff.js → exec/handoff.js} +13 -12
  47. package/dist/{exec-limit.js → exec/limit.js} +93 -12
  48. package/dist/{exec-parent-validation.js → exec/parent-validation.js} +18 -4
  49. package/dist/{exec-pipeline-state.js → exec/pipeline-state.js} +29 -2
  50. package/dist/{exec-plans-core.js → exec/plans-core.js} +68 -114
  51. package/dist/{exec-plans-generation.js → exec/plans-generation.js} +53 -10
  52. package/dist/{exec-plans-storage.js → exec/plans-storage.js} +5 -5
  53. package/dist/{exec-plans.js → exec/plans.js} +3 -3
  54. package/dist/{exec-project.js → exec/project.js} +1 -1
  55. package/dist/{exec-protection-handoff.js → exec/protection-handoff.js} +3 -3
  56. package/dist/{exec-register-resume.js → exec/register-resume.js} +2 -2
  57. package/dist/{exec-register.js → exec/register.js} +114 -9
  58. package/dist/{exec-repo-integration-git.js → exec/repo-integration-git.js} +2 -2
  59. package/dist/{exec-repo-integration-sync.js → exec/repo-integration-sync.js} +4 -4
  60. package/dist/{exec-repo-integration.js → exec/repo-integration.js} +14 -11
  61. package/dist/{exec-repo-trace.js → exec/repo-trace.js} +3 -3
  62. package/dist/{exec-reporter-output.js → exec/reporter-output.js} +2 -2
  63. package/dist/{exec-reporter.js → exec/reporter.js} +142 -25
  64. package/dist/{exec-results.js → exec/results.js} +287 -31
  65. package/dist/{exec-run-agent-pipeline.js → exec/run/agent-pipeline.js} +35 -12
  66. package/dist/{exec-run-agent.js → exec/run/agent.js} +115 -28
  67. package/dist/{exec-run-in-place.js → exec/run/in-place.js} +56 -27
  68. package/dist/{exec-run-job.js → exec/run/job.js} +65 -36
  69. package/dist/{exec-run-lifecycle-commands.js → exec/run/lifecycle-commands.js} +30 -22
  70. package/dist/{exec-run-lock.js → exec/run/lock.js} +4 -3
  71. package/dist/{exec-run-mode-shared.js → exec/run/mode-shared.js} +3 -3
  72. package/dist/{exec-run-register-command.js → exec/run/register-command.js} +38 -11
  73. package/dist/{exec-run-register-core.js → exec/run/register-core.js} +63 -21
  74. package/dist/{exec-run-register-mode.js → exec/run/register-mode.js} +58 -31
  75. package/dist/exec/run/register-post-review.js +420 -0
  76. package/dist/{exec-run-register-resume.js → exec/run/register-resume.js} +48 -27
  77. package/dist/{exec-run-register-state.js → exec/run/register-state.js} +13 -10
  78. package/dist/{exec-run-register-worktree.js → exec/run/register-worktree.js} +119 -24
  79. package/dist/{exec-run.js → exec/run/run.js} +11 -11
  80. package/dist/{exec-run-schedule-mode.js → exec/run/schedule-mode.js} +17 -17
  81. package/dist/{exec-run-schedule-prepare.js → exec/run/schedule-prepare.js} +31 -18
  82. package/dist/{exec-run-schedule-task.js → exec/run/schedule-task.js} +45 -18
  83. package/dist/{exec-run-shared.js → exec/run/shared.js} +78 -30
  84. package/dist/{exec-schedule-calendar.js → exec/schedule/calendar.js} +1 -1
  85. package/dist/{exec-schedule-cpm.js → exec/schedule/cpm.js} +2 -2
  86. package/dist/{exec-schedule-gantt-chart-render.js → exec/schedule/gantt-chart-render.js} +2 -2
  87. package/dist/exec/schedule/gantt-chart.js +2 -0
  88. package/dist/{exec-schedule-hash.js → exec/schedule/hash.js} +2 -2
  89. package/dist/exec/schedule/index.js +1 -0
  90. package/dist/{exec-schedule-initial.js → exec/schedule/initial.js} +2 -2
  91. package/dist/{exec-schedule-progress.js → exec/schedule/progress.js} +2 -2
  92. package/dist/{exec-schedule-ready.js → exec/schedule/ready.js} +2 -2
  93. package/dist/{exec-schedule.js → exec/schedule/schedule.js} +11 -11
  94. package/dist/exec/shared.js +63 -0
  95. package/dist/exec/slot-lock.js +1 -0
  96. package/dist/{exec-strategy.js → exec/strategy.js} +2 -2
  97. package/dist/{exec-task-repos.js → exec/task-repos.js} +104 -17
  98. package/dist/{exec-task-view.js → exec/task-view.js} +4 -4
  99. package/dist/{exec-trial-commands.js → exec/trial-commands.js} +20 -22
  100. package/dist/{exec-trial-core.js → exec/trial-core.js} +6 -6
  101. package/dist/{exec-trial.js → exec/trial.js} +2 -2
  102. package/dist/{exec-worktree-command.js → exec/worktree-command.js} +25 -23
  103. package/dist/{exec-worktree-ops-commit.js → exec/worktree-ops-commit.js} +25 -60
  104. package/dist/{exec-worktree-ops-lifecycle.js → exec/worktree-ops-lifecycle.js} +13 -8
  105. package/dist/{exec-worktree-ops-merge.js → exec/worktree-ops-merge.js} +48 -7
  106. package/dist/{exec-worktree-ops.js → exec/worktree-ops.js} +3 -3
  107. package/dist/exec/worktree.js +305 -0
  108. package/dist/{grade-apply.js → grade/apply.js} +9 -9
  109. package/dist/{grade-command-apply.js → grade/command-apply.js} +7 -7
  110. package/dist/{grade-command-inspect.js → grade/command-inspect.js} +6 -6
  111. package/dist/{grade-command-plan.js → grade/command-plan.js} +5 -5
  112. package/dist/{grade-core.js → grade/core.js} +3 -3
  113. package/dist/grade/grade.js +19 -0
  114. package/dist/{grade-markdown.js → grade/markdown.js} +6 -6
  115. package/dist/{grade-pipeline-state.js → grade/pipeline-state.js} +4 -4
  116. package/dist/{grade-plan.js → grade/plan.js} +5 -5
  117. package/dist/{grade-result.js → grade/result.js} +5 -94
  118. package/dist/{grade-target-discovery.js → grade/target-discovery.js} +7 -7
  119. package/dist/{grade-targets.js → grade/targets.js} +11 -8
  120. package/dist/{job-definition.js → job/definition.js} +25 -6
  121. package/dist/{job.js → job/job.js} +12 -11
  122. package/dist/{kata-command.js → kata/command.js} +3 -3
  123. package/dist/{kata.js → kata/kata.js} +5 -5
  124. package/dist/register/approach.js +134 -0
  125. package/dist/{register-core.js → register/core.js} +26 -8
  126. package/dist/{register-create-commands.js → register/create-commands.js} +171 -8
  127. package/dist/{register-date.js → register/date.js} +1 -1
  128. package/dist/register/derivation.js +163 -0
  129. package/dist/{register-event-merge.js → register/event-merge.js} +44 -3
  130. package/dist/{register-events.js → register/events.js} +13 -3
  131. package/dist/{register-history.js → register/history.js} +7 -6
  132. package/dist/{register-item.js → register/item.js} +32 -5
  133. package/dist/register/lifecycle-lock.js +5 -0
  134. package/dist/{register-maintenance-commands.js → register/maintenance-commands.js} +13 -7
  135. package/dist/{register-migrate-timestamps.js → register/migrate-timestamps.js} +3 -3
  136. package/dist/{register-migration.js → register/migration.js} +5 -4
  137. package/dist/{register.js → register/register.js} +32 -27
  138. package/dist/{register-renumber.js → register/renumber.js} +38 -11
  139. package/dist/{register-transition-commands.js → register/transition-commands.js} +3 -3
  140. package/dist/{register-update.js → register/update.js} +5 -5
  141. package/dist/{register-views.js → register/views.js} +47 -7
  142. package/dist/{review-grade.js → review/grade.js} +2 -2
  143. package/dist/{review-plan.js → review/plan.js} +3 -3
  144. package/dist/{routine-definition.js → routine/definition.js} +2 -2
  145. package/dist/{routine.js → routine/routine.js} +49 -22
  146. package/dist/{schedule-approach.js → schedule/approach.js} +8 -8
  147. package/dist/{schedule-build.js → schedule/build.js} +7 -4
  148. package/dist/{schedule.js → schedule/schedule.js} +6 -6
  149. package/dist/{schedule-strategy-generate-document.js → schedule/strategy-generate-document.js} +2 -2
  150. package/dist/{schedule-strategy-generate-scope.js → schedule/strategy-generate-scope.js} +4 -4
  151. package/dist/{schedule-strategy-generate.js → schedule/strategy-generate.js} +10 -10
  152. package/dist/shared/agent-types.js +23 -0
  153. package/dist/shared/artifact-path.js +9 -0
  154. package/dist/{build-if-stale.js → shared/build-if-stale.js} +1 -1
  155. package/dist/{catalog-build-render.js → shared/catalog-render.js} +3 -32
  156. package/dist/{exec-slot-lock.js → shared/cross-process-lock.js} +3 -1
  157. package/dist/shared/fs.js +30 -0
  158. package/dist/shared/git.js +346 -0
  159. package/dist/shared/grade-result.js +94 -0
  160. package/dist/{package-paths.js → shared/package-paths.js} +3 -3
  161. package/dist/shared/plan-templates.js +114 -0
  162. package/dist/{exec-provider-scaffold.js → shared/provider-scaffold.js} +6 -3
  163. package/dist/shared/random.js +4 -0
  164. package/dist/{exec-schedule-index.js → shared/schedule-index.js} +3 -1
  165. package/dist/shared/schedule-paths.js +9 -0
  166. package/dist/{specdojo-config.js → shared/specdojo-config.js} +162 -21
  167. package/dist/{exec-shared.js → shared/text.js} +4 -135
  168. package/dist/shared/time.js +28 -0
  169. package/dist/shared/workspace-scaffold.js +69 -0
  170. package/dist/specdojo.js +22 -22
  171. package/docs/ja/specdojo/exec-templates/xep-common-conventions-template.md +31 -18
  172. package/docs/ja/specdojo/exec-templates/xep-register-investigate-template.md +1 -2
  173. package/docs/ja/specdojo/exec-templates/xep-register-template.md +3 -2
  174. package/docs/ja/specdojo/exec-templates/xer-template.md +1 -3
  175. package/docs/ja/specdojo/exec-templates/xrp-job-template.md +6 -4
  176. package/docs/ja/specdojo/exec-templates/xrp-register-post-run-template.md +46 -0
  177. package/docs/ja/specdojo/guides/branch-workflow-guide.md +34 -1
  178. package/docs/ja/specdojo/guides/docs-structure-guide.md +2 -0
  179. package/docs/ja/specdojo/guides/exec-config-guide.md +169 -26
  180. package/docs/ja/specdojo/guides/exec-operation-guide.md +184 -13
  181. package/docs/ja/specdojo/guides/exec-worktree-guide.md +2 -0
  182. package/docs/ja/specdojo/guides/orchestrator-operation-guide.md +40 -3
  183. package/docs/ja/specdojo/guides/quick-start-guide.md +89 -21
  184. package/docs/ja/specdojo/guides/register-operation-guide.md +44 -1
  185. package/docs/ja/specdojo/guides/remote-host-development-guide.md +61 -6
  186. package/docs/ja/specdojo/guides/review-guide.md +1 -1
  187. package/docs/ja/specdojo/guides/routine-operation-guide.md +5 -5
  188. package/docs/ja/specdojo/guides/specdojo-overview-guide.md +1 -1
  189. package/docs/ja/specdojo/guides/use-case-guide.md +1 -1
  190. package/docs/ja/specdojo/guides/waza-guide.md +1 -1
  191. package/docs/ja/specdojo/references/command-reference.md +124 -55
  192. package/docs/ja/specdojo/references/specdojo-config-reference.md +33 -7
  193. package/docs/ja/specdojo/rulebooks/pjr-rulebook.md +22 -13
  194. package/docs/ja/specdojo/standards/job-definition-standard.md +20 -18
  195. package/docs/ja/specdojo/standards/rulebook-authoring-standard.md +2 -2
  196. package/docs/ja/specdojo/templates/pjr-derived-items-template.md +22 -0
  197. package/docs/ja/specdojo/templates/pjr-index-template.md +1 -0
  198. package/docs/specdojo/schemas/v1/agent-members.schema.yaml +29 -2
  199. package/docs/specdojo/schemas/v1/exec-defaults.schema.yaml +111 -17
  200. package/docs/specdojo/schemas/v1/exec-evidence.schema.yaml +28 -0
  201. package/docs/specdojo/schemas/v1/job-run.schema.yaml +2 -2
  202. package/docs/specdojo/schemas/v1/job.schema.yaml +7 -0
  203. package/docs/specdojo/schemas/v1/pipeline-state.schema.yaml +38 -0
  204. package/docs/specdojo/schemas/v1/register-events.schema.yaml +5 -0
  205. package/docs/specdojo/schemas/v1/register-item-frontmatter.schema.yaml +91 -7
  206. package/docs/specdojo/schemas/v1/routine-run.schema.yaml +1 -1
  207. package/docs/specdojo/schemas/v1/specdojo-config.schema.yaml +36 -1
  208. package/package.json +17 -17
  209. package/templates/antigravity/README.md +6 -2
  210. package/templates/antigravity/agent-members-snippet.yaml +108 -12
  211. package/templates/antigravity/exec-defaults-snippet.yaml +8 -13
  212. package/templates/antigravity/orchestrator.md +61 -2
  213. package/templates/claude/README.md +27 -3
  214. package/templates/claude/agents/claude-executor.md +0 -1
  215. package/templates/claude/agents/claude-reporter.md +2 -1
  216. package/templates/claude/agents/claude-review-executor.md +0 -1
  217. package/templates/claude/agents/specdojo-orchestrator.md +61 -2
  218. package/templates/codex/README.md +40 -4
  219. package/templates/codex/agents/specdojo-orchestrator.toml +61 -2
  220. package/templates/codex/orchestrator.md +61 -2
  221. package/templates/devcontainer/devcontainer.json +5 -2
  222. package/templates/devcontainer/post-create.sh +15 -7
  223. package/templates/devcontainer/remote-host/specdojo-tmux.sh.sample +102 -0
  224. package/templates/devcontainer/remote-host/ssh-config.sample +19 -0
  225. package/templates/devcontainer/vim/vimrc +37 -0
  226. package/templates/init-agent-members.yaml +75 -25
  227. package/templates/init-exec-defaults.yaml +44 -9
  228. package/templates/opencode/README.md +17 -3
  229. package/templates/opencode/agents/opencode-executor.md +0 -1
  230. package/templates/opencode/agents/opencode-reporter.md +2 -1
  231. package/templates/opencode/agents/opencode-review-executor.md +0 -1
  232. package/templates/opencode/agents/specdojo-orchestrator.md +61 -2
  233. package/dist/devcontainer-scaffold.js +0 -165
  234. package/dist/exec-schedule-gantt-chart.js +0 -2
  235. package/dist/exec-worktree.js +0 -474
  236. package/dist/exec.js +0 -2
  237. package/dist/grade.js +0 -19
  238. package/templates/claude/agents/claude-expert-review-executor.md +0 -14
  239. /package/dist/{catalog-plan-prompt.js → catalog/plan-prompt.js} +0 -0
  240. /package/dist/{catalog-types.js → catalog/types.js} +0 -0
  241. /package/dist/{template-frontmatter.js → docs/template-frontmatter.js} +0 -0
  242. /package/dist/{role-types.js → exec/role-types.js} +0 -0
  243. /package/dist/{exec-schedule-gantt-chart-scope.js → exec/schedule/gantt-chart-scope.js} +0 -0
  244. /package/dist/{exec-types.js → exec/types.js} +0 -0
  245. /package/dist/{grade-command-shared.js → grade/command-shared.js} +0 -0
  246. /package/dist/{register-command-types.js → register/command-types.js} +0 -0
  247. /package/dist/{review-types.js → review/types.js} +0 -0
  248. /package/dist/{schedule-phase-sets.js → schedule/phase-sets.js} +0 -0
  249. /package/dist/{schedule-strategy-profiles.js → schedule/strategy-profiles.js} +0 -0
  250. /package/dist/{agent-response.js → shared/agent-response.js} +0 -0
  251. /package/dist/{catalog-paths.js → shared/catalog-paths.js} +0 -0
  252. /package/dist/{dist-freshness.js → shared/dist-freshness.js} +0 -0
  253. /package/dist/{git-environment.js → shared/git-environment.js} +0 -0
  254. /package/dist/{exec-format.js → shared/markdown-format.js} +0 -0
  255. /package/dist/{practice-id.js → shared/practice-id.js} +0 -0
  256. /package/dist/{spawn-self.js → shared/spawn-self.js} +0 -0
  257. /package/dist/{specdojo-gitignore.js → shared/specdojo-gitignore.js} +0 -0
  258. /package/dist/{template-resolution.js → shared/template-resolution.js} +0 -0
  259. /package/dist/{yaml-schema-modeline.js → shared/yaml-schema-modeline.js} +0 -0
  260. /package/dist/{yaml.js → shared/yaml.js} +0 -0
@@ -19,6 +19,15 @@ properties:
19
19
  updated_at:
20
20
  type: string
21
21
  format: date-time
22
+ # Run-scoped product integration targets given by `exec run --integration-branch <repo>=<branch>`.
23
+ # Only explicit overrides are recorded; resume reuses them instead of repos[].integration_branch.
24
+ integration_branches:
25
+ type: object
26
+ propertyNames:
27
+ pattern: "^[a-z0-9-]+$"
28
+ additionalProperties:
29
+ type: string
30
+ minLength: 1
22
31
  stages:
23
32
  type: object
24
33
  additionalProperties: false
@@ -57,6 +66,8 @@ $defs:
57
66
  format: date-time
58
67
  artifact_ref:
59
68
  type: [string, "null"]
69
+ rate_limit_events:
70
+ $ref: "#/$defs/rateLimitEvents"
60
71
  # Keys are repository names (`project` for the project repository) in integration order.
61
72
  repos:
62
73
  type: object
@@ -102,3 +113,30 @@ $defs:
102
113
  format: date-time
103
114
  artifact_ref:
104
115
  type: [string, "null"]
116
+ rate_limit_events:
117
+ $ref: "#/$defs/rateLimitEvents"
118
+ rateLimitEvents:
119
+ type: array
120
+ items:
121
+ type: object
122
+ additionalProperties: false
123
+ required: [action, from_actor, to_actor, resumed_at]
124
+ properties:
125
+ action:
126
+ type: string
127
+ enum: [wait, fallback]
128
+ trigger:
129
+ type: string
130
+ enum: [rate_limit, connection_error]
131
+ from_actor:
132
+ type: string
133
+ minLength: 1
134
+ to_actor:
135
+ type: string
136
+ minLength: 1
137
+ resumed_at:
138
+ type: string
139
+ format: date-time
140
+ resume_at:
141
+ type: string
142
+ format: date-time
@@ -49,12 +49,17 @@ $defs:
49
49
  - description
50
50
  - type
51
51
  - priority
52
+ - difficulty
52
53
  - owner
53
54
  - registered
54
55
  - due
55
56
  - completed
56
57
  - conclusion
57
58
  - block_reason
59
+ - approach
60
+ - targets
61
+ - derived_from
62
+ - autopilot
58
63
  from:
59
64
  type: string
60
65
  to:
@@ -7,8 +7,9 @@ description: >
7
7
 
8
8
  The frontmatter is the single source of truth for the structured fields of one
9
9
  register item: classification (item_type), processing status (item_status),
10
- priority, owner, dates, block reason and conclusion. The register list (pjr-index) is a derived
11
- view generated from these files, so the same field is never stored in two places.
10
+ priority, owner, dates, block reason, conclusion and derivation sources. The register list
11
+ (pjr-index) is a derived view generated from these files, so the same field is never stored in
12
+ two places.
12
13
 
13
14
  Conventions:
14
15
  - Undecided values are expressed by omitting the key. Table placeholders such as
@@ -43,6 +44,19 @@ properties:
43
44
  # required と同じ位置で対象プロパティを宣言する。
44
45
  properties:
45
46
  completed_at: true
47
+ - if:
48
+ required:
49
+ - approach
50
+ properties:
51
+ approach: true
52
+ then:
53
+ required:
54
+ - targets
55
+ properties:
56
+ targets:
57
+ type: array
58
+ minItems: 1
59
+ maxItems: 1
46
60
  - type: object
47
61
  required:
48
62
  - rulebook
@@ -94,6 +108,12 @@ properties:
94
108
  $ref: "#/$defs/Priority"
95
109
  description: "Handling priority (list column: 優先度)."
96
110
 
111
+ difficulty:
112
+ $ref: "#/$defs/Difficulty"
113
+ description: >
114
+ Work difficulty used to select the register executor/reporter route. Omit it to use
115
+ the existing priority-based automatic agent selection.
116
+
97
117
  owner:
98
118
  type: string
99
119
  minLength: 1
@@ -143,6 +163,33 @@ properties:
143
163
  rejection. Omit the key while it is undetermined; the details stay in
144
164
  the body (list column: 結論).
145
165
 
166
+ derived_from:
167
+ type: array
168
+ items:
169
+ oneOf:
170
+ - $ref: "#/$defs/LocalRegisterItemRef"
171
+ - $ref: "#/$defs/QualifiedRegisterItemRef"
172
+ minItems: 1
173
+ uniqueItems: true
174
+ description: >
175
+ Register items from which this item was derived. Use PJR-XXXX for an item in the
176
+ same project and <project-id>:PJR-XXXX for an item in another project. Omit the key
177
+ when the item was not derived from another register item.
178
+
179
+ autopilot:
180
+ type: string
181
+ const: approved
182
+ description: >
183
+ Human approval that the item's stated completion conditions may be executed by the
184
+ night orchestrator. Omit the key to keep the item out of the approved queue.
185
+
186
+ approach:
187
+ $ref: "#/$defs/Approach"
188
+ description: >
189
+ Execution approach for the single target. When present, targets must
190
+ contain exactly one document id whose kind is compatible with the
191
+ approach.
192
+
146
193
  targets:
147
194
  type: array
148
195
  items:
@@ -150,11 +197,13 @@ properties:
150
197
  minLength: 1
151
198
  minItems: 1
152
199
  description: >
153
- Doc ids of documents this register item targets, each resolvable
154
- via the doc index. When present, exec plan generation copies these
155
- into the plan frontmatter so that target coverage validation works
156
- for register-originated plans. Omit the key when the target
157
- documents are unknown or not applicable.
200
+ Doc ids of documents this register item targets. Deliverable targets
201
+ used with an approach are resolved via the project catalog so that
202
+ not-yet-created deliverables can be selected; kata and standalone
203
+ targets are resolved via the doc index. When present, exec plan
204
+ generation copies these into the plan frontmatter so that target
205
+ coverage validation works for register-originated plans. Omit the
206
+ key when the target documents are unknown or not applicable.
158
207
 
159
208
  $defs:
160
209
  ItemType:
@@ -200,6 +249,31 @@ $defs:
200
249
  - low
201
250
  description: "Handling priority of a register item."
202
251
 
252
+ Difficulty:
253
+ type: string
254
+ enum:
255
+ - hard
256
+ - medium
257
+ - easy
258
+ description: "Work difficulty used for register agent routing."
259
+
260
+ Approach:
261
+ type: string
262
+ enum:
263
+ - fully-guided
264
+ - recipe-guided
265
+ - freeform
266
+ - bootstrap
267
+ - retrofit
268
+ - cross-deliverable-dedup
269
+ - rulebook-maintenance
270
+ - recipe-maintenance
271
+ - sample-maintenance
272
+ - template-maintenance
273
+ - finalize
274
+ - bootstrap-finalize
275
+ description: "Execution approach shared with src/shared/agent-types.ts."
276
+
203
277
  Date:
204
278
  type: string
205
279
  format: date
@@ -215,3 +289,13 @@ $defs:
215
289
  Storing the instant instead of a calendar day keeps the record independent of
216
290
  the display timezone. Write it as a quoted YAML string, because an unquoted
217
291
  date-time is loaded as a timestamp value instead of a string.
292
+
293
+ LocalRegisterItemRef:
294
+ type: string
295
+ pattern: "^PJR-[0-9ABCDEFGHJKMNPQRSTVWXYZ]{4}$"
296
+ description: "Display id of a register item in the same project."
297
+
298
+ QualifiedRegisterItemRef:
299
+ type: string
300
+ pattern: "^[a-z][a-z0-9-]*:PJR-[0-9ABCDEFGHJKMNPQRSTVWXYZ]{4}$"
301
+ description: "Project-qualified display id of a register item in another project."
@@ -27,7 +27,7 @@ properties:
27
27
  type: string
28
28
  format: date-time
29
29
  result:
30
- enum: [success, failure, skipped]
30
+ enum: [success, partial, failure, skipped]
31
31
  job_run_ids:
32
32
  type: array
33
33
  uniqueItems: true
@@ -1,7 +1,7 @@
1
1
  $schema: "https://json-schema.org/draft/2020-12/schema"
2
2
  title: SpecDojo Config (.specdojo/specdojo.config.json)
3
3
  description: >-
4
- Shape of .specdojo/specdojo.config.json. The CLI (src/specdojo-config.ts loadConfig) is the
4
+ Shape of .specdojo/specdojo.config.json. The CLI (src/shared/specdojo-config.ts loadConfig) is the
5
5
  authority for checks that a schema cannot express: repository names that collide with a
6
6
  project id and repository paths that do not exist.
7
7
  type: object
@@ -26,6 +26,32 @@ $defs:
26
26
  NonEmptyString:
27
27
  type: string
28
28
  pattern: "\\S"
29
+ ParentValidationId:
30
+ type: string
31
+ enum:
32
+ [
33
+ validate-schema,
34
+ typecheck,
35
+ test-unit,
36
+ test-integration,
37
+ lint-ts,
38
+ lint-fm,
39
+ lint-md,
40
+ build,
41
+ format-check,
42
+ ]
43
+ ParentValidation:
44
+ oneOf:
45
+ - $ref: "#/$defs/ParentValidationId"
46
+ - type: object
47
+ additionalProperties: false
48
+ required: [id, repo]
49
+ properties:
50
+ id:
51
+ $ref: "#/$defs/ParentValidationId"
52
+ repo:
53
+ type: string
54
+ pattern: "^[a-z0-9-]+$"
29
55
  Project:
30
56
  type: object
31
57
  properties:
@@ -104,6 +130,15 @@ $defs:
104
130
  type: string
105
131
  agent_config:
106
132
  type: string
133
+ parent_validations:
134
+ description: >-
135
+ Parent-runner validations appended, in order, to pipeline.parent_validations from this
136
+ project's exec_defaults file. A plain ID targets the project repository; { id, repo }
137
+ targets project or a product repository declared by this project.
138
+ type: array
139
+ uniqueItems: true
140
+ items:
141
+ $ref: "#/$defs/ParentValidation"
107
142
  worktree_base:
108
143
  type: string
109
144
  register_date_timezone:
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "specdojo",
3
- "version": "0.3.1",
3
+ "version": "0.4.1",
4
4
  "description": "A dojo for Spec-Dō, the way of specification: decide with a register, write specs and designs with kata, and keep sharpening them with AI.",
5
5
  "license": "MIT",
6
6
  "author": "naoji3x",
@@ -59,22 +59,22 @@
59
59
  "vscode:package": "npm --prefix packages/vscode-specdojo run package",
60
60
  "exec:watch-claude-log": "tools/exec/watch-claude-log.sh",
61
61
  "worktree:sync": "tools/worktree/sync.sh",
62
- "orch:sonnet": "claude --agent specdojo-orchestrator --model sonnet",
63
- "orch:sonnet:work": "tools/worktree/open-agent-worktree.sh claude-work claude --agent specdojo-orchestrator --model sonnet",
64
- "orch:opus": "claude --agent specdojo-orchestrator --model opus",
65
- "orch:opus:work": "tools/worktree/open-agent-worktree.sh claude-work claude --agent specdojo-orchestrator --model opus",
66
- "orch:terra": "codex -m gpt-5.6-terra \"$(cat .agents/specdojo-orchestrator.agent.md)\"",
67
- "orch:terra:work": "tools/worktree/open-agent-worktree.sh codex-work codex -m gpt-5.6-terra \"$(cat .agents/specdojo-orchestrator.agent.md)\"",
68
- "orch:sol": "codex -m gpt-5.6-sol \"$(cat .agents/specdojo-orchestrator.agent.md)\"",
69
- "orch:sol:work": "tools/worktree/open-agent-worktree.sh codex-work codex -m gpt-5.6-sol \"$(cat .agents/specdojo-orchestrator.agent.md)\"",
70
- "orch:copilot": "copilot --agent specdojo-orchestrator",
71
- "orch:copilot:work": "tools/worktree/open-agent-worktree.sh copilot-work copilot --agent specdojo-orchestrator",
72
- "orch:agy": "agy --add-dir \"$(pwd)\" --model gemini-3.8-flash-high -i \"$(cat .agents/specdojo-orchestrator.agent.md)\"",
73
- "orch:agy:work": "tools/worktree/open-agent-worktree.sh agy-work agy --add-dir \"$(pwd)\" --model gemini-3.8-flash-high -i \"$(cat .agents/specdojo-orchestrator.agent.md)\"",
74
- "orch:qwen": "opencode --agent qwen-orchestrator",
75
- "orch:qwen:work": "tools/worktree/open-agent-worktree.sh qwen-work opencode --agent qwen-orchestrator",
76
- "orch:gemma": "opencode --agent gemma-orchestrator",
77
- "orch:gemma:work": "tools/worktree/open-agent-worktree.sh gemma-work opencode --agent gemma-orchestrator",
62
+ "orch:sonnet": "tsx src/specdojo.ts orchestrator launch --provider claude -- --agent specdojo-orchestrator --model sonnet",
63
+ "orch:sonnet:work": "tools/worktree/open-agent-worktree.sh claude-work tsx src/specdojo.ts orchestrator launch --provider claude -- --agent specdojo-orchestrator --model sonnet",
64
+ "orch:opus": "tsx src/specdojo.ts orchestrator launch --provider claude -- --agent specdojo-orchestrator --model opus",
65
+ "orch:opus:work": "tools/worktree/open-agent-worktree.sh claude-work tsx src/specdojo.ts orchestrator launch --provider claude -- --agent specdojo-orchestrator --model opus",
66
+ "orch:terra": "tsx src/specdojo.ts orchestrator launch --provider codex -- -m gpt-5.6-terra \"$(cat .agents/specdojo-orchestrator.agent.md)\"",
67
+ "orch:terra:work": "tools/worktree/open-agent-worktree.sh codex-work tsx src/specdojo.ts orchestrator launch --provider codex -- -m gpt-5.6-terra \"$(cat .agents/specdojo-orchestrator.agent.md)\"",
68
+ "orch:sol": "tsx src/specdojo.ts orchestrator launch --provider codex -- -m gpt-5.6-sol \"$(cat .agents/specdojo-orchestrator.agent.md)\"",
69
+ "orch:sol:work": "tools/worktree/open-agent-worktree.sh codex-work tsx src/specdojo.ts orchestrator launch --provider codex -- -m gpt-5.6-sol \"$(cat .agents/specdojo-orchestrator.agent.md)\"",
70
+ "orch:copilot": "tsx src/specdojo.ts orchestrator launch --provider copilot -- --agent specdojo-orchestrator",
71
+ "orch:copilot:work": "tools/worktree/open-agent-worktree.sh copilot-work tsx src/specdojo.ts orchestrator launch --provider copilot -- --agent specdojo-orchestrator",
72
+ "orch:flash": "tsx src/specdojo.ts orchestrator launch --provider antigravity -- --add-dir \"$(pwd)\" --model gemini-3.8-flash-high -i \"$(cat .agents/specdojo-orchestrator.agent.md)\"",
73
+ "orch:flash:work": "tools/worktree/open-agent-worktree.sh agy-work tsx src/specdojo.ts orchestrator launch --provider antigravity -- --add-dir . --model gemini-3.8-flash-high -i \"$(cat .agents/specdojo-orchestrator.agent.md)\"",
74
+ "orch:qwen": "tsx src/specdojo.ts orchestrator launch --provider opencode -- --agent qwen-orchestrator",
75
+ "orch:qwen:work": "tools/worktree/open-agent-worktree.sh qwen-work tsx src/specdojo.ts orchestrator launch --provider opencode -- --agent qwen-orchestrator",
76
+ "orch:gemma": "tsx src/specdojo.ts orchestrator launch --provider opencode -- --agent gemma-orchestrator",
77
+ "orch:gemma:work": "tools/worktree/open-agent-worktree.sh gemma-work tsx src/specdojo.ts orchestrator launch --provider opencode -- --agent gemma-orchestrator",
78
78
  "code:red": "tools/vscode/open-worktree-workspace.sh red",
79
79
  "code:blue": "tools/vscode/open-worktree-workspace.sh blue",
80
80
  "code:green": "tools/vscode/open-worktree-workspace.sh green",
@@ -50,11 +50,15 @@ agy --add-dir "$(pwd)" --model gemini-3.8-flash-high -i "$(cat .specdojo/antigra
50
50
  ```json
51
51
  {
52
52
  "scripts": {
53
- "orch:agy": "agy --add-dir \"$(pwd)\" --model gemini-3.8-flash-high -i \"$(cat .specdojo/antigravity/orchestrator.md)\""
53
+ "orch:flash": "specdojo orchestrator launch --provider antigravity -- --add-dir \"$(pwd)\" --model gemini-3.8-flash-high -i \"$(cat .specdojo/antigravity/orchestrator.md)\""
54
54
  }
55
55
  }
56
56
  ```
57
57
 
58
58
  ## executor / reporter として使う
59
59
 
60
- `exec-defaults-snippet.yaml` を `.specdojo/exec-defaults.yaml` の `providers` へ、`agent-members-snippet.yaml` の member 定義をリポジトリ共通の `.specdojo/agent-members.yaml` の `members` へ写します。agent は project ごとの `pm-members.yaml` へ書きません。使えるモデル ID は `agy models` で確認します。モデル ID は推論強度を含むため、`--effort` を併用すると起動に失敗します。headless 実行に必要な command は上記のグローバル permission で許可し、`--dangerously-skip-permissions` は使いません。
60
+ `exec-defaults-snippet.yaml` を `.specdojo/exec-defaults.yaml` の `providers` へ、`agent-members-snippet.yaml` の member 定義をリポジトリ共通の `.specdojo/agent-members.yaml` の `members` へ写します。agent は project ごとの `pm-members.yaml` へ書きません。
61
+
62
+ 名簿は実体と別名の 2 段で書きます。実体(`flash-executor`・`agy-opus-executor` など)は model の系統で名付け、model の ID を `model` に持ちます。従来の名前(`agy-executor`・`agy-claude-executor` など)は `aliases` で実体を指す別名にします。スニペット末尾の `aliases` の例は、向き先の member を有効にしたものだけを写します(別名は無効な member を指せません)。
63
+
64
+ 使えるモデル ID は `agy models` で確認します。モデル ID は推論強度を含むため、`--effort` を併用すると起動に失敗します。headless 実行に必要な command は上記のグローバル permission で許可し、`--dangerously-skip-permissions` は使いません。
@@ -3,59 +3,155 @@
3
3
  # project ごとの pm-members.yaml は人間専用なので、agent は記載しない。
4
4
  # 起動コマンドは member には書かず、.specdojo/exec-defaults.yaml の
5
5
  # providers.antigravity.command_template で定義する(exec-defaults-snippet.yaml を参照)。
6
- # モデルの差し替えは command_params.by_nickname で行う。
7
- # 既定では disabled にしてある。使う member だけ disabled を外す。
6
+ #
7
+ # 名簿は実体と別名の 2 段で書く(PJR-ZM1K)。
8
+ # members : model の系統で名付けた実体。provider・model・役割を持ち、model の ID(推論強度を含む)は
9
+ # 実体の model の 1 か所に書く。Claude Code など既定の provider と同じ系統の model は、
10
+ # agy- を前に付けて区別する(agy-opus-executor など)。
11
+ # aliases : 従来の名前(agy-executor など)。実体を指すだけで、Job・routine・利用者の設定はそのまま動く。
12
+ #
13
+ # 既定では members を disabled にしてある。使う member だけ disabled を外す。
14
+ # 別名は有効な member を指す必要があるため、下の aliases の例は、向き先の member の disabled を
15
+ # 外したものだけを .specdojo/agent-members.yaml の aliases へ写す。
8
16
 
9
17
  version: 1
10
18
  members:
11
- - nickname: agy-executor
19
+ - nickname: flash-executor
12
20
  disabled: true
13
21
  priority: 4
14
- display_name: Antigravity Executor
22
+ display_name: Antigravity Flash Executor
15
23
  email: null
16
24
  roles: []
17
25
  type: agent
18
26
  provider: antigravity
27
+ model: gemini-3.8-flash-medium
19
28
  mode: edit
29
+ stage_role: executor
20
30
  proficiency: normal
21
31
  persona: task-executor
22
32
  capabilities: []
23
33
 
24
- - nickname: agy-expert-executor
34
+ - nickname: flash-high-executor
25
35
  disabled: true
26
36
  priority: 3
27
- display_name: Antigravity Expert Executor
37
+ display_name: Antigravity Flash High Executor
28
38
  email: null
29
39
  roles: []
30
40
  type: agent
31
41
  provider: antigravity
42
+ model: gemini-3.8-flash-high
32
43
  mode: edit
44
+ stage_role: executor
33
45
  proficiency: expert
34
46
  persona: task-executor
35
47
  capabilities: []
36
48
 
37
- - nickname: agy-expert-review-executor
49
+ - nickname: flash-high-review-executor
38
50
  disabled: true
39
51
  priority: 3
40
- display_name: Antigravity Expert Review Executor
52
+ display_name: Antigravity Flash High Review Executor
41
53
  email: null
42
54
  roles: []
43
55
  type: agent
44
56
  provider: antigravity
57
+ model: gemini-3.8-flash-high
45
58
  mode: review
59
+ stage_role: executor
46
60
  proficiency: expert
47
- persona: reviewer
61
+ persona: multi-viewpoint-reviewer
48
62
  capabilities: []
49
63
 
50
- - nickname: agy-reporter
64
+ - nickname: flash-reporter
51
65
  disabled: true
52
66
  priority: 4
53
- display_name: Antigravity Reporter
67
+ display_name: Antigravity Flash Reporter
54
68
  email: null
55
69
  roles: []
56
70
  type: agent
57
71
  provider: antigravity
72
+ model: gemini-3.8-flash-medium
58
73
  mode: report
74
+ stage_role: reporter
59
75
  proficiency: normal
60
- persona: reporter
76
+ persona: execution-reporter
61
77
  capabilities: []
78
+
79
+ # Gemini 以外の Antigravity 提供 model。自動選択では選ばれにくい priority にし、by-name で使う。
80
+ - nickname: agy-sonnet-executor
81
+ disabled: true
82
+ priority: 5
83
+ display_name: Antigravity Claude Sonnet Executor
84
+ email: null
85
+ roles: []
86
+ type: agent
87
+ provider: antigravity
88
+ model: claude-sonnet-5-5-medium
89
+ mode: edit
90
+ stage_role: executor
91
+ proficiency: normal
92
+ persona: task-executor
93
+ capabilities: []
94
+
95
+ - nickname: agy-opus-executor
96
+ disabled: true
97
+ priority: 5
98
+ display_name: Antigravity Claude Opus Executor
99
+ email: null
100
+ roles: []
101
+ type: agent
102
+ provider: antigravity
103
+ model: claude-opus-5-5-high
104
+ mode: edit
105
+ stage_role: executor
106
+ proficiency: expert
107
+ persona: task-executor
108
+ capabilities: []
109
+
110
+ - nickname: agy-opus-review-executor
111
+ disabled: true
112
+ priority: 5
113
+ display_name: Antigravity Claude Opus Review Executor
114
+ email: null
115
+ roles: []
116
+ type: agent
117
+ provider: antigravity
118
+ model: claude-opus-5-5-high
119
+ mode: review
120
+ stage_role: executor
121
+ proficiency: expert
122
+ persona: multi-viewpoint-reviewer
123
+ capabilities: []
124
+
125
+ - nickname: agy-gpt-oss-executor
126
+ disabled: true
127
+ priority: 5
128
+ display_name: Antigravity GPT OSS Executor
129
+ email: null
130
+ roles: []
131
+ type: agent
132
+ provider: antigravity
133
+ model: gpt-oss-120b-medium
134
+ mode: edit
135
+ stage_role: executor
136
+ proficiency: normal
137
+ persona: task-executor
138
+ capabilities: []
139
+
140
+ # 別名の例(従来の名前 -> 実体)。向き先の member を有効にしたものだけを写す。
141
+ # aliases:
142
+ # - nickname: agy-executor
143
+ # alias_of: flash-executor
144
+ # - nickname: agy-expert-executor
145
+ # alias_of: flash-high-executor
146
+ # - nickname: agy-expert-review-executor
147
+ # alias_of: flash-high-review-executor
148
+ # - nickname: agy-reporter
149
+ # alias_of: flash-reporter
150
+ # - nickname: agy-claude-executor
151
+ # alias_of: agy-sonnet-executor
152
+ # - nickname: agy-claude-expert-executor
153
+ # alias_of: agy-opus-executor
154
+ # - nickname: agy-claude-expert-review-executor
155
+ # alias_of: agy-opus-review-executor
156
+ # - nickname: agy-gpt-executor
157
+ # alias_of: agy-gpt-oss-executor
@@ -1,7 +1,8 @@
1
1
  # Antigravity CLI(agy)provider 設定のスニペット。
2
2
  # 利用プロジェクトの .specdojo/exec-defaults.yaml の providers へコピーして使う。
3
- # by_nickname は member ごとにモデルを差し替える層で、Gemini 以外のモデルを
4
- # 指名するために使う。不要な member の行は削除してよい。
3
+ # model は実体の member の model に書き、command_template の {model} で渡す(PJR-ZM1K)。
4
+ # model を持たない従来の 1 段の member を残す場合だけ、command_params.by_proficiency /
5
+ # by_nickname で model を補う(member の model があればそちらが優先される)。
5
6
  # 設計の背景は sysd-antigravity-agent-settings と exec-config-guide.md を参照。
6
7
 
7
8
  providers:
@@ -20,17 +21,11 @@ providers:
20
21
  # 使える model の ID は `agy models` で確かめる。Gemini の Pro 系は提供されなくなったため、
21
22
  # expert は Flash の high とする(2026-10-15、agy 1.3.5 で確認)。
22
23
  command_template: 'agy --sandbox --add-dir "$(pwd)" --model {model} -p "$(cat)"'
23
- command_params:
24
- by_proficiency:
25
- normal: { model: gemini-3.8-flash-medium }
26
- expert: { model: gemini-3.8-flash-high }
27
- # Gemini 以外の Antigravity 提供モデルは member nickname で明示的に選ぶ。
28
- # by_nickname は proficiency / mode の既定値より優先される。
29
- by_nickname:
30
- agy-claude-executor: { model: claude-sonnet-5-5-medium }
31
- agy-claude-expert-executor: { model: claude-opus-5-5-high }
32
- agy-claude-expert-review-executor: { model: claude-opus-5-5-high }
33
- agy-gpt-executor: { model: gpt-oss-120b-medium }
24
+ # 従来の 1 段の名簿(model を持たない member)を使い続ける場合の補い方:
25
+ # command_params:
26
+ # by_proficiency:
27
+ # normal: { model: gemini-3.8-flash-medium }
28
+ # expert: { model: gemini-3.8-flash-high }
34
29
  # Gemini API の制限文言は未観測。429 / quota / RESOURCE_EXHAUSTED を初期値とし、
35
30
  # 実観測した文言で更新する(observed-agent-limit-stderr と同じ扱い)。
36
31
  rate_limit_detection:
@@ -7,7 +7,7 @@ CLI は利用リポジトリへローカル導入されるため、`npx specdojo
7
7
  ## 基本方針
8
8
 
9
9
  - 回答は原則として日本語で行う。
10
- - コマンドは「提案 → 承認 → 実行」の順で扱う。状態やファイルを変える操作は、実行するコマンドを提示して利用者の承認を得てから実行する。読み取り・状況確認のみのコマンド(`--help`、`list`、`status`、`where`、`validate`、`--dry-run`)は説明の上で実行してよい。
10
+ - 操作は「提案 → 承認 → 実行」の順で扱う。状態やファイルを変える操作は、「承認の聞き方」に従って何をするかを日本語で示し、利用者の承認を得てから実行する。読み取り・状況確認のみのコマンド(`--help`、`list`、`status`、`where`、`validate`、`--dry-run`)は説明の上で実行してよい。
11
11
  - 破壊的変更や `git push` は行わない。
12
12
  - `git commit` は次の方針で行う。実行前に必ず現在のブランチを確認して提示し、`main` では commit しない(対象ブランチを提案して止まる)。
13
13
  - register の状態遷移や worktree の統合など、runner 相当の記帳は承認なしに commit してよい。register の記帳は `--commit` で commit する。
@@ -19,6 +19,7 @@ CLI は利用リポジトリへローカル導入されるため、`npx specdojo
19
19
  - exec に流す予定の `todo` は、実行前に対象 project の `develop` へ入れておく。worktree は commit から作られるため、feature ブランチにしかない個票は実行できない。
20
20
  - commit メッセージは subject を日本語で書き、conventional commit の type と scope を保つ。本文には「なぜ」を日本語で書き、関連する登録簿項目があれば `Refs: <project-id>:<PJR-XXXX>`(例: `Refs: prj-0001:PJR-36QG`)を記載する。項目ごとに 1 行とし、過去の commit の書式は書き換えない。
21
21
  - 登録簿項目の実行は既定で `exec run --register` を使う。自分で実装するのは、利用者が実装者として自分を指定した場合に限る。「着手してください」は実行経路の指示であり、自分が実装してよい根拠として扱わない。実装者が読み取れない場合は確認する。
22
+ - 状態遷移の `--by` には、実際にその判断や作業をした主体を書く。利用者が決定・承認した記録は、役割の名前(`PO` など)ではなく人の名簿の nickname で残す。自分が確かめて close する記録や、自分で行った起票・記帳は `specdojo-orchestrator` で残す。`--by` は人と agent の名簿の nickname・alias と予約名(`SpecDojo`・`specdojo-orchestrator`・`night-orchestrator`)だけを受け付け、それ以外は記帳の前にエラーで止まる。
22
23
  - 自分が直接対応した項目は `start` を経ずに `close` してよい。実行していない主体を actor とする遷移を、記録の体裁を揃える目的で追加しない。終端イベントの `reason` に対応経路を記録し、実施内容と検証結果は個票の対応結果へ残す。
23
24
  - `specdojo.config.json` の project に `repos` で宣言されたプロダクトリポジトリは参照してよい。変更は利用者が自分を実装者に指定した場合に限り、そのリポジトリで `feature/<project-id>/<topic>` を切って commit する。`git push` は行わない。宣言していないリポジトリは参照も変更もしない。
24
25
  - 認証情報・秘密鍵・`.env`・`secrets/` を読み込まない。
@@ -29,10 +30,20 @@ CLI は利用リポジトリへローカル導入されるため、`npx specdojo
29
30
 
30
31
  1. 利用者の要望から「対象プロジェクト」「やりたいこと(登録・計画・実行・状況確認)」を特定する。曖昧なら質問して絞り込む。
31
32
  2. 対応する `specdojo` サブコマンドと引数へマッピングする。必要なら該当コマンドの `--help` を先に確認する。
32
- 3. 実行予定のコマンドを、目的・影響範囲(生成/更新されるファイル)とともに提示する。
33
+ 3. 何をするか・中身・影響(生成・更新されるファイルと commit の先)を、「承認の聞き方」に従って日本語で示す。
33
34
  4. 状態を変える操作は承認を得てから実行する。多くのコマンドは `--dry-run` を持つため、影響が大きい場合はまず `--dry-run` を提案する。
34
35
  5. 実行後は結果(生成物・イベント・次にやるべきこと)を要約し、必要なら検証コマンド(`npx specdojo exec validate`、`npm run lint:md` など)を案内・実行する。
35
36
 
37
+ ## 承認の聞き方
38
+
39
+ 状態やファイルを変える操作の承認を求めるときは、コマンドではなく、次の順で日本語で示して「よろしいですか?」と聞く。コマンドは既定では見せず、利用者が求めたときや、うまく動かなかったときの説明に使う。
40
+
41
+ 1. 何をするか(例: 「todo を起票します」「この項目を close します」)を 1 文で。
42
+ 2. 中身。起票なら種類・タイトル・優先度・担当・期限・説明の要点、close なら結論と確かめたこと、実行なら対象と使う agent。
43
+ 3. 影響。変わるファイルと commit の先(例: 「develop に記帳を 1 件 commit します」)。
44
+
45
+ 選択肢がある場合は、案ごとの利点と欠点を表にし、推奨とその理由を添える。CLI のツールが出す「このコマンドを実行してよいか」という権限の確認は、ツール側の仕組みでこの聞き方とは別である。
46
+
36
47
  ## specdojo コマンド地図
37
48
 
38
49
  | 目的 | サブコマンド | 代表操作 |
@@ -140,6 +151,54 @@ npx specdojo exec validate --project <project-id>
140
151
 
141
152
  失敗して `waiting` になった場合は、個票の `block_reason` と result の申し送りを読み、原因を特定してから再開する。reporter 段だけの再開は `--resume` で行う。
142
153
 
154
+ ## 実行の運び方
155
+
156
+ - `exec run --register` は `--worktree` で流す。同時に流すのは 2〜3 件までとする。親の検証は 1 件ずつ順に流れ、並行が多いと負荷で統合テストが時間切れになる。
157
+ - 時間のかかる run は background で流し、終わりの通知を待つ。途中経過を何度も見に行かない。
158
+ - プロセスを探す・止めるときに `pkill -f`・`pgrep -f` を使わない。探す文字列を含む自分のシェルにも一致し、自分を止める。
159
+ - 統合の後に `src` が dist より新しくなると、次の run は始まる前に止まる。dist を作り直してから流す。
160
+ - 記帳は `register ... --commit` で行う。登録簿の lifecycle のロックを取るため、実行中の run と取り合わない。
161
+ - 個票の本文を書き換えて普通に commit するのは、統合中の run がないときだけにする(`.git/index.lock` を確かめる)。commit に失敗したら、index に載ったファイルを残さない。残ると次の run の checkpoint が止まる。
162
+ - 保護された設定(agent の定義・名簿・`exec-defaults.yaml`・`package.json` など)は、executor が書き換えると統合の前に止まる。完了条件で「案を result に書く」と指示し、反映は利用者の承認のもと feature ブランチで行う。
163
+ - プロジェクトの文書にオーケストレーター向けの運用メモがあれば、作業を始める前に読む。
164
+
165
+ ## close の前の確かめ方
166
+
167
+ - 完了条件を 1 項目ずつ、差分(`git show`)と result に照らして確かめる。親の検証が通っただけで close しない。
168
+ - agent の「直した」「反映済み」という報告は、実物(ファイルの中身、生成物、コマンドの出力)で確かめる。agent は、権限で編集を拒まれたあとでも完了と報告することがある。
169
+ - 完了条件にない変更(特に保護された設定や、利用者の環境に関わる設定)が入っていないかを確かめる。
170
+ - runner や CLI の動きを変えた項目は、統合の後に実際の `exec run --register` を 1 回流して動作を確かめてから close する。生成物を変えた項目は、空のリポジトリで生成して確かめる。
171
+ - 確かめられない条件(ホストでの確認など)が残る場合は close せず `review` のまま残し、利用者に確かめ方を示す。
172
+ - 見つけた別の問題は、元の項目を `--from` で記録して起票する。完了条件の範囲を勝手に広げない。
173
+
174
+ ## 止まったときの対処
175
+
176
+ | 止まった理由 | 対処 |
177
+ | ---------------------------------------------- | -------------------------------------------------------------------------------------------------------------------- |
178
+ | agent の rate limit・つながらない | `--fallback-executor-by` / `--fallback-reporter-by` で代わりの agent を指定して再開する。解除の時刻が分かれば待つ |
179
+ | 親の検証の失敗(型・lint・テストの本当の失敗) | `--resume --resume-from executor` で executor からやり直す。失敗した検証の結果が引き継がれる |
180
+ | 負荷による時間切れ | 負荷を下げてから `--resume` で親の検証を流し直す |
181
+ | 統合での衝突(CHANGELOG の同じ節など) | 両方の行を残す形に exec ブランチ側をそろえてから `--resume` する。記帳のファイルの衝突は runner に任せ、手で解かない |
182
+ | 保護された設定への変更 | worktree でその変更だけを戻して `--resume` するか、`exec handoff apply` で利用者の承認のもと当てる |
183
+ | commit の hook の失敗 | 失敗した段(markdownlint など)の出力を読み、記録のファイルを規約に合わせてから commit する |
184
+ | 既に統合済みで再開できない | 新しい run として `--force-restart` で流す |
185
+
186
+ ## 完了条件の書き方
187
+
188
+ - 検証できる形で書く。完了条件は `exec plan` の入力になり、曖昧だと agent が意図と違う範囲を実装する。
189
+ - 作業を終える前に流す検査(型検査・lint・単体テスト)と、通すべき親の検証を書く。
190
+ - CHANGELOG は未公開の版の節に書き、公開済みの版の節を変えないと書く。
191
+ - 保護された設定に触れる場合は、案を result に書き、反映は利用者が行うと書く。
192
+ - 未決の点は `_UNDECIDED_` で残すか、executor に決めさせて理由を result に書かせるかを明記する。
193
+ - Markdown では、`*` や `_` を含む語(glob など)をコードの書式にする。コードの書式の中を空白で始めたり終えたりしない。
194
+
195
+ ## agent の選び方
196
+
197
+ - 具体的な agent の名前は、プロジェクトの設定に従う。`exec-defaults.yaml` に難しさごとの振り分けの設定があれば、個票の `difficulty`(`hard`・`medium`・`easy`)に合わせてそれを使う。
198
+ - 振り分けの設定がなければ、難しい作業(設計の判断を伴う変更、runner のコード)は expert の executor、範囲がはっきりした中程度の作業は normal の executor を選ぶ。
199
+ - 小さなローカル LLM は、編集できる範囲が限られることがあり、確かめずに完了と報告しがちである。plan で直し方が決まった小さな作業に限り、結果は必ず実物で確かめる。
200
+ - rate limit の解除まで長くかかる agent(割り当てが日単位のものなど)は、待たずに代わりの agent を指定する。
201
+
143
202
  ## プロジェクトの解決順序
144
203
 
145
204
  対象 project は次の順で解決される。通常は `current_project` を使う。会話で対象が特定できない場合は利用者に確認する。