@brucewaynedecoy/make-docs 1.0.0-rc.1 → 2.0.2
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/LICENSE +21 -201
- package/README.md +36 -27
- package/dist/backup-73HQNKMC.js +20 -0
- package/dist/backup-73HQNKMC.js.map +1 -0
- package/dist/chunk-3BAJQXGH.js +1575 -0
- package/dist/chunk-3BAJQXGH.js.map +1 -0
- package/dist/chunk-64CTKJO7.js +4136 -0
- package/dist/chunk-64CTKJO7.js.map +1 -0
- package/dist/chunk-BENO4IH5.js +875 -0
- package/dist/chunk-BENO4IH5.js.map +1 -0
- package/dist/chunk-D4HDZEJT.js +37 -0
- package/dist/chunk-D4HDZEJT.js.map +1 -0
- package/dist/chunk-G5EF63GG.js +1291 -0
- package/dist/chunk-G5EF63GG.js.map +1 -0
- package/dist/chunk-GNP6HRVP.js +523 -0
- package/dist/chunk-GNP6HRVP.js.map +1 -0
- package/dist/chunk-HJYIQTMD.js +204 -0
- package/dist/chunk-HJYIQTMD.js.map +1 -0
- package/dist/chunk-LQ5NSWCJ.js +39 -0
- package/dist/chunk-LQ5NSWCJ.js.map +1 -0
- package/dist/chunk-LRVV7UDD.js +2340 -0
- package/dist/chunk-LRVV7UDD.js.map +1 -0
- package/dist/chunk-LVQSJF63.js +24674 -0
- package/dist/chunk-LVQSJF63.js.map +1 -0
- package/dist/chunk-MXBHCHSM.js +13995 -0
- package/dist/chunk-MXBHCHSM.js.map +1 -0
- package/dist/chunk-Z5K4FHYP.js +922 -0
- package/dist/chunk-Z5K4FHYP.js.map +1 -0
- package/dist/index.js +3798 -250
- package/dist/index.js.map +1 -1
- package/dist/self-YYXOLDKU.js +653 -0
- package/dist/self-YYXOLDKU.js.map +1 -0
- package/dist/server-O2ZELIMX.js +512 -0
- package/dist/server-O2ZELIMX.js.map +1 -0
- package/dist/setup-system-HZROFNMP.js +544 -0
- package/dist/setup-system-HZROFNMP.js.map +1 -0
- package/dist/{skills-command-3ESCZ75U.js → skills-command-MGGHY7HU.js} +190 -32
- package/dist/skills-command-MGGHY7HU.js.map +1 -0
- package/dist/uninstall-3UXXXNFO.js +223 -0
- package/dist/uninstall-3UXXXNFO.js.map +1 -0
- package/dist/virtual_make-docs-first-party-skills-ZII74YOB.js +11 -0
- package/dist/virtual_make-docs-first-party-skills-ZII74YOB.js.map +1 -0
- package/package.json +9 -6
- package/skill-registry.json +328 -125
- package/skill-registry.schema.json +221 -45
- package/template/.make-docs/AGENTS.md +18 -0
- package/template/.make-docs/CLAUDE.md +18 -0
- package/template/.make-docs/archive/AGENTS.md +11 -0
- package/template/.make-docs/archive/CLAUDE.md +11 -0
- package/template/.make-docs/system/AGENTS.md +12 -0
- package/template/.make-docs/system/CLAUDE.md +12 -0
- package/template/.make-docs/system/contracts/AGENTS.md +13 -0
- package/template/.make-docs/system/contracts/CLAUDE.md +13 -0
- package/template/{docs/assets/references → .make-docs/system/contracts}/commit-message-convention.md +4 -4
- package/template/.make-docs/system/contracts/coverage-pass-contract.md +198 -0
- package/template/.make-docs/system/contracts/deferred-obligation-contract.md +128 -0
- package/template/{docs/assets/references → .make-docs/system/contracts}/design-contract.md +7 -2
- package/template/{docs/assets/references → .make-docs/system/contracts}/guide-contract.md +21 -19
- package/template/{docs/assets/references → .make-docs/system/contracts}/history-record-contract.md +17 -11
- package/template/.make-docs/system/contracts/human-experience-contract.md +134 -0
- package/template/.make-docs/system/contracts/naive-uat-contract.md +231 -0
- package/template/.make-docs/system/contracts/output-contract.md +277 -0
- package/template/.make-docs/system/contracts/performance-evidence-governance.md +257 -0
- package/template/.make-docs/system/contracts/system-resource-contract.md +93 -0
- package/template/.make-docs/system/prompts/AGENTS.md +12 -0
- package/template/.make-docs/system/prompts/CLAUDE.md +12 -0
- package/template/.make-docs/system/prompts/coverage-pass-maintainer-guide.prompt.md +20 -0
- package/template/.make-docs/system/prompts/coverage-pass-prd-reconciliation.prompt.md +18 -0
- package/template/.make-docs/system/prompts/coverage-pass-testing-uat.prompt.md +46 -0
- package/template/.make-docs/system/prompts/coverage-pass-user-guide.prompt.md +20 -0
- package/template/.make-docs/system/prompts/designs-to-plan-change.prompt.md +18 -0
- package/template/.make-docs/system/prompts/designs-to-plan.prompt.md +14 -0
- package/template/.make-docs/system/prompts/docs-path-hygiene-cleanup.prompt.md +29 -0
- package/template/.make-docs/system/prompts/naive-uat-facilitator.prompt.md +28 -0
- package/template/.make-docs/system/prompts/naive-uat-tester.prompt.md +20 -0
- package/template/.make-docs/system/prompts/performance-coverage.prompt.md +63 -0
- package/template/.make-docs/system/prompts/plan-to-prd-change.prompt.md +12 -0
- package/template/.make-docs/system/prompts/plan-to-prd-green-field.prompt.md +10 -0
- package/template/.make-docs/system/prompts/prd-change-to-work.prompt.md +14 -0
- package/template/.make-docs/system/prompts/prd-to-work-full-prd.prompt.md +10 -0
- package/template/.make-docs/system/prompts/prd-to-work-prd-feature.prompt.md +10 -0
- package/template/.make-docs/system/prompts/request-to-design.prompt.md +20 -0
- package/template/.make-docs/system/prompts/session-to-history-record.prompt.md +23 -0
- package/template/{docs/assets → .make-docs/system}/prompts/work-to-commit-message.prompt.md +2 -2
- package/template/.make-docs/system/prompts/work-to-guides.prompt.md +22 -0
- package/template/.make-docs/system/references/AGENTS.md +14 -0
- package/template/.make-docs/system/references/CLAUDE.md +14 -0
- package/template/{docs/assets → .make-docs/system}/references/design-workflow.md +15 -2
- package/template/.make-docs/system/references/execution-workflow.md +189 -0
- package/template/.make-docs/system/references/human-experience.md +138 -0
- package/template/.make-docs/system/references/lifecycle.md +153 -0
- package/template/.make-docs/system/references/naive-uat-validation.md +65 -0
- package/template/.make-docs/system/references/naive-uat-workflow.md +64 -0
- package/template/.make-docs/system/references/path-and-link-hygiene.md +101 -0
- package/template/.make-docs/system/references/performance-evidence.md +114 -0
- package/template/.make-docs/system/references/planning-workflow.md +209 -0
- package/template/.make-docs/system/references/prd-change-management.md +165 -0
- package/template/{docs/assets → .make-docs/system}/references/wave-model.md +10 -8
- package/template/.make-docs/system/templates/AGENTS.md +12 -0
- package/template/.make-docs/system/templates/CLAUDE.md +12 -0
- package/template/.make-docs/system/templates/design.md +79 -0
- package/template/{docs/assets/templates/guide-developer.md → .make-docs/system/templates/guide-maintainer.md} +7 -3
- package/template/{docs/assets → .make-docs/system}/templates/guide-user.md +6 -2
- package/template/{docs/assets → .make-docs/system}/templates/history-record.md +6 -3
- package/template/.make-docs/system/templates/naive-uat-scenario.md +91 -0
- package/template/.make-docs/system/templates/performance-evidence-profile.md +252 -0
- package/template/.make-docs/system/templates/plan-overview.md +76 -0
- package/template/.make-docs/system/templates/plan-prd-change.md +155 -0
- package/template/{docs/assets → .make-docs/system}/templates/plan-prd-decompose.md +10 -0
- package/template/{docs/assets → .make-docs/system}/templates/plan-prd.md +28 -2
- package/template/{docs/assets → .make-docs/system}/templates/prd-architecture.md +13 -0
- package/template/.make-docs/system/templates/prd-glossary.md +28 -0
- package/template/.make-docs/system/templates/prd-index.md +70 -0
- package/template/{docs/assets → .make-docs/system}/templates/prd-overview.md +13 -0
- package/template/.make-docs/system/templates/prd-reference.md +30 -0
- package/template/{docs/assets → .make-docs/system}/templates/prd-risk-register.md +16 -1
- package/template/{docs/assets → .make-docs/system}/templates/prd-subsystem.md +15 -0
- package/template/.make-docs/system/templates/work-index.md +58 -0
- package/template/.make-docs/system/templates/work-phase.md +107 -0
- package/template/.make-docs/system-resources.catalog.json +91 -0
- package/template/.make-docs/system-resources.schema.json +204 -0
- package/template/AGENTS.md +8 -1
- package/template/CLAUDE.md +8 -1
- package/template/docs/AGENTS.codex-only.md +22 -0
- package/template/docs/AGENTS.md +21 -13
- package/template/docs/CLAUDE.claude-only.md +22 -0
- package/template/docs/CLAUDE.md +21 -13
- package/template/docs/assets/AGENTS.md +11 -7
- package/template/docs/assets/CLAUDE.md +11 -7
- package/template/docs/designs/AGENTS.md +8 -3
- package/template/docs/designs/CLAUDE.md +8 -3
- package/template/docs/plans/AGENTS.md +10 -3
- package/template/docs/plans/CLAUDE.md +10 -3
- package/template/docs/prd/AGENTS.md +14 -4
- package/template/docs/prd/CLAUDE.md +14 -4
- package/template/docs/work/AGENTS.md +10 -3
- package/template/docs/work/CLAUDE.md +10 -3
- package/dist/chunk-HP3HBG7F.js +0 -626
- package/dist/chunk-HP3HBG7F.js.map +0 -1
- package/dist/chunk-QRFH4J6H.js +0 -1194
- package/dist/chunk-QRFH4J6H.js.map +0 -1
- package/dist/chunk-WM3OXYTW.js +0 -2630
- package/dist/chunk-WM3OXYTW.js.map +0 -1
- package/dist/skills-command-3ESCZ75U.js.map +0 -1
- package/dist/uninstall-GQE4SJF2.js +0 -150
- package/dist/uninstall-GQE4SJF2.js.map +0 -1
- package/template/.make-docs/scripts/check_path_hygiene.py +0 -435
- package/template/docs/assets/archive/AGENTS.md +0 -20
- package/template/docs/assets/archive/CLAUDE.md +0 -20
- package/template/docs/assets/history/AGENTS.md +0 -12
- package/template/docs/assets/history/CLAUDE.md +0 -12
- package/template/docs/assets/prompts/AGENTS.md +0 -8
- package/template/docs/assets/prompts/CLAUDE.md +0 -8
- package/template/docs/assets/prompts/designs-to-plan-change.prompt.md +0 -14
- package/template/docs/assets/prompts/designs-to-plan.prompt.md +0 -10
- package/template/docs/assets/prompts/docs-path-hygiene-cleanup.prompt.md +0 -27
- package/template/docs/assets/prompts/plan-to-prd-change.prompt.md +0 -8
- package/template/docs/assets/prompts/plan-to-prd-green-field.prompt.md +0 -6
- package/template/docs/assets/prompts/prd-change-to-work.prompt.md +0 -10
- package/template/docs/assets/prompts/prd-to-work-full-prd.prompt.md +0 -6
- package/template/docs/assets/prompts/prd-to-work-prd-feature.prompt.md +0 -6
- package/template/docs/assets/prompts/request-to-design.prompt.md +0 -16
- package/template/docs/assets/prompts/session-to-history-record.prompt.md +0 -19
- package/template/docs/assets/prompts/work-to-guides.prompt.md +0 -18
- package/template/docs/assets/references/AGENTS.md +0 -9
- package/template/docs/assets/references/CLAUDE.md +0 -9
- package/template/docs/assets/references/execution-workflow.md +0 -157
- package/template/docs/assets/references/output-contract.md +0 -221
- package/template/docs/assets/references/path-and-link-hygiene.md +0 -49
- package/template/docs/assets/references/planning-workflow.md +0 -160
- package/template/docs/assets/references/prd-change-management.md +0 -129
- package/template/docs/assets/templates/AGENTS.md +0 -8
- package/template/docs/assets/templates/CLAUDE.md +0 -8
- package/template/docs/assets/templates/design.md +0 -30
- package/template/docs/assets/templates/plan-overview.md +0 -32
- package/template/docs/assets/templates/plan-prd-change.md +0 -99
- package/template/docs/assets/templates/prd-change-addition.md +0 -45
- package/template/docs/assets/templates/prd-change-revision.md +0 -45
- package/template/docs/assets/templates/prd-glossary.md +0 -15
- package/template/docs/assets/templates/prd-index.md +0 -45
- package/template/docs/assets/templates/prd-reference.md +0 -17
- package/template/docs/assets/templates/work-index.md +0 -21
- package/template/docs/assets/templates/work-phase.md +0 -34
- package/template/docs/guides/AGENTS.md +0 -15
- package/template/docs/guides/CLAUDE.md +0 -15
- /package/template/{docs/assets → .make-docs/system}/prompts/update-readme-green-field.prompt.md +0 -0
- /package/template/{docs/assets → .make-docs/system}/references/harness-capability-matrix.md +0 -0
|
@@ -1,61 +1,237 @@
|
|
|
1
1
|
{
|
|
2
2
|
"$schema": "https://json-schema.org/draft/2020-12/schema",
|
|
3
3
|
"$id": "./skill-registry.schema.json",
|
|
4
|
-
"title": "make-docs skill registry",
|
|
4
|
+
"title": "make-docs skill registry manifest",
|
|
5
5
|
"type": "object",
|
|
6
6
|
"additionalProperties": false,
|
|
7
|
-
"required": [
|
|
7
|
+
"required": [
|
|
8
|
+
"schemaVersion",
|
|
9
|
+
"manifestId",
|
|
10
|
+
"displayName",
|
|
11
|
+
"purposes",
|
|
12
|
+
"sourcePolicy",
|
|
13
|
+
"skills"
|
|
14
|
+
],
|
|
8
15
|
"properties": {
|
|
16
|
+
"$schema": {
|
|
17
|
+
"type": "string"
|
|
18
|
+
},
|
|
19
|
+
"schemaVersion": {
|
|
20
|
+
"type": "integer",
|
|
21
|
+
"minimum": 1
|
|
22
|
+
},
|
|
23
|
+
"manifestId": {
|
|
24
|
+
"type": "string",
|
|
25
|
+
"minLength": 1
|
|
26
|
+
},
|
|
27
|
+
"displayName": {
|
|
28
|
+
"type": "string",
|
|
29
|
+
"minLength": 1
|
|
30
|
+
},
|
|
31
|
+
"description": {
|
|
32
|
+
"type": "string"
|
|
33
|
+
},
|
|
34
|
+
"sourcePolicy": {
|
|
35
|
+
"$ref": "#/$defs/sourcePolicy"
|
|
36
|
+
},
|
|
37
|
+
"purposes": {
|
|
38
|
+
"type": "array",
|
|
39
|
+
"items": {
|
|
40
|
+
"$ref": "#/$defs/purpose"
|
|
41
|
+
}
|
|
42
|
+
},
|
|
9
43
|
"skills": {
|
|
10
44
|
"type": "array",
|
|
11
45
|
"items": {
|
|
12
|
-
"
|
|
13
|
-
|
|
14
|
-
|
|
15
|
-
|
|
16
|
-
|
|
17
|
-
|
|
18
|
-
|
|
19
|
-
|
|
20
|
-
|
|
21
|
-
|
|
22
|
-
"
|
|
23
|
-
|
|
24
|
-
|
|
25
|
-
|
|
26
|
-
|
|
27
|
-
|
|
28
|
-
"
|
|
29
|
-
"
|
|
30
|
-
|
|
31
|
-
|
|
46
|
+
"$ref": "#/$defs/skill"
|
|
47
|
+
}
|
|
48
|
+
}
|
|
49
|
+
},
|
|
50
|
+
"$defs": {
|
|
51
|
+
"sourcePolicy": {
|
|
52
|
+
"type": "object",
|
|
53
|
+
"additionalProperties": false,
|
|
54
|
+
"required": [
|
|
55
|
+
"kind",
|
|
56
|
+
"label"
|
|
57
|
+
],
|
|
58
|
+
"properties": {
|
|
59
|
+
"kind": {
|
|
60
|
+
"enum": [
|
|
61
|
+
"first-party",
|
|
62
|
+
"local",
|
|
63
|
+
"remote-pinned"
|
|
64
|
+
]
|
|
65
|
+
},
|
|
66
|
+
"label": {
|
|
67
|
+
"type": "string",
|
|
68
|
+
"minLength": 1
|
|
69
|
+
},
|
|
70
|
+
"allowRemoteSkillSources": {
|
|
71
|
+
"type": "boolean"
|
|
72
|
+
}
|
|
73
|
+
}
|
|
74
|
+
},
|
|
75
|
+
"provenance": {
|
|
76
|
+
"type": "object",
|
|
77
|
+
"additionalProperties": false,
|
|
78
|
+
"required": [
|
|
79
|
+
"kind",
|
|
80
|
+
"label"
|
|
81
|
+
],
|
|
82
|
+
"properties": {
|
|
83
|
+
"kind": {
|
|
84
|
+
"enum": [
|
|
85
|
+
"first-party",
|
|
86
|
+
"local",
|
|
87
|
+
"remote-pinned",
|
|
88
|
+
"third-party"
|
|
89
|
+
]
|
|
90
|
+
},
|
|
91
|
+
"label": {
|
|
92
|
+
"type": "string",
|
|
93
|
+
"minLength": 1
|
|
94
|
+
},
|
|
95
|
+
"manifestId": {
|
|
96
|
+
"type": "string",
|
|
97
|
+
"minLength": 1
|
|
98
|
+
},
|
|
99
|
+
"repository": {
|
|
100
|
+
"type": "string",
|
|
101
|
+
"minLength": 1
|
|
102
|
+
},
|
|
103
|
+
"ref": {
|
|
104
|
+
"type": "string",
|
|
105
|
+
"minLength": 1
|
|
106
|
+
},
|
|
107
|
+
"digest": {
|
|
108
|
+
"type": "string",
|
|
109
|
+
"minLength": 1
|
|
110
|
+
}
|
|
111
|
+
}
|
|
112
|
+
},
|
|
113
|
+
"purpose": {
|
|
114
|
+
"type": "object",
|
|
115
|
+
"additionalProperties": false,
|
|
116
|
+
"required": [
|
|
117
|
+
"id",
|
|
118
|
+
"label",
|
|
119
|
+
"description",
|
|
120
|
+
"provenance"
|
|
121
|
+
],
|
|
122
|
+
"properties": {
|
|
123
|
+
"id": {
|
|
124
|
+
"type": "string",
|
|
125
|
+
"minLength": 1
|
|
126
|
+
},
|
|
127
|
+
"label": {
|
|
128
|
+
"type": "string",
|
|
129
|
+
"minLength": 1
|
|
130
|
+
},
|
|
131
|
+
"description": {
|
|
132
|
+
"type": "string",
|
|
133
|
+
"minLength": 1
|
|
134
|
+
},
|
|
135
|
+
"order": {
|
|
136
|
+
"type": "integer"
|
|
137
|
+
},
|
|
138
|
+
"provenance": {
|
|
139
|
+
"$ref": "#/$defs/provenance"
|
|
140
|
+
}
|
|
141
|
+
}
|
|
142
|
+
},
|
|
143
|
+
"asset": {
|
|
144
|
+
"type": "object",
|
|
145
|
+
"additionalProperties": false,
|
|
146
|
+
"required": [
|
|
147
|
+
"source",
|
|
148
|
+
"installPath"
|
|
149
|
+
],
|
|
150
|
+
"properties": {
|
|
151
|
+
"source": {
|
|
152
|
+
"type": "string",
|
|
153
|
+
"minLength": 1
|
|
154
|
+
},
|
|
155
|
+
"installPath": {
|
|
156
|
+
"type": "string",
|
|
157
|
+
"minLength": 1
|
|
158
|
+
}
|
|
159
|
+
}
|
|
160
|
+
},
|
|
161
|
+
"skill": {
|
|
162
|
+
"type": "object",
|
|
163
|
+
"additionalProperties": false,
|
|
164
|
+
"required": [
|
|
165
|
+
"name",
|
|
166
|
+
"displayName",
|
|
167
|
+
"source",
|
|
168
|
+
"entryPoint",
|
|
169
|
+
"installName",
|
|
170
|
+
"description",
|
|
171
|
+
"purposes",
|
|
172
|
+
"supportedHarnesses",
|
|
173
|
+
"provenance",
|
|
174
|
+
"assets"
|
|
175
|
+
],
|
|
176
|
+
"properties": {
|
|
177
|
+
"name": {
|
|
178
|
+
"type": "string",
|
|
179
|
+
"minLength": 1
|
|
180
|
+
},
|
|
181
|
+
"displayName": {
|
|
182
|
+
"type": "string",
|
|
183
|
+
"minLength": 1
|
|
184
|
+
},
|
|
185
|
+
"source": {
|
|
186
|
+
"type": "string",
|
|
187
|
+
"minLength": 1,
|
|
188
|
+
"description": "First-party sources use embedded:<name>; explicit alternate manifests retain their local or pinned remote source policy."
|
|
189
|
+
},
|
|
190
|
+
"entryPoint": {
|
|
191
|
+
"type": "string",
|
|
192
|
+
"minLength": 1
|
|
193
|
+
},
|
|
194
|
+
"installName": {
|
|
195
|
+
"type": "string",
|
|
196
|
+
"minLength": 1
|
|
197
|
+
},
|
|
198
|
+
"description": {
|
|
199
|
+
"type": "string",
|
|
200
|
+
"minLength": 1
|
|
201
|
+
},
|
|
202
|
+
"purposes": {
|
|
203
|
+
"type": "array",
|
|
204
|
+
"minItems": 1,
|
|
205
|
+
"items": {
|
|
32
206
|
"type": "string",
|
|
33
207
|
"minLength": 1
|
|
34
|
-
}
|
|
35
|
-
|
|
208
|
+
}
|
|
209
|
+
},
|
|
210
|
+
"supportedHarnesses": {
|
|
211
|
+
"type": "array",
|
|
212
|
+
"minItems": 1,
|
|
213
|
+
"uniqueItems": true,
|
|
214
|
+
"items": {
|
|
215
|
+
"enum": [
|
|
216
|
+
"claude-code",
|
|
217
|
+
"codex"
|
|
218
|
+
]
|
|
219
|
+
}
|
|
220
|
+
},
|
|
221
|
+
"provenance": {
|
|
222
|
+
"$ref": "#/$defs/provenance"
|
|
223
|
+
},
|
|
224
|
+
"defaultForPurposes": {
|
|
225
|
+
"type": "array",
|
|
226
|
+
"items": {
|
|
36
227
|
"type": "string",
|
|
37
228
|
"minLength": 1
|
|
38
|
-
}
|
|
39
|
-
|
|
40
|
-
|
|
41
|
-
|
|
42
|
-
"
|
|
43
|
-
"
|
|
44
|
-
"items": {
|
|
45
|
-
"type": "object",
|
|
46
|
-
"additionalProperties": false,
|
|
47
|
-
"required": ["source", "installPath"],
|
|
48
|
-
"properties": {
|
|
49
|
-
"source": {
|
|
50
|
-
"type": "string",
|
|
51
|
-
"minLength": 1
|
|
52
|
-
},
|
|
53
|
-
"installPath": {
|
|
54
|
-
"type": "string",
|
|
55
|
-
"minLength": 1
|
|
56
|
-
}
|
|
57
|
-
}
|
|
58
|
-
}
|
|
229
|
+
}
|
|
230
|
+
},
|
|
231
|
+
"assets": {
|
|
232
|
+
"type": "array",
|
|
233
|
+
"items": {
|
|
234
|
+
"$ref": "#/$defs/asset"
|
|
59
235
|
}
|
|
60
236
|
}
|
|
61
237
|
}
|
|
@@ -0,0 +1,18 @@
|
|
|
1
|
+
<!-- make-docs:begin -->
|
|
2
|
+
# Make Docs System Router
|
|
3
|
+
|
|
4
|
+
This directory owns the resource catalog, the always-local router skeleton, declarative project settings, installed content, and source evidence.
|
|
5
|
+
|
|
6
|
+
- Read `.make-docs/system-resources.catalog.json` for the current resource inventory and `.make-docs/system-resources.schema.json` for its shape.
|
|
7
|
+
- Use `.make-docs/system/contracts/`, `.make-docs/system/prompts/`, `.make-docs/system/references/`, and `.make-docs/system/templates/` for the four current resource types.
|
|
8
|
+
- Use a valid local resource body first. If the body is absent, read its stable `make-docs://system/<type>/<posix-relative-path>` URI with `make-docs resource read`.
|
|
9
|
+
- Resource selection controls optional bodies only. It does not remove this router, `.make-docs/system/`, or any typed router.
|
|
10
|
+
- The installed provider supplies resource bytes when no valid local body exists. A local body must retain recorded provider and hash evidence.
|
|
11
|
+
- Install selected Skills only at standard agent Skill paths for the chosen scope and harnesses. Keep installation state in the global Store; do not create a private `.make-docs` Skill layer.
|
|
12
|
+
- Make Docs installation and operation state belongs only in the global Make Docs Store, managed through the CLI. This includes applied hashes, provenance, migration receipts, locks, conflict decisions, and recovery records. Never create project-local operational state or write directly to the Store.
|
|
13
|
+
- Treat `.make-docs/manifest.json` and `.make-docs/state/` only as legacy CLI transfer inputs. Do not repair, recreate, or delete them by hand. Use `make-docs project state status` for state and safe next steps.
|
|
14
|
+
- Keep declarative identity and desired settings in project config. Local backup, conflict, and archive file copies may remain under their content contracts. Their live recovery metadata belongs in the Store.
|
|
15
|
+
- If the CLI is unavailable or optional lifecycle capture fails, continue ordinary project work and report capture as unavailable. Do not claim success, queue a later write, or create a local fallback. Required Store recording for CLI-managed changes remains mandatory; those changes stop safely when recording fails.
|
|
16
|
+
- Do not put project designs, plans, PRDs, work backlogs, archives, artifacts, guides, testing evidence, or other authored project documents here.
|
|
17
|
+
- Do not infer optional Skills, plugins, Playbooks, Protocols, or unavailable policy from this router.
|
|
18
|
+
<!-- make-docs:end -->
|
|
@@ -0,0 +1,18 @@
|
|
|
1
|
+
<!-- make-docs:begin -->
|
|
2
|
+
# Make Docs System Router
|
|
3
|
+
|
|
4
|
+
This directory owns the resource catalog, the always-local router skeleton, declarative project settings, installed content, and source evidence.
|
|
5
|
+
|
|
6
|
+
- Read `.make-docs/system-resources.catalog.json` for the current resource inventory and `.make-docs/system-resources.schema.json` for its shape.
|
|
7
|
+
- Use `.make-docs/system/contracts/`, `.make-docs/system/prompts/`, `.make-docs/system/references/`, and `.make-docs/system/templates/` for the four current resource types.
|
|
8
|
+
- Use a valid local resource body first. If the body is absent, read its stable `make-docs://system/<type>/<posix-relative-path>` URI with `make-docs resource read`.
|
|
9
|
+
- Resource selection controls optional bodies only. It does not remove this router, `.make-docs/system/`, or any typed router.
|
|
10
|
+
- The installed provider supplies resource bytes when no valid local body exists. A local body must retain recorded provider and hash evidence.
|
|
11
|
+
- Install selected Skills only at standard agent Skill paths for the chosen scope and harnesses. Keep installation state in the global Store; do not create a private `.make-docs` Skill layer.
|
|
12
|
+
- Make Docs installation and operation state belongs only in the global Make Docs Store, managed through the CLI. This includes applied hashes, provenance, migration receipts, locks, conflict decisions, and recovery records. Never create project-local operational state or write directly to the Store.
|
|
13
|
+
- Treat `.make-docs/manifest.json` and `.make-docs/state/` only as legacy CLI transfer inputs. Do not repair, recreate, or delete them by hand. Use `make-docs project state status` for state and safe next steps.
|
|
14
|
+
- Keep declarative identity and desired settings in project config. Local backup, conflict, and archive file copies may remain under their content contracts. Their live recovery metadata belongs in the Store.
|
|
15
|
+
- If the CLI is unavailable or optional lifecycle capture fails, continue ordinary project work and report capture as unavailable. Do not claim success, queue a later write, or create a local fallback. Required Store recording for CLI-managed changes remains mandatory; those changes stop safely when recording fails.
|
|
16
|
+
- Do not put project designs, plans, PRDs, work backlogs, archives, artifacts, guides, testing evidence, or other authored project documents here.
|
|
17
|
+
- Do not infer optional Skills, plugins, Playbooks, Protocols, or unavailable policy from this router.
|
|
18
|
+
<!-- make-docs:end -->
|
|
@@ -0,0 +1,11 @@
|
|
|
1
|
+
<!-- make-docs:begin -->
|
|
2
|
+
# Archive Router
|
|
3
|
+
|
|
4
|
+
This directory holds historical and provenance records, not current product authority.
|
|
5
|
+
|
|
6
|
+
- Use `.make-docs/archive/history/` for session history. Preserve recorded outcomes and coordinates; repair links only through a recorded reviewed move.
|
|
7
|
+
- Before writing, use valid local `.make-docs/system/contracts/history-record-contract.md` and `.make-docs/system/templates/history-record.md`; read absent bodies with `make-docs resource read` at `make-docs://system/contract/history-record-contract.md` and `make-docs://system/template/history-record.md`.
|
|
8
|
+
- Shared material uses `docs/assets/project/`; audience assets use `docs/assets/<persona-slug>/`.
|
|
9
|
+
- Retired Playbooks stay inactive under `.make-docs/archive/legacy-playbooks/`. Do not infer a current workflow from them.
|
|
10
|
+
- Operational state stays in the global Store through the CLI. Archive or backup content is not an operational fallback.
|
|
11
|
+
<!-- make-docs:end -->
|
|
@@ -0,0 +1,11 @@
|
|
|
1
|
+
<!-- make-docs:begin -->
|
|
2
|
+
# Archive Router
|
|
3
|
+
|
|
4
|
+
This directory holds historical and provenance records, not current product authority.
|
|
5
|
+
|
|
6
|
+
- Use `.make-docs/archive/history/` for session history. Preserve recorded outcomes and coordinates; repair links only through a recorded reviewed move.
|
|
7
|
+
- Before writing, use valid local `.make-docs/system/contracts/history-record-contract.md` and `.make-docs/system/templates/history-record.md`; read absent bodies with `make-docs resource read` at `make-docs://system/contract/history-record-contract.md` and `make-docs://system/template/history-record.md`.
|
|
8
|
+
- Shared material uses `docs/assets/project/`; audience assets use `docs/assets/<persona-slug>/`.
|
|
9
|
+
- Retired Playbooks stay inactive under `.make-docs/archive/legacy-playbooks/`. Do not infer a current workflow from them.
|
|
10
|
+
- Operational state stays in the global Store through the CLI. Archive or backup content is not an operational fallback.
|
|
11
|
+
<!-- make-docs:end -->
|
|
@@ -0,0 +1,12 @@
|
|
|
1
|
+
<!-- make-docs:begin -->
|
|
2
|
+
# System Resources Router
|
|
3
|
+
|
|
4
|
+
This always-local directory routes the four peer Make Docs system-resource types. Resource bodies are optional.
|
|
5
|
+
|
|
6
|
+
- Use a valid local body in `contracts/`, `prompts/`, `references/`, or `templates/` first.
|
|
7
|
+
- If a required body is absent, read its stable `make-docs://system/<type>/<posix-relative-path>` URI with `make-docs resource read`.
|
|
8
|
+
- Resource selection controls bodies only. It does not remove this router or any typed directory router.
|
|
9
|
+
- Keep reusable policy in contracts and explanatory workflow guidance in references.
|
|
10
|
+
- Do not write generated project documentation here.
|
|
11
|
+
- Do not infer optional Skills, plugins, Playbooks, Protocols, or unavailable policy from this router.
|
|
12
|
+
<!-- make-docs:end -->
|
|
@@ -0,0 +1,12 @@
|
|
|
1
|
+
<!-- make-docs:begin -->
|
|
2
|
+
# System Resources Router
|
|
3
|
+
|
|
4
|
+
This always-local directory routes the four peer Make Docs system-resource types. Resource bodies are optional.
|
|
5
|
+
|
|
6
|
+
- Use a valid local body in `contracts/`, `prompts/`, `references/`, or `templates/` first.
|
|
7
|
+
- If a required body is absent, read its stable `make-docs://system/<type>/<posix-relative-path>` URI with `make-docs resource read`.
|
|
8
|
+
- Resource selection controls bodies only. It does not remove this router or any typed directory router.
|
|
9
|
+
- Keep reusable policy in contracts and explanatory workflow guidance in references.
|
|
10
|
+
- Do not write generated project documentation here.
|
|
11
|
+
- Do not infer optional Skills, plugins, Playbooks, Protocols, or unavailable policy from this router.
|
|
12
|
+
<!-- make-docs:end -->
|
|
@@ -0,0 +1,13 @@
|
|
|
1
|
+
<!-- make-docs:begin -->
|
|
2
|
+
# System Contracts Router
|
|
3
|
+
|
|
4
|
+
This always-local directory routes current Make Docs contracts. A contract defines reusable rules and constraints. Contract bodies are optional local projections.
|
|
5
|
+
|
|
6
|
+
- Use a valid local contract body first. If it is absent, read `make-docs://system/contract/<posix-relative-path>` with `make-docs resource read`.
|
|
7
|
+
- Read `system-resource-contract.md` before you add or change a resource root, catalog entry, identity, or workflow composition.
|
|
8
|
+
- Read only the other contract needed for the task.
|
|
9
|
+
- Use `.make-docs/system/references/` for explanatory workflow guidance and `.make-docs/system/templates/` for reusable output shapes.
|
|
10
|
+
- Use `naive-uat-contract.md` for Unassisted Goal Testing policy. Keep that policy out of routers, prompts, and Skills.
|
|
11
|
+
- Do not write generated project documentation here.
|
|
12
|
+
- Do not infer optional Skills, plugins, Playbooks, Protocols, or unavailable policy from this router.
|
|
13
|
+
<!-- make-docs:end -->
|
|
@@ -0,0 +1,13 @@
|
|
|
1
|
+
<!-- make-docs:begin -->
|
|
2
|
+
# System Contracts Router
|
|
3
|
+
|
|
4
|
+
This always-local directory routes current Make Docs contracts. A contract defines reusable rules and constraints. Contract bodies are optional local projections.
|
|
5
|
+
|
|
6
|
+
- Use a valid local contract body first. If it is absent, read `make-docs://system/contract/<posix-relative-path>` with `make-docs resource read`.
|
|
7
|
+
- Read `system-resource-contract.md` before you add or change a resource root, catalog entry, identity, or workflow composition.
|
|
8
|
+
- Read only the other contract needed for the task.
|
|
9
|
+
- Use `.make-docs/system/references/` for explanatory workflow guidance and `.make-docs/system/templates/` for reusable output shapes.
|
|
10
|
+
- Use `naive-uat-contract.md` for Unassisted Goal Testing policy. Keep that policy out of routers, prompts, and Skills.
|
|
11
|
+
- Do not write generated project documentation here.
|
|
12
|
+
- Do not infer optional Skills, plugins, Playbooks, Protocols, or unavailable policy from this router.
|
|
13
|
+
<!-- make-docs:end -->
|
package/template/{docs/assets/references → .make-docs/system/contracts}/commit-message-convention.md
RENAMED
|
@@ -24,9 +24,9 @@ Rules:
|
|
|
24
24
|
Example:
|
|
25
25
|
|
|
26
26
|
```text
|
|
27
|
-
feat: [W1 R2 P1] CLI Agent Terminology and Help Flags -
|
|
27
|
+
feat: [W1 R2 P1] CLI Agent Terminology and Help Flags - Authority Maintenance
|
|
28
28
|
|
|
29
|
-
|
|
29
|
+
Updates the owning CLI authority with the current REQ02 contract, records the prior requirement in its non-normative Requirement History, and marks W1 R2 P1 complete so downstream parser and documentation phases cite the effective `--agent`, `-a`, help, and rejected `--harness` requirements.
|
|
30
30
|
```
|
|
31
31
|
|
|
32
32
|
## Document Commits
|
|
@@ -88,7 +88,7 @@ Rules:
|
|
|
88
88
|
Body:
|
|
89
89
|
|
|
90
90
|
- Copy the first paragraph under `## Changes` from the matching history record.
|
|
91
|
-
- Prefer
|
|
91
|
+
- Prefer `.make-docs/archive/history/`.
|
|
92
92
|
- If the repo has not migrated yet, accept legacy history records identified by the legacy router.
|
|
93
93
|
- Do not include tables, documentation sections, verification lists, or extra commentary in the commit body.
|
|
94
94
|
|
|
@@ -97,7 +97,7 @@ Example:
|
|
|
97
97
|
```text
|
|
98
98
|
feat: [W8 R0 P5] CLI command simplification - Apply and sync output polish
|
|
99
99
|
|
|
100
|
-
Implemented a Wave 8 follow-up phase for the `make-docs` apply/sync review output, framed by the command simplification design (`docs/designs/2026-04-20-cli-command-simplification.md`) and the completed Phase 4 validation work in the Phase 4 history record (
|
|
100
|
+
Implemented a Wave 8 follow-up phase for the `make-docs` apply/sync review output, framed by the command simplification design (`docs/designs/2026-04-20-cli-command-simplification.md`) and the completed Phase 4 validation work in the Phase 4 history record (`.make-docs/archive/history/2026-04-20-w8-r0-p4-cli-command-simplification.md`). This phase focused on making the already-installed no-op sync readout clearer, less redundant, and consistent with Clack-rendered CLI screens.
|
|
101
101
|
```
|
|
102
102
|
|
|
103
103
|
## Plan Commits
|
|
@@ -0,0 +1,198 @@
|
|
|
1
|
+
# Coverage Pass Contract
|
|
2
|
+
|
|
3
|
+
## Purpose
|
|
4
|
+
|
|
5
|
+
Use this contract for closeout-style coverage passes that decide whether a completed change needs follow-on documentation, testing, PRD reconciliation, or history updates.
|
|
6
|
+
|
|
7
|
+
The contract owns the pass mechanics only: the skeleton, verdict vocabulary, surface mappings, Persona targeting, backlog evidence reports and acceptance-case captures, history idempotency, and validation checklist. It does not replace the detailed content contracts for guides, PRDs, work outputs, system resources, or history records.
|
|
8
|
+
|
|
9
|
+
## Pass Skeleton
|
|
10
|
+
|
|
11
|
+
Every coverage pass follows this seven-step skeleton:
|
|
12
|
+
|
|
13
|
+
1. Load the authority docs for the surface being checked.
|
|
14
|
+
2. Enumerate every candidate capability, behavior, workflow, artifact, or finding that may need coverage.
|
|
15
|
+
3. Assign one verdict to every candidate.
|
|
16
|
+
4. Prefer updating existing coverage over creating a new artifact when an existing artifact owns the topic.
|
|
17
|
+
5. Reconcile the session history record using the idempotency rule below.
|
|
18
|
+
6. Validate the changed or intentionally unchanged coverage.
|
|
19
|
+
7. Close the pass with a concise summary of verdicts, reasons, artifacts changed, validation run, and any remaining handoffs.
|
|
20
|
+
|
|
21
|
+
Do not skip a candidate silently. A candidate that needs no artifact still receives a `none` verdict and a reason.
|
|
22
|
+
|
|
23
|
+
## Base Verdict Spine
|
|
24
|
+
|
|
25
|
+
Coverage verdicts map to this shared spine:
|
|
26
|
+
|
|
27
|
+
| Verdict | Use when |
|
|
28
|
+
| --- | --- |
|
|
29
|
+
| `create` | A new artifact is warranted because no current artifact owns the topic. |
|
|
30
|
+
| `update-existing` | An existing artifact owns the topic and should be updated in place. |
|
|
31
|
+
| `link-only` | Existing coverage is sufficient, but discoverability improves through a pointer, related link, router entry, or handoff note. |
|
|
32
|
+
| `none` | No artifact or link change is warranted; record the reason instead of omitting the decision. |
|
|
33
|
+
|
|
34
|
+
The spine is semantic, not a required superset. Surface-specific verdicts may use different names when they map clearly to one spine verdict.
|
|
35
|
+
|
|
36
|
+
## Coverage Surfaces
|
|
37
|
+
|
|
38
|
+
### Guide And System-Resource Coverage
|
|
39
|
+
|
|
40
|
+
Guide and system-resource coverage uses the verdict spine directly: `create`, `update-existing`, `link-only`, or `none`.
|
|
41
|
+
|
|
42
|
+
Guide verdicts carry a configured Persona target when the guide is Persona-bearing. System-resource verdicts carry one of the four peer types: contract, prompt, reference, or template. A system resource does not become Persona-bearing unless its owning contract says so.
|
|
43
|
+
|
|
44
|
+
The Persona target is separate from the verdict. `create` answers what to do. The Persona target answers who the artifact is for.
|
|
45
|
+
|
|
46
|
+
Guide content remains governed by [guide-contract.md](guide-contract.md). System-resource content remains governed by [system-resource-contract.md](system-resource-contract.md) and its type-specific authority.
|
|
47
|
+
|
|
48
|
+
### History Coverage
|
|
49
|
+
|
|
50
|
+
History coverage is not persona-scoped. Use the verdict spine directly: `create`, `update-existing`, `link-only`, or `none`.
|
|
51
|
+
|
|
52
|
+
History records remain governed by [history-record-contract.md](history-record-contract.md). This surface decides whether the pass needs a history breadcrumb; it does not redefine history filename, frontmatter, heading, or link rules.
|
|
53
|
+
|
|
54
|
+
### PRD Reconciliation Coverage
|
|
55
|
+
|
|
56
|
+
PRD reconciliation is not persona-scoped. Use the verdict spine directly: `create`, `update-existing`, `link-only`, or `none`.
|
|
57
|
+
|
|
58
|
+
The governing invariant is that `docs/prd/` describes the current authoritative shape of the product and never the editorial operation used to change that authority.
|
|
59
|
+
|
|
60
|
+
- Use `update-existing` when an existing PRD owns the changed requirement, when its non-normative requirement history needs a material prior contract recorded, or when the active index or risk register needs maintenance.
|
|
61
|
+
- Use `create` only when completed work establishes a coherent, wholesale new capability, subsystem, or product boundary with no suitable existing PRD owner.
|
|
62
|
+
- Use `link-only` when current product authority is sufficient but a navigation or related-authority pointer improves discoverability.
|
|
63
|
+
- Use `none` when no PRD, risk-register, index, or link change is warranted; record why the completed work implements or confirms existing authority.
|
|
64
|
+
|
|
65
|
+
Never use `create` for a document that describes an addition, enhancement, revision, removal, migration, reconciliation, or other editorial operation. PRD content remains governed by [prd-change-management.md](../references/prd-change-management.md) and [output-contract.md](output-contract.md).
|
|
66
|
+
|
|
67
|
+
### Testing Coverage
|
|
68
|
+
|
|
69
|
+
Keep each testing type as a separate current decision. Consider automated implementation testing, performance testing, guided progress review, Unassisted Goal Testing, specialist accessibility testing, visual regression, conformance, and owner or architecture review.
|
|
70
|
+
|
|
71
|
+
Each testing decision records:
|
|
72
|
+
|
|
73
|
+
- `Testing type`;
|
|
74
|
+
- `Decision informed`;
|
|
75
|
+
- `Reason now`;
|
|
76
|
+
- `Product maturity`;
|
|
77
|
+
- `Scope`;
|
|
78
|
+
- `Executor`;
|
|
79
|
+
- `Gate effect`;
|
|
80
|
+
- `Effort budget`;
|
|
81
|
+
- `Stop condition`;
|
|
82
|
+
- `Evidence retained`; and
|
|
83
|
+
- `Rerun trigger`.
|
|
84
|
+
|
|
85
|
+
Use the artifact verdict spine only for the files or links that support a testing decision. A test decision is not reduced to `create`, `update-existing`, `link-only`, or `none`.
|
|
86
|
+
|
|
87
|
+
Activate Unassisted Goal Testing only when an unassisted attempt can answer a material current human-experience uncertainty, or when explicit current authority requires it. Otherwise record `not-needed-now`, the reason, and the evidence that already answers the uncertainty. Do not create a scenario or durable obligation only for this result.
|
|
88
|
+
|
|
89
|
+
Each activated run selects one eligible configured Persona and defaults to canonical `user` when none is supplied. Persona selection controls audience framing and evidence routing. It does not prove executor qualification.
|
|
90
|
+
|
|
91
|
+
Use one run result: `clear`, `friction`, `blocked`, or `invalid-run`. Keep the default gate effect advisory. Use a blocking effect only when explicit current authority names the result and the blocked outcome or claim.
|
|
92
|
+
|
|
93
|
+
Reuse unchanged evidence. Expand the test boundary only after a failure signal, a cross-cutting change, an explicit support claim, or accepted risk.
|
|
94
|
+
|
|
95
|
+
## Acceptance-Case Evidence Retention
|
|
96
|
+
|
|
97
|
+
### Central Evidence Report
|
|
98
|
+
|
|
99
|
+
When a work backlog retains evidence for acceptance or review, create or update `<work>/evidence.md`. Here, `<work>` is the owning backlog directory under `docs/work/`, not an individual phase file. This written report is the main entry point for the evidence. A folder of captures, a list of links, or a bare pass/fail statement does not replace it. The report is required even when all supporting evidence already exists elsewhere and no new capture folder is needed.
|
|
100
|
+
|
|
101
|
+
For Human Experience Review, the agent prepares and records the per-promise review with evidence, observations, conclusions, reviewer, and limits. Human feedback is optional by default. For completed direct human-facing work, the completion can include a short optional experience handoff. Require and record a human response only when accepted authority explicitly defines a human acceptance gate with a scope, human reviewer, surface, acceptance question, and gate effect.
|
|
102
|
+
|
|
103
|
+
Keep one central report for the backlog. Start with a short summary of the current findings. Group the detail by phase and acceptance-case ID, or by named review when no case applies. For each case or review, record:
|
|
104
|
+
|
|
105
|
+
- The claim or user goal being checked and the surface or behavior reviewed.
|
|
106
|
+
- The tested revision or package identity, the relevant environment, and any limits in identifying the tested build.
|
|
107
|
+
- The check performed, the result, and what the reviewer observed.
|
|
108
|
+
- The conclusion supported by those observations, the reviewer, the review limits, and any unresolved gaps or follow-up.
|
|
109
|
+
- Relative links to supporting files and relevant report sections where applicable. State which run supports the current conclusion.
|
|
110
|
+
|
|
111
|
+
Link the report from the backlog's `00-index.md`. Link the relevant report sections from each owning phase's acceptance or closeout record. Keep these links current as evidence changes. A detailed report inside a case folder is optional when it adds useful detail; link it from the central report and summarize its finding there.
|
|
112
|
+
|
|
113
|
+
Do not create an empty report when drafting a backlog or starting a phase. When no durable evidence record is needed, state the reason in the phase's acceptance or closeout record. A reason why no new capture is needed does not waive the report when existing evidence supports a retained acceptance or review finding.
|
|
114
|
+
|
|
115
|
+
### Supporting Captures
|
|
116
|
+
|
|
117
|
+
Keep new acceptance-case captures in `<work>/evidence/a<number>/`. Use the accepted case ID to choose the folder: case `A4` uses `evidence/a4/`; case `A12` uses `evidence/a12/`. The name `a4` is an example, not a fixed directory name.
|
|
118
|
+
|
|
119
|
+
Use stable `A<number>` IDs for acceptance cases. Each number must identify one case across the owning backlog, including all its phases. Keep existing IDs stable. Give a new case an unused number. Resolve duplicate IDs in the backlog before saving evidence for different cases to the same folder.
|
|
120
|
+
|
|
121
|
+
Create `evidence/` and a case folder only when new captures need to be kept. Do not create empty folders when drafting a backlog or starting a phase. Link existing evidence from the central report when that is sufficient. An accepted case can have a failed, blocked, or invalid result; retain those results when they help review or further work. Retention does not mean the case passed or the owner accepted the result.
|
|
122
|
+
|
|
123
|
+
For each retained case:
|
|
124
|
+
|
|
125
|
+
- Link useful captures from the case's section in the central report.
|
|
126
|
+
- Keep the prompt and context boundary, transcript, screenshots, file trees, output snapshots, or file hashes that support the claim. Select useful proof; do not require every capture type for every case.
|
|
127
|
+
- Preserve earlier evidence when a new run changes the result or tested build. Use named run subfolders within the same case folder when needed. State which run supports the current conclusion.
|
|
128
|
+
- Keep copied instructions inert. For example, save a captured `AGENTS.md` as `AGENTS.md.txt`, not as an active router file. Remove secrets and private material that the review does not need.
|
|
129
|
+
|
|
130
|
+
Link to evidence already owned by another contract instead of moving or duplicating it. This rule governs new backlog-owned captures. It does not require a bulk move of existing evidence.
|
|
131
|
+
|
|
132
|
+
The report and supporting files are review evidence, not Make Docs operation state. Keep authoritative installation, upgrade, migration, progress, and recovery state in the global Make Docs Store through the CLI. Do not create local state files or use the evidence report or folders as a fallback when the CLI or Store is unavailable.
|
|
133
|
+
|
|
134
|
+
## Persona Targets
|
|
135
|
+
|
|
136
|
+
Verdicts and persona targets are separate axes. A verdict says what coverage action to take; a target says which configured persona or audience receives that coverage.
|
|
137
|
+
|
|
138
|
+
Merge the built-in Personas with valid `.make-docs/config.yaml` overrides and custom entries. Missing or empty configuration keeps both defaults. Use persona slugs, not display labels, in machine-readable coverage output. The default configured target slugs are:
|
|
139
|
+
|
|
140
|
+
| Persona target | Primitive | Use for |
|
|
141
|
+
| --- | --- |
|
|
142
|
+
| `maintainer` | `maintainer` | Contributors, maintainers, integrators, operators, validation owners, and extension authors. |
|
|
143
|
+
| `user` | `user` | People or agents using the shipped product, reading task guidance, or adopting a workflow. |
|
|
144
|
+
|
|
145
|
+
Either primitive can be human or agent; actor identity does not select a Persona. `agent` is not a primitive. Custom persona targets retain their slug and use only `user` or `maintainer` as their primitive. Custom persona targets use the same schema: `slug`, `label`, `description`, and `primitive`. Do not hard-code display labels in new contracts or prompts.
|
|
146
|
+
|
|
147
|
+
If both audiences need distinct coverage, record one verdict per target or one verdict with an explicit multi-target reason. Do not collapse different audience needs into one artifact merely because they share a source change.
|
|
148
|
+
|
|
149
|
+
## History Idempotency
|
|
150
|
+
|
|
151
|
+
Every coverage pass reconciles session history exactly once for the current work session. If no session history record exists yet, create one when the pass or closeout requires a breadcrumb. If a record for the current session already exists, update that same record instead of creating a duplicate. Follow [history-record-contract.md](history-record-contract.md) for filename, frontmatter, headings, table shape, and link rules.
|
|
152
|
+
|
|
153
|
+
History has a dual role: it is step 5 in every coverage pass skeleton, and it is also a standalone coverage surface when the pass is explicitly deciding whether history coverage is needed.
|
|
154
|
+
|
|
155
|
+
## Verdict And Reason Rule
|
|
156
|
+
|
|
157
|
+
Every candidate gets a verdict and a reason. The reason should name the evidence used, such as an existing guide owning the topic, a PRD already covering the requirement, a missing user-facing scenario, or a new artifact being warranted.
|
|
158
|
+
|
|
159
|
+
`none` is a first-class verdict. A silent skip is not a valid coverage decision.
|
|
160
|
+
|
|
161
|
+
## Validation Checklist
|
|
162
|
+
|
|
163
|
+
At close of pass, confirm:
|
|
164
|
+
|
|
165
|
+
1. The relevant authority docs were read.
|
|
166
|
+
2. Every candidate has exactly one verdict and a reason.
|
|
167
|
+
3. `create` decisions do not duplicate an existing owner artifact.
|
|
168
|
+
4. `update-existing` decisions preserve the owning artifact's contract.
|
|
169
|
+
5. `link-only` decisions use resolving relative links where applicable.
|
|
170
|
+
6. `none` decisions include the no-change rationale.
|
|
171
|
+
7. History idempotency was applied for the current session.
|
|
172
|
+
8. Changed docs have no unresolved placeholders such as `TODO`, `TBD`, or `{{...}}` unless the contract explicitly permits them.
|
|
173
|
+
9. Focused validation was run for the files touched by the pass, including `git diff --check` when files changed.
|
|
174
|
+
10. Testing output preserves separate type decisions, finite budgets, stop conditions, and evidence reuse.
|
|
175
|
+
11. Each activated Unassisted Goal Test records one eligible configured Persona and a separately qualified executor.
|
|
176
|
+
12. Retained backlog evidence has a central `evidence.md` report with findings, supporting links, tested build and environment, reviewer, and review limits. The backlog index and relevant phase records link to it. This applies even when no new capture folder is needed. When no report is needed, the phase record states why.
|
|
177
|
+
13. A retained Human Experience Review records the agent's evidence, observations, conclusions, reviewer, and limits. A declined or unanswered optional experience handoff does not block closure or create an obligation. Any human acceptance gate names its explicit authority, scope, human reviewer, surface, acceptance question, response, and gate effect.
|
|
178
|
+
14. New acceptance-case captures use the owning backlog's `evidence/a<number>/` path and stable case IDs. The central report links to them. Captured instructions are inert, and Make Docs operation state remains in the Store.
|
|
179
|
+
|
|
180
|
+
## Defining A New Coverage Pass
|
|
181
|
+
|
|
182
|
+
To define a new coverage pass:
|
|
183
|
+
|
|
184
|
+
1. Name the surface and the authority docs that govern its content.
|
|
185
|
+
2. State whether the surface is persona-scoped.
|
|
186
|
+
3. Define the pass-specific verdict set.
|
|
187
|
+
4. Map every pass-specific verdict to the base verdict spine.
|
|
188
|
+
5. State how the pass applies the history idempotency rule.
|
|
189
|
+
6. State the minimum validation expected before closeout.
|
|
190
|
+
7. Keep pass-specific content rules in the surface contract, not in this shared mechanics contract.
|
|
191
|
+
|
|
192
|
+
## Non-Goals
|
|
193
|
+
|
|
194
|
+
- This contract does not define guide content, PRD content, work backlog structure beyond evidence reports and acceptance-case captures, prompt syntax, or history-record fields.
|
|
195
|
+
- This contract does not require every pass to create an artifact.
|
|
196
|
+
- This contract does not hard-code future persona names.
|
|
197
|
+
- This contract does not enforce CLI behavior; future automation may validate the mechanics separately.
|
|
198
|
+
- This contract does not turn advisory coverage passes into release, merge, publish, or push gates.
|