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
|
@@ -3,310 +3,255 @@ specdojo:
|
|
|
3
3
|
id: specdojo:ifx-file-rulebook
|
|
4
4
|
type: rulebook
|
|
5
5
|
deliverable_type: api
|
|
6
|
-
status:
|
|
6
|
+
status: ready
|
|
7
|
+
target_format: yaml
|
|
7
8
|
recipe: not-needed
|
|
8
9
|
sample: specdojo:ifx-file-sample
|
|
9
10
|
template: not-needed
|
|
11
|
+
based_on:
|
|
12
|
+
- specdojo:rulebook-authoring-standard
|
|
10
13
|
---
|
|
11
14
|
|
|
12
|
-
#
|
|
15
|
+
# 外部ファイル連携仕様作成ルール
|
|
13
16
|
|
|
14
|
-
|
|
17
|
+
External File Exchange Specification Authoring Rulebook
|
|
15
18
|
|
|
16
|
-
|
|
17
|
-
ESIL 側の `spec_ref: ifx-file-...` は、このEFESのID(およびファイル名)と対応させます。
|
|
19
|
+
外部システムや独立したサブシステム・プロセス間でファイルを授受する契約(配置場所・命名規則・データ形式・必須項目・書き手と読み手・受け渡し手段・失敗時の扱い)を YAML 形式で定義するための規約を定めます。実装コードや外部スキーマの詳細構造は正本を参照し、本書ではファイル受け渡し契約の必須構造と判断基準を規定します。
|
|
18
20
|
|
|
19
|
-
|
|
21
|
+
## 1. 全体方針
|
|
20
22
|
|
|
21
|
-
|
|
23
|
+
### 1.1. 目的と適用範囲
|
|
22
24
|
|
|
23
|
-
|
|
24
|
-
|
|
25
|
-
-
|
|
25
|
+
1. **目的**: システム間・プロセス間で授受されるデータファイルおよび状態ファイルの契約を YAML 1 ファイルで明確化し、書き手(送信元)と読み手(受信先)の認識齟齬および異常時の対応漏れを防ぎます。
|
|
26
|
+
2. **適用範囲**: CSV、TSV、JSON、XML 等のファイルを介して行われるバッチ連携、データ受け渡し、および実行パイプライン段間のエビデンス・状態ファイル連携仕様に適用します。
|
|
27
|
+
3. **共通の運用**: 役割の割り当ては適用先のメンバー定義に、`status` の昇格と承認、改訂と廃止、未決事項の登録簿への引き継ぎは [[specdojo:document-metadata-standard|ドキュメントメタ情報標準]] に従い、本書と成果物で言い直しません。文書の整形・lint はリポジトリの検証で扱い、業務の検証に含めません。
|
|
26
28
|
|
|
27
|
-
|
|
29
|
+
### 1.2. 記載原則と責務境界
|
|
28
30
|
|
|
29
|
-
|
|
30
|
-
|
|
31
|
-
-
|
|
31
|
+
1. **外部合意に必要な最小十分の記載**: 読み手・書き手間の契約合意と検証に必要な項目に集中し、DB 物理テーブル名や内部実装クラス名などの内部構造は記載しません。
|
|
32
|
+
2. **他の外部インターフェース仕様との境界**:
|
|
33
|
+
- ネットワーク越しの同期 API 契約は [[specdojo:ifx-api-rulebook|外部API仕様作成ルール]]、外部 CLI プロセスの起動契約(引数・標準入出力・終了コード)は [[specdojo:ifx-cmd-rulebook|外部コマンド連携仕様作成ルール]] で扱います。
|
|
34
|
+
- 外部コマンドやエージェントが生成・参照するファイル自体の永続化契約・必須項目・破損時の扱いを独立して合意・検証する必要がある場合は、本ルール(`ifx-file`)で定義します。
|
|
35
|
+
3. **正本の参照と二重管理の防止**: データ構造の完全な定義が外部スキーマ(JSON Schema、XSD 等)や実装コードの型定義に存在する場合は、`schema_ref` または `schema.references` で正本を参照し、全項目の再掲を避けます。
|
|
32
36
|
|
|
33
|
-
## 2.
|
|
37
|
+
## 2. 位置づけ
|
|
34
38
|
|
|
35
|
-
|
|
36
|
-
|
|
37
|
-
-
|
|
38
|
-
-
|
|
39
|
-
|
|
40
|
-
|
|
39
|
+
```mermaid
|
|
40
|
+
flowchart LR
|
|
41
|
+
ESIL["外部システムI/F一覧 (ifx-index)"] -->|"spec_ref で参照"| EFES["外部ファイル連携仕様 (ifx-file-*)"]
|
|
42
|
+
IFXCMD["外部コマンド連携仕様 (ifx-cmd-*)"] -.->|"受け渡しファイル契約を参照"| EFES
|
|
43
|
+
EFES -->|"schema_ref / references で参照"| SCHEMA["正本スキーマ / 型定義"]
|
|
44
|
+
```
|
|
41
45
|
|
|
42
|
-
|
|
46
|
+
1. **一覧からの詳細化**: 本仕様は [[specdojo:ifx-index-rulebook|外部システムI/F一覧作成ルール]] に従う `ifx-index` に登録されたファイル連携(`kind: ファイル`、または外部コマンド連携等で授受するファイル契約)の詳細仕様として位置づけます。
|
|
47
|
+
2. **ID の対応**: `ifx-index` 側の `spec_ref` に記載された文書 ID(例: `prj-0001:ifx-file-agent-evidence`)と、本仕様の `x-spec-meta.id` を一致させます。
|
|
48
|
+
3. **契約の主体とファイルの主体**: `source` / `target` は連携契約全体の送信元・受信先、`writer` / `reader` は個別ファイルを実際に書く・読む主体です。報告内容の作り手とファイルの書き手が異なる場合は、`writer` にファイルの書き手を書きます。
|
|
43
49
|
|
|
44
|
-
|
|
45
|
-
- 実装クラス/関数名・内部モジュール構成
|
|
46
|
-
- UI操作の逐語列挙
|
|
50
|
+
## 3. ファイル命名・ID規則
|
|
47
51
|
|
|
48
|
-
|
|
52
|
+
命名と配置の共通原則は [[specdojo:docs-structure-guide|ドキュメント構成ガイド]] に従います。
|
|
49
53
|
|
|
50
|
-
|
|
54
|
+
### 3.1. ファイル配置と命名規則
|
|
51
55
|
|
|
52
|
-
|
|
53
|
-
- `file
|
|
54
|
-
-
|
|
55
|
-
- `format`(`CSV`/`TSV`/`JSON`/`XML`)
|
|
56
|
-
- `transport`(受け渡し方法の概要)
|
|
57
|
-
- `schema`(フォーマット別の構造定義)
|
|
56
|
+
1. **配置先**: プロダクト文書は `docs/ja/product/020-external-interface-specs/`、プロジェクト文書は `docs/ja/projects/<project-id>/020-external-interface-specs/` に配置します。
|
|
57
|
+
2. **ファイル名**: `ifx-file-<対象データまたは連携名>.yaml`(英小文字・数字・ハイフンの kebab-case、例: `ifx-file-agent-evidence.yaml`)とします。
|
|
58
|
+
3. **1 ファイルの粒度**: 原則として 1 つのファイル連携契約(1 バッチ処理または 1 パイプライン受け渡し単位)につき 1 YAML ファイルを作成します。同一契約内で連動して生成・参照される複数ファイル(例: `evidence.json` と `pipeline-state.json`)は、`files` 配列を用いて 1 ファイルにまとめて定義できます。
|
|
58
59
|
|
|
59
|
-
|
|
60
|
+
### 3.2. 仕様 ID 規則
|
|
60
61
|
|
|
61
|
-
|
|
62
|
-
|
|
63
|
-
| id | ファイル仕様ID(`ifx-file-...`)、ESILの `spec_ref` と対応 | ○ |
|
|
64
|
-
| type | `api` 固定 | ○ |
|
|
65
|
-
| status | `draft` / `ready` / `deprecated` | ○ |
|
|
66
|
-
| based_on | 根拠となる他仕様のIDリスト(例: `["ifx-api-auth"]`) | 任意 |
|
|
62
|
+
1. **仕様 ID**: プロダクト文書は `ifx-file-<kebab-case>`、プロジェクト修飾を伴う場合は `<project-id>:ifx-file-<kebab-case>` とします。
|
|
63
|
+
2. **一意性**: ファイル名の stem(拡張子を除いた部分)と ID のローカル部を一致させ、文書インデックス全体で一意にします。
|
|
67
64
|
|
|
68
|
-
## 4.
|
|
65
|
+
## 4. 推奨 Frontmatter・メタ情報項目
|
|
69
66
|
|
|
70
|
-
|
|
67
|
+
共通メタ情報の原則は [[specdojo:document-metadata-standard|ドキュメントメタ情報標準]] を正本とします。
|
|
71
68
|
|
|
72
|
-
|
|
69
|
+
### 4.1. スキーマ宣言とメタ情報(x-spec-meta)の構成
|
|
73
70
|
|
|
74
|
-
|
|
71
|
+
YAML 成果物の先頭にはスキーマ検証用の modeline コメント(専用スキーマが未整備の場合は `# specdojo-schema: none reason=no-ifx-file-schema`)を記載し、ルートキー `x-spec-meta` 配下にメタ情報を定義します。`none` は構造の検証だけを省き、`x-spec-meta.type` と rulebook 宣言の照合はリポジトリの schema 検証で省かれません。
|
|
75
72
|
|
|
76
|
-
|
|
73
|
+
```yaml
|
|
74
|
+
# specdojo-schema: none reason=no-ifx-file-schema
|
|
75
|
+
x-spec-meta:
|
|
76
|
+
id: prj-0001:ifx-file-agent-evidence
|
|
77
|
+
type: api
|
|
78
|
+
status: draft
|
|
79
|
+
title: 外部ファイル連携仕様(agent の evidence)
|
|
80
|
+
rulebook: specdojo:ifx-file-rulebook
|
|
81
|
+
based_on:
|
|
82
|
+
- prj-0001:ifx-index
|
|
83
|
+
```
|
|
77
84
|
|
|
78
|
-
|
|
85
|
+
### 4.2. メタ情報の各フィールド定義
|
|
79
86
|
|
|
80
|
-
|
|
87
|
+
| フィールド名 | 必須 | 型 | 説明 |
|
|
88
|
+
| ------------ | ---- | ------ | ------------------------------------------------------------------------------------------------------------ |
|
|
89
|
+
| `id` | ○ | string | 仕様の一意な ID。ファイル名および `ifx-index` の `spec_ref` と対応させます。 |
|
|
90
|
+
| `type` | ○ | string | `api` 固定。本 rulebook の `deliverable_type: api` と一致させます(`file` 等の別値を指定してはなりません)。 |
|
|
91
|
+
| `status` | ○ | string | 文書のライフサイクル状態(`draft` / `ready` / `deprecated`)。 |
|
|
92
|
+
| `title` | ○ | string | 対象ファイルまたは連携契約を識別できる日本語名称。 |
|
|
93
|
+
| `rulebook` | ○ | string | 準拠する rulebook ID(`specdojo:ifx-file-rulebook` 固定)。 |
|
|
94
|
+
| `part_of` | 任意 | array | 所属する上位文書 ID の配列。 |
|
|
95
|
+
| `based_on` | 任意 | array | 根拠となる上位文書 ID(`ifx-index` 等)の配列。未作成の文書や無関係な ID は記載しません。 |
|
|
96
|
+
| `supersedes` | 任意 | array | 置き換え元の旧仕様 ID の配列。 |
|
|
81
97
|
|
|
82
|
-
|
|
98
|
+
## 5. 本文要件
|
|
83
99
|
|
|
84
|
-
|
|
85
|
-
- `endpoint`: 接続先の説明(URL/ホスト名/共有パス等。機密値は書かない)
|
|
100
|
+
### 5.1. トップレベル構造
|
|
86
101
|
|
|
87
|
-
|
|
102
|
+
YAML のルートには以下のキーを配置します。
|
|
88
103
|
|
|
89
|
-
|
|
104
|
+
| キー名 | 必須 | 型 | 概要 |
|
|
105
|
+
| --------------------- | ---- | -------------- | ------------------------------------------------------------------------- |
|
|
106
|
+
| `x-spec-meta` | ○ | object | 仕様のメタ情報(第4章参照)。 |
|
|
107
|
+
| `file` または `files` | ○ | object / array | 単一ファイルの場合は `file`、複数ファイル群の場合は `files` で定義する。 |
|
|
108
|
+
| `source` | ○ | string | 送信元・生成元のシステムまたは主体。 |
|
|
109
|
+
| `target` | ○ | string | 受信先・利用先のシステムまたは主体。 |
|
|
110
|
+
| `direction` | ○ | string | 連携方向(`source_to_target` / `target_to_source` / `bidirectional`)。 |
|
|
111
|
+
| `format` | ○ | string | 代表データフォーマット(`CSV` / `TSV` / `JSON` / `XML` / `その他`)。 |
|
|
112
|
+
| `timing` | ○ | string | 連携が発生する契機・スケジュール・パイプライン段階。 |
|
|
113
|
+
| `transport` | ○ | object | 受け渡し手段・配置エンドポイント・頻度・書き込み安全性。 |
|
|
114
|
+
| `schema` | ○ | object | フォーマット別の構文設定と、フィールド定義または正本スキーマ参照。 |
|
|
115
|
+
| `error_handling` | ○ | object | 欠落(`missing`)・破損(`malformed`)・伝送失敗(`transport_failure`)。 |
|
|
90
116
|
|
|
91
|
-
|
|
117
|
+
### 5.2. ファイル基本情報(file / files)
|
|
92
118
|
|
|
93
|
-
|
|
94
|
-
- **厳密スキーマ(任意)**:
|
|
95
|
-
- JSON: `schema.json_schema`(JSON Schema相当をYAMLで記述、または外部参照)
|
|
96
|
-
- XML: `schema.xsd_ref`(XSDへの参照)
|
|
119
|
+
単一ファイルの場合は `file` オブジェクト、同一契約内で複数のファイルを扱う場合は `files` 配列の各要素に以下の項目を定義します。
|
|
97
120
|
|
|
98
|
-
|
|
121
|
+
| 項目名 | 必須 | 型 | 説明 |
|
|
122
|
+
| ----------------- | -------- | ------ | ------------------------------------------------------------------------------------------------------------------------ |
|
|
123
|
+
| `name` | ○ | string | ファイルの基本名称(例: `orders.csv`、`evidence.json`)。 |
|
|
124
|
+
| `naming_rule` | ○ | string | 固定名または日時・連番・識別子を含む命名規則(例: `orders_YYYYMMDD.csv`、`evidence.json`)。 |
|
|
125
|
+
| `location` | ○ | string | 配置ディレクトリまたは論理パス。可変部は `<project-id>`、`<run-id>` 等のプレースホルダで示します。 |
|
|
126
|
+
| `description` | ○ | string | 当該ファイルが担う役割と格納データの要約。 |
|
|
127
|
+
| `writer` | 条件付き | string | ファイルを生成・更新する主体と書き込み契機。`files` で複数ファイルを扱う場合や `bidirectional` 連携では必須とします。 |
|
|
128
|
+
| `reader` | 条件付き | string | ファイルを読み取る主体と利用目的。`files` で複数ファイルを扱う場合や `bidirectional` 連携では必須とします。 |
|
|
129
|
+
| `format` | 任意 | string | ファイル個別のフォーマット(`files` 内で形式や文字コードを確認・明示する場合に記載)。 |
|
|
130
|
+
| `encoding` | 任意 | string | ファイル個別の文字エンコーディング(例: `UTF-8`)。 |
|
|
131
|
+
| `schema_ref` | 任意 | string | 当該ファイルの構造正本(実装型定義やスキーマファイル)への参照パス(例: `src/exec/evidence.ts#ExecEvidence`)。 |
|
|
132
|
+
| `required_fields` | 任意 | array | 正本参照時に読み手が必須として検証するトップレベル項目名の配列(例: `[schema_version, task_id, run_id, validations]`)。 |
|
|
99
133
|
|
|
100
|
-
|
|
101
|
-
- 各フィールド要素は以下を持つ
|
|
134
|
+
### 5.3. 連携方向と参加者(source, target, direction)
|
|
102
135
|
|
|
103
|
-
|
|
104
|
-
|
|
105
|
-
| name | 項目名(snake_case推奨) | ○ |
|
|
106
|
-
| type | `string` / `integer` / `number` / `boolean` / `date` / `datetime` / `enum` | ○ |
|
|
107
|
-
| description | 項目説明 | 任意 |
|
|
108
|
-
| required | 必須かどうか(true/false) | 任意 |
|
|
109
|
-
| example | 例値 | 任意 |
|
|
110
|
-
| constraints | 制約(min/max/pattern等。必要な範囲で) | 任意 |
|
|
111
|
-
| enum | `type: enum` の場合の許容値 | 任意 |
|
|
112
|
-
| mapping | フォーマット別の対応付け(CSV列名、JSONパス、XPath等) | 任意 |
|
|
136
|
+
1. `source` / `target`: システム名またはコンポーネント名で書きます。
|
|
137
|
+
2. `direction`: 段間遷移や状態ファイル更新など、双方が書き読みする授受は `bidirectional` とします。
|
|
113
138
|
|
|
114
|
-
|
|
139
|
+
### 5.4. フォーマットと連携契機(format, timing)
|
|
115
140
|
|
|
116
|
-
|
|
117
|
-
- JSON: `mapping.json.pointer: "/data/order_id"`(JSON Pointer)
|
|
118
|
-
- XML: `mapping.xml.xpath: "/Order/OrderId"`(XPath例)
|
|
141
|
+
1. `timing`: 定期バッチの実行時刻(例: `毎週日曜日 21:30`、`毎日営業終了後 21:00`)またはイベント・状態遷移の契機(例: `executor 完了直後、親検証完了時、reporter 起動前後`)を検証可能な条件として記述します。
|
|
119
142
|
|
|
120
|
-
### 5.
|
|
143
|
+
### 5.5. 受け渡し方法(transport)
|
|
121
144
|
|
|
122
|
-
|
|
145
|
+
1. `method`(必須): `ローカルファイルシステム`、`共有ストレージ`、`SFTP`、`HTTPS`、`S3`、`その他` から受け渡し手段を指定します。
|
|
146
|
+
2. `endpoint`(必須): 格納ディレクトリパス、接続先ホスト・パス、またはアップロード先 URL を記述します。認証情報や秘密鍵の値は記載しません。
|
|
147
|
+
3. `frequency`(必須): 連携頻度(`都度`、`タスク実行ごとに都度`、`日次`、`週次` 等)を記述します。
|
|
148
|
+
4. `atomic_write`(任意): ローカルファイルシステムや共有ストレージ等で書き込み途中の読み取り・競合を防ぐ必要がある場合、一時ファイル(`.tmp` 等)への書き込みとアトミック置換(`renameSync` 等)の方針を明記します。
|
|
123
149
|
|
|
124
|
-
|
|
125
|
-
- `header`: true/false
|
|
126
|
-
- `quote`: `"` など(任意)
|
|
127
|
-
- `encoding`: `UTF-8` 推奨
|
|
128
|
-
- `line_ending`: `LF` 推奨(必要なら `CRLF`)
|
|
150
|
+
### 5.6. 構造定義と正本参照(schema)
|
|
129
151
|
|
|
130
|
-
|
|
152
|
+
フォーマット別の構文設定と、データ項目の定義または正本参照を記載します。
|
|
131
153
|
|
|
132
|
-
|
|
154
|
+
1. **フォーマット別の構文設定**:
|
|
155
|
+
- `schema.csv` / `schema.tsv`: `delimiter`(区切り文字)、`header`(ヘッダ行の有無, boolean)、`quote`(囲み文字)、`encoding`(原則 `UTF-8`)、`line_ending`(`LF` / `CRLF`)。
|
|
156
|
+
- `schema.json`: `root_type`(`object` / `array`)、`content_type`(`application/json` 等)、`encoding`(`UTF-8`)。
|
|
157
|
+
- `schema.xml`: `root_element`、`namespace`、`encoding`、`xsd_ref`。
|
|
158
|
+
2. **項目定義(外部との合意スキーマを本仕様で直接定める場合)**:
|
|
159
|
+
- `schema.fields` 配列に各フィールドの `name`(必須)、`type`(必須)、`description`(必須)、`required`(必須, boolean)を定義し、必要に応じて `example`、`constraints`(`min`、`max`、`maxLength`、`pattern` 等)、`mapping`(`csv.column`、`json.pointer` 等)を記載します。
|
|
160
|
+
3. **正本スキーマ・型定義参照(既存の schema やコード型定義が正本の場合)**:
|
|
161
|
+
- `schema.references`(または `schema.schema_ref`、`files[].schema_ref`)に正本ファイルパスを記載し、各ファイルの契約上の必須項目は `files[].required_fields` で宣言します。正本に定義済みの全フィールド構造を YAML 内へ重複転記しません。
|
|
133
162
|
|
|
134
|
-
|
|
135
|
-
- `content_type`: `application/json`
|
|
136
|
-
- `json_schema`: 任意(厳密に縛る場合)
|
|
163
|
+
### 5.7. 失敗時の扱いとエラーハンドリング(`error_handling`)
|
|
137
164
|
|
|
138
|
-
|
|
165
|
+
以下の 3 区分をすべて定義します。単一ファイル契約では各区分の直下に `action` を記述し、複数ファイル(`files`)や事象ごとに振る舞いが異なる場合は対象別のサブキー(例: `evidence_json`、`pipeline_state_json`、`io_error`)を切って `action` を記述します。
|
|
139
166
|
|
|
140
|
-
|
|
167
|
+
1. `missing`(ファイル欠落時): 予定時刻または所定段階にファイルが存在しない場合の検知条件、フォールバック継続か中断(`blocked` 等)かの判断、新規初期化や手動発注・再実行案内などの回復手順を規定します。
|
|
168
|
+
2. `malformed`(フォーマット・スキーマ不正時): 構文解析エラー、必須項目欠落、型不正、サイズ上限超過等を検知した場合の扱い(処理停止または空フォールバック、破損ファイルの退避・保持、自動再試行の有無、引き継ぎ先)を規定します。
|
|
169
|
+
3. `transport_failure`(伝送・保存失敗時): ネットワーク遮断、接続タイムアウト、ディスク容量不足、権限不足、ロック競合等の I/O 失敗時の再試行方針(間隔・上限回数)または即時異常停止(終了コード等)と復旧手順を規定します。
|
|
141
170
|
|
|
142
|
-
|
|
143
|
-
- `namespace`: 任意
|
|
144
|
-
- `content_type`: `application/xml`
|
|
145
|
-
- `xsd_ref`: 任意(厳密に縛る場合。ファイル名やURLを記載)
|
|
171
|
+
## 6. 記述ガイド
|
|
146
172
|
|
|
147
|
-
|
|
173
|
+
### 6.1. ファイル基本情報と責務境界の判断基準
|
|
148
174
|
|
|
149
|
-
|
|
150
|
-
|
|
151
|
-
|
|
152
|
-
type: file
|
|
153
|
-
status: draft
|
|
154
|
-
based_on: []
|
|
175
|
+
1. **判断基準**: 誰がいつファイルを書き(`source` / `writer`)、誰が何のために読み(`target` / `reader`)、どこにどの名前で置かれるか(`location` / `naming_rule`)が、実装コードを見ずに特定できること。
|
|
176
|
+
2. **単一ファイルと複数ファイルの使い分け**: 1 つのファイルだけで完結する連携は `file` を使い、実行エビデンス(`evidence.json`)とパイプライン状態(`pipeline-state.json`)のように同一実行単位で協調動作するファイル群は `files` 配列で定義し、ファイルごとに `writer`・`reader`・`required_fields` を明記します。
|
|
177
|
+
3. **仮置き・前提条件の明記**: 通信環境や運用体制に関する前提条件、または未確定の技術判断がある場合は、YAML コメントで `# _ASSUMPTION_:` や `# _UNDECIDED_:` を付記し、何が決まれば解消するかを書きます。
|
|
155
178
|
|
|
156
|
-
|
|
157
|
-
name: orders.csv
|
|
158
|
-
naming_rule: orders_YYYYMMDD.csv
|
|
159
|
-
description: 発注データ(仕入先へ送付)
|
|
179
|
+
### 6.2. 受け渡し条件と構造定義の判断基準
|
|
160
180
|
|
|
161
|
-
|
|
162
|
-
|
|
181
|
+
1. **判断基準**: 下流の実装者がパーサ・バリデータ・ファイル配置処理を実装でき、テスト担当が正常データと境界値・異常データのテストケースを導出できること。
|
|
182
|
+
2. **インライン定義と正本参照の選択**:
|
|
183
|
+
- 外部取引先(問屋や外部システム)との CSV / JSON 連携など、リポジトリ内に別途スキーマ定義が存在しない場合は、`schema.fields` に型・必須性・制約(`constraints`)・マッピング(`mapping`)を具体的に記述します。
|
|
184
|
+
- 同一システム内のランナーとエージェント間の契約など、TypeScript 型定義や JSON Schema が正本として存在する場合は、`files[].schema_ref` および `schema.references` で正本パスを指し、`files[].required_fields` に必須キーを列挙して二重管理を防ぎます。
|
|
163
185
|
|
|
164
|
-
|
|
165
|
-
format: CSV
|
|
186
|
+
### 6.3. 失敗時の扱いの判断基準
|
|
166
187
|
|
|
167
|
-
|
|
188
|
+
1. **判断基準**: `missing`・`malformed`・`transport_failure` のそれぞれについて、「処理を継続するか停止するか」「既存の作業成果や破損ファイルを保持するか退避するか」「自動再試行するか人間へ引き継ぐか」が明確に判別できること。
|
|
189
|
+
2. **再実行時の安全性**: 再試行や `--resume` により二重処理や成果物の消失が起きないよう、状態ファイル欠落時とエビデンス欠落時の扱いの違い(例: 初回は新規生成、`--resume` 時はエラー停止)を区別して記述します。
|
|
168
190
|
|
|
169
|
-
|
|
170
|
-
|
|
171
|
-
|
|
172
|
-
|
|
173
|
-
|
|
174
|
-
|
|
175
|
-
|
|
176
|
-
|
|
177
|
-
|
|
178
|
-
|
|
179
|
-
|
|
180
|
-
|
|
181
|
-
|
|
182
|
-
|
|
183
|
-
|
|
184
|
-
|
|
185
|
-
|
|
186
|
-
|
|
187
|
-
|
|
188
|
-
|
|
189
|
-
|
|
190
|
-
|
|
191
|
-
|
|
192
|
-
|
|
193
|
-
type: datetime
|
|
194
|
-
description: 発注日時(RFC3339)
|
|
195
|
-
required: true
|
|
196
|
-
example: 2025-12-24T12:34:56Z
|
|
197
|
-
mapping:
|
|
198
|
-
csv:
|
|
199
|
-
column: ordered_at
|
|
200
|
-
|
|
201
|
-
- name: total_amount
|
|
202
|
-
type: integer
|
|
203
|
-
description: 合計金額
|
|
204
|
-
required: true
|
|
205
|
-
example: 1200
|
|
206
|
-
constraints:
|
|
207
|
-
min: 0
|
|
208
|
-
mapping:
|
|
209
|
-
csv:
|
|
210
|
-
column: total_amount
|
|
191
|
+
### 6.4. 良い例と悪い例
|
|
192
|
+
|
|
193
|
+
#### 6.4.1. 良い例: 正本参照・書き手と読み手・異常時動作の明確化
|
|
194
|
+
|
|
195
|
+
書き手と読み手、正本参照と必須項目、異常時の動作に絞った抜粋です。
|
|
196
|
+
|
|
197
|
+
```yaml
|
|
198
|
+
files:
|
|
199
|
+
- name: evidence.json
|
|
200
|
+
writer: SpecDojo runner(agent の stdout から抽出・正規化して書き込み)
|
|
201
|
+
reader: SpecDojo runner(検証合否判定、reporter への入力、result.md 反映)
|
|
202
|
+
schema_ref: src/exec/evidence.ts#ExecEvidence
|
|
203
|
+
required_fields: [schema_version, task_id, run_id, stage, changes, validations, final_message]
|
|
204
|
+
|
|
205
|
+
error_handling:
|
|
206
|
+
missing:
|
|
207
|
+
evidence_json:
|
|
208
|
+
action: executor 終了時に未生成の場合は構造化報告を空としてフォールバックし、終了コードと親検証で判定する
|
|
209
|
+
malformed:
|
|
210
|
+
evidence_json:
|
|
211
|
+
action: 解析失敗ログを出力した上で構造化報告を空として扱い、成果物の変更内容は保持して手動確認へ引き継ぐ
|
|
212
|
+
transport_failure:
|
|
213
|
+
io_error:
|
|
214
|
+
action: ディスク容量不足や権限エラー時は標準エラー出力に理由を出力し、即時異常停止(exit code 1)させる
|
|
211
215
|
```
|
|
212
216
|
|
|
213
|
-
|
|
217
|
+
#### 6.4.2. 悪い例: メタ情報不整合・実装詳細の混入・曖昧な異常時処理
|
|
214
218
|
|
|
215
219
|
```yaml
|
|
216
220
|
x-spec-meta:
|
|
217
|
-
id: ifx-file-
|
|
218
|
-
type: file
|
|
219
|
-
|
|
220
|
-
|
|
221
|
+
id: ifx-file-bad-example
|
|
222
|
+
type: file # 禁止: deliverable_type と不整合(api 固定)
|
|
223
|
+
title: 連携仕様
|
|
224
|
+
rulebook: specdojo:ifx-file-rulebook
|
|
221
225
|
|
|
226
|
+
# 禁止: source, target, timing, direction が欠落している
|
|
222
227
|
file:
|
|
223
|
-
name:
|
|
224
|
-
naming_rule
|
|
225
|
-
|
|
226
|
-
|
|
227
|
-
source: 在庫(コンテナ)
|
|
228
|
-
target: 物流システム
|
|
229
|
-
|
|
230
|
-
direction: source_to_target
|
|
231
|
-
format: JSON
|
|
232
|
-
|
|
233
|
-
timing: 日次集計後
|
|
228
|
+
name: data.json
|
|
229
|
+
# 禁止: naming_rule, location, description が欠落している
|
|
230
|
+
query: SELECT * FROM orders WHERE status = 'DONE' # 禁止: 内部 SQL の記述
|
|
231
|
+
handler_class: com.example.OrderHandlerImpl # 禁止: 内部実装クラス名の記述
|
|
234
232
|
|
|
235
233
|
transport:
|
|
236
|
-
method:
|
|
237
|
-
endpoint: https://logistics.example.com/upload
|
|
238
|
-
frequency: 日次 02:00
|
|
239
|
-
|
|
240
|
-
schema:
|
|
241
|
-
json:
|
|
242
|
-
root_type: object
|
|
243
|
-
content_type: application/json
|
|
244
|
-
|
|
245
|
-
fields:
|
|
246
|
-
- name: snapshot_date
|
|
247
|
-
type: date
|
|
248
|
-
required: true
|
|
249
|
-
example: 2025-12-24
|
|
250
|
-
mapping:
|
|
251
|
-
json:
|
|
252
|
-
pointer: /snapshot_date
|
|
253
|
-
|
|
254
|
-
- name: items
|
|
255
|
-
type: string
|
|
256
|
-
description: 明細配列(厳密に縛る場合は json_schema を使用)
|
|
257
|
-
required: true
|
|
258
|
-
mapping:
|
|
259
|
-
json:
|
|
260
|
-
pointer: /items
|
|
261
|
-
```
|
|
262
|
-
|
|
263
|
-
## 8. サンプル(XML)
|
|
234
|
+
method: 適切に転送する # 禁止: 手段・endpoint・frequency が不明
|
|
264
235
|
|
|
265
|
-
|
|
266
|
-
|
|
267
|
-
|
|
268
|
-
type: file
|
|
269
|
-
status: draft
|
|
270
|
-
based_on: []
|
|
236
|
+
error_handling:
|
|
237
|
+
action: 問題ないように処理する # 禁止: missing / malformed / transport_failure の区分と具体的な回復手順がない
|
|
238
|
+
```
|
|
271
239
|
|
|
272
|
-
|
|
273
|
-
name: payment_result.xml
|
|
274
|
-
naming_rule: payment_result_YYYYMMDDHHmmss.xml
|
|
275
|
-
description: 決済結果(外部→当社)
|
|
240
|
+
## 7. 禁止事項
|
|
276
241
|
|
|
277
|
-
|
|
278
|
-
|
|
242
|
+
| 禁止する記述 | 理由 |
|
|
243
|
+
| ------------------------------------------------------------------------------- | -------------------------------------------------------------------------- |
|
|
244
|
+
| `x-spec-meta.type` に `api` 以外の値(`file` 等)を指定すること | rulebook の `deliverable_type: api` およびスキーマ検証との整合が崩れるため |
|
|
245
|
+
| `source`、`target`、`timing`、`direction`、または `file` 必須項目の省略 | 責任境界、連携契機、配置場所・命名規則が特定できず実装・検証不能になるため |
|
|
246
|
+
| `error_handling` の 3 区分(`missing` / `malformed` / `transport_failure`)省略 | 異常発生時の停止・継続判断や破損ファイルの退避・復旧手順が定まらないため |
|
|
247
|
+
| 正本スキーマや型定義の全文コピー&ペーストによる再掲 | 正本との二重管理になり、フィールド変更時に仕様間の不整合を引き起こすため |
|
|
248
|
+
| DB 物理テーブル名、SQL 文、内部クラス名などの内部実装詳細の記載 | 外部インターフェース契約と内部設計の責務境界が混同されるため |
|
|
249
|
+
| 接続パスワード、秘密鍵、API トークン、個人情報の実データの直接記載 | セキュリティおよび機密保護上のリスクを防ぐため |
|
|
250
|
+
| 「適切に処理する」「問題ないようにする」等の検証不能な曖昧表現 | 実装の分岐および合否判定の基準として機能しないため |
|
|
279
251
|
|
|
280
|
-
|
|
281
|
-
format: XML
|
|
252
|
+
## 8. 運用ルール
|
|
282
253
|
|
|
283
|
-
|
|
254
|
+
### 8.1. 成果物の検証手順
|
|
284
255
|
|
|
285
|
-
|
|
286
|
-
|
|
287
|
-
endpoint: /shared/payment/result
|
|
288
|
-
frequency: 都度
|
|
289
|
-
|
|
290
|
-
schema:
|
|
291
|
-
xml:
|
|
292
|
-
root_element: PaymentResult
|
|
293
|
-
namespace: TBD
|
|
294
|
-
content_type: application/xml
|
|
295
|
-
xsd_ref: TBD
|
|
296
|
-
|
|
297
|
-
fields:
|
|
298
|
-
- name: payment_id
|
|
299
|
-
type: string
|
|
300
|
-
required: true
|
|
301
|
-
mapping:
|
|
302
|
-
xml:
|
|
303
|
-
xpath: /PaymentResult/PaymentId
|
|
304
|
-
|
|
305
|
-
- name: status
|
|
306
|
-
type: enum
|
|
307
|
-
required: true
|
|
308
|
-
enum: [PENDING, PAID, FAILED]
|
|
309
|
-
mapping:
|
|
310
|
-
xml:
|
|
311
|
-
xpath: /PaymentResult/Status
|
|
312
|
-
```
|
|
256
|
+
1. **一覧・正本との照合**: `ifx-index` の `spec_ref` と `x-spec-meta.id` が一致し、`schema_ref` / `references` の参照先が実在して、`files[].required_fields` が正本の必須項目と矛盾しないことを確かめます。欠落や不一致が 1 件でもあれば不合格とし、正本に合わせて直します。
|
|
257
|
+
2. **異常系の導出**: `error_handling` の 3 区分(`missing`、`malformed`、`transport_failure`)と `required_fields` から正常系・異常系の確認ケースを導出し、各ケースで継続・停止、ファイルの保持・退避、再試行・引き継ぎの期待結果が一意に決まることを確かめます。
|