@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,128 @@
1
+ # Deferred Obligation Contract
2
+
3
+ ## Purpose
4
+
5
+ Use this contract for accepted future product outcomes that cannot be completed in the current scope but must remain durable, visible, and routed.
6
+
7
+ Deferred obligations are product authority, not implementation scratch notes. They preserve required future work without turning every idea, risk, or rejected option into a tracked obligation.
8
+
9
+ ## Canonical Register
10
+
11
+ The canonical register lives in `docs/prd/03-open-questions-and-risk-register.md` under a fixed `## Deferred Obligations` section.
12
+
13
+ Every record uses a stable heading of the form `### O-001 <title>`. IDs are append-only, never renumbered, never reused, and remain valid when owner, coordinate, status, or links change.
14
+
15
+ ## When To Create An Obligation
16
+
17
+ Create an `O-###` record only when accepted authority establishes a required future outcome that must survive the current scope.
18
+
19
+ Do not create an obligation for:
20
+
21
+ - optional ideas;
22
+ - rejected alternatives;
23
+ - unresolved questions that do not yet establish owed work;
24
+ - ordinary implementation notes;
25
+ - future automation possibilities that remain explicitly optional.
26
+
27
+ ## Required Record Fields
28
+
29
+ Every obligation record includes:
30
+
31
+ | Field | Requirement |
32
+ | --- | --- |
33
+ | `ID` | Stable `O-###` identity matching the heading |
34
+ | `Title` | Short product-language title |
35
+ | `Status` | `Active`, `Deferred`, `Fulfilled`, `Cancelled`, or `Superseded` |
36
+ | `Summary` | Concise statement of the owed future outcome |
37
+ | `Source authority` | PRD, design, plan, work, or finding links that establish or materially change the obligation |
38
+ | `Owner` | Durable owner authority responsible for future completion or disposition |
39
+ | `Target coordinate` | Concrete future coordinate or explicit owner-routed target |
40
+ | `Future trigger` | Concrete condition that activates the obligation when it is not immediately runnable |
41
+ | `Dependencies` | Blocking authorities, work, platforms, or approvals |
42
+ | `Acceptance exit criteria` | Evidence required to treat the obligation as fulfilled |
43
+ | `Related requirements and findings` | Owning requirements plus any linked finding or scenario refs |
44
+ | `History / disposition note` | Concise reason when status becomes terminal or materially rerouted |
45
+
46
+ ## Status Semantics
47
+
48
+ | Status | Meaning |
49
+ | --- | --- |
50
+ | `Active` | Required future work is accepted and currently actionable or awaiting immediate routing |
51
+ | `Deferred` | Required future work is accepted but awaits its stated trigger, dependency, or owner-ready coordinate |
52
+ | `Fulfilled` | Exit criteria were met and the authority chain now records completion |
53
+ | `Cancelled` | Product authority explicitly removed the requirement and recorded why it is no longer owed |
54
+ | `Superseded` | A newer obligation replaced this one; the replacement `O-###` must be linked |
55
+
56
+ Terminal statuses require a concise rationale. `Superseded` must link the replacement record. `Cancelled` must cite the authority that removed the requirement.
57
+
58
+ ## Authority Chain And Backlinks
59
+
60
+ Obligations link bidirectionally while active:
61
+
62
+ - the obligation links every source that establishes or materially changes it;
63
+ - active PRDs, plans, work phases, scenarios, findings, and history entries link back to the `O-###` when they consume it.
64
+
65
+ Do not create a second obligation register in plans, work, scenarios, or history. Those surfaces route the canonical record; they do not replace it.
66
+
67
+ ## Orphan Audit
68
+
69
+ Phase closeout includes a non-persona orphan audit. The audit checks whether accepted future outcomes, deferred findings, or scope-narrowing claims are fully routed. An Unassisted Goal Testing result of `not-needed-now` creates no obligation by itself.
70
+
71
+ An orphan audit does not replace:
72
+
73
+ - guide or system-resource coverage;
74
+ - PRD reconciliation;
75
+ - validation;
76
+ - Unassisted Goal Testing;
77
+ - accessibility or other manual testing.
78
+
79
+ A phase with an unresolved orphan does not claim capability completion.
80
+
81
+ ## Completion Language
82
+
83
+ Use exact status language:
84
+
85
+ - `Phase complete` means the current phase finished its approved scope.
86
+ - `Capability complete` means no accepted required outcome for that capability remains active, deferred, blocked by missing routing, or otherwise owed.
87
+
88
+ A phase may be complete while capability status remains partial. Do not collapse those states.
89
+
90
+ ## Repository And Operational State Boundary
91
+
92
+ Repository-canonical:
93
+
94
+ - obligation identity and meaning;
95
+ - owner, trigger, target, dependencies, and exit criteria;
96
+ - links to requirements, findings, scenarios, work, and history.
97
+
98
+ Project work records or optional operational capture:
99
+
100
+ - audit progress;
101
+ - sign-off progress;
102
+ - local validation evidence;
103
+ - raw notes that do not change authority meaning.
104
+
105
+ Project audit notes, work status, and local validation evidence remain valid project knowledge. Any Make Docs operational capture belongs in the global Make Docs Store through the CLI. Do not treat local notes as installation, migration, or recovery authority.
106
+
107
+ If the CLI is unavailable or optional capture fails, continue project work and report unavailable capture. Do not claim success, write directly to the Store, queue a later write, or create local fallback state. Required Store recording for CLI-managed changes remains mandatory.
108
+
109
+ The documentation-first round does not require a new runtime schema, store table, or CLI operation.
110
+
111
+ ## Compatibility And Migration
112
+
113
+ Adopt obligations conservatively:
114
+
115
+ - preserve existing `D-###`, `Q-###`, and `R-###` identities;
116
+ - create `O-###` prospectively when accepted authority proves future work is owed;
117
+ - do not rewrite archives;
118
+ - stop for review when active content is modified or ambiguous.
119
+
120
+ A deferred question or risk becomes an obligation only when accepted authority establishes a required future outcome.
121
+
122
+ ## Non-Goals
123
+
124
+ - No automatic conversion of every deferred item into `O-###`.
125
+ - No second canonical register.
126
+ - No runtime automation requirement.
127
+ - No database or Global Store schema requirement.
128
+ - No hidden completion claims without explicit authority maintenance.
@@ -16,7 +16,7 @@ User-authored design docs may not fully conform. Apply this contract to newly ge
16
16
 
