@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.
Files changed (187) hide show
  1. package/LICENSE +21 -201
  2. package/README.md +36 -27
  3. package/dist/backup-73HQNKMC.js +20 -0
  4. package/dist/backup-73HQNKMC.js.map +1 -0
  5. package/dist/chunk-3BAJQXGH.js +1575 -0
  6. package/dist/chunk-3BAJQXGH.js.map +1 -0
  7. package/dist/chunk-64CTKJO7.js +4136 -0
  8. package/dist/chunk-64CTKJO7.js.map +1 -0
  9. package/dist/chunk-BENO4IH5.js +875 -0
  10. package/dist/chunk-BENO4IH5.js.map +1 -0
  11. package/dist/chunk-D4HDZEJT.js +37 -0
  12. package/dist/chunk-D4HDZEJT.js.map +1 -0
  13. package/dist/chunk-G5EF63GG.js +1291 -0
  14. package/dist/chunk-G5EF63GG.js.map +1 -0
  15. package/dist/chunk-GNP6HRVP.js +523 -0
  16. package/dist/chunk-GNP6HRVP.js.map +1 -0
  17. package/dist/chunk-HJYIQTMD.js +204 -0
  18. package/dist/chunk-HJYIQTMD.js.map +1 -0
  19. package/dist/chunk-LQ5NSWCJ.js +39 -0
  20. package/dist/chunk-LQ5NSWCJ.js.map +1 -0
  21. package/dist/chunk-LRVV7UDD.js +2340 -0
  22. package/dist/chunk-LRVV7UDD.js.map +1 -0
  23. package/dist/chunk-LVQSJF63.js +24674 -0
  24. package/dist/chunk-LVQSJF63.js.map +1 -0
  25. package/dist/chunk-MXBHCHSM.js +13995 -0
  26. package/dist/chunk-MXBHCHSM.js.map +1 -0
  27. package/dist/chunk-Z5K4FHYP.js +922 -0
  28. package/dist/chunk-Z5K4FHYP.js.map +1 -0
  29. package/dist/index.js +3798 -250
  30. package/dist/index.js.map +1 -1
  31. package/dist/self-YYXOLDKU.js +653 -0
  32. package/dist/self-YYXOLDKU.js.map +1 -0
  33. package/dist/server-O2ZELIMX.js +512 -0
  34. package/dist/server-O2ZELIMX.js.map +1 -0
  35. package/dist/setup-system-HZROFNMP.js +544 -0
  36. package/dist/setup-system-HZROFNMP.js.map +1 -0
  37. package/dist/{skills-command-3ESCZ75U.js → skills-command-MGGHY7HU.js} +190 -32
  38. package/dist/skills-command-MGGHY7HU.js.map +1 -0
  39. package/dist/uninstall-3UXXXNFO.js +223 -0
  40. package/dist/uninstall-3UXXXNFO.js.map +1 -0
  41. package/dist/virtual_make-docs-first-party-skills-ZII74YOB.js +11 -0
  42. package/dist/virtual_make-docs-first-party-skills-ZII74YOB.js.map +1 -0
  43. package/package.json +9 -6
  44. package/skill-registry.json +328 -125
  45. package/skill-registry.schema.json +221 -45
  46. package/template/.make-docs/AGENTS.md +18 -0
  47. package/template/.make-docs/CLAUDE.md +18 -0
  48. package/template/.make-docs/archive/AGENTS.md +11 -0
  49. package/template/.make-docs/archive/CLAUDE.md +11 -0
  50. package/template/.make-docs/system/AGENTS.md +12 -0
  51. package/template/.make-docs/system/CLAUDE.md +12 -0
  52. package/template/.make-docs/system/contracts/AGENTS.md +13 -0
  53. package/template/.make-docs/system/contracts/CLAUDE.md +13 -0
  54. package/template/{docs/assets/references → .make-docs/system/contracts}/commit-message-convention.md +4 -4
  55. package/template/.make-docs/system/contracts/coverage-pass-contract.md +198 -0
  56. package/template/.make-docs/system/contracts/deferred-obligation-contract.md +128 -0
  57. package/template/{docs/assets/references → .make-docs/system/contracts}/design-contract.md +7 -2
  58. package/template/{docs/assets/references → .make-docs/system/contracts}/guide-contract.md +21 -19
  59. package/template/{docs/assets/references → .make-docs/system/contracts}/history-record-contract.md +17 -11
  60. package/template/.make-docs/system/contracts/human-experience-contract.md +134 -0
  61. package/template/.make-docs/system/contracts/naive-uat-contract.md +231 -0
  62. package/template/.make-docs/system/contracts/output-contract.md +277 -0
  63. package/template/.make-docs/system/contracts/performance-evidence-governance.md +257 -0
  64. package/template/.make-docs/system/contracts/system-resource-contract.md +93 -0
  65. package/template/.make-docs/system/prompts/AGENTS.md +12 -0
  66. package/template/.make-docs/system/prompts/CLAUDE.md +12 -0
  67. package/template/.make-docs/system/prompts/coverage-pass-maintainer-guide.prompt.md +20 -0
  68. package/template/.make-docs/system/prompts/coverage-pass-prd-reconciliation.prompt.md +18 -0
  69. package/template/.make-docs/system/prompts/coverage-pass-testing-uat.prompt.md +46 -0
  70. package/template/.make-docs/system/prompts/coverage-pass-user-guide.prompt.md +20 -0
  71. package/template/.make-docs/system/prompts/designs-to-plan-change.prompt.md +18 -0
  72. package/template/.make-docs/system/prompts/designs-to-plan.prompt.md +14 -0
  73. package/template/.make-docs/system/prompts/docs-path-hygiene-cleanup.prompt.md +29 -0
  74. package/template/.make-docs/system/prompts/naive-uat-facilitator.prompt.md +28 -0
  75. package/template/.make-docs/system/prompts/naive-uat-tester.prompt.md +20 -0
  76. package/template/.make-docs/system/prompts/performance-coverage.prompt.md +63 -0
  77. package/template/.make-docs/system/prompts/plan-to-prd-change.prompt.md +12 -0
  78. package/template/.make-docs/system/prompts/plan-to-prd-green-field.prompt.md +10 -0
  79. package/template/.make-docs/system/prompts/prd-change-to-work.prompt.md +14 -0
  80. package/template/.make-docs/system/prompts/prd-to-work-full-prd.prompt.md +10 -0
  81. package/template/.make-docs/system/prompts/prd-to-work-prd-feature.prompt.md +10 -0
  82. package/template/.make-docs/system/prompts/request-to-design.prompt.md +20 -0
  83. package/template/.make-docs/system/prompts/session-to-history-record.prompt.md +23 -0
  84. package/template/{docs/assets → .make-docs/system}/prompts/work-to-commit-message.prompt.md +2 -2
  85. package/template/.make-docs/system/prompts/work-to-guides.prompt.md +22 -0
  86. package/template/.make-docs/system/references/AGENTS.md +14 -0
  87. package/template/.make-docs/system/references/CLAUDE.md +14 -0
  88. package/template/{docs/assets → .make-docs/system}/references/design-workflow.md +15 -2
  89. package/template/.make-docs/system/references/execution-workflow.md +189 -0
  90. package/template/.make-docs/system/references/human-experience.md +138 -0
  91. package/template/.make-docs/system/references/lifecycle.md +153 -0
  92. package/template/.make-docs/system/references/naive-uat-validation.md +65 -0
  93. package/template/.make-docs/system/references/naive-uat-workflow.md +64 -0
  94. package/template/.make-docs/system/references/path-and-link-hygiene.md +101 -0
  95. package/template/.make-docs/system/references/performance-evidence.md +114 -0
  96. package/template/.make-docs/system/references/planning-workflow.md +209 -0
  97. package/template/.make-docs/system/references/prd-change-management.md +165 -0
  98. package/template/{docs/assets → .make-docs/system}/references/wave-model.md +10 -8
  99. package/template/.make-docs/system/templates/AGENTS.md +12 -0
  100. package/template/.make-docs/system/templates/CLAUDE.md +12 -0
  101. package/template/.make-docs/system/templates/design.md +79 -0
  102. package/template/{docs/assets/templates/guide-developer.md → .make-docs/system/templates/guide-maintainer.md} +7 -3
  103. package/template/{docs/assets → .make-docs/system}/templates/guide-user.md +6 -2
  104. package/template/{docs/assets → .make-docs/system}/templates/history-record.md +6 -3
  105. package/template/.make-docs/system/templates/naive-uat-scenario.md +91 -0
  106. package/template/.make-docs/system/templates/performance-evidence-profile.md +252 -0
  107. package/template/.make-docs/system/templates/plan-overview.md +76 -0
  108. package/template/.make-docs/system/templates/plan-prd-change.md +155 -0
  109. package/template/{docs/assets → .make-docs/system}/templates/plan-prd-decompose.md +10 -0
  110. package/template/{docs/assets → .make-docs/system}/templates/plan-prd.md +28 -2
  111. package/template/{docs/assets → .make-docs/system}/templates/prd-architecture.md +13 -0
  112. package/template/.make-docs/system/templates/prd-glossary.md +28 -0
  113. package/template/.make-docs/system/templates/prd-index.md +70 -0
  114. package/template/{docs/assets → .make-docs/system}/templates/prd-overview.md +13 -0
  115. package/template/.make-docs/system/templates/prd-reference.md +30 -0
  116. package/template/{docs/assets → .make-docs/system}/templates/prd-risk-register.md +16 -1
  117. package/template/{docs/assets → .make-docs/system}/templates/prd-subsystem.md +15 -0
  118. package/template/.make-docs/system/templates/work-index.md +58 -0
  119. package/template/.make-docs/system/templates/work-phase.md +107 -0
  120. package/template/.make-docs/system-resources.catalog.json +91 -0
  121. package/template/.make-docs/system-resources.schema.json +204 -0
  122. package/template/AGENTS.md +8 -1
  123. package/template/CLAUDE.md +8 -1
  124. package/template/docs/AGENTS.codex-only.md +22 -0
  125. package/template/docs/AGENTS.md +21 -13
  126. package/template/docs/CLAUDE.claude-only.md +22 -0
  127. package/template/docs/CLAUDE.md +21 -13
  128. package/template/docs/assets/AGENTS.md +11 -7
  129. package/template/docs/assets/CLAUDE.md +11 -7
  130. package/template/docs/designs/AGENTS.md +8 -3
  131. package/template/docs/designs/CLAUDE.md +8 -3
  132. package/template/docs/plans/AGENTS.md +10 -3
  133. package/template/docs/plans/CLAUDE.md +10 -3
  134. package/template/docs/prd/AGENTS.md +14 -4
  135. package/template/docs/prd/CLAUDE.md +14 -4
  136. package/template/docs/work/AGENTS.md +10 -3
  137. package/template/docs/work/CLAUDE.md +10 -3
  138. package/dist/chunk-HP3HBG7F.js +0 -626
  139. package/dist/chunk-HP3HBG7F.js.map +0 -1
  140. package/dist/chunk-QRFH4J6H.js +0 -1194
  141. package/dist/chunk-QRFH4J6H.js.map +0 -1
  142. package/dist/chunk-WM3OXYTW.js +0 -2630
  143. package/dist/chunk-WM3OXYTW.js.map +0 -1
  144. package/dist/skills-command-3ESCZ75U.js.map +0 -1
  145. package/dist/uninstall-GQE4SJF2.js +0 -150
  146. package/dist/uninstall-GQE4SJF2.js.map +0 -1
  147. package/template/.make-docs/scripts/check_path_hygiene.py +0 -435
  148. package/template/docs/assets/archive/AGENTS.md +0 -20
  149. package/template/docs/assets/archive/CLAUDE.md +0 -20
  150. package/template/docs/assets/history/AGENTS.md +0 -12
  151. package/template/docs/assets/history/CLAUDE.md +0 -12
  152. package/template/docs/assets/prompts/AGENTS.md +0 -8
  153. package/template/docs/assets/prompts/CLAUDE.md +0 -8
  154. package/template/docs/assets/prompts/designs-to-plan-change.prompt.md +0 -14
  155. package/template/docs/assets/prompts/designs-to-plan.prompt.md +0 -10
  156. package/template/docs/assets/prompts/docs-path-hygiene-cleanup.prompt.md +0 -27
  157. package/template/docs/assets/prompts/plan-to-prd-change.prompt.md +0 -8
  158. package/template/docs/assets/prompts/plan-to-prd-green-field.prompt.md +0 -6
  159. package/template/docs/assets/prompts/prd-change-to-work.prompt.md +0 -10
  160. package/template/docs/assets/prompts/prd-to-work-full-prd.prompt.md +0 -6
  161. package/template/docs/assets/prompts/prd-to-work-prd-feature.prompt.md +0 -6
  162. package/template/docs/assets/prompts/request-to-design.prompt.md +0 -16
  163. package/template/docs/assets/prompts/session-to-history-record.prompt.md +0 -19
  164. package/template/docs/assets/prompts/work-to-guides.prompt.md +0 -18
  165. package/template/docs/assets/references/AGENTS.md +0 -9
  166. package/template/docs/assets/references/CLAUDE.md +0 -9
  167. package/template/docs/assets/references/execution-workflow.md +0 -157
  168. package/template/docs/assets/references/output-contract.md +0 -221
  169. package/template/docs/assets/references/path-and-link-hygiene.md +0 -49
  170. package/template/docs/assets/references/planning-workflow.md +0 -160
  171. package/template/docs/assets/references/prd-change-management.md +0 -129
  172. package/template/docs/assets/templates/AGENTS.md +0 -8
  173. package/template/docs/assets/templates/CLAUDE.md +0 -8
  174. package/template/docs/assets/templates/design.md +0 -30
  175. package/template/docs/assets/templates/plan-overview.md +0 -32
  176. package/template/docs/assets/templates/plan-prd-change.md +0 -99
  177. package/template/docs/assets/templates/prd-change-addition.md +0 -45
  178. package/template/docs/assets/templates/prd-change-revision.md +0 -45
  179. package/template/docs/assets/templates/prd-glossary.md +0 -15
  180. package/template/docs/assets/templates/prd-index.md +0 -45
  181. package/template/docs/assets/templates/prd-reference.md +0 -17
  182. package/template/docs/assets/templates/work-index.md +0 -21
  183. package/template/docs/assets/templates/work-phase.md +0 -34
  184. package/template/docs/guides/AGENTS.md +0 -15
  185. package/template/docs/guides/CLAUDE.md +0 -15
  186. /package/template/{docs/assets → .make-docs/system}/prompts/update-readme-green-field.prompt.md +0 -0
  187. /package/template/{docs/assets → .make-docs/system}/references/harness-capability-matrix.md +0 -0
