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