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
|
@@ -14,114 +14,117 @@ specdojo:
|
|
|
14
14
|
|
|
15
15
|
External Command Interface Specification (ECIS) Documentation Rules
|
|
16
16
|
|
|
17
|
-
外部 CLI
|
|
17
|
+
外部 CLI プロセスとの実行契約、入出力、終了判定、副作用、失敗処置、認証注入を YAML 1 ファイルで定義する基準を定めます。
|
|
18
18
|
|
|
19
19
|
## 1. 全体方針
|
|
20
20
|
|
|
21
|
-
- 1
|
|
22
|
-
-
|
|
23
|
-
-
|
|
24
|
-
-
|
|
21
|
+
- **1 連携 1 ファイル**: 実行目的と入出力契約を単位とし、同じ CLI でも目的・権限・出力契約が異なれば分割する。複数 provider をまとめる場合は、共通契約と差異の正本を示す。
|
|
22
|
+
- **正本を分担する**: 共通事項は上位の外部 I/F 一覧・設計、構造・値の制約は schema、起動方法は設定・リファレンスへ委ね、プロセス境界の判断情報に絞る。
|
|
23
|
+
- **起動方式を事実に合わせる**: 原則はシェルを経由しない。例外条件は「コマンドと正本参照」に従う。
|
|
24
|
+
- **共通の運用**: 役割の割り当ては適用先のメンバー定義に、`status`・承認・改訂と廃止・未決事項の登録簿への引き継ぎは [[specdojo:document-metadata-standard|ドキュメントメタ情報標準]] に従う。文書の整形・lint・構造検証はリポジトリの検証で扱い、業務の受入確認に含めない。
|
|
25
25
|
|
|
26
|
-
## 2.
|
|
26
|
+
## 2. 位置づけ
|
|
27
27
|
|
|
28
|
-
|
|
29
|
-
|
|
30
|
-
| 外部コマンド | 対象システムのプロセス境界外にあり、実行可能ファイルと引数を指定して起動する CLI |
|
|
31
|
-
| 起動契約 | 実行可能ファイル、サブコマンド、引数、実行ディレクトリ、タイムアウトの合意 |
|
|
32
|
-
| ストリーム契約 | stdin、stdout、stderr それぞれの使用有無、形式、文字コード、成功時・失敗時の意味 |
|
|
33
|
-
| 認証注入 | シークレットストアや CLI 認証プロファイルから、プロセスに認証状態を渡す方式。秘密値自体は仕様に含めない |
|
|
34
|
-
| 終了カテゴリ | CLI 固有の終了コードを、成功、入力不正、認証失敗、一時失敗など呼び出し元が扱える意味へ分類した値 |
|
|
35
|
-
|
|
36
|
-
ESIL は連携の存在と方向を一覧化し、本仕様は対応する `spec_ref` の先でプロセス起動の契約を定義します。API、ファイル転送、メッセージングが連携の本体であり CLI が単なる操作ツールの場合は、対応する API/ファイル/メッセージ仕様を正本とし、本仕様との責務の重複を避けます。
|
|
28
|
+
- ESIL(外部システム I/F 一覧)の `spec_ref` の先でプロセス境界の契約を定める。API・ファイル・メッセージ連携の操作手段として CLI を使う場合は、各方式の仕様を正本とする。
|
|
29
|
+
- 起動方法の正本は対象によって選ぶ。SpecDojo 自身のコマンドはコマンドリファレンス、SpecDojo が起動する AI provider CLI は起動設定の `command_template` と [[specdojo:exec-config-guide|exec 設定ガイド]]、その他の外部 CLI は公式リファレンスや製品マニュアルを参照する。
|
|
37
30
|
|
|
38
31
|
## 3. ファイル命名・ID規則
|
|
39
32
|
|
|
40
|
-
- ファイル名は `ifx-cmd-<term>.yaml
|
|
41
|
-
- ESIL の `interfaces[].kind` は
|
|
42
|
-
-
|
|
43
|
-
-
|
|
33
|
+
- ファイル名は `ifx-cmd-<term>.yaml`、ID のローカル部分は `ifx-cmd-<term>` とする。`<term>` は連携目的または外部 CLI を表す kebab-case とし、配置と ID の所有範囲は [[specdojo:docs-structure-guide|ドキュメント構成ガイド]] に従う。
|
|
34
|
+
- ESIL の `interfaces[].kind` は `コマンド` とし、`interfaces[].spec_ref` から本仕様の ID を一意に解決できるようにする。詳細仕様が未作成の間だけ `TBD` を使用できる。
|
|
35
|
+
- 同じ CLI の読取・更新など、契約を分ける場合は `ifx-cmd-git-read` / `ifx-cmd-git-write` のように目的を付ける。バージョンや状態は ID に含めない。
|
|
36
|
+
- 同梱の完成例の ID `specdojo:ifx-cmd-sample` は命名上の例外であり、実際の ESIL の参照先には使用しない。
|
|
44
37
|
|
|
45
38
|
## 4. 先頭メタ項目
|
|
46
39
|
|
|
47
|
-
YAML
|
|
40
|
+
- 先頭メタ項目と雛形自身のメタ情報は、[[specdojo:document-metadata-standard|ドキュメントメタ情報標準]] の「独立 YAML データファイルのメタ情報」と「生成物メタ情報雛形(`metadata_template`)」に従う。
|
|
41
|
+
- 成果物(雛形では `metadata_template` 内)は `type: api`、`rulebook: specdojo:ifx-cmd-rulebook` とし、`title` で対象と実行目的を識別する。
|
|
42
|
+
- `based_on` は作成根拠、`command.reference` は起動方法の正本参照として区別する。
|
|
43
|
+
- メタ項目の `version` は呼び出し契約の改版、`command.version_constraint` は CLI の対応バージョンを表す。
|
|
48
44
|
|
|
49
|
-
|
|
50
|
-
| -------- | ------------------------------------------------ | ---- |
|
|
51
|
-
| id | コマンド連携仕様 ID。成果物では `ifx-cmd-<term>` | ○ |
|
|
52
|
-
| type | `api` 固定 | ○ |
|
|
53
|
-
| title | 対象と実行目的が分かる仕様名 | ○ |
|
|
54
|
-
| status | `draft` / `ready` / `deprecated` | ○ |
|
|
55
|
-
| rulebook | `specdojo:ifx-cmd-rulebook` | ○ |
|
|
45
|
+
## 5. 本文要件
|
|
56
46
|
|
|
57
|
-
|
|
58
|
-
| based_on | 作成時に直接確認した設計・運用文書の ID 配列 | 任意 |
|
|
59
|
-
| supersedes | 置き換え対象の文書 ID 配列 | 任意 |
|
|
47
|
+
構造・型・許容値は `docs/specdojo/schemas/v1/ifx-cmd.schema.yaml` を正本とする。以下は契約の内容要件であり、schema で任意の項目も、本書で必須とした場合は記述する。
|
|
60
48
|
|
|
61
|
-
|
|
49
|
+
| 対象キー | 必須性 | 契約として定める内容 |
|
|
50
|
+
| ---------------- | ------------------------------ | ------------------------------------------------------------------------------------------------------------------------------ |
|
|
51
|
+
| `command` | 必須 | 実行目的、実行ファイルの識別方法、起動方式。`reference` に起動方法を解決できる正本を必ず示す |
|
|
52
|
+
| `streams` | 必須 | stdin の要否、stdout の受領内容と解析対象、stderr の診断用途。各ストリームの形式と意味を明示し、テキストは原則 UTF-8 とする |
|
|
53
|
+
| `files` | ファイル入出力がある場合は必須 | 渡すファイルと作るファイルのパスまたは解決規則、形式、用途、作成・更新主体。内容の構造は対応する schema・仕様を参照する |
|
|
54
|
+
| `side_effects` | 副作用の有無の説明が必須 | 外部状態・ローカル環境への変更と利用枠消費。ルートまたは `execution.side_effects` の一方にまとめ、副作用がなければその旨を書く |
|
|
55
|
+
| `exit_codes` | 必須 | 成功と代表的失敗の終了コード、識別条件、共通カテゴリ、自動再試行の可否 |
|
|
56
|
+
| `authentication` | 必須 | 認証方式、注入機構、参照名、供給元の管理境界、マスク方針。認証不要でもその旨を明示する |
|
|
57
|
+
| `execution` | 必須 | 作業ディレクトリ、時間・並列実行・ネットワークの制約、冪等性の成立条件または保証できない理由 |
|
|
58
|
+
| `error_handling` | 必須 | 再試行の対象と上限・待機方式、タイムアウト、出力解析失敗、認証失敗に対する個別の処置 |
|
|
62
59
|
|
|
63
|
-
|
|
60
|
+
`arguments` は既存仕様との後方互換性のための定義である。新規作成・改訂では引数表を持たず、`command.reference` と入出力の契約へ一本化する。
|
|
64
61
|
|
|
65
|
-
|
|
66
|
-
| -------------- | -------------------------------------------------------------------------------- | ---- |
|
|
67
|
-
| command | 実行可能ファイル、サブコマンド、用途、バージョン制約、シェル経由の有無 | ○ |
|
|
68
|
-
| arguments | option/positional の種別、必須性、型、値の供給元、説明 | ○ |
|
|
69
|
-
| streams | stdin、stdout、stderr の使用有無、データ形式、文字コード、契約 | ○ |
|
|
70
|
-
| exit_codes | 終了コードと意味、共通カテゴリ、リトライ可否 | ○ |
|
|
71
|
-
| authentication | 認証方式、注入機構、参照名、秘密値の供給元、ログのマスク方針 | ○ |
|
|
72
|
-
| execution | 実行ディレクトリ、タイムアウト、ネットワーク要否、並列実行数、冪等性 | ○ |
|
|
73
|
-
| error_handling | 再試行対象、試行上限、待機方式、タイムアウト時、出力解析失敗時、認証失敗時の処置 | ○ |
|
|
62
|
+
## 6. 記述ガイド
|
|
74
63
|
|
|
75
|
-
|
|
64
|
+
### 6.1. 連携単位とメタ情報
|
|
76
65
|
|
|
77
|
-
|
|
66
|
+
- **判断基準**: ESIL の目的と成功後の状態が対応し、1 ファイルを一つの契約として検証できること。provider 一覧や設定値を複数キーへ繰り返さない。
|
|
67
|
+
- **影響の照合先**: ESIL の参照行、呼び出し元の業務完了・回復条件、起動設定・入出力処理、正常・異常・再試行の検証を照合する。
|
|
68
|
+
- **良い例**: 読取と更新を別 ID にし、`title` に対象と目的を書く。provider ごとに実行ファイルが変わるときは、`executable` に設定の該当キーから解決する旨を示し、一覧自体は設定へ委ねる。
|
|
69
|
+
- **悪い例**: 一つの仕様に読取・登録・削除を混在させる。設定の provider 一覧を目的・実行ファイル・コメントへそれぞれ転載する。
|
|
70
|
+
|
|
71
|
+
### 6.2. コマンドと正本参照
|
|
72
|
+
|
|
73
|
+
- **判断基準**: `purpose` で呼び出し元から見た成功後の状態を示し、`reference` で正本の文書・設定キー・対象操作を特定する。通常は実行ファイルとサブコマンドを分け、`shell: false` とする。
|
|
74
|
+
- **シェル起動の例外**: 呼び出し元が管理された起動設定を展開し、シェルが必要な場合は `shell: true` を認める。理由、テンプレートの正本と管理境界、展開値の検証・制限の参照先を示す。利用者入力の無制限なシェル構文評価は認めない。テンプレート全文や複数コマンドの処理手順は転載しない。
|
|
75
|
+
- **良い例**: AI provider CLI では `reference` に `.specdojo/exec-defaults.yaml` の `providers.<provider>.command_template` と exec 設定ガイドを示す。`shell: true` の理由を stdin から起動引数への変換として説明し、設定の保護と展開値の検証は同ガイドの契約を参照する。
|
|
76
|
+
- **悪い例**: 実際はシェルを使うのに `false` と書く。「外部 CLI だから」という理由だけで `true` にする。`executable` に引数やパイプを連結し、起動設定と別のコマンド全文を管理する。
|
|
78
77
|
|
|
79
|
-
### 6.
|
|
78
|
+
### 6.3. ストリーム
|
|
80
79
|
|
|
81
|
-
-
|
|
82
|
-
-
|
|
80
|
+
- **判断基準**: stdin は入力内容と終端、stdout は採用範囲、stderr は診断用途を記す。stdin を使わない場合も要否と形式を明示する。出力の詳細構造は正本へ委ね、判定に必要な意味を残す。
|
|
81
|
+
- **良い例**: 進捗が混在する stdout では、末尾の構造化報告の抽出範囲と欠落・解析失敗時の扱いを示す。終了コードと報告内容の両方で完了を判断するなら、各々が保証する範囲を書く。
|
|
82
|
+
- **悪い例**: 構造化部分があることを理由に stdout 全体を JSON と記す。「CLI の既定出力」とだけ書く。stderr が空なら成功と判定する。
|
|
83
83
|
|
|
84
|
-
|
|
85
|
-
- positional 引数は `position` を 1 始まりで付け、option 引数は `name` に CLI の表記を記載する。可変値は `example` に実値ではなく公開可能な例を置く。
|
|
84
|
+
### 6.4. ファイル
|
|
86
85
|
|
|
87
|
-
|
|
86
|
+
- **判断基準**: 入出力別に、パスの基準、可変部の供給元と書式、形式、作成・更新・読取主体、内容仕様の正本を特定する。`description` など既存欄で説明し、専用キーやフィールド一覧を追加しない。CLI の生成物と呼び出し元の実行記録を区別する。
|
|
87
|
+
- **入出力がない場合**: 入出力のない側の配列は `[]` または省略で表し、どちらも該当の入出力がないことを意味する。入出力が一切なければ `files` 自体を省略できる。未確認の場合と混同しない。
|
|
88
|
+
- **良い例**: 入力の相対パス、可変部分の解決元(確定済み取引の識別情報)、作成主体(呼び出し元)、内容仕様の正本を示す。CLI が出力ファイルを作らない例では `outputs: []` とし、呼び出し元のログ保存と分ける。
|
|
89
|
+
- **悪い例**: 出力を「各種ファイル」とだけ書く。呼び出し元が保存するログや別段階で作成する result を、同じ CLI の出力として列挙する。入力ファイルの作成主体や可変部分の解決元が書かれていない。
|
|
88
90
|
|
|
89
|
-
|
|
90
|
-
- `streams.stdout` は成功時に呼び出し元が解析する形式と最小契約を記載する。機械処理する場合は `json` または `jsonl` を優先し、人向けの可変文言に依存しない。
|
|
91
|
-
- `streams.stderr` は進捗、警告、失敗詳細のどれが出力されるかを記載する。stderr の文言だけで成否を判定せず、終了コードと構造化出力を優先する。
|
|
92
|
-
- 形式は `text` / `json` / `jsonl` / `yaml` / `binary` / `none` から選び、テキスト形式には原則 `UTF-8` を指定する。
|
|
91
|
+
### 6.5. 終了状態と識別条件
|
|
93
92
|
|
|
94
|
-
|
|
93
|
+
- **判断基準**: 各終了コードから呼び出し元の次の動作を判断できること。同じコードが複数の意味を持つ場合は、`meaning` に追加信号・判定順・未分類時の扱いを記す。正本に定義された構造化エラーや stdout / stderr の検出条件を参照できればよく、検出パターンの一覧は転載しない。
|
|
94
|
+
- **カテゴリの使い分け**: `success` はプロセスの成功を表し、業務完了に別の条件があれば区別する。`input_error` は入力修正、`authentication_error` は再認証、`authorization_error` は権限の見直し、`permanent_failure` は原因解消を必要とする。`rate_limit` は利用制限、`transient_failure` は一時的障害であり、再試行できる条件を失敗処置で定める。
|
|
95
|
+
- **良い例**: 非ゼロ終了と設定済み検出信号が一致した場合だけ利用制限とし、ほかの非ゼロ終了は汎用失敗として停止する。認証失敗を個別検出できない実装なら、その制約と手動確認の扱いも書く。
|
|
96
|
+
- **悪い例**: 汎用的な exit 1 をすべて一時失敗とする。識別信号がないのに原因別の自動分岐ができると宣言する。exit 0 だけで成果物の検証まで成功したとみなす。
|
|
95
97
|
|
|
96
|
-
|
|
97
|
-
| ------- | ------------------------------------------ | ---- |
|
|
98
|
-
| code | CLI が返す整数の終了コード | ○ |
|
|
99
|
-
| meaning | CLI 固有の意味と呼び出し元が識別できる条件 | ○ |
|
|
98
|
+
### 6.6. 副作用と冪等性
|
|
100
99
|
|
|
101
|
-
|
|
102
|
-
|
|
100
|
+
- **判断基準**: 永続的な変更、利用枠・課金への影響、変更してはならない範囲を示す。`idempotency` は同一入力での再実行の保証を表し、自動再試行する場合は二重処理を防ぐ条件を明記する。保証がなければ、再開前に既存状態をどう扱うかを書く。
|
|
101
|
+
- **良い例**: 発注登録では同じリクエスト ID による重複排除を条件とする。非決定的な編集処理では冪等性を保証せず、同じ作業ディレクトリの差分を引き継ぎ、確認して再開する条件を示す。
|
|
102
|
+
- **悪い例**: 同じファイル名へ書くという理由だけで業務処理全体が冪等とする。再試行による二重登録や利用枠の追加消費を説明しない。
|
|
103
103
|
|
|
104
|
-
|
|
104
|
+
### 6.7. 認証注入
|
|
105
105
|
|
|
106
|
-
|
|
106
|
+
- **判断基準**: `method` と `injection` は認証の種類と渡し方を分け、`names` には必要な参照名を書く。認証値は起動引数や標準入力へ埋め込まない。`secret_source` には管理境界、`log_policy` には引数・環境変数・stdout・stderr・保存ログのマスク対象とタイミングを書く。認証不要の場合の表現も schema の制約を満たすこと。
|
|
107
|
+
- **良い例**: CLI のログインプロファイルを利用する場合、プロファイル名と保管を担う管理境界を示し、呼び出し元が秘密値を注入しないことを書く。環境変数で渡す場合は変数名だけを示す。
|
|
108
|
+
- **悪い例**: 認証トークンの実値、秘密値入り URL、個人環境の認証ファイルの実パスを例示する。プロファイルを利用するのに環境変数注入と記す。
|
|
107
109
|
|
|
108
|
-
|
|
109
|
-
- `injection.mechanism` は `none` / `environment_variable` / `credential_store` / `workload_identity` / `cli_profile` から選び、必要な参照名を `injection.names` に列挙する。
|
|
110
|
-
- `secret_source` に値を供給する管理境界を記載し、`log_policy` に引数、環境変数、stdout/stderr のマスク条件を記載する。
|
|
111
|
-
- 認証トークン、秘密鍵、パスワード、認証プロファイルの実パスを記載しない。コマンド引数への秘密値の埋め込みも許可しない。
|
|
110
|
+
### 6.8. 実行制約と失敗処置
|
|
112
111
|
|
|
113
|
-
|
|
112
|
+
- **判断基準**: 作業ディレクトリと時間・並列実行・ネットワークの制約は公開契約や確認した実装・設定を根拠にする。schema で参照値や上限なしを表せず判断が未了なら、許容されるプレースホルダと共通ラベルで現在動作・不足する判断・影響・確認先を残し、架空の固定値で埋めない。
|
|
113
|
+
- **再試行と回復**: `retryable` と `retry.on_categories` を照合し、対象条件、試行上限の数え方、待機方式を揃える。利用制限でも短時間の制限と利用枠の枯渇を区別し、実際の停止・待機・切替条件は正本へ委ねる。タイムアウト時の子プロセスと部分出力、出力解析失敗時の既存変更、認証失敗時の確認先を個別に定める。
|
|
114
|
+
- **良い例**: タイムアウトが未決定なら、現在は終了まで待つことと、上限・終了処置を決める必要を区別して記す。出力異常時は自動再試行を止め、変更を保持して人の確認または再開に委ねる。
|
|
115
|
+
- **悪い例**: schema を通すためだけに時間や並列数を捏造する。「失敗時はリトライ」とだけ書く。認証・認可・入力不正を待機だけで回復する一時失敗として扱う。
|
|
114
116
|
|
|
115
|
-
|
|
116
|
-
- `execution.idempotency` は `guaranteed` とその条件を記載する。副作用のあるコマンドを再試行する場合は、リクエスト ID など重複実行を防ぐ条件を明示する。
|
|
117
|
-
- `error_handling.retry.on_categories` は `exit_codes` の category と一致させ、`max_attempts` と `backoff` を記載する。認証失敗や入力不正は自動再試行しない。
|
|
117
|
+
### 6.9. 成果物の検証手順
|
|
118
118
|
|
|
119
|
-
-
|
|
119
|
+
- **判断基準**: 作成・改訂した仕様 YAML の契約を、参照する正本と起動・入出力・報告解析の検証入口へ照合できること。CLI を起動する検証の詳細は参照先へ委ねる。
|
|
120
|
+
- **確認手順**: 正本の実在と適用範囲、ファイルの作成主体・可変パス・内容仕様を照合し、正常、同じコードの異なる失敗、出力欠落、途中失敗後の再実行を追う。入力・観測信号・期待結果と検証入口の参照先、確認結果を実行記録に残す。
|
|
121
|
+
- **合格条件**: 各ケースの業務完了判定、次の動作、副作用と回復条件が契約と一致する。識別不能な失敗は自動分類せず手動確認へつながり、未決事項は現在動作と影響をたどれること。不一致は仕様または参照先を修正し、該当ケースを再確認する。
|
|
122
|
+
- **良い例**: 同じ exit 1 を追加信号と判定順で分類し、途中失敗後の再実行で二重処理を防ぐ条件まで正本・検証結果と照合する。
|
|
123
|
+
- **悪い例**: schema 合格だけで業務完了や再試行の安全性も保証したとみなす。検証入口を示さず「動作確認済み」とする。
|
|
120
124
|
|
|
121
125
|
## 7. 禁止事項
|
|
122
126
|
|
|
123
|
-
-
|
|
124
|
-
-
|
|
125
|
-
-
|
|
126
|
-
-
|
|
127
|
-
- DB 物理構造、内部クラス名、プロセス起動ライブラリの API 呼び出し、スクリプト全文などの実装詳細を含めない。
|
|
127
|
+
- 引数表、起動テンプレート全文、検出パターン一覧を正本と別に管理すること。
|
|
128
|
+
- シェル起動の例外条件を満たさず `shell: true` とすること、または実際の起動方式を隠して `false` とすること。
|
|
129
|
+
- stdout / stderr、プロセス終了 / 業務完了、CLI の生成物 / 呼び出し元の記録を混同すること。
|
|
130
|
+
- 追加信号のない終了コードだけで原因を断定したり、副作用の回復条件がないまま自動再試行したりすること。
|