@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,257 @@
1
+ # Performance Evidence Governance Contract
2
+
3
+ ## Purpose
4
+
5
+ Use this contract to decide when performance evidence is needed and what that evidence can prove.
6
+
7
+ This is the sole reusable policy source for Make Docs performance evidence. The prompt orders the coverage work. The reference explains the policy. The template supplies the record shape. Those resources must not create a second policy source.
8
+
9
+ This contract applies to latency, throughput, resource use, capacity, startup or interaction response, and artifact size when size changes execution. It applies across GUI, CLI, API, SDK, service, device, batch, background, and headless surfaces.
10
+
11
+ The initial delivery is documentation-first. The admitted validation twin adds one read-only structural validator and one canonical agent review method. It does not create a benchmark runner, daemon, retry service, or hidden state change.
12
+
13
+ ## Resource Composition
14
+
15
+ | Role | Stable URI |
16
+ | --- | --- |
17
+ | Governing contract | `make-docs://system/contract/performance-evidence-governance.md` |
18
+ | Coverage prompt | `make-docs://system/prompt/performance-coverage.prompt.md` |
19
+ | Workflow reference | `make-docs://system/reference/performance-evidence.md` |
20
+ | Progressive profile template | `make-docs://system/template/performance-evidence-profile.md` |
21
+
22
+ The installed provider supplies these resources by default. A project can use a valid local projection. The project does not need a local copy.
23
+
24
+ ## Start With Applicability
25
+
26
+ Inventory each current candidate before you define a target or start a measurement.
27
+
28
+ Record one base coverage action for each candidate:
29
+
30
+ - `create`;
31
+ - `update-existing`;
32
+ - `link-only`; or
33
+ - `none`.
34
+
35
+ Record one performance applicability disposition for each candidate:
36
+
37
+ | Disposition | Use |
38
+ | --- | --- |
39
+ | `required-now` | Current evidence is necessary for an accepted product outcome, feasibility limit, safety or resource boundary, external mandate, dependency budget, or material regression decision. |
40
+ | `characterize-now` | A current decision needs a baseline, and the path is stable enough for the measurement to have meaning. |
41
+ | `defer-required` | An accepted later outcome remains owed through one stable `O-###` record. |
42
+ | `not-needed` | Performance evidence cannot change a current decision. |
43
+ | `reject-unsupported` | The candidate rests on intuition, copied numbers, arbitrary round values, absolute language, or an unowned implementation preference. |
44
+
45
+ The qualification record must name the candidate, protected outcome, decision informed, failure cost, risk, reversibility, supported scope, product maturity, source authority or evidence, baseline availability, owner, lifecycle coordinate, and reason.
46
+
47
+ Words such as fast, instant, real-time, zero regression, at scale, and production-grade do not qualify a candidate by themselves.
48
+
49
+ Only `required-now` and `characterize-now` can proceed to an executable profile. `Defer-required` stops at the linked `O-###`. `Not-needed` and `reject-unsupported` stop with their recorded reason.
50
+
51
+ Do not relabel a blocked active run as `not-needed` because execution is difficult.
52
+
53
+ ## Keep Proof Proportionate
54
+
55
+ Set the proof burden from the current decision. Consider product maturity, blast radius, reversibility, user harm, data or financial exposure, support scope, novelty, platform variance, false-pass cost, false-fail cost, and evidence cost.
56
+
57
+ For proof-of-concept work, prefer the smallest useful feasibility characterization. For MVP work, prefer bounded baselines and engineering guardrails for critical paths. For beta or prerelease work, prefer representative workloads and stated uncertainty for claimed scopes. For production work, use maintained profiles, risk-based coverage, expiry, and reevaluation.
58
+
59
+ These are default postures. They are not exemptions. They do not create a target. A genuine feasibility, safety, contract, or central product outcome can require a hard boundary at any maturity level.
60
+
61
+ ## Assign One Target Class And Owner
62
+
63
+ Every applicable candidate has one target class.
64
+
65
+ | Target class | Meaning | Canonical owner | Executable now |
66
+ | --- | --- | --- | --- |
67
+ | `hard-product-requirement` | An approved blocking product target for an exact protected outcome and scope | The active PRD that owns the outcome | Yes, with `required-now` |
68
+ | `engineering-guardrail` | A bounded engineering limit that does not define product support | The accepted plan or work phase that owns its finite budget | Yes, with `required-now` |
69
+ | `characterization-baseline` | An observed distribution with stated uncertainty, not a pass/fail gate | The accepted plan, work, engineering, or characterization record that owns the inquiry | Yes, with `characterize-now` |
70
+ | `experiment-or-stretch` | A bounded inquiry or stretch aim with no product authority | The accepted plan, work, engineering, or experiment record that owns the inquiry | Yes, when current applicability permits it |
71
+ | `deferred-required-outcome` | An accepted later outcome | One `O-###` record | No |
72
+ | `unsupported-assumption` | A candidate without adequate authority or evidence | The record that rejects or revises it | No |
73
+
74
+ A hard product target exists only when the active owning PRD states the protected outcome and contains the explicit owner-approved requirement. It can block only its accepted scope. It is the only target class that has product authority.
75
+
76
+ Plan and work profiles are non-product authority. They cannot create a support claim or silently change a PRD. An execution packet can bind operational detail. It cannot define or change a product target.
77
+
78
+ Each target has one live canonical authority. Canonical means the one source allowed to define its current meaning. Other records link to it. They do not copy it into another live target.
79
+
80
+ Characterization must come before threshold promotion. An observed baseline does not become a hard target or engineering guardrail by itself. Promotion requires the source, comparability, normal variance, measurement resolution, protected-outcome reason, trade-offs, and owner approval. Promotion to product authority also requires current PRD maintenance. The promoted profile must link to the source profile and supersede it without leaving two live authorities.
81
+
82
+ ## Preserve Profile Identity And Lineage
83
+
84
+ Each executable candidate uses one repository-canonical `PERF-###` profile. IDs are project-wide and append-only. Do not reuse or renumber them.
85
+
86
+ Keep the same ID when the protected outcome and workload stay the same. Increment `profile_version` when the target, authority, scope, environment, workload, measurement method, analysis, or outcome rules change in a meaningful way. Use a new ID for a materially different protected outcome or workload.
87
+
88
+ Bind each result to the exact profile ID, version, and source digest. Record predecessor, successor, promotion source, replacement, retirement, and superseding reason when they apply.
89
+
90
+ ## Predeclare Measurement And Comparability
91
+
92
+ Before a blocking execution, the profile must state:
93
+
94
+ - the product build and relevant dependency and configuration state;
95
+ - the instrument version and measurement boundary;
96
+ - the qualified environment or environment class;
97
+ - the workload, scale, fixture or dataset, concurrency, and operation mix;
98
+ - the cold or warm state and warmup rule;
99
+ - the repetitions or observation window;
100
+ - the statistic, variance, and uncertainty treatment;
101
+ - the outlier rule;
102
+ - the comparison method;
103
+ - the raw-evidence retention rule; and
104
+ - any material observer effect.
105
+
106
+ Choose these items for the protected decision and instrument. Make Docs supplies no shared sample count, warmup, statistic, interval, variance limit, outlier rule, workload, environment, framework, or recipe.
107
+
108
+ Compare results only when their evidence fingerprints match or the profile states and supports an explicit equivalence rule. Do not silently compare material differences in host, operating system, architecture, virtualization, dependency state, power or thermal state, data, scale, configuration, or instrument.
109
+
110
+ Keep uncertainty, environment variance, instrument limits, exclusions, and excluded observations visible. Apply only the predeclared outlier rule. If variance or measurement resolution cannot support the decision margin, use `revise` or `blocked`.
111
+
112
+ ## Protect Non-Sacrificable Constraints
113
+
114
+ Correctness, durability, safety, security, privacy, accessibility, portability, cost, and maintainability are preconditions. A faster result cannot pass when it breaks one of these constraints.
115
+
116
+ Validate the fixture and measurement seam before optimization work begins.
117
+
118
+ ## Bound The Work
119
+
120
+ Each execution phase must declare finite limits for:
121
+
122
+ - characterization passes;
123
+ - materially distinct correction attempts;
124
+ - review cycles;
125
+ - elapsed investigation time;
126
+ - compute; and
127
+ - external resource spend.
128
+
129
+ An unspecified or self-renewing budget is invalid.
130
+
131
+ The evidence fingerprint binds the profile version and digest, build, relevant code and dependency state, configuration, environment, workload, fixture or dataset, instrument version, and analysis method. It also records the comparability result and reasons. A fingerprint supports a reuse decision. It does not authorize an execution.
132
+
133
+ When the fingerprint is unchanged, reuse the prior applicable result. A desire for another outcome is not a material change. The single requalification case below is the only exception.
134
+
135
+ After a material change, rerun only the affected checks. Reuse all unaffected valid evidence. Spend only the remaining authorized budget.
136
+
137
+ Stop at budget exhaustion or diminishing return. Diminishing return exists when distinct attempts do not change the verdict, an improvement is below the declared resolution or tolerance, or the next attempt costs more than the remaining budget. Use `blocked`, `revise`, a scoped `fail`, or an owner decision. Do not grow the budget without new authority.
138
+
139
+ Evidence must cover the smallest representative scope that supports the decision. Do not require an exhaustive matrix or proof outside claimed configurations.
140
+
141
+ The budget ledger must name the authorizing plan or work scope, budget event, declared limits, each distinct attempt, affected checks, time, compute, spend, review cycles, remaining budget, reused evidence, stop reason, and escalation. It cannot renew itself.
142
+
143
+ ## Record Outcomes, Findings, And Waivers
144
+
145
+ Each executed profile version has one outcome:
146
+
147
+ | Outcome | Meaning |
148
+ | --- | --- |
149
+ | `pass` | The exact profile version and supported scope meet the rule, with required evidence and all non-sacrificable constraints intact. |
150
+ | `fail` | Comparable and reproducible evidence shows a valid target miss or constraint break. |
151
+ | `revise` | The target, profile, protocol, comparison rule, uncertainty treatment, or protected outcome is not fit for the decision. |
152
+ | `blocked` | A required environment, dependency, instrument, access, budget, or other precondition is missing. It proves neither pass nor fail. |
153
+ | `waived` | The owner accepts a stated risk for a bounded scope and time. It is not a pass. |
154
+
155
+ Use one severity for each result or finding: `critical`, `major`, `moderate`, or `minor`. Use one reproducibility state: `reproduced`, `not-reproduced`, `intermittent`, or `not-attempted`.
156
+
157
+ A performance result must record its identity, exact profile binding, build, fingerprint, environment, workload, raw and analyzed evidence, observed distribution, uncertainty, exclusions, budget ledger, outcome, findings, owner or reviewer disposition, scope limit, expiry, and later-result link.
158
+
159
+ A finding must record its identity, observed behavior, expected protected outcome, target class, severity, reproducibility and attempts, affected scope, source requirement, evidence, owner, disposition, expiry, remediation work, and later result. Completing a task does not close a finding by itself.
160
+
161
+ A waiver must name the exact requirement and profile, miss, affected scope, reason, accepted risk, non-sacrificable constraint status, owner, approver, expiry or release boundary, reevaluation or remediation trigger, and linked `O-###` when work remains owed. A waiver cannot be indefinite or self-approved by an implementation agent. It cannot promote a support claim. Renewal needs material review.
162
+
163
+ An escalation must state the profile, evidence, current outcome, severity, reproducibility, budget used, unchanged-check state, real decision deadline when one exists, and owner choices. The implementation agent can report options. It cannot select a change to authority.
164
+
165
+ ## Expire And Requalify Evidence
166
+
167
+ Evidence expires when a declared change or boundary makes it no longer current. Triggers can include the profile, build, environment, workload, scope, dependency, instrument, analysis method, time boundary, or release boundary.
168
+
169
+ Expired evidence remains history. It cannot support a current pass. Expiry does not authorize execution, renew a budget, or imply pass or fail.
170
+
171
+ Each requalification needs separate owner or phase authorization and a new finite budget. If the fingerprint is unchanged, that authorization permits exactly one bounded qualification execution. After that execution, reuse the result until a valid later trigger and another explicit authorization.
172
+
173
+ If a material change occurs during requalification, rerun only affected checks within the remaining requalification budget.
174
+
175
+ ## Keep Proof Modes Separate
176
+
177
+ Performance Testing does not replace Automated Implementation Testing, Guided Progress Review, Unassisted Goal Testing, agent Human Experience Review, owner or architecture review, accessibility testing, visual regression, static-adapter proof, direct installed-product proof, release validation, or support-claim promotion.
178
+
179
+ Another proof type can report perceived slowness or share a physical run. It certifies no performance profile unless the performance authority, required fields, comparison rules, and outcome stay explicit. A performance result does not certify another proof type or gate.
180
+
181
+ ## Keep Repository And Operational State Separate
182
+
183
+ The repository is canonical for qualification, target class, `PERF-###` identity and schema, source requirements, protected outcome, scope, target and waiver meaning, owner, approver, expiry rules, findings that change product meaning, obligations, and history.
184
+
185
+ Project State or the Global Store can project run IDs, fingerprints, raw-evidence references, timestamps, attempt and budget ledgers, review state, and large-evidence references. This state is operational only. It must be privacy-bounded and rebuildable from repository authority and retained evidence.
186
+
187
+ A Store row or receipt proves only the operational write. It does not create or change product meaning. Missing operational evidence makes a required result unverified. It does not erase or reinterpret the repository profile.
188
+
189
+ ## Adopt Without Retroactive Claims
190
+
191
+ Do not retroactively fail completed phases. At the first qualifying design, plan, PRD maintenance, work generation, or phase close, inventory active thresholds, regression claims, resource budgets, absolute performance language, benchmark assets, and current evidence.
192
+
193
+ Keep an existing hard target only when its source, owner, protected outcome, profile, and comparability can be calibrated. Otherwise, the owner must reclassify, defer, narrow, or remove it through current authority.
194
+
195
+ Existing scripts and results remain assets only for what they prove. Adoption does not delete, move, rename, rerun, certify, tighten, promote, or broaden them. Do not infer a pass from old green output or fabricate missing evidence.
196
+
197
+ ## Validation Methods
198
+
199
+ Use one or both methods. Keep their evidence separate.
200
+
201
+ ### Deterministic method
202
+
203
+ When the Make Docs CLI is available, run:
204
+
205
+ ```text
206
+ make-docs run performance evidence validate --target-root <project>
207
+ ```
208
+
209
+ The operation reads Markdown repository authority under `docs/` and `.make-docs/archive/history/`. It inventories candidate language and validates the catalog-marked structural facts. It runs no benchmark and writes no project, Store, or host file.
210
+
211
+ The result status is `passed`, `failed`, `blocked`, or `refused`. Only `passed` earns `validator-passed`. A failed, blocked, or refused result has no favorable proof state. A fingerprint classification is only `unchanged`, `materially-changed`, or `not-comparable`, with its recorded reason. It never authorizes an execution or retry.
212
+
213
+ ### Agent method
214
+
215
+ Use this method when the CLI is absent or unavailable, or when a catalog rule requires judgment.
216
+
217
+ 1. Read repository authority from `docs/` and `.make-docs/archive/history/`. Do not use hidden state as authority.
218
+ 2. State whether the deterministic operation ran. If it did not run, say so. Do not infer a validator pass.
219
+ 3. Inventory numeric units, rates, percentiles, percentages, resource quantities, relative comparisons, and absolute performance language. Do not decide applicability from the inventory alone.
220
+ 4. Review every applicable `PERF-###` profile and linked result, finding, waiver, obligation, and evidence record against the rule catalog below.
221
+ 5. For each reviewed rule, record the rule ID, exact evidence, observation, conclusion, limit, and next action.
222
+ 6. Apply judgment only to catalog rules marked `agent-only` or `partial`. Report a missing owner choice as a product question. Do not answer it on the owner's behalf.
223
+ 7. Preserve missing, invalid, expired, non-comparable, adjacent-mode, and unsupported evidence without favorable inference.
224
+ 8. A complete agent review can earn `agent-reviewed`. It cannot earn `validator-passed`. Use `combined` only when a separate passed deterministic result and a separate completed agent review both exist.
225
+
226
+ The agent method is read-only. It does not repair files, run a benchmark, select a target, approve a waiver, close a finding or obligation, renew a budget, authorize a run or retry, promote supported scope, or substitute for another testing or proof mode.
227
+
228
+ ### Stable rule catalog
229
+
230
+ | Rule | Class | Deterministic support | Agent review | Diagnostic | Parity or one-sided reason |
231
+ | --- | --- | --- | --- | --- | --- |
232
+ | `PERF-RULE-001` | fact | full | Confirm safe, readable repository authority roots. | `PERF-VAL-001` | Both methods stop on unreadable, unsafe, or escaping authority. |
233
+ | `PERF-RULE-002` | fact | full | Inventory candidate language without deciding applicability. | `PERF-VAL-002` | Both methods preserve the same candidate classes. |
234
+ | `PERF-RULE-003` | fact | full | Confirm one append-only `PERF-###` identity, version, and digest. | `PERF-VAL-003` | Both methods inspect the same profile binding. |
235
+ | `PERF-RULE-004` | fact | full | Confirm required profile structure and resolved values. | `PERF-VAL-004` | Both methods use the canonical profile shape. |
236
+ | `PERF-RULE-005` | fact | full | Confirm the target class and canonical owner location. | `PERF-VAL-005` | Both methods use the target-class owner map. |
237
+ | `PERF-RULE-006` | fact | full | Confirm the durable approver and required target approval. | `PERF-VAL-006` | Both methods require recorded approval evidence. |
238
+ | `PERF-RULE-007` | fact | full | Confirm expiry triggers and one bounded unchanged-fingerprint requalification. | `PERF-VAL-007` | Both methods preserve expiry and separate requalification authority. |
239
+ | `PERF-RULE-008` | fact | full | Confirm every evidence limit is finite and cannot renew itself. | `PERF-VAL-008` | Both methods reject unspecified, unlimited, and self-renewing budgets. |
240
+ | `PERF-RULE-009` | fact | full | Confirm diminishing-return and budget-exhaustion stops. | `PERF-VAL-009` | Both methods preserve finite stop behavior. |
241
+ | `PERF-RULE-010` | fact | full | Confirm only `pass`, `fail`, `revise`, `blocked`, and `waived`. | `PERF-VAL-010` | Both methods keep outcome and proof state separate. |
242
+ | `PERF-RULE-011` | fact | full | Confirm authority, plan, work, result, finding, waiver, and obligation lineage. | `PERF-VAL-011` | Both methods keep repository records authoritative. |
243
+ | `PERF-RULE-012` | fact | full | Confirm evidence links are present, readable, and repository-bounded. | `PERF-VAL-012` | Both methods preserve missing or unsafe evidence as a failure state. |
244
+ | `PERF-RULE-013` | fact | full | Report the declared fingerprint class and reason only. | `PERF-VAL-013` | Neither method turns fingerprint equality into run authority. |
245
+ | `PERF-RULE-014` | fact | partial | Decide whether a flagged numeric work criterion is stricter than linked authority. | `PERF-VAL-014` | The validator flags missing traceability. The agent supplies the decision-specific comparison. |
246
+ | `PERF-RULE-015` | decision | agent-only | Review applicability and maturity against the current product decision. | `PERF-AGENT-015` | Applicability and maturity depend on current risk, value, and product direction. |
247
+ | `PERF-RULE-016` | decision | agent-only | Review whether the declared environment and comparison support the current decision. | `PERF-AGENT-016` | Representative conditions and material equivalence require decision-specific judgment. |
248
+ | `PERF-RULE-017` | decision | agent-only | Review impact, severity, accepted risk, waiver authority, and supported scope. | `PERF-AGENT-017` | These items are owner decisions and cannot be derived from structure. |
249
+ | `PERF-RULE-018` | fact | full | Confirm honest proof state and all method limits. | `PERF-VAL-018` | Each method reports only its own evidence path and never certifies the other. |
250
+
251
+ Any catalog change must review its mapped deterministic rule, agent instruction, diagnostic, fixtures, and tests. An agent-only or otherwise one-sided rule must retain its explicit reason.
252
+
253
+ ## Automation Limit
254
+
255
+ The deterministic operation may check structure, links, identity, owner location, approval, expiry, budget, stop rules, traceability, evidence references, controlled vocabulary, and declared fingerprint equality.
256
+
257
+ Neither method may decide applicability, maturity, target value, analysis method, representative environment, comparability, user impact, severity, trade-offs, waiver approval, obligation fulfillment, supported scope, requirement changes, or support-claim promotion. Neither method may authorize executions or retries.
@@ -0,0 +1,93 @@
1
+ # System Resource Contract
2
+
3
+ ## Purpose
4
+
5
+ Use this contract to author, identify, list, and read Make Docs system resources.
6
+
7
+ A system resource is reusable Make Docs content owned by the shipped template. Contracts, prompts, references, and templates are four peer resource types. A peer type has the same identity and catalog standing as each other type.
8
+
9
+ ## Upstream Authority
10
+
11
+ Author system resources only in these physical upstream package roots:
12
+
13
+ | Type | Upstream source root |
14
+ | --- | --- |
15
+ | `contract` | `packages/docs/template/.make-docs/system/contracts/` |
16
+ | `prompt` | `packages/docs/template/.make-docs/system/prompts/` |
17
+ | `reference` | `packages/docs/template/.make-docs/system/references/` |
18
+ | `template` | `packages/docs/template/.make-docs/system/templates/` |
19
+
20
+ The catalog at `packages/docs/template/.make-docs/system-resources.catalog.json` is the one upstream inventory. Its schema is `packages/docs/template/.make-docs/system-resources.schema.json`. These physical paths are maintainer authoring authority. Provider-backed consumers do not depend on them.
21
+
22
+ Routers named `AGENTS.md` or `CLAUDE.md` are local instruction surfaces. They are not content resources and do not receive a system-resource URI.
23
+
24
+ ## Stable Identity
25
+
26
+ Each resource has one stable URI:
27
+
28
+ `make-docs://system/<type>/<posix-relative-path>`
29
+
30
+ The type is singular. The path is the file path relative to its type root. A POSIX-relative path uses `/` as the separator on every platform.
31
+
32
+ The path is case-sensitive. It must not be empty or absolute. It must not contain `.` or `..` segments. It must not expose a package, project, home, or temporary installation path.
33
+
34
+ ## Resource Metadata
35
+
36
+ The catalog supplies or derives this metadata for each current resource:
37
+
38
+ | Field | Source |
39
+ | --- | --- |
40
+ | `uri` | Stable URI derived from type and relative path |
41
+ | `type` | Catalog type entry |
42
+ | `path` | Path relative to the type root |
43
+ | `mediaType` | Catalog default or a later explicit resource override |
44
+ | `origin` | Effective source selected by the resolver |
45
+ | `providerIdentity` | Installed provider identity |
46
+ | `packageIdentity` | Installed package identity |
47
+ | `versionOrRef` | Provider version or immutable reference |
48
+ | `digest` | Hash algorithm and hash derived from the exact resource bytes |
49
+ | `localPath` | Local path when a trusted local source supplied the bytes |
50
+ | `provenanceState` | Evidence state for the provider or trusted local source |
51
+ | `content` | Exact resource bytes |
52
+
53
+ Here, a provider is an installed source of resource bytes. Provenance is evidence of where those bytes came from and who owns them.
54
+
55
+ The catalog and path supply the fields known during authoring. Origin, provider, package, version, digest, local path, provenance, and content fields are derived when the provider inventory is built or read. A catalog entry must not prefill a false provider version, local path, or digest.
56
+
57
+ ## Provider And Projection
58
+
59
+ The installed provider is the default list and read source. A project does not need a local copy of a resource.
60
+
61
+ An explicit, trustworthy local projection may supply the same URI under `.make-docs/system/{contracts,prompts,references,templates}/`. Local projection is optional. It must retain provider, version, URI, path, ownership, and hash evidence. A changed or untrusted local file must not silently replace provider bytes.
62
+
63
+ ## Prompt Boundary
64
+
65
+ A prompt is a first-class resource. Do not store a current prompt below the reference root. A prompt may route an agent through a workflow, but the governing contract owns reusable rules and constraints.
66
+
67
+ Do not add prompt inclusion, template mode, reference mode, or another legacy resource selection field. Resource availability does not depend on local projection.
68
+
69
+ ## System Workflow Composition
70
+
71
+ A system workflow is a named catalog composition of current contract, prompt, reference, and template URIs. It does not create a fifth resource type, generic workflow engine, Playbook, Protocol, Skill requirement, or local projection requirement.
72
+
73
+ The Unassisted Goal Testing workflow is the first catalog composition. Its stable `naive-uat` ID and resource names remain for compatibility. Its governing policy remains in `make-docs://system/contract/naive-uat-contract.md`.
74
+
75
+ ## Preserved Legacy Files
76
+
77
+ The catalog may name physically preserved legacy files that are not current resources. A preserved legacy file keeps its bytes for later reviewed migration. Its presence does not give it a URI, provider standing, product capability, or support claim.
78
+
79
+ The Playbook contract and Playbook defaults remain preserved for the later traced retirement phase. They are not current Make Docs resources.
80
+
81
+ ## Validation
82
+
83
+ Validation must prove:
84
+
85
+ - the catalog matches its schema;
86
+ - all four types occur exactly once;
87
+ - each source root matches its type;
88
+ - every current resource derives one unique URI;
89
+ - every workflow URI resolves in the current inventory;
90
+ - routers are excluded from the content inventory;
91
+ - preserved legacy files are excluded from current resource identity;
92
+ - prompt files live under the prompt root;
93
+ - no legacy resource selection field appears as current authority.
@@ -0,0 +1,12 @@
1
+ <!-- make-docs:begin -->
2
+ # System Prompts Router
3
+
4
+ This always-local directory routes first-class Make Docs prompt resources. Prompt bodies are optional local projections.
5
+
6
+ - Use a valid local prompt body first. If it is absent, read `make-docs://system/prompt/<posix-relative-path>` with `make-docs resource read`.
7
+ - Keep prompt placeholders explicit unless the user asks to fill them.
8
+ - Before you run a prompt, read its governing contract, workflow reference, applicable template, and target output router.
9
+ - Keep reusable rules in contracts. A prompt may order or frame work, but it must not become a second policy source.
10
+ - Do not write generated plans, PRDs, work backlogs, designs, test evidence, or other project outputs 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 Prompts Router
3
+
4
+ This always-local directory routes first-class Make Docs prompt resources. Prompt bodies are optional local projections.
5
+
6
+ - Use a valid local prompt body first. If it is absent, read `make-docs://system/prompt/<posix-relative-path>` with `make-docs resource read`.
7
+ - Keep prompt placeholders explicit unless the user asks to fill them.
8
+ - Before you run a prompt, read its governing contract, workflow reference, applicable template, and target output router.
9
+ - Keep reusable rules in contracts. A prompt may order or frame work, but it must not become a second policy source.
10
+ - Do not write generated plans, PRDs, work backlogs, designs, test evidence, or other project outputs here.
11
+ - Do not infer optional Skills, plugins, Playbooks, Protocols, or unavailable policy from this router.
12
+ <!-- make-docs:end -->
@@ -0,0 +1,20 @@
1
+ ___
2
+ name: Coverage Pass - Maintainer Guide
3
+ description: Runs the maintainer-guide coverage pass for completed work using the coverage-pass and guide contracts.
4
+ ___
5
+
6
+ When generating or materially rewriting make-docs documents, include PRD 23 YAML frontmatter: common `title`, `kind`, and `status`; add `coordinate`, `persona`, `source`, `lifecycle`, and `follow_on` only when their conditions apply; omit unknown coordinate levels rather than inserting placeholders.
7
+
8
+ Please run the maintainer-guide coverage pass for the completed work context supplied with this request.
9
+
10
+ Before writing anything, read `.make-docs/system/contracts/coverage-pass-contract.md`, `.make-docs/system/contracts/guide-contract.md`, and the router at `docs/assets/AGENTS.md` (or `CLAUDE.md`). Treat those files as the authority; cite them in your closeout summary but do not restate their shared mechanics.
11
+
12
+ Use the guide coverage surface from the coverage-pass contract and the maintainer-guide audience rules from the guide contract. Choose an effective Persona with the `maintainer` primitive from the merged built-in defaults and valid project config. Without custom configuration, target `maintainer`. Either role can be human or agent; do not infer the audience from the executor.
13
+
14
+ Inspect existing guides under the selected effective Persona path and related guides for other effective Personas. Built-in paths are `docs/assets/maintainer/` and `docs/assets/user/`. Enumerate every candidate maintainer-facing capability, workflow, validation path, contract, extension point, operator task, or troubleshooting item from the completed work.
15
+
16
+ Assign exactly one verdict to every candidate: `create`, `update-existing`, `link-only`, or `none`. Include the target persona and a reason for each candidate, including `none`. Prefer updating an existing guide when it owns the topic.
17
+
18
+ Apply the history idempotency rule in `coverage-pass-contract.md` for this session and follow `history-record-contract.md` only if the pass creates or updates a history breadcrumb. Reference the validation checklist in `coverage-pass-contract.md` instead of restating it, and run focused validation for any changed files.
19
+
20
+ Close with a concise pass summary: verdict table, artifacts changed, validation run, no-change rationales, and remaining handoffs. If commit-message work is needed, read `make-docs://system/prompt/work-to-commit-message.prompt.md` with `make-docs resource read`; do not create a duplicate commit-message starter.
@@ -0,0 +1,18 @@
1
+ ___
2
+ name: Coverage Pass - PRD Reconciliation
3
+ description: Runs the PRD reconciliation coverage pass for completed work using the coverage-pass and PRD authority-maintenance contracts.
4
+ ___
5
+
6
+ When generating or materially rewriting make-docs documents, include PRD 23 YAML frontmatter: common `title`, `kind`, and `status`; add `coordinate`, `persona`, `source`, `lifecycle`, and `follow_on` only when their conditions apply; omit unknown coordinate levels rather than inserting placeholders.
7
+
8
+ Please run the PRD reconciliation coverage pass for the completed work context supplied with this request.
9
+
10
+ Before writing anything, read `.make-docs/system/contracts/coverage-pass-contract.md`, `.make-docs/system/references/prd-change-management.md`, `.make-docs/system/contracts/output-contract.md`, `docs/prd/AGENTS.md` (or `CLAUDE.md`), `docs/prd/00-index.md`, and `docs/prd/03-open-questions-and-risk-register.md`. Treat those files as the authority; cite them in your closeout summary but do not restate their shared mechanics.
11
+
12
+ Use the PRD reconciliation coverage surface from the coverage-pass contract. Inspect the active PRD namespace and enumerate every candidate current-requirement update, genuinely new capability authority, requirement-history entry, risk-register item, index/status update, discoverability pointer, or no-change decision raised by the completed work.
13
+
14
+ Assign exactly one verdict to every candidate: `create`, `update-existing`, `link-only`, or `none`. Include a reason for each candidate, including `none`. Update the active PRD owner in place when its subject owns the requirement. Use `create` only for a coherent, wholesale new capability, subsystem, or product boundary with no suitable owner. Never create a PRD that describes the editorial operation used to change product authority.
15
+
16
+ Apply the history idempotency rule in `coverage-pass-contract.md` for this session and follow `history-record-contract.md` only if the pass creates or updates a history breadcrumb. Reference the validation checklist in `coverage-pass-contract.md` and the PRD validation checklist in `prd-change-management.md` instead of restating them, and run focused validation for any changed files.
17
+
18
+ Close with a concise pass summary: verdict table, artifacts changed, validation run, no-change rationales, and remaining handoffs. If commit-message work is needed, read `make-docs://system/prompt/work-to-commit-message.prompt.md` with `make-docs resource read`; do not create a duplicate commit-message starter.
@@ -0,0 +1,46 @@
1
+ ___
2
+ name: Coverage Pass - Testing
3
+ description: Runs the proportionate testing coverage pass for completed work.
4
+ ___
5
+
6
+ Run the testing coverage pass for the completed work context supplied with this request.
7
+
8
+ Before writing, read `.make-docs/system/contracts/coverage-pass-contract.md` and `.make-docs/system/contracts/history-record-contract.md`. When Unassisted Goal Testing or an accepted future outcome can apply, also read `.make-docs/system/contracts/naive-uat-contract.md` and `.make-docs/system/contracts/deferred-obligation-contract.md`. Read the local test, validation, release, and acceptance documents that own the changed surface.
9
+
10
+ When a performance candidate exists, also read `.make-docs/system/contracts/performance-evidence-governance.md`. Use it as the only detailed performance policy source.
11
+
12
+ Use the testing coverage surface from the coverage-pass contract. Make a separate current decision for each applicable testing type. Consider automated implementation testing, performance testing, guided progress review, Unassisted Goal Testing, specialist accessibility testing, visual regression, conformance, smoke tests, no-test decisions, and validation links.
13
+
14
+ For each testing decision, record:
15
+
16
+ - Testing type;
17
+ - Decision informed;
18
+ - Reason now;
19
+ - Product maturity;
20
+ - Scope;
21
+ - Executor;
22
+ - Gate effect;
23
+ - Effort budget;
24
+ - Stop condition;
25
+ - Evidence retained; and
26
+ - Rerun trigger.
27
+
28
+ For each performance candidate, also record:
29
+
30
+ - Base maintenance action;
31
+ - Performance applicability;
32
+ - Canonical `PERF-###` profile link or `none`;
33
+ - Finite evidence budget and stop-rule reference or `not-applicable`; and
34
+ - Outcome and evidence handoff or `none`.
35
+
36
+ For required performance evidence, check the exact profile version and digest, fingerprint comparability, supported scope, outcome, material findings, waiver scope and expiry, obligation links, remaining budget, unchanged-result reuse, and requalification state. Missing, expired, invalid, non-comparable, adjacent-mode, or unrun required evidence is not a pass. A waiver is bounded risk acceptance, not success.
37
+
38
+ For Unassisted Goal Testing, activate a run only when it 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 obligation only for this result.
39
+
40
+ For each activated run, resolve one configured Persona whose primitive is `user` or `maintainer`. Use canonical `user` when none is supplied. Keep Persona selection separate from executor qualification. Use one result: `clear`, `friction`, `blocked`, or `invalid-run`. Keep the default gate effect advisory unless explicit current authority names a blocking effect.
41
+
42
+ Reuse unchanged evidence. Expand testing only after a failure signal, a cross-cutting change, an explicit support claim, or accepted risk. Stop when the recorded budget or stop condition ends.
43
+
44
+ Apply the history idempotency rule in `coverage-pass-contract.md`. Follow `history-record-contract.md` for any history record. Run focused validation for changed files.
45
+
46
+ Close with a short summary of the testing decisions, files changed, validation run, any activated `NUAT-###`, any `not-needed-now` result, and remaining handoffs. If commit-message work is needed, read `make-docs://system/prompt/work-to-commit-message.prompt.md` with `make-docs resource read`.
@@ -0,0 +1,20 @@
1
+ ___
2
+ name: Coverage Pass - User Guide
3
+ description: Runs the user-guide coverage pass for completed work using the coverage-pass and guide contracts.
4
+ ___
5
+
6
+ When generating or materially rewriting make-docs documents, include PRD 23 YAML frontmatter: common `title`, `kind`, and `status`; add `coordinate`, `persona`, `source`, `lifecycle`, and `follow_on` only when their conditions apply; omit unknown coordinate levels rather than inserting placeholders.
7
+
8
+ Please run the user-guide coverage pass for the completed work context supplied with this request.
9
+
10
+ Before writing anything, read `.make-docs/system/contracts/coverage-pass-contract.md`, `.make-docs/system/contracts/guide-contract.md`, and the router at `docs/assets/AGENTS.md` (or `CLAUDE.md`). Treat those files as the authority; cite them in your closeout summary but do not restate their shared mechanics.
11
+
12
+ Use the guide coverage surface from the coverage-pass contract and the user-guide audience rules from the guide contract. Choose an effective Persona with the `user` primitive from the merged built-in defaults and valid project config. Without custom configuration, target `user`. Either role can be human or agent; do not infer the audience from the executor.
13
+
14
+ Inspect existing guides under the selected effective Persona path and related guides for other effective Personas. Built-in paths are `docs/assets/user/` and `docs/assets/maintainer/`. Enumerate every candidate user-facing capability, workflow, concept, decision point, prerequisite, expected result, or troubleshooting item from the completed work.
15
+
16
+ Assign exactly one verdict to every candidate: `create`, `update-existing`, `link-only`, or `none`. Include the target persona and a reason for each candidate, including `none`. Prefer updating an existing guide when it owns the topic.
17
+
18
+ Apply the history idempotency rule in `coverage-pass-contract.md` for this session and follow `history-record-contract.md` only if the pass creates or updates a history breadcrumb. Reference the validation checklist in `coverage-pass-contract.md` instead of restating it, and run focused validation for any changed files.
19
+
20
+ Close with a concise pass summary: verdict table, artifacts changed, validation run, no-change rationales, and remaining handoffs. If commit-message work is needed, read `make-docs://system/prompt/work-to-commit-message.prompt.md` with `make-docs resource read`; do not create a duplicate commit-message starter.
@@ -0,0 +1,18 @@
1
+ ___
2
+ name: Designs to PRD Authority Maintenance Plan
3
+ description: Instructs the agent to review one or more design docs and plan surgical maintenance of the active product authority.
4
+ ___
5
+
6
+ When generating or materially rewriting make-docs documents, include PRD 23 YAML frontmatter: common `title`, `kind`, and `status`; add `coordinate`, `persona`, `source`, `lifecycle`, and `follow_on` only when their conditions apply; omit unknown coordinate levels rather than inserting placeholders.
7
+
8
+ Please read the design docs {{DESIGN DOCS}} and inspect each doc's `## Intended Follow-On` section before planning. If a design includes `Coordinate Handoff`, use it as the starting point for W/R resolution.
9
+
10
+ Confirm that the referenced design docs point to the `change-plan` route. If they point to `baseline-plan`, use the baseline planning prompt instead unless the user explicitly instructs otherwise.
11
+
12
+ Read `make-docs://system/contract/human-experience-contract.md`, `make-docs://system/reference/human-experience.md`, and `make-docs://system/reference/lifecycle.md` through valid local bodies or `make-docs resource read`. Treat each source design's Human Experience Intent as the local outcome authority. Map each accepted promise or preserved `none` boundary to its owning PRD, affected surface or artifact, work phase, evidence source or current testing decision, evidence executor when current authority selects one, and obligation route for accepted deferral. Preserve the source design and W/R lineage through existing links and allowed metadata. Do not copy the full intent section or standard into the plan.
13
+
14
+ Then inspect the active PRD namespace in `docs/prd/` and create a detailed PRD authority-maintenance plan in `docs/plans/`. Follow the instructions, references, and templates in the `docs` directory, especially `.make-docs/system/references/wave-model.md` and `.make-docs/system/references/prd-change-management.md`.
15
+
16
+ Resolve the plan coordinate before writing. Source lineage from the user request, design handoff, prior plans, prior work backlogs, and history records takes precedence over the highest existing wave. If the change revises, reworks, corrects, standardizes, or finishes work delivered in an earlier wave, keep that wave and use the next unused revision.
17
+
18
+ For every candidate requirement, select `update-existing`, `create`, `link-only`, or `none`. The plan must list existing PRD owners to update; genuinely new product PRDs, if any; required non-normative `## Requirement History` entries; and affected links, risks, plans, and work artifacts. Record the plan coordinate and state whether a scoped delta backlog is sufficient. Do not plan standalone PRDs whose subject is an editorial operation.
@@ -0,0 +1,14 @@
1
+ ___
2
+ name: Design to Plan
3
+ description: Instructs the agent to review referenced design docs and then generate a detailed plan.
4
+ ___
5
+
6
+ When generating or materially rewriting make-docs documents, include PRD 23 YAML frontmatter: common `title`, `kind`, and `status`; add `coordinate`, `persona`, `source`, `lifecycle`, and `follow_on` only when their conditions apply; omit unknown coordinate levels rather than inserting placeholders.
7
+
8
+ Please read the design docs {{DESIGN DOCS}} and inspect each doc's `## Intended Follow-On` section before planning. If a design includes `Coordinate Handoff`, use it as the starting point for W/R resolution.
9
+
10
+ Confirm that the referenced design docs point to the `baseline-plan` route. If they point to `change-plan`, use the change-planning prompt instead unless the user explicitly instructs otherwise.
11
+
12
+ Read `make-docs://system/contract/human-experience-contract.md`, `make-docs://system/reference/human-experience.md`, and `make-docs://system/reference/lifecycle.md` through valid local bodies or `make-docs resource read`. Treat each source design's Human Experience Intent as the local outcome authority. Map each accepted promise or preserved `none` boundary to its owning PRD, affected surface or artifact, work phase, evidence source or current testing decision, evidence executor when current authority selects one, and obligation route for accepted deferral. Preserve the source design and W/R lineage through existing links and allowed metadata. Do not copy the full intent section or standard into the plan.
13
+
14
+ Then help me create a detailed plan document in `docs/plans` to implement this design idea. Follow `.make-docs/system/references/wave-model.md` and record the coordinate decision in the plan.
@@ -0,0 +1,29 @@
1
+ ___
2
+ name: Docs Path Hygiene Cleanup
3
+ description: Instructs the agent to audit and repair Make Docs-managed documentation for local absolute checkout and user-specific paths.
4
+ ___
5
+
6
+ Please audit and repair Make Docs-managed documentation for local, user-specific, or checkout-specific paths.
7
+
8
+ Before editing anything, read `docs/AGENTS.md`, and `.make-docs/system/references/path-and-link-hygiene.md`. Treat the path hygiene reference as the authority for project-relative paths, relative Markdown links, sanitized placeholders, and full-path exceptions.
9
+
10
+ Run the CLI checker. It selects local content without a manifest or Store. If the CLI is absent, review paths manually and report that the automated check did not run. Use repeated `--path <project-relative-file-or-directory>` arguments for a custom docs root or a narrower reviewed scope. Never create operational state to make this check run:
11
+
12
+ ```bash
13
+ make-docs project path-hygiene validate --format json
14
+ ```
15
+
16
+ Preview safe project-path repairs with `make-docs project path-hygiene repair --format text`. Add `--apply` to write the repairs.
17
+
18
+ For each still-valid finding, repair the documentation with a project-relative path or sanitized placeholder. Preserve full paths only when the reference allows the exception, and add or preserve the `make-docs-path-hygiene: allow` comment with a clear reason.
19
+
20
+ After repairs, rerun:
21
+
22
+ ```bash
23
+ make-docs project path-hygiene validate --format text
24
+ just docs-links docs
25
+ just docs-style docs
26
+ git diff --check
27
+ ```
28
+
29
+ Report the files changed, the findings fixed, any findings intentionally skipped with reasons, and any validation command that could not be run.
@@ -0,0 +1,28 @@
1
+ ___
2
+ name: Unassisted Goal Testing Facilitator
3
+ description: Decides activation and supervises one qualified unassisted attempt without coaching.
4
+ ___
5
+
6
+ Read these resources before you decide or prepare a run:
7
+
8
+ - `make-docs://system/contract/naive-uat-contract.md`
9
+ - `make-docs://system/reference/naive-uat-workflow.md`
10
+ - `make-docs://system/template/naive-uat-scenario.md`
11
+
12
+ Record the common testing decision fields. Activate a run only when it can answer a material current human-experience uncertainty, or when explicit current authority requires it.
13
+
14
+ When no current decision justifies a run, return `not-needed-now` with the reason, applicable evidence, advisory gate effect, effort budget, stop condition, and rerun trigger. Do not create a scenario or obligation only for this result.
15
+
16
+ When testing activates, use canonical scenario `{{NUAT_SCENARIO_ID}}` at version `{{SCENARIO_VERSION}}` from `{{OWNING_PRD}}`.
17
+
18
+ Resolve `{{PERSONA_SLUG_OR_DEFAULT_USER}}` against the configured Persona set. Accept only a `user`- or `maintainer`-primitive Persona. Keep Persona identity separate from executor qualification.
19
+
20
+ Qualify a human or an agent in a separate isolated context. Prove 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.
21
+
22
+ Prepare the normally consumable product, realistic environment, consent, capture, safety, and teardown boundary. Render the operator view and tester packet from the same scenario record. Remove leaked requirement IDs, work coordinates, implementation terms, hidden setup, expected answers, preferred steps, or operator success rules.
23
+
24
+ Start the qualified executor with only the tester prompt, approved tester packet, product access, and allowed public resources. Do not give the executor this facilitator prompt.
25
+
26
+ Record every intervention. Stop for safety when required. Save approved records and evidence under `docs/assets/<persona-slug>/testing/`. Bind them to the exact scenario version or digest.
27
+
28
+ Return the run record, findings, one result of `clear`, `friction`, `blocked`, or `invalid-run`, and the applicable PRD, work, and gate routes. Use an obligation route only when an accepted future outcome remains owed. Do not treat a typed Store receipt as proof of the result.
@@ -0,0 +1,20 @@
1
+ ___
2
+ name: Unassisted Goal Testing Executor
3
+ description: Starts one qualified executor with an approved goal packet and no private product context.
4
+ ___
5
+
6
+ You are the executor for `{{NUAT_SCENARIO_ID}}` at version `{{SCENARIO_VERSION}}`.
7
+
8
+ Use only:
9
+
10
+ - the product access in `{{PRODUCT_ACCESS}}`;
11
+ - the approved tester packet in `{{TESTER_PACKET}}`; and
12
+ - the public or realistic resources listed in that packet.
13
+
14
+ Do not use source code, private project files, implementation notes, PRDs, work backlogs, private conversations, hidden setup, known defects, remembered successful steps, or other private route knowledge.
15
+
16
+ Attempt the goal in the way that makes sense to you. You can stop for safety, privacy, access, consent, unexpected spending, or possible data loss.
17
+
18
+ Report what you tried, what you expected, what happened, where you hesitated or became confused, which allowed help you used, whether you recovered, and whether you completed the goal.
19
+
20
+ Record any help or intervention you received. Do not claim a clear result when private or material coaching supplied the route or answer.