17
17
  Archive designs only when the user explicitly asks. Never archive proactively.
18
18
 
19
- Defer to `docs/assets/archive/AGENTS.md` for archive structure and procedure.
19
+ Defer to `.make-docs/archive/AGENTS.md` for archive structure and procedure.
20
20
 
21
21
  ## Required Headings
22
22
 
@@ -24,11 +24,16 @@ Generated design docs must include:
24
24
 
25
25
  - `## Purpose`
26
26
  - `## Context`
27
+ - `## Human Experience Intent`
27
28
  - `## Decision`
28
29
  - `## Alternatives Considered`
29
30
  - `## Consequences`
30
31
  - `## Intended Follow-On`
31
32
 
33
+ ## Human Experience Intent
34
+
35
+ Use the [Human Experience Contract](human-experience-contract.md) for one conditional intent section after Context and before Decision. It owns impact, field order, evidence, and prospective adoption. Use the [Human Experience Reference](../references/human-experience.md) for examples. Keep the section in the body. Apply it to new generated designs and substantial agent-authored updates; preserve older designs and minor edits under the contract.
36
+
32
37
  ## Intended Follow-On Contract
33
38
 
34
39
  The `## Intended Follow-On` section must include:
@@ -58,5 +63,5 @@ When present, include:
58
63
  ## Link Rules
59
64
 
60
65
  - Use relative Markdown links between design docs and related plans, PRD docs, or work items.
61
- - Apply `docs/assets/references/path-and-link-hygiene.md` for repo-relative path rules, sanitized placeholders, and full-path exceptions.
66
+ - Apply `.make-docs/system/references/path-and-link-hygiene.md` for repo-relative path rules, sanitized placeholders, and full-path exceptions.
62
67
  - If a design is intended to feed planning, the `Next Prompt` link in `## Intended Follow-On` must resolve.
