specdojo 0.5.0 → 0.7.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.
Files changed (137) hide show
  1. package/.github/agents/specdojo-orchestrator.md +2 -0
  2. package/CHANGELOG.md +100 -0
  3. package/README.md +2 -2
  4. package/dist/catalog/generate.js +144 -13
  5. package/dist/commands/agent.js +33 -0
  6. package/dist/commands/init.js +2 -0
  7. package/dist/commands/orchestrator.js +10 -1
  8. package/dist/deliverable/deliverable.js +77 -4
  9. package/dist/devcontainer/command.js +18 -0
  10. package/dist/devcontainer/host-script.js +21 -0
  11. package/dist/devcontainer/scaffold.js +4 -3
  12. package/dist/exec/antigravity-session.js +154 -0
  13. package/dist/exec/core.js +1 -0
  14. package/dist/exec/parent-validation.js +14 -0
  15. package/dist/exec/plan-markdownlint.js +89 -0
  16. package/dist/exec/plans-core.js +46 -1
  17. package/dist/exec/plans-generation.js +45 -5
  18. package/dist/exec/plans-planning.js +1 -1
  19. package/dist/exec/plans-storage.js +1 -0
  20. package/dist/exec/product-branch-records.js +105 -0
  21. package/dist/exec/product-branches.js +52 -0
  22. package/dist/exec/register-product-message.js +50 -0
  23. package/dist/exec/register-resume.js +28 -0
  24. package/dist/exec/register.js +6 -0
  25. package/dist/exec/repo-integration-sync.js +4 -2
  26. package/dist/exec/repo-integration.js +41 -4
  27. package/dist/exec/repo-trace.js +2 -0
  28. package/dist/exec/results.js +9 -5
  29. package/dist/exec/run/lifecycle-commands.js +85 -16
  30. package/dist/exec/run/register-command.js +22 -0
  31. package/dist/exec/run/register-resume.js +11 -1
  32. package/dist/exec/run/register-worktree.js +29 -8
  33. package/dist/exec/run/schedule-mode.js +22 -2
  34. package/dist/exec/run/schedule-prepare.js +49 -4
  35. package/dist/exec/run/schedule-task.js +3 -0
  36. package/dist/exec/strategy.js +2 -1
  37. package/dist/exec/task-repos.js +78 -16
  38. package/dist/exec/worktree-command.js +2 -2
  39. package/dist/exec/worktree-ops-commit.js +1 -13
  40. package/dist/exec/worktree-ops-lifecycle.js +40 -36
  41. package/dist/exec/worktree.js +3 -3
  42. package/dist/register/core.js +5 -0
  43. package/dist/register/create-commands.js +54 -2
  44. package/dist/register/deliverable-target.js +24 -17
  45. package/dist/register/event-merge.js +4 -0
  46. package/dist/register/events.js +6 -0
  47. package/dist/register/external-project.js +2 -0
  48. package/dist/register/input.js +168 -0
  49. package/dist/register/item.js +61 -0
  50. package/dist/register/register.js +33 -25
  51. package/dist/register/renumber.js +4 -0
  52. package/dist/register/update.js +6 -0
  53. package/dist/schedule/approach.js +9 -0
  54. package/dist/schedule/strategy-profiles.js +22 -2
  55. package/dist/shared/agent-types.js +4 -1
  56. package/dist/shared/branch-template.js +26 -0
  57. package/dist/shared/commit-message-template.js +38 -0
  58. package/dist/shared/commit-types.js +15 -0
  59. package/dist/shared/git.js +7 -0
  60. package/dist/shared/provider-scaffold.js +2 -0
  61. package/dist/shared/specdojo-config.js +35 -4
  62. package/dist/shared/specdojo-gitignore.js +1 -0
  63. package/docs/ja/specdojo/defaults/pm-review-viewpoints.yaml +2 -0
  64. package/docs/ja/specdojo/exec-templates/xep-draft-template.md +93 -0
  65. package/docs/ja/specdojo/exec-templates/xep-fully-guided-template.md +9 -2
  66. package/docs/ja/specdojo/exec-templates/xep-register-investigate-template.md +2 -0
  67. package/docs/ja/specdojo/exec-templates/xep-register-template.md +2 -0
  68. package/docs/ja/specdojo/exec-templates/xer-human-bootstrap-finalize-template.md +2 -0
  69. package/docs/ja/specdojo/exec-templates/xer-human-draft-template.md +23 -0
  70. package/docs/ja/specdojo/exec-templates/xer-human-finalize-template.md +2 -0
  71. package/docs/ja/specdojo/exec-templates/xrp-fully-guided-template.md +7 -4
  72. package/docs/ja/specdojo/guides/docs-editing-guide.md +36 -0
  73. package/docs/ja/specdojo/guides/exec-config-guide.md +16 -12
  74. package/docs/ja/specdojo/guides/exec-operation-guide.md +116 -10
  75. package/docs/ja/specdojo/guides/orchestrator-operation-guide.md +4 -2
  76. package/docs/ja/specdojo/guides/quick-start-guide.md +597 -871
  77. package/docs/ja/specdojo/guides/register-operation-guide.md +16 -1
  78. package/docs/ja/specdojo/guides/remote-host-development-guide.md +31 -4
  79. package/docs/ja/specdojo/guides/ryu-guide.md +114 -23
  80. package/docs/ja/specdojo/guides/schedule-design-guide.md +31 -4
  81. package/docs/ja/specdojo/guides/schedule-operation-guide.md +14 -0
  82. package/docs/ja/specdojo/guides/use-case-guide.md +537 -77
  83. package/docs/ja/specdojo/recipes/cdfd-overview-recipe.md +88 -86
  84. package/docs/ja/specdojo/recipes/cdfd-uc-recipe.md +96 -122
  85. package/docs/ja/specdojo/recipes/exec-human-finalize-recipe.md +1 -0
  86. package/docs/ja/specdojo/recipes/tsd-recipe.md +20 -12
  87. package/docs/ja/specdojo/references/command-reference.md +111 -46
  88. package/docs/ja/specdojo/references/specdojo-config-reference.md +69 -8
  89. package/docs/ja/specdojo/rulebooks/cdfd-d2-rulebook.md +367 -0
  90. package/docs/ja/specdojo/rulebooks/cdfd-mermaid-rulebook.md +6 -5
  91. package/docs/ja/specdojo/rulebooks/cdfd-overview-rulebook.md +96 -100
  92. package/docs/ja/specdojo/rulebooks/cdfd-rulebook.md +38 -47
  93. package/docs/ja/specdojo/rulebooks/cdfd-uc-rulebook.md +108 -103
  94. package/docs/ja/specdojo/rulebooks/dct-rulebook.md +8 -0
  95. package/docs/ja/specdojo/rulebooks/pjr-rulebook.md +4 -0
  96. package/docs/ja/specdojo/rulebooks/sch-rulebook.md +3 -1
  97. package/docs/ja/specdojo/samples/cdfd-overview-sample.md +248 -140
  98. package/docs/ja/specdojo/samples/cdfd-uc-sample.md +128 -97
  99. package/docs/ja/specdojo/samples/dct-sample.yaml +5 -1
  100. package/docs/ja/specdojo/standards/document-metadata-standard.md +16 -0
  101. package/docs/ja/specdojo/standards/exec-human-finalize-standard.md +1 -0
  102. package/docs/ja/specdojo/standards/guide-authoring-standard.md +2 -1
  103. package/docs/ja/specdojo/standards/philosophy-authoring-standard.md +1 -0
  104. package/docs/ja/specdojo/standards/recipe-authoring-standard.md +2 -1
  105. package/docs/ja/specdojo/standards/rulebook-authoring-standard.md +2 -1
  106. package/docs/ja/specdojo/standards/standard-authoring-standard.md +2 -1
  107. package/docs/ja/specdojo/templates/cdfd-overview-template.md +161 -83
  108. package/docs/ja/specdojo/templates/cdfd-uc-template.md +127 -90
  109. package/docs/ja/specdojo/templates/pjr-change-request-template.md +10 -4
  110. package/docs/ja/specdojo/templates/pjr-issue-template.md +10 -4
  111. package/docs/ja/specdojo/templates/pjr-question-template.md +11 -5
  112. package/docs/ja/specdojo/templates/pjr-risk-template.md +10 -4
  113. package/docs/ja/specdojo/templates/pjr-todo-template.md +10 -4
  114. package/docs/specdojo/schemas/v1/dct.schema.yaml +9 -0
  115. package/docs/specdojo/schemas/v1/exec-common.schema.yaml +2 -1
  116. package/docs/specdojo/schemas/v1/exec-defaults.schema.yaml +2 -0
  117. package/docs/specdojo/schemas/v1/register-events.schema.yaml +3 -0
  118. package/docs/specdojo/schemas/v1/register-item-frontmatter.schema.yaml +35 -0
  119. package/docs/specdojo/schemas/v1/sch-strategy.schema.yaml +1 -0
  120. package/docs/specdojo/schemas/v1/specdojo-config.schema.yaml +41 -2
  121. package/package.json +6 -2
  122. package/templates/antigravity/README.md +19 -46
  123. package/templates/antigravity/exec-defaults-snippet.yaml +5 -6
  124. package/templates/antigravity/orchestrator.md +2 -0
  125. package/templates/antigravity/settings.edit.json +73 -0
  126. package/templates/antigravity/settings.orchestrator.json +15 -0
  127. package/templates/antigravity/settings.report.json +7 -0
  128. package/templates/antigravity/settings.review.json +7 -0
  129. package/templates/claude/agents/specdojo-orchestrator.md +2 -0
  130. package/templates/codex/agents/specdojo-orchestrator.toml +2 -0
  131. package/templates/codex/orchestrator.md +2 -0
  132. package/templates/devcontainer/remote-host/devcontainer-tmux.sh +217 -0
  133. package/templates/devcontainer/remote-host/specdojo-tmux.sh.sample +8 -90
  134. package/templates/devcontainer/remote-host/ssh-config.sample +3 -1
  135. package/templates/init-agent-members.yaml +1 -0
  136. package/templates/init-exec-defaults.yaml +1 -1
  137. package/templates/opencode/agents/specdojo-orchestrator.md +2 -0
