specdojo 0.6.0 → 0.8.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 +3 -2
- package/CHANGELOG.md +193 -0
- package/README.md +2 -2
- package/dist/catalog/build.js +24 -1
- package/dist/catalog/plan.js +1 -1
- package/dist/catalog/scaffold.js +4 -1
- package/dist/commands/agent.js +33 -0
- package/dist/commands/init.js +6 -1
- package/dist/commands/night-orchestrator.js +6 -4
- package/dist/commands/orchestrator.js +10 -1
- package/dist/dashboard/dashboard-timeline.js +18 -16
- package/dist/dashboard/dashboard.js +612 -259
- package/dist/dashboard/epic-plan.js +81 -0
- package/dist/dashboard/exec-records.js +16 -20
- package/dist/dashboard/routines.js +8 -6
- package/dist/dashboard/timeline-build.js +5 -9
- package/dist/dashboard/timeline.js +9 -4
- package/dist/devcontainer/command.js +18 -0
- package/dist/devcontainer/host-script.js +21 -0
- package/dist/devcontainer/scaffold.js +22 -3
- package/dist/docs/frontmatter-namespace.js +1 -48
- package/dist/docs/yaml-pages.js +125 -3
- package/dist/exec/agent-config.js +22 -0
- package/dist/exec/agent-plan.js +3 -2
- package/dist/exec/antigravity-session.js +154 -0
- package/dist/exec/commands.js +69 -21
- package/dist/exec/commit-hook-skips.js +78 -0
- package/dist/exec/core.js +19 -7
- package/dist/exec/events.js +159 -8
- package/dist/exec/evidence.js +64 -16
- 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 +160 -12
- package/dist/exec/pipeline-state.js +27 -5
- package/dist/exec/plan-markdownlint.js +89 -0
- package/dist/exec/plans-condense-findings.js +89 -0
- package/dist/exec/plans-core.js +24 -17
- package/dist/exec/plans-generation.js +52 -25
- 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/register-resume.js +69 -42
- package/dist/exec/register.js +26 -22
- package/dist/exec/repo-integration-sync.js +8 -4
- package/dist/exec/repo-integration.js +21 -1
- package/dist/exec/reporter.js +121 -23
- package/dist/exec/results.js +85 -24
- package/dist/exec/review-completion.js +47 -0
- package/dist/exec/review-kata.js +109 -0
- package/dist/exec/run/agent-pipeline.js +75 -6
- package/dist/exec/run/agent.js +20 -7
- package/dist/exec/run/in-place.js +69 -32
- package/dist/exec/run/job.js +81 -24
- package/dist/exec/run/lifecycle-commands.js +264 -43
- package/dist/exec/run/mode-shared.js +11 -3
- package/dist/exec/run/register-command.js +12 -10
- package/dist/exec/run/register-core.js +20 -13
- package/dist/exec/run/register-mode.js +12 -12
- package/dist/exec/run/register-post-review.js +21 -9
- package/dist/exec/run/register-resume.js +28 -18
- package/dist/exec/run/register-state.js +10 -7
- package/dist/exec/run/register-worktree.js +60 -30
- package/dist/exec/run/schedule-mode.js +26 -6
- package/dist/exec/run/schedule-prepare.js +228 -45
- package/dist/exec/run/schedule-task.js +132 -25
- package/dist/exec/run/shared.js +4 -3
- package/dist/exec/run/trailing-records.js +35 -0
- package/dist/exec/run-records.js +2 -0
- package/dist/exec/strategy.js +1 -0
- package/dist/exec/trailing-records.js +242 -0
- package/dist/exec/trial-commands.js +3 -2
- package/dist/exec/validate-records-commit.js +110 -0
- package/dist/exec/validate-records.js +148 -0
- package/dist/exec/worktree-command.js +29 -16
- package/dist/exec/worktree-ops-commit.js +118 -59
- package/dist/exec/worktree-ops-lifecycle.js +77 -44
- package/dist/exec/worktree-ops-merge.js +13 -2
- package/dist/exec/worktree-ops.js +2 -2
- package/dist/exec/worktree.js +19 -2
- package/dist/grade/apply.js +32 -6
- package/dist/grade/command-inspect.js +2 -2
- package/dist/grade/command-run.js +2 -0
- 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 +23 -3
- package/dist/grade/target-discovery.js +17 -4
- package/dist/grade/targets.js +12 -11
- package/dist/job/job.js +31 -17
- package/dist/job/noop.js +104 -0
- 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 +4 -1
- package/dist/register/planning.js +7 -14
- package/dist/register/register.js +74 -32
- 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 +4 -3
- package/dist/routine/failure.js +30 -0
- package/dist/routine/routine.js +56 -32
- package/dist/routine/storage.js +33 -0
- package/dist/schedule/schedule.js +1 -0
- 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 +2 -0
- package/dist/shared/condense-records.js +25 -0
- package/dist/shared/deprecation.js +8 -0
- 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.js +149 -15
- package/dist/shared/grade-result.js +17 -1
- 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/provider-scaffold.js +2 -0
- package/dist/shared/run-records.js +224 -0
- package/dist/shared/specdojo-config.js +39 -21
- package/dist/shared/specdojo-gitignore.js +1 -0
- package/dist/shared/text.js +65 -5
- package/dist/shared/timeline-index.js +2 -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 +48 -0
- package/docs/ja/specdojo/guides/docs-structure-guide.md +48 -15
- package/docs/ja/specdojo/guides/exec-config-guide.md +61 -28
- package/docs/ja/specdojo/guides/exec-operation-guide.md +61 -13
- package/docs/ja/specdojo/guides/exec-worktree-guide.md +20 -11
- package/docs/ja/specdojo/guides/orchestrator-operation-guide.md +4 -2
- 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 +589 -807
- package/docs/ja/specdojo/guides/register-operation-guide.md +26 -4
- package/docs/ja/specdojo/guides/remote-host-development-guide.md +33 -4
- package/docs/ja/specdojo/guides/review-guide.md +22 -19
- package/docs/ja/specdojo/guides/routine-operation-guide.md +14 -8
- package/docs/ja/specdojo/guides/ryu-guide.md +23 -13
- package/docs/ja/specdojo/guides/schedule-design-guide.md +7 -4
- package/docs/ja/specdojo/guides/schedule-operation-guide.md +41 -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 +471 -74
- package/docs/ja/specdojo/recipes/bac-recipe.md +94 -0
- package/docs/ja/specdojo/recipes/bes-recipe.md +105 -0
- package/docs/ja/specdojo/recipes/br-recipe.md +84 -0
- package/docs/ja/specdojo/recipes/cdfd-overview-recipe.md +88 -86
- package/docs/ja/specdojo/recipes/cdfd-uc-recipe.md +108 -122
- package/docs/ja/specdojo/recipes/cnd-recipe.md +125 -0
- package/docs/ja/specdojo/recipes/cpd-recipe.md +126 -0
- package/docs/ja/specdojo/recipes/cxd-recipe.md +145 -0
- package/docs/ja/specdojo/recipes/ifd-recipe.md +134 -0
- package/docs/ja/specdojo/recipes/ifx-cmd-recipe.md +135 -86
- package/docs/ja/specdojo/recipes/ifx-index-recipe.md +130 -0
- package/docs/ja/specdojo/recipes/pm-organization-recipe.md +29 -26
- package/docs/ja/specdojo/recipes/pm-plan-recipe.md +35 -26
- package/docs/ja/specdojo/recipes/pm-quality-management-plan-recipe.md +38 -28
- package/docs/ja/specdojo/recipes/pm-raci-recipe.md +39 -31
- package/docs/ja/specdojo/recipes/pm-roles-recipe.md +26 -28
- package/docs/ja/specdojo/recipes/prj-assumptions-constraints-dependencies-recipe.md +10 -8
- package/docs/ja/specdojo/recipes/prj-comparison-of-alternatives-recipe.md +18 -17
- package/docs/ja/specdojo/recipes/stsd-recipe.md +100 -62
- package/docs/ja/specdojo/recipes/sysd-critical-flows-recipe.md +106 -0
- package/docs/ja/specdojo/recipes/sysd-cross-cutting-policy-recipe.md +137 -0
- package/docs/ja/specdojo/recipes/sysd-index-recipe.md +122 -0
- package/docs/ja/specdojo/references/command-reference.md +146 -99
- package/docs/ja/specdojo/references/deliverables-reference.md +9 -4
- package/docs/ja/specdojo/references/directory-layout-reference.md +3 -2
- package/docs/ja/specdojo/references/specdojo-config-reference.md +17 -16
- package/docs/ja/specdojo/rulebooks/bac-rulebook.md +72 -290
- package/docs/ja/specdojo/rulebooks/bdd-rulebook.md +212 -79
- package/docs/ja/specdojo/rulebooks/bds-rulebook.md +138 -154
- package/docs/ja/specdojo/rulebooks/bes-index-rulebook.md +147 -59
- package/docs/ja/specdojo/rulebooks/bes-rulebook.md +100 -96
- package/docs/ja/specdojo/rulebooks/br-rulebook.md +88 -108
- package/docs/ja/specdojo/rulebooks/ccd-mermaid-rulebook.md +126 -211
- package/docs/ja/specdojo/rulebooks/cdfd-d2-rulebook.md +367 -0
- package/docs/ja/specdojo/rulebooks/cdfd-mermaid-rulebook.md +6 -5
- package/docs/ja/specdojo/rulebooks/cdfd-overview-rulebook.md +96 -100
- package/docs/ja/specdojo/rulebooks/cdfd-rulebook.md +38 -47
- package/docs/ja/specdojo/rulebooks/cdfd-uc-rulebook.md +132 -106
- package/docs/ja/specdojo/rulebooks/cdsd-rulebook.md +102 -68
- package/docs/ja/specdojo/rulebooks/cdt-rulebook.md +152 -0
- package/docs/ja/specdojo/rulebooks/cld-rulebook.md +9 -184
- package/docs/ja/specdojo/rulebooks/clis-rulebook.md +187 -0
- package/docs/ja/specdojo/rulebooks/cnd-rulebook.md +93 -247
- package/docs/ja/specdojo/rulebooks/cpd-rulebook.md +104 -241
- package/docs/ja/specdojo/rulebooks/cxd-rulebook.md +124 -257
- package/docs/ja/specdojo/rulebooks/dct-index-rulebook.md +87 -98
- package/docs/ja/specdojo/rulebooks/dct-rulebook.md +9 -7
- package/docs/ja/specdojo/rulebooks/dec-rulebook.md +2 -1
- package/docs/ja/specdojo/rulebooks/dss-rulebook.md +193 -0
- package/docs/ja/specdojo/rulebooks/gl-rulebook.md +100 -54
- package/docs/ja/specdojo/rulebooks/ifd-mermaid-rulebook.md +69 -252
- package/docs/ja/specdojo/rulebooks/ifx-cmd-rulebook.md +91 -76
- package/docs/ja/specdojo/rulebooks/ifx-file-rulebook.md +252 -226
- package/docs/ja/specdojo/rulebooks/ifx-index-rulebook.md +118 -40
- package/docs/ja/specdojo/rulebooks/imp-business-rulebook.md +11 -11
- package/docs/ja/specdojo/rulebooks/imp-data-rulebook.md +9 -9
- package/docs/ja/specdojo/rulebooks/imp-interface-rulebook.md +4 -4
- package/docs/ja/specdojo/rulebooks/imp-operations-rulebook.md +11 -11
- package/docs/ja/specdojo/rulebooks/imp-test-rulebook.md +11 -11
- package/docs/ja/specdojo/rulebooks/mm-rulebook.md +4 -3
- package/docs/ja/specdojo/rulebooks/pjr-rulebook.md +34 -29
- package/docs/ja/specdojo/rulebooks/pm-change-request-log-rulebook.md +8 -8
- package/docs/ja/specdojo/rulebooks/pm-issue-log-rulebook.md +2 -2
- package/docs/ja/specdojo/rulebooks/pm-organization-rulebook.md +50 -56
- package/docs/ja/specdojo/rulebooks/pm-plan-rulebook.md +46 -55
- package/docs/ja/specdojo/rulebooks/pm-quality-management-plan-rulebook.md +57 -54
- package/docs/ja/specdojo/rulebooks/pm-raci-rulebook.md +50 -65
- package/docs/ja/specdojo/rulebooks/pm-risk-register-rulebook.md +2 -2
- package/docs/ja/specdojo/rulebooks/pm-roles-rulebook.md +70 -97
- package/docs/ja/specdojo/rulebooks/pr-rulebook.md +2 -1
- package/docs/ja/specdojo/rulebooks/prj-assumptions-constraints-dependencies-rulebook.md +47 -56
- package/docs/ja/specdojo/rulebooks/prj-comparison-of-alternatives-rulebook.md +61 -135
- package/docs/ja/specdojo/rulebooks/sf-index-rulebook.md +116 -32
- package/docs/ja/specdojo/rulebooks/sf-rulebook.md +118 -61
- package/docs/ja/specdojo/rulebooks/sld-rulebook.md +152 -57
- package/docs/ja/specdojo/rulebooks/stsd-mermaid-rulebook.md +51 -39
- package/docs/ja/specdojo/rulebooks/stsd-rulebook.md +101 -46
- package/docs/ja/specdojo/rulebooks/sysd-critical-flows-rulebook.md +72 -329
- package/docs/ja/specdojo/rulebooks/sysd-cross-cutting-policy-rulebook.md +74 -263
- package/docs/ja/specdojo/rulebooks/sysd-index-rulebook.md +78 -195
- package/docs/ja/specdojo/rulebooks/tml-rulebook.md +4 -9
- package/docs/ja/specdojo/rulebooks/trc-requirements-to-specs-rulebook.md +3 -4
- package/docs/ja/specdojo/rulebooks/trc-requirements-to-tests-rulebook.md +3 -3
- package/docs/ja/specdojo/rulebooks/uis-rulebook.md +140 -143
- 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 +100 -21
- package/docs/ja/specdojo/samples/bes-index-sample.md +59 -20
- package/docs/ja/specdojo/samples/bes-sample.md +80 -21
- package/docs/ja/specdojo/samples/br-sample.md +68 -14
- package/docs/ja/specdojo/samples/ccd-sample.md +81 -19
- package/docs/ja/specdojo/samples/cdfd-overview-sample.md +248 -140
- package/docs/ja/specdojo/samples/cdfd-sample.md +172 -99
- package/docs/ja/specdojo/samples/cdfd-uc-sample.md +130 -97
- package/docs/ja/specdojo/samples/cdsd-sample.md +89 -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 +132 -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/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-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/pm-members-sample.yaml +37 -13
- package/docs/ja/specdojo/samples/pm-organization-sample.md +52 -20
- package/docs/ja/specdojo/samples/pm-plan-sample.md +84 -26
- package/docs/ja/specdojo/samples/pm-quality-management-plan-sample.md +55 -22
- package/docs/ja/specdojo/samples/pm-raci-sample.md +69 -28
- package/docs/ja/specdojo/samples/pm-roles-sample.yaml +13 -12
- package/docs/ja/specdojo/samples/prj-assumptions-constraints-dependencies-sample.md +50 -26
- package/docs/ja/specdojo/samples/prj-comparison-of-alternatives-sample.md +89 -62
- package/docs/ja/specdojo/samples/sf-index-sample.md +89 -20
- package/docs/ja/specdojo/samples/sf-sample.md +121 -21
- package/docs/ja/specdojo/samples/sld-sample.md +107 -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 +164 -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/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-overview-template.md +161 -83
- package/docs/ja/specdojo/templates/cdfd-template.md +81 -54
- package/docs/ja/specdojo/templates/cdfd-uc-template.md +130 -89
- 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 +3 -0
- package/docs/specdojo/schemas/v1/exec-defaults.schema.yaml +54 -3
- package/docs/specdojo/schemas/v1/exec-evidence.schema.yaml +3 -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/register-events.schema.yaml +2 -0
- package/docs/specdojo/schemas/v1/register-item-frontmatter.schema.yaml +17 -1
- package/docs/specdojo/schemas/v1/specdojo-config.schema.yaml +1 -0
- package/package.json +6 -3
- package/templates/antigravity/README.md +19 -46
- package/templates/antigravity/exec-defaults-snippet.yaml +5 -6
- package/templates/antigravity/orchestrator.md +3 -2
- package/templates/antigravity/settings.edit.json +73 -0
- package/templates/antigravity/settings.orchestrator.json +15 -0
- package/templates/antigravity/settings.report.json +7 -0
- package/templates/antigravity/settings.review.json +7 -0
- package/templates/claude/agents/specdojo-orchestrator.md +3 -2
- package/templates/codex/agents/specdojo-orchestrator.toml +3 -2
- package/templates/codex/orchestrator.md +3 -2
- package/templates/devcontainer/remote-host/devcontainer-tmux.sh +217 -0
- package/templates/devcontainer/remote-host/specdojo-tmux.sh.sample +8 -96
- package/templates/devcontainer/remote-host/ssh-config.sample +3 -1
- package/templates/devcontainer/tmux.conf +6 -0
- package/templates/init-agent-members.yaml +1 -0
- package/templates/init-exec-defaults.yaml +1 -1
- package/templates/opencode/agents/specdojo-orchestrator.md +3 -2
|
@@ -3,375 +3,118 @@ 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件とする。上限の例外は設けない。追加候補で超過する場合は既存との統合・置換・対象外への整理を先に行い、整理後も5件以内であることと選定理由を確認してから反映する。
|
|
21
|
+
- 通常処理の網羅より、順序、排他、重複、部分成功、外部障害、人間承認を誤った場合の結果を明確にする。
|
|
22
|
+
- 読み手が開始条件、成功の確定、失敗時に残るもの、再開の可否を判断できる粒度にする。
|
|
23
|
+
- 値・構文・データ構造は実装、schema、リファレンスを正本とする。本書には一意な参照と確認条件だけを置く。
|
|
24
|
+
- 設計上の要求、確認済みの動作、未確認の適合を区別する。未決の業務判断や運用条件を完成済みと扱わない。
|
|
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 と対応させる。
|
|
43
|
+
- 統合・廃止時は ARC が図・一覧・設計索引を、DEV が実装・schema・CLI・互換性を、QE がテストを、OPS が運用導線を確認する。PM は計画・登録簿への影響を管理し、人間の PO が採否を承認する。
|
|
59
44
|
|
|
60
45
|
## 4. 推奨 Frontmatter 項目
|
|
61
46
|
|
|
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
|
-
| 項目 | 説明 | 必須 |
|
|
47
|
+
共通の形式・必須キー・型は [[specdojo:document-metadata-standard|ドキュメントメタ情報標準]] と `docs/specdojo/schemas/v1/deliverable-frontmatter.schema.yaml`(共通定義は `common-frontmatter.schema.yaml`)を正本とする。以下の項目は `specdojo:` 名前空間配下に置く。文書名は本文先頭の H1 に記し、`specdojo.title` は使用しない。
|
|
67
48
|
|
|
68
|
-
|
|
|
69
|
-
|
|
|
70
|
-
|
|
|
71
|
-
|
|
|
72
|
-
| status |
|
|
73
|
-
|
|
|
74
|
-
|
|
|
49
|
+
| 項目 | 必須性 | 本系統での判断・記入方針 |
|
|
50
|
+
| ---------------------- | ------ | ---------------------------------------------------------------------------------------------- |
|
|
51
|
+
| `id` | 必須 | 対象範囲で一意な文書 ID を示す |
|
|
52
|
+
| `type` | 必須 | システム設計として `architecture` を使う |
|
|
53
|
+
| `status` | 必須 | 文書の成熟度を示す。AI Agent は `ready` へ昇格させない |
|
|
54
|
+
| `rulebook` | 必須 | 本規約の ID を示す |
|
|
55
|
+
| `owner` | 任意 | 更新責任の Role code を示す。人間の最終承認者とは区別する |
|
|
56
|
+
| `part_of` / `based_on` | 任意 | 所属索引と、実際に判断へ用いた依存範囲内の根拠を示す。参照ハブから辿れる文書を一律に転記しない |
|
|
75
57
|
|
|
76
|
-
|
|
58
|
+
## 5. 本文要件
|
|
77
59
|
|
|
78
|
-
|
|
79
|
-
- `based_on` / `supersedes` は ID 配列(未指定は `[]` 可)。
|
|
60
|
+
全章を必須とする。見出し順・表・記入欄の骨組みは宣言された雛形を正本とし、ここでは意味要件を定める。
|
|
80
61
|
|
|
81
|
-
|
|
62
|
+
| 内容 | 目的と満たす条件 |
|
|
63
|
+
| -------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------- |
|
|
64
|
+
| 概要 | 対象・対象外、最大5件の管理方針、設計索引への接続、公開する情報と除外する情報、人間の最終承認責任を示す |
|
|
65
|
+
| 重要フロー一覧 | ID・名称・事故論点に、影響を受ける利用者/運用者、放置時の影響、期待効果、通常処理より優先する理由を対応させる |
|
|
66
|
+
| フロー詳細 | フローごとに目的・トリガー・範囲・主要入出力、図、永続化点、整合性・冪等・再実行、失敗時の保持・補償・再開条件、利用者が確認できる受入条件を示す |
|
|
67
|
+
| 観測性と運用連携 | フローごとの相関キーと追跡範囲、trace の伝搬範囲または非採用理由、監視条件・閾値の正本、実装動作、人間の一次対応とエスカレーション先を分離して示す |
|
|
68
|
+
| 関連ドキュメント導線 | 実装・設定、テスト、運用、判断記録への一意な導線と変更影響を示す。未解決事項、依存順・担当・完了条件・判断時期、公開/承認条件もここで管理する |
|
|
82
69
|
|
|
83
|
-
|
|
70
|
+
フロー詳細の図はシステム内外、サービス/プロセスと保存先の境界、主要識別子、同期・非同期の区別を示す。矢印の意味を定義し、要求受付と業務完了を同一視しない。分散トレースの導入は必須とせず、複数プロセスを関連付ける方法を示す。
|
|
84
71
|
|
|
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件を超える場合は、分割前に統合・重複排除を検討する。
|
|
72
|
+
テスト参照は実在するパスまたはテスト ID とし、実行方法、対象条件、期待結果、失敗判定を対応させる。既存テストの所在確認とシナリオ網羅の確認を区別し、未網羅なら担当と解消先を示す。内部結合テストは ITC(`itc-` 系)、外部結合テストは ETC(`etc-` 系)の名称を使う。
|
|
105
73
|
|
|
106
74
|
## 6. 記述ガイド
|
|
107
75
|
|
|
108
|
-
|
|
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障害」「再実行性」などで明示する。
|
|
76
|
+
共通の状態・権限・設定は上位の索引・仕様を正本とし、本書にはフロー固有の条件だけを書く。
|
|
124
77
|
|
|
125
|
-
|
|
78
|
+
### 6.1. 概要
|
|
126
79
|
|
|
127
|
-
-
|
|
128
|
-
-
|
|
129
|
-
-
|
|
130
|
-
- 整合性が難しい(最終的整合性、二重書き込み、在庫/金額/残高)
|
|
131
|
-
- 外部I/F障害が業務影響に直結(タイムアウト、リトライ、部分失敗)
|
|
132
|
-
- 監査対象(改ざん/追跡が必要)
|
|
133
|
-
- 性能/可用性のボトルネック候補(ピーク処理、バッチ遅延)
|
|
80
|
+
- 判断基準: 対象の入口・出口と最終承認責任が特定でき、公開範囲を判断できること。
|
|
81
|
+
- 良い例: 「販売要求から受付照合までを扱う。公開版は設計条件だけを含み、顧客別の購入記録は含めない。実運用の採否は人間の PO が判断する」。
|
|
82
|
+
- 悪い例: 「システム全体を安全に運用する」。境界と判断者が分からない。
|
|
134
83
|
|
|
135
|
-
### 6.
|
|
84
|
+
### 6.2. 重要フロー一覧
|
|
136
85
|
|
|
137
|
-
|
|
86
|
+
- 推奨列は ID、名称、事故論点、対象者、業務影響、期待効果・選定理由。優先度だけで選定理由の代わりにしない。
|
|
87
|
+
- 判断基準: 重複実行や中断によって誰のどの作業が損なわれるかを説明でき、追加候補と既存フローの比較から対象を絞れていること。
|
|
88
|
+
- 良い例: 「応答欠落後の売上再送は二重計上の恐れがあるため、閲覧より先に扱う」。
|
|
89
|
+
- 悪い例: 「重要なので High」。他候補より優先する根拠がない。
|
|
138
90
|
|
|
139
|
-
|
|
91
|
+
### 6.3. フロー詳細
|
|
140
92
|
|
|
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)
|
|
93
|
+
- 判断基準: 任意の永続化点で止めても、残存状態と再開条件が一つに定まること。設定依存の上限はキーまたは一意な設計参照へ接続する。
|
|
94
|
+
- 良い例: 「外部受付後に応答が失われた場合は取引 ID で照合し、未受付と確認するまで再送しない。受入では同一 ID の二回入力が一件の売上になることを確認する」。
|
|
95
|
+
- 悪い例: 「失敗なら retry」。受付済み、保存失敗、通信失敗を区別していない。
|
|
96
|
+
- 図の良い例: 内部 CLI、端末保存、外部受付を境界で分け、同じ取引 ID を送信・受付・控えに対応させる。矢印の凡例から、送信と応答欠落後の照合を見分けられる。
|
|
97
|
+
- 図の悪い例: 「受付 → 保存 → 完了」だけを並べる。保存主体・識別子・応答欠落時の経路が分からない。
|
|
173
98
|
|
|
174
99
|
### 6.4. 観測性と運用連携
|
|
175
100
|
|
|
176
|
-
|
|
177
|
-
|
|
178
|
-
-
|
|
179
|
-
|
|
180
|
-
-
|
|
181
|
-
- 監視条件(アラート閾値)、手動介入条件、OPR手順への導線を明記する。
|
|
182
|
-
- 業務影響の大きい失敗は OPD の停止判断基準に接続する。
|
|
101
|
+
- 判断基準: 検知条件、プログラムの動作、人間の対応、問い合わせ先、記録先が混ざっていないこと。閾値が未決なら無通知でよいとは判断しない。
|
|
102
|
+
- 良い例: 「重複確定を一件検知したら自動処理を停止する設計。OPS が保持記録を確認して ARC へ照会し、PM へ issue 起票を依頼する」。
|
|
103
|
+
- 悪い例: 「runner が担当」。機械を責任者としている。
|
|
104
|
+
- 相関の良い例: 「外部受付へ内部 trace を渡せないため、取引 ID と受付 ID で CLI・外部受付・保存控えを照合する」。全フロー共通の方針は一度だけ記し、フロー別のキーと範囲へ対応付ける。採否未確認なら代替手段と確認担当・解消先を示す。
|
|
105
|
+
- 相関の悪い例: 「`trace_id` を記録する」。境界を越えた対応や保存先まで追えるか判断できない。
|
|
183
106
|
|
|
184
107
|
### 6.5. 関連ドキュメント導線
|
|
185
108
|
|
|
186
|
-
|
|
187
|
-
|
|
188
|
-
-
|
|
189
|
-
- 参照先は「ID」または「リポジトリ相対パス」で一意に辿れる形にする。
|
|
190
|
-
- 分冊が無い場合でも `(本書のみ)` または `(なし)` を明記し、空欄にしない。
|
|
109
|
+
- 判断基準: 読み手が同じ正本・検証・未決事項へ辿れ、未作成の手順と確認済みの参照を見分けられること。
|
|
110
|
+
- 良い例: 「検証 V-01 は指定したテストファイルを実行し、二重反映を fail とする。未作成の障害手順は U-01 で OPS が追跡し、受入前に PM が Schedule へ依存を登録する」。
|
|
111
|
+
- 悪い例: 「関連テスト、障害対応 OPR を参照」。所在・成立条件・未整備の影響が分からない。
|
|
191
112
|
|
|
192
113
|
## 7. 禁止事項
|
|
193
114
|
|
|
194
|
-
|
|
195
|
-
|
|
196
|
-
|
|
197
|
-
|
|
198
|
-
|
|
199
|
-
|
|
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 | 例外・設計判断の追跡 | 必須 |
|
|
115
|
+
- 総数6件以上のフローを掲載すること、全 API や通常処理を網羅すること。
|
|
116
|
+
- 設定値・構文・schema の表、実装の逐語説明、図をなぞるだけの本文を二重管理すること。
|
|
117
|
+
- 保存前に完了扱いすること、根拠のない retry・補償・自動再開を指示すること。
|
|
118
|
+
- 一般名称や glob だけで参照を済ませること、未作成文書を存在するリンクとして記載すること。
|
|
119
|
+
- テストファイルの存在を、シナリオ網羅・実行成功・人間承認の証拠として扱うこと。
|
|
120
|
+
- 未決事項の影響・担当・解消条件を省くこと、機械の動作主体と人間の責任を混同すること。
|