@@ -2,19 +2,19 @@
2
2
 
3
3
  ## Purpose
4
4
 
5
- Use this contract for developer and user guides under `docs/guides/developer/` and `docs/guides/user/`.
5
+ Use this contract for audience guides under `docs/assets/<persona-slug>/`. Built-in `maintainer` and `user` guides use `docs/assets/maintainer/` and `docs/assets/user/`. Merge valid project config with both defaults; custom audiences retain their own paths and declared primitive. Either primitive can be human or agent. Use `guide-maintainer.md` for the `maintainer` primitive and `guide-user.md` for the `user` primitive. Set `persona` to the selected effective slug, including a custom slug when selected.
6
6
 
7
- This contract does NOT apply to history records, which use `docs/assets/references/history-record-contract.md`.
7
+ This contract does NOT apply to breadcrumb records, which use `.make-docs/system/contracts/history-record-contract.md`.
8
8
 
9
9
  Guides are living documentation for the current usable or maintainable product surface. They should not read like phase logs, release notes, or implementation summaries. Use phase, plan, PRD, design, and history docs as evidence, then write the guide around what a reader needs to do next.
10
10
 
11
11
  ## Audience Contract
12
12
 
13
- ### Developer Guides
13
+ ### Maintainer Guides
14
14
 
15
- Developer guides live in `docs/guides/developer/`. Write them for contributors, maintainers, integrators, and operators who need to understand, extend, validate, troubleshoot, or safely change the project.
15
+ Maintainer guides live in `docs/assets/<persona-slug>/` for the selected `maintainer`-primitive Persona; the built-in path is `docs/assets/maintainer/`. Write them for contributors, maintainers, integrators, and operators who need to understand, extend, validate, troubleshoot, or safely change the project.
16
16
 
17
- A developer guide should help a capable developer quickly reach a first useful PR or maintenance action. Prefer:
17
+ A maintainer guide should help a capable maintainer quickly reach a first useful PR or maintenance action. Prefer:
18
18
 
19
19
  - codebase and documentation navigation
20
20
  - local setup, validation, release, or operational procedures
@@ -22,11 +22,11 @@ A developer guide should help a capable developer quickly reach a first useful P
22
22
  - maintainer workflows, troubleshooting, and safe-change notes
23
23
  - links to deeper designs, PRDs, work backlogs, and reference contracts
24
24
 
25
- Avoid writing developer guides as implementation diaries. Historical context belongs only where it helps the reader make a current decision.
25
+ Avoid writing maintainer guides as implementation diaries. Historical context belongs only where it helps the reader make a current decision.
26
26
 
27
27
  ### User Guides
28
28
 
29
- User guides live in `docs/guides/user/`. Write them for people who use what the project ships, including novices who need orientation and advanced users who want to explore deeper workflows.
29
+ User guides live in `docs/assets/<persona-slug>/` for the selected `user`-primitive Persona; the built-in path is `docs/assets/user/`. Write them for people or agents who use what the project ships, including novices who need orientation and advanced users who want to explore deeper workflows.
30
30
 
31
31
  A user guide should help the reader understand the product from a user's perspective and complete real tasks. Prefer:
32
32
 
@@ -44,6 +44,8 @@ Every guide must begin with a YAML frontmatter block. Required fields:
44
44
  | Field | Type | Description |
45
45
  | --- | --- | --- |
46
46
  | `title` | string | Display title of the guide. |
47
+ | `kind` | string | `guide`. |
48
+ | `persona` | string | Effective Persona slug matching the audience directory. |
47
49
  | `path` | string | Virtual grouping and publication path. Lowercase, forward-slash separated, no leading or trailing slash. 1-3 segments. Examples: `cli/development`, `getting-started`, `template/customization`. |
48
50
  | `status` | enum | One of `draft`, `published`, `deprecated`. |
49
51
 
@@ -63,20 +65,20 @@ Do not add frontmatter fields for deferred guide work. Use `## Future Coverage`
63
65
 
64
66
  Before creating a guide, inspect existing guides for overlap. Prefer updating or linking an existing guide when that produces a clearer documentation set than adding a new file.
65
67
 