@@ -11,49 +11,43 @@ specdojo:
11
11
 
12
12
  Conceptual Data Flow Diagram Use Case Writing Recipe
13
13
 
14
- 全体概要で選定した横断ユースケースを、プロセスグループの順序、引き渡す情報、引き渡し条件、条件不成立時の戻り先へ具体化し、グループ内部を重複させずに合意するための作成手順です。
14
+ 全体概要で選定した一つのユースケースまたは系統について、開始から終了までの流れと、受け渡す情報・物を具体化するための作成手順です。参加単位と詳細化の境界は rulebook の「描き方の選択」に従います。
15
15
 
16
16
  ## 1. このレシピの使い方
17
17
 
18
- - 最初に、全体概要から一つのケース ID、業務目的、横断するプロセスグループを抜き出し、開始イベントと終了条件を短いメモにします。
19
- - 次に、正常系のグループごとに、説明文、主要入力・主要出力・データストアの箇条書き、横断上の役割表を作ります。
20
- - 全体概要の「データストア」から引き渡しに使う部分集合を切り出し、グループ代表ノードと引き渡し条件だけで図を作ります。
21
- - その後、隣接するグループ間ごとに渡す情報、受け側を開始できる条件、受け取れない場合の戻す条件を具体化し、条件不成立時の戻り先と再開条件を表へ整理します。
22
- - 最後に、全体概要との名称整合、全引き渡しの追跡、グループ内部と状態遷移の非重複をレビューします。
18
+ - 全体概要からケース ID、業務目的、参加単位、開始・終了を抜き出します。
19
+ - 目的、適用範囲、役割表、データストアの部分集合を作り、上から下へ進む図で受け渡しを示します。
20
+ - 最後に表と図の名称・順序、全体概要との境界、有効な参照先を確認します。業務上重要な戻りだけ、任意の図を追加します。
23
21
 