@@ -0,0 +1,231 @@
1
+ # Unassisted Goal Testing Contract
2
+
3
+ ## Purpose
4
+
5
+ Use this contract to decide whether an unassisted attempt can answer a material current human-experience question.
6
+
7
+ The stable resource name and `naive-uat` workflow ID remain for compatibility. Current human-facing language uses Unassisted Goal Testing.
8
+
9
+ An executor can be a human or an agent in a separate isolated context. The executor must not have private knowledge that reveals the tested route. The executor uses only the normally consumable product, realistic starting information, and allowed public resources.
10
+
11
+ A configured Persona can define audience framing and evidence routing. Persona selection does not prove executor qualification.
12
+
13
+ ## System Workflow Composition
14
+
15
+ The workflow is complete through these peer system resources:
16
+
17
+ - `make-docs://system/contract/naive-uat-contract.md`
18
+ - `make-docs://system/prompt/naive-uat-facilitator.prompt.md`
19
+ - `make-docs://system/prompt/naive-uat-tester.prompt.md`
20
+ - `make-docs://system/reference/naive-uat-workflow.md`
21
+ - `make-docs://system/template/naive-uat-scenario.md`
22
+
23
+ The installed provider supplies the resources by default. A project-local projection is optional.
24
+
25
+ Direct CLI, native MCP, system-resource, and selected thin-Skill paths must resolve the same resources, typed operations, and receipts. The six stable `uat.*` validation operations are compatibility surfaces. A Skill must not copy this policy.
26
+
27
+ ## Qualified Executor And Test Boundary
28
+
29
+ A valid run:
30
+
31
+ - uses a human or an agent in a separate isolated context;
32
+ - proves that the executor has no repository access, private memory, implementation conversation, known-defect knowledge, hidden answer, successful-path knowledge, or project-specific path guidance beyond the tester packet;
33
+ - uses only the product form that the intended audience normally consumes;
34
+ - starts from realistic visible conditions;
35
+ - uses only allowed public or realistic information;
36
+ - avoids hidden route coaching and compensating shortcuts; and
37
+ - records qualification, product identity, support scope, public help, interventions, observations, result, and material findings.
38
+
39
+ An agent execution is valid only when the separate context and access limits are proved. Self-attestation alone is not sufficient.
40
+
41
+ A source checkout or development server qualifies only when the intended audience normally consumes that exact form.
42
+
43
+ ## Activation And `not-needed-now`
44
+
45
+ Unassisted Goal Testing activates only when an unassisted attempt can reveal a material current human-experience uncertainty that other evidence cannot answer well enough, or when explicit current product or release authority requires it.
46
+
47
+ Useful triggers include:
48
+
49
+ - a new mental model;
50
+ - discoverability or orientation risk;
51
+ - a costly wrong assumption;
52
+ - weak recovery;
53
+ - a relationship or state that implementers understand only from private knowledge;
54
+ - a new public goal without applicable unassisted evidence; or
55
+ - an explicit acceptance requirement.
56
+
57
+ A user-observable slice, phase close, available executor, existing scenario, or desire for reassurance does not activate a test by itself.
58
+
59
+ `not-needed-now` is valid when no current decision justifies a run. Record the reason and the evidence that already answers the uncertainty. Do not create a scenario or durable obligation only to record this result.
60
+
61
+ When an accepted future outcome remains owed, route it through the deferred-obligation contract with an owner, trigger, target, exit criteria, and reason. “Test later” alone is invalid.
62
+
63
+ ## Distinct Testing And Review Types
64
+
65
+ Unassisted Goal Testing remains separate from:
66
+
67
+ - automated implementation testing;
68
+ - performance testing;
69
+ - guided progress review;
70
+ - knowledgeable visual or manual exploration;
71
+ - specialist accessibility testing;
72
+ - visual-regression automation;
73
+ - conformance or lab evidence; and
74
+ - owner or architecture review.
75
+
76
+ One type's evidence can inform a testing decision. It cannot be mislabeled as an unassisted attempt.
77
+
78
+ ## Anti-Coaching
79
+
80
+ Tester instructions describe a realistic situation, goal, visible starting state, allowed public help, and genuine safety constraints. They do not reveal the answer or route.
81
+
82
+ Do not leak:
83
+
84
+ - internal terms;
85
+ - requirement or work IDs;
86
+ - architecture knowledge;
87
+ - hidden setup;
88
+ - expected answers;
89
+ - prescribed clicks, commands, or navigation shortcuts; or
90
+ - compensating instructions that hide a discoverability problem.
91
+
92
+ Safety intervention is always allowed and must be recorded. Material coaching makes the run `invalid-run`.
93
+
94
+ ## Scenario Authority
95
+
96
+ Canonical scenarios live in the active PRD that owns the primary external outcome. They use stable append-only `NUAT-###` identifiers.
97
+
98
+ The same goal keeps its ID and increments `scenario_version` for a material change. A materially different goal, audience, support claim, or risk receives a new ID.
99
+
100
+ Work files, plans, and history records do not become a second scenario authority. A `not-needed-now` decision does not require a scenario.
101
+
102
+ ## Required Scenario And Decision Fields
103
+
104
+ Each testing decision uses the common PRD 50 fields:
105
+
106
+ | Field | Requirement |
107
+ | --- | --- |
108
+ | `testing_type` | Unassisted Goal Testing |
109
+ | `decision_informed` | Current product, release, or human-experience decision |
110
+ | `reason_now` | Activation reason or `not-needed-now` reason |
111
+ | `product_maturity` | Relevant product state |
112
+ | `scope` | Product, platform, audience, and support boundary |
113
+ | `executor` | Qualified executor or `none` when no run occurs |
114
+ | `gate_effect` | `advisory`, `blocking-current-work`, or `blocking-claim-only` |
115
+ | `effort_budget` | Finite run and correction limit |
116
+ | `stop_condition` | Condition that ends the work |
117
+ | `evidence_retained` | Evidence needed for the decision |
118
+ | `rerun_trigger` | Material change that justifies another run |
119
+
120
+ An activated scenario also records:
121
+
122
+ | Field | Requirement |
123
+ | --- | --- |
124
+ | `scenario_id` | Stable `NUAT-###` identity |
125
+ | `scenario_version` | Version that increases for each material change |
126
+ | `title` | Short product-language title |
127
+ | `user_goal` | Real-world target outcome |
128
+ | `source_requirements` | Owning requirement links |
129
+ | `target_user` | Intended audience and assumptions |
130
+ | `selected_persona` | One eligible configured Persona or canonical `user` default |
131
+ | `build_identity` / `environment` | Reproducible product identity and normally consumable form |
132
+ | `starting_state` | Realistic visible starting conditions |
133
+ | `public_resources` | Exact allowed public resources |
134
+ | `prohibited_context` | Private knowledge and hidden-route guidance |
135
+ | `tester_prompt` | Goal-oriented tester packet |
136
+ | `operator_success_outcomes` | Operator-only evaluation rules |
137
+ | `setup` / `teardown` | Isolation, consent, capture, cleanup, and restoration |
138
+ | `evidence_requirements` | Evidence needed for the current decision |
139
+ | `severity_rules` | Base or project-specific escalation rule |
140
+ | `finding_route` | Owning PRD, work, and gate route |
141
+
142
+ ## Tester Packet Safety
143
+
144
+ One canonical scenario can render two views:
145
+
146
+ 1. an operator view with the complete record;
147
+ 2. a tester packet with only the situation, goal, visible starting state, allowed public resources, genuine constraints, consent notice, and tester-owned teardown steps.
148
+
149
+ Operator-only fields must not enter the tester packet.
150
+
151
+ ## Run, Result, And Finding Fields
152
+
153
+ Every run records the exact scenario reference, executor qualification, selected Persona, product build and environment, support scope, public guidance, interventions, result, observations, reproduction details, evidence references, finding references, and review disposition.
154
+
155
+ Every finding records observed behavior, expected human outcome, severity, reproducibility, support scope, evidence, source requirement or promise, owner, and disposition.
156
+
157
+ ## Result Meanings
158
+
159
+ | Result | Meaning |
160
+ | --- | --- |
161
+ | `clear` | The executor understood and attempted the goal without material hidden help or human-experience friction that changes the current decision. |
162
+ | `friction` | The attempt exposed confusion, excess effort, a wrong mental model, weak recovery, or another material human-experience issue. |
163
+ | `blocked` | The product or environment prevented a valid attempt. |
164
+ | `invalid-run` | Coaching, prior private knowledge, broken setup, lost evidence, or another validity failure prevents a conclusion. |
165
+ | `not-needed-now` | No current decision justifies an unassisted attempt. No run occurred. |
166
+
167
+ One valid independent run can answer the bounded current uncertainty unless accepted risk or support authority requires more. More clear runs cannot erase an unresolved material finding.
168
+
169
+ ## Severity Meanings
170
+
171
+ | Severity | Meaning |
172
+ | --- | --- |
173
+ | `critical` | Credible safety, privacy, security, irreversible-data, unauthorized-external-effect, or severe accessibility risk |
174
+ | `major` | The intended goal is impossible for the tested scope or needs private coaching or an undocumented workaround |
175
+ | `moderate` | The goal completes only with substantial confusion, repeated failure, or a misleading mental model |
176
+ | `minor` | Bounded friction that does not threaten core completion |
177
+
178
+ ## Gate Effects
179
+
180
+ The default gate effect is `advisory`.
181
+
182
+ A result is `blocking-current-work` or `blocking-claim-only` only when explicit current product or release authority names the result and the blocked outcome or claim.
183
+
184
+ `friction` creates feedback or remediation. It does not automatically fail a phase. `blocked` and `invalid-run` prove no human conclusion. `not-needed-now` is not a failed or deferred test.
185
+
186
+ Task or obligation completion cannot rewrite a result or close a finding.
187
+
188
+ ## Evidence Boundary
189
+
190
+ Repository-canonical material includes:
191
+
192
+ - scenario identity and meaning;
193
+ - testing decisions and gate effects;
194
+ - target audience and support scope;
195
+ - run records, results, findings, and dispositions; and
196
+ - approved evidence references.
197
+
198
+ Persona-specific packets, runs, findings, and approved evidence live under `docs/assets/<persona-slug>/testing/`.
199
+
200
+ Optional Make Docs operational capture belongs in the global Make Docs Store through the CLI. It can contain run progress, timestamps, bounded Store receipts, and sanitized project-relative evidence references. Repository run records and evidence remain project knowledge.
201
+
202
+ If the CLI is unavailable or optional capture fails, continue project work and report unavailable capture. Do not claim success, write directly to the Store, queue a later write, or create local fallback state. This does not waive required Store recording for CLI-managed changes, and it does not replace missing required testing evidence.
203
+
204
+ Large external captures can remain outside the repository when consent, retention, and privacy rules require it. Missing or corrupt required evidence prevents a conclusion.
205
+
206
+ ## Compatibility
207
+
208
+ Adopt this contract conservatively:
209
+
210
+ - preserve stable resource names, `NUAT-###` IDs, and `R-NUAT-*` anchors;
211
+ - classify earlier manual or UAT artifacts by what they prove;
212
+ - do not relabel an automated run or coached walkthrough as Unassisted Goal Testing;
213
+ - preserve historical language in historical records;
214
+ - keep the six typed `uat.*` validators as compatibility surfaces; and
215
+ - stop instead of overwriting modified active project content.
216
+
217
+ ## Future Automation Limits
218
+
219
+ Future tooling can inventory candidates, render packets, facilitate runs, record observations, or validate links and required fields.
220
+
221
+ Automation must not infer material human uncertainty, executor qualification, intervention materiality, finding severity, product acceptance, support narrowing, or requirement cancellation.
222
+
223
+ ## Non-Goals
224
+
225
+ - No automatic test because a phase has a user-observable slice.
226
+ - No required `naive-tester` Persona.
227
+ - No human-only executor rule.
228
+ - No implementation-shaped answer script.
229
+ - No other test or review type mislabeled as an unassisted attempt.
230
+ - No Playbook or Protocol workflow, runner, or asset requirement.
231
+ - No copied policy in a Skill, plugin, hook, extension, or harness adapter.
@@ -0,0 +1,277 @@
1
+ # Output Contract
2
+
3
+ See `.make-docs/system/references/wave-model.md` for W/R/P semantics and resolution.
4
+
5
+ ## Purpose
6
+
7
+ Use this contract to keep plan, PRD, and work document outputs consistent across repositories and harnesses. Treat the codebase as authoritative, write in plain English, and keep the PRD set descriptive while keeping implementation work prescriptive.
8
+
9
+ The governing PRD invariant is:
10
+
11
+ > `docs/prd/` describes the current authoritative shape of the product. It must never describe the editorial operation used to change that authority.
12
+
13
+ ## Markdown Source Formatting
14
+
15
+ - Do not hard-wrap prose paragraphs for visual width; use editor soft-wrap instead. Paragraphs should be one logical source line unless semantic Markdown structure requires otherwise.
16
+ - Insert line breaks only for semantic Markdown structure: paragraph boundaries, headings, list items, tables, blockquotes, code fences, frontmatter, comments, or intentional line-based formats.
17
+ - Separate every Markdown block from the next block with one blank line, including headings, paragraphs, lists, fenced code blocks, blockquotes, comments, and tables.
18
+ - Prefer one logical line per list item unless nested structure is semantically required. When list continuation or nesting is required, indentation is semantic and must be preserved exactly.
19
+
20
+ ## Required Paths
21
+
22
+ | Artifact | Required path |
23
+ | --- | --- |
24
+ | Design | `docs/designs/YYYY-MM-DD-<slug>.md` |
25
+ | Plan directory | `docs/plans/YYYY-MM-DD-w{W}-r{R}-<slug>/` |
26
+ | Work directory | `docs/work/YYYY-MM-DD-w{W}-r{R}-<slug>/` |
27
+ | PRD index | `docs/prd/00-index.md` |
28
+ | Product overview | `docs/prd/01-product-overview.md` |
29
+ | Architecture overview | `docs/prd/02-architecture-overview.md` |
30
+ | Risk and gap register | `docs/prd/03-open-questions-and-risk-register.md` |
31
+ | Glossary | `docs/prd/04-glossary.md` |
32
+ | Archived PRD set | `.make-docs/archive/prds/YYYY-MM-DD/` or `.make-docs/archive/prds/YYYY-MM-DD-XX/` |
33
+ | Breadcrumb record | `.make-docs/archive/history/YYYY-MM-DD-w{W}-r{R}-p{P}-<slug>.md` when W/R/P is known; fall back to `.make-docs/archive/history/YYYY-MM-DD-w{W}-r{R}-<slug>.md` when only W/R is known or `.make-docs/archive/history/YYYY-MM-DD-<slug>.md` when no coordinate is known. |
34
+
35
+ Plan directories contain `00-overview.md` plus one or more `0N-<phase>.md` files. Work directories contain `00-index.md` plus one or more `0N-<phase>.md` files. See `.make-docs/system/references/wave-model.md` for the full naming pattern and `## Work Phase Structure Rules` below for work content requirements.
36
+
37
+ For change-oriented plans and delta backlogs, carry the distinguishing context in the `<slug>` (for example `...-auth-recovery-change` or `...-notifications-delta`) rather than in the directory structure. Every plan and every work backlog uses the same W/R directory shape.
38
+
39
+ ## PRD Lifecycle Rules
40
+
41
+ - `docs/prd/` contains one active PRD namespace at a time.
42
+ - Every root entry in `docs/prd/` is part of the active namespace.
43
+ - Active namespaces can be established or maintained in two ways:
44
+ - `full-set generation` — generate or replace the active namespace as a set
45
+ - `authoritative PRD maintenance` — surgically update existing product authorities and create a new PRD only for a coherent capability, subsystem, or product boundary with no current owner
46
+ - Editorial operations, migration sequencing, and reconciliation activity belong in plans, work backlogs, and history records, not in the active PRD namespace.
47
+ - `docs/prd/03-open-questions-and-risk-register.md` is the living register for discovered gaps, confirmed drift, open questions, decisions, and rebuild risks in the active namespace.
48
+ - Older namespaces belong under `.make-docs/archive/prds/`, not alongside the active namespace.
49
+ - Archived PRD sets are historical records and are not part of active PRD validation.
50
+
51
+ ## Archive Rules
52
+
53
+ Apply these rules only when writing a fresh active PRD namespace through `full-set generation`.
54
+
55
+ - Before writing a fresh PRD set, inspect `docs/prd/` for active root entries.
56
+ - If no such entries exist, proceed normally.
57
+ - If active root entries exist, summarize them and ask for explicit approval before moving them.
58
+ - On approval, move those entries into `.make-docs/archive/prds/YYYY-MM-DD/`.
59
+ - If that dated directory already exists, use `.make-docs/archive/prds/YYYY-MM-DD-XX/`, where `XX` is a zero-padded increment starting at `01`.
60
+ - Do not place loose files directly under `.make-docs/archive/prds/`; it should contain dated directories only.
61
+ - Never archive designs, plans, work, or PRDs unless the user explicitly asks.
62
+
63
+ Archive layout and hard rules are authoritative in `.make-docs/archive/AGENTS.md`.
64
+
65
+ ## Authoritative PRD Maintenance Rules
66
+
67
+ Apply these rules when a decision, design, implementation, or finding may change the current product authority.
68
+
69
+ - Do not archive the active namespace merely because current authority needs maintenance.
70
+ - Update the existing PRD when its subject owns the changed requirement.
71
+ - Put the current normative requirement inline in the owning PRD.
72
+ - Create a new numbered PRD only for a coherent, wholesale new capability, subsystem, or product boundary with no suitable existing owner.
73
+ - Create no PRD when the current authority already covers the decision; record the rationale in the governing plan, coverage pass, or history record.
74
+ - Preserve material prior iterations in the owning PRD's optional, non-normative `## Requirement History` section as defined in `.make-docs/system/references/prd-change-management.md`.
75
+ - Express removals and deprecations as current scope, non-goal, limitation, status, or boundary text in the owning PRD, then preserve the prior contract in requirement history when useful.
76
+ - Never use active PRD filenames, H1 titles, index kinds, or document identities that describe editorial operations such as additions, enhancements, revisions, removals, migrations, or reconciliation.
77
+ - Never renumber or reorder existing active PRDs merely because authority changed.
78
+ - Update `docs/prd/03-open-questions-and-risk-register.md` directly for newly discovered or resolved gaps, drift, questions, decisions, and risks.
79
+ - Update `docs/prd/00-index.md` so current ownership, status, focus, and navigation remain readable.
80
+
81
+ ## Human Experience Propagation
82
+
83
+ Use the [Human Experience Contract](human-experience-contract.md) as the canonical authority and the [Human Experience Reference](../references/human-experience.md) for explanation and examples. Human Experience is a cross-cutting lens. It is not a lifecycle stage, frontmatter schema, PRD kind, or testing type. Plans, PRDs, work, evidence, and review records link to the authority and record their local mapping or verdict. They do not copy the standard. Apply this shape to new generated artifacts and to substantial updates when the planned change affects the human path. Existing and archived artifacts remain valid without a backfill.
84
+
85
+ - A `direct` or `indirect` plan maps each accepted promise to its owning PRD, affected human-facing surface or indirect effect, work phase, evidence source or testing type selected under current testing authority, and any accepted `O-###` obligation.
86
+ - A `none` plan names the preserved human boundary and the evidence that will prove it unchanged.
87
+ - A PRD puts each current observable human outcome in the document that owns the affected capability. Do not create an editorial Human Experience PRD or add Human Experience fields to frontmatter.
88
+ - A work index retains the source design, plan, owning PRDs, phase order, evidence decisions, implementation gate, and any accepted obligation for the applicable promises or preserved boundary.
89
+ - Each applicable work phase states the intended human outcome, affected surface or indirect effect, implementation work, observable acceptance, evidence source or selected testing type, executor, and accepted obligation route when work remains owed.
90
+ - Each generated work phase records the current decision for Automated Implementation Testing, Performance Testing, Guided Progress Review, and Unassisted Goal Testing. A type that cannot change a current decision records `not-needed-now`; the phase does not invent an activity to make every type active. Human Experience Review remains separate required agent review work for applicable promises and is not a fifth testing type. The record keeps the evidence, observations, conclusions, reviewer, and limits. A short experience handoff is optional and non-blocking. A human response is required only when accepted authority explicitly defines a human acceptance gate.
91
+ - Acceptance must identify an observable result. `UX is good`, `easy to use`, and `intuitive` are invalid without a stated observation and evidence.
92
+
93
+ For example, acceptance can require that a person can identify the current subject, understand an important relationship, distinguish success from partial or failed state, find the next useful action, recover from an error, reach exact detail through a clear secondary path, or complete the goal without first learning an unexplained internal identifier.
94
+
95
+ ## PRD Tree Rules
96
+
97
+ ### Fixed core
98
+
99
+ Always generate the fixed core first or reserve its numbers:
100
+
101
+ - `00-index.md`
102
+ - `01-product-overview.md`
103
+ - `02-architecture-overview.md`
104
+ - `03-open-questions-and-risk-register.md`
105
+ - `04-glossary.md`
106
+
107
+ ### Adaptive middle
108
+
109
+ Use `05` through `99` for:
110
+
111
+ - product capability docs
112
+ - subsystem docs
113
+ - reference docs
114
+
115
+ Prefer a flat PRD tree by default:
116
+
117
+ ```text
118
+ docs/prd/
119
+ ├── 00-index.md
120
+ ├── 01-product-overview.md
121
+ ├── 02-architecture-overview.md
122
+ ├── 03-open-questions-and-risk-register.md
123
+ ├── 04-glossary.md
124
+ ├── 05-payments.md
125
+ ├── 06-notifications.md
126
+ ├── 07-notifications-reference.md
127
+ └── 08-billing-reliability.md
128
+ ```
129
+
130
+ Switch to a numbered subfolder only when one baseline subsystem is too large for one doc:
131
+
132
+ ```text
133
+ docs/prd/
134
+ ├── 00-index.md
135
+ ├── 01-product-overview.md
136
+ ├── 02-architecture-overview.md
137
+ ├── 03-open-questions-and-risk-register.md
138
+ ├── 04-glossary.md
139
+ ├── 05-backend/
140
+ │ ├── 01-server-core.md
141
+ │ ├── 02-handlers.md
142
+ │ └── 03-stores.md
143
+ ├── 06-frontend/
144
+ │ ├── 01-app-framework.md
145
+ │ └── 02-pages.md
146
+ ├── 07-account-recovery.md
147
+ └── 08-session-lifecycle.md
148
+ ```
149
+
150
+ Do not place unnumbered Markdown files directly under `docs/prd/`. Do not place active PRD docs under `.make-docs/archive/prds/`.
151
+
152
+ ## Section Contracts
153
+
154
+ Use the matching template in `.make-docs/system/templates/` and preserve these required headings.
155
+
156
+ | Doc type | Required headings |
157
+ | --- | --- |
158
+ | `prd-index.md` | `## Purpose`, `## Reading Order`, `## Document Map`, `## Source Anchors`, `## Audience Paths`, `## Intended Follow-On` |
159
+ | `prd-overview.md` | `## Purpose`, `## Users`, `## Key Capabilities`, `## System Boundaries`, `## Current Limitations`, `## Source Anchors` |
160
+ | `prd-architecture.md` | `## Purpose`, `## Topology`, `## Module Map`, `## Runtime Boundaries`, `## Data Flow`, `## Configuration Surfaces`, `## Source Anchors` |
161
+ | `prd-risk-register.md` | `## Purpose`, `## Confirmed Drift`, `## Open Questions`, `## Rebuild Risks`, `## Source Anchors` |
162
+ | `prd-glossary.md` | `## Purpose`, `## Terms`, `## Source Anchors` |
163
+ | `prd-subsystem.md` | `## Purpose`, `## Scope`, `## Component and Capability Map`, `## Contracts and Data`, `## Integrations`, `## Rebuild Notes`, `## Source Anchors` |
164
+ | `prd-reference.md` | `## Purpose`, `## Reference`, `## Source Anchors` |
165
+ | `work-index.md` | `## Purpose`, `## Phase Map`, `## Usage Notes`, `## Intended Follow-On` |
166
+ | `work-phase.md` | `## Purpose`, `## Overview`, `## Source PRD Docs`, repeatable `## Stage {{STAGE_NUMBER}} - {{STAGE_NAME}}` headings with `### Tasks`, `### Acceptance criteria`, and `### Dependencies` |
167
+
168
+ When deferred-obligation or Unassisted Goal Testing routing is active, work indexes inventory applicable `O-###` and `NUAT-###` authorities plus capability-status expectations. Work phases link applicable obligations, activated scenarios, findings, separate testing decisions, and phase or capability closeout status without becoming a second authority. A `not-needed-now` result does not require a scenario or obligation.
169
+
170
+ Product overview, architecture, subsystem, reference, glossary, and other requirement-owning PRDs may include an optional `## Requirement History` section immediately before `## Source Anchors`. Current normative requirements remain in the main body and always win. History is non-normative and uses the dated entry contract in `.make-docs/system/references/prd-change-management.md`. The PRD index and living risk register use their own navigation and item-history contracts instead.
171
+
172
+ Risk-register items under `## Confirmed Drift`, `## Open Questions`, and `## Rebuild Risks` use numbered `###` item headings with a `Status` / `Decision` / `Follow-Up` table. Use `D-001`, `D-002`, etc. for confirmed drift; `Q-001`, `Q-002`, etc. for open questions; and `R-001`, `R-002`, etc. for rebuild risks. Assign the next available number within the section and never renumber existing items, even when they move to `Closed`. Valid item statuses are `Open`, `Confirming`, `Deferred`, and `Closed`. Each item should include `Question` or `Issue`, `Why it matters`, `Recommendation`, and `To close`; include `Resolution` only for closed items.
173
+
174
+ When deferred-obligation governance is active, `docs/prd/03-open-questions-and-risk-register.md` also carries one fixed `## Deferred Obligations` section with stable append-only `O-###` records. That section is the canonical obligation register and is not duplicated in plans, work, scenarios, or history.
175
+
176
+ ## Intended Follow-On Handoffs
177
+
178
+ The `## Intended Follow-On` section is advisory-default-but-overridable: it is
179
+ authoritative unless the user explicitly overrides it, and it is not a gate or
180
+ precondition.
181
+ No document fails validation solely because its follow-on is deferred,
182
+ overridden, or unresolved.
183
+
184
+ Each handoff includes:
185
+
186
+ - `Route:` the downstream workflow route
187
+ - `Next step:` the recommended next action
188
+ - `Why:` the reason that next step normally follows
189
+ - `Coordinate Handoff:` the W/R/P lineage or coordinate question the downstream
190
+ workflow should carry
191
+
192
+ A route, coordinate, workflow term, or task ID does not replace a plain-language next step. State what the user should do in normal words. Use internal labels only as supporting navigation or audit detail.
193
+
194
+ For PRD indexes, use route `work-backlog-generation` and recommend creating or
195
+ updating the work backlog from the PRD set.
196
+ For work indexes, use route `implementation-loop` and recommend starting with
197
+ the first applicable phase in the backlog.
198
+ When deferred-obligation or Unassisted Goal Testing routing is active, preserve applicable `O-###`, activated `NUAT-###`, finding, and capability-status traceability in the coordinate handoff. A `not-needed-now` result does not require an ID.
199
+
200
+ ## Work Phase Structure Rules
201
+
202
+ Every work backlog is a directory, not a single file.
203
+
204
+ - The work directory is `docs/work/YYYY-MM-DD-w{W}-r{R}-<slug>/`.
205
+ - It contains an index file `00-index.md` with:
206
+ - `## Purpose`
207
+ - `## Phase Map`
208
+ - `## Usage Notes`
209
+ - `## Intended Follow-On`
210
+ - It contains one or more phase files named `0N-<phase>.md`. Each phase file contains:
211
+ - `## Purpose`
212
+ - `## Overview`
213
+ - `## Source PRD Docs`
214
+ - one or more `## Stage {{STAGE_NUMBER}} - {{STAGE_NAME}}` sections
215
+ - Each stage in a phase file contains:
216
+ - `### Tasks`
217
+ - `### Acceptance criteria`
218
+ - `### Dependencies`
219
+ - `### Tasks` items are markdown task list items with phase-local task IDs: `- [ ] t1: {{TASK}}` for open tasks and `- [x] t1: {{TASK}}` for completed tasks.
220
+ - Task IDs start at `t1` in each phase file and increment across all stages in that file. Do not reset numbering in later stages and do not renumber existing task IDs when inserting or completing work.
221
+ - `### Acceptance criteria` items are always plain unordered bullets (`- {{ACCEPTANCE}}`). Do not use checkbox syntax or `t{T}` labels in acceptance criteria.
222
+
223
+ ## Code Anchor Rules
224
+
225
+ ### General rule
226
+
227
+ Every substantive PRD section should cite concrete repo paths in inline code. Prefer relative repo paths with optional line anchors. Apply `.make-docs/system/references/path-and-link-hygiene.md` for repo-relative path rules, relative Markdown links, sanitized placeholders, and full-path exceptions.
228
+
229
+ Accepted examples:
230
+
231
+ - `package.json`
232
+ - `src/main.ts`
233
+ - `src/server/router.ts:42`
234
+ - `cmd/sensoroni.go:49`
235
+ - `server/modules/modules.go`
236
+
237
+ ### Practical rule
238
+
239
+ Keep code anchors inside the section they support. Do not rely only on a final source list to justify claims made earlier in the document.
240
+
241
+ ### Source anchors section
242
+
243
+ Use `## Source Anchors` to aggregate the most important files that shaped the document. This section supplements, but does not replace, section-level anchors.
244
+
245
+ ## Existing Documentation Rule
246
+
247
+ - Supplement existing docs and cite them where useful.
248
+ - Do not silently rewrite or replace existing documentation that already serves a different audience.
249
+ - If docs and code disagree, treat the code as authoritative and record the disagreement in `03-open-questions-and-risk-register.md`.
250
+ - Do not create separate questions, decisions, risks, gaps, or architecture-decision files when the active PRD risk register exists unless the user explicitly asks for a new convention.
251
+ - If an older active PRD namespace exists in `docs/prd/` and the task is full-set generation, archive it as a set before writing the new active namespace.
252
+ - If the task is authoritative PRD maintenance, update the owning current requirement surgically, preserve material prior state in non-normative requirement history, and keep editorial operations outside `docs/prd/`.
253
+
254
+ ## Work Backlog Rule
255
+
256
+ - Keep work out of `docs/prd/`.
257
+ - Every work backlog is a directory under `docs/work/` following the W/R naming pattern; link phase files back to the relevant PRD docs.
258
+ - Organize phases and stages by dependency order, not by implementation convenience.
259
+ - Include markdown task-list items and plain-bullet acceptance criteria in every stage.
260
+ - Use phase-local task IDs (`t1`, `t2`, etc.) on task items so a task can be referenced externally as `w{W} r{R} p{P} t{T}`.
261
+ - For PRD authority-maintenance work, use a dated delta work directory with a distinguishing slug (for example `...-<subject>-delta`) instead of rewriting a prior backlog.
262
+ - Treat updated and genuinely new product PRDs as downstream requirement authority. Plans describe sequencing and requirement-history entries preserve provenance; neither overrides the current normative PRD body.
263
+ - Every phase file must include `## Source PRD Docs`.
264
+ - New generated work indexes and phases, and substantial active-work updates that affect the human path, must carry the mapping required by `## Human Experience Propagation`, including a proved preserved boundary for `none`. This does not require a repository-wide backfill.
265
+ - Every work `00-index.md` includes `## Intended Follow-On` recommending the implementation loop as the next step. The handoff is authoritative unless the user explicitly overrides it, and it is not a gate or precondition.
266
+
267
+ ## Link Rules
268
+
269
+ - Use relative Markdown links between generated docs.
270
+ - Apply `.make-docs/system/references/path-and-link-hygiene.md` when deciding whether an absolute path or sanitized placeholder is warranted.
271
+ - Make sure every internal link resolves.
272
+ - Use the PRD index and the work `00-index.md` as navigation entry points.
273
+ - Archived PRD docs do not need to satisfy the active PRD link contract.
274
+
275
+ ## PRD Authority Validation
276
+
277
+ Run `make-docs run prd authority validate --target-root <project>` before treating an active PRD set as downstream authority. The read-only validator enforces `PRD-AUTH-001` through `PRD-AUTH-008` as defined in `.make-docs/system/references/prd-change-management.md`: filename/H1 editorial stems use the narrow twelve-term set that allows legitimate Update Delivery, Replacement Policy, and Migration Safety subjects; controlled kinds additionally prohibit update/replace/replacement/migrate/migration; and the remaining diagnostics cover retired headings, authority targets, top-level coordinates, invalid target roots, and unsafe or escaping documentation roots. It scans authority-bearing Markdown sections and structured JSON/JSONL/YAML/YML fields, exempts standardized provenance sections/containers, and grants a path-wide provenance exemption only to `.make-docs/archive/**`. Human TTY output summarizes diagnostics and remediation; `--json` and non-TTY output return the complete report. An explicit `failed` report exits nonzero after rendering.