66
- Resolve each documentation-worthy capability to one of these outcomes:
68
+ Resolve each documentation-worthy capability to one verdict. Select the effective Persona target separately, as required by the coverage-pass contract.
67
69
 
68
- | Outcome | Use when |
70
+ | Verdict | Use when |
69
71
  | --- | --- |
70
- | `developer` | The durable knowledge is maintainer-facing, contributor-facing, operational, validation-related, or extension-related. |
71
- | `user` | The durable knowledge helps people use the shipped product, understand a concept, or complete a task. |
72
- | `both` | The capability has distinct user and developer needs that should not be collapsed into one audience. |
73
- | `update-existing` | A current guide already owns the topic and should be expanded instead of creating a new guide. |
74
- | `link-only` | The capability is covered well enough by a related guide, reference, design, PRD, or existing navigation surface. |
72
+ | `create` | Durable knowledge needs a new guide for the selected audience. |
73
+ | `update-existing` | A current guide already owns the topic and should be expanded. |
74
+ | `link-only` | A related guide, reference, design, PRD, or navigation surface already covers the need. |
75
75
  | `none` | The capability is obsolete, too internal, too narrow, or only useful as a history entry. |
76
76
 
77
+ Use a `maintainer`-primitive target for building, maintaining, operating, validating, or extending the project. Use a `user`-primitive target for using the shipped product. Custom Personas retain their selected slug. Either role can be human or agent. When distinct audiences need coverage, record each target explicitly; `both` is not a Persona slug or verdict.
78
+
77
79
  When both audiences are relevant, avoid duplicating the same guide in both directories. Put the detailed guide in the primary audience directory and use `related` frontmatter plus concise companion coverage when the secondary audience needs a different entry point.
78
80
 
79
- After creating or updating guide content, re-check overlapping developer and user guides. Add reciprocal links, `related` frontmatter, or concise supplemental context when the new guide work helps an existing guide become easier to discover, navigate, or apply.
81
+ After creating or updating guide content, re-check overlapping maintainer and user guides. Add reciprocal links, `related` frontmatter, or concise supplemental context when the new guide work helps an existing guide become easier to discover, navigate, or apply.
80
82
 
81
83
  When no guide is needed during closeout or generation, record the no-guide decision in the history entry or planning artifact with the reason.
82
84
 
@@ -144,16 +146,16 @@ The `path` field serves dual purposes:
144
146
 
145
147
  New guides always start as `draft`. An agent must never set `status: published` on a newly created guide. Only the user or an explicit user request promotes a guide to `published`.
146
148
 
147
- Transitions: `draft` to `published` to `deprecated`. A `deprecated` guide may return to `draft` for substantial rewrites. Archival, moving to `docs/assets/archive/guides/`, follows existing archive rules and happens only when the user explicitly asks.
149
+ Transitions: `draft` to `published` to `deprecated`. A `deprecated` guide may return to `draft` for substantial rewrites. Archival, moving to `.make-docs/archive/guides/`, follows existing archive rules and happens only when the user explicitly asks.
148
150
 
149
151
  ## Scope
150
152
 
151
- - Applies to `docs/guides/developer/` and `docs/guides/user/` only.
152
- - Does NOT apply to history records, which use `docs/assets/references/history-record-contract.md`.
153
+ - Applies to guides under every effective `docs/assets/<persona-slug>/` audience, including configured custom Personas. Shared `docs/assets/project/` material is not Persona-scoped.
154
+ - Does NOT apply to breadcrumb records, which use `.make-docs/system/contracts/history-record-contract.md`.
153
155
 
154
156
  ## Link Rules
155
157
 
156
158
  - Use relative Markdown links between guides and related designs, plans, PRDs, work backlogs, history records, or reference files.
157
- - Apply `docs/assets/references/path-and-link-hygiene.md` for repo-relative path rules, sanitized placeholders, and full-path exceptions.
159
+ - Apply `.make-docs/system/references/path-and-link-hygiene.md` for repo-relative path rules, sanitized placeholders, and full-path exceptions.
158
160
  - Every internal link must resolve.
159
161
  - Use `related` frontmatter for companion guides and high-value source artifacts.
@@ -2,15 +2,15 @@
2
2
 