24
- この成果物は、上位で合意した業務目的を Why として引き継ぎ、グループ間で成立させる情報と条件を What、順序と戻し方を How、ケース ID・引き渡し ID・参照先の対応を Trace として整理します。内部プロセスや状態遷移を複製せず、責任を持つ文書へ接続します。
22
+ ケース ID、参加単位の名称・領域 ID、データストア名を軸に、範囲・表・図を対応させます。引き渡し ID を追加せず、情報・物の名前を線のラベルにします。
25
23
 
26
24
  ## 2. 作成前に集める情報
27
25
 
28
- | 項目 | 集める情報 |
29
- | ---------------- | ---------------------------------------------------------------------------------- |
30
- | 対象ケース | 全体概要にある `C-<nn>`、ユースケース名、業務目的 |
31
- | 開始と終了 | 最初のグループを起動するイベント、最後のグループが成果を利用可能と判断する条件 |
32
- | 参加グループ | 正常系で通過する二つ以上のプロセスグループ名、領域 ID、通過順、主要入出力 |
33
- | グループ別責務 | 各グループが前段から受け取るものと、次段へ引き渡す成果 |
34
- | グループ別 CDFD | 各参加グループの `cdfd-<group>` と、そこに定義された境界入出力 |
35
- | 引き渡す情報 | 受け側が業務を始めるために必要な情報・物・承認結果 |
36
- | 引き渡し条件 | 必須情報の充足、承認、記録確定、現物との一致など、受け側が確認できる条件 |
37
- | 戻す条件 | 情報不足、不一致、承認未了など、受け側が引き渡しを受理できない条件 |
38
- | 関連データストア | 引き渡す情報または条件判定の正本となる、全体概要の「データストア」にある名称と区分 |
39
- | 判断者 | 引き渡し可否、戻し、再開を最終判断する人間のロール |
40
- | 状態の参照先 | 状態一覧と状態遷移図を統合した STSD。内容は転記せず参照先だけ控える |
41
- | 未決事項 | 横断境界、条件、戻り先、判断者が未確定な論点と、影響、決定者、決定時期 |
26
+ | 項目 | 集める情報 |
27
+ | ------------ | ---------------------------------------------------------------------------- |
28
+ | 対象ケース | 全体概要にあるケース ID、業務名、業務目的 |
29
+ | 描く単位 | rulebook の「描き方の選択」で決める参加単位と詳細化の境界 |
30
+ | 開始と終了 | 開始する出来事と、最後に利用可能になる成果 |
31
+ | 役割と順序 | 全体概要と同じグループ・区分、領域 ID、正常系の通過順、各参加単位の責務 |
32
+ | 受け渡し | 隣接する参加単位やデータストアの間で渡す情報・物 |
33
+ | データストア | 全体概要にある名称、マスタ・構成/トランザクションの区分、参照・更新する内容 |
34
+ | 共通の約束 | 全体概要の責任分担、凡例、Orchestrator の指示の図 |
35
+ | 参照先 | 有効な全体概要、必要な詳細文書と STSD。status が `deprecated` の文書は除く |
36
+ | 重要な戻り | 補完・再判断を担う参加単位、返す不足情報や差異。業務上重要な場合だけ集める |
37
+ | 未決事項 | 境界、名称、責務、判断者が未確定な論点、影響、決定者、決定時期 |
42
38
 
43
39
  ## 3. 全体の作成手順
44
40
 
45
- 1. 全体概要から対象のケース ID、ユースケース名、業務目的、参加グループを抜き出します。
46
- 2. 最初のグループが動き始める出来事を開始イベント、最後のグループが成果を受理した状態を終了条件として一文ずつ書きます。
47
- 3. 正常系の参加グループを順に並べ、各グループについて役割の説明文、主要入力・主要出力・データストアの箇条書き、横断上の役割表を作ります。
48
- 4. グループ名、含む領域 ID、境界入出力を全体概要と各 `cdfd-<group>` で突き合わせ、名称ゆれを解消します。
49
- 5. 隣接グループ間ごとに引き渡し候補を作り、正常順序に沿って `H-<nn>` を仮置きします。
50
- 6. 全体概要の「データストア」から、引き渡す情報または条件判定に使う行だけを同じ区分で転記し、関連する引き渡し ID と利用内容を記入します。
51
- 7. 開始イベント、グループ代表ノード、引き渡し条件、終了条件を左から右へ並べ、引き渡し ID と情報名を付けて図にします。
52
- 8. 「データストア」の各行を同名ノードとして図へ加え、行とノードが一対一で対応することを確認します。
53
- 9. 各引き渡しについて、情報、受け側が yes / no で判定できる引き渡し条件、送り元へ戻す条件を書きます。
54
- 10. 条件不成立ごとに、補完責任を持つ戻り先、戻す情報、同じ引き渡しを再評価できる再開条件を整理します。
55
- 11. 内部プロセス名、内部例外、状態名・遷移、実装項目を探し、対応する `cdfd-<group>` と STSD の参照へ置き換えます。
56
- 12. ケース ID と引き渡し ID を使って、範囲、プロセス領域、データストア、図、引き渡し表、戻り先表の重複・欠落を解消します。
41
+ 1. 全体概要の「詳細 CDFD 一覧」からケースを選び、rulebook の「描き方の選択」で参加単位を決めます。
42
+ 2. その業務が何のためにあるかを、開始からどの成果までを成立させるかという 1〜2 文で書きます。読み手の承認・設計・確認作業は含めません。
43
+ 3. 対象と対象外を 1 行ずつ書き、共通原則は全体概要を参照します。`based_on` と本文の参照先が有効な文書であることを確認します。
44
+ 4. 全体概要と同じグループ・区分ごとに節を設け、正常系の順序と責務を役割表だけで示します。PDCA が必要なら独立した任意の列を追加します。
45
+ 5. 全体概要から、このケースで参照・更新するデータストアを同じ名称・区分で切り出し、関連する参加単位と利用内容を書きます。
46
+ 6. 開始イベント、参加単位、終了の出来事を上から下へ並べ、渡す情報・物の名前を線のラベルにします。D2 は `direction: down` とし、引き渡し条件のイベントや Orchestrator は置きません。
47
+ 7. データストアを同名ノードで加え、表の各行と図を対応させます。イベントは一ノード一出来事の短い文とし、長ければ原文を保って改行します。
48
+ 8. 図に業務の言葉で題を付け、読み取れることを 1 文で説明します。凡例は全体概要への短い参照にします。
49
+ 9. 業務上重要な戻りがある場合だけ、「概念データフロー」に「例外時の戻り」の図を追加し、返す情報を線にします。戻りの線は上側のノードを左辺にした `a <- b` で書きます。
50
+ 10. ケース ID、名称、領域 ID で範囲・表・図を突き合わせ、内部処理や状態定義・遷移の重複を除きます。
57
51
 
