specdojo 0.2.0 → 0.3.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 +165 -0
- package/CHANGELOG.md +280 -0
- package/README.md +143 -30
- package/dist/agent-response.js +20 -0
- package/dist/agent.js +4 -4
- package/dist/build-command.js +28 -8
- package/dist/dashboard.js +140 -9
- package/dist/devcontainer-command.js +43 -0
- package/dist/devcontainer-scaffold.js +165 -0
- package/dist/exec-agent-config.js +107 -9
- package/dist/exec-agent-git-state.js +18 -0
- package/dist/exec-agent-protected-config.js +46 -8
- package/dist/exec-evidence.js +254 -11
- package/dist/exec-format.js +13 -4
- package/dist/exec-handoff.js +336 -0
- package/dist/exec-parent-validation.js +317 -43
- package/dist/exec-pipeline-state.js +74 -9
- package/dist/exec-plans.js +115 -113
- package/dist/exec-protection-handoff.js +43 -2
- package/dist/exec-provider-scaffold.js +247 -15
- package/dist/exec-register-resume.js +65 -19
- package/dist/exec-register.js +9 -3
- package/dist/exec-repo-integration.js +811 -0
- package/dist/exec-repo-trace.js +182 -0
- package/dist/exec-reporter.js +613 -132
- package/dist/exec-results.js +81 -56
- package/dist/exec-run-lock.js +110 -107
- package/dist/exec-run.js +1585 -356
- package/dist/exec-shared.js +7 -0
- package/dist/exec-slot-lock.js +242 -0
- package/dist/exec-task-repos.js +415 -0
- package/dist/exec-trial.js +51 -25
- package/dist/exec-worktree-command.js +87 -43
- package/dist/exec-worktree-ops.js +502 -57
- package/dist/exec-worktree.js +114 -27
- package/dist/exec.js +13 -6
- package/dist/grade-result.js +128 -0
- package/dist/grade.js +809 -72
- package/dist/init-command.js +443 -0
- package/dist/job.js +160 -10
- package/dist/orchestrator.js +213 -0
- package/dist/package-paths.js +19 -1
- package/dist/register-event-merge.js +169 -0
- package/dist/register-item.js +7 -1
- package/dist/register.js +294 -86
- package/dist/review-grade.js +252 -0
- package/dist/review-plan.js +111 -1
- package/dist/review-types.js +40 -1
- package/dist/routine.js +72 -5
- package/dist/schedule-build.js +2 -2
- package/dist/schedule.js +17 -4
- package/dist/specdojo-config.js +466 -20
- package/dist/specdojo-gitignore.js +135 -0
- package/dist/specdojo.js +8 -1
- package/dist/viewpoint-document-kinds-check.js +128 -0
- package/docs/ja/specdojo/defaults/pm-review-viewpoints.yaml +348 -90
- package/docs/ja/specdojo/exec-templates/xep-common-conventions-template.md +51 -17
- package/docs/ja/specdojo/exec-templates/xep-fully-guided-template.md +7 -5
- package/docs/ja/specdojo/exec-templates/xrp-freeform-template.md +29 -31
- package/docs/ja/specdojo/exec-templates/xrp-fully-guided-template.md +34 -55
- package/docs/ja/specdojo/exec-templates/xrp-job-template.md +54 -0
- package/docs/ja/specdojo/exec-templates/xrp-recipe-guided-template.md +28 -37
- package/docs/ja/specdojo/exec-templates/xrp-recipe-maintenance-template.md +29 -34
- package/docs/ja/specdojo/exec-templates/xrp-retrofit-template.md +30 -30
- package/docs/ja/specdojo/exec-templates/xrp-rulebook-maintenance-template.md +29 -34
- package/docs/ja/specdojo/exec-templates/xrp-sample-maintenance-template.md +29 -34
- package/docs/ja/specdojo/exec-templates/xrp-template-maintenance-template.md +29 -34
- package/docs/ja/specdojo/exec-templates/xrp-template.md +29 -28
- package/docs/ja/specdojo/exec-templates/xrr-template.md +11 -9
- package/docs/ja/specdojo/guides/docs-editing-guide.md +20 -0
- package/docs/ja/specdojo/guides/docs-structure-guide.md +103 -70
- package/docs/ja/specdojo/guides/exec-config-guide.md +91 -47
- package/docs/ja/specdojo/guides/exec-operation-guide.md +124 -27
- package/docs/ja/specdojo/guides/exec-worktree-guide.md +40 -11
- package/docs/ja/specdojo/guides/kata-guide.md +4 -4
- package/docs/ja/specdojo/guides/orchestrator-operation-guide.md +25 -4
- package/docs/ja/specdojo/guides/plan-result-lifecycle-guide.md +1 -1
- package/docs/ja/specdojo/guides/practice-system-composition-guide.md +13 -13
- package/docs/ja/specdojo/guides/quick-start-guide.md +261 -32
- package/docs/ja/specdojo/guides/register-operation-guide.md +31 -14
- package/docs/ja/specdojo/guides/release-v0-3-0-migration-guide.md +264 -0
- package/docs/ja/specdojo/guides/remote-host-development-guide.md +184 -0
- package/docs/ja/specdojo/guides/review-guide.md +195 -158
- package/docs/ja/specdojo/guides/routine-operation-guide.md +74 -9
- package/docs/ja/specdojo/guides/ryu-guide.md +32 -30
- package/docs/ja/specdojo/guides/schedule-design-guide.md +10 -10
- package/docs/ja/specdojo/guides/schedule-operation-guide.md +1 -1
- package/docs/ja/specdojo/guides/specdojo-overview-guide.md +58 -33
- package/docs/ja/specdojo/guides/use-case-guide.md +3 -3
- package/docs/ja/specdojo/guides/waza-guide.md +15 -2
- package/docs/ja/specdojo/index.md +2 -2
- package/docs/ja/specdojo/philosophy/specdojo-philosophy.md +5 -5
- package/docs/ja/specdojo/recipes/bps-recipe.md +213 -0
- package/docs/ja/specdojo/recipes/pm-members-recipe.md +52 -117
- package/docs/ja/specdojo/references/command-reference.md +336 -93
- package/docs/ja/specdojo/references/deliverables-reference.md +1 -1
- package/docs/ja/specdojo/references/directory-layout-reference.md +13 -9
- package/docs/ja/specdojo/references/specdojo-config-reference.md +107 -24
- package/docs/ja/specdojo/rulebooks/bps-rulebook.md +132 -220
- package/docs/ja/specdojo/rulebooks/br-rulebook.md +6 -44
- package/docs/ja/specdojo/rulebooks/cdfd-rulebook.md +2 -0
- package/docs/ja/specdojo/rulebooks/dmd-rulebook.md +0 -87
- package/docs/ja/specdojo/rulebooks/gl-rulebook.md +61 -39
- package/docs/ja/specdojo/rulebooks/ifx-cmd-rulebook.md +0 -87
- package/docs/ja/specdojo/rulebooks/ifx-index-rulebook.md +1 -33
- package/docs/ja/specdojo/rulebooks/opd-rulebook.md +0 -137
- package/docs/ja/specdojo/rulebooks/opr-rulebook.md +0 -247
- package/docs/ja/specdojo/rulebooks/otp-rulebook.md +0 -83
- package/docs/ja/specdojo/rulebooks/pjr-rulebook.md +4 -2
- package/docs/ja/specdojo/rulebooks/pm-members-rulebook.md +78 -150
- package/docs/ja/specdojo/rulebooks/pm-roles-rulebook.md +5 -4
- package/docs/ja/specdojo/rulebooks/sch-rulebook.md +1 -1
- package/docs/ja/specdojo/rulebooks/stsd-mermaid-rulebook.md +0 -11
- package/docs/ja/specdojo/rulebooks/stsd-rulebook.md +0 -61
- package/docs/ja/specdojo/rulebooks/tml-rulebook.md +2 -47
- package/docs/ja/specdojo/samples/bps-sample.md +74 -21
- package/docs/ja/specdojo/samples/gl-sample.yaml +17 -1
- package/docs/ja/specdojo/samples/ifx-index-sample.yaml +28 -0
- package/docs/ja/specdojo/samples/pm-members-sample.yaml +2 -67
- package/docs/ja/specdojo/samples/pm-organization-sample.md +8 -7
- package/docs/ja/specdojo/samples/pm-raci-sample.md +1 -1
- package/docs/ja/specdojo/samples/tml-sample.yaml +40 -0
- package/docs/ja/specdojo/standards/document-metadata-standard.md +21 -16
- package/docs/ja/specdojo/standards/id-and-file-naming-standard.md +14 -14
- package/docs/ja/specdojo/standards/job-definition-standard.md +37 -17
- package/docs/ja/specdojo/standards/people-and-organization-definition-standard.md +37 -32
- package/docs/ja/specdojo/standards/philosophy-authoring-standard.md +1 -1
- package/docs/ja/specdojo/standards/rulebook-authoring-standard.md +21 -11
- package/docs/ja/specdojo/templates/agent-members-template.yaml +25 -0
- package/docs/ja/specdojo/templates/bps-template.md +91 -0
- package/docs/ja/specdojo/templates/pm-members-template.yaml +2 -59
- package/docs/specdojo/schemas/v1/agent-members.schema.yaml +76 -0
- package/docs/specdojo/schemas/v1/exec-common.schema.yaml +4 -2
- package/docs/specdojo/schemas/v1/exec-defaults.schema.yaml +55 -2
- package/docs/specdojo/schemas/v1/exec-evidence.schema.yaml +93 -6
- package/docs/specdojo/schemas/v1/exec-reporter-output.schema.yaml +27 -78
- package/docs/specdojo/schemas/v1/gl.schema.yaml +87 -0
- package/docs/specdojo/schemas/v1/grade-result.schema.yaml +33 -0
- package/docs/specdojo/schemas/v1/job-run.schema.yaml +27 -0
- package/docs/specdojo/schemas/v1/job.schema.yaml +25 -0
- package/docs/specdojo/schemas/v1/pipeline-state.schema.yaml +49 -1
- package/docs/specdojo/schemas/v1/pm-members.schema.yaml +9 -169
- package/docs/specdojo/schemas/v1/pm-review-viewpoints.schema.yaml +100 -10
- package/docs/specdojo/schemas/v1/register-item-frontmatter.schema.yaml +13 -0
- package/docs/specdojo/schemas/v1/routine-run.schema.yaml +3 -0
- package/docs/specdojo/schemas/v1/routine.schema.yaml +7 -0
- package/docs/specdojo/schemas/v1/specdojo-config.schema.yaml +110 -0
- package/package.json +16 -9
- package/templates/antigravity/README.md +60 -0
- package/templates/antigravity/agent-members-snippet.yaml +61 -0
- package/templates/antigravity/exec-defaults-snippet.yaml +39 -0
- package/templates/antigravity/orchestrator.md +157 -0
- package/templates/antigravity/settings.global.json +55 -0
- package/templates/claude/agents/claude-executor.md +14 -0
- package/templates/claude/agents/claude-reporter.md +16 -0
- package/templates/claude/agents/specdojo-orchestrator.md +164 -0
- package/templates/claude/settings.edit.json +27 -1
- package/templates/codex/README.md +5 -4
- package/templates/codex/agents/specdojo-orchestrator.toml +165 -0
- package/templates/codex/orchestrator.md +157 -0
- package/templates/copilot/README.md +7 -5
- package/templates/copilot/{pm-members-snippet.yaml → agent-members-snippet.yaml} +4 -2
- package/templates/devcontainer/devcontainer.json +27 -0
- package/templates/devcontainer/emacs/init.el +88 -0
- package/templates/devcontainer/post-create.sh +62 -0
- package/templates/init-agent-members.yaml +200 -0
- package/templates/init-exec-defaults.yaml +72 -0
- package/templates/opencode/agents/specdojo-orchestrator.md +204 -0
- package/docs/ja/specdojo/exec-templates/xrp-viewpoint-detail-template.md +0 -7
- package/docs/ja/specdojo/exec-templates/xrr-viewpoint-detail-template.md +0 -7
|
@@ -9,75 +9,76 @@ specdojo:
|
|
|
9
9
|
|
|
10
10
|
Review Guide
|
|
11
11
|
|
|
12
|
-
本ドキュメントは SpecDojo
|
|
12
|
+
本ドキュメントは SpecDojo における review(レビュー)の進め方を定義します。
|
|
13
13
|
|
|
14
|
-
|
|
14
|
+
review はタスクの成果を判定する作業です。成果物の品質は判定しません。成果物の品質は grade が一度だけ評価し、review はその評価結果(grade・finding)を確定済みの事実として受け取り、このタスクを完了してよいかを判断します。観点ごとに成果物を評価し直すことはしません。
|
|
15
15
|
|
|
16
16
|
**対象読者**
|
|
17
17
|
|
|
18
|
-
- SpecDojo
|
|
18
|
+
- SpecDojo の review plan を実行する担当者・エージェント、品質管理者
|
|
19
19
|
|
|
20
20
|
**この文書で分かること**
|
|
21
21
|
|
|
22
|
-
-
|
|
22
|
+
- grade と review の分担、review の入力、review plan・result の構成、verdict の記録、改善指示の扱い、成果物を ready にする条件
|
|
23
23
|
|
|
24
24
|
**次に読む文書**
|
|
25
25
|
|
|
26
26
|
- レビュー時の実践の型の使い方は [実践の進め方ガイド](ryu-guide.md)、plan・result の共通ライフサイクルは [plan/resultライフサイクルガイド](plan-result-lifecycle-guide.md) を参照してください。
|
|
27
27
|
|
|
28
|
-
|
|
28
|
+
最初に review を実行する場合は、`レビューの位置づけ`、`review plan と review result`、`完了と確定` を読めば実施できます。grade が評価する観点の定義は `grade が評価する観点`、改善指示の転記判断は `レビュー結果の記録`、手動で agent へ依頼する場合の文面は `Agent への指示テンプレート` を参照してください。
|
|
29
29
|
|
|
30
30
|
## 1. レビューの位置づけ
|
|
31
31
|
|
|
32
|
-
|
|
32
|
+
review が何を判定する活動か、何を入力とするか、grade・機械検証とどう分担するかを示します。
|
|
33
33
|
|
|
34
34
|
### 1.1. レビューの役割
|
|
35
35
|
|
|
36
|
-
|
|
36
|
+
grade と review は判定する対象が異なります。2 つは重複する評価ではなく、別の問いに答えます。
|
|
37
37
|
|
|
38
|
-
|
|
|
39
|
-
|
|
|
40
|
-
|
|
|
41
|
-
|
|
|
42
|
-
| 妥当性 | 上位目的、業務価値、制約、判断方針に合っているか |
|
|
43
|
-
| 検証可能性 | pass / fail を判断できる完了条件、受入条件、証跡があるか |
|
|
44
|
-
| 追跡可能性 | 上位目的から要求、要件、仕様、設計、テスト、運用まで対応を追えるか |
|
|
38
|
+
| 経路 | 判定対象 | 出力 | 問い |
|
|
39
|
+
| ------ | ------------ | -------------------------------- | ------------------------ |
|
|
40
|
+
| grade | 成果物 | grade(verdict・score)・finding | この文書の品質はどうか |
|
|
41
|
+
| review | タスクの成果 | verdict(完了可否)・改善指示 | この作業を完了してよいか |
|
|
45
42
|
|
|
46
|
-
|
|
43
|
+
品質が低くても今回のタスクの範囲では完了してよい場合があり、品質が十分でもタスクが要求したことを行っていなければ完了できません。review はこの違いを判断します。
|
|
44
|
+
|
|
45
|
+
- 同じ対象を同じ基準で 2 回評価しません。完全性・整合性・妥当性・検証可能性・追跡可能性といった成果物の品質は、grade が観点ごとに評価します。
|
|
46
|
+
- review は grade の結果を事実として受け取り、観点ごとの判定を付け直したり、grade が検出済みの finding を改めて指摘したりしません。評価結果に疑義がある場合は、疑義の内容と再評価が必要な理由を改善指示に記録します。
|
|
47
|
+
- タスクの完了条件は、対象プロジェクトの成果物カタログに定義された `done_criteria` を正とします。充足の判定が評価結果にある場合は、それを事実として用います。
|
|
47
48
|
|
|
48
49
|
### 1.2. レビューの入力
|
|
49
50
|
|
|
50
|
-
|
|
51
|
+
review では次を入力として扱います。確認に用いる文書は review plan に記載されたものに限ります。
|
|
51
52
|
|
|
52
|
-
| 入力
|
|
53
|
-
|
|
|
54
|
-
|
|
|
55
|
-
|
|
|
56
|
-
|
|
|
57
|
-
|
|
|
58
|
-
|
|
|
59
|
-
| 関連成果物
|
|
60
|
-
|
|
|
61
|
-
| 登録簿 | `generated/pjr-index.md` | 未解決事項、課題、リスク、変更要求、決定の転記先 |
|
|
53
|
+
| 入力 | 正本ファイル | 役割 |
|
|
54
|
+
| -------------- | ------------------------------ | ------------------------------------------------------------------------------ |
|
|
55
|
+
| 評価結果 | grade result サイドカー | grade の verdict・score・観点ごとの level・finding。review plan にも提示される |
|
|
56
|
+
| review plan | `exec/plans/<task-id>-plan.md` | 対象成果物、評価結果、完了条件、進め方を固定する |
|
|
57
|
+
| 実行記録 | 先行する edit タスクの result | 何を変更し、どの検証を実行したか |
|
|
58
|
+
| 対象成果物 | - | 変更内容を確かめる対象の Markdown / YAML / JSON など |
|
|
59
|
+
| 成果物カタログ | `dct-*.yaml` | 成果物、依存関係、`done_criteria`(text / roles / viewpoint)を定義する |
|
|
60
|
+
| 関連成果物 | - | `depends_on` 成果物とプロジェクトコンテキスト |
|
|
61
|
+
| 登録簿 | `generated/pjr-index.md` | 未解決事項、課題、リスク、変更要求、決定の転記先 |
|
|
62
62
|
|
|
63
|
-
### 1.3.
|
|
63
|
+
### 1.3. grade・機械検証・review の分担
|
|
64
64
|
|
|
65
|
-
|
|
65
|
+
機械で確認できることと成果物の品質は、review の判断の前に確定させます。
|
|
66
66
|
|
|
67
|
-
| 確認対象 | 主な方法
|
|
68
|
-
| ---------------------- |
|
|
69
|
-
| YAML / JSON の必須キー | JSON Schema
|
|
70
|
-
| 型、enum、ID形式 | JSON Schema
|
|
71
|
-
| Markdown の基本構造 | lint、custom validator
|
|
72
|
-
| リンク、参照先 | custom validator
|
|
73
|
-
| IDの一意性 | custom validator
|
|
74
|
-
| 生成物の同期 | generate command、diff
|
|
75
|
-
|
|
|
76
|
-
|
|
|
67
|
+
| 確認対象 | 主な方法 |
|
|
68
|
+
| ---------------------- | ----------------------- |
|
|
69
|
+
| YAML / JSON の必須キー | JSON Schema |
|
|
70
|
+
| 型、enum、ID形式 | JSON Schema |
|
|
71
|
+
| Markdown の基本構造 | lint、custom validator |
|
|
72
|
+
| リンク、参照先 | custom validator |
|
|
73
|
+
| IDの一意性 | custom validator |
|
|
74
|
+
| 生成物の同期 | generate command、diff |
|
|
75
|
+
| 成果物の品質 | grade(観点ごとの評価) |
|
|
76
|
+
| タスクの完了可否 | review(verdict) |
|
|
77
|
+
| 判断責任 | human approver |
|
|
77
78
|
|
|
78
|
-
|
|
79
|
+
機械検証で失敗した成果物は、review の前に修正します。grade の評価結果が最新でない場合、review は成果物を自分で評価して補わず、verdict を `grade-stale` として記録します。
|
|
79
80
|
|
|
80
|
-
### 1.
|
|
81
|
+
### 1.4. 共通観点とプロジェクト差分
|
|
81
82
|
|
|
82
83
|
レビュー観点の共通正本は [[specdojo:pm-review-viewpoints|共通レビュー観点一覧]] です。プロジェクトの `viewpoints_path` は共通正本の全量コピーではなく、次の差分だけを保持します。
|
|
83
84
|
|
|
@@ -88,13 +89,13 @@ SpecDojo のレビューは次を扱います。
|
|
|
88
89
|
|
|
89
90
|
標準ロールは PO、PM、BA、ARC、DEV、QE、UX、OPS です。独自ロールを使うプロジェクトは、その Role code を `pm-roles.yaml` に定義したうえで、同じ role の `viewpoints` と `role_viewpoint_sets` をプロジェクト差分へ追加します。既存の全量形式は互換入力として読み込めますが、`exec scaffold` が新規生成するのは差分形式です。
|
|
90
91
|
|
|
91
|
-
## 2.
|
|
92
|
+
## 2. grade が評価する観点
|
|
92
93
|
|
|
93
|
-
|
|
94
|
+
観点(viewpoint)は grade が成果物を評価するための定義です。本章は、観点がどの方向から成果物をたどり、何の型を確認するかを示します。review はこれらの観点で成果物を評価し直しません。
|
|
94
95
|
|
|
95
|
-
### 2.1.
|
|
96
|
+
### 2.1. 評価の基本パス
|
|
96
97
|
|
|
97
|
-
|
|
98
|
+
観点の評価は 3 つのパスで行います。
|
|
98
99
|
|
|
99
100
|
#### 2.1.1. 上位から下位へ
|
|
100
101
|
|
|
@@ -139,27 +140,13 @@ SpecDojo のレビューは次を扱います。
|
|
|
139
140
|
|
|
140
141
|
### 2.2. coverage_types の使い方
|
|
141
142
|
|
|
142
|
-
`coverage_types`
|
|
143
|
-
|
|
144
|
-
`coverage_types` は観点そのものではなく、レビュー探索の軸です。たとえば `vp-qe-omissions-consistency` を使う場合でも、実際には `stakeholder`、`exception_case`、`non_functional`、`traceability` など、どの型を確認したかを分けて記録します。
|
|
145
|
-
|
|
146
|
-
review result では、`レビュー観点別結果` セクションの各 `RVP-NNN` に対して、確認した coverage_types と根拠を記述します。
|
|
147
|
-
|
|
148
|
-
例
|
|
149
|
-
|
|
150
|
-
```text
|
|
151
|
-
### RVP-003
|
|
143
|
+
`coverage_types` は、観点が「何の型を確認するか」を表す語彙です。
|
|
152
144
|
|
|
153
|
-
- result
|
|
154
|
-
- evidence: dct-project-definition.yaml の done_criteria / prj-scope.md / prj-success-criteria-and-acceptance-criteria.md
|
|
155
|
-
- notes: 例外ケースと非機能要求の展開に不足がある(確認できたのは stakeholder, use_case, exception_case, non_functional。traceability は未確認)。
|
|
156
|
-
```
|
|
145
|
+
`coverage_types` は観点そのものではなく、評価の探索軸です。たとえば `vp-qe-omissions-consistency` は、`stakeholder`、`exception_case`、`non_functional`、`traceability` など複数の型にまたがって抜け漏れを確認します。観点定義の `coverage_types` は grade の評価で使われ、review result には記録しません。
|
|
157
146
|
|
|
158
|
-
|
|
147
|
+
### 2.3. 要求・要件・仕様の評価
|
|
159
148
|
|
|
160
|
-
|
|
161
|
-
|
|
162
|
-
要求、要件、仕様のヌケモレや間違いは、成果物単体だけでは検出しにくいものです。必ず隣接成果物との対応を確認します。各概念(要求 / 要件 / 仕様 / 設計 / 実装)の定義と、Why → What → How のトレース欠落・粒度混在などの典型的な失敗は [要求から実装までの考え方](../philosophy/needs-to-implementation-philosophy.md) を正本とし、レビュー観点の土台にします。
|
|
149
|
+
要求、要件、仕様のヌケモレや間違いは、成果物単体だけでは検出しにくいものです。観点は隣接成果物との対応を確認します。各概念(要求 / 要件 / 仕様 / 設計 / 実装)の定義と、Why → What → How のトレース欠落・粒度混在などの典型的な失敗は [要求から実装までの考え方](../philosophy/needs-to-implementation-philosophy.md) を正本とし、評価観点の土台にします。
|
|
163
150
|
|
|
164
151
|
| 対象 | 主な確認 |
|
|
165
152
|
| ---- | -------------------------------------------------------------------------------- |
|
|
@@ -169,81 +156,115 @@ review result では、`レビュー観点別結果` セクションの各 `RVP-
|
|
|
169
156
|
| 設計 | 仕様を実現する構造、制約、責務、データ、外部依存、運用方法が明確か |
|
|
170
157
|
| 運用 | 公開後の変更、問い合わせ、障害対応、監査、保守の扱いが明確か |
|
|
171
158
|
|
|
172
|
-
### 2.
|
|
159
|
+
### 2.4. grade と共有する評価属性・rubric
|
|
160
|
+
|
|
161
|
+
viewpoint は継続品質評価 `specdojo grade` の正本です。review plan は同じ観点定義から完了条件の適用を判定しますが、観点を評価し直すためではありません。各 viewpoint の `evaluation` は判定の規準がどこにあるか(`deterministic` / `referential` / `discretionary`)を宣言し、判定の実行経路を選ぶためにだけ使います。すべての viewpoint が grade の対象です。grade の対象範囲は `grade_targets` と `document_kinds` だけで決まります。旧フィールド `continuous` は削除済みで、観点定義に残っていると削除済みであることを示すエラーで読み込みに失敗します。`grade_targets` を省略した観点は kata と成果物の両方、指定した観点は列挙対象だけに適用します。`document_kinds` は rulebook ID 単位でさらに適用先を絞り、grade plan と review plan の両方が同じ宣言を使います。grade 専用の別観点 ID は作りません。
|
|
173
162
|
|
|
174
|
-
|
|
163
|
+
`evaluation` は「判定に必要な根拠がどこにあるか」ではなく、「何が正しいかを決める規準がどこにあるか」で区分します。観点を追加するときは、`check` の文言に何と比べるかが書かれているかで判定します。
|
|
175
164
|
|
|
176
|
-
|
|
165
|
+
| `evaluation` | 規準の所在 | `check` の文型の例 | grade での実行経路 |
|
|
166
|
+
| --------------- | ------------------------------------------------------------------------------- | ----------------------------------------------------- | -------------------------------------- |
|
|
167
|
+
| `deterministic` | 機械可読な規則(schema、lint) | schema と整合しているか、文書体系と整合しているか | コードで判定する |
|
|
168
|
+
| `referential` | 他の文書、宣言された定義(`done_criteria` など)、または `check` 自身が書く規準 | …と矛盾していないか、`done_criteria` を満たしているか | agent へ渡す。突き合わせ先を指示する |
|
|
169
|
+
| `discretionary` | 判定者が持ち込む。文書に規準がない | 必要な範囲で明示されているか、使える粒度か、分かるか | agent へ渡す。判定の安定性は保証しない |
|
|
177
170
|
|
|
178
|
-
|
|
171
|
+
「必要十分」「適切な粒度」のような十分性の語を含む観点でも、`check` が判定規準を書き込んでいれば `referential` です。`discretionary` の観点は、`check` に規準を書き込むことで `referential` へ移せます。`evaluation` は実行主体を表しません。grade はすべての区分の観点を判定し、review はどの区分の観点も判定し直しません。旧値 `agent` / `human` は削除済みで、読み込むと新しい値を示すエラーで失敗します。
|
|
179
172
|
|
|
180
|
-
|
|
173
|
+
文書の種類は Frontmatter の `specdojo.rulebook` を正本とします。rulebook 文書は自身の `specdojo.id`、template 文書は `frontmatter_template.specdojo.rulebook` から種類を解決するため、同じ実践の型に属する rulebook / recipe / sample / template / 成果物は同じ rulebook ID で判定されます。`rulebook: none`、未設定、`undecided`、`not-needed` は未分類です。未分類文書は既定で観点を適用し、`document_kinds.unclassified: exclude` を明示した観点だけ除外します。
|
|
174
|
+
|
|
175
|
+
`document_kinds.include` は列挙した種類だけへ適用し、`document_kinds.exclude` は列挙した種類を除外します。二つは同時に指定できません。宣言を省略した観点は全種類へ適用します。`grade_targets` は kata / deliverable という評価経路の大分類、`document_kinds` は rulebook ID による文書種類の細分類であり、両方を指定した場合は双方を満たす文書だけを対象にします。
|
|
176
|
+
|
|
177
|
+
`include` または `exclude` で rulebook ID を列挙した観点は、すべての rulebook について扱いを判断済みにします。列挙していない rulebook を既定の結果(`exclude` の観点では適用、`include` の観点では対象外)のままにすると判断した場合は、`document_kinds.confirmed_default` へ列挙します。`confirmed_default` は判断の記録で、適用判定は変えません。同じ rulebook を `include` / `exclude` と重ねて書くことはできません。`src/viewpoint-document-kinds-check.ts` の検証は、どこにも載っていない rulebook、存在しない rulebook ID、重複した判断を観点 ID と rulebook ID の組で error として報告します。この検証は `npm test`(`npm run check` に含まれる)で実行され、`npx tsx src/viewpoint-document-kinds-check.ts` で単独でも実行できます。`unclassified` だけを宣言した観点は全種類へ適用するため、検証の対象外です。
|
|
178
|
+
|
|
179
|
+
`grade_rubric` の level 0-4 は category を跨いで共有し、viewpoint score を `level × 25` とします。`grade_rubric` には level ごとの `review_verdict`(level 4 が `complete`、level 3 が `complete-with-findings`、level 0-2 が `incomplete`)が定義されています。これは grade の level を review の入力にする写像であり、review はこの対応で観点を判定し直しません。写像の使い方は `grade の結果を review の入力にする規則` に示します。
|
|
180
|
+
|
|
181
|
+
文書の score は、category ごとの score(観点の level 平均 × 25)を `grade_rubric.weights` の重みで加重平均した値です。重みは kata と成果物で別に持ち、どちらも 9 category すべてに重みを置きます。文書に適用される観点が 1 つもない category は、その文書の加重平均から外します。観点の category に重みがない rubric は、grade の実行時にエラーで失敗します。verdict は blocker があれば `fail`、major があるか score が `pass_score` 未満なら `needs-work`、それ以外は `pass` です。`pass_score` は level 3(軽微な課題)の score に合わせて 75 とし、major のない文書が category の数や重みに関係なく満たす下限にしています。
|
|
182
|
+
|
|
183
|
+
rubric は `grade-rubric-v2` です。v1 は 4 category(architecture / consistency / quality / usability)だけで score を計算していました。v2 は 28 観点すべてと 9 category で計算するため、v1 の grade result とは score・verdict を比較できません。同じ文書でも、目的・計画・業務価値・実装・運用の観点が加わることで score が変わります。grade result の `rubric` が `grade-rubric-v1` の結果は旧基準の値として扱い、現在品質の根拠や傾向比較に使う前に `grade list --rubric-outdated` で列挙して再評価します。`--changed-only` は rubric の違いを検出しません。
|
|
184
|
+
|
|
185
|
+
grade は継続監視の最新スナップショット、review result は完成時の合意形成履歴です。Kata の grade は schedule strategy の approach 導出に使われますが、完成時の合意形成や最終承認を代替しません。
|
|
186
|
+
|
|
187
|
+
#### 2.4.1. 成果物 grade と review result の責務境界
|
|
181
188
|
|
|
182
189
|
成果物の現在品質と変更後の再評価は `grade --target deliverable` を正とします。成果物カタログの `done_criteria` は grade plan に取り込まれ、score とは独立して条件ごとの充足を判定します。充足数・総数・未充足条件の担当 Role code・詳細参照は grade result サイドカーに置き、条件文と不足理由は成果物ごとの grade 詳細ファイルに記録します。
|
|
183
190
|
|
|
184
|
-
評価が現在内容に対するものかは、保存された `content_hash` と現在の成果物ファイル全体のハッシュが一致するかで判断します。不一致の grade と、実行後に成果物が変更された review result は、どちらも現在品質の根拠には使いません。`grade list --target deliverable --changed-only` と定期 routine
|
|
191
|
+
評価が現在内容に対するものかは、保存された `content_hash` と現在の成果物ファイル全体のハッシュが一致するかで判断します。不一致の grade と、実行後に成果物が変更された review result は、どちらも現在品質の根拠には使いません。`grade list --target deliverable --changed-only` と定期 routine は、この不一致を再評価対象として検出します。成果物カタログやメンバー定義など他の文書と突き合わせる観点は、観点定義の `comparison_sources` で突き合わせ先を宣言します。突き合わせ先の hash がサイドカーの `source_hashes` と異なる grade も、本文が変わっていなくても現在品質の根拠に使わず、`--changed-only` で再評価対象になります。
|
|
185
192
|
|
|
186
193
|
review result は特定時点に誰が何を確認し、どの合意を行ったかを残す不変の履歴です。既存 review result は削除・移行せず、最新状態の判定には利用しません。090 の review タスクと `G-*-review-pass` は人の合意形成・最終承認のゲートとして維持し、継続品質の再評価は grade が担います。これにより二つの結果を同じ最新状態として同期させる必要をなくします。
|
|
187
194
|
|
|
188
|
-
`vp-arc-single-responsibility` は、異なる主題を一つの文書へ同居させている状態を検出します。章を独立して参照・更新できるか、対象読者と利用時点が異なるか、別々の sample・recipe・template に対応するかを組み合わせて判断します。長さや対応する実践の型の数だけでは fail
|
|
195
|
+
`vp-arc-single-responsibility` は、異なる主題を一つの文書へ同居させている状態を検出します。章を独立して参照・更新できるか、対象読者と利用時点が異なるか、別々の sample・recipe・template に対応するかを組み合わせて判断します。長さや対応する実践の型の数だけでは fail にしません。複数主題の案内自体を責務とする index、catalog、overview は `document_kinds.exclude` で対象外にし、判定文へ例外を混在させません。同じ主張の反復や正本の過剰な再掲は `vp-arc-conciseness` で扱います。
|
|
189
196
|
|
|
190
197
|
分割が必要な場合、finding には独立する主題と境界候補、参照・カタログへの影響を記録します。grade はファイル作成や ID 採番を行わず、人が finding を確認して分割の採否と PJR 起票を判断します。起票後は新規ファイル、成果物カタログ、参照元、対応する sample・recipe・template の変更を通常の edit task として扱います。
|
|
191
198
|
|
|
192
199
|
## 3. review plan と review result
|
|
193
200
|
|
|
194
|
-
SpecDojo
|
|
201
|
+
SpecDojo の review は、review plan を作ってから実施し、review result を残します。
|
|
195
202
|
|
|
196
203
|
review plan は `specdojo exec plan` または `specdojo exec run` が必要時に生成します。review result は `specdojo exec claim` 時に scaffold され(`specdojo exec run` が claim を兼ねる場合も含む)、`specdojo exec run` または人の作業によって Frontmatter + Markdown 形式で更新します。
|
|
197
204
|
|
|
198
205
|
```text
|
|
199
|
-
|
|
200
|
-
↓ 解決
|
|
201
|
-
dct-*.yaml
|
|
206
|
+
edit タスク(成果物を作る・直す)
|
|
202
207
|
↓
|
|
203
|
-
|
|
208
|
+
grade(成果物を評価する。評価結果が最新なら再実行しない)
|
|
204
209
|
↓
|
|
205
|
-
exec plan / exec run → review plan(exec/plans/<task-id>-plan.md
|
|
210
|
+
exec plan / exec run → review plan(exec/plans/<task-id>-plan.md。評価結果を提示する)
|
|
206
211
|
↓
|
|
207
|
-
human / agent review
|
|
212
|
+
human / agent review(タスクの完了可否を判断する)
|
|
208
213
|
↓
|
|
209
214
|
review result(exec/results/<task-id>-result.md)
|
|
210
215
|
↓
|
|
211
|
-
|
|
216
|
+
完了 / 再評価 / 再計画
|
|
212
217
|
```
|
|
213
218
|
|
|
214
|
-
review plan
|
|
215
|
-
|
|
216
|
-
| 成果物 | 役割 |
|
|
217
|
-
| ------------- | ------------------------------------------------------------------------------------- |
|
|
218
|
-
| review plan | 対象成果物、Role code、viewpoint、coverage_required、エビデンス例、完了手順を定義する |
|
|
219
|
-
| review result | レビュー観点ごとの判定(pass / fail / unclear)、根拠、findings、decision を記録する |
|
|
219
|
+
review plan は「このタスクの完了可否を何に基づいて判断するか」を固定します。review result は「どの評価結果と実行記録を照合し、どの verdict を選んだか」を記録します。
|
|
220
220
|
|
|
221
|
-
|
|
221
|
+
| 成果物 | 役割 |
|
|
222
|
+
| ------------- | ----------------------------------------------------------------------------------------- |
|
|
223
|
+
| review plan | 対象成果物、評価結果(grade の verdict・finding)、完了条件、進め方、完了手順を定義する |
|
|
224
|
+
| review result | 評価結果の確認、判断根拠、未充足事項・改善指示、approach に応じた確認、verdict を記録する |
|
|
222
225
|
|
|
223
226
|
### 3.1. edit plan の完了の狙い
|
|
224
227
|
|
|
225
228
|
通常の成果物編集を行う edit plan は、観点別の自己レビューを行いません。代わりに、`done_criteria` を「完了の狙い」として素の箇条書き(観点・coverage なし)で提示し、編集者は rulebook / recipe / sample / template と「進め方」に沿って記述する中で、その狙いを満たすことを目指します。
|
|
226
229
|
|
|
227
230
|
- 品質の担保は rulebook(必須項目・禁止事項)・recipe(書き方・レビュー観点・仕上げチェック)・sample・template が担います。
|
|
228
|
-
- `done_criteria`
|
|
231
|
+
- 成果物の品質と `done_criteria` の一次判定は grade、タスクの完了可否は後続の独立した review plan / review result が判断します。
|
|
229
232
|
- maintenance 系 approach は対象と判定基準が異なるため、完了の狙いの提示は行いません。
|
|
230
233
|
|
|
231
|
-
edit plan
|
|
234
|
+
edit plan で観点別の自己レビューを行わないのは、各観点を満たそうとして成果物へ過剰な記述を挿入する副作用を避けるためです。review task では成果物を修正せず、第三者的な立場で完了可否を判断します。
|
|
235
|
+
|
|
236
|
+
### 3.2. review 前段の grade
|
|
237
|
+
|
|
238
|
+
`specdojo exec run` は、`mode: review` のタスクの plan を生成する前に、runner 自身が評価対象へ grade を実行します。executor(review を行う agent)には grade を実行させません。評価の独立性を保つためです。
|
|
232
239
|
|
|
233
|
-
|
|
240
|
+
この自動 grade は SpecDojo 本体リポジトリにある開発用の `tools/grade/run-per-document.sh` を使います。スクリプトは npm package に含まれないため、v0.3.0 の公開物では自動 grade を利用できません。公開物の grade は試験的で、利用者は `grade list` / `plan` / `apply` / `validate` / `result` などの部品を使って事前に評価します。成果物の grade には project の `catalog_path` が必要です。1 文書の手順は [CLI コマンドリファレンス](../references/command-reference.md#81-npm-package-で-1-文書を評価する)を参照してください。
|
|
234
241
|
|
|
235
|
-
|
|
242
|
+
- 評価対象は成果物です。`approach` が `rulebook-maintenance` / `recipe-maintenance` / `sample-maintenance` / `template-maintenance` の場合は、見直した実践の型そのものが評価対象になります(`--target kata`)。
|
|
243
|
+
- 評価対象の `content_hash` が既存の評価結果サイドカーの `content_hash` と一致する場合は、grade を再実行せず既存の評価結果を使います。どちらの場合も評価は 1 回です。
|
|
244
|
+
- 本体リポジトリでは grade を `tools/grade/run-per-document.sh` で評価対象 1 件に絞って実行します。npm package の利用先を含むスクリプトがないリポジトリ、評価対象を解決できない場合、`--dry-run` の場合は実行しません。
|
|
245
|
+
- grade が失敗しても review は止めません。実行の結果と評価結果の鮮度を review plan に示し、review が verdict(`grade-stale` / `grade-unavailable` など)として記録します。
|
|
246
|
+
|
|
247
|
+
### 3.3. review plan の生成
|
|
248
|
+
|
|
249
|
+
review plan は `specdojo exec plan` または `specdojo exec run` によって機械生成します(`mode: review` のタスクが対象)。`exec refresh` は Ready などの実行状態を更新しますが、plan は生成しません。`exec plan` は grade を実行せず、その時点の評価結果を提示します。
|
|
236
250
|
|
|
237
251
|
主な入力
|
|
238
252
|
|
|
239
253
|
- 成果物カタログの `local_id`、`path`、`depends_on`、`done_criteria`
|
|
240
|
-
-
|
|
254
|
+
- 評価対象の評価結果サイドカー(grade result)
|
|
255
|
+
- 共通正本と `pm-review-viewpoints.yaml` の差分を解決した `viewpoints`(完了条件の適用判定に使う)
|
|
241
256
|
- 対応する rulebook
|
|
242
257
|
- `sch-strategy-<track>.yaml` が宣言する `mode: review` フェーズ
|
|
243
258
|
|
|
244
|
-
review plan
|
|
259
|
+
review plan の `評価結果` 章には、評価結果を確定済みの事実として次を提示します。
|
|
260
|
+
|
|
261
|
+
- runner の grade 実行の結果(実行した / 評価結果が最新のため省略した / 失敗した / 実行していない)
|
|
262
|
+
- 鮮度(評価対象の `content_hash` と評価結果の `content_hash` が一致するか)。一致しない場合は、提示する評価結果が変更前の内容に対するものであることを明示する
|
|
263
|
+
- grade の `verdict`、`score`、`graded_at`、finding 件数
|
|
264
|
+
- grade が判定した全観点の level と score。観点の区分(`evaluation`)で提示を絞らない
|
|
265
|
+
- finding(ID、severity、観点、行、内容)
|
|
245
266
|
|
|
246
|
-
### 3.
|
|
267
|
+
### 3.4. review plan の配置
|
|
247
268
|
|
|
248
269
|
review plan は `<execution_path>/exec/plans/<task-id>-plan.md` に生成します。`<execution_path>` はプロジェクトの実行ディレクトリ(例: `execution`)を指します。
|
|
249
270
|
|
|
@@ -253,7 +274,7 @@ review plan は `<execution_path>/exec/plans/<task-id>-plan.md` に生成しま
|
|
|
253
274
|
exec/plans/T-LAUNCH-prj-overview-030-plan.md
|
|
254
275
|
```
|
|
255
276
|
|
|
256
|
-
### 3.
|
|
277
|
+
### 3.5. review plan の構成
|
|
257
278
|
|
|
258
279
|
review plan は Frontmatter と本文セクションで構成します。
|
|
259
280
|
|
|
@@ -271,29 +292,42 @@ specdojo:
|
|
|
271
292
|
on_critical_path: true | false
|
|
272
293
|
```
|
|
273
294
|
|
|
274
|
-
| セクション | 内容
|
|
275
|
-
| ---------------------- |
|
|
276
|
-
| このフェーズで行うこと |
|
|
277
|
-
| 対象成果物 |
|
|
278
|
-
|
|
|
279
|
-
|
|
|
280
|
-
|
|
|
295
|
+
| セクション | 内容 |
|
|
296
|
+
| ---------------------- | ------------------------------------------------------------------------------------------ |
|
|
297
|
+
| このフェーズで行うこと | フェーズ説明。このタスクが何を求めたか |
|
|
298
|
+
| 対象成果物 | 対象パス、`depends_on`、rulebook、対応する review result のパス |
|
|
299
|
+
| 評価結果 | 評価対象、`--target`、評価結果サイドカー、runner の grade 実行結果、鮮度、評価値と finding |
|
|
300
|
+
| 完了条件 | `done_criteria` を完了条件として照合する表(観点ごとに評価し直すための表ではない) |
|
|
301
|
+
| 進め方 | `approach` に応じた確認と、参照してよい文書の範囲 |
|
|
302
|
+
| 完了手順 | 鮮度確認、verdict の選択、review result への記入手順 |
|
|
303
|
+
| 異常終了の条件 | review 自体を完了できない場合の扱い |
|
|
304
|
+
|
|
305
|
+
判断の手順と verdict の定義は、plan に注入される共通規約の `review の判断手順` を正本とします。
|
|
306
|
+
|
|
307
|
+
### 3.6. review execution
|
|
281
308
|
|
|
282
|
-
|
|
309
|
+
人または agent は review plan に従って review します。`<execution_path>/exec/results/<task-id>-result.md` は `specdojo exec claim` の時点で scaffold される(手動 claim でも `exec run` 経由の claim でも同様)ため、agent または人はそこに結果を記入します。
|
|
283
310
|
|
|
284
|
-
|
|
311
|
+
agent に review を実行させる場合は、`exec run --plan` で executor と reporter を指定して 2 段で実行します。
|
|
285
312
|
|
|
286
|
-
|
|
313
|
+
```bash
|
|
314
|
+
# review を 2 段で実行する
|
|
315
|
+
npx specdojo exec run --project <project-id> --plan <execution_path>/exec/plans/<task-id>-plan.md \
|
|
316
|
+
--executor-by <executor-nickname> --reporter-by <reporter-nickname>
|
|
317
|
+
```
|
|
318
|
+
|
|
319
|
+
review で `approach` に応じて何を確かめるかは、plan の `進め方` と [実践の進め方ガイド](ryu-guide.md) に従います。
|
|
287
320
|
|
|
288
321
|
実行時の原則
|
|
289
322
|
|
|
290
|
-
-
|
|
291
|
-
-
|
|
292
|
-
-
|
|
293
|
-
-
|
|
323
|
+
- 最初に評価結果の鮮度を確認します。最新でなければ成果物を自分で評価して補わず、verdict を `grade-stale` とします。
|
|
324
|
+
- 成果物を再評価しません。観点ごとの判定を付け直したり、評価結果の判定を自分の判断で置き換えたりしません。
|
|
325
|
+
- 変更内容・plan・実行記録・完了条件・最新の finding を照合し、このタスクの範囲と完了条件を満たすかを判断します。
|
|
326
|
+
- finding が残っていても、このタスクの範囲と完了条件を満たしていれば完了できます。その場合は finding が完了を妨げない理由と改善指示を残します。
|
|
327
|
+
- 判断の根拠は、実際に読んで得た具体的な事実に限ります。executor の最終メッセージや result の自己申告を根拠にしません。
|
|
294
328
|
- agent は最終承認、公開可否判断、説明責任を担いません。
|
|
295
329
|
|
|
296
|
-
### 3.
|
|
330
|
+
### 3.7. review result の構成
|
|
297
331
|
|
|
298
332
|
review result は `<execution_path>/exec/results/<task-id>-result.md` に生成・更新します。
|
|
299
333
|
|
|
@@ -311,41 +345,52 @@ specdojo:
|
|
|
311
345
|
agent: <member nickname>
|
|
312
346
|
```
|
|
313
347
|
|
|
314
|
-
| セクション
|
|
315
|
-
|
|
|
316
|
-
|
|
|
317
|
-
|
|
|
318
|
-
|
|
|
348
|
+
| セクション | 内容 |
|
|
349
|
+
| --------------------- | --------------------------------------------------------------------- |
|
|
350
|
+
| 評価結果の確認 | 鮮度確認のコマンドと出力、grade の `verdict` / `score` / finding 件数 |
|
|
351
|
+
| 判断根拠 | 照合した内容と verdict を選んだ理由 |
|
|
352
|
+
| 未充足事項・改善指示 | 未充足事項と、再計画・改善・再評価に使う改善指示 |
|
|
353
|
+
| approach に応じた確認 | `approach` に応じて確認した内容 |
|
|
354
|
+
| decision | `verdict`(タスク完了可否の 6 値。値の一覧は次のとおり) |
|
|
319
355
|
|
|
320
|
-
|
|
356
|
+
`verdict` は `complete` / `complete-with-findings` / `incomplete` / `grade-stale` / `grade-unavailable` / `changed-during-review` のいずれかです。`pm-review-viewpoints.yaml` の `verdict_definitions` も同じ 6 値を定義します。各値を選ぶ条件は共通規約の `review の判断手順` を正本とします。verdict が `complete` 以外でも、review result を記録できた場合は正常終了します。runner は verdict に応じて再評価または再計画へ進みます。
|
|
321
357
|
|
|
322
|
-
|
|
358
|
+
### 3.8. grade の結果を review の入力にする規則
|
|
323
359
|
|
|
324
|
-
|
|
360
|
+
grade と review は違う対象を判定します。判定の語彙は判定対象ごとに分け、同じ対象を判定する語彙だけを一つにします。
|
|
325
361
|
|
|
326
|
-
|
|
362
|
+
| 語彙 | 判定対象 | 値 |
|
|
363
|
+
| -------------------------------------------------------------------------------- | ---------------------- | -------------------------------------------------------------------------------------------------------------------- |
|
|
364
|
+
| grade の文書 `verdict` | 成果物の品質 | `pass` / `needs-work` / `fail` |
|
|
365
|
+
| grade の観点 level | 観点ごとの成果物の品質 | 0-4 |
|
|
366
|
+
| review result の `verdict`、`pm-review-viewpoints.yaml` の `verdict_definitions` | タスクの完了可否 | `complete` / `complete-with-findings` / `incomplete` / `grade-stale` / `grade-unavailable` / `changed-during-review` |
|
|
327
367
|
|
|
328
|
-
|
|
368
|
+
タスクの完了可否は review result の `verdict` と `verdict_definitions` の同じ 6 値だけで表します。grade の語彙は review の語彙へ統一しません。grade の結果は、次の規則で review の入力になります。
|
|
329
369
|
|
|
330
|
-
|
|
331
|
-
|
|
332
|
-
|
|
333
|
-
|
|
334
|
-
|
|
370
|
+
- grade の結果は review にとって確定済みの事実です。review は level や grade の `verdict` を付け直しません。
|
|
371
|
+
- `grade_rubric` の `review_verdict` は、観点の level が review の判断に与える起点です。level 4 は `complete`、level 3 は `complete-with-findings`、level 0-2 は `incomplete` を起点とします。
|
|
372
|
+
- review は、このタスクの範囲と完了条件に関わる観点の level から最も制限の強い起点を選び、変更内容・plan・実行記録・完了条件と照合して verdict を確定します。
|
|
373
|
+
- 起点と異なる verdict を選ぶ場合は、理由を判断根拠に記録します。たとえば level 2 の finding がこのタスクの範囲外で完了を妨げない場合は `complete-with-findings` を選び、その理由を記録します。起点が `complete` でも、plan または完了条件に未充足事項があれば `incomplete` とします。
|
|
374
|
+
- `grade-stale` / `grade-unavailable` / `changed-during-review` は grade の level からは決まらないため、写像に含めません。鮮度の確認と評価不能の判定で決めます。
|
|
335
375
|
|
|
336
|
-
`findings`
|
|
376
|
+
旧来の語彙は読み込み時に移行先の値を示すエラーで失敗します。`verdict_definitions` と `review_verdict` の旧値は `pass` → `complete`、`conditional_pass` → `complete-with-findings`、`changes_requested` → `incomplete`、`blocked` → `grade-stale` / `grade-unavailable` / `changed-during-review` のいずれかへ移ります。review result の旧 `decision.recommendation` は `verdict` へ置き換わり、`approve` は `complete` または `complete-with-findings`、`revise` と `reject` は `incomplete` へ移ります。
|
|
337
377
|
|
|
338
|
-
|
|
339
|
-
| -------------- | -------------------------------------------------------------------------------------------------------------------------------- |
|
|
340
|
-
| severity | `blocker` / `major` / `minor` / `note` |
|
|
341
|
-
| category | `purpose` / `planning` / `business` / `architecture` / `implementation` / `quality` / `usability` / `operations` / `consistency` |
|
|
342
|
-
| location | 見出し、行、キー、またはファイル全体 |
|
|
343
|
-
| summary | 指摘概要 |
|
|
344
|
-
| recommendation | 修正方針 |
|
|
378
|
+
## 4. レビュー結果の記録
|
|
345
379
|
|
|
346
|
-
|
|
380
|
+
review result に何をどう残し、未充足事項をどう分類し、どこへ引き継ぐかを扱います。
|
|
347
381
|
|
|
348
|
-
### 4.
|
|
382
|
+
### 4.1. レビュー結果の残し方
|
|
383
|
+
|
|
384
|
+
review result はタスク単位で記録します。review result は必ず review plan に対応させ、Frontmatter の `plan_ref` で参照します。
|
|
385
|
+
|
|
386
|
+
- `評価結果の確認` には、鮮度確認で実行したコマンドと出力、grade の `verdict` / `score` / finding 件数を書きます。評価結果が最新でない、または評価不能の場合は、その事実と理由を書きます。
|
|
387
|
+
- `判断根拠` には、照合した変更内容・plan・実行記録・完了条件・finding と、verdict を選んだ理由を書きます。
|
|
388
|
+
- `未充足事項・改善指示` には、未充足事項と改善指示を書きます。grade の finding を書き写すのではなく、このタスクの完了に何が足りないか、次に何をすべきかを書きます。
|
|
389
|
+
- `decision` には `verdict` を書きます。PO 判断が必要な事項は、判断根拠に明記し PJR へ接続します。
|
|
390
|
+
|
|
391
|
+
### 4.2. 未充足事項の分類
|
|
392
|
+
|
|
393
|
+
未充足事項や改善指示を書くときは、次の種別で性質を示します。grade の finding を分類し直すためのものではありません。
|
|
349
394
|
|
|
350
395
|
| 種別 | 内容 |
|
|
351
396
|
| ---------------- | ------------------------------------------------ |
|
|
@@ -353,13 +398,13 @@ review result に何をどう残し、findings をどう分類し、どこへ引
|
|
|
353
398
|
| inconsistency | 成果物間で矛盾している |
|
|
354
399
|
| unsupported | 上位根拠のない記述がある |
|
|
355
400
|
| ambiguous | 判断、実装、検証に必要な具体性が不足している |
|
|
356
|
-
| unverifiable |
|
|
401
|
+
| unverifiable | 完了を判断できない |
|
|
357
402
|
| risk | 後続作業、公開、運用で問題になる可能性がある |
|
|
358
403
|
| policy_violation | 禁止事項、承認責任、agent 委任境界に違反している |
|
|
359
404
|
|
|
360
405
|
### 4.3. PJR への転記
|
|
361
406
|
|
|
362
|
-
|
|
407
|
+
すべての未充足事項を PJR に転記しません。review result には詳細を残し、プロジェクト管理対象だけを PJR に転記します。
|
|
363
408
|
|
|
364
409
|
PJR に転記する条件
|
|
365
410
|
|
|
@@ -374,45 +419,37 @@ PJR に転記する条件
|
|
|
374
419
|
### 5.1. 単体レビュー
|
|
375
420
|
|
|
376
421
|
```text
|
|
377
|
-
review plan
|
|
378
|
-
|
|
379
|
-
|
|
380
|
-
|
|
381
|
-
### 5.2. トレーサビリティレビュー
|
|
382
|
-
|
|
383
|
-
```text
|
|
384
|
-
対象成果物を単体でレビューせず、上位成果物と下位成果物の対応を確認してください。
|
|
385
|
-
上位から下位への未展開、下位から上位への根拠なし、横断観点の抜けを findings として整理してください。
|
|
422
|
+
review plan に従って、このタスクを完了してよいかを判断してください。
|
|
423
|
+
成果物を再評価せず、plan の「評価結果」に示された grade の結果を事実として受け取ってください。
|
|
424
|
+
最初に評価結果の鮮度を確認し、変更内容・plan・実行記録・完了条件を照合して、verdict(complete / complete-with-findings / incomplete / grade-stale / grade-unavailable / changed-during-review)を review result に記録してください。
|
|
386
425
|
```
|
|
387
426
|
|
|
388
|
-
### 5.
|
|
427
|
+
### 5.2. 再計画後の再レビュー
|
|
389
428
|
|
|
390
429
|
```text
|
|
391
|
-
|
|
392
|
-
|
|
430
|
+
前回の review result の未充足事項・改善指示が、今回の変更と最新の評価結果で解消しているかを確認してください。
|
|
431
|
+
成果物を再評価せず、解消した事項、未解消の事項、新たに生じた未充足事項を根拠付きで記録してください。
|
|
393
432
|
```
|
|
394
433
|
|
|
395
|
-
### 5.
|
|
434
|
+
### 5.3. 評価結果に疑義がある場合
|
|
396
435
|
|
|
397
436
|
```text
|
|
398
|
-
|
|
399
|
-
|
|
437
|
+
評価結果の内容に疑義がある場合も、review で観点を評価し直さないでください。
|
|
438
|
+
疑義の内容、対象の finding または観点、再評価が必要な理由を未充足事項・改善指示に記録してください。
|
|
400
439
|
```
|
|
401
440
|
|
|
402
441
|
## 6. 完了と確定
|
|
403
442
|
|
|
404
|
-
|
|
443
|
+
review を完了と見なす条件と、成果物を `ready` へ昇格させる条件を扱います。
|
|
405
444
|
|
|
406
445
|
### 6.1. 完了条件
|
|
407
446
|
|
|
408
|
-
|
|
447
|
+
review を完了とするには、次を満たします。
|
|
409
448
|
|
|
410
|
-
-
|
|
411
|
-
-
|
|
412
|
-
-
|
|
413
|
-
-
|
|
414
|
-
- 未確認範囲がある場合は `notes` に残しています。
|
|
415
|
-
- `blocker` と `major` の未解決指摘が扱われています。
|
|
449
|
+
- 評価結果の鮮度を確認したコマンドと出力が記録されています。
|
|
450
|
+
- verdict が 6 値のいずれかで記録され、選んだ理由が判断根拠に書かれています。
|
|
451
|
+
- 完了条件(`done_criteria`)の照合結果が判断根拠に書かれています。
|
|
452
|
+
- finding が残るのに完了とした場合は、完了を妨げない理由と改善指示が記録されています。
|
|
416
453
|
- PO 判断が必要な事項は PJR または decision に接続されています。
|
|
417
454
|
- agent が最終承認者になっていません。
|
|
418
455
|
|
|
@@ -420,7 +457,7 @@ review plan に従って対象成果物をレビューしてください。
|
|
|
420
457
|
|
|
421
458
|
成果物を完成版または `ready` 候補にするには、次をすべて満たすことが必要です。
|
|
422
459
|
|
|
423
|
-
- 対象成果物の `
|
|
460
|
+
- 対象成果物の review タスクが `complete` または `complete-with-findings` で完了しています。
|
|
424
461
|
- `blocker` と `major` の未解決指摘が 0 件です。
|
|
425
462
|
- 条件付き合格とした指摘が PO により許容または対応済みと判断されています。
|
|
426
463
|
- 関連する PJR がある場合、対応方針、担当 Role code、期限が記録されています。
|