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,375 +3,109 @@ specdojo:
|
|
|
3
3
|
id: specdojo:sysd-critical-flows-rulebook
|
|
4
4
|
type: rulebook
|
|
5
5
|
deliverable_type: architecture
|
|
6
|
-
status:
|
|
6
|
+
status: ready
|
|
7
|
+
recipe: specdojo:sysd-critical-flows-recipe
|
|
7
8
|
sample: specdojo:sysd-critical-flows-sample
|
|
9
|
+
template: specdojo:sysd-critical-flows-template
|
|
8
10
|
---
|
|
9
11
|
|
|
10
12
|
# システム設計 重要フロー 作成ルール
|
|
11
13
|
|
|
12
|
-
System Design Critical Flows
|
|
14
|
+
System Design Critical Flows Documentation Rules
|
|
13
15
|
|
|
14
|
-
|
|
15
|
-
|
|
16
|
-
「読まないと事故る」重要フローだけを最小限で記述する **System Design Critical Flows (SYSD-CF)** の記述ルールを定義する。
|
|
17
|
-
|
|
18
|
-
SYSD Critical Flows は詳細設計書ではない。**実装・テスト・運用の共通理解が必要な“難所”** に限定して可視化する。
|
|
16
|
+
事故や仕様誤解につながる処理の境界・永続化点・再実行性・失敗時挙動と、実装・テスト・運用の正本への導線を定める。
|
|
19
17
|
|
|
20
18
|
## 1. 全体方針
|
|
21
19
|
|
|
22
|
-
|
|
23
|
-
|
|
24
|
-
-
|
|
25
|
-
-
|
|
26
|
-
|
|
27
|
-
- テスト(ITS/ETS/STC)および運用(OPD/OPR)へ **観点と導線** を提供する
|
|
28
|
-
|
|
29
|
-
基本方針:
|
|
30
|
-
|
|
31
|
-
- 重要フローは **最大5件** を原則とし、追加時は統合・削減で総数を維持する
|
|
32
|
-
- 詳細手順の逐語化は行わず、境界・永続化点・整合性・冪等・失敗時・観測性を明示する
|
|
33
|
-
- API/イベント/DB/ジョブ/設定の詳細はコード・定義ファイルをSSOTとし、SYSD-CFは導線を担う
|
|
20
|
+
- 一覧と詳細は同じフロー ID の集合で、例外なく最大5件とする。超過時は統合・置換・対象外を先に判断し、件数と選定理由を確認する。
|
|
21
|
+
- 順序・排他・重複・部分成功・外部障害・人間承認を誤る結果を、通常処理の網羅より優先する。
|
|
22
|
+
- 値・構文・データ構造は実装・schema・リファレンスを正本とし、一意な参照と確認条件だけを置く。
|
|
23
|
+
- 設計要求・確認済み動作・未確認の適合を区別し、未決の業務判断・運用条件を完成済みと扱わない。
|
|
24
|
+
- **共通の運用**: 役割の割り当ては適用先のメンバー定義に、`status` の昇格と承認、改訂と廃止、未決事項の登録簿への引き継ぎは [[specdojo:document-metadata-standard|ドキュメントメタ情報標準]] に従う。文書の整形・lint はリポジトリの検証で扱い、業務の受入確認に含めない。
|
|
34
25
|
|
|
35
26
|
## 2. 位置づけと用語定義
|
|
36
27
|
|
|
37
|
-
|
|
28
|
+
| 情報 | 本書との責務境界 |
|
|
29
|
+
| -------------------------- | ------------------------------------------------------------ |
|
|
30
|
+
| システム設計索引 | 実装・設定・定義ファイルの所在と共通条件の正本 |
|
|
31
|
+
| 業務フロー・状態遷移仕様 | 対象者・起動条件・状態用語の正本 |
|
|
32
|
+
| テスト・運用手順・判断記録 | 検証・復旧操作・採否の正本。フローとの対応と不足の影響を示す |
|
|
38
33
|
|
|
39
|
-
-
|
|
40
|
-
-
|
|
41
|
-
-
|
|
42
|
-
- `opd-*` / `opr-*`:失敗時運用・監視・手順の実行ルール
|
|
43
|
-
- `dec-*`:設計判断の背景・採否理由
|
|
44
|
-
|
|
45
|
-
### 2.2. 用語定義
|
|
46
|
-
|
|
47
|
-
| 用語 | 定義 |
|
|
48
|
-
| ---------- | -------------------------------------------------------- |
|
|
49
|
-
| 重要フロー | 実装・運用事故に直結しやすく、共通理解が必須な処理フロー |
|
|
50
|
-
|
|
51
|
-
| 永続化点 | commit / outbox / enqueue など、状態確定や配送起点となる地点 |
|
|
52
|
-
| 補償 | 一部成功後の不整合を是正するための戻し・取り消し・代替処理 |
|
|
34
|
+
- **永続化点**: 中断後も状態確定の証拠となる保存地点。要求送信だけの地点と区別する。
|
|
35
|
+
- **再実行性**: 繰返し操作の結果と実行を許す条件。冪等を保証しない経路も示す。
|
|
36
|
+
- **補償**: 部分成功後の取消・戻し・代替処理による整合回復。履歴削除と区別する。
|
|
53
37
|
|
|
54
38
|
## 3. ファイル命名・ID規則
|
|
55
39
|
|
|
56
|
-
-
|
|
57
|
-
-
|
|
58
|
-
-
|
|
40
|
+
- ファイルは `sysd-critical-flows.md` を基準に、対象のシステム設計文書群へ置く。
|
|
41
|
+
- 文書 ID は適用先の名前空間に従う。フロー ID は `scf-001` 形式で一意とし、廃止 ID を再利用しない。
|
|
42
|
+
- フロー名は成功後の結果を表す。未決事項・検証条件にも文書内で一意な ID を付け、フロー ID と結ぶ。
|
|
59
43
|
|
|
60
44
|
## 4. 推奨 Frontmatter 項目
|
|
61
45
|
|
|
62
|
-
|
|
63
|
-
|
|
64
|
-
Frontmatter は共通スキーマに従います(参照: [docs/specdojo/schemas/v1/deliverable-frontmatter.schema.yaml](../../../specdojo/schemas/v1/deliverable-frontmatter.schema.yaml) / [document-metadata-standard.md](../standards/document-metadata-standard.md))。
|
|
65
|
-
|
|
66
|
-
| 項目 | 説明 | 必須 |
|
|
46
|
+
共通の形式・必須キー・型は [[specdojo:document-metadata-standard|ドキュメントメタ情報標準]] を正本とする。
|
|
67
47
|
|
|
68
|
-
|
|
69
|
-
|
|
70
|
-
|
|
71
|
-
| title | システム設計: 重要フロー | ○ |
|
|
72
|
-
| status | `draft` / `ready` / `deprecated` | ○ |
|
|
73
|
-
| based_on | 根拠となる仕様ID(ID配列。未指定は `[]` 可) | 任意 |
|
|
74
|
-
| supersedes | 置き換え関係(ID配列。未指定は `[]` 可) | 任意 |
|
|
48
|
+
- `type` は `architecture`、`rulebook` は本規約の ID とする。
|
|
49
|
+
- `part_of` は所属するシステム設計索引を示す。
|
|
50
|
+
- `based_on` は判断に用いた依存範囲内の根拠に限り、参照ハブの先を一律に転記しない。
|
|
75
51
|
|
|
76
|
-
|
|
52
|
+
## 5. 本文要件
|
|
77
53
|
|
|
78
|
-
|
|
79
|
-
- `based_on` / `supersedes` は ID 配列(未指定は `[]` 可)。
|
|
54
|
+
全章必須。見出し順・表・記入欄は宣言された雛形、意味要件は以下を正本とする。
|
|
80
55
|
|
|
81
|
-
|
|
56
|
+
| 内容 | 目的と満たす条件 |
|
|
57
|
+
| -------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
|
58
|
+
| 概要 | 対象・対象外、最大5件の管理方針、設計索引への接続、公開する情報と除外する情報を示す |
|
|
59
|
+
| 重要フロー一覧 | ID・名称・事故論点に、影響を受ける利用者/運用者、放置時の影響、期待効果、通常処理より優先する理由を対応させる |
|
|
60
|
+
| フロー詳細 | フローごとに目的・トリガー・範囲・主要入出力、図、永続化点、整合性・冪等・再実行、失敗時の保持・補償・再開条件、利用者が確認できる受入条件を示す |
|
|
61
|
+
| 観測性と運用連携 | フローごとの相関キーと追跡範囲、trace の伝搬範囲または非採用理由、監視条件・閾値の正本、実装動作、人間の一次対応とエスカレーション先を分離して示す |
|
|
62
|
+
| 関連ドキュメント導線 | 実装・設定、テスト、運用、判断記録への一意な導線と、契約・schema・生成物・CLI・保存済み記録の互換性への変更影響を示す。未決事項は論点・依存・受入や運用への影響・当面の扱い・解消条件を示す |
|
|
82
63
|
|
|
83
|
-
|
|
64
|
+
図はシステム内外・サービス/プロセス・保存先の境界、主要識別子、同期・非同期と矢印の意味を示し、要求受付と業務完了を分ける。分散トレースは必須とせず、プロセス間の相関方法を示す。
|
|
84
65
|
|
|
85
|
-
|
|
86
|
-
| ---- | ------------------------------------------- | ---- |
|
|
87
|
-
| 1 | 概要(対象・運用方針) | ○ |
|
|
88
|
-
| 2 | 重要フロー一覧(最大5件) | ○ |
|
|
89
|
-
| 3 | フロー詳細(IDごと) | ○ |
|
|
90
|
-
| 4 | 観測性と運用連携 | ○ |
|
|
91
|
-
| 5 | 関連ドキュメント導線(SDI/テスト/運用/DEC) | ○ |
|
|
92
|
-
|
|
93
|
-
`3. フロー詳細` は、フローIDごとに以下の構成で記述する。
|
|
94
|
-
|
|
95
|
-
- ヘッダ:ID、フロー名、目的、トリガー、範囲(含む/含まない)
|
|
96
|
-
- フロー概要:図(推奨Mermaid)または箇条書き、登場要素、永続化点
|
|
97
|
-
- 整合性・冪等・再実行:整合性モデル、冪等キー、重複時挙動、再実行方針
|
|
98
|
-
- 失敗時:失敗分類、リトライ方針、補償/ロールバック、影響・通知
|
|
99
|
-
- 観測性:trace_id引き回し、必須ログ項目、監査ログ要件
|
|
100
|
-
- 参照:SDI、外部I/F、NFR、OPD/OPR、DEC、ITS/ETS/STC
|
|
101
|
-
|
|
102
|
-
補足:
|
|
103
|
-
|
|
104
|
-
- フロー数が5件を超える場合は、分割前に統合・重複排除を検討する。
|
|
66
|
+
テスト参照は実在するパスまたはテスト ID とし、受入条件に実行方法・対象条件・期待結果・失敗判定を対応させる。所在・網羅性・実行結果を区別し、不足は未決事項に接続する。内部結合は ITC(`itc-` 系)、外部結合は ETC(`etc-` 系)とする。
|
|
105
67
|
|
|
106
68
|
## 6. 記述ガイド
|
|
107
69
|
|
|
108
|
-
### 6.1.
|
|
109
|
-
|
|
110
|
-
生成する本文の見出しは **## 1. 概要(対象・運用方針)**
|
|
111
|
-
|
|
112
|
-
- SYSD-CFの適用対象と「最大5件運用」の方針を1〜3段落で明記する。
|
|
113
|
-
- SYSD-CFが詳細実装書ではなく、事故予防のための重要フロー文書であることを明記する。
|
|
114
|
-
- SSOTはコード/定義ファイル側であること(SYSD-CFは導線)を明記する。
|
|
115
|
-
|
|
116
|
-
### 6.2. 重要フロー一覧(最大5件)
|
|
117
|
-
|
|
118
|
-
生成する本文の見出しは **## 2. 重要フロー一覧(最大5件)**
|
|
119
|
-
|
|
120
|
-
- フローID、フロー名、事故論点、優先度、備考を表形式で記載する。
|
|
121
|
-
- 一覧は最大5件までとし、6件目以降は統合・削減の検討結果を反映してから追加する。
|
|
122
|
-
|
|
123
|
-
- 事故論点は「冪等」「非同期整合性」「補償」「外部I/F障害」「再実行性」などで明示する。
|
|
70
|
+
### 6.1. 概要
|
|
124
71
|
|
|
125
|
-
|
|
72
|
+
- 判断基準: 対象の入口・出口と公開範囲が特定できること。
|
|
73
|
+
- 良い例: 「販売要求から受付照合まで。公開版は設計条件だけを含み、顧客別の購入記録は除く」。
|
|
74
|
+
- 悪い例: 「システム全体を安全に運用する」。境界が分からない。
|
|
126
75
|
|
|
127
|
-
|
|
128
|
-
- 非同期(順序・再実行・重複が絡む)
|
|
129
|
-
- 補償が必要(分散トランザクション、取り消し、戻し)
|
|
130
|
-
- 整合性が難しい(最終的整合性、二重書き込み、在庫/金額/残高)
|
|
131
|
-
- 外部I/F障害が業務影響に直結(タイムアウト、リトライ、部分失敗)
|
|
132
|
-
- 監査対象(改ざん/追跡が必要)
|
|
133
|
-
- 性能/可用性のボトルネック候補(ピーク処理、バッチ遅延)
|
|
76
|
+
### 6.2. 重要フロー一覧
|
|
134
77
|
|
|
135
|
-
|
|
78
|
+
- 推奨列は ID、名称、事故論点、対象者、業務影響、期待効果・選定理由。優先度だけでは選定理由にならない。
|
|
79
|
+
- 判断基準: 重複・中断による対象者の損失で、追加候補と既存フローを比較できること。
|
|
80
|
+
- 良い例: 「応答欠落後の再送は二重売上になるため、閲覧より優先する」。
|
|
81
|
+
- 悪い例: 「重要なので High」。他候補より優先する根拠がない。
|
|
136
82
|
|
|
137
|
-
|
|
83
|
+
### 6.3. フロー詳細
|
|
138
84
|
|
|
139
|
-
|
|
140
|
-
|
|
141
|
-
-
|
|
142
|
-
-
|
|
143
|
-
|
|
144
|
-
- 整合性・冪等・再実行:整合性モデル、冪等キー、重複時挙動、再実行方針
|
|
145
|
-
- 失敗時:失敗分類、リトライ方針、補償/ロールバック、影響・通知
|
|
146
|
-
- 観測性:trace_id引き回し、必須ログ項目、監査ログ要件
|
|
147
|
-
- 参照:SDI、外部I/F、NFR、OPD/OPR、DEC、ITS/ETS/STC
|
|
148
|
-
|
|
149
|
-
図の記法(推奨):
|
|
150
|
-
|
|
151
|
-
- Flowchart:境界と流れ(同期/非同期)を表現
|
|
152
|
-
- SequenceDiagram:時系列と呼び出し順(必要時のみ)
|
|
153
|
-
- 概要図の粒度は **C4コンポーネント図レベル相当** とし、実装クラス/メソッド詳細には踏み込まない
|
|
154
|
-
|
|
155
|
-
```mermaid
|
|
156
|
-
|
|
157
|
-
flowchart LR
|
|
158
|
-
UI[UI] -->|POST /sales| API[Sales API]
|
|
159
|
-
API --> SVC[Sales Service]
|
|
160
|
-
SVC -->|commit| DB[(Sales DB)]
|
|
161
|
-
SVC -->|outbox enqueue| OB[(Outbox)]
|
|
162
|
-
OB -->|publish| MQ[(Event Bus)]
|
|
163
|
-
MQ --> INV[Inventory Service]
|
|
164
|
-
INV -->|commit| IDB[(Inventory DB)]
|
|
165
|
-
```
|
|
166
|
-
|
|
167
|
-
図に必ず入れる情報:
|
|
168
|
-
|
|
169
|
-
- 境界(システム内/外、サービス境界)
|
|
170
|
-
- 永続化点(commit/outbox/enqueue)
|
|
171
|
-
- 非同期点(queue/event)
|
|
172
|
-
- 主要識別子(冪等キー、entity_id)
|
|
85
|
+
- 判断基準: 各永続化点で中断後の残存状態・再開条件が一意に定まること。設定依存の上限はキーか一意な設計参照へ結ぶ。
|
|
86
|
+
- 良い例: 「受付後の応答欠落は取引 ID で照合し、未受付と確認するまで再送しない。受入では同一 ID の二回入力が売上一件になることを確認する」。
|
|
87
|
+
- 悪い例: 「失敗なら retry」。受付済み、保存失敗、通信失敗を区別していない。
|
|
88
|
+
- 図の良い例: CLI 内部・端末保存・外部受付を分け、同じ取引 ID で結ぶ。凡例で送信と応答欠落後の照合を区別する。
|
|
89
|
+
- 図の悪い例: 「受付 → 保存 → 完了」。保存主体・識別子・応答欠落時の経路が不明。
|
|
173
90
|
|
|
174
91
|
### 6.4. 観測性と運用連携
|
|
175
92
|
|
|
176
|
-
|
|
177
|
-
|
|
178
|
-
-
|
|
179
|
-
|
|
180
|
-
-
|
|
181
|
-
- 監視条件(アラート閾値)、手動介入条件、OPR手順への導線を明記する。
|
|
182
|
-
- 業務影響の大きい失敗は OPD の停止判断基準に接続する。
|
|
93
|
+
- 判断基準: 検知条件・実装動作・人間の対応・照会先・記録先を分けること。閾値未決を無通知でよいと扱わない。
|
|
94
|
+
- 良い例: 「重複確定一件で自動処理を停止。一次対応者が保持記録を確認して技術照会先へ渡す」。
|
|
95
|
+
- 悪い例: 「runner が担当」。機械を責任者としている。
|
|
96
|
+
- 相関の良い例: 「内部 trace を渡せない外部受付は、取引 ID と受付 ID で CLI・保存控えと照合する」。共通方針は一度だけ記し、フロー別のキー・範囲へ結ぶ。採否未確認なら代替手段と確認条件を示す。
|
|
97
|
+
- 相関の悪い例: 「`trace_id` を記録する」。境界から保存先まで追えるか不明。
|
|
183
98
|
|
|
184
99
|
### 6.5. 関連ドキュメント導線
|
|
185
100
|
|
|
186
|
-
|
|
187
|
-
|
|
188
|
-
-
|
|
189
|
-
- 参照先は「ID」または「リポジトリ相対パス」で一意に辿れる形にする。
|
|
190
|
-
- 分冊が無い場合でも `(本書のみ)` または `(なし)` を明記し、空欄にしない。
|
|
101
|
+
- 判断基準: 正本・検証・未決事項へ辿れ、未作成の手順と確認済みの参照を見分けられること。
|
|
102
|
+
- 良い例: 「V-01 は指定テストで二重反映を fail とする。U-01 の照合手順が未整備なら、受付不明時の自動再送を保留する」。
|
|
103
|
+
- 悪い例: 「テスト、OPR を参照」。所在・成立条件・未整備の影響が不明。
|
|
191
104
|
|
|
192
105
|
## 7. 禁止事項
|
|
193
106
|
|
|
194
|
-
|
|
195
|
-
|
|
196
|
-
|
|
197
|
-
|
|
198
|
-
|
|
199
|
-
| 冪等/整合性/失敗時の記述を省略する | SYSD-CFの主目的を満たせないため |
|
|
200
|
-
| SDI・運用・テスト・DECへの導線を置かない | 実行・検証・運用へ接続できないため |
|
|
201
|
-
| 重要フローを6件以上に増やす(無整理の追加) | 文書が肥大化し、合意形成が困難になるため |
|
|
202
|
-
|
|
203
|
-
## 8. サンプル
|
|
204
|
-
|
|
205
|
-
注:以下はルール文書内の例示です。生成する `sysd-critical-flows` では `## 1...` から始まります。
|
|
206
|
-
|
|
207
|
-
```yaml
|
|
208
|
-
|
|
209
|
-
---
|
|
210
|
-
id: sysd-critical-flows
|
|
211
|
-
type: architecture
|
|
212
|
-
title: システム設計: 重要フロー
|
|
213
|
-
status: draft
|
|
214
|
-
based_on: []
|
|
215
|
-
supersedes: []
|
|
216
|
-
---
|
|
217
|
-
```
|
|
218
|
-
|
|
219
|
-
### 8.1. 概要(対象・運用方針)
|
|
220
|
-
|
|
221
|
-
本書は、事故影響の大きい重要フローを最大5件まで整理し、
|
|
222
|
-
設計・テスト・運用が同じ前提で判断できる状態を作る。
|
|
223
|
-
|
|
224
|
-
### 8.2. 重要フロー一覧(最大5件)
|
|
225
|
-
|
|
226
|
-
| フローID | フロー名 | 事故論点 | 優先度 | 備考 |
|
|
227
|
-
| -------- | ------------------------------ | -------------------------------------- | ------ | ---------- |
|
|
228
|
-
| scf-001 | 売上確定→在庫更新→発注候補生成 | 非同期整合性 / 冪等 | 高 | outbox採用 |
|
|
229
|
-
| scf-002 | 外部決済作成 | タイムアウト / リトライ / 二重課金防止 | 高 | 補償あり |
|
|
230
|
-
| scf-003 | バッチ再実行(売上集計) | 再実行性 / run_id / 重複排除 | 中 | 日次ジョブ |
|
|
231
|
-
|
|
232
|
-
### 8.3. フロー詳細(IDごと)
|
|
233
|
-
|
|
234
|
-
#### 8.3.1. scf-001: 売上確定→在庫更新→発注候補生成(非同期)
|
|
235
|
-
|
|
236
|
-
- **目的**:売上確定を起点に在庫を更新し、在庫不足時に発注候補を生成する
|
|
237
|
-
- **トリガー**:`POST /sales`(内部API)
|
|
238
|
-
- **範囲**:売上確定、在庫更新イベント発行、発注候補生成(外部仕入先送信は別フロー)
|
|
239
|
-
|
|
240
|
-
##### 8.3.1.1. フロー概要
|
|
241
|
-
|
|
242
|
-
```mermaid
|
|
243
|
-
flowchart LR
|
|
244
|
-
UI[UI] -->|POST /sales| API[Sales API]
|
|
245
|
-
API --> SVC[Sales Service]
|
|
246
|
-
SVC -->|commit| DB[(Sales DB)]
|
|
247
|
-
SVC -->|outbox enqueue| OB[(Outbox)]
|
|
248
|
-
OB -->|publish| MQ[(Event Bus)]
|
|
249
|
-
MQ --> INV[Inventory Service]
|
|
250
|
-
INV -->|commit| IDB[(Inventory DB)]
|
|
251
|
-
```
|
|
252
|
-
|
|
253
|
-
##### 8.3.1.2. 整合性・冪等・再実行
|
|
254
|
-
|
|
255
|
-
- 整合性:売上確定は同期で確定、在庫更新はイベントで最終的整合性
|
|
256
|
-
- 冪等キー:`sale_id`
|
|
257
|
-
- 重複時:同一 `sale_id` は二重計上しない(既処理判定)
|
|
258
|
-
- 再実行:イベントはリプレイ可能、`event_id` で重複排除
|
|
259
|
-
|
|
260
|
-
##### 8.3.1.3. 失敗時
|
|
261
|
-
|
|
262
|
-
- イベント発行失敗:outbox再送(指数バックオフ、最大5回)
|
|
263
|
-
- 在庫更新失敗:メッセージをDLQへ退避し、Ops通知後に手動リプレイ
|
|
264
|
-
|
|
265
|
-
##### 8.3.1.4. 観測性
|
|
266
|
-
|
|
267
|
-
- trace_id を API→イベント→在庫更新まで継承
|
|
268
|
-
- 必須ログ:`flow_id`, `sale_id`, `event_id`, `result`, `retry_count`
|
|
269
|
-
- 監査:売上確定は who/when/amount/before/after を記録
|
|
270
|
-
|
|
271
|
-
##### 8.3.1.5. 参照
|
|
272
|
-
|
|
273
|
-
- SDI:`api/openapi.yaml`、`api/asyncapi.yaml`、`db/migrations/*`
|
|
274
|
-
- テスト:ITC(内部結合)、STC(E2E)
|
|
275
|
-
- 運用:OPD(監視/アラート)、OPR(DLQ対応)
|
|
276
|
-
- DEC:outbox採用理由
|
|
277
|
-
|
|
278
|
-
#### 8.3.2. scf-002: 外部決済作成(タイムアウト/リトライ/二重課金防止)
|
|
279
|
-
|
|
280
|
-
- **目的**:決済要求の成功率を担保しつつ、二重課金を防止する
|
|
281
|
-
- **トリガー**:`POST /payments`
|
|
282
|
-
- **範囲**:決済要求送信、結果確定、失敗時補償(返金)
|
|
283
|
-
|
|
284
|
-
##### 8.3.2.1. フロー概要
|
|
285
|
-
|
|
286
|
-
```mermaid
|
|
287
|
-
flowchart LR
|
|
288
|
-
UI[Client] -->|POST /payments| API[Payment API]
|
|
289
|
-
API --> APP[Payment Service]
|
|
290
|
-
APP -->|idempotency check| IDEM[(Idempotency Store)]
|
|
291
|
-
APP -->|request| PSP[External PSP]
|
|
292
|
-
PSP -->|result webhook| API
|
|
293
|
-
API -->|commit| PDB[(Payment DB)]
|
|
294
|
-
APP -->|on partial failure| CQ[(Compensation Queue)]
|
|
295
|
-
```
|
|
296
|
-
|
|
297
|
-
##### 8.3.2.2. 整合性・冪等・再実行
|
|
298
|
-
|
|
299
|
-
- 整合性:外部確定前は `pending`、確定通知で `confirmed` へ遷移
|
|
300
|
-
- 冪等キー:`payment_request_id`
|
|
301
|
-
- 重複時:同一キーは既存決済結果を返却し、新規作成しない
|
|
302
|
-
- 再実行:タイムアウト時のみ最大3回リトライ(指数バックオフ)
|
|
303
|
-
|
|
304
|
-
##### 8.3.2.3. 失敗時
|
|
305
|
-
|
|
306
|
-
- 3回失敗で `manual_review` へ遷移
|
|
307
|
-
- 部分失敗(外部成功/内部失敗)は補償キューへ投入し、返金または再同期
|
|
308
|
-
|
|
309
|
-
##### 8.3.2.4. 観測性
|
|
310
|
-
|
|
311
|
-
- 必須ログ:`flow_id`, `payment_request_id`, `provider_tx_id`, `result`, `error_code`
|
|
312
|
-
- アラート条件:外部失敗率 > 5% / 5分
|
|
313
|
-
|
|
314
|
-
##### 8.3.2.5. 参照
|
|
315
|
-
|
|
316
|
-
- SDI:外部I/F仕様、決済API仕様
|
|
317
|
-
- テスト:ETC(外部I/F障害系)、STC(決済E2E)
|
|
318
|
-
- 運用:OPR(障害一次対応)、OPD(停止判断基準)
|
|
319
|
-
- DEC:補償方式(返金優先)
|
|
320
|
-
|
|
321
|
-
#### 8.3.3. scf-003: 売上集計バッチ再実行(run_id単位)
|
|
322
|
-
|
|
323
|
-
- **目的**:集計失敗時に重複計上なく安全に再実行する
|
|
324
|
-
- **トリガー**:日次スケジュール(`02:00 JST`)
|
|
325
|
-
- **範囲**:集計ジョブ実行、結果反映、失敗時再実行
|
|
326
|
-
|
|
327
|
-
##### 8.3.3.1. フロー概要
|
|
328
|
-
|
|
329
|
-
```mermaid
|
|
330
|
-
flowchart LR
|
|
331
|
-
SCH[Scheduler] -->|daily 02:00| JOB[Aggregation Job]
|
|
332
|
-
JOB -->|read| SRC[(Sales Source)]
|
|
333
|
-
JOB -->|calculate| TMP[(Result by run_id)]
|
|
334
|
-
TMP -->|validate| VAL{valid?}
|
|
335
|
-
VAL -->|yes| REP[(Aggregated Report)]
|
|
336
|
-
VAL -->|no| INV[(invalid mark)]
|
|
337
|
-
JOB -->|notify on failure| OPS[Ops Alert]
|
|
338
|
-
```
|
|
339
|
-
|
|
340
|
-
##### 8.3.3.2. 整合性・冪等・再実行
|
|
341
|
-
|
|
342
|
-
- 整合性:`run_id` 単位で結果を分離し、最新成功runのみ採用
|
|
343
|
-
- 冪等キー:`aggregation_date + run_id`
|
|
344
|
-
- 再実行上限:自動1回、以降はOps承認で手動再実行
|
|
345
|
-
|
|
346
|
-
##### 8.3.3.3. 失敗時
|
|
347
|
-
|
|
348
|
-
- 失敗時は部分結果を `invalid` マークし採用対象から除外
|
|
349
|
-
- 2回連続失敗でP2アラートを発報し、OPRへエスカレーション
|
|
350
|
-
|
|
351
|
-
##### 8.3.3.4. 観測性
|
|
352
|
-
|
|
353
|
-
- 必須ログ:`flow_id`, `job_name`, `run_id`, `input_count`, `output_count`, `result`
|
|
354
|
-
|
|
355
|
-
##### 8.3.3.5. 参照
|
|
356
|
-
|
|
357
|
-
- SDI:ジョブ定義、DB migration
|
|
358
|
-
- テスト:ITC(再実行性)、STC(月次締め影響)
|
|
359
|
-
- 運用:OPR(バッチ再実行手順)、OPD(SLA)
|
|
360
|
-
|
|
361
|
-
### 8.4. 観測性と運用連携
|
|
362
|
-
|
|
363
|
-
| 項目 | ルール | 監視/運用連携 |
|
|
364
|
-
| -------- | ------------------------------------------------------------ | -------------------------------------- |
|
|
365
|
-
| trace_id | API入口で採番し、イベント・ジョブまで必ず伝搬 | 監査調査時は trace_id を起点に横断追跡 |
|
|
366
|
-
| 必須ログ | `flow_id`, `request_id`, `entity_id`, `result`, `error_code` | 欠落時は開発品質アラート |
|
|
367
|
-
| 失敗通知 | P1/P2相当は即時通知、P3は定時集約可 | OPR の一次対応手順へ接続 |
|
|
368
|
-
| 手動介入 | DLQ滞留、再実行上限超過、補償失敗時に介入 | OPD の停止判断基準に従う |
|
|
369
|
-
|
|
370
|
-
### 8.5. 関連ドキュメント導線
|
|
371
|
-
|
|
372
|
-
| 種別 | ドキュメントID/参照先 | 目的 | 備考 |
|
|
373
|
-
| -------- | ------------------------------------------------------------------------ | ---------------------- | ---- |
|
|
374
|
-
| SSOT | sysd-index / `api/openapi.yaml` / `api/asyncapi.yaml` / `db/migrations/` | 一次情報参照 | 必須 |
|
|
375
|
-
| テスト | its-index / ets-index / stc-index | 観点検証 | 必須 |
|
|
376
|
-
| 運用 | opd-index / opr-index | 監視・障害対応・再実行 | 必須 |
|
|
377
|
-
| 判断記録 | dec-index | 例外・設計判断の追跡 | 必須 |
|
|
107
|
+
- 総数6件以上のフローを掲載すること、全 API や通常処理を網羅すること。
|
|
108
|
+
- 保存前に完了扱いすること、根拠のない retry・補償・自動再開を指示すること。
|
|
109
|
+
- 一般名称や glob だけで実装・設定・テスト・復旧手順の参照を済ませること。
|
|
110
|
+
- テストファイルの存在を、シナリオ網羅・実行成功の証拠として扱うこと。
|
|
111
|
+
- 未決事項の影響・当面の扱い・解消条件を省くこと、機械の動作主体と人間の一次対応を混同すること。
|