58
52
  ## 4. 各章の書き方
59
53
 
@@ -61,138 +55,118 @@ Conceptual Data Flow Diagram Use Case Writing Recipe
61
55
 
62
56
  問い:
63
57
 
64
- - 誰がグループの通過順と責任境界を承認しますか。
65
- - 誰が引き渡す情報と条件を設計入力として使いますか。
66
- - 誰がグループ間の重複・欠落と戻り経路を確認しますか。
58
+ - そのユースケースまたは系統は何のためにありますか。
59
+ - どの出来事から、どの成果または判断までを成立させますか。
67
60
 
68
- 「業務を分かりやすくする」ではなく、「店主代表が在庫・仕入・販売の引き渡し条件を承認する」のように、対象者と利用結果を結び付けます。上位の業務目的はケース ID で引き継ぎ、同じ背景説明を繰り返しません。
61
+ 「欠品した商品を補充し、売場で販売できるようにする」のように業務の目的を 1〜2 文で書きます。BA・QE・承認者などの読み手の役割は書きません。
69
62
 
70
63
  ### 4.2. 適用範囲
71
64
 
72
65
  問い:
73
66
 
74
- - ケース ID、ユースケース名、参加グループは全体概要と一致していますか。
75
- - どの出来事で最初のグループが始まり、どの成果を誰が受理すれば終わりますか。
76
- - 対象となる組織、システム境界、現物の範囲を説明できますか。
77
- - 内部プロセス、補助操作、状態遷移、実装詳細をどこへ委ねますか。
78
- - 承認と最終判断を担う人間のロールを参照できますか。
67
+ - ケース ID、参加単位、開始・終了は全体概要と一致していますか。
68
+ - 対象と対象外がそれぞれ 1 行で分かりますか。
69
+ - 共通原則と調整役の指示を全体概要に委ねていますか。
70
+ - 本文と `based_on` に `deprecated` の文書が残っていませんか。
79
71
 
80
- 開始と終了は単なる期間ではなく、発生または成立を判定できる出来事・成果で区切ります。参加グループの追加や削除が必要なら、横断図だけで補正せず、全体概要へ判断を戻します。
72
+ 全体概要の選定を変える必要があれば先に全体概要を見直します。未作成の参照先は ID をインラインコードで仮置きします。
81
73
 
82
74
  ### 4.3. プロセス領域
83
75
 
84
76
  問い:
85
77
 
86
- - 正常系のグループを開始から終了まで一節ずつ順に並べましたか。
87
- - 各節が、説明文、主要入力・主要出力・データストアの箇条書き、横断上の役割表の順になっていますか。
88
- - 各グループの名称と領域 ID は全体概要と同じですか。
89
- - 主要入力・主要出力と横断上の役割は、前段から受け取るものと次段へ渡すものに限定されていますか。
90
- - 各グループの内部を確認できる `cdfd-<group>` を一意に示せますか。
78
+ - rulebook の「描き方の選択」に従い、全体概要と同じまとまりの節にしていますか。
79
+ - 各節は役割表だけですか。主要入力・主要出力・データストアの箇条書きが残っていませんか。
80
+ - 順序、プロセスグループ・区分、含む領域、横断上の役割、参照先を示していますか。
81
+ - PDCA を示す場合は独立した任意の列にし、全体概要の区分と混同していませんか。
91
82
 
92
- 各節の表の一行を一つの代表ノードへ対応させます。同じグループが正常系で再登場する場合は節を分け、前回と異なる引き渡し目的を説明します。内部の処理順や担当は書き写しません。
83
+ 表の一行を図の一つのプロセスノードに対応させます。全体概要を名称と領域の正本とし、入力・出力の正本は図にします。
93
84
 
94
85
  ### 4.4. データストア
95
86
 
96
87
  問い:
97
88
 
98
- - 引き渡す情報または引き渡し条件の判定に必要なデータストアだけを掲載していますか。
99
- - 名称と区分は全体概要の「データストア」と一致していますか。
100
- - 各行に関連する引き渡し ID と、横断上の利用内容がありますか。
101
- - 各行が概念データフローの同名ノードに対応していますか。
89
+ - 対象ケースで参照・更新する正本だけですか。
90
+ - 名称と区分は全体概要と一致していますか。
91
+ - 関連する参加単位を名称・領域 ID で示し、利用内容を説明していますか。
92
+ - 表の各行と図の同名ノードが対応していますか。
102
93
 
