@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,114 @@
1
+ # Performance Evidence Reference
2
+
3
+ ## Purpose
4
+
5
+ Use this reference to understand the performance evidence workflow in plain language.
6
+
7
+ The [Performance Evidence Governance Contract](../contracts/performance-evidence-governance.md) owns the rules. The [performance coverage prompt](../prompts/performance-coverage.prompt.md) orders the inventory. The [performance evidence profile template](../templates/performance-evidence-profile.md) supplies the record shape.
8
+
9
+ ## Qualify Before You Measure
10
+
11
+ Start with the decision, not the benchmark.
12
+
13
+ Ask what user or business outcome needs protection. Ask what decision the evidence can change. Then record the cost of failure, current product maturity, support scope, risk, reversibility, source authority, current baseline, owner, and lifecycle point.
14
+
15
+ This step can end with no measurement. `Not-needed` means evidence cannot change a current decision. `Reject-unsupported` means the proposed claim has no sound basis. `Defer-required` sends an accepted later outcome to one `O-###` record. These are complete governance results.
16
+
17
+ Only `required-now` and `characterize-now` can lead to an executable profile.
18
+
19
+ ## Understand Target Classes
20
+
21
+ A target class says what authority the record has.
22
+
23
+ A `hard-product-requirement` is the only product target. It lives in the active PRD that owns the protected outcome. The owner must approve it.
24
+
25
+ An `engineering-guardrail` protects bounded engineering work. A `characterization-baseline` describes observed behavior and uncertainty. An `experiment-or-stretch` supports a bounded inquiry. These profiles live in accepted plan or work authority. They do not define product support.
26
+
27
+ A `deferred-required-outcome` stays in an `O-###` record until activation. An `unsupported-assumption` has no executable profile.
28
+
29
+ Characterization is not promotion. A measured baseline becomes a threshold only after the owner accepts the reason, trade-offs, comparison basis, and authority change. Product promotion needs PRD maintenance and explicit lineage.
30
+
31
+ ## Keep One Profile Identity
32
+
33
+ Use one `PERF-###` ID for one protected outcome and workload. Keep that ID when details change. Increase `profile_version` for a meaningful change to the target, authority, scope, environment, workload, method, analysis, or outcome rules.
34
+
35
+ Use a new ID for a different outcome or workload. Bind each result to the exact ID, version, and source digest.
36
+
37
+ Lineage explains where a profile came from and what replaced it. Record promotion, predecessor, successor, supersession, and retirement links. This prevents an old result from looking current.
38
+
39
+ ## Use Fingerprints For Comparison And Reuse
40
+
41
+ An evidence fingerprint identifies the exact profile, build, dependencies, configuration, environment, workload, fixture, instrument, and analysis method used for a result.
42
+
43
+ Matching fingerprints support direct comparison and reuse. A declared equivalence rule can support comparison when a controlled difference is known and justified. A silent environment or workload difference does not.
44
+
45
+ If the fingerprint is unchanged, use the current applicable result. Wanting another answer is not a reason to rerun.
46
+
47
+ If something material changed, rerun only the checks affected by that change. Keep valid unaffected evidence.
48
+
49
+ ## Use A Finite Budget
50
+
51
+ Every execution has a fixed budget before it starts. The budget covers characterization passes, distinct correction attempts, review cycles, elapsed time, compute, and outside spend.
52
+
53
+ The budget ledger shows what authority supplied the budget. It also shows each attempt, affected checks, resources used, remaining budget, reused evidence, and the stop reason.
54
+
55
+ Stop when the budget ends. Stop when distinct attempts no longer change the decision. Stop when a possible gain is below the declared resolution or tolerance. Stop when the next attempt costs more than the remaining budget.
56
+
57
+ The next result can be `blocked`, `revise`, a scoped `fail`, or an owner decision. The budget does not grow by itself.
58
+
59
+ ## Read Outcomes Carefully
60
+
61
+ `Pass` applies only to the exact profile version and supported scope. It also requires all protected constraints to remain intact.
62
+
63
+ `Fail` needs comparable and reproducible evidence of a valid miss. `Revise` means the decision record or method is not fit. `Blocked` means a required precondition is missing and proves neither pass nor fail. `Waived` means an owner accepts a bounded risk. A waiver is never a pass.
64
+
65
+ Findings keep the observed behavior, expected outcome, severity, reproducibility, scope, evidence, owner, disposition, expiry, and later result together. A task closure does not close a finding by itself.
66
+
67
+ Waivers need an exact scope, owner, approver, risk, end point, and review trigger. Link an `O-###` when future work remains owed.
68
+
69
+ ## Expiry Does Not Authorize A Rerun
70
+
71
+ Evidence can expire after a material profile, build, environment, workload, scope, dependency, instrument, analysis, time, or release change. It remains useful history but no longer supports a current pass.
72
+
73
+ Expiry does not create a new budget. Requalification needs separate authority and a new finite budget.
74
+
75
+ When the fingerprint is unchanged, one authorized requalification event permits one bounded qualification execution. Then the new result is reused until another valid trigger and another explicit authorization.
76
+
77
+ ## Keep Authority Failures Visible
78
+
79
+ Stop and report an authority gap when:
80
+
81
+ - a hard target has no active owning PRD or owner approval;
82
+ - a plan or work guardrail is presented as product authority;
83
+ - a baseline is used as a pass/fail threshold without promotion;
84
+ - two live records define the same target;
85
+ - a deferred outcome has no accepted `O-###`;
86
+ - a result lacks its exact profile version or digest;
87
+ - a comparison lacks a matching fingerprint or justified equivalence rule;
88
+ - an execution has no finite budget or stop rule;
89
+ - a waiver lacks an owner, approver, scope, or end point; or
90
+ - a rerun lacks a material change or separate requalification authority.
91
+
92
+ Do not fill these gaps with guessed values.
93
+
94
+ ## Keep Proof Modes And State Separate
95
+
96
+ Performance evidence can support another review. It cannot replace automated tests, Guided Progress Review, Unassisted Goal Testing, Human Experience Review, accessibility review, installed-product proof, release validation, or support approval.
97
+
98
+ Repository records own product meaning. Project State or the Global Store can hold operational run state and evidence references. That state is a rebuildable aid. It is not product authority.
99
+
100
+ ## Use The Validation Twin
101
+
102
+ The [Performance Evidence Governance Contract](../contracts/performance-evidence-governance.md#validation-methods) owns both validation methods and the stable rule catalog.
103
+
104
+ Use the deterministic CLI method for repeatable structure and trace checks when the CLI is available. Use the agent method when the CLI is absent or when a catalog rule requires judgment. The agent must say whether the deterministic operation ran.
105
+
106
+ Keep the evidence paths distinct:
107
+
108
+ - `validator-passed` means the deterministic result passed.
109
+ - `agent-reviewed` means the canonical agent review is complete within its stated evidence and limits.
110
+ - `combined` means both separate records exist.
111
+
112
+ These states describe how validation evidence was supplied. They do not prove a performance outcome, certify the other method, authorize execution, close a finding or obligation, approve a waiver, or promote supported scope.
113
+
114
+ For an agent review, report the rule ID, evidence, observation, conclusion, limit, and next action. Keep missing, invalid, expired, non-comparable, adjacent-mode, and unsupported evidence visible. Route product choices to the owner or owning PRD.
@@ -0,0 +1,209 @@
1
+ # Planning Workflow
2
+
3
+ See `.make-docs/system/references/wave-model.md` for W/R semantics and resolution rules.
4
+
5
+ ## Purpose
6
+
7
+ Use this workflow to produce a reviewable plan before generating or maintaining PRD documentation. Planning mode exists to lock the output structure, workstream boundaries, and validation approach before the repo is mutated.
8
+
9
+ This workflow supports three planning modes:
10
+
11
+ 1. baseline PRD generation from a new idea or design
12
+ 2. decomposition of an existing codebase into a fresh PRD set
13
+ 3. authoritative PRD maintenance for changed, deprecated, removed, or genuinely new product requirements
14
+
15
+ ## Preflight
16
+
17
+ Inspect:
18
+
19
+ - the repo root and current documentation tree
20
+ - any `docs/assets/project/` inputs; if present, read them to hydrate the design and
21
+ plan
22
+ - any referenced design docs and whether they include `## Intended Follow-On`
23
+ - the impact and Human Experience Intent in each applicable source design, using the [Human Experience Contract](../contracts/human-experience-contract.md) and [Human Experience Reference](human-experience.md)
24
+ - any `Coordinate Handoff` or source-lineage notes in referenced designs
25
+ - any existing plans, PRD docs, and work backlogs
26
+ - any history records for prior phases that the request revises, reworks, corrects, standardizes, or finishes
27
+ - whether `docs/prd/` already contains active content (archives live under `.make-docs/archive/prds/YYYY-MM-DD/`)
28
+ - whether the user request is best classified as baseline generation, decomposition, or authoritative PRD maintenance
29
+
30
+ If a referenced design doc includes `## Intended Follow-On`, treat that route as authoritative unless the user explicitly overrides it.
31
+
32
+ Treat architecture notes, diagrams, meeting notes, transcripts, sketches,
33
+ requirements, and similar source material as artifacts.
34
+ Use `docs/assets/project/` as the optional input home; do not create or require an
35
+ architecture-specific seed directory name.
36
+
37
+ Resolve the W/R coordinate using `.make-docs/system/references/wave-model.md` before writing. Explicit user guidance and source lineage from designs, prior plans, prior work backlogs, and history records take precedence over the highest existing wave. If source lineage points to an earlier wave but later unrelated waves exist, keep the lineage wave and increment its revision.
38
+
39
+ If the request is ambiguous, infer the likely mode from the repo, prompt, and explicit design handoff. Ask the user only when the ambiguity materially changes the output shape.
40
+
41
+ ## Planning Goals
42
+
43
+ Produce a plan that makes the execution step decision-complete. The plan should settle:
44
+
45
+ - the execution mode
46
+ - the doc tree shape
47
+ - the fixed core docs plus adaptive product-authority docs
48
+ - whether execution requires an archive gate or an authoritative-maintenance path
49
+ - the delegation tier and workstream split
50
+ - the coordinator role and write scope
51
+ - the backlog placement under `docs/work/YYYY-MM-DD-w{W}-r{R}-<slug>/`
52
+ - the validation pass and any follow-up review
53
+ - for `direct` or `indirect` impact, a per-promise map to the owning PRD, affected human-facing surface or indirect effect, work phase, evidence source or selected testing type, and any accepted obligation
54
+ - for `none`, the preserved human boundary and the evidence that will prove it unchanged
55
+ - for each performance candidate, both the base maintenance action and performance applicability disposition
56
+ - for each executable performance candidate, one canonical `PERF-###` profile link plus a finite execution budget and stop-rule reference
57
+
58
+ For authoritative PRD maintenance, the plan should also settle:
59
+
60
+ - one `update-existing`, `create`, `link-only`, or `none` decision and reason for every candidate requirement
61
+ - the existing PRD owners and exact current sections to update
62
+ - the genuinely new capability, subsystem, or product-boundary PRDs to create, if any
63
+ - the standardized, non-normative requirement-history entries to add
64
+ - the affected links, risks, plans, work artifacts, and downstream source-authority relationships
65
+ - whether a scoped delta backlog is sufficient or the user explicitly wants a regenerated full backlog
66
+ - any deferred-obligation dispositions, material current human-experience uncertainties, proposed `NUAT-###` ownership for activated tests, and `not-needed-now` reasons needed before implementation
67
+
68
+ ## Human Experience Planning
69
+
70
+ Use the accepted Human Experience Intent as a cross-cutting planning input. Keep the full standard in the canonical contract and reference. Do not copy it into the plan.
71
+
72
+ For `direct` or `indirect` impact, map each accepted promise to:
73
+
74
+ - the current or planned PRD that owns the capability;
75
+ - the affected human-facing surface or indirect human effect;
76
+ - the phase that implements it;
77
+ - the evidence source or testing type selected by current testing authority; and
78
+ - an accepted `O-###` obligation only when authorized work remains owed after the current closeout.
79
+
80
+ For `none`, state the human boundary that must remain unchanged and the evidence that will prove the boundary. Do not invent a human flow for a change with no human effect.
81
+
82
+ The map preserves the human goal through planning. It does not replace product requirements, testing decisions, specialist reviews, or the obligation register.
83
+
84
+ ## User Preference Questions
85
+
86
+ Ask the user only when the answer affects the output shape or execution style. Typical planning questions include:
87
+
88
+ - whether a large subsystem should split into a numbered folder
89
+ - whether reference-style docs should stay separate from subsystem docs
90
+ - whether maintenance should stay a scoped delta or requires coordinated updates across several existing PRD owners
91
+ - whether an apparent new subject is coherent enough for its own product PRD or belongs in an existing owner
92
+ - whether the backlog directory should be scoped to a delta or regenerated as a full backlog
93
+ - whether the user explicitly wants to forbid delegation and force single-agent execution despite the default
94
+
95
+ Do not ask questions that can be answered by repo inspection. Do not ask the user which planning route to use when the referenced design docs already declare `## Intended Follow-On`, unless the user is explicitly reconsidering that route.
96
+
97
+ ## Plan Structure
98
+
99
+ Plans are always directories. The chosen template describes the shape of the `00-overview.md` entry point inside the plan directory, plus the referenced `0N-<phase>.md` files.
100
+
101
+ Start from the relevant template in `.make-docs/system/templates/`:
102
+
103
+ - `plan-prd.md` for baseline PRD generation from a new idea or design
104
+ - `plan-prd-decompose.md` for reverse-engineering an existing codebase into a fresh PRD set
105
+ - `plan-prd-change.md` for authoritative maintenance of an existing PRD namespace
106
+
107
+ Every plan should cover:
108
+
109
+ - coordinate decision, including whether the plan is a new wave or a revision and the evidence used
110
+ - repo summary
111
+ - output contract
112
+ - execution mode and PRD lifecycle handling
113
+ - coordinator policy and delegation tier
114
+ - planned document catalog
115
+ - intended follow-on, including route, next step, why, and coordinate handoff
116
+ - worker ownership, write scopes, and dependencies
117
+ - MCP strategy and fallback strategy
118
+ - validation and review steps
119
+ - the Human Experience promise map or preserved `none` boundary, with links to the source design and canonical authority
120
+ - the bounded performance-candidate inventory, with no copied product target or implicit execution authority
121
+
122
+ PRD authority-maintenance plans should additionally cover:
123
+
124
+ - existing PRDs to update
125
+ - genuinely new product PRDs, if any
126
+ - requirement-history entries
127
+ - affected links, risks, plans, and work artifacts
128
+ - delta backlog scope and downstream authority links
129
+ - obligation routing, current-uncertainty planning, and separate testing decisions when Unassisted Goal Testing is implicated
130
+ - canonical performance-profile ownership, execution-packet ownership, evidence reuse, expiry, and phase-gate consumption when Performance Testing is implicated
131
+
132
+ ## File Writing Rule
133
+
134
+ Planning mode should present the plan in chat first.
135
+
136
+ Plans are always directories. Write only after approval, using the matching path:
137
+
138
+ - baseline or decomposition plan: `docs/plans/YYYY-MM-DD-w{W}-r{R}-<slug>/` (with `00-overview.md` as the entry point and `0N-<phase>.md` files for each phase)
139
+ - PRD authority-maintenance plan: same directory pattern — `docs/plans/YYYY-MM-DD-w{W}-r{R}-<slug>/` — using a slug that identifies the maintenance scope (for example, `...-notification-delivery-maintenance`). Do not hard-code a `-change-plan` suffix.
140
+
141
+ ## Approval Prompt Rule
142
+
143
+ After presenting the plan, separate the two user decisions:
144
+
145
+ - whether to save the plan file
146
+ - whether to start execution now
147
+
148
+ Do not imply that approving the plan automatically authorizes execution. If the user approves the plan without explicitly choosing execution, default to saving the plan only and stop.
149
+
150
+ ## Workstream Rules
151
+
152
+ - Design workstreams to be delegation-ready first, not single-agent first.
153
+ - For context-heavy repos, prefer using the same delegation ladder during planning if the harness supports it: parallel agents, then subagents, then single-agent fallback.
154
+ - If delegation is available, the coordinator write scope is `none`.
155
+ - Assign every output-writing task to a worker, including shared docs such as `docs/prd/00-index.md`, `docs/prd/03-open-questions-and-risk-register.md`, `docs/prd/04-glossary.md`, and the backlog.
156
+ - Reserve a dedicated assembly worker for shared docs and a dedicated validation or fix worker for contract cleanup when the harness can support them.
157
+ - Describe workstreams, dependencies, and merge order.
158
+ - Do not hard-code Agent A, Agent B, or panel-specific assignments in the saved plan.
159
+ - Keep scopes disjoint so an execution harness can parallelize safely.
160
+ - The coordinator should never appear as the owner of document-writing tasks when delegation is available.
161
+
162
+ For authoritative PRD maintenance:
163
+
164
+ - keep existing-owner updates, genuinely new product PRDs, shared index/risk updates, and delta backlog generation as separate write scopes whenever practical
165
+ - route cross-doc status updates and backlink validation to assembly or validation workers rather than the coordinator
166
+
167
+ ## Flat Vs Nested Decision
168
+
169
+ Use a flat PRD tree when:
170
+
171
+ - the repo is small or medium
172
+ - the subsystem count is manageable
173
+ - one file per subsystem remains readable
174
+ - capability, subsystem, and reference authorities remain easy to navigate
175
+
176
+ Use a numbered subfolder when:
177
+
178
+ - a subsystem would become too large for one doc
179
+ - the repo has strong backend or frontend or service or domain boundaries
180
+ - a deep subsystem needs multiple docs but still needs one top-level number
181
+
182
+ ## Handoff To Execution
183
+
184
+ Before leaving planning mode, make the execution prerequisites explicit:
185
+
186
+ - approved plan exists
187
+ - the user has not necessarily approved execution yet
188
+ - MCP availability has been confirmed or fallback is accepted
189
+ - target output paths are fixed
190
+ - execution should use the delegation ladder by default: parallel agents, then subagents, then single-agent fallback
191
+ - if delegation is available, the coordinator write scope is `none`
192
+ - if the task is full-set replacement and `docs/prd/` already has active content, archival approval is required before execution can write the new PRD set
193
+ - if the task is authoritative PRD maintenance, the plan names existing owners, any genuinely new product PRDs, requirement-history entries, affected links/risks/plans/work, and delta backlog scope
194
+ - workstreams are disjoint
195
+ - validation is mandatory
196
+ - the plan keeps each accepted Human Experience promise or preserved boundary traceable to current PRD authority, work, evidence, and any accepted obligation
197
+
198
+ Every plan `00-overview.md` includes `## Intended Follow-On` recommending PRD
199
+ generation as the next step.
200
+ That handoff is advisory-default-but-overridable: it is authoritative unless the
201
+ user explicitly overrides it, and it is not a gate or precondition.
202
+ Include:
203
+
204
+ - `Route:` `prd-generation`
205
+ - `Next step:` generate or update the PRD set from the plan
206
+ - `Why:` why the plan should become the product or documentation contract before
207
+ backlog generation
208
+ - `Coordinate Handoff:` the W/R lineage the downstream PRD and work backlog
209
+ should carry, or the coordinate question that must be resolved before writing
@@ -0,0 +1,165 @@
1
+ # PRD Authority Maintenance
2
+
3
+ Archive layout is authoritative in `.make-docs/archive/AGENTS.md`.
4
+
5
+ ## Purpose
6
+
7
+ Use this reference when `docs/prd/` already contains the active product authority and a decision, design, implementation, or finding may affect that authority.
8
+
9
+ The governing 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
+ Implementation sequencing, migration actions, reconciliation work, and editorial language such as “revise X” belong in plans, work backlogs, and history records. They do not become standalone PRDs.
14
+
15
+ ## Maintenance Decisions
16
+
17
+ Assign one decision to every candidate requirement change:
18
+
19
+ | Decision | Use when |
20
+ | --- | --- |
21
+ | `update-existing` | An existing PRD subject owns the changed requirement. Update its current normative text surgically and non-destructively. |
22
+ | `create` | No existing PRD owns a coherent, wholesale new capability, subsystem, or product boundary. Create a product-authority PRD named for that subject. |
23
+ | `link-only` | Current authority is correct, but the index, related links, or another navigation surface needs a pointer. |
24
+ | `none` | Current authority already covers the decision and no PRD or link change is warranted. Record the rationale in the governing plan, coverage pass, or history record. |
25
+
26
+ Do not create PRDs whose subject is an editorial action. Active filenames, H1 titles, index kinds, and downstream authority links must describe product capabilities or boundaries, never additions, enhancements, revisions, removals, migrations, or reconciliation operations.
27
+
28
+ ## Ownership And Surgical Update Rules
29
+
30
+ - Read the active PRD index and candidate owner documents before writing.
31
+ - Update the existing PRD when its subject already owns the affected behavior, contract, scope, limitation, non-goal, or product boundary.
32
+ - Put the current normative requirement inline in the owning section. A reader must not need to follow a history link to discover what the product currently requires.
33
+ - Preserve unaffected text, anchors, links, terminology, and document identity.
34
+ - Do not renumber existing PRDs merely because authority changed.
35
+ - Create a new numbered PRD only when the product gains a coherent capability, subsystem, or boundary that has no suitable existing owner.
36
+ - If a candidate cuts across several owners, update each owning PRD rather than creating a cross-cutting editorial record.
37
+ - If the current PRDs already cover the decision, create no PRD and record `none` with its rationale outside the active PRD tree.
38
+ - Put each current observable Human Experience outcome in the PRD that owns the affected capability. Link to the [Human Experience Contract](../contracts/human-experience-contract.md) and use the [Human Experience Reference](human-experience.md) for examples. Do not create an editorial Human Experience PRD, copy the universal standard, or add Human Experience frontmatter.
39
+ - For each performance candidate, keep the base maintenance action separate from its performance applicability disposition. A hard product target and its canonical `PERF-###` profile belong only in the PRD that owns the protected outcome. Link to plan/work guardrails, characterization, experiments, obligations, results, and history without copying them into competing current authority.
40
+
41
+ ## Requirement History Contract
42
+
43
+ `## Requirement History` is an optional, non-normative section in a product-authority PRD. It preserves material prior iterations after the current requirement has been updated inline.
44
+
45
+ - Current normative requirements in the main body always win over requirement-history entries.
46
+ - Add history only for a material replacement, removal, or deprecation that future readers may need to understand.
47
+ - Do not duplicate an entire prior PRD or retain obsolete normative prose in the current requirement section.
48
+ - Place `## Requirement History` after the current normative sections and before `## Source Anchors` when the template uses source anchors.
49
+ - Use one dated `###` entry per coherent requirement change, newest last.
50
+ - Every entry records:
51
+ - `Date`
52
+ - `Coordinate` when one is known; otherwise state `Not assigned`
53
+ - `Affected requirement or section`
54
+ - `Previous contract`
55
+ - `Replacement contract`
56
+ - `Rationale`
57
+ - `Source`, using a resolving link to the governing design, plan, work, history, owner decision, or implementation evidence when available
58
+
59
+ Use this shape:
60
+
61
+ ```md
62
+ ## Requirement History
63
+
64
+ ### {{DATE}} — {{COORDINATE_OR_NOT_ASSIGNED}}
65
+
66
+ - Affected requirement or section: `{{SECTION_OR_REQUIREMENT}}`
67
+ - Previous contract: {{PREVIOUS_CONTRACT}}
68
+ - Replacement contract: {{REPLACEMENT_CONTRACT}}
69
+ - Rationale: {{RATIONALE}}
70
+ - Source: [{{SOURCE_LABEL}}]({{RELATIVE_SOURCE_PATH}})
71
+ ```
72
+
73
+ The source coordinate identifies the maintenance event; it is not the PRD document's identity. Product PRDs do not use W/R/P coordinates in filenames, titles, or document-level frontmatter.
74
+
75
+ ## Removals And Deprecations
76
+
77
+ - Express a removal or deprecation as the current scope, non-goal, limitation, status, or boundary in the owning PRD.
78
+ - Update current normative text first.
79
+ - Preserve the prior state in `## Requirement History` when it is materially useful.
80
+ - Update product-oriented index status or focus text only when it helps readers understand the current product shape.
81
+ - Do not leave a removed requirement active in the body and rely on a history entry, backlink, or separate removal document to override it.
82
+
83
+ ## Risk Register Update Rules
84
+
85
+ - Keep `docs/prd/03-open-questions-and-risk-register.md` as the canonical living register for gap state, open questions, resolved decisions, confirmed drift, and rebuild risks.
86
+ - Preserve the fixed sections `## Confirmed Drift`, `## Open Questions`, `## Rebuild Risks`, and `## Source Anchors`.
87
+ - Add or update one numbered `###` item per gap, question, drift, or risk.
88
+ - Use `D-001`, `D-002`, etc. under `## Confirmed Drift`; `Q-001`, `Q-002`, etc. under `## Open Questions`; and `R-001`, `R-002`, etc. under `## Rebuild Risks`.
89
+ - Assign the next available number within the section and never renumber existing items, even when they move to `Closed`.
90
+ - Each item starts with a table containing `Status`, `Decision`, and `Follow-Up`.
91
+ - Use only `Open`, `Confirming`, `Deferred`, or `Closed` for item status.
92
+ - Include `Question` or `Issue`, `Why it matters`, `Recommendation`, and `To close` for every item.
93
+ - Add `Resolution` only when the item is closed.
94
+ - If the item is already documented, update that existing item instead of duplicating it.
95
+ - Do not use `## Requirement History` as a substitute for unresolved risk or decision tracking.
96
+ - When deferred-obligation governance is active, maintain the canonical `## Deferred Obligations` section in this same register and preserve stable `O-###` identities rather than creating a second register.
97
+
98
+ ## Index And Status Rules
99
+
100
+ - Update `docs/prd/00-index.md` whenever an authoritative PRD is created, renamed, retired from the active set, or changes navigation relationships.
101
+ - The document map should show at least:
102
+ - document path
103
+ - product-oriented kind
104
+ - current status
105
+ - related authoritative docs
106
+ - current focus
107
+ - Use product-oriented kinds such as `core`, `capability`, `subsystem`, and `reference`. Never use editorial kinds such as `addition`, `enhancement`, `revision`, or `removal`.
108
+ - Status describes the current product authority, not the operation that changed it.
109
+ - Related links connect current authorities to one another. Do not link retired editorial change records as product authority.
110
+
111
+ ## Plans, Work, And History
112
+
113
+ Changes that activate, defer, narrow, cancel, or supersede user-observable acceptance outcomes must update the owning requirement, the linked `O-###` when future work remains owed, and the canonical `NUAT-###` scenario authority in the same change set. Plans and work route those records; they do not replace them.
114
+
115
+ - Plans may describe the editorial maintenance operation, including which PRDs to update, which new product authorities to create, and which history entries to add.
116
+ - Work backlogs may use change, revision, migration, reconciliation, or removal language when that language describes implementation work.
117
+ - History records preserve execution provenance and completed maintenance activity.
118
+ - Downstream work reads the updated authoritative PRDs for product requirements. It may read the governing plan for sequencing and the history record for provenance, but neither overrides the current PRD body.
119
+ - Plans and backlogs are always directories: `docs/plans/YYYY-MM-DD-w{W}-r{R}-<slug>/` and `docs/work/YYYY-MM-DD-w{W}-r{R}-<slug>/`.
120
+ - A scoped maintenance effort normally produces a dated delta backlog rather than rewriting an earlier backlog.
121
+ - Every delta backlog phase cites the updated or genuinely new authoritative PRDs that constrain implementation.
122
+ - For `direct` or `indirect` Human Experience impact, the plan and backlog map each accepted promise to its owning PRD, affected surface or effect, work phase, evidence source or selected testing type, and any accepted obligation. For `none` Human Experience impact, they name the preserved human boundary and its proof. These links carry the accepted outcome forward without making the plan or backlog a second product authority.
123
+
124
+ ## Validation Checklist
125
+
126
+ Before closing PRD authority maintenance, confirm:
127
+
128
+ 1. Every candidate has a `create`, `update-existing`, `link-only`, or `none` decision and a reason.
129
+ 2. Current normative requirements are inline in their owning PRDs.
130
+ 3. Every new PRD represents a coherent capability, subsystem, or product boundary rather than an editorial operation.
131
+ 4. Material prior contracts are preserved only in non-normative `## Requirement History` entries with the required fields.
132
+ 5. Removals and deprecations are expressed in current scope, non-goal, limitation, status, or boundary text before history is recorded.
133
+ 6. `docs/prd/00-index.md` uses product-oriented kinds and links only to current product authorities.
134
+ 7. Downstream work cites updated authoritative PRDs rather than retired change records.
135
+ 8. Newly discovered or resolved gaps, drift, questions, decisions, and risks are reflected in `docs/prd/03-open-questions-and-risk-register.md`.
136
+ 9. No existing PRD was renumbered or broadly rewritten without an ownership-based reason.
137
+ 10. Observable Human Experience outcomes are current requirements in their capability owners, with links to canonical authority and no copied standard, editorial experience PRD, or new frontmatter field.
138
+ 11. Plans and work preserve each accepted promise or `none` boundary through observable acceptance, evidence, and any accepted obligation.
139
+ 12. Every performance candidate has both decisions, and every executable candidate links exactly one canonical profile with its version, digest, target class, owner, supported scope, and lineage.
140
+ 13. No result, Store projection, plan/work profile, or adjacent proof mode changes a hard product target or promotes a support claim.
141
+
142
+ ## Deterministic Authority Validation
143
+
144
+ Run `make-docs run prd authority validate --target-root <project>` against the project root after PRD maintenance and before downstream work treats the set as authority. The read-only operation scans active `docs/prd/**/*.md` files plus live documentation links and source fields.
145
+
146
+ The validator uses two finite, case-insensitive sets. Filenames and H1 subjects prohibit only `revise`, `revision`, `add`, `addition`, `enhance`, `enhancement`, `remove`, `removal`, `deprecate`, `deprecation`, `reconcile`, and `reconciliation`. Product subjects such as Update Delivery, Replacement Policy, and Migration Safety therefore remain valid. Frontmatter and PRD-index editorial kinds prohibit those twelve terms plus `update`, `replace`, `replacement`, `migrate`, and `migration`.
147
+
148
+ | Code | Meaning |
149
+ | --- | --- |
150
+ | `PRD-AUTH-001` | An active filename begins with a number and prohibited editorial stem. |
151
+ | `PRD-AUTH-002` | The first H1 subject begins with a prohibited editorial stem after an optional PRD number is removed. |
152
+ | `PRD-AUTH-003` | Active frontmatter or an index `Kind`, `Document Kind`, or `Type` cell declares a prohibited editorial kind. |
153
+ | `PRD-AUTH-004` | An active PRD uses `Change Type`, `Capability Addition or Enhancement`, `Affected Baseline Docs`, `Baseline Being Revised or Removed`, or `Required Baseline Annotations`. |
154
+ | `PRD-AUTH-005` | A live Markdown link or authority-like frontmatter source field treats an action-prefixed PRD as current authority. |
155
+ | `PRD-AUTH-006` | An active product PRD declares top-level `coordinate` frontmatter as document identity. |
156
+ | `PRD-AUTH-007` | The requested target root is missing, unreadable, or not a directory. |
157
+ | `PRD-AUTH-008` | `docs/` or `docs/prd/` is unsafe, including a symlink or resolved path that escapes the target project. |
158
+
159
+ Markdown links are authority-bearing only within `Source PRD Docs`, `Source PRDs`, `Source PRD Documents`, `PRD Authority`, `Product Authority`, `Current PRD Authority`, `Authoritative PRDs`, `Authoritative PRD Docs`, `Source Authority`, `Authority Sources`, or `Active Authority Baseline`, plus the PRD index's `Document Map`. The provenance sections `Requirement History`, `Provenance`, `Lineage`, `Source Anchors`, `Design Provenance`, `Migration Provenance`, `Migration History`, `Historical Provenance`, and `Archive Provenance` are exempt from authority-link enforcement.
160
+
161
+ Outside the only canonical path exemption, `.make-docs/archive/**`, the validator also reads JSON, JSONL, YAML, and YML. After punctuation removal and lowercasing, authority fields are `source(s)`, `sourcePath(s)`, `sourcePrd(s)`, `sourcePrdPath(s)`, `sourcePrdDoc(s)`, `authority/authorities`, `authorityPath(s)`, `authorityPrd(s)`, `prd(s)`, `prdPath(s)`, and `prdDoc(s)`, including nested `path(s)` under source, authority, or PRD containers. Standardized provenance containers matching the provenance section vocabulary are exempt.
162
+
163
+ These provenance exemptions do not permit an active PRD filename, H1, kind, retired heading, or document-level coordinate to violate current-authority rules. The validator resolves the target root and documentation scan roots before reading; an absent or invalid root fails with `PRD-AUTH-007`, while an escaping or otherwise unsafe `docs/` or `docs/prd/` root fails closed with `PRD-AUTH-008`.
164
+
165
+ Interactive TTY output is a human summary followed by every diagnostic and remediation. `--json` output, and non-TTY output, emit the complete structured report. A report with `status: failed` exits nonzero after printing the full result; `status: passed` exits zero.
@@ -4,7 +4,7 @@
4
4
 
5
5
  This file is the single source of truth for the Wave/Revision/Phase (W/R/P) encoding used across `make-docs` v2.
6
6
 
7
- Every other reference file, template, and router links here instead of restating these rules. The encoding was piloted in `docs/assets/references/history-record-contract.md` and is extended to designs, plans, and work in v2. PRDs are exempt; see `## PRD Exemption`.
7
+ Every other reference file, template, and router links here instead of restating these rules. The encoding was piloted in `.make-docs/system/contracts/history-record-contract.md` and is extended to designs, plans, and work in v2. PRDs are exempt; see `## PRD Exemption`.
8
8
 
9
9
  ## Terms
10
10
 
@@ -25,7 +25,7 @@ Every other reference file, template, and router links here instead of restating
25
25
  | Work directory | `docs/work/YYYY-MM-DD-w{W}-r{R}-<slug>/` |
26
26
  | Work index file | `docs/work/YYYY-MM-DD-w{W}-r{R}-<slug>/00-index.md` |
27
27
  | Work phase file | `docs/work/YYYY-MM-DD-w{W}-r{R}-<slug>/0N-<phase>.md` |
28
- | History record | `docs/assets/history/YYYY-MM-DD-w{W}-r{R}-p{P}-<slug>.md` when W/R/P is known; see `docs/assets/references/history-record-contract.md` for fallbacks. |
28
+ | Breadcrumb record | `.make-docs/archive/history/YYYY-MM-DD-w{W}-r{R}-p{P}-<slug>.md` when W/R/P is known; see `.make-docs/system/contracts/history-record-contract.md` for fallbacks. |
29
29
 
30
30
  `YYYY-MM-DD` is the date the artifact is written. Never backdate.
31
31
 
@@ -45,16 +45,18 @@ When writing a new plan directory or work directory, determine `W` and `R` in th
45
45
 
46
46
  Do not assign a new wave solely because newer unrelated waves exist. The highest-wave scan is a fallback for genuinely new initiatives, not evidence that a revision to older work belongs to a newer wave.
47
47
 
48
- For history records, store any known W/R/P/S/T position in the `coordinate` frontmatter field described by `docs/assets/references/history-record-contract.md`. Include W/R/P in the filename when all three are known. Include W/R when only those two are known. Keep stage and task detail only in `coordinate`.
48
+ For breadcrumb records, store any known W/R/P/S/T position in the `coordinate` frontmatter field described by `.make-docs/system/contracts/history-record-contract.md`. Include W/R/P in the filename when all three are known. Include W/R when only those two are known. Keep stage and task detail only in `coordinate`.
49
49
 
50
50
  For work backlog tasks, number task IDs ordinally across the entire phase file, not within each stage. Start the first task at `t1`, continue through later `### Tasks` sections without resetting, and do not renumber existing task IDs when inserting or completing work. Use unordered markdown task syntax (`- [ ] t1: ...` or `- [x] t1: ...`) so checkbox rendering stays reliable.
51
51
 
52
52
  ## PRD Exemption
53
53
 
54
- PRDs are intentionally exempt from W/R/P. The PRD namespace evolves in place through active-set evolution and change docs rather than iterating in waves.
54
+ PRDs are intentionally exempt from W/R/P. The PRD namespace is maintained in place as the current product authority rather than iterating in waves.
55
55
 
56
- - PRD docs keep the fixed `NN-<slug>.md` convention described in `docs/assets/references/output-contract.md`.
57
- - Change management for PRDs is governed by `docs/assets/references/prd-change-management.md`.
56
+ - PRD docs keep the fixed `NN-<slug>.md` convention described in `.make-docs/system/contracts/output-contract.md`.
57
+ - PRD filenames, H1 titles, kinds, and document-level frontmatter describe product subjects, not maintenance operations or revision coordinates.
58
+ - W/R/P coordinates may appear in a PRD's source links or non-normative `## Requirement History` entries to identify the maintenance event; they are not PRD document identity.
59
+ - Authoritative maintenance for PRDs is governed by `.make-docs/system/references/prd-change-management.md`.
58
60
  - Archived PRD sets are grouped by date, not by wave (see `## Archive Integration`).
59
61
 
60
62
  ## Design Exemption
@@ -63,13 +65,13 @@ Designs are exempt from W/R encoding. Design filenames use the simplified patter
63
65
 
64
66
  The date provides chronological ordering; the slug provides topical identity. No wave or revision identifier is required.
65
67
 
66
- When a design is revised or superseded, write a new dated design and use `## Design Lineage` (defined in `docs/assets/references/design-contract.md`) to link back to prior designs. Do not use `r{R}` revision numbering on designs.
68
+ When a design is revised or superseded, write a new dated design and use `## Design Lineage` (defined in `.make-docs/system/contracts/design-contract.md`) to link back to prior designs. Do not use `r{R}` revision numbering on designs.
67
69
 
68
70
  Designs are inputs to a wave cycle (design → plan → work), not products of one. Binding a design to a wave number implies a 1:1 relationship with a downstream plan/work cycle that often does not hold.
69
71
 
70
72
  ## Archive Integration
71
73
 
72
- Archive rules for designs, plans, work, and PRDs live in `docs/assets/archive/AGENTS.md`. W/R/P naming is preserved when an artifact is archived; it is not rewritten.
74
+ Archive rules for designs, plans, work, and PRDs live in `.make-docs/archive/AGENTS.md`. W/R/P naming is preserved when an artifact is archived; it is not rewritten.
73
75
 
74
76
  ## Forward Compatibility
75
77
 
@@ -0,0 +1,12 @@
1
+ <!-- make-docs:begin -->
2
+ # Templates Router
3
+
4
+ This always-local directory routes template system resources. A template is a reusable output shape. Template bodies are optional local projections.
5
+
6
+ - Use a valid local template body first. If it is absent, read `make-docs://system/template/<posix-relative-path>` with `make-docs resource read`.
7
+ - Copy the relevant template shape into the target output file. Do not write outputs here.
8
+ - Use the design, guide, plan, PRD, work, history, or Unassisted Goal Testing template that matches the target artifact.
9
+ - Resolve workflow questions through references and policy questions through contracts, then continue in the target output directory router.
10
+ - Do not modify a template body unless the user asks.
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
+ # Templates Router
3
+
4
+ This always-local directory routes template system resources. A template is a reusable output shape. Template bodies are optional local projections.
5
+
6
+ - Use a valid local template body first. If it is absent, read `make-docs://system/template/<posix-relative-path>` with `make-docs resource read`.
7
+ - Copy the relevant template shape into the target output file. Do not write outputs here.
8
+ - Use the design, guide, plan, PRD, work, history, or Unassisted Goal Testing template that matches the target artifact.
9
+ - Resolve workflow questions through references and policy questions through contracts, then continue in the target output directory router.
10
+ - Do not modify a template body unless the user asks.
11
+ - Do not infer optional Skills, plugins, Playbooks, Protocols, or unavailable policy from this router.
12
+ <!-- make-docs:end -->