specdojo 0.7.0 → 0.9.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.
- package/.github/agents/specdojo-orchestrator.md +7 -3
- package/CHANGELOG.md +217 -0
- package/dist/catalog/build.js +24 -1
- package/dist/catalog/catalog.js +16 -14
- package/dist/catalog/plan.js +1 -1
- package/dist/catalog/scaffold.js +4 -1
- package/dist/commands/agent.js +5 -3
- package/dist/commands/build.js +69 -10
- package/dist/commands/git.js +206 -0
- package/dist/commands/init.js +9 -3
- package/dist/commands/night-orchestrator.js +6 -4
- package/dist/commands/where.js +25 -0
- package/dist/dashboard/dashboard-timeline.js +18 -16
- package/dist/dashboard/dashboard.js +616 -261
- package/dist/dashboard/epic-plan.js +81 -0
- package/dist/dashboard/exec-records.js +16 -20
- package/dist/dashboard/routines.js +11 -12
- package/dist/dashboard/timeline-build.js +5 -9
- package/dist/dashboard/timeline.js +23 -18
- package/dist/devcontainer/scaffold.js +18 -0
- package/dist/docs/frontmatter-namespace.js +1 -48
- package/dist/docs/index-command.js +2 -2
- package/dist/docs/yaml-business-tables.js +243 -0
- package/dist/docs/yaml-interface-tables.js +106 -0
- package/dist/docs/yaml-pages-command.js +5 -3
- package/dist/docs/yaml-pages.js +268 -3
- package/dist/docs/yaml-table-shared.js +70 -0
- package/dist/docs/yaml-tables.js +39 -0
- package/dist/exec/agent-config.js +31 -0
- package/dist/exec/agent-plan.js +3 -2
- package/dist/exec/agent-protected-config.js +2 -0
- package/dist/exec/commands.js +100 -39
- package/dist/exec/commit-hook-skips.js +78 -0
- package/dist/exec/core.js +19 -7
- package/dist/exec/events.js +179 -8
- package/dist/exec/evidence.js +77 -19
- package/dist/exec/handoff.js +9 -13
- package/dist/exec/limit.js +1 -1
- package/dist/exec/mechanical-result.js +45 -0
- package/dist/exec/migrate-records.js +249 -0
- package/dist/exec/parent-validation.js +209 -15
- package/dist/exec/pipeline-state.js +27 -5
- package/dist/exec/plans-condense-findings.js +89 -0
- package/dist/exec/plans-core.js +45 -19
- package/dist/exec/plans-generation.js +52 -30
- package/dist/exec/plans-grade-findings.js +8 -3
- package/dist/exec/plans-kata-findings.js +61 -0
- package/dist/exec/plans-planning.js +3 -3
- package/dist/exec/plans-storage.js +12 -24
- package/dist/exec/post-integration.js +162 -0
- package/dist/exec/queue-command.js +166 -0
- package/dist/exec/queue.js +285 -0
- package/dist/exec/register-foreign-wait.js +84 -0
- package/dist/exec/register-resume.js +55 -56
- package/dist/exec/register.js +26 -22
- package/dist/exec/repo-integration-sync.js +21 -5
- package/dist/exec/repo-integration.js +21 -1
- package/dist/exec/reporter.js +121 -23
- package/dist/exec/results.js +106 -25
- package/dist/exec/review-completion.js +47 -0
- package/dist/exec/review-kata.js +112 -0
- package/dist/exec/run/agent-pipeline.js +78 -8
- package/dist/exec/run/agent.js +32 -13
- package/dist/exec/run/change-scope.js +365 -0
- package/dist/exec/run/deferred-cleanup.js +31 -0
- package/dist/exec/run/in-place.js +73 -33
- package/dist/exec/run/job-lock.js +66 -0
- package/dist/exec/run/job-sequence.js +137 -0
- package/dist/exec/run/job.js +135 -41
- package/dist/exec/run/lifecycle-commands.js +189 -37
- package/dist/exec/run/lock.js +22 -1
- package/dist/exec/run/mode-shared.js +11 -3
- package/dist/exec/run/register-command.js +14 -15
- package/dist/exec/run/register-core.js +20 -13
- package/dist/exec/run/register-mode.js +77 -17
- package/dist/exec/run/register-post-review.js +21 -9
- package/dist/exec/run/register-resume.js +95 -31
- package/dist/exec/run/register-state.js +23 -15
- package/dist/exec/run/register-worktree.js +184 -139
- package/dist/exec/run/schedule-mode.js +79 -18
- package/dist/exec/run/schedule-prepare.js +204 -59
- package/dist/exec/run/schedule-task.js +203 -49
- package/dist/exec/run/shared.js +9 -3
- package/dist/exec/run/trailing-records.js +35 -0
- package/dist/exec/run-records.js +2 -0
- package/dist/exec/schedule/schedule.js +116 -4
- package/dist/exec/shared.js +1 -1
- package/dist/exec/smoke.js +190 -0
- package/dist/exec/strategy.js +14 -3
- package/dist/exec/task-view.js +6 -4
- package/dist/exec/trailing-records.js +242 -0
- package/dist/exec/trial-commands.js +8 -4
- package/dist/exec/trial-core.js +6 -1
- package/dist/exec/validate-records-commit.js +110 -0
- package/dist/exec/validate-records.js +148 -0
- package/dist/exec/validation-metrics.js +181 -0
- package/dist/exec/worktree-cleanup-lock.js +26 -0
- package/dist/exec/worktree-command.js +38 -17
- package/dist/exec/worktree-ops-commit.js +119 -48
- package/dist/exec/worktree-ops-lifecycle.js +77 -48
- package/dist/exec/worktree-ops-merge.js +13 -2
- package/dist/exec/worktree-ops.js +2 -2
- package/dist/exec/worktree.js +32 -4
- package/dist/grade/apply.js +32 -6
- package/dist/grade/command-apply.js +3 -3
- package/dist/grade/command-inspect.js +7 -5
- package/dist/grade/command-plan.js +1 -1
- package/dist/grade/command-run.js +7 -1
- package/dist/grade/command-shared.js +1 -1
- package/dist/grade/core.js +18 -5
- package/dist/grade/markdown.js +3 -3
- package/dist/grade/pipeline-state.js +15 -11
- package/dist/grade/plan.js +37 -17
- package/dist/grade/result.js +3 -3
- package/dist/grade/run.js +87 -11
- package/dist/grade/target-discovery.js +17 -4
- package/dist/grade/targets.js +12 -11
- package/dist/job/definition.js +84 -8
- package/dist/job/job.js +109 -39
- package/dist/job/noop.js +104 -0
- package/dist/register/authoring-sources.js +22 -16
- package/dist/register/core.js +2 -0
- package/dist/register/create-commands.js +28 -3
- package/dist/register/deliverable-target.js +9 -1
- package/dist/register/epic.js +104 -26
- package/dist/register/event-merge.js +3 -0
- package/dist/register/events.js +4 -0
- package/dist/register/external-project.js +3 -0
- package/dist/register/item.js +6 -0
- package/dist/register/maintenance-commands.js +6 -3
- package/dist/register/planning.js +7 -14
- package/dist/register/register.js +74 -16
- package/dist/register/track-domains.js +34 -0
- package/dist/register/track-plan.js +78 -0
- package/dist/register/transition-commands.js +8 -0
- package/dist/register/work-table.js +64 -0
- package/dist/review/grade.js +35 -13
- package/dist/routine/definition.js +13 -3
- package/dist/routine/failure.js +30 -0
- package/dist/routine/routine.js +189 -71
- package/dist/routine/status.js +62 -0
- package/dist/routine/storage.js +33 -0
- package/dist/schedule/schedule.js +39 -39
- package/dist/schedule/strategy-generate-document.js +26 -14
- package/dist/schedule/strategy-generate-scope.js +17 -45
- package/dist/schedule/strategy-generate.js +33 -3
- package/dist/schedule/strategy-profiles.js +86 -12
- package/dist/shared/agent-types.js +7 -0
- package/dist/shared/condense-records.js +25 -0
- package/dist/shared/cross-process-lock.js +9 -1
- package/dist/shared/deprecation.js +8 -0
- package/dist/shared/dist-freshness.js +8 -2
- package/dist/shared/document-metadata.js +20 -0
- package/dist/shared/finding-cause.js +20 -0
- package/dist/shared/frontmatter-namespace.js +48 -0
- package/dist/shared/git-environment.js +2 -1
- package/dist/shared/git.js +186 -16
- package/dist/shared/grade-result.js +17 -1
- package/dist/shared/lefthook-scaffold.js +3 -0
- package/dist/shared/local-config.js +244 -0
- package/dist/shared/local-state.js +20 -0
- package/dist/shared/markdownlint-config.js +8 -3
- package/dist/shared/plan-conventions.js +129 -0
- package/dist/shared/plan-templates.js +57 -41
- package/dist/shared/run-records.js +224 -0
- package/dist/shared/specdojo-config.js +73 -41
- package/dist/shared/specdojo-gitignore.js +1 -0
- package/dist/shared/text.js +74 -6
- package/dist/shared/timeline-index.js +2 -0
- package/dist/shared/where-alias.js +13 -0
- package/dist/specdojo.js +4 -0
- package/docs/ja/specdojo/defaults/pm-review-viewpoints.yaml +11 -2
- package/docs/ja/specdojo/exec-templates/xep-common-conventions-template.md +4 -74
- package/docs/ja/specdojo/exec-templates/xep-condense-template.md +50 -0
- package/docs/ja/specdojo/exec-templates/xep-draft-template.md +17 -5
- package/docs/ja/specdojo/exec-templates/xep-fully-guided-template.md +16 -3
- package/docs/ja/specdojo/exec-templates/xep-recipe-guided-template.md +15 -5
- package/docs/ja/specdojo/exec-templates/xep-recipe-maintenance-template.md +6 -0
- package/docs/ja/specdojo/exec-templates/xep-register-template.md +1 -1
- package/docs/ja/specdojo/exec-templates/xep-rulebook-maintenance-template.md +6 -0
- package/docs/ja/specdojo/exec-templates/xep-sample-maintenance-template.md +6 -0
- package/docs/ja/specdojo/exec-templates/xep-template-maintenance-template.md +6 -0
- package/docs/ja/specdojo/exec-templates/xer-condense-template.md +25 -0
- package/docs/ja/specdojo/exec-templates/xp-common-conventions-template.md +50 -0
- package/docs/ja/specdojo/exec-templates/xrp-common-conventions-template.md +30 -0
- package/docs/ja/specdojo/guides/branch-workflow-guide.md +1 -1
- package/docs/ja/specdojo/guides/docs-editing-guide.md +12 -0
- package/docs/ja/specdojo/guides/docs-structure-guide.md +48 -15
- package/docs/ja/specdojo/guides/exec-config-guide.md +69 -19
- package/docs/ja/specdojo/guides/exec-operation-guide.md +97 -18
- package/docs/ja/specdojo/guides/exec-worktree-guide.md +20 -11
- package/docs/ja/specdojo/guides/job-sequence-guide.md +77 -0
- package/docs/ja/specdojo/guides/plan-result-lifecycle-guide.md +92 -55
- package/docs/ja/specdojo/guides/project-move-guide.md +381 -0
- package/docs/ja/specdojo/guides/quick-start-guide.md +73 -17
- package/docs/ja/specdojo/guides/register-operation-guide.md +26 -6
- package/docs/ja/specdojo/guides/remote-host-development-guide.md +2 -0
- package/docs/ja/specdojo/guides/review-guide.md +22 -19
- package/docs/ja/specdojo/guides/routine-operation-guide.md +23 -12
- package/docs/ja/specdojo/guides/ryu-guide.md +23 -13
- package/docs/ja/specdojo/guides/schedule-design-guide.md +27 -21
- package/docs/ja/specdojo/guides/schedule-operation-guide.md +27 -3
- package/docs/ja/specdojo/guides/specdojo-overview-guide.md +5 -4
- package/docs/ja/specdojo/guides/timeline-design-guide.md +27 -144
- package/docs/ja/specdojo/guides/use-case-guide.md +92 -155
- package/docs/ja/specdojo/guides/waza-guide.md +12 -8
- package/docs/ja/specdojo/recipes/bac-recipe.md +111 -0
- package/docs/ja/specdojo/recipes/bes-recipe.md +141 -0
- package/docs/ja/specdojo/recipes/bps-recipe.md +88 -139
- package/docs/ja/specdojo/recipes/br-recipe.md +77 -0
- package/docs/ja/specdojo/recipes/cdfd-overview-recipe.md +97 -109
- package/docs/ja/specdojo/recipes/cdfd-recipe.md +85 -146
- package/docs/ja/specdojo/recipes/cdfd-uc-recipe.md +92 -99
- package/docs/ja/specdojo/recipes/cnd-recipe.md +135 -0
- package/docs/ja/specdojo/recipes/cpd-recipe.md +140 -0
- package/docs/ja/specdojo/recipes/cxd-recipe.md +162 -0
- package/docs/ja/specdojo/recipes/ifd-recipe.md +145 -0
- package/docs/ja/specdojo/recipes/ifx-cmd-recipe.md +112 -90
- package/docs/ja/specdojo/recipes/ifx-index-recipe.md +164 -0
- package/docs/ja/specdojo/recipes/pm-communication-plan-recipe.md +60 -49
- package/docs/ja/specdojo/recipes/pm-members-recipe.md +50 -51
- package/docs/ja/specdojo/recipes/pm-organization-recipe.md +59 -48
- package/docs/ja/specdojo/recipes/pm-plan-recipe.md +72 -50
- package/docs/ja/specdojo/recipes/pm-quality-management-plan-recipe.md +40 -49
- package/docs/ja/specdojo/recipes/pm-raci-recipe.md +42 -48
- package/docs/ja/specdojo/recipes/pm-roles-recipe.md +52 -81
- package/docs/ja/specdojo/recipes/prj-assumptions-constraints-dependencies-recipe.md +64 -91
- package/docs/ja/specdojo/recipes/prj-charter-recipe.md +71 -106
- package/docs/ja/specdojo/recipes/prj-comparison-of-alternatives-recipe.md +78 -156
- package/docs/ja/specdojo/recipes/prj-issues-and-approach-recipe.md +62 -111
- package/docs/ja/specdojo/recipes/prj-scope-recipe.md +67 -123
- package/docs/ja/specdojo/recipes/prj-stakeholder-register-recipe.md +60 -96
- package/docs/ja/specdojo/recipes/prj-success-criteria-and-acceptance-criteria-recipe.md +61 -105
- package/docs/ja/specdojo/recipes/stsd-recipe.md +88 -80
- package/docs/ja/specdojo/recipes/sysd-critical-flows-recipe.md +129 -0
- package/docs/ja/specdojo/recipes/sysd-cross-cutting-policy-recipe.md +146 -0
- package/docs/ja/specdojo/recipes/sysd-index-recipe.md +141 -0
- package/docs/ja/specdojo/recipes/tsd-recipe.md +149 -129
- package/docs/ja/specdojo/references/command-reference.md +303 -148
- package/docs/ja/specdojo/references/deliverables-reference.md +30 -16
- package/docs/ja/specdojo/references/directory-layout-reference.md +3 -2
- package/docs/ja/specdojo/references/specdojo-config-reference.md +54 -18
- package/docs/ja/specdojo/rulebooks/atc-index-rulebook.md +101 -257
- package/docs/ja/specdojo/rulebooks/atc-rulebook.md +102 -228
- package/docs/ja/specdojo/rulebooks/bac-rulebook.md +63 -290
- package/docs/ja/specdojo/rulebooks/bdd-rulebook.md +162 -80
- package/docs/ja/specdojo/rulebooks/bds-rulebook.md +118 -155
- package/docs/ja/specdojo/rulebooks/bes-index-rulebook.md +128 -60
- package/docs/ja/specdojo/rulebooks/bes-rulebook.md +70 -94
- package/docs/ja/specdojo/rulebooks/bps-rulebook.md +24 -56
- package/docs/ja/specdojo/rulebooks/br-rulebook.md +58 -103
- package/docs/ja/specdojo/rulebooks/ccd-mermaid-rulebook.md +103 -223
- package/docs/ja/specdojo/rulebooks/cdfd-d2-rulebook.md +18 -93
- package/docs/ja/specdojo/rulebooks/cdfd-mermaid-rulebook.md +18 -52
- package/docs/ja/specdojo/rulebooks/cdfd-overview-rulebook.md +109 -147
- package/docs/ja/specdojo/rulebooks/cdfd-rulebook.md +80 -108
- package/docs/ja/specdojo/rulebooks/cdfd-uc-rulebook.md +51 -55
- package/docs/ja/specdojo/rulebooks/cdr-rulebook.md +144 -0
- package/docs/ja/specdojo/rulebooks/cdsd-rulebook.md +81 -68
- package/docs/ja/specdojo/rulebooks/cdt-rulebook.md +139 -0
- package/docs/ja/specdojo/rulebooks/cld-rulebook.md +9 -184
- package/docs/ja/specdojo/rulebooks/clis-rulebook.md +170 -0
- package/docs/ja/specdojo/rulebooks/cnd-mermaid-rulebook.md +33 -86
- package/docs/ja/specdojo/rulebooks/cnd-rulebook.md +79 -249
- package/docs/ja/specdojo/rulebooks/cop-index-rulebook.md +45 -131
- package/docs/ja/specdojo/rulebooks/cop-rulebook.md +69 -275
- package/docs/ja/specdojo/rulebooks/cpd-mermaid-rulebook.md +20 -112
- package/docs/ja/specdojo/rulebooks/cpd-rulebook.md +79 -249
- package/docs/ja/specdojo/rulebooks/cxd-mermaid-rulebook.md +12 -145
- package/docs/ja/specdojo/rulebooks/cxd-rulebook.md +115 -256
- package/docs/ja/specdojo/rulebooks/dct-index-rulebook.md +79 -109
- package/docs/ja/specdojo/rulebooks/dct-rulebook.md +119 -174
- package/docs/ja/specdojo/rulebooks/dec-rulebook.md +6 -14
- package/docs/ja/specdojo/rulebooks/dmd-index-rulebook.md +22 -66
- package/docs/ja/specdojo/rulebooks/dmd-rulebook.md +36 -94
- package/docs/ja/specdojo/rulebooks/dss-rulebook.md +171 -0
- package/docs/ja/specdojo/rulebooks/etc-index-rulebook.md +31 -131
- package/docs/ja/specdojo/rulebooks/etc-rulebook.md +50 -104
- package/docs/ja/specdojo/rulebooks/gl-rulebook.md +93 -57
- package/docs/ja/specdojo/rulebooks/ifd-mermaid-rulebook.md +63 -253
- package/docs/ja/specdojo/rulebooks/ifx-api-rulebook.md +14 -20
- package/docs/ja/specdojo/rulebooks/ifx-cmd-rulebook.md +79 -76
- package/docs/ja/specdojo/rulebooks/ifx-file-rulebook.md +182 -237
- package/docs/ja/specdojo/rulebooks/ifx-index-rulebook.md +111 -40
- package/docs/ja/specdojo/rulebooks/ifx-msg-rulebook.md +14 -22
- package/docs/ja/specdojo/rulebooks/imp-business-rulebook.md +23 -46
- package/docs/ja/specdojo/rulebooks/imp-data-rulebook.md +41 -64
- package/docs/ja/specdojo/rulebooks/imp-interface-rulebook.md +16 -40
- package/docs/ja/specdojo/rulebooks/imp-operations-rulebook.md +34 -61
- package/docs/ja/specdojo/rulebooks/imp-test-rulebook.md +27 -50
- package/docs/ja/specdojo/rulebooks/itc-index-rulebook.md +70 -199
- package/docs/ja/specdojo/rulebooks/itc-rulebook.md +65 -153
- package/docs/ja/specdojo/rulebooks/mip-index-rulebook.md +74 -150
- package/docs/ja/specdojo/rulebooks/mm-rulebook.md +12 -23
- package/docs/ja/specdojo/rulebooks/mtp-rulebook.md +99 -176
- package/docs/ja/specdojo/rulebooks/nfr-availability-rulebook.md +35 -61
- package/docs/ja/specdojo/rulebooks/nfr-index-rulebook.md +75 -117
- package/docs/ja/specdojo/rulebooks/nfr-integrity-rulebook.md +31 -60
- package/docs/ja/specdojo/rulebooks/nfr-maintainability-rulebook.md +26 -81
- package/docs/ja/specdojo/rulebooks/nfr-operations-rulebook.md +32 -70
- package/docs/ja/specdojo/rulebooks/nfr-performance-rulebook.md +45 -87
- package/docs/ja/specdojo/rulebooks/nfr-reliability-rulebook.md +48 -101
- package/docs/ja/specdojo/rulebooks/nfr-security-safety-rulebook.md +44 -80
- package/docs/ja/specdojo/rulebooks/nfr-usability-rulebook.md +59 -127
- package/docs/ja/specdojo/rulebooks/opd-index-rulebook.md +31 -50
- package/docs/ja/specdojo/rulebooks/opd-rulebook.md +42 -109
- package/docs/ja/specdojo/rulebooks/opr-index-rulebook.md +29 -42
- package/docs/ja/specdojo/rulebooks/opr-rulebook.md +29 -87
- package/docs/ja/specdojo/rulebooks/otp-index-rulebook.md +62 -84
- package/docs/ja/specdojo/rulebooks/otp-rulebook.md +11 -61
- package/docs/ja/specdojo/rulebooks/pjr-rulebook.md +92 -102
- package/docs/ja/specdojo/rulebooks/pm-change-request-log-rulebook.md +25 -34
- package/docs/ja/specdojo/rulebooks/pm-communication-plan-rulebook.md +30 -53
- package/docs/ja/specdojo/rulebooks/pm-issue-log-rulebook.md +23 -35
- package/docs/ja/specdojo/rulebooks/pm-members-rulebook.md +27 -45
- package/docs/ja/specdojo/rulebooks/pm-organization-rulebook.md +45 -59
- package/docs/ja/specdojo/rulebooks/pm-plan-rulebook.md +56 -66
- package/docs/ja/specdojo/rulebooks/pm-quality-management-plan-rulebook.md +54 -62
- package/docs/ja/specdojo/rulebooks/pm-raci-rulebook.md +46 -65
- package/docs/ja/specdojo/rulebooks/pm-risk-register-rulebook.md +28 -35
- package/docs/ja/specdojo/rulebooks/pm-roles-rulebook.md +65 -97
- package/docs/ja/specdojo/rulebooks/pr-rulebook.md +6 -18
- package/docs/ja/specdojo/rulebooks/prj-assumptions-constraints-dependencies-rulebook.md +48 -78
- package/docs/ja/specdojo/rulebooks/prj-charter-rulebook.md +23 -97
- package/docs/ja/specdojo/rulebooks/prj-comparison-of-alternatives-rulebook.md +61 -153
- package/docs/ja/specdojo/rulebooks/prj-issues-and-approach-rulebook.md +43 -116
- package/docs/ja/specdojo/rulebooks/prj-scope-rulebook.md +16 -51
- package/docs/ja/specdojo/rulebooks/prj-stakeholder-register-rulebook.md +47 -92
- package/docs/ja/specdojo/rulebooks/prj-success-criteria-and-acceptance-criteria-rulebook.md +25 -84
- package/docs/ja/specdojo/rulebooks/sac-rulebook.md +44 -107
- package/docs/ja/specdojo/rulebooks/sf-index-rulebook.md +106 -32
- package/docs/ja/specdojo/rulebooks/sf-rulebook.md +111 -61
- package/docs/ja/specdojo/rulebooks/sld-rulebook.md +129 -59
- package/docs/ja/specdojo/rulebooks/stc-index-rulebook.md +90 -189
- package/docs/ja/specdojo/rulebooks/stc-rulebook.md +45 -105
- package/docs/ja/specdojo/rulebooks/stsd-mermaid-rulebook.md +46 -40
- package/docs/ja/specdojo/rulebooks/stsd-rulebook.md +104 -68
- package/docs/ja/specdojo/rulebooks/sysd-critical-flows-rulebook.md +64 -330
- package/docs/ja/specdojo/rulebooks/sysd-cross-cutting-policy-rulebook.md +70 -263
- package/docs/ja/specdojo/rulebooks/sysd-index-rulebook.md +58 -200
- package/docs/ja/specdojo/rulebooks/sysd-rulebook.md +47 -60
- package/docs/ja/specdojo/rulebooks/tml-rulebook.md +4 -9
- package/docs/ja/specdojo/rulebooks/trc-requirements-to-specs-rulebook.md +69 -71
- package/docs/ja/specdojo/rulebooks/trc-requirements-to-tests-rulebook.md +65 -72
- package/docs/ja/specdojo/rulebooks/tsd-index-rulebook.md +35 -46
- package/docs/ja/specdojo/rulebooks/tsd-rulebook.md +49 -66
- package/docs/ja/specdojo/rulebooks/tsp-index-rulebook.md +64 -139
- package/docs/ja/specdojo/rulebooks/uis-rulebook.md +91 -161
- package/docs/ja/specdojo/rulebooks/utc-index-rulebook.md +49 -144
- package/docs/ja/specdojo/rulebooks/utc-rulebook.md +67 -155
- package/docs/ja/specdojo/samples/bac-sample.md +106 -21
- package/docs/ja/specdojo/samples/bdd-sample.yaml +143 -35
- package/docs/ja/specdojo/samples/bds-sample.md +87 -21
- package/docs/ja/specdojo/samples/bes-index-sample.md +42 -20
- package/docs/ja/specdojo/samples/bes-sample.md +70 -21
- package/docs/ja/specdojo/samples/bps-sample.md +42 -54
- package/docs/ja/specdojo/samples/br-sample.md +57 -15
- package/docs/ja/specdojo/samples/ccd-sample.md +80 -19
- package/docs/ja/specdojo/samples/cdfd-sample.md +172 -99
- package/docs/ja/specdojo/samples/cdfd-uc-sample.md +9 -7
- package/docs/ja/specdojo/samples/cdr-sample.md +78 -0
- package/docs/ja/specdojo/samples/cdsd-sample.md +73 -20
- package/docs/ja/specdojo/samples/cdt-sample.md +116 -0
- package/docs/ja/specdojo/samples/cld-sample.md +3 -30
- package/docs/ja/specdojo/samples/clis-sample.md +125 -0
- package/docs/ja/specdojo/samples/cnd-sample.md +127 -21
- package/docs/ja/specdojo/samples/cpd-sample.md +136 -22
- package/docs/ja/specdojo/samples/cxd-sample.md +108 -22
- package/docs/ja/specdojo/samples/dct-index-sample.yaml +63 -17
- package/docs/ja/specdojo/samples/dec-sample.md +2 -3
- package/docs/ja/specdojo/samples/dss-sample.md +175 -0
- package/docs/ja/specdojo/samples/gl-sample.yaml +50 -14
- package/docs/ja/specdojo/samples/ifd-sample.md +105 -21
- package/docs/ja/specdojo/samples/ifx-api-sample.yaml +0 -2
- package/docs/ja/specdojo/samples/ifx-cmd-sample.yaml +91 -60
- package/docs/ja/specdojo/samples/ifx-file-sample.md +462 -21
- package/docs/ja/specdojo/samples/ifx-index-sample.yaml +87 -19
- package/docs/ja/specdojo/samples/ifx-msg-sample.yaml +0 -2
- package/docs/ja/specdojo/samples/job-sequence.yaml +67 -0
- package/docs/ja/specdojo/samples/mip-index-sample.md +98 -20
- package/docs/ja/specdojo/samples/pm-communication-plan-sample.md +26 -19
- package/docs/ja/specdojo/samples/pm-members-sample.yaml +37 -13
- package/docs/ja/specdojo/samples/pm-organization-sample.md +42 -21
- package/docs/ja/specdojo/samples/pm-plan-sample.md +78 -26
- package/docs/ja/specdojo/samples/pm-quality-management-plan-sample.md +41 -22
- package/docs/ja/specdojo/samples/pm-raci-sample.md +63 -28
- package/docs/ja/specdojo/samples/pm-roles-sample.yaml +13 -12
- package/docs/ja/specdojo/samples/prj-assumptions-constraints-dependencies-sample.md +33 -25
- package/docs/ja/specdojo/samples/prj-charter-sample.md +42 -59
- package/docs/ja/specdojo/samples/prj-comparison-of-alternatives-sample.md +83 -62
- package/docs/ja/specdojo/samples/prj-success-criteria-and-acceptance-criteria-sample.md +30 -33
- package/docs/ja/specdojo/samples/sf-index-sample.md +47 -20
- package/docs/ja/specdojo/samples/sf-sample.md +109 -21
- package/docs/ja/specdojo/samples/sld-sample.md +88 -21
- package/docs/ja/specdojo/samples/stsd-sample.md +54 -26
- package/docs/ja/specdojo/samples/sysd-critical-flows-sample.md +166 -21
- package/docs/ja/specdojo/samples/sysd-cross-cutting-policy-sample.md +178 -21
- package/docs/ja/specdojo/samples/sysd-index-sample.md +82 -21
- package/docs/ja/specdojo/samples/tml-sample.yaml +4 -1
- package/docs/ja/specdojo/samples/uis-sample.md +141 -20
- package/docs/ja/specdojo/standards/document-metadata-standard.md +33 -4
- package/docs/ja/specdojo/standards/id-and-file-naming-standard.md +3 -1
- package/docs/ja/specdojo/standards/job-definition-standard.md +24 -9
- package/docs/ja/specdojo/standards/rulebook-authoring-standard.md +1 -0
- package/docs/ja/specdojo/templates/bac-template.md +76 -0
- package/docs/ja/specdojo/templates/bes-template.md +56 -0
- package/docs/ja/specdojo/templates/br-template.md +64 -0
- package/docs/ja/specdojo/templates/cdfd-template.md +81 -54
- package/docs/ja/specdojo/templates/cdfd-uc-template.md +9 -5
- package/docs/ja/specdojo/templates/cdr-template.md +58 -0
- package/docs/ja/specdojo/templates/cnd-template.md +137 -0
- package/docs/ja/specdojo/templates/cpd-template.md +129 -0
- package/docs/ja/specdojo/templates/cxd-template.md +105 -0
- package/docs/ja/specdojo/templates/dct-data-model-cdt-template.yaml +40 -0
- package/docs/ja/specdojo/templates/dct-data-model-cld-template.yaml +7 -14
- package/docs/ja/specdojo/templates/dct-index-template.md +9 -20
- package/docs/ja/specdojo/templates/dct-project-management-template.yaml +5 -1
- package/docs/ja/specdojo/templates/ifd-template.md +86 -0
- package/docs/ja/specdojo/templates/ifx-cmd-template.yaml +44 -28
- package/docs/ja/specdojo/templates/ifx-index-template.yaml +40 -0
- package/docs/ja/specdojo/templates/opr-template.md +2 -4
- package/docs/ja/specdojo/templates/pm-organization-template.md +9 -3
- package/docs/ja/specdojo/templates/pm-plan-template.md +4 -4
- package/docs/ja/specdojo/templates/pm-quality-management-plan-template.md +17 -9
- package/docs/ja/specdojo/templates/pm-raci-template.md +24 -13
- package/docs/ja/specdojo/templates/pm-roles-template.yaml +3 -2
- package/docs/ja/specdojo/templates/prj-assumptions-constraints-dependencies-template.md +6 -3
- package/docs/ja/specdojo/templates/prj-comparison-of-alternatives-template.md +22 -19
- package/docs/ja/specdojo/templates/stsd-template.md +46 -21
- package/docs/ja/specdojo/templates/sysd-critical-flows-template.md +94 -0
- package/docs/ja/specdojo/templates/sysd-cross-cutting-policy-template.md +122 -0
- package/docs/ja/specdojo/templates/sysd-index-template.md +89 -0
- package/docs/specdojo/lib/yaml-metadata.cjs +7 -0
- package/docs/specdojo/schemas/v1/bdd.schema.yaml +25 -57
- package/docs/specdojo/schemas/v1/condense-records.schema.yaml +26 -0
- package/docs/specdojo/schemas/v1/dct.schema.yaml +10 -0
- package/docs/specdojo/schemas/v1/deliverable-frontmatter.schema.yaml +3 -0
- package/docs/specdojo/schemas/v1/esil.schema.yaml +7 -141
- package/docs/specdojo/schemas/v1/exec-common.schema.yaml +5 -1
- package/docs/specdojo/schemas/v1/exec-defaults.schema.yaml +95 -8
- package/docs/specdojo/schemas/v1/exec-evidence.schema.yaml +38 -0
- package/docs/specdojo/schemas/v1/exec-plan-frontmatter.schema.yaml +14 -0
- package/docs/specdojo/schemas/v1/exec-result-frontmatter.schema.yaml +18 -0
- package/docs/specdojo/schemas/v1/finding-cause.schema.yaml +22 -0
- package/docs/specdojo/schemas/v1/grade-pipeline-state.schema.yaml +1 -1
- package/docs/specdojo/schemas/v1/grade-result.schema.yaml +2 -0
- package/docs/specdojo/schemas/v1/ifx-cmd.schema.yaml +65 -5
- package/docs/specdojo/schemas/v1/ifx-index.schema.yaml +142 -0
- package/docs/specdojo/schemas/v1/job-run.schema.yaml +23 -0
- package/docs/specdojo/schemas/v1/job.schema.yaml +63 -2
- package/docs/specdojo/schemas/v1/register-events.schema.yaml +2 -0
- package/docs/specdojo/schemas/v1/register-item-frontmatter.schema.yaml +17 -1
- package/docs/specdojo/schemas/v1/sch-strategy.schema.yaml +2 -2
- package/package.json +10 -7
- package/templates/antigravity/orchestrator.md +7 -3
- package/templates/claude/agents/specdojo-orchestrator.md +7 -3
- package/templates/codex/agents/specdojo-orchestrator.toml +7 -3
- package/templates/codex/orchestrator.md +7 -3
- package/templates/devcontainer/tmux.conf +6 -0
- package/templates/init-exec-defaults.yaml +13 -0
- package/templates/lefthook/tools/specdojo-pre-commit.mjs +8 -0
- package/templates/opencode/agents/specdojo-orchestrator.md +8 -4
|
@@ -86,6 +86,9 @@ register 実行は exec events を記録しないため、schedule の Ready・C
|
|
|
86
86
|
| plan を確認してから実行する | `exec plan` -> `exec run --plan` | 任意 | 任意 |
|
|
87
87
|
| worktree の各段階を人が確認する | `exec worktree prepare` から `remove` | 手動 | あり |
|
|
88
88
|
| 同じplanで複数agentを比較する | `exec trial run` | なし | agent別 |
|
|
89
|
+
| grade・`exec run`・build を混ぜた順番を予約して流す | `exec queue add` -> `exec queue run` | 予約ファイル | 段に依存 |
|
|
90
|
+
|
|
91
|
+
順番の予約は `<execution_path>/queues/<queue-id>.json` に残り、`exec queue status` と `exec status` の末尾の `queues:` で中身・進み具合・止まった段と理由を確かめます。段の書式と失敗時の扱いは [[specdojo:command-reference|コマンドリファレンス]] の「実行の予約(exec queue)」を参照してください。
|
|
89
92
|
|
|
90
93
|
`exec run --register ... --register-commit` は、各IDのcommit後にhookによる整形差分を同じcommitへ収束させ、対象差分が残っていないことを検証します。登録簿・派生ビュー・当該plan/resultはrunner管理パスとして扱い、その他の実行前からある利用者変更はcommitしません。過去の未commit plan/resultを検出した場合は、現在のIDへ混ぜず警告します。
|
|
91
94
|
|
|
@@ -138,14 +141,31 @@ specdojo exec run --project <project-id> --register PJR-00QV --worktree --join
|
|
|
138
141
|
| agent の同時実行数 | provider の `max_concurrency` をプロセスを跨いで数える | `exec/.locks/provider-<provider>/` |
|
|
139
142
|
| root での状態遷移・生成物の再生成・統合段 | start 遷移・checkpoint・develop への merge・wait commit・派生ビューの再生成を 1 つずつ実行する | `exec/.locks/exec-lifecycle/` |
|
|
140
143
|
| 親 runner の検証(`parent_validations`) | `pipeline.parent_validation_concurrency` をプロセスを跨いで数える | `exec/.locks/parent-validation/` |
|
|
144
|
+
| 変更範囲が重なる項目 | worktree 作成前に範囲を予約し、先行項目の統合後に次の項目を準備する | `exec/.locks/change-scopes/` |
|
|
141
145
|
| 同じ項目の二重実行 | 従来どおり register の start 遷移が防ぐ。遷移は上記の直列化の中で行うため、2 つの run が同時に通らない | - |
|
|
142
146
|
|
|
143
147
|
- 同時に動かせる run の数は `exec-defaults.yaml` の `run.max_concurrent_runs`(既定 4。最初の run を含む)で決まります。`1` にすると `--join` を無効にできます。
|
|
144
148
|
- 合流の枠が埋まっている場合は `--if-busy` に従います。routine から `--if-busy skip` で起動した場合は、従来どおり skip として記録されます。
|
|
145
149
|
- `--auto`、`--task`、`exec cycle`、`exec resume` など register の worktree 実行以外の run は、合流中の run が残っている間は busy として扱われます。
|
|
146
|
-
- 各 run
|
|
150
|
+
- 各 run は自分の項目の結果を持ちます。先行項目が未統合で失敗した場合、変更範囲が重なる後続項目は起動せず、先行項目の再開を促します。
|
|
147
151
|
- 枠の待ちは run のログに `Waiting for <provider> slot held by another exec run`、`Waiting for the register lifecycle lock held by another exec run`、`Waiting for parent validation slot held by another exec run` として出力されます。
|
|
148
152
|
|
|
153
|
+
親検証の時間切れを調べるときは、run の `evidence.json` と同じディレクトリの `parent-validation-metrics.jsonl` を確認します。trial では `exec/trials/<comparison-id>/trials/<trial-id>/` に保存します。再開時も追記するため、`batch_id` と検証の `id`・`repo` で絞って読みます。
|
|
154
|
+
|
|
155
|
+
| 記録 | 読み方 |
|
|
156
|
+
| ------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
|
157
|
+
| `gate-queued` / `gate-acquired` | 枠の要求・取得時刻。`local_wait_ms` は同一プロセス内、`shared_wait_ms` は共有ロックの取得にかかった時間。各検証の `gate_wait_ms` はバッチ全体の待ち時間で、検証ごとの待ちの合計ではありません |
|
|
158
|
+
| `validation-start` / `validation-end` | `at` は UTC の記録時刻、`started_at` は開始時刻、`duration_ms` は単調時計で測った実行時間。`status`・`exit_code`・`timed_out` で終了状態を確認します |
|
|
159
|
+
| `validation-timeout` | 上限に達した時点で終了要求より先に保存します。`active_test_files` は開始通知があり終了通知のないテストファイル、`output_tail` は直近 16 Ki 文字の標準出力です。詳細な出力は従来の失敗ログも参照します |
|
|
160
|
+
| `load` | Linux の CPU・memory・I/O の PSI(`pressure`)、`loadavg`、`/proc/meminfo` 由来のメモリ・swap 使用量(bytes)。PSI の `avg10` などは待ちの割合、`total` は累積待ち時間(マイクロ秒)です。開始・終了・時間切れの差分で確認します |
|
|
161
|
+
| `activity` | `scope: project-locks` は同じ project の primary / join run の数と PID、および実行中 executor の子 PID・worktree 名。reporter と終了済み executor は数えません。共有ロックのない実行は `scope: process` として自プロセスだけを数えます |
|
|
162
|
+
|
|
163
|
+
このリポジトリの Vitest 設定は、親検証が渡す `SPECDOJO_PARENT_VALIDATION_METRICS=1` のときだけファイル開始・終了通知を出します。他リポジトリの検証でこの通知がない場合、`active_test_files` は空で、実行ファイルは未特定です。直近の出力が示す完了済みファイルを実行中と解釈しないでください。テストの初期化前の停止も通知がない場合があります。
|
|
164
|
+
|
|
165
|
+
負荷はホストの `/proc` が見せる値で、cgroup の上限とは一致しない場合があります。run 数は heartbeat が有効な枠のスナップショットです。executor 数はこの版の runner が起動したプロセスを対象とし、別 project、旧版の runner、手動起動のテストは含みません。executor の記録は `exec/.locks/metrics-executors/` に置き、終了時に除去し、異常終了で残っても PID が生存しなければ数えません。
|
|
166
|
+
|
|
167
|
+
取得できない負荷項目は省略し、計測先への書き込み失敗も検証の合否には影響させません。計測は待ちの要求・取得と検証の開始・終了・時間切れ時だけ行い、継続的なプロセス走査や I/O ベンチマークは行いません。記録は原因の切り分けに使い、同時数や時間上限を自動変更しません。
|
|
168
|
+
|
|
149
169
|
上限と現在の使用枠は `exec slots` で確認できます。ロックは取得しないため、実行中にいつでも実行できます。
|
|
150
170
|
|
|
151
171
|
```bash
|
|
@@ -164,6 +184,29 @@ provider opencode: 1/1
|
|
|
164
184
|
parent validations: 0/1
|
|
165
185
|
```
|
|
166
186
|
|
|
187
|
+
#### 1.4.2. 変更範囲が重なる項目の順番待ち
|
|
188
|
+
|
|
189
|
+
register の worktree 実行(同じ run の `--parallel` と別 run の `--join`)および schedule の `--auto` は、対象範囲を worktree 作成前に予約します。同じファイル、または一方のディレクトリが他方のパスを含む項目は、先行項目の統合後の HEAD から準備します。agent の終了や commit だけでは予約を解放しません。重ならない項目は並列に進めます。
|
|
190
|
+
|
|
191
|
+
範囲は次の和集合で求めます。
|
|
192
|
+
|
|
193
|
+
| 入力 | 推定する範囲 |
|
|
194
|
+
| -------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
|
195
|
+
| 個票・既存 plan の `targets`、個票の `target_path` | doc ID を文書索引、未作成の成果物はカタログからパスへ解決する。`target_path` は作成前でも使う |
|
|
196
|
+
| 個票・既存 plan の本文 | バッククォート内のファイル・ディレクトリと、本文に書かれた `src/exec/run.ts` のような相対パス。個票は対応結果・関連ドキュメント以降を除く。plan は対象・入力・完了条件・作業内容など項目固有の節と finding だけを使い、共通の進め方・完了手順・異常終了条件・規約は除く。項目固有の実行記録パスも除外する |
|
|
197
|
+
| schedule の成果物 | `local_id` / `target_local_ids` と approach から導出する plan の対象文書 |
|
|
198
|
+
| approach の既定 | 通常は対象成果物。bootstrap・bootstrap-finalize・maintenance は `targets` から解決した個別の kata ファイルも含む。authoring の `targets` は先頭の出力だけを使い、後続の参考資料は含めない。変更許可用の kata ディレクトリ全体は自動追加しない。catalog-planning は共有索引を含むカタログディレクトリ、strategy-planning は対象 track の strategy / track ファイル |
|
|
199
|
+
|
|
200
|
+
ディレクトリは `src/exec/` のように書きます。`app:src/main.ts` は宣言済み product repo を表し、無修飾のパスは project repo として区別します。`./` と `..` を正規化し、行番号・`#関数名` はファイル単位へ広げます。glob は最初のワイルドカードより前のディレクトリ全体を予約します。本文の参照パスも安全側に含めるため、読み取り専用の資料が共通して待機する場合があります。宣言にない変更や別名パスまで静的に予測するものではありません。
|
|
201
|
+
|
|
202
|
+
`generated/` 配下と project repo で Git が無視するパス(派生一覧など)は、明示対象も含めて除外します。Git の判定に失敗した場合は `generated/` 以外の候補を残します。生成 plan の共通文に加え、項目固有の本文でも「保護された設定は変えない」「`CHANGELOG.md` は変えず」のように変更しないと明示した節のパスは除外します。同じ文の別の節や別の条件に書かれた変更対象と、明示した `targets` / `target_path` は残します。
|
|
203
|
+
|
|
204
|
+
範囲が空、または対象 doc ID の一部を解決できない場合は不明として扱います。`--unknown-scope parallel`(既定)は推定できた範囲だけで重複を判断し、不明部分は従来どおり並列を許可します。`--unknown-scope serialize` は、不明な項目を他の項目と直列化します。たとえば `exec run --auto --parallel 2 --unknown-scope serialize` で指定します。`--if-busy` は project / join 枠の待機方針であり、この範囲待ちとは別です。dry-run は範囲を予約しません。
|
|
205
|
+
|
|
206
|
+
待機時は `[scope] waiting: <項目> — <先行項目>: <重複範囲>` を出力し、`execution_path/exec/.locks/change-scopes/waits.jsonl` に日時・両項目・理由を追記します。起動できた項目は生成 plan の「変更範囲による実行待ち」にも記録し、統合して残します。schedule の非 loop 実行は従来どおり最大 `--parallel` 件を実行し、重複する項目の準備を前の統合後へ遅らせます。
|
|
207
|
+
|
|
208
|
+
統合前に失敗した予約と heartbeat が止まった予約は、未統合の障害として後続をエラーにし、無期限に待ち続けません。表示された先行項目を再開・再実行し、統合してから後続を流します。保持した worktree の衝突解消は既存の再開手順に従います。統合後の撤去・post-review の失敗は予約の解放を妨げません。
|
|
209
|
+
|
|
167
210
|
### 1.5. 実行eventの保存粒度
|
|
168
211
|
|
|
169
212
|
Schedule taskの状態eventは、`execution_path/exec/events/`へ1 event 1 JSONファイルで保存されます。ファイル名はUTC時刻、actor、task ID、event種別、衝突回避用の乱数を含みます。`exec refresh`などの読取処理は全eventを時系列に並べ、foldして現在状態を再構成します。この保存規範の正本は[[sysd-cross-cutting-policy|SpecDojo システム設計横断ルール]]の`scp-STA-001`です。
|
|
@@ -249,27 +292,27 @@ agent起動時はhook由来の`GIT_DIR`などを継承せず、各trialのcwdか
|
|
|
249
292
|
|
|
250
293
|
`blocked` は人の判断や外部対応が必要な障害を表します。状況に応じて次のコマンドを使います。
|
|
251
294
|
|
|
252
|
-
| 状況
|
|
253
|
-
|
|
|
254
|
-
| 中断で `doing` のまま
|
|
255
|
-
| pipeline の reporter で `blocked`
|
|
256
|
-
| reporter
|
|
257
|
-
| pipeline の統合段で `blocked`
|
|
258
|
-
| 障害を解消し同じ試行を続ける
|
|
259
|
-
| 試行を破棄して最初からやり直す
|
|
260
|
-
| 着手前のタスクを恒久的に中止する
|
|
295
|
+
| 状況 | コマンド | 結果 |
|
|
296
|
+
| --------------------------------------------------------------------------------------- | ------------------------------------------------ | ------------------------------------------------------------------ |
|
|
297
|
+
| 中断で `doing` のまま | `exec resume` | 既存 worktree 上で継続 |
|
|
298
|
+
| pipeline の reporter で `blocked` | `exec resume --task <id>` | executor evidence から再開 |
|
|
299
|
+
| reporter・統合段で `blocked`、または中断で `doing` の pipeline を executor からやり直す | `exec resume --task <id> --resume-from executor` | 既存 worktree と変更を引き継ぎ、executor → reporter → 統合を再実行 |
|
|
300
|
+
| pipeline の統合段で `blocked` | `exec resume --task <id>` | agent を起動せず統合だけ再開 |
|
|
301
|
+
| 障害を解消し同じ試行を続ける | `exec unblock` | `blocked -> doing` |
|
|
302
|
+
| 試行を破棄して最初からやり直す | `exec release` | `blocked -> todo` |
|
|
303
|
+
| 着手前のタスクを恒久的に中止する | `exec cancel` | `todo -> cancelled` |
|
|
261
304
|
|
|
262
305
|
`release` は `doing` / `blocked` の試行を破棄して `todo` に戻します。`cancel` は `todo` のタスクを終端状態にする操作です。
|
|
263
306
|
|
|
264
|
-
executor / reporter pipeline では、run ごとの
|
|
307
|
+
executor / reporter pipeline では、run ごとの `<execution_path>/runs/<出どころ>/<項目 ID>/<run ID>/pipeline-state.json` に各段(executor / reporter と、runner が担う統合段 `integrate`)の状態、agent、試行回数、evidence / result 参照を保存します。executor 中断の block event は `pipeline_stage=executor`、reporter 失敗は `pipeline_stage=reporter`、統合失敗は `pipeline_stage=integrate` を持ち、いずれも `pipeline_state_ref` から同じ run を再開します。`exec resume --task <task-id>` は state に応じて未完了の段から再開し、完了済みの agent 段を重複実行しません。
|
|
265
308
|
|
|
266
|
-
成果物の不足を executor に直させる場合は `--resume-from executor` を付けます。対象は executor が `succeeded`
|
|
309
|
+
成果物の不足を executor に直させる場合は `--resume-from executor` を付けます。対象は executor が `succeeded` で、reporter が未完了または統合段(commit・検査・merge)で止まった pipeline と、approach の必須項目(`condense_records` など)を欠いた報告として runner が executor の段で止めた pipeline に限ります。既存 run の executor 試行回数を増やし、`blocked` からの再開は `unblock` イベントを記録します。統合段から戻す場合は、executor を起動する前に統合先(project は root の現在ブランチ)を exec branch と worktree へ取り込むため、統合先で直した不具合を worktree で `git merge` せずに受け取れます。未 commit の変更と run の記録は取り込みの前に控えて戻し、戻せない場合は取り込み前へ戻して停止します。統合段の block 理由と result には、失敗した操作のメッセージと、この再開と統合だけの再試行(`exec resume --task <id>`)の 2 つの次の操作を記録します。統合が成功済みの run、一部のリポジトリを統合済みの run、exec branch が merge 済みの run、worktree が merge の途中の run(中止すると stage 済みの変更を失うため)、executor 未成功、pipeline 以外、`executor` 以外の値は理由を表示して停止します。この指定には `--task` が必要で、`--due` とは併用できません。
|
|
267
310
|
|
|
268
311
|
停止後に plan の指示を補う場合は、次の手順で再開します。
|
|
269
312
|
|
|
270
313
|
1. `specdojo exec worktree status --project <project-id> --task <task-id>` で残っている worktree を確認する。
|
|
271
|
-
2. その worktree の `<execution_path>/
|
|
272
|
-
3. `specdojo exec resume --project <project-id> --task <task-id> --resume-from executor`
|
|
314
|
+
2. その worktree の `<execution_path>/runs/<出どころ>/<項目 ID>/<run ID>/plan.md` を編集し、追加の指示と、変更の理由・再開までの経緯を result の申し送りへ残す指示を書く。
|
|
315
|
+
3. `specdojo exec resume --project <project-id> --task <task-id> --resume-from executor`(登録簿の場合は `specdojo exec run --project <project-id> --register <id> --resume --resume-from executor`)を実行する。root で plan を生成し直さず、worktree にある編集済み plan を executor と reporter へ渡す。既存の成果物と未コミット変更も引き継ぎ、統合時には直した plan がコミットに含まれて元の plan で上書きされずに履歴に残る。
|
|
273
316
|
4. 再開後の result で経緯と検証結果を確認する。pipeline の executor は result を直接編集せず、報告の `handoff` に経緯を記載し、reporter と runner が result へ反映する。
|
|
274
317
|
|
|
275
318
|
stage agent を明示する場合は次のように指定します。片方を省略すると、その stage は要件と優先度から自動選択されます。
|
|
@@ -282,6 +325,8 @@ specdojo exec resume \
|
|
|
282
325
|
--reporter-by <reporter-nickname>
|
|
283
326
|
```
|
|
284
327
|
|
|
328
|
+
executor 段から再開するとき(`--resume-from executor` を付けた再開、または executor 段で止まったタスクの再開)に `--executor-by` で現在の claim の持ち主と異なる executor を指定すると、実行前に元の actor の `release` イベントと新しい executor の `claim` イベントを記録して claim を新しい executor へ移し、完了時の `complete` イベント(および中断時の `block` イベント)も新しい executor で記録します。`--executor-by` を省略した場合や同じ executor を指定した場合は既存の claim を維持します(`doing` はそのまま継続し、`blocked` は `unblock` イベントで `doing` に戻します)。reporter 段や統合段のみを再開する場合は既存の claim を維持します。
|
|
329
|
+
|
|
285
330
|
```bash
|
|
286
331
|
specdojo exec release \
|
|
287
332
|
--project <project-id> \
|
|
@@ -303,6 +348,17 @@ specdojo exec release \
|
|
|
303
348
|
|
|
304
349
|
`--reset-worktree` は未commitの result や成果物変更を破棄します。内容を確認したい場合は、先に [exec worktree運用ガイド](exec-worktree-guide.md) の `status` を使います。
|
|
305
350
|
|
|
351
|
+
#### 2.2.1. 人が unblock するときの続行と引き取り
|
|
352
|
+
|
|
353
|
+
`exec unblock` を人が実行しても、claim の持ち主は変わりません。claim の持ち主は `claim` イベントの actor で、`note` やほかの actor の `unblock` では移りません。人が障害を取り除いて agent の run を続けさせる場合と、人が自分で直して完了させる場合は、`--take-over` の有無で区別します。
|
|
354
|
+
|
|
355
|
+
| 意図 | コマンド | claim の持ち主 | その後 |
|
|
356
|
+
| ------------------------------------ | ------------------------------------------------------------- | ------------------------- | --------------------------------------------------------------------------------------- |
|
|
357
|
+
| agent の run を続けさせる | `exec unblock --task <id> --by <human> --msg ...` | 元の actor(agent)のまま | `exec resume --task <id>` が元の agent で再開し、runner の `complete` / `block` も通る |
|
|
358
|
+
| 人が引き取り、自分で直して完了させる | `exec unblock --task <id> --by <human> --msg ... --take-over` | unblock した人 | 人が `exec complete --task <id> --by <human>` で完了させる。agent の run は完了できない |
|
|
359
|
+
|
|
360
|
+
`--take-over` は roster の `type: human` の actor だけが使えます。`--take-over` の `unblock` イベントは `take_over=true` を持ち、pipeline の再開情報(`pipeline_stage` など)を引き継ぎません。claim の持ち主を確かめるには `exec status --state doing` を使います。`by` 列と `--by` の絞り込みは claim の持ち主を表します。
|
|
361
|
+
|
|
306
362
|
### 2.3. 完了済みタスクをtodoに戻す
|
|
307
363
|
|
|
308
364
|
完了条件を満たしていないのに `complete` した場合など、完了判定そのものを訂正するときは `exec reopen` を使います。単に追加作業が発生した場合は、完了履歴を訂正せず新しい schedule task として計画します。
|
|
@@ -328,7 +384,7 @@ specdojo exec refresh --project <project-id>
|
|
|
328
384
|
|
|
329
385
|
後続 task も完了済みの場合は、依存グラフの下流から順に `reopen` します。後続 task が `doing` / `blocked` の場合は、先に同じ試行を完了させるか、`exec release` で `todo` に戻します。これにより、完了していない依存先を前提に後続 task が進行・完了している状態を防ぎます。
|
|
330
386
|
|
|
331
|
-
`reopen`
|
|
387
|
+
`reopen` は過去 run の plan・result、成果物、Git 履歴を変更・削除しません。完了済み plan は同じ run ディレクトリに残り、次の `exec plan` / `exec run` で新しい run を生成します。同じ run の続きは `exec resume` で再開します。
|
|
332
388
|
|
|
333
389
|
```bash
|
|
334
390
|
specdojo exec claim --project <project-id> --task <task-id> --by <actor> --msg "rerun"
|
|
@@ -392,11 +448,13 @@ specdojo exec run --project <project-id> --task <task-id> --worktree
|
|
|
392
448
|
schedule に `agent_pipeline` を持たない plan(`exec plan --deliverable <localId> --mode review` で生成した review plan など)は、`exec run --plan` または `exec run --deliverable` に `--executor-by` / `--reporter-by` を足すと同じ 2 stage で実行します。片方だけ指定した場合、もう一方は `stage_role` による自動選択で決まります。reporter が scaffold 済みの result を記入するため、`--plan` では frontmatter に `task_id` を持つ plan が必要です。`--by` に `stage_role` を持つ pipeline 用 agent を指定すると、result 未記入の blocked にはせず、`--executor-by` / `--reporter-by` を使うよう案内するエラーで実行前に拒否します。
|
|
393
449
|
|
|
394
450
|
```bash
|
|
395
|
-
specdojo exec run --project <project-id> --plan <
|
|
451
|
+
specdojo exec run --project <project-id> --plan <execution_path>/runs/<出どころ>/<項目 ID>/<run ID>/plan.md \
|
|
396
452
|
--executor-by <executor-nickname> --reporter-by <reporter-nickname>
|
|
397
453
|
```
|
|
398
454
|
|
|
399
|
-
run
|
|
455
|
+
新規 run の plan・result・evidence・ログ・state は `<execution_path>/runs/<出どころ>/<項目 ID>/<run ID>/` に残ります。出どころは `register`・`schedule`・`job` です。停止位置と再開可否はここを見て判断します。
|
|
456
|
+
|
|
457
|
+
旧配置の `<execution_path>/exec/evidence/<task-id>/<run-id>/` に checkpoint がある run は、`--resume`(`--resume-from executor` を含む)後も同じ run ID とディレクトリへ記録を続けます。executor を再実行すると、前回の state・evidence・ログを同じ場所の `*.attempt-N.*` に退避します。統合では result の配置にかかわらず現在の run の記録を commit します。commit 対象から外した別 run の記録は、ほかの許可外の変更とともに標準出力と `integrate.log` に一覧を表示します。
|
|
400
458
|
|
|
401
459
|
| ファイル | 確認できること |
|
|
402
460
|
| --------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------- |
|
|
@@ -406,7 +464,7 @@ run ごとの実行記録は `<execution_path>/exec/evidence/<task-id>/<run-id>/
|
|
|
406
464
|
| `reporter-attempt-<n>.stdout.log` / `reporter-attempt-<n>.stderr.log` | 失敗した reporter の形式試行別の生出力(秘匿値は伏せ字化、各ストリーム 64KiB で切り詰め) |
|
|
407
465
|
| `integrate.log` | checkpoint・統合段の commit / merge 失敗の stdout / stderr 全文(秘匿値は伏せ字化) |
|
|
408
466
|
|
|
409
|
-
agent ログは人が調査するための参照先で、reporter には渡りません。reporter が受け取るのは plan、runner 管理記録を除いた `evidence.json` の変更一覧、文章項目と対応づけ用パスだけの出力スキーマです。runner 管理記録は、解決済みの execution path 配下の evidence、project register とその派生ビュー、当該 result のパスを基準に除外します。ただし executor の試行中に runner 管理記録が実際に変わった場合、そのパスと状態は reporter 専用の `runner_context.runner_managed_attempt_changes` に含めます。reporter は、executor の最終メッセージがその変更に触れたのに `changed_files` にないという理由だけで確認を求めません。result の変更パスはこの除外後の `changes`、`outcome` と `block_reason` は executor の stage・終了コード・保護理由と検証結果から runner が機械生成します。executor または親 runner の検証に failed / `not_run` があれば blocked です。executor の `not_run` は、親 runner が同じコマンドを project で実行して成功していれば満たされたものとして扱います。また、対応する npm script がない、`npx` の package
|
|
467
|
+
agent ログは人が調査するための参照先で、reporter には渡りません。reporter が受け取るのは plan、runner 管理記録を除いた `evidence.json` の変更一覧、文章項目と対応づけ用パスだけの出力スキーマです。runner 管理記録は、解決済みの execution path 配下の evidence、project register とその派生ビュー、当該 result のパスを基準に除外します。ただし executor の試行中に runner 管理記録が実際に変わった場合、そのパスと状態は reporter 専用の `runner_context.runner_managed_attempt_changes` に含めます。reporter は、executor の最終メッセージがその変更に触れたのに `changed_files` にないという理由だけで確認を求めません。result の変更パスはこの除外後の `changes`、`outcome` と `block_reason` は executor の stage・終了コード・保護理由と検証結果から runner が機械生成します。executor または親 runner の検証に failed / `not_run` があれば blocked です。executor の `not_run` は、親 runner が同じコマンドを project で実行して成功していれば満たされたものとして扱います。また、対応する npm script がない、`npx` の package が未導入、変更ファイル種別を含む適用条件を満たさない、または SpecDojo サブコマンドの設定上の適用条件を満たさないと runner が確定できる場合は適用外として block せず、result の申し送りへ「適用外の検証(runner の判定)」を残します。この判定は reporter 専用の `runner_context.mechanically_not_applicable` にも含め、reporter は同じ検証の実行を申し送りで求めません。変更範囲の判定では、runner が生成・更新する `exec/` 配下(`plans/`・`results/`・`evidence/`・`events/`・`.locks/`)を executor の変更ファイルから除外します。`validate:history-links`(`specdojo-docs-lint history-links` を含む)は履歴蓄積ファイル(`pjr-*.md`(`pjr-index.md` を除く)、または executor 自身が変更した `execution/runs/<origin>/<item>/<run>/` 配下の `plan.md`・`result.md` や旧来の `exec/plans/**/*.md`・`exec/results/**/*.md`)の変更がある場合だけ適用対象とします。`catalog validate`(`npm run validate:catalog` および `tools/catalog-validate-if-configured.mjs` を含む)は対象 project の `catalog_path` と、runner 管理記録を除いた変更が `docs/ja/projects/` 配下に及ぶかで判定し、設定や対象 project を特定できない場合と適用条件が未定義のサブコマンドは救済しません。対象 project は `--project <id>`、run の対象 project、`current_project` の順に決めるため、別の project の `catalog_path` では判定しません。`<repo>:<path>` を引数に含むコマンドや `--prefix <repo>` 付きのコマンドは、そのプロダクトリポジトリの `package.json` で判定します。`npm run <name> -- <args>` と `npm run <name> <args>` も `<name>` の script が存在すれば適用外の申告を反証しますが、引数付きコマンドを親 runner が実行した引数なしコマンドと同一とはみなしません。`npm run check` のような合成コマンドは、構成する各コマンドが親 runner か executor の検証で通っていれば満たされたものとして扱います。理由付きの `not_applicable` は block せず result の申し送りへ残しますが、理由がない場合や、変更ファイル種別を含む適用条件を満たしたうえで存在する npm script/依存 package を適用外とした場合は blocked です。ただし SpecDojo サブコマンドは package の有無だけでは反証せず、既知の適用条件を設定から判定します。executor の `requires_human` は sandbox 外で人が行う確認として block せず、runner が edit result の申し送りへ「人の確認が必要: `<コマンド>`(<要約>)」を機械的に追記します。reporter は実施内容、パスと対にした各変更の説明、申し送り、approach、review の判断根拠と改善指示だけを返します。runner はパスで説明を突き合わせ、順序は問いません。説明がない evidence のパスには差分参照を促す既定文を記録し、evidence にないパスの説明は捨てるため、件数の過不足で result の作成は失敗しません。機械管理項目を追加した出力は形式不正として拒否されます。失敗理由の要約だけでは原因が分からない場合は、記録済み `evidence.json` の `log_refs` から stdout / stderr を個別に確認します。ログは Git 管理対象の evidence ディレクトリにありますが、失敗中の worktree では未コミットのため、`--force-restart` などで破棄する前に確認します(詳細は [exec設定ガイド](exec-config-guide.md) の `evidence とログの引き渡し方針`)。
|
|
410
468
|
|
|
411
469
|
stage 別の失敗と対応は次のとおりです。
|
|
412
470
|
|
|
@@ -526,6 +584,25 @@ reporter 段の再開の入力は、`pipeline-state.json`(stage 状態と plan
|
|
|
526
584
|
|
|
527
585
|
統合段の再開は、executor と reporter が成功したまま commit・merge・worktree 撤去のいずれかが失敗した run が対象です。worktree は統合が完了したときにだけ撤去されるため、reporter 成功済みの worktree が残っていること自体が統合の未完了を意味します。この再開では agent を1つも起動せず、worktree に残っている成果物と記入済み result をそのまま統合します。前回の試行で merge まで完了していた場合は、取り込み済みの exec ブランチを再 merge せずに残りの手順(worktree 撤去と `register review`)だけを進めます。再開の開始時に項目は `in-progress` へ戻り、成功なら `review`、失敗なら `waiting` へ遷移するため、再試行の成否は登録簿の状態とイベントに残ります。統合段の進捗(開始と失敗)は `pipeline-state.json` の `integrate` にも記録します。
|
|
528
586
|
|
|
587
|
+
register の統合で許可外の追加など commit 対象外の変更が見つかると、成果物の commit・merge を止め、項目を `waiting` にして worktree を保持します。`block_reason` に未 commit の件数・先頭3件のパス・worktree 内の `integrate.log` の場所、run の最後の要約に `uncommitted=<件数>` を表示します。ログには全対象パスが残ります。移動元の削除が許可内でも、移動先が許可外なら同じ扱いです。
|
|
588
|
+
|
|
589
|
+
新しい最上位ディレクトリへの移動など必要な変更の場合は、ログと差分を確認し、利用者の承認後に保持した worktree で対象パスを明示して commit します。次は `docs/ja/product/trash/` から `archive/ja/product/trash/` への移動の例です。`<worktree-path>` は停止時に表示された場所に置き換えます。
|
|
590
|
+
|
|
591
|
+
```bash
|
|
592
|
+
git -C <worktree-path> status --short --untracked-files=all
|
|
593
|
+
git -C <worktree-path> diff -- docs/ja/product/trash/
|
|
594
|
+
# 移動先の内容と links.json も確認し、利用者の承認を得てから実行する
|
|
595
|
+
git -C <worktree-path> add -A -- docs/ja/product/trash/ archive/ja/product/trash/
|
|
596
|
+
git -C <worktree-path> diff --cached --stat
|
|
597
|
+
git -C <worktree-path> commit -m "Archive documents approved by user"
|
|
598
|
+
```
|
|
599
|
+
|
|
600
|
+
その後、統合先の worktree から次を実行します。executor と reporter を再実行せず、手動 commit と残りの成果物を統合します。不要な一時ファイルだった場合は worktree 内で対象だけを除去してから同じコマンドで再開します。新しいディレクトリの自動許可や `--force-restart` による破棄は必要ありません。
|
|
601
|
+
|
|
602
|
+
```bash
|
|
603
|
+
specdojo exec run --project <project-id> --register <PJR-ID> --worktree --resume
|
|
604
|
+
```
|
|
605
|
+
|
|
529
606
|
`specdojo.config.json` の project に `repos` を宣言している場合、統合段は宣言順のプロダクトリポジトリ、最後にプロジェクトリポジトリの順で統合し、リポジトリ別の状態(`pending` / `merged` / `unchanged` / `failed`)を `pipeline-state.json` の `integrate.repos` に記録します。途中で失敗すると、統合済みのリポジトリはそのまま残し、項目を `waiting` へ戻して全リポジトリの worktree を保持します。統合段の再開では、統合先へ取り込み済みのプロダクトを merge し直さず、失敗したリポジトリから統合を続けます。統合の順序と部分状態の詳細は [[specdojo:docs-structure-guide|ドキュメント構成ガイド]] の「複数リポジトリの統合の失敗と再開」を参照してください。
|
|
530
607
|
|
|
531
608
|
再開できるかどうかは、対象 worktree の最新 run だけで判定します。次の場合は worktree・exec ブランチ・未コミットの成果を一切変更せず、理由を出力して終了コード 1 で終わります。
|
|
@@ -667,6 +744,8 @@ specdojo:
|
|
|
667
744
|
- **対象(`targets`)**: 成果物カタログ(DCT)に定義されている成果物の文書 ID(doc id)を指定します(例: `prj-0001:cxd-specdojo`、`specdojo:exec-config-guide`)。プロダクト成果物の場合は `local_id` の canonical 形式(`<project-id>:<local_id>`)も受け付けます。まだ文書ファイルが作成されていない成果物であっても、カタログに定義されていればカタログで解決され、起票・実行できます。
|
|
668
745
|
- **進め方(`approach`)**: 成果物を作成・修正する進め方(`draft`(文脈を調べて下書き)、`fully-guided`(既存成果物の磨き込み)、`recipe-guided`、`freeform`、`bootstrap`、`retrofit`、`cross-deliverable-dedup` など)から目的に応じて選びます。
|
|
669
746
|
|
|
747
|
+
`draft`・`fully-guided`・`recipe-guided` の edit plan は、カタログの `evidence_refs` を「実装エビデンスと未作成の依存」節へ展開します。列挙された実装は読み取り専用で、変更許可範囲と commit 対象には入りません。`evidence_refs` がない場合やカタログなしの場合も、それだけでは停止しません。未作成の `depends_on` はインラインコードと「未作成」で示し、内容を推測せず _TODO_ / _ASSUMPTION_ と次のアクションを残して進めます。資料が食い違うときの根拠の使い分けは [[specdojo:ryu-guide|実践の進め方ガイド]] を参照してください。
|
|
748
|
+
|
|
670
749
|
#### 4.3.2. kata(実践の型)を対象にする場合
|
|
671
750
|
|
|
672
751
|
- **対象(`targets`)**: kata の文書 ID(doc id)を指定します(例: `specdojo:pjr-rulebook`、`specdojo:exec-human-finalize-recipe` など)。kata は文書索引(doc-index)で解決されます。
|
|
@@ -82,6 +82,8 @@ specdojo exec complete \
|
|
|
82
82
|
|
|
83
83
|
`exec worktree` は独自の JSON や状態ファイルを作りません。必要な情報は毎回既存情報から導出します。
|
|
84
84
|
|
|
85
|
+
worktree の配置は `--worktree-base`、project 設定の `run.worktree_base`、既定値 `../worktrees` の順で決まります。設定値と既定値の相対パスは主の作業ツリーを基準に解決するため、Job worktree 内からの起動でも同じ配置になります。明示的な `--worktree-base` の相対パスは起動元の作業ツリーが基準で、絶対パスはそのまま使います。統合先は起動元のブランチです。
|
|
86
|
+
|
|
85
87
|
| 情報 | 導出元 |
|
|
86
88
|
| ------------------- | ---------------------------------------------------------- |
|
|
87
89
|
| worktree名 / branch | project 修飾 task ID から `<slug>` と `exec/<slug>` を導出 |
|
|
@@ -136,7 +138,7 @@ specdojo exec worktree prepare \
|
|
|
136
138
|
|
|
137
139
|
root にある無関係な未commit変更は checkpoint commit に含めません。stage 済み変更はパスを警告へ表示して保持し、plan、result、claim event などの checkpoint 対象と重複する場合だけ停止します。checkpoint commit が hook などで失敗した場合は、checkpoint 対象だけを unstage し、無関係な stage 済み変更は変更しません。checkpoint は exec branch だけに置かれるため、統合先の first-parent に `prepare execution` commit は増えません。root 側の plan、result、claim event は未commitのまま残り、task が `doing` であることは統合先からも見えます。これらの root 側の複製は `worktree merge` が統合の直前に解放し(HEAD の状態へ戻し)、merge が exec branch の commit 済み内容を持ち込みます。merge が失敗した場合は複製を元に戻します。
|
|
138
140
|
|
|
139
|
-
作成または再利用した task worktree では、tracked `package-lock.json` ごとに `npm ci --include=dev` を実行し、root と独立 package の `node_modules` を worktree 内へ実体として配置します。依存関係を元 worktree と共有しないため、agent の sandbox は task worktree 内だけへの書き込みで build、typecheck、依存更新を実行できます。
|
|
141
|
+
作成または再利用した task worktree では、tracked `package-lock.json` ごとに `npm ci --include=dev --prefer-offline --no-audit --no-fund` を実行し、root と独立 package の `node_modules` を worktree 内へ実体として配置します。依存関係を元 worktree と共有しないため、agent の sandbox は task worktree 内だけへの書き込みで build、typecheck、依存更新を実行できます。lock から入る依存は主の作業ツリーと同じになるため、npm cache にある tarball を再検証せずに使い、準備に要らない audit と fund の問い合わせは省きます(PJR-T01P)。
|
|
140
142
|
|
|
141
143
|
過去のバージョンが作成した `node_modules` シンボリックリンクを検出した場合は、リンク先へ変更を加えずリンクだけを削除してから `npm ci` で置き換えます。install に失敗した場合は agent を起動せず、調査できるよう task worktree を保持したままエラー終了します。依存取得に必要な registry と npm cache は、`exec run` を起動する環境から利用できる必要があります。
|
|
142
144
|
|
|
@@ -202,19 +204,19 @@ specdojo exec worktree commit \
|
|
|
202
204
|
|
|
203
205
|
commit 対象から除外する主なパス:
|
|
204
206
|
|
|
205
|
-
| 除外対象
|
|
206
|
-
|
|
|
207
|
-
| `tmp/`
|
|
208
|
-
| `
|
|
209
|
-
| 対象
|
|
210
|
-
| `exec/events/`
|
|
211
|
-
| `generated/`
|
|
207
|
+
| 除外対象 | 理由 |
|
|
208
|
+
| --------------------------------- | ---------------------------------------------- |
|
|
209
|
+
| `tmp/` | agent の作業用一時ファイルは commit に含めない |
|
|
210
|
+
| `plan.md` | plan は実行入力であり agent の成果物ではない |
|
|
211
|
+
| 対象 run 以外の `execution/runs/` | 他タスク・他 run の記録を混ぜない |
|
|
212
|
+
| `exec/events/` | event は root 側の状態管理で扱う |
|
|
213
|
+
| `generated/` | 再生成物を task 成果物に混ぜない |
|
|
212
214
|
|
|
213
215
|
対象 task の result は成果物変更と同じ commit に含めます。変更がない場合は commit を作成しません。
|
|
214
216
|
|
|
215
|
-
上表の除外に加え、プロンプトインジェクション対策として commit 対象を mode 別の許可リストで絞ります。review は対象 task の result のみ、edit は result と plan の `targets` から解決した成果物(maintenance / bootstrap 系 approach は実践の型ディレクトリも)だけを commit
|
|
217
|
+
上表の除外に加え、プロンプトインジェクション対策として commit 対象を mode 別の許可リストで絞ります。review は対象 task の result のみ、edit は result と plan の `targets` から解決した成果物(maintenance / bootstrap 系 approach は実践の型ディレクトリも)だけを commit し、許可リスト外の変更が残っていれば `commit-scope: integration blocked` と対象パスを出力し、commit・統合・通常の worktree 撤去を止めます。対象パスと次のアクションは result の申し送りと `integrate.log` に残します。詳細は [[specdojo:exec-config-guide|exec 設定ガイド]] の `agent 権限とプロンプトインジェクション対策` を参照します。
|
|
216
218
|
|
|
217
|
-
登録簿由来(`origin: register`)のタスクは許可リストを使わず、上表の除外だけを適用して作業ツリーの差分を commit します。HEAD に無い新規ファイルは、リポジトリ最上位、既知の成果物ディレクトリ(`docs/`、`src/`、`tests/`、`tools/`、`scripts/`、`packages/`)、HEAD で追跡済みの最上位ディレクトリ、対象 task の result と evidence、plan の `targets` から解決した成果物に置かれたものを commit します。`tmp/` 配下のファイルは常に commit
|
|
219
|
+
登録簿由来(`origin: register`)のタスクは許可リストを使わず、上表の除外だけを適用して作業ツリーの差分を commit します。HEAD に無い新規ファイルは、リポジトリ最上位、既知の成果物ディレクトリ(`docs/`、`src/`、`tests/`、`tools/`、`scripts/`、`packages/`)、HEAD で追跡済みの最上位ディレクトリ、対象 task の result と evidence、plan の `targets` から解決した成果物に置かれたものを commit します。`tmp/` 配下のファイルは常に commit 対象から除外します。それ以外の未追跡ディレクトリに置かれた新規ファイルは、上記の停止ガードの対象です。最上位に追加した新規ファイルを commit した場合は、統合ログと result の申し送りに「最上位に追加したファイル」として列挙します。既存ファイルの変更と削除、人間の作業(`execution: human`)は従来どおり commit します。`ready` への昇格検査は commit 対象のパスだけに適用するため、`tmp/` 配下の一時ファイルの `ready` は統合を止めません。
|
|
218
220
|
|
|
219
221
|
### 2.5. merge
|
|
220
222
|
|
|
@@ -233,10 +235,13 @@ specdojo exec worktree merge \
|
|
|
233
235
|
| exec branch 側に未統合 commit がある | merge する差分が存在する |
|
|
234
236
|
| task worktree に commit 対象の未commit変更がない | result / 成果物を取りこぼさない |
|
|
235
237
|
| 現在ブランチが exec branch ではない | 自分自身へ merge しない |
|
|
238
|
+
| 統合先の index に stage 済み変更がない | 別の操作の stage を保持する |
|
|
236
239
|
| 現在の未commit変更と merge 対象パスが重複しない | 手作業の変更を壊さない |
|
|
237
240
|
|
|
238
241
|
`prepare` が root に残した plan、result、claim event の複製は、重複判定の前に解放します(exec branch の commit 済み内容が merge で入るため)。それ以外の未commit変更が merge 対象パスと重複する場合は停止します。
|
|
239
242
|
|
|
243
|
+
stage 済み変更は merge 対象との重複にかかわらず、複製の解放前に対象パスと復旧手順を示して停止します。表示された worktree で commit するか、各パスに `git restore --staged -- <path>` を実行して本文を残してから再開します。複数リポジトリの統合も、いずれかの統合先に stage 済み変更があれば全体の事前検査で停止します。
|
|
244
|
+
|
|
240
245
|
通常は `git merge --no-ff` 相当で統合します。自動実行では `exec(<task-id>): <task name>` を merge commit の subject に使い、統合先の first-parent を1タスク1commitにします(`prepare execution` / `apply task changes` は exec branch 側に残ります)。`--ff-only` 指定時は fast-forward 可能な場合だけ統合します。
|
|
241
246
|
|
|
242
247
|
register 項目の統合で競合したのが項目自身の記帳ファイル(個票・イベント・plan・result)だけの場合は、記帳ファイルを次のように解決して merge commit を作ります。`waiting` を複数回経た項目では、wait 時の同期 merge の後も統合先と exec branch の双方で記帳ファイルが変わるためです。解決後の commit は通常の `git merge` と同じく pre-commit hook を実行しません。
|
|
@@ -246,11 +251,13 @@ register 項目の統合で競合したのが項目自身の記帳ファイル
|
|
|
246
251
|
- 個票は exec branch 側を基準にし、統合先だけにあるイベントが変えた `type` / `priority` / `owner` / `due` をイベントから再構築します。同じフィールドを後から exec branch 側のイベントが変えている場合は、exec branch 側を残します。タイトル・説明(本文)、状態遷移に伴うフィールド、登録日時はイベントから元の値を復元できないため再構築しません。
|
|
247
252
|
- plan・result・登録簿(`pjr-index.md`)は exec branch 側(再開後の最新の記帳)の内容で解決します。
|
|
248
253
|
|
|
254
|
+
Schedule タスクの統合で、run の終わりの記帳 commit が先に統合先へ入れた plan・result・claim event と、exec branch 側の同じファイルが両側の追加として競合した場合も、その task の run の記録(`runs/schedule/<task-id>/` 配下)と checkpoint の複製に限って exec branch 側の内容で解決します([Schedule実行運用ガイド](schedule-operation-guide.md) の「実行記録の記帳」を参照)。
|
|
255
|
+
|
|
249
256
|
上記以外の競合または commit hook の失敗で merge commit を作れなかった場合は、runner が `git merge --abort` を実行して統合先を開始前の状態へ戻します。Schedule タスクは `blocked`、register 項目は `waiting` へ遷移し、再開に使う exec branch と worktree は保持します。register の `wait` commit は abort 後に作るため、統合先へ `MERGE_HEAD` を残したまま部分 commit を試みません。block reason には hook の罫線や色を除いた失敗ステップ名、最初のエラー行、Vitest の末尾にある `FAIL`・`Test Files`・`Tests` の集計行を記録します。executor/reporter pipeline では checkpoint と統合段の commit / merge が失敗したときの stdout / stderr 全文と abort 結果を秘匿処理し、同じ run の `integrate.log` に保存します。
|
|
250
257
|
|
|
251
258
|
register 項目を `waiting` へ遷移したあとは、`wait` commit と、その時点までに統合先へ入った変更を exec branch へ通常 merge します。root の `wait` commit に保存済みの個票・イベント・plan・result は、worktree に残る同内容の未 commit 変更を解放してから merge し、これらの記帳パスの競合だけを `wait` commit 側で解決します。それ以外の競合は自動解決せずに同期 merge を中断します。これにより、再開時の merge-base を進めながら、別項目が統合先へ追加した成果を exec branch 側の削除として扱わないようにします。
|
|
252
259
|
|
|
253
|
-
hook や検査を直した後は、Schedule タスクでは `specdojo exec resume --project <project-id> --task <task-id>`、register 項目では元の `exec run --register ... --worktree --resume` を実行します。統合段から再開するため agent は再実行せず、保持した exec branch を merge します。親検証の失敗を成果物側で修正する必要がある register 項目は `--resume-from executor`
|
|
260
|
+
hook や検査を直した後は、Schedule タスクでは `specdojo exec resume --project <project-id> --task <task-id>`、register 項目では元の `exec run --register ... --worktree --resume` を実行します。統合段から再開するため agent は再実行せず、保持した exec branch を merge します。親検証の失敗を成果物側で修正する必要がある register 項目は `--resume-from executor` を併用します。統合段で止まった Schedule タスクの成果物を直す場合は `specdojo exec resume --project <project-id> --task <task-id> --resume-from executor` を実行します。統合先を exec branch と worktree へ取り込んでから executor を再実行するため、worktree で `git merge` や `git merge --abort` を実行しません。保護対象の設定変更を人が統合先へ適用した場合も、通常の `--resume` が統合先を exec branch と worktree へ取り込んでから executor を再開するため、worktree で手動 merge しません。
|
|
254
261
|
|
|
255
262
|
runner は `git merge --abort` の前に `git update-index -q --refresh` を実行します。同じ作業ツリーで動く routine などがファイルの stat だけを変えた場合でも、`not uptodate` で abort が失敗しないようにするためです。自動の `git merge --abort` 自体が失敗した場合は、runner が標準エラーへ手動復旧を案内します。案内された root worktree で状態と失敗原因を確認し、ロックファイルや Git プロセスなどの原因を解消してから次を実行してください。abort が完了するまでは commit や統合再開を行いません。
|
|
256
263
|
|
|
@@ -304,6 +311,8 @@ specdojo exec worktree prune --project <project-id>
|
|
|
304
311
|
|
|
305
312
|
分割コマンドは状態 event を更新しないため、成果物確認後に人が明示的に `complete` または `block` を実行します。
|
|
306
313
|
|
|
314
|
+
人が書いたイベントは、書いた人が成果物と合わせて commit します。runner の記帳 commit(`exec run` / `exec resume` / `exec cycle` の終わり)が拾うのは、`by` が `.specdojo/agent-members.yaml` の agent のイベントだけです。
|
|
315
|
+
|
|
307
316
|
```bash
|
|
308
317
|
specdojo exec complete \
|
|
309
318
|
--project <project-id> \
|
|
@@ -0,0 +1,77 @@
|
|
|
1
|
+
---
|
|
2
|
+
specdojo:
|
|
3
|
+
id: specdojo:job-sequence-guide
|
|
4
|
+
type: guide
|
|
5
|
+
status: draft
|
|
6
|
+
---
|
|
7
|
+
|
|
8
|
+
# 順次実行 Job の例
|
|
9
|
+
|
|
10
|
+
Sequential Job Guide
|
|
11
|
+
|
|
12
|
+
止まった Schedule task の再開 → track の auto ループ → 次の register 項目 → grade → docs build を、runner が順に実行する例です。`docs/ja/specdojo/samples/job-sequence.yaml` を project の `jobs_path` へコピーして使います。値制約と記録形式は [[specdojo:job-definition-standard|Job 定義標準]] を参照してください。
|
|
13
|
+
|
|
14
|
+
**対象読者**
|
|
15
|
+
|
|
16
|
+
- exec・grade・検査を夜間などにまとめて順次実行する開発者、運用者
|
|
17
|
+
|
|
18
|
+
**この文書で分かること**
|
|
19
|
+
|
|
20
|
+
- 順次実行 Job の定義例、手動・routine / cron からの起動、結果確認と再試行
|
|
21
|
+
|
|
22
|
+
**次に読む文書**
|
|
23
|
+
|
|
24
|
+
- [[specdojo:job-definition-standard|Job 定義標準]]
|
|
25
|
+
- [[specdojo:routine-operation-guide|routine 運用ガイド]]
|
|
26
|
+
|
|
27
|
+
## 1. 手動実行
|
|
28
|
+
|
|
29
|
+
入力の task ID・track・個票・評価対象を、実在する対象へ置き換えます。`schedule_state` は `execution_path` の `generated/state.json` を指し、段の末尾の `exec refresh` で最新状態を生成します。例は SpecDojo 本体の `docs:build` を呼ぶため、別の repository では導入済みの検査へ差し替えます。
|
|
30
|
+
|
|
31
|
+
```bash
|
|
32
|
+
specdojo job validate --project prj-0001
|
|
33
|
+
specdojo exec run --project prj-0001 --job job-sequence \
|
|
34
|
+
--input resume_task=T-EXAMPLE-document-020 track=example \
|
|
35
|
+
track_end_task=T-EXAMPLE-document-090 \
|
|
36
|
+
schedule_state=docs/ja/projects/prj-0001/execution/generated/state.json \
|
|
37
|
+
register_item=PJR-XXXX \
|
|
38
|
+
register_ticket=docs/ja/projects/prj-0001/controls/project-register/pjr-xxxx-example.md \
|
|
39
|
+
grade_path=docs/ja/product/example.md --dry-run
|
|
40
|
+
```
|
|
41
|
+
|
|
42
|
+
dry-run で解決済みの段・状態参照先を確かめ、実行時は `--dry-run` を外します。resume と auto は refresh 後の task 状態、register は個票の状態を終了コードに加えて確認します。grade は選択した文書の pipeline が完了しなければ非 0 で終了するため、その終了コードを使います。grade の失敗後も build を試す `on_failure: continue` を例示していますが、Run 全体は失敗のままです。
|
|
43
|
+
|
|
44
|
+
## 2. routine と cron
|
|
45
|
+
|
|
46
|
+
同じ Job を routine の `action` で参照します。`rtn-sequence.yaml` を `routines_path` に置き、入力は手動例と同様に対象へ合わせます。運用前に実行対象と agent 設定を確認してください。
|
|
47
|
+
|
|
48
|
+
```yaml
|
|
49
|
+
id: rtn-sequence
|
|
50
|
+
name: 夜間の順次実行
|
|
51
|
+
enabled: true
|
|
52
|
+
trigger:
|
|
53
|
+
cron: "0 1 * * *"
|
|
54
|
+
timezone: Asia/Tokyo
|
|
55
|
+
action:
|
|
56
|
+
kind: job
|
|
57
|
+
job: job-sequence
|
|
58
|
+
inputs:
|
|
59
|
+
resume_task: T-EXAMPLE-document-020
|
|
60
|
+
track: example
|
|
61
|
+
track_end_task: T-EXAMPLE-document-090
|
|
62
|
+
schedule_state: docs/ja/projects/prj-0001/execution/generated/state.json
|
|
63
|
+
register_item: PJR-XXXX
|
|
64
|
+
register_ticket: docs/ja/projects/prj-0001/controls/project-register/pjr-xxxx-example.md
|
|
65
|
+
grade_path: docs/ja/product/example.md
|
|
66
|
+
policy:
|
|
67
|
+
missed_run: latest
|
|
68
|
+
overlap: skip
|
|
69
|
+
```
|
|
70
|
+
|
|
71
|
+
cron は repository に移動して `routine run --due` を起動するだけです。たとえば5分ごとに `cd /path/to/repository && specdojo routine run --project prj-0001 --due` を呼びます。runner 自身が待機・各段の起動・完了判定を行うので、Claude Code・Codex・Antigravity の会話機能には依存しません。
|
|
72
|
+
|
|
73
|
+
## 3. 結果と再試行
|
|
74
|
+
|
|
75
|
+
Job Run JSON の `attempts[].steps` で成功・失敗・延期、終了コード、理由、各 command evidence 参照を確認します。project lock を取得するまでの上限は定義の3600秒です。grade 独自の lock も `--if-busy wait` で待ちます。grade 段の `timeout_seconds: 7200` は待機と処理を含む実行時間の上限で、超過するとプロセスを停止して延期にします。次回は同じ `job_run_id` による grade の再開を使います。
|
|
76
|
+
|
|
77
|
+
同じ `--scheduled-at` と入力で再実行すると、失敗した Run の次 attempt で先頭から実行します。完了済み Run の同じ実行枠は重複実行しません。新しい `--scheduled-at` は新規 Run になるため、停止した task の再開条件を確認して入力を変えます。routine 自体の失敗・延期履歴と実行枠の扱いは [[specdojo:routine-operation-guide|routine 運用ガイド]] に従います。
|