3
3
  ## Purpose
4
4
 
5
- Use this contract for session history records under `docs/assets/history/`.
5
+ Use this contract for session breadcrumb records under `.make-docs/archive/history/`.
6
6
 
7
7
  History records are **breadcrumbs**: concise, point-in-time references for a future auditor. A reader should be able to skim one and know what was touched and why, then follow links to deeper detail. They are not verbose narratives and not live logs.
8
8
 
9
9
  ## Required Path
10
10
 
11
- - When wave, revision, and phase are known: `docs/assets/history/YYYY-MM-DD-w{W}-r{R}-p{P}-<slug>.md`
12
- - When only wave and revision are known: `docs/assets/history/YYYY-MM-DD-w{W}-r{R}-<slug>.md`
13
- - When no coordinate is known: `docs/assets/history/YYYY-MM-DD-<slug>.md`
11
+ - When wave, revision, and phase are known: `.make-docs/archive/history/YYYY-MM-DD-w{W}-r{R}-p{P}-<slug>.md`
12
+ - When only wave and revision are known: `.make-docs/archive/history/YYYY-MM-DD-w{W}-r{R}-<slug>.md`
13
+ - When no coordinate is known: `.make-docs/archive/history/YYYY-MM-DD-<slug>.md`
14
14
 
15
15
  Use today's date in `YYYY-MM-DD`. Never backdate.
16
16
 
@@ -54,7 +54,7 @@ Encode known wave/revision/phase position in the filename for phase-scoped histo
54
54
 
55
55
  ## Coordinate Rules
56
56
 
57
- See `docs/assets/references/wave-model.md` for W/R/P semantics and general resolution rules. The rules below are specific to history records and extend (do not replace) the general model.
57
+ See `.make-docs/system/references/wave-model.md` for W/R/P semantics and general resolution rules. The rules below are specific to breadcrumb records and extend (do not replace) the general model.
58
58
 
59
59
  Coordinates use one combined abbreviation that captures as much positioning as is known for the session:
60
60
 
@@ -78,19 +78,25 @@ Each history record must include, in order:
78
78
  - `## Changes` — free-form prose, markdown tables, and/or file trees summarizing what was touched. May use sub-headings.
79
79
  - `## Documentation` — contains all required sub-sections below.
80
80
  - `### Project`
81
- - `### Developer`
81
+ - `### Maintainer`
82
82
  - `### User`
83
83
 
84
+ New records use `Maintainer`. Existing historical records with a `Developer` heading remain valid historical input; do not rewrite them merely to change the heading. Group custom Persona guides by their declared primitive and keep their actual paths.
85
+
84
86
  ## Documentation Tables
85
87
 
86
88
  All sub-sections under `## Documentation` are markdown tables with columns `Path` and `Description`.
87
89
 
88
90
  - `### Project` — project-level documentation created or updated in the session: READMEs, agent instructions (`AGENTS.md`/`CLAUDE.md`), designs, plans, work backlogs, and reference or template files.
89
- - `### Developer` — developer guides created or updated in the session.
91
+ - `### Maintainer` — maintainer-primitive guides created or updated in the session.
90
92
  - `### User` — user guides created or updated in the session.
91
93
 
92
94
  If a sub-section has no entries, state `None this session.` in place of the table.
93
95
 
96
+ When deferred obligations or Unassisted Goal Testing changed materially, summarize the durable delta once in `## Changes`. Name the affected `O-###` or `NUAT-###` when one exists. Record `not-needed-now` without inventing either ID. Include the orphan-audit result when it matters and link the resulting scenario or finding disposition to authority. Do not duplicate raw run logs, transcripts, or evidence payloads in history.
97
+
98
+ History coverage remains one project record. When Unassisted Goal Testing changed materially, it links the selected-Persona testing records without copying their packets, findings, or evidence.
99
+
94
100
  Example:
95
101
 