103
- 全体概要の「データストア」から必要な行を切り出し、マスタ・構成データとトランザクションデータの区分を保ちます。グループ内部だけで使うデータストアは載せません。新しい名称や区分が必要なら、先に全体概要を見直します。
94
+ マスタ・構成データとトランザクションデータに分け、該当する行がない区分は節ごと省略します。
104
95
 
105
96
  ### 4.5. 概念データフロー
106
97
 
107
98
  問い:
108
99
 
109
- - 一つの角丸長方形が一つのプロセスグループを表していますか。
110
- - 開始イベントから終了条件まで、正常系のグループ順序を左から右へ追えますか。
111
- - 引き渡し ID と情報名を、図と引き渡し表で対応付けられますか。
112
- - 図へ置いたデータストアは、引き渡し条件または引き渡す情報の正本として必要ですか。
113
- - グループ内部のプロセス、例外、状態遷移を図へ混ぜていませんか。
100
+ - 正常系の参加単位を開始から終了まで上から下へ追えますか。
101
+ - 一つのイベントに一つの出来事だけを書き、短い文または改行で読めますか。入口の文言は選んだ方式の規定に合っていますか。
102
+ - 渡す情報・物を線の名詞ラベルから読み取れますか。条件のイベントや引き渡し ID が残っていませんか。
103
+ - Orchestrator と調整要求・応答を図から外していますか。
104
+ - 図の題は業務の言葉ですか。説明は読み取れることの 1 文ですか。
114
105
 
115
- グループ代表ノードの間に、引き渡し条件を表すイベントノードを置きます。データストアを加える場合も、どの内部処理が読む・書くかは描かず、横断条件の根拠となる情報だけを示します。図直後の注記で凡例、線種、省略境界、選定したデータストアを説明します。
106
+ D2 は `direction: down` とします。必要な承認は「承認済みの補充依頼」など成果の性質として線に表し、条件の判定ノードは置きません。凡例は全体概要を参照します。
116
107
 
117
- ### 4.6. 引き渡し
108
+ ### 4.6. 例外時の戻りの図(任意)
118
109
 
119
110
  問い:
120
111
 
121
- - 隣接するすべてのグループ間に一つ以上の引き渡しがありますか。
122
- - 引き渡す情報は、受け側が何を受け取るか分かる名詞になっていますか。
123
- - 引き渡し条件は、情報の充足、承認、記録確定、現物との一致を判定できますか。
124
- - 条件を満たさないとき、何をどのグループへ戻すか分かりますか。
112
+ - 先行する参加単位へ情報や判断を戻すことが、業務として重要ですか。
113
+ - 戻す不足情報・差異と、補完・再判断を担う参加単位が線から分かりますか。
114
+ - 再提示も「修正・承認済みの補充依頼」などの情報として描いていますか。
125
115
 
126
- まず受け側が開始前に確認するチェックを列挙し、そのチェックに必要な情報だけを引き渡しへ残します。送り元の作業完了を条件にするのではなく、受け側が受理できる成果の状態を記述します。
116
+ 必要な場合だけ「概念データフロー」の節に追加し、通常の図と名称・領域 ID をそろえます。「引き渡し」「例外時の戻り先」の章や、戻す条件・再開条件の表は作りません。
127
117
 
128
- ### 4.7. 例外時の戻り先
129
-
130
- 問い:
131
-
132
- - 各引き渡しの戻す条件を、戻り先表の条件不成立へ対応させましたか。
133
- - 不足を補完または再判断できるグループが戻り先になっていますか。
134
- - 戻す情報から、不足・不一致・判断待ちの内容が分かりますか。
135
- - 再開条件は同じ引き渡しを再評価できる形になっていますか。
136
-
137
- 戻り先は内部プロセスではなくグループまでに留めます。受け側内部の再試行やログは扱わず、先行グループへ情報・判断を戻すことで横断順序が変わる場合だけを記載します。
138
-
139
- ### 4.8. 未決事項(任意)
118
+ ### 4.7. 未決事項(任意)
140
119
 
141
120
  - 調査で確定できる不足情報は _TODO_:、意思決定待ちは _UNDECIDED_:、仮置きする前提は _ASSUMPTION_: とします。
142
- - 未決論点には、影響するケース ID または引き渡し ID、決定者、決定時期を添えます。
143
- - 未決事項がない場合は章を省略し、空表や「なし」だけの章を残しません。
121
+ - 未決論点には影響するケース・参加単位、決定者、決定時期を添えます。
122
+ - ない場合は章を省略し、空表や「なし」だけの章を残しません。
144
123
 
145
124
  ## 5. 深掘り手順
146
125
 
147
- 1. 最後のグループが受理する成果から逆向きにたどり、直前の引き渡し情報と条件が本当に必要かを確認します。
148
- 2. 開始イベントから順方向にたどり、各グループが前段から受け取らないと作れない成果を特定します。
149
- 3. 各引き渡し条件を yes / no の質問へ置き換え、判定者と根拠情報を答えられない条件を具体化します。
150
- 4. グループ代表ノードを隠し、内部プロセス名が図や表に残っていないか検索します。残っていればグループ責務または参照へ置き換えます。
151
- 5. 状態を表す語を検索し、状態の意味や遷移を定義している箇所を STSD の参照へ移します。
152
- 6. 引き渡し ID を一つずつ追い、データストア、図、引き渡し表、戻り先表で情報と条件が一致するか確認します。
153
- 7. 条件不成立を一つずつ仮定し、戻り先が不足を補完でき、再開条件の成立後に同じ引き渡しへ戻れるか確認します。
154
- 8. データストアを一つずつ外しても引き渡し条件を説明できるか試し、不要なものを図から削除します。
126
+ 1. 最後の成果から逆にたどり、各参加単位と受け渡しが業務目的に必要か確認します。
127
+ 2. 開始イベントから順にたどり、前段の成果が次段へ情報・物として渡っているか確認します。
128
+ 3. 全体概要の区分と領域 ID を突き合わせ、PDCA の値で区分を置き換えた行を直します。
129
+ 4. データストアを一つずつ確かめ、このケースの情報・物の受け渡しに不要なものを除きます。
130
+ 5. 状態定義・遷移や内部プロセスが残っていれば、責任を持つ有効な文書の参照へ移します。
131
+ 6. 戻りの図がある場合だけ、不足情報や差異が補完責任のある参加単位へ届くか確認します。
132
+ 7. D2 を `d2 --layout elk` で SVG に出力し、上下の順序、ノードとラベルの大きさを確認します。読みづらい場合はイベントの改行や図の分割を見直します。
155
133
 
156
134
  ## 6. 良い例 / 悪い例
157
135
 
158
- | 観点 | 良い例 | 悪い例 |
159
- | -------------- | ------------------------------------------------------------- | ---------------------------------------------------- |
160
- | 対象ケース | `C-02` の在庫 → 仕入 → 販売を扱う | 在庫グループ内の在庫確認だけを扱う |
161
- | グループノード | 「在庫(P-05〜P-06)」を一つの代表ノードにする | 補充判定や在庫更新を別々のプロセスノードにする |
162
- | 引き渡す情報 | 在庫から仕入へ「補充対象、数量、判断者」を渡す | 必要なデータ一式を渡す |
163
- | 引き渡し条件 | 補充対象と数量が確定し、店主代表が発注判断を承認した | 在庫処理が適切に完了した |
164
- | 戻す条件 | 商品または数量を一意に特定できない場合は在庫へ戻す | エラー時は前へ戻す |
165
- | 再開条件 | 修正済みの補充依頼を店主代表が再承認し、`H-01` を再評価できる | 問題が解決したら再開する |
166
- | データストア | 引き渡し判定に使う在庫記録を全体概要と同じ名称で置く | 図だけ「在庫 DB」と改名し、内部テーブルまで描く |
167
- | 状態責務 | 商品状態は STSD を参照し、図には引き渡し成立条件だけを描く | 未発注 → 入荷済み → 販売可能の遷移を横断図で定義する |
168
- | グループ内例外 | 発注不可の結果を在庫へ戻す条件だけを扱う | 仕入先選定、再発注、返品処理の手順を横断図へ展開する |
136
+ | 観点 | 良い例 | 悪い例 |
137
+ | ----------- | ------------------------------------------------ | -------------------------------------------------- |
138
+ | 目的 | 欠品した商品を補充し、売場で販売できるようにする | BA が承認し、QE が検証へ使う |
139
+ | 区分と PDCA | 区分は実行サイクル、PDCA は別列で Do | 区分を Do に置き換える |
140
+ | 渡す情報 | 在庫から仕入へ「承認済みの補充依頼」を直接つなぐ | 途中に「H-01 受理できる」というイベントを置く |
141
+ | イベント | 「在庫が補充基準を下回った」を必要なら改行 | 複数の出来事を一つの長い六角形に詰める |
142
+ | 戻り | 仕入から在庫へ「不足項目・商品候補」を返す線 | すべての受け渡しについて戻り先表を必須にする |
143
+ | 参照先 | 有効な全体概要を参照する | `deprecated` のグループ別 CDFD を参照する |
144
+ | 調整役 | Orchestrator の指示は全体概要の図に任せる | 詳細の図に Orchestrator と各段階への要求を再掲する |
145
+ | 状態責務 | 商品状態は STSD を参照する | 未発注から販売可能への状態遷移を本書で定義する |
169
146
 
170
147
  ## 7. レビュー観点
171
148
 
172
- | 観点 | 確認内容 | 主な確認者 |
173
- | ------------ | -------------------------------------------------------------------------------- | -------------------------- |
174
- | 業務価値 | ケースの終了条件が上位の業務目的を満たし、各引き渡しがその成立に必要と説明できる | 業務分析担当、店主代表 |
175
- | 横断範囲 | 二つ以上の参加グループ、通過順、領域 ID が全体概要と一致する | 業務分析担当 |
176
- | 引き渡し | 情報、条件、戻す条件を受け側が yes / no で判定できる | 業務分析担当、技術メンター |
177
- | 責任境界 | 戻り先と判断者が明確で、内部プロセスを横断側で再定義していない | 店主代表、アーキテクト |
178
- | 図の追跡性 | ケース ID、引き渡し ID、グループ名、領域 ID を表と図で対応付けられる | 品質確認担当 |
179
- | データ整合 | 関連データストアの名称・区分が全体概要と一致し、条件判定に必要なものだけがある | 技術メンター、品質確認担当 |
180
- | 状態責務 | 状態定義・遷移を複製せず、必要な STSD へ接続している | 技術メンター |
181
- | 例外時の再開 | 条件不成立から戻り先、戻す情報、再開条件、再評価する引き渡しまでたどれる | 品質確認担当、店主代表 |
149
+ | 観点 | 確認内容 | 主な確認者 |
150
+ | ---------- | ---------------------------------------------------------- | -------------------------- |
151
+ | 業務価値 | 目的が業務の存在理由・成果を示し、終了時の成果と一致する | 業務分析担当、業務責任者 |
152
+ | 範囲と粒度 | rulebook の「描き方の選択」と全体概要に合う | 業務分析担当 |
153
+ | 表と図 | 順序・名称・領域 ID が対応し、受け渡しを線から読み取れる | 品質確認担当 |
154
+ | データ整合 | データストアの名称・区分と凡例が全体概要に合う | 技術メンター、品質確認担当 |
155
+ | 戻り | 図が必要な場合だけあり、戻す情報と責任が分かる | 業務責任者、品質確認担当 |
156
+ | 正本の境界 | 調整・状態遷移・内部処理を重複させず、有効な文書を参照する | アーキテクト |
182
157
 
183
- 「業務分析担当」「品質確認担当」「技術メンター」「アーキテクト」は、対象プロジェクトのロール定義または責任分担文書で正式な担当へ対応付けます。
158
+ 確認者の呼称は、対象プロジェクトのロール定義または責任分担文書で正式な担当へ対応付けます。
184
159
 
185
160
  ## 8. 仕上げチェック
186
161
 
187
- - 全体概要から一つのケース ID、ユースケース名、業務目的、二つ以上の参加グループを引き継いだ。
188
- - 開始イベントと終了条件を第三者が判定できる形で記述した。
189
- - 参加グループを正常系の順序で一節ずつ並べ、各節を説明文、三つの箇条書き、役割表の順で構成した。
190
- - 隣接グループ間へ `H-<nn>` を付け、情報、引き渡し条件、戻す条件を記述した。
191
- - 図の一つのプロセスノードが一つのプロセスグループを表し、内部プロセスを描いていない。
192
- - 図の開始から終了までをたどれ、引き渡し ID と情報名を表へ対応付けられる。
193
- - 「データストア」は全体概要と同じ名称・区分の部分集合で、各行を引き渡し ID と図の同名ノードへ対応させた。
194
- - 全引き渡しについて、条件不成立、戻り先、戻す情報、再開条件を確認した。
195
- - グループ内部の領域・プロセス・主要例外・操作手順を再掲していない。
196
- - 状態の定義、遷移表、状態遷移図を記載せず、必要な STSD を参照した。
197
- - 未決事項は共通ラベルで確定情報と区別し、ない場合は章を設けていない。
198
- - 個人情報、秘密情報、非公開の組織情報など、公開範囲に不適切な内容を含めていない。
162
+ - 全体概要のケース ID、業務名、目的、名称・領域 ID を引き継いだ。
163
+ - 目的は業務のための 1〜2 文、適用範囲は対象と対象外が 1 行ずつになっている。
164
+ - 各節が役割表だけで、区分と任意の PDCA 列を分けた。
165
+ - 表と図の参加単位、データストアが対応し、開始から終了まで縦に追える。
166
+ - イベントは一ノード一出来事で短く、入口の原文を保っている。
167
+ - 受け渡しは線のラベルにあり、引き渡し ID・条件イベント・旧来の引き渡し/戻り先の章がない。
168
+ - Orchestrator を詳細の図に置かず、全体概要の指示の図へ委ねた。
169
+ - 図の題は業務の言葉、説明は読み取れることの 1 文で、凡例は全体概要を参照している。
170
+ - 戻りの図は業務上重要な場合だけ追加し、条件表や内部の再試行手順を置いていない。
171
+ - `based_on` と本文に `deprecated` の参照先がなく、状態定義・遷移を複製していない。
172
+ - 未決事項がない場合は章を省略し、公開範囲に不適切な情報を含めていない。
@@ -52,6 +52,7 @@ Human Finalize Execution Recipe
52
52
  ### 4.2. 成果物の最終確認
53
53
 
54
54
  - 各 `done_criteria` について、完成版のどの記述が満たすかを確認します。
55
+ - 確定対象の本文に未反映の `_CONTEXT_:` がないことを確認します。残っていれば承認せず、元の指示と対象箇所を備考に記録して `draft` へ差し戻します。
55
56
  - 不足を直す場合は既存の責務と文脈を保ち、確定に必要な範囲だけを修正します。
56
57
  - 修正後は対象形式に対応する検証を再実行し、エラーがない状態にします。
57
58
 
@@ -24,23 +24,31 @@ Technology Stack Detail Definition (TSD) Writing Recipe
24
24
 
25
25
  秘密値を収集せず、次の問いに答える短いメモを作る。確認不足は _TODO_、意思決定待ちは _UNDECIDED_、仮の前提は _ASSUMPTION_ を付け、担当と確認・判断の時期を添える。
26
26
 
27
- | 入力 | 答える問い・集める情報 |
28
- | ------------------ | -------------------------------------------------------------------------------------------------------- |
29
- | 利用目的と根拠 | 誰が何をできるようにするか。上位設計のどの責務・品質条件に応えるか |
30
- | 文書の境界 | 技術一覧、既存の基盤定義、接続設定、利用手順のどこに正本があるか |
31
- | 環境と権限 | OS、実行環境、ユーザー、権限、依存の版、必要な CPU・メモリ・ディスクは何か。特別な条件がない項目はどれか |
32
- | 配置と経路 | 接続元、ホスト、コンテナ、サービスはどこで動き、どの方向へ通信するか。公開範囲はどこまでか |
33
- | 設定の事実 | 導入済みの版、有効な設定、保存先、優先順位、再起動の要否を何で確認できるか |
34
- | 採用の判断 | 決定済みの値と推奨候補は何か。互換性、ライセンス、資源の制約と採否の根拠は何か |
35
- | 認証と公開範囲 | 認証方式、秘密情報の取得・保存・参照の仕組みは何か。固有の接続先や識別子を公開できるか |
36
- | 確認と証跡 | 最小の利用成功は何か。確認場所、期待結果、確認環境・版・日付、記録先は何か |
37
- | 継続利用と変更影響 | 切断、再起動、再構築で何が残るか。旧方式との競合、切り戻し、撤去で失う状態は何か |
27
+ agent に作成を任せる場合は、集めた情報や前提をどこに渡すかを決める。成果物の外から継続して渡す共通前提はカタログの `brief`、起票時や対話で決まった前提・調査選定の委任は個票の `入力`(`--input`)、成果物の特定章に対する具体的な指示は雛形内の `_CONTEXT_:` に書く。
28
+
29
+ | 入力 | 答える問い・集める情報 | 主な文脈の置き場所 |
30
+ | ------------------ | -------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------- |
31
+ | 利用目的と根拠 | 誰が何をできるようにするか。上位設計のどの責務・品質条件に応えるか | カタログの `brief` または個票の `--input` |
32
+ | 文書の境界 | 技術一覧、既存の基盤定義、接続設定、利用手順のどこに正本があるか | カタログの `brief` または第 1 章(概要・位置づけ)の `_CONTEXT_:` |
33
+ | 環境と権限 | OS、実行環境、ユーザー、権限、依存の版、必要な CPU・メモリ・ディスクは何か。特別な条件がない項目はどれか | カタログの `brief`(共通基盤条件)または第 2 章(対象環境・前提条件)の `_CONTEXT_:` |
34
+ | 配置と経路 | 接続元、ホスト、コンテナ、サービスはどこで動き、どの方向へ通信するか。公開範囲はどこまでか | 第 3 章(全体構成・接続経路)の `_CONTEXT_:` または個票の `--input` |
35
+ | 設定の事実 | 導入済みの版、有効な設定、保存先、優先順位、再起動の要否を何で確認できるか | 第 5 章(導入・初期設定)の `_CONTEXT_:` または個票の `--input` |
36
+ | 採用の判断 | 決定済みの値と推奨候補は何か。互換性、ライセンス、資源の制約と採否の根拠は何か | カタログの `brief`(決定方針)または第 4 章(採用技術・設定)の `_CONTEXT_:`・`--input` |
37
+ | 認証と公開範囲 | 認証方式、秘密情報の取得・保存・参照の仕組みは何か。固有の接続先や識別子を公開できるか | 第 6 章(接続設定と秘密情報の扱い)の `_CONTEXT_:` または個票の `--input` |
38
+ | 確認と証跡 | 最小の利用成功は何か。確認場所、期待結果、確認環境・版・日付、記録先は何か | カタログの `done_criteria`(完了条件)または第 7 章(動作確認)の `_CONTEXT_:` |
39
+ | 継続利用と変更影響 | 切断、再起動、再構築で何が残るか。旧方式との競合、切り戻し、撤去で失う状態は何か | 第 8 章(継続利用・運用)・第 10 章(更新・復旧・撤去)の `_CONTEXT_:` |
40
+
41
+ ### 2.1. 文脈の置き場所の使い分けの目安
42
+
43
+ - **カタログの `brief`**: プロジェクトや成果物群で共通する技術スタック・基盤前提(例: 「静的サイト構成とし、主流の技術スタック(Astro 等)を採用する」)。YAML アンカーで複数成果物へ共有できる。
44
+ - **個票の `入力`(`--input`)**: 起票時や対話で決まった前提、または agent に技術スタックの調査や選定を任せる範囲(例: `--input "静的サイトで主流の技術スタックを調べて選定する"`)。
45
+ - **成果物内の `_CONTEXT_:`**: `deliverable scaffold --project <project-id> --target <doc-id>` で生成した雛形の各章見出し直下に書く局所的な指示(カタログにない成果物は `--target-path` と `--target-rulebook` を指定。例: 第 4 章で `_CONTEXT_: 主流のフレームワークを比較し、選定理由と採用値を提案してください`)。`draft` が本文へ反映後に削除する。
38
46
 
39
47
  ## 3. 全体の作成手順
40
48
 
41
49
  1. 利用目的を一文にし、文書を読み始める人の状態と、読み終えて確認する到達状態を書き出す。独立した利用目的が混ざっていたら別文書へ分ける。
42
50
  2. 初期構築・接続設定・日常利用の担当を決める。同じ読み手が同じ前提で一続きに作業し、設定を一か所で保守できるなら一冊にまとめる。構築済み基盤を複数のクライアントが利用する、または接続・再開だけを繰り返すなら分冊を選ぶ。分冊ごとに前提の文書と開始できる確認結果をメモする。
43
- 3. 対象が分かる `tsd-<term>.md` の名前と配置を決め、既存文書との重複を確かめる。各設定の正本を一つ決め、別冊側ではその完了条件と本書で変える差分を示す。
51
+ 3. 対象が分かる `tsd-<term>.md` の名前と配置を決め、既存文書との重複を確かめる。各設定の正本を一つ決め、別冊側ではその完了条件と本書で変える差分を示す。CLI で雛形を作成する場合は `specdojo deliverable scaffold --project <project-id> --target <project-id>:tsd-<term>`(カタログにない成果物は `--target-path` と `--target-rulebook` を指定)を実行する。TSD の rulebook(`specdojo:tsd-rulebook`)は `template: not-needed` だが、`deliverable_type: architecture` を引き継いだ最小構成の雛形が生成される。
44
52
  4. 章の下書きを「概要・位置づけ」「対象環境・前提条件」「全体構成・接続経路」「採用技術・設定」「導入・初期設定」「接続設定」「動作確認」「継続利用・運用」「制約・トラブルシュート」「更新・復旧・撤去」「参照情報」の流れで置く。対象に応じて章を統合・並べ替え、扱わない手順は対象外とする理由や委譲先を概要へ残す。
45
53
  5. 接続元・ホスト・コンテナなどに呼び名を付け、配置と通信方向を図か表にする。各操作の実行場所、設定保存先、権限をこの呼び名へそろえる。
46
54
  6. 採用設定を表にし、推奨候補や任意の選択肢と分ける。実測・決定・公式情報のどれを根拠にしたか確かめ、裏付けがない版や容量は決めた値として埋めない。