96
102
  ```markdown
@@ -100,13 +106,13 @@ Example:
100
106
 
101
107
  | Path | Description |
102
108
  | --- | --- |
103
- | [docs/designs/2026-04-16-w2-r0-auth-redesign.md](../../designs/2026-04-16-w2-r0-auth-redesign.md) | New design for the auth module redesign. |
109
+ | [docs/designs/2026-04-16-w2-r0-auth-redesign.md](../../../docs/designs/2026-04-16-w2-r0-auth-redesign.md) | New design for the auth module redesign. |
104
110
 
105
- ### Developer
111
+ ### Maintainer
106
112
 
107
113
  | Path | Description |
108
114
  | --- | --- |
109
- | [docs/guides/developer/auth-module.md](../developer/auth-module.md) | New developer reference for the auth module. |
115
+ | [docs/assets/maintainer/auth-module.md](../../../docs/assets/maintainer/auth-module.md) | New maintainer reference for the auth module. |
110
116
 
111
117
  ### User
112
118
 
@@ -132,6 +138,6 @@ History records are written once at the end of the relevant span. Do not maintai
132
138
  ## Link Rules
133
139
 
134
140
  - Use relative Markdown links when referencing specific files, plans, designs, or work items that the session touched.
135
- - Apply `docs/assets/references/path-and-link-hygiene.md` for repo-relative path rules, sanitized placeholders, and full-path exceptions.
141
+ - Apply `.make-docs/system/references/path-and-link-hygiene.md` for repo-relative path rules, sanitized placeholders, and full-path exceptions.
136
142
  - Make sure every internal link resolves.
137
143
  - Link back to the active plan, design, or backlog phase that frames the session whenever one exists.
@@ -0,0 +1,134 @@
1
+ # Human Experience Contract
2
+
3
+ ## Purpose and Standard
4
+
5
+ This contract owns the Human Experience Standard and required design form. Use the [Human Experience Reference](../references/human-experience.md) for examples. Its stable identity is `make-docs://system/contract/human-experience-contract.md`.
6
+
7
+ > Every human-facing result must help a person complete a real goal without needless thought, effort, or doubt. The normal path must preserve context, reveal meaning and relationships, make state and next actions clear, and hide internal detail until it is useful. A person must not need to understand the system's internal model. Agents must shape a coherent experience, not merely expose correct capabilities. Work is not complete until proportionate evidence shows that the intended human remains oriented, capable, and in control.
8
+
9
+ Correctness, safety, completeness, and truthful presentation remain required. A clear human surface must not hide a failure, risk, limit, or material fact.
10
+
11
+ ## Impact
12
+
13
+ Classify the proposed change, not the fact that a person can read its design.
14
+
15
+ | Value | Meaning |
16
+ | --- | --- |
17
+ | `direct` | The change affects a surface a person perceives or uses. This includes commands, output, prompts, interfaces, documents, reports, configuration, APIs, SDKs, file trees, installation, review, recovery, and handoff. |
18
+ | `indirect` | Normal interaction stays the same, but performance, reliability, accuracy, freshness, safety, privacy, security, recovery, diagnostics, maintenance, accessibility support, resources, cost, or risk can affect a person. |
19
+ | `none` | The change has no direct or indirect human effect. Name the preserved experience and evidence that proves the boundary. |
20
+
21
+ Agent-facing or headless work is not automatically `none`. Consider the people who author, review, operate, maintain, recover, and rely on the result. Persona answers “for whom.” Intent answers “to what end and with what experience.” Use configured human Persona slugs, clear human roles, or both. Do not invent a Persona to fill the section. An agent acting in a Persona does not supply lived human experience evidence.
22
+
23
+ ## Design Form
24
+
25
+ An activated design must contain exactly one `## Human Experience Intent` after `## Context` and before `## Decision`. Keep the fields in the document body, in the order below. Do not add frontmatter keys. Do not rename the fields through configuration.
26
+
27
+ For `direct` or `indirect`, use this form. Choose one impact value.
28
+
29
+ ```markdown
30
+ ## Human Experience Intent
31
+
32
+ Impact: `direct`
33
+
34
+ Affected humans: {{HUMANS}}
35
+
36
+ Human goal or effect: {{GOAL_OR_EFFECT}}
37
+
38
+ Experience promises:
39
+
40
+ - {{OBSERVABLE_PROMISE}}
41
+
42
+ Complexity kept out of the human path:
43
+
44
+ - {{INTERNAL_DETAIL_NOT_REQUIRED_FOR_THE_GOAL}}
45
+
46
+ Evidence required:
47
+
48
+ - {{PLANNED_PROOF}}
49
+ ```
50
+
51
+ For `none`, replace the full form with this short form. Do not append another section.
52
+
53
+ ```markdown
54
+ ## Human Experience Intent
55
+
56
+ Impact: `none`
57
+
58
+ Reason: {{NO_DIRECT_OR_INDIRECT_EFFECT}}
59
+
60
+ Preserved experience: {{UNCHANGED_HUMAN_BOUNDARY}}
61
+
62
+ Evidence required:
63
+
64
+ - {{BOUNDARY_PROOF}}
65
+ ```
66
+
67
+ Fill each field with real content. Resolve placeholders. Describe future evidence as planned evidence; do not claim a test or review happened before it did. If accepted authority does not support a coherent human goal or path, stop for the missing product choice.
68
+
69
+ ## Principles
70
+
71
+ Apply the principles that matter to the goal:
72
+
73
+ - Put the human goal before the internal model.
74
+ - Preserve orientation and continuity. Show the subject, prior state, relationships, and current place.
75
+ - Distinguish success, partial success, waiting, failure, and blocked state. Name the next useful action.
76
+ - Show useful meaning first. Keep exact machine detail available through a discoverable secondary path.
77
+ - Use human names and explain needed special terms.
78
+ - Make ownership, parentage, sequence, membership, aliases, dependencies, and revisions clear where they matter.
79
+ - Give enough information for the current decision without flooding it or hiding a caveat.
80
+ - Make effects, confirmation limits, control, and recovery clear when needed.
81
+ - Use coherent navigation, file names, document structure, and command grammar.
82
+ - Support people who must perceive, understand, and operate the result. Use separate accessibility review when required.
83
+ - Aim for calm, confidence, and control. Beauty and elegance are not limited to decoration.
84
+
85
+ Human and machine surfaces may differ in form and density. They must preserve the same meaning and outcome. Exact identifiers, records, revisions, and receipts remain available for automation and audit. Context determines the useful default: interactive use may favor human presentation; pipes, exports, APIs, or explicit machine output may favor exact data.
86
+
87
+ ## User Action Requests
88
+
89
+ When a reply asks the user to act, make the request self-contained. State what the user must do, why it is needed, whether it is required or optional, what work it blocks, where supporting detail is available, and what should happen after the action. Explain internal terms and identifiers. A link can provide detail, but the user must not need to open it to understand the request.
90
+
91
+ ## Lifecycle Duties
92
+
93
+ Carry accepted intent through the current [lifecycle](../references/lifecycle.md). Do not add a lifecycle stage or copy the full section into each later artifact.
94
+
95
+ - Design records intent and planned evidence.
96
+ - Planning maps every promise to an owning PRD, affected surface or artifact, work phase, evidence source or selected testing type, and obligation route.
97
+ - PRD reconciliation makes observable human outcomes normative in the capability owner.
98
+ - Work traces tasks and acceptance criteria to each promise or preserved boundary. “UX is good” is not an acceptance criterion.
99
+ - Implementation and review inspect the real human surface for direct impact when it is available.
100
+ - Coverage applies Human Experience Review to every applicable promise. The agent prepares and records a concise review from the accepted promises, the real result, and suitable evidence. It records an observation, conclusion, limit, and next action for each promise.
101
+ - Acceptance keeps claims within that review. Completed direct human-facing work normally includes a short optional experience handoff with one to three normal-use steps, what to notice, and an invitation for feedback. A human response is required only when accepted authority explicitly defines a human acceptance gate.
102
+ - Release and completion claims stay within accepted evidence. Retrospective findings use the normal authority change process.
103
+
104
+ ## Evidence and Completion
105
+
106
+ Match evidence to the impact, risk, and promise. Direct work needs structural and functional proof plus review of the real surface when it exists. Indirect work needs technical or operational evidence tied to the human effect, with human review when that effect is perceivable or matters to a decision. None needs proof of the preserved boundary.
107
+
108
+ Human Experience Review is required agent review work, not a fifth testing type or a duplicate test verdict. The agent records the review and its evidence limits. A normal review does not require an owner response or approval. When proof is insufficient for a current claim, select the smallest added activity that can answer the current question under the current testing authority and [coverage contract](coverage-pass-contract.md). Direct impact alone does not activate every testing type. Follow the [Unassisted Goal Testing contract](naive-uat-contract.md) for its conditional selection, qualified human executor, public path, and anti-coaching rules. Private coaching does not prove discoverability.
109
+
110
+ An agent can draft intent, inspect the real result, compare evidence, and record the review. It can support an observable conclusion within the evidence. It cannot claim a person's lived ease, confidence, joy, or acceptance without evidence from that person. A complete section is necessary structure, not proof that the result is good for people.
111
+
112
+ The optional experience handoff is completion communication, not a testing type or gate. Silence, refusal, or no feedback does not block completion and does not create an obligation. Indirect work includes a handoff only when it gives the person useful information. `none` work does not invent one. If the activity is meant to answer a current decision, select the applicable testing type instead of hiding a test inside the handoff.
113
+
114
+ A human acceptance gate exists only when the user, an accepted design or PRD, release authority, or safety authority explicitly defines it. The gate must name its scope, human reviewer, surface, acceptance question, and gate effect. The agent prepares the review. The human can correct it, add feedback, acknowledge it, or accept it. The response blocks only the named scope. Without this authority, a missing human response is not missing evidence.
115
+
116
+ | Conclusion | Completion effect |
117
+ | --- | --- |
118
+ | `satisfied` | Supports only the exact reviewed promise or claim within the recorded evidence and limits. It does not claim a lived human reaction. |
119
+ | `material gap` | Blocks complete status for the affected promise or claim. Remediation and repeated proof, or an accepted bounded caveat or narrower claim, can resolve the current completion effect. Partial status may continue only when a valid obligation preserves an accepted owed outcome; the obligation does not resolve the gap. |
120
+ | `insufficient evidence` | Supports no unqualified human-outcome claim. Record the limit and select the smallest added testing activity only when the evidence can change a current decision or an explicit gate requires it. |
121
+
122
+ Do not make an unqualified human-outcome claim while required evidence is missing or an accepted material finding remains unresolved. Technical implementation can close with a bounded claim when the only missing evidence is optional lived-human feedback and no explicit human acceptance gate exists. A bounded caveat names the promise, evidence limit, risk, owner, and follow-on route. A phase can close with partial capability status when an accepted later outcome has a valid [deferred obligation](deferred-obligation-contract.md) with owner, trigger, target, dependencies, and exit criteria. Skipped advisory work, a declined or unanswered optional handoff, and `not-needed-now` do not create obligations. Later feedback becomes a finding; a material defect can reopen or narrow only the affected claim. This contract does not impose an automatic ban on each local commit, push, or draft phase close.
123
+
124
+ ## Adoption and Structural Validation
125
+
126
+ Apply the section to new agent-generated designs and substantial agent-authored design updates under this contract. Minor edits do not trigger unrelated rewrites. Existing and archived artifacts remain valid until applicable substantial work adopts the rule. Active work adopts it when a planned change affects its human path. Do not require a repository-wide backfill.
127
+
128
+ Authoring context selects required validation. Do not infer activation from file age, dates, names, diff size, or an agent-facing label. Without that context, a structural check may inspect an existing section but must not invalidate an older design merely because the section is absent. See the [design workflow](../references/design-workflow.md) for the internal validation call and its limits.
129
+
130
+ Structural checks verify one section, its position, one allowed impact value, stable conditional fields in order, nonempty content, and resolved placeholders. Headings and labels inside fenced examples do not count as live section structure. Diagnostics state the structural defect and repair. Meaning, intuition, beauty, usefulness, and joy require suitable review; do not build semantic judgments from keywords.
131
+
132
+ ## Delivery Boundary
133
+
134
+ Use the existing contract and reference resource types and optional projection model. Keep the reference at `make-docs://system/reference/human-experience.md`. Author upstream, then build and review package and local projection parity under the [System Resource Contract](system-resource-contract.md). Preserve project ownership and conflict rules. No mandatory Skill, new resource type, Persona schema, or Human Experience frontmatter is required.