@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,138 @@
|
|
|
1
|
+
# Human Experience Reference
|
|
2
|
+
|
|
3
|
+
## Start with the Human Goal
|
|
4
|
+
|
|
5
|
+
The [Human Experience Contract](../contracts/human-experience-contract.md) owns the rules and exact forms. This reference explains them. Read it by `make-docs://system/reference/human-experience.md` when no valid local copy exists.
|
|
6
|
+
|
|
7
|
+
Start with a concrete task. “An operator can identify a failed import and safely retry only the failed rows” gives a design direction. “Expose import state records” describes machinery but leaves the human task unclear.
|
|
8
|
+
|
|
9
|
+
Ask what changes for the people who use, read, operate, maintain, review, recover, or rely on the result. A Persona supplies the audience; the local intent supplies the goal. A clear role such as “on-call operator” is enough when no configured Persona fits.
|
|
10
|
+
|
|
11
|
+
## Use Clear Expectations to Support Action
|
|
12
|
+
|
|
13
|
+
> “When users don't know what to *expect*, they are less likely to *act*.”
|
|
14
|
+
|
|
15
|
+
Set an honest expectation about the result, current state, material limit, or next useful action. Do not turn an uncertain result into a promise. State the uncertainty and explain how it affects the person's choice.
|
|
16
|
+
|
|
17
|
+
## Shape Material Agent Replies
|
|
18
|
+
|
|
19
|
+
A material reply reports task state, presents a decision or recommendation, explains an error or limit, or closes work. Treat that reply as a human-facing result.
|
|
20
|
+
|
|
21
|
+
First identify what the user needs next. They may need orientation, a decision, an action, or exact supporting detail. Then shape the whole reply around that need:
|
|
22
|
+
|
|
23
|
+
- Lead with the result, meaning, or current state.
|
|
24
|
+
- Restore the minimum needed context when time, task length, or interruption may have broken continuity.
|
|
25
|
+
- Distinguish complete, partial, waiting, blocked, failed, and unverified work.
|
|
26
|
+
- Give a recommendation or next useful action when one exists. Say when no action is needed.
|
|
27
|
+
- Put technical proof after the human account. Keep exact paths, identifiers, commands, and evidence available when they help the user verify or continue the work.
|
|
28
|
+
- Keep material limits and uncertainty visible.
|
|
29
|
+
|
|
30
|
+
When the reply asks the user to act, check these questions:
|
|
31
|
+
|
|
32
|
+
- What does the user need to do?
|
|
33
|
+
- Why is the action needed now?
|
|
34
|
+
- Is it required, optional, or a separate authorization?
|
|
35
|
+
- What work waits for it?
|
|
36
|
+
- What should the user return or expect afterward?
|
|
37
|
+
|
|
38
|
+
Weak: "Please approve `commit-phase-gate`; see task `w4 r1 p2 t19`."
|
|
39
|
+
|
|
40
|
+
Useful: "Please authorize staging for the reviewed notification-recovery changes. Staging means placing only the reviewed changes into the proposed commit set. This separate permission is required before any file is staged, and it blocks only the proposed commit. The linked work record lists the exact files and checks. After you authorize staging, the agent will stage only that set and return the staged diff for a separate commit decision."
|
|
41
|
+
|
|
42
|
+
The useful request explains the internal staging term and the separate commit decision through normal words. The reply supplies the meaning and action. The linked work record supplies audit detail.
|
|
43
|
+
|
|
44
|
+
Do not force one layout, tone, length, or level of technical detail. Routine short acknowledgements can stay light. Do not add a separate experience summary or claim how the user feels.
|
|
45
|
+
|
|
46
|
+
## Examples and Counterexamples
|
|
47
|
+
|
|
48
|
+
These examples are interpretation aids, not extra policy or finished evidence.
|
|
49
|
+
|
|
50
|
+
| Change | Impact and useful promise | Weak result and proof that can reveal it |
|
|
51
|
+
| --- | --- | --- |
|
|
52
|
+
| Command output | `direct`: An operator can identify the project, result, and next safe action. Exact run IDs remain available in detail output. | A wall of IDs can be correct but leave the operator lost. Inspect the installed success, partial, and failure output; compare human and machine meaning. |
|
|
53
|
+
| Document or report | `direct`: A reader can find the decision, owner, source, and open limit without reading the full report. | A valid heading list can still bury the decision. Review the actual rendered document and follow its source links. |
|
|
54
|
+
| Public API or SDK | `direct`: An integrator can understand a failed call and recover without guessing state. | An unexplained error code exposes the model but not the action. Exercise the public error and retry path and inspect its documentation. |
|
|
55
|
+
| File tree | `direct`: A maintainer can tell which files are project content, generated copies, and source authority. | Three identical file names with no ownership clues invite edits to the wrong copy. Inspect the actual tree and instructions together. |
|
|
56
|
+
| Reliability repair | `indirect`: A queued task survives a restart without duplicate work. Normal controls stay the same. | “No UI change” misses the person's lost work. Use restart and duplicate-prevention evidence tied to that risk. |
|
|
57
|
+
| Recovery workflow | `direct`: An operator sees what will change, what remains safe, and where to resume. | A generic “done” after partial recovery hides state. Inspect interruption, partial result, and resume evidence. |
|
|
58
|
+
| Internal refactor | `none`: Existing output, operating steps, errors, timing bounds, and resource behavior remain within the same accepted boundary. | “Internal only” is not proof. Use focused compatibility evidence for the claimed unchanged boundaries. |
|
|
59
|
+
| Agent-only integration | Often `direct` or `indirect`: The maintainer can review decisions or recover the agent's actions. | Selecting `none` only because the first caller is an agent ignores the people who rely on it. Review the claimed effect; a structure check cannot decide it. |
|
|
60
|
+
|
|
61
|
+
## A Full Intent Example
|
|
62
|
+
|
|
63
|
+
For a command-result change, a completed design section can read:
|
|
64
|
+
|
|
65
|
+
```markdown
|
|
66
|
+
## Human Experience Intent
|
|
67
|
+
|
|
68
|
+
Impact: `direct`
|
|
69
|
+
|
|
70
|
+
Affected humans: Operators who retry failed imports.
|
|
71
|
+
|
|
72
|
+
Human goal or effect: Identify failed rows and retry them without repeating successful work.
|
|
73
|
+
|
|
74
|
+
Experience promises:
|
|
75
|
+
|
|
76
|
+
- Show the import name and distinct complete, partial, or failed state.
|
|
77
|
+
- Name the safe next action and retain the last useful context.
|
|
78
|
+
- Keep full row IDs available through the documented detail output.
|
|
79
|
+
|
|
80
|
+
Complexity kept out of the human path:
|
|
81
|
+
|
|
82
|
+
- Internal state keys and receipt layout are not needed to choose a retry.
|
|
83
|
+
|
|
84
|
+
Evidence required:
|
|
85
|
+
|
|
86
|
+
- Inspect installed output for complete, partial, and failed imports.
|
|
87
|
+
- Compare the visible counts and status with machine output.
|
|
88
|
+
- Exercise retry and confirm successful rows are preserved.
|
|
89
|
+
```
|
|
90
|
+
|
|
91
|
+
For indirect work, use the same fields with `Impact: indirect`. Tie each promise to a material human effect, such as avoiding lost work or reducing a known wait. Do not invent a new interface just to fill the form.
|
|
92
|
+
|
|
93
|
+
## A Short None Example
|
|
94
|
+
|
|
95
|
+
```markdown
|
|
96
|
+
## Human Experience Intent
|
|
97
|
+
|
|
98
|
+
Impact: `none`
|
|
99
|
+
|
|
100
|
+
Reason: This private helper split preserves behavior and its accepted operating bounds.
|
|
101
|
+
|
|
102
|
+
Preserved experience: Public output, errors, operating steps, and resource limits remain unchanged.
|
|
103
|
+
|
|
104
|
+
Evidence required:
|
|
105
|
+
|
|
106
|
+
- Compare public results and errors before and after the split.
|
|
107
|
+
- Check the same operating and resource limits with the focused regression cases.
|
|
108
|
+
```
|
|
109
|
+
|
|
110
|
+
A statement that a private helper has no effect is a claim to review. If the split changes latency, recovery, or maintenance effort, reconsider the impact. A complete short form does not settle that question.
|
|
111
|
+
|
|
112
|
+
## Missing Product Choice
|
|
113
|
+
|
|
114
|
+
Suppose a request says “simplify account recovery,” but current authority does not say who may restore access or which proof is needed. The author can identify the affected people and current failure. It cannot invent the recovery permission rule. Stop with that one product choice, its proposed result, and the effects of the real alternatives. Do not fill the intent with invented promises.
|
|
115
|
+
|
|
116
|
+
## Keep Human Judgment in the Lead
|
|
117
|
+
|
|
118
|
+
> “Data-driven design has its part, but it [shouldn't] lead the process. What matters *most* is being *personally involved*, testing everything *yourself*...And a huge part of that is paying attention to *how the product feels to you*, while always keeping its *core idea* in mind.”
|
|
119
|
+
|
|
120
|
+
Use data, automated checks, and agent analysis to find problems and support a conclusion. Do not let them replace direct review of the real result. The agent responsible for the work must inspect or use the available result, keep its core idea in view, and record direct observations and limits.
|
|
121
|
+
|
|
122
|
+
Human feedback adds evidence that an agent cannot create. One person's response is evidence from that person. It is not proof of every person's experience.
|
|
123
|
+
|
|
124
|
+
## Review the Actual Result
|
|
125
|
+
|
|
126
|
+
Use each accepted promise as a question about evidence. Can the reader identify the subject and its relationships? Does the result preserve context? Are waiting, partial, failure, and success distinct? Is the next action useful? Can a person recover and stay in control? Is exact detail discoverable when needed?
|
|
127
|
+
|
|
128
|
+
Use human names before internal IDs, but keep material facts visible. For example, a project name plus “3 rows failed; review the failed rows before retry” helps a decision. A short “success” message that hides those failures breaks meaning even if a JSON record remains exact elsewhere.
|
|
129
|
+
|
|
130
|
+
Reuse a suitable screenshot, document, command transcript, fixture, or functional result. The agent prepares and records a concise review from the accepted promises, the real result, and this evidence. For each promise, it records the observation, conclusion, limit, and next action.
|
|
131
|
+
|
|
132
|
+
For completed direct human-facing work, normally give the person one to three normal-use steps, state what is worth noticing, and invite optional feedback. Keep this experience handoff short. It is not a test, sign-off request, or close gate. Silence, refusal, or no feedback does not block completion or create an obligation. Use a handoff for indirect work only when it gives the person useful information. Do not invent one for `none`.
|
|
133
|
+
|
|
134
|
+
Require a human response only when the user, an accepted design or PRD, release authority, or safety authority explicitly defines a human acceptance gate. Name the 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 without writing a report or using a special phrase. Apply the response only to the named scope.
|
|
135
|
+
|
|
136
|
+
If evidence is insufficient, use current testing authority to select the smallest useful next activity only when it can change a current decision or an explicit gate requires it. Do not create a second run just to call it Human Experience Review.
|
|
137
|
+
|
|
138
|
+
An agent review can show that structure, wording, behavior, and evidence agree. It cannot claim a person's lived ease, confidence, joy, or acceptance without evidence from that person. Keep that limit visible in completion claims. Later feedback becomes a normal finding. A material defect can reopen or narrow the affected claim.
|
|
@@ -0,0 +1,153 @@
|
|
|
1
|
+
# Lifecycle Anchor
|
|
2
|
+
|
|
3
|
+
## Purpose
|
|
4
|
+
|
|
5
|
+
Use this anchor to orient documentation lifecycle work before choosing the next
|
|
6
|
+
workflow step.
|
|
7
|
+
It states the default arc and the expected departure behavior without turning
|
|
8
|
+
the arc into an absolute gate.
|
|
9
|
+
|
|
10
|
+
## Lifecycle Arc
|
|
11
|
+
|
|
12
|
+
The lifecycle is organized as bands.
|
|
13
|
+
|
|
14
|
+
### Optional Inputs
|
|
15
|
+
|
|
16
|
+
`docs/assets/project/` may hold source material, notes, screenshots, analysis, or
|
|
17
|
+
other inputs that inform later work.
|
|
18
|
+
It is an input surface, not a lifecycle stage.
|
|
19
|
+
If present, read it to hydrate the design and plan.
|
|
20
|
+
|
|
21
|
+
### Segment 1 - Plan
|
|
22
|
+
|
|
23
|
+
The planning segment usually moves in this order:
|
|
24
|
+
|
|
25
|
+
1. Design
|
|
26
|
+
2. Plan
|
|
27
|
+
3. PRD
|
|
28
|
+
4. Work backlog
|
|
29
|
+
|
|
30
|
+
This segment establishes the problem, implementation shape, product contract,
|
|
31
|
+
and executable work queue.
|
|
32
|
+
|
|
33
|
+
The PRD stage maintains one current product authority. `docs/prd/` describes the
|
|
34
|
+
current authoritative shape of the product and never the editorial operation
|
|
35
|
+
used to change that authority. Update an existing owning PRD surgically, create
|
|
36
|
+
a new PRD only for a coherent product subject with no owner, or record why no
|
|
37
|
+
PRD change is needed. Preserve material prior contracts in non-normative
|
|
38
|
+
requirement history; keep maintenance sequencing in plans, work, and history
|
|
39
|
+
records.
|
|
40
|
+
|
|
41
|
+
### Segment 2 - Build
|
|
42
|
+
|
|
43
|
+
The build segment loops per work phase:
|
|
44
|
+
|
|
45
|
+
1. Implement, including relevant automated tests.
|
|
46
|
+
2. Run the coverage-pass band.
|
|
47
|
+
3. Commit and pass the phase gate.
|
|
48
|
+
|
|
49
|
+
Use [coverage-pass-contract.md](../contracts/coverage-pass-contract.md) for the coverage-pass
|
|
50
|
+
band.
|
|
51
|
+
The band covers guide and system-resource coverage, history, PRD reconciliation,
|
|
52
|
+
documentation hygiene, validation, deferred-obligation consumption, and UAT or manual-test decisions.
|
|
53
|
+
|
|
54
|
+
### Segment 3 - Release And Beyond
|
|
55
|
+
|
|
56
|
+
The post-build segment usually moves in this order:
|
|
57
|
+
|
|
58
|
+
1. Release / publish
|
|
59
|
+
2. Archival
|
|
60
|
+
3. Retrospective
|
|
61
|
+
|
|
62
|
+
Release / publish means making work available to its audience.
|
|
63
|
+
Examples include deploying code, publishing docs, pushing to source control, or
|
|
64
|
+
handing off a report.
|
|
65
|
+
|
|
66
|
+
## Cross-Cutting Lenses
|
|
67
|
+
|
|
68
|
+
The coverage-pass band is a repeatable lens used during build closeout.
|
|
69
|
+
The Persona lens separates maintainer-facing coverage, user-facing coverage, and
|
|
70
|
+
project/history coverage so one audience does not quietly substitute for another.
|
|
71
|
+
Testing types keep separate decisions. Each activated Unassisted Goal Test selects one eligible configured Persona for audience framing and evidence routing. Persona selection does not prove executor qualification.
|
|
72
|
+
|
|
73
|
+
### Human Experience
|
|
74
|
+
|
|
75
|
+
Human Experience is a cross-cutting lens. It is not a new lifecycle stage. Use the [Human Experience Contract](../contracts/human-experience-contract.md) as authority and the [Human Experience Reference](human-experience.md) for explanation and examples. Link to that authority from local artifacts. Do not copy the standard into each plan, PRD, backlog, prompt, or router.
|
|
76
|
+
|
|
77
|
+
| Lifecycle point | Local action |
|
|
78
|
+
| --- | --- |
|
|
79
|
+
| Design | Record the impact and Human Experience Intent before product and architecture decisions. |
|
|
80
|
+
| Plan | For `direct` or `indirect` impact, map each accepted promise to its owning PRD, affected human-facing surface or indirect effect, work phase, evidence source or selected testing type, and any accepted obligation. For `none`, name the preserved human boundary and how it will be proved unchanged. |
|
|
81
|
+
| PRD | Put each current observable human outcome in the PRD that owns the capability. Link to the canonical contract instead of creating an editorial Human Experience PRD. |
|
|
82
|
+
| Work backlog | Trace tasks and observable acceptance to the owning requirement and promise, or to the preserved boundary for `none`. Keep phase order, evidence decisions, and the implementation gate visible. |
|
|
83
|
+
| Implementation | Preserve the intended human path and the required technical result. Keep useful meaning, state, next action, and recovery clear on the affected surface. |
|
|
84
|
+
| Review | Inspect the actual human-facing surface for `direct` impact when it exists. Tie `indirect` evidence to the stated human effect. The agent prepares and records a concise review with per-promise observations, conclusions, limits, and next actions. |
|
|
85
|
+
| Coverage | Apply Human Experience Review as an agent-owned lens over suitable evidence for each applicable promise. Reuse evidence that answers the promise. Human Experience Review is not a separate testing type. |
|
|
86
|
+
| Acceptance | Keep claims within the agent review. For completed direct human-facing work, normally give a short optional experience handoff. A missing human response does not block closure or create an obligation unless accepted authority explicitly defines a human acceptance gate. Keep a material gap open or route later owed work through an accepted obligation. |
|
|
87
|
+
| Release / publish | Keep claims within the accepted evidence and the human paths that were reviewed. Preserve an accepted obligation when later work remains owed. |
|
|
88
|
+
| Retrospective | Route a repeatable lesson through the normal change process to the contract, reference, or PRD that owns it. Do not turn one local preference into universal policy. |
|
|
89
|
+
|
|
90
|
+
This lens does not replace architecture, accessibility, visual design, security, privacy, safety, performance, Persona, or testing authority. Use those owners when their specialized decision is required. Direct impact does not activate Unassisted Goal Testing by itself.
|
|
91
|
+
|
|
92
|
+
### Performance Evidence
|
|
93
|
+
|
|
94
|
+
Performance Evidence is a cross-cutting decision and evidence path. It is not mandatory for every change. Use the [Performance Evidence Governance Contract](../contracts/performance-evidence-governance.md) as the only detailed policy source and the [Performance Evidence Reference](performance-evidence.md) for explanation. Keep the two candidate decisions separate: the base maintenance action and the performance applicability disposition.
|
|
95
|
+
|
|
96
|
+
| Lifecycle point | Local action |
|
|
97
|
+
| --- | --- |
|
|
98
|
+
| Design | Inventory current candidates, protected outcomes, and decisions without inventing targets. |
|
|
99
|
+
| Plan | Select each target class and canonical owner. Give every executable candidate one `PERF-###` profile and a finite evidence budget. |
|
|
100
|
+
| PRD | Keep hard product targets only in the owning PRD. Link to bounded non-product profiles without copying their targets. |
|
|
101
|
+
| Work backlog | Link the canonical profile and render a finite execution packet with build, environment, workload, measurement, correctness, budget, fingerprint, reuse, stop, and evidence fields. |
|
|
102
|
+
| Implementation | Validate correctness and the measurement seam first. Execute only an authorized packet. Reuse unchanged evidence and rerun only affected checks within the remaining budget. |
|
|
103
|
+
| Coverage | Record both candidate decisions. Keep Performance Testing separate from the other testing types and review lenses. |
|
|
104
|
+
| Closeout | Consume result validity, findings, waivers, obligations, expiry, comparability, budget, reuse, requalification, gate effect, and supported scope. Missing, expired, invalid, non-comparable, adjacent-mode, or unrun required evidence does not pass. |
|
|
105
|
+
| Release / publish | Do not turn a performance result or waiver into installed-product proof, release readiness, public support, or wider scope. |
|
|
106
|
+
|
|
107
|
+
Repository records own qualification, profile meaning, target authority, supported scope, findings, waivers, obligations, and history. Optional Project State or Global Store data is a rebuildable operational aid. It proves recording only and cannot authorize a run, renew a budget, or change an outcome.
|
|
108
|
+
|
|
109
|
+
At the first qualifying lifecycle event after adoption, inventory current performance claims and assets without retroactive failure or inferred certification. Route an ambiguous or modified managed resource through the compatibility conflict stop in the [PRD Change Management Guide](prd-change-management.md) and its owning authority.
|
|
110
|
+
|
|
111
|
+
## Default Ordering
|
|
112
|
+
|
|
113
|
+
Implementation normally derives from a work backlog.
|
|
114
|
+
The work backlog normally derives from a PRD.
|
|
115
|
+
The PRD normally derives from a plan, but the plan's maintenance actions do not
|
|
116
|
+
become standalone PRDs; downstream work reads the resulting current PRD
|
|
117
|
+
authority.
|
|
118
|
+
The plan normally derives from a design or another explicit source input.
|
|
119
|
+
|
|
120
|
+
When the current request is ambiguous, prefer the next step implied by that
|
|
121
|
+
chain.
|
|
122
|
+
If a work backlog already exists, treat it as the implementation authority for
|
|
123
|
+
phase work unless the user directs a different source of truth.
|
|
124
|
+
|
|
125
|
+
## Straddle Rule
|
|
126
|
+
|
|
127
|
+
Default to the lifecycle arc, but do not treat it as an absolute skip ban.
|
|
128
|
+
Skip, reorder, or revisit stages when the user directs it or when the situation
|
|
129
|
+
warrants it.
|
|
130
|
+
When departing from the default arc, say so explicitly and record the reason in
|
|
131
|
+
the relevant plan, work, history, or closeout artifact.
|
|
132
|
+
|
|
133
|
+
The failure mode to avoid is silent departure.
|
|
134
|
+
|
|
135
|
+
## Optional State Capture
|
|
136
|
+
|
|
137
|
+
Ordinary project work does not depend on Make Docs state capture. If the CLI is not installed, cannot run, or reports `run-capture-unavailable` for optional lifecycle capture, continue the project work and report that capture was unavailable. Do not claim capture succeeded, write directly to the Store, queue a later write, or create project-local fallback state. Project documents, history breadcrumbs, and optional work backlog updates remain valid project knowledge. They must not act as installation or recovery records.
|
|
138
|
+
|
|
139
|
+
CLI-managed installs, upgrades, migrations, and other managed changes must save their required records in the global Make Docs Store. If required recording fails, the CLI must stop before further project writes and preserve recovery evidence. Optional capture failure never waives this requirement. Use `make-docs project state status` to inspect installation state and follow its safe next action.
|
|
140
|
+
|
|
141
|
+
## Router Use
|
|
142
|
+
|
|
143
|
+
Routers should point here for lifecycle orientation instead of restating this
|
|
144
|
+
policy.
|
|
145
|
+
Read this anchor when selecting the next stage, deciding whether an existing
|
|
146
|
+
artifact is sufficient, or noticing that a request skips, reorders, or revisits a
|
|
147
|
+
stage.
|
|
148
|
+
|
|
149
|
+
## Non-Goals
|
|
150
|
+
|
|
151
|
+
This anchor does not replace the phase backlog, PRD, plan, or stage-specific
|
|
152
|
+
contracts.
|
|
153
|
+
It does not require creating every artifact for every request.
|
|
@@ -0,0 +1,65 @@
|
|
|
1
|
+
# Unassisted Goal Testing Typed Validation
|
|
2
|
+
|
|
3
|
+
## Scope
|
|
4
|
+
|
|
5
|
+
Use the workflow in `make-docs://system/reference/naive-uat-workflow.md` first. These read-only helpers check record structure, current file digests, and links. They do not certify executor qualification, human judgment, acceptance, or a support claim. An output with `valid: true` means only that the submitted record passed these checks. `qualification_verified` and `independently_verified` are false. A recorded human conclusion remains the assessor's conclusion.
|
|
6
|
+
|
|
7
|
+
## CLI And MCP
|
|
8
|
+
|
|
9
|
+
The stable paths are:
|
|
10
|
+
|
|
11
|
+
- `make-docs run uat persona resolve`
|
|
12
|
+
- `make-docs run uat scenario validate`
|
|
13
|
+
- `make-docs run uat target validate`
|
|
14
|
+
- `make-docs run uat evidence-reference validate`
|
|
15
|
+
- `make-docs run uat finding validate`
|
|
16
|
+
- `make-docs run uat result validate`
|
|
17
|
+
|
|
18
|
+
Each accepts `--payload-json <file-or-inline-JSON>` and `--json`. The payload is the same object as the derived MCP tool input. The Persona helper also accepts `--target-root <project>` and `--persona <configured-slug>`. Other helpers use the payload. All payloads can include `targetRoot` and `persona`. Omit `persona` to use canonical `user`. The MCP names replace punctuation in each stable operation ID with underscores and add `make_docs_`.
|
|
19
|
+
|
|
20
|
+
## Reference Fields
|
|
21
|
+
|
|
22
|
+
A file reference has `path` and `sha256`. Use a current SHA-256 digest of the complete file. Paths use project-relative forward slashes. Evidence and artifact references stay under `docs/assets/<selected-slug>/testing/`. Source scenario and current gate authority references name files under `docs/prd/`. Links, traversal, missing files, changed digests, and Persona frontmatter drift fail closed. No helper moves or rewrites an artifact.
|
|
23
|
+
|
|
24
|
+
Large external capture can remain external. Retain its consent, retention, redaction, and capture reference in a Persona-scoped metadata file. Pass that file's reference to the helper. The helper does not fetch or certify external capture.
|
|
25
|
+
|
|
26
|
+
## Payloads
|
|
27
|
+
|
|
28
|
+
| Operation | Required payload fields |
|
|
29
|
+
| --- | --- |
|
|
30
|
+
| Persona | No required fields; optional `artifact` file reference checks applicable Persona frontmatter |
|
|
31
|
+
| Scenario | `source` file reference and `scenario` typed record |
|
|
32
|
+
| Target | `target` record |
|
|
33
|
+
| Evidence reference | `evidence` file reference |
|
|
34
|
+
| Finding | `record` file reference and `finding` record |
|
|
35
|
+
| Result | `record` file reference, `decision`, and `result`; activated results also require `run` |
|
|
36
|
+
|
|
37
|
+
The decision body uses `testing_type`, `decision_informed`, `reason_now`, `product_maturity`, `scope`, `executor`, `gate_effect`, `effort_budget`, `stop_condition`, `evidence_retained`, and `rerun_trigger`. This is body data, not required frontmatter. `gate_effect` defaults to `advisory`.
|
|
38
|
+
|
|
39
|
+
The scenario uses the fields in the governing scenario template. Typed names are `selected_persona`, `scenario_id`, `scenario_version`, `title`, `user_goal`, `source_requirements`, `target_user`, `current_uncertainty`, `supported_scope`, `build_identity`, `environment`, `starting_state`, `public_resources`, `prohibited_context`, `tester_prompt`, `operator_success_outcomes`, `setup`, `teardown`, `evidence_requirements`, `severity_rules`, `finding_route`, and `decision`. List fields use arrays. Version is a positive integer.
|
|
40
|
+
|
|
41
|
+
`tester_packet` contains only `situation`, `goal`, `starting_state`, `public_resources`, `safety_limits`, `consent_notice`, and `tester_teardown`. `packet_review` records `reviewer`, an `evidence` file reference, and the recorded `no_hidden_guidance: true` judgment. The helper checks structural separation and direct leaks. It cannot judge all forms of coaching.
|
|
42
|
+
|
|
43
|
+
A target has `build_identity`, `environment`, `supported_scope`, `target_user`, `normally_consumable_form`, `audience_consumption_evidence`, `qualification`, `consent`, `capture`, and `readiness`.
|
|
44
|
+
|
|
45
|
+
Qualification records `executor`, `kind` (`human` or `agent`), `separate_context`, `assessed_by`, `assessment`, and `isolation_evidence` file references. The recorded access judgments are `no_private_knowledge`, `no_repository_access`, `no_private_memory`, `no_implementation_conversation`, `no_coaching`, and `public_information_only`. Each must be true before an activated target qualifies for record validation. The assessor must differ from the executor. Supporting evidence must exist and match its digest. These checks do not replace an assessor's inspection of the actual access limits.
|
|
46
|
+
|
|
47
|
+
A finding has `finding_id`, `run_id`, `scenario_id`, `scenario_version`, `observed_behavior`, `expected_human_outcome`, `severity`, `reproducibility`, `supported_scope`, `source_requirement`, `owner`, `disposition`, `disposition_authority`, and `evidence`. Severity uses the contract's four values. The last two evidence fields use file references. The disposition authority body must contain a JSON record with the exact `finding_id`, `owner`, and `disposition`. An isolation note or another unrelated record cannot prove a disposition. Owning requirement and work links do not become evidence destinations.
|
|
48
|
+
|
|
49
|
+
A run has `run_id`, `scenario_ref` (file reference plus `scenario_id` and `scenario_version`), `selected_persona`, `persona_primitive`, `persona_resolution`, `work_coordinate`, `product_build`, `environment`, `support_scope`, `target_user`, `qualification`, `public_resources_used`, `interventions`, `observations`, `reproduction`, `evidence_refs`, `findings`, `cleanup_state`, `review`, and `validity`. Each intervention records `description`, `material_coaching`, and `assessed_by`. Validity records `private_knowledge`, `broken_setup`, `lost_evidence`, and `assessed_by`. A material validity failure cannot be recorded as a valid conclusion.
|
|
50
|
+
|
|
51
|
+
## Canonical Bodies And Existing Markdown
|
|
52
|
+
|
|
53
|
+
The canonical scenario stays in its owning active PRD. The helper accepts its existing Markdown field table and tester-packet bullets. Pass a typed transcription as `scenario`; the helper compares it with that source. Use the current table field names. List cells use semicolon-separated values. The combined Product Build And Environment cell must equal the complete supplied build identity, a semicolon and space, and the complete supplied environment. Substrings do not prove source equality. Separate Build Identity and Environment rows remain supported. The testing decision table precedes the scenario. The Current Uncertainty row supplies the bounded question.
|
|
54
|
+
|
|
55
|
+
A PRD can instead contain the typed scenario as a JSON body record. This is optional. It does not create another canonical location. For a Markdown scenario, a result payload includes the same typed transcription as `run.scenario`, which is checked against the source again. Existing historical records remain readable. These helpers do not require a bulk conversion or relabel an earlier walkthrough.
|
|
56
|
+
|
|
57
|
+
Finding and result helpers compare submitted typed records with a JSON body record in the referenced Persona artifact. A JSON fenced block or a JSON file is supported. The result body contains `decision`, `result`, and any `run`, `gate_authority`, or `future_obligation`; it excludes transport roots and the artifact's own file reference. This optional typed helper format does not replace manual workflow records.
|
|
58
|
+
|
|
59
|
+
## Results And Gates
|
|
60
|
+
|
|
61
|
+
The result is preserved. The helper never upgrades evidence to `clear`, closes findings, or rewrites a result after a waiver, obligation, timebox, or later run. A `clear` result with findings returns `valid: false` and `validation_status: unverified`; it retains the recorded result and all finding/disposition references for review. Free-text disposition labels do not prove accepted closure. The helper adds no status vocabulary and does not infer resolution from text such as open, unresolved, closed, or accepted risk. `not-needed-now` has no run and uses executor `none`. For an activated run, the decision executor must equal the recorded qualification executor, and the decision scope must equal the run support scope.
|
|
62
|
+
|
|
63
|
+
Blocking requires `gate_authority`: a current PRD file reference plus `result`, `outcome`, and `gate_effect`. The authority body records those exact three fields. Its outcome must match `decision_informed`; its result and effect must match the submitted result and decision. A matching typed record is evidence of the recorded authority, not proof of owner acceptance by the helper.
|
|
64
|
+
|
|
65
|
+
Only an accepted future outcome uses `future_obligation`: `id` (`O-###`), `owner`, `trigger`, `target`, `exit_criteria`, `reason`, and `accepted_authority` reference. The cited acceptance body must contain the exact obligation `id`, `owner`, `trigger`, `target`, `exit_criteria`, and `reason` as a JSON body record. A matching file digest alone does not prove this link. No helper creates an obligation or a Store row. Use the existing lifecycle operations for lifecycle state and bounded evidence receipts. Repository records remain authoritative.
|
|
@@ -0,0 +1,64 @@
|
|
|
1
|
+
# Unassisted Goal Testing Workflow
|
|
2
|
+
|
|
3
|
+
## Purpose
|
|
4
|
+
|
|
5
|
+
Use this reference to decide, prepare, run, and record one Unassisted Goal Test. The stable resource filename and `naive-uat` workflow ID remain for compatibility.
|
|
6
|
+
|
|
7
|
+
The [Unassisted Goal Testing Contract](../contracts/naive-uat-contract.md) owns the reusable rules. This reference gives the order of work. It does not create a second policy source.
|
|
8
|
+
|
|
9
|
+
## Resource Composition
|
|
10
|
+
|
|
11
|
+
| Role | Stable URI | Use |
|
|
12
|
+
| --- | --- | --- |
|
|
13
|
+
| Governing contract | `make-docs://system/contract/naive-uat-contract.md` | Activation, qualification, anti-coaching, scenario, evidence, finding, result, and gate rules |
|
|
14
|
+
| Facilitator prompt | `make-docs://system/prompt/naive-uat-facilitator.prompt.md` | Decide activation and supervise one valid run |
|
|
15
|
+
| Tester prompt | `make-docs://system/prompt/naive-uat-tester.prompt.md` | Start a qualified executor with only the approved tester packet |
|
|
16
|
+
| Workflow reference | `make-docs://system/reference/naive-uat-workflow.md` | Order the resource composition |
|
|
17
|
+
| Scenario template | `make-docs://system/template/naive-uat-scenario.md` | Record a testing decision and author an activated canonical scenario |
|
|
18
|
+
|
|
19
|
+
The installed provider supplies these resources by default. A project can select a trustworthy local projection. The workflow does not require one.
|
|
20
|
+
|
|
21
|
+
## Workflow
|
|
22
|
+
|
|
23
|
+
1. Record the common testing decision fields from PRD 50.
|
|
24
|
+
2. Decide whether an unassisted attempt can answer a material current human-experience uncertainty, or whether explicit current authority requires it.
|
|
25
|
+
3. When no current decision justifies a run, record `not-needed-now`, its reason, the evidence that already answers the uncertainty, the advisory gate effect, the effort budget, the stop condition, and the rerun trigger. Do not create a scenario or obligation only for this result.
|
|
26
|
+
4. When testing activates, select the canonical `NUAT-###` scenario in the PRD that owns the public outcome. Create or update that record before the run when current authority requires it.
|
|
27
|
+
5. Resolve exactly one configured Persona. Accept only a `user`- or `maintainer`-primitive Persona. Use canonical `user` when none is supplied.
|
|
28
|
+
6. Qualify the executor separately from Persona selection. A human or an agent can execute. An agent must use a separate isolated context with no repository access, private memory, implementation conversation, known-defect knowledge, hidden answer, or successful-path knowledge.
|
|
29
|
+
7. Render the operator view and tester packet from the same scenario version. Confirm that no operator-only field entered the tester packet.
|
|
30
|
+
8. Prepare the normally consumable product, realistic environment, consent, capture, and safety boundary without rehearsing the goal.
|
|
31
|
+
9. Give the executor only the tester prompt, tester packet, product access, and allowed public resources.
|
|
32
|
+
10. Record interventions, observations, one result, findings, and approved evidence under `docs/assets/<persona-slug>/testing/`. Bind them to the exact scenario version or content digest.
|
|
33
|
+
11. Apply teardown, redaction, retention, cleanup, and restoration rules.
|
|
34
|
+
12. Route `clear`, `friction`, `blocked`, or `invalid-run` through the owning PRD, finding, work, and gate authority. A Store receipt records only the requested Store mutation.
|
|
35
|
+
|
|
36
|
+
## Access Paths
|
|
37
|
+
|
|
38
|
+
Direct CLI, native MCP resources, MCP tools where needed, and an explicitly selected thin Skill must resolve the same resource URIs and typed operations.
|
|
39
|
+
|
|
40
|
+
A Skill can adapt arguments or format receipts. It must not copy activation, qualification, Persona, scenario, anti-coaching, evidence, finding, result, or gate policy.
|
|
41
|
+
|
|
42
|
+
## Gate Effects
|
|
43
|
+
|
|
44
|
+
The default effect is advisory. Use `blocking-current-work` or `blocking-claim-only` only when explicit current authority names the result and the blocked outcome or claim.
|
|
45
|
+
|
|
46
|
+
`friction` does not automatically fail a phase. `blocked` and `invalid-run` prove no human conclusion. `not-needed-now` is not a failed or deferred test.
|
|
47
|
+
|
|
48
|
+
## Stop Conditions
|
|
49
|
+
|
|
50
|
+
Stop the run when:
|
|
51
|
+
|
|
52
|
+
- executor qualification or isolation is not proved;
|
|
53
|
+
- the selected Persona is missing, unknown, or ineligible;
|
|
54
|
+
- the product form or public resources do not match the scenario;
|
|
55
|
+
- operator-only content entered the tester packet;
|
|
56
|
+
- safety, privacy, consent, access, account, or environment conditions prevent a valid attempt;
|
|
57
|
+
- the scenario version or evidence destination is unclear; or
|
|
58
|
+
- the accepted effort budget ends.
|
|
59
|
+
|
|
60
|
+
Record `blocked` when the product or environment prevents a valid attempt. Record `invalid-run` when setup, coaching, private knowledge, or lost evidence prevents a conclusion.
|
|
61
|
+
|
|
62
|
+
## Typed Helper Access
|
|
63
|
+
|
|
64
|
+
For input fields and read-only CLI/MCP validation, read `make-docs://system/reference/naive-uat-validation.md`. The helpers check records and references. They do not make qualification or human-experience judgments.
|
|
@@ -0,0 +1,101 @@
|
|
|
1
|
+
# Path and Link Hygiene
|
|
2
|
+
|
|
3
|
+
## Purpose
|
|
4
|
+
|
|
5
|
+
Use this reference when writing, reviewing, or repairing project documentation that mentions repository files, generated documentation links, local runtime paths, or diagnostic paths.
|
|
6
|
+
|
|
7
|
+
Documentation should be portable across checkouts, machines, and users. Do not write local checkout paths into project documentation when a project-relative path communicates the same information.
|
|
8
|
+
|
|
9
|
+
## Project Path Rules
|
|
10
|
+
|
|
11
|
+
- Use project-relative paths for files inside the repository.
|
|
12
|
+
- Prefer paths such as `README.md`, `./README.md`, `docs/prd/00-index.md`, or `src/main.rs`.
|
|
13
|
+
- Use relative Markdown links between project documents.
|
|
14
|
+
- Do not include real checkout paths such as `/Users/<name>/projects/repo/README.md`, `/home/<name>/projects/repo/README.md`, `C:\Users\<name>\projects\repo\README.md`, or `/mnt/c/Users/<name>/projects/repo/README.md`.
|
|
15
|
+
- Do not include machine-local temporary paths such as `/private/var/folders/<id>/...` or `/var/folders/<id>/...` unless they are necessary diagnostic evidence and are sanitized.
|
|
16
|
+
|
|
17
|
+
## Namespace Hygiene
|
|
18
|
+
|
|
19
|
+
- Use `docs/assets/project/**` for optional, non-authoritative source and analysis inputs.
|
|
20
|
+
- Use `.make-docs/archive/**` for Make Docs-managed archive and provenance records.
|
|
21
|
+
- Use `docs/assets/<persona-slug>/**` for Persona-scoped reader assets. Use `docs/assets/<persona-slug>/testing/**` for Unassisted Goal Testing packets, runs, findings, and approved evidence.
|
|
22
|
+
- Treat `docs/assets/archive/**`, `docs/assets/artifacts/**`, `docs/artifacts/**`, `docs/assets/library/**`, and `docs/assets/playbooks/**` as legacy migration inputs, not current shipped targets.
|
|
23
|
+
- Current selected local resource projections live under `.make-docs/system/<resource-type>/**`. Installed-provider resources remain available without a local projection.
|
|
24
|
+
- Routers, scripts, selected agentic payloads, declarative config, and backup or conflict file copies are not content-resource types.
|
|
25
|
+
- Make Docs installation and operation state belongs only in the global Make Docs Store, managed through the CLI. Applied ownership, hashes, migration receipts, locks, conflict decisions, and recovery metadata must not live in project folders.
|
|
26
|
+
- `.make-docs/manifest.json` and `.make-docs/state/` are legacy CLI transfer inputs only. Never recreate them or replace them with another local operational record.
|
|
27
|
+
- Keep declarative project identity and desired settings in config. Project knowledge, history breadcrumbs, optional work status, and approved backup, archive, or conflict file copies remain local. File copies do not authorize recovery; verified Store records do.
|
|
28
|
+
- Ordinary project work can continue when the CLI is unavailable or optional lifecycle capture fails. Report unavailable capture. Never 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.
|
|
29
|
+
- A local `.make-docs/system/**` resource projection is optional. Its absence does not reduce installed-provider availability.
|
|
30
|
+
|
|
31
|
+
## Allowed Absolute Path Forms
|
|
32
|
+
|
|
33
|
+
Absolute paths are allowed only when the path is not a repository file path or when the absolute location is the subject of the documentation. Examples include platform storage locations, external tool conventions, or diagnostic evidence that cannot be made relative.
|
|
34
|
+
|
|
35
|
+
When an absolute path is warranted, prefer sanitized placeholders:
|
|
36
|
+
|
|
37
|
+
- `<repo-root>/docs/prd/00-index.md`
|
|
38
|
+
- `<user-home>/.config/pile/config.toml`
|
|
39
|
+
- `$HOME/.local/share/pile`
|
|
40
|
+
- `~/.pile/profiles/default.toml`
|
|
41
|
+
- `%APPDATA%\pile\config.toml`
|
|
42
|
+
- `<temp-dir>/runtime/trace.log`
|
|
43
|
+
|
|
44
|
+
If a real absolute path must remain for a specific audit reason, add an inline allow comment on the same line or the previous line:
|
|
45
|
+
|
|
46
|
+
```markdown
|
|
47
|
+
<!-- make-docs-path-hygiene: allow retained diagnostic evidence from user-provided log -->
|
|
48
|
+
```
|
|
49
|
+
|
|
50
|
+
Use the allow comment sparingly. The reason must explain why a project-relative path or sanitized placeholder would lose necessary evidence.
|
|
51
|
+
|
|
52
|
+
## Repair Policy
|
|
53
|
+
|
|
54
|
+
- Convert paths under the current repository root to project-relative paths.
|
|
55
|
+
- In Markdown link destinations, use plain relative destinations such as `docs/prd/00-index.md`.
|
|
56
|
+
- In inline code or prose path literals, use `./docs/prd/00-index.md` when the leading `./` helps signal repository-relative intent.
|
|
57
|
+
- Convert user-home examples to placeholders such as `<user-home>`, `$HOME`, or `~` when the exact username is not meaningful.
|
|
58
|
+
- Convert temporary path examples to `<temp-dir>/...` when the exact machine-local path is not meaningful.
|
|
59
|
+
- Preserve absolute paths only when they describe external behavior or required evidence, and document the exception with the allow comment.
|
|
60
|
+
|
|
61
|
+
## Template Link Placeholders
|
|
62
|
+
|
|
63
|
+
- Use a recognized whole-link token such as `{{SOURCE_PRD_LINK_ONE}}` when a raw template cannot know the final relative target.
|
|
64
|
+
- Replace the token with one complete Markdown link such as `[Product Overview](../../prd/01-product-overview.md)` during generation.
|
|
65
|
+
- A raw-template check may defer only recognized whole-link tokens. It must still reject broken concrete links and malformed partial-link placeholders.
|
|
66
|
+
- A generated-document check must reject every unresolved link token and every link whose final target is missing.
|
|
67
|
+
|
|
68
|
+
## Approved URI Schemes
|
|
69
|
+
|
|
70
|
+
- Use `https:` or `http:` only for an external web resource.
|
|
71
|
+
- Use `mailto:` only for an external email address.
|
|
72
|
+
- Use `make-docs:` only for a cataloged `make-docs://system/<type>/<posix-relative-path>` resource identity.
|
|
73
|
+
- Reject all other URI schemes in generated documentation.
|
|
74
|
+
|
|
75
|
+
## Validation
|
|
76
|
+
|
|
77
|
+
Use `make-docs project path-hygiene validate` to audit local documentation. The default content scope needs neither the Store nor an installation manifest. It checks `docs/`, root routers and `README.md`, and local `.make-docs/system/` bodies. Repeated `--path <project-relative-file-or-directory>` arguments replace the default roots. Use `--include-skills` to include installed Skill text. It skips symbolic links, backup payloads, and operational directories. Explicit linked or unsafe paths are errors.
|
|
78
|
+
|
|
79
|
+
Use `--scope managed` for installation checks. This requires Store inventory. An explicit `--manifest` selects legacy inventory only. Do not combine either with `--path`, or combine a manifest with content scope. A content scan is not installation evidence.
|
|
80
|
+
|
|
81
|
+
Output defaults to JSON. Use `--format text` for a readable report. Exit codes are 0 for clean results, 1 for findings, and 2 for input or file errors.
|
|
82
|
+
|
|
83
|
+
Use `make-docs project path-hygiene repair` to preview repairs. Add `--apply` to write them. Repairs change only current-project absolute paths, preserve allow comments and line endings, and keep Markdown links relative to their document. Other findings require manual review. CLI and MCP use the same operations; MCP writes require its normal write permission.
|
|
84
|
+
|
|
85
|
+
If the CLI is absent, review paths manually and report that the automated check did not run. Do not install a Python helper or create operational state for this check.
|
|
86
|
+
|
|
87
|
+
## Effective Audiences and First Assets
|
|
88
|
+
|
|
89
|
+
The only built-in Personas and primitives are `user` and `maintainer`. Both roles can be filled by humans or agents. The defaults are User (People or agents that use the project.) and Maintainer (People or agents that build, operate, maintain, or extend the project.). Each entry has `slug`, `label`, `description`, and `primitive`. Merge `.make-docs/config.yaml` entries by slug with these defaults. Built-in display fields may be omitted and inherited; supplied primitive mappings must stay fixed. Custom entries need all four fields and one of the two primitives. Absent, empty, or comment-only config and an absent or empty Persona list keep both defaults. Explicit null, wrong types, invalid YAML, duplicate/unsafe slugs, or invalid primitives are errors; do not rewrite the file to hide them. Reserve `project`, `archive`, `artifacts`, `library`, and `playbooks` as structural names. Legacy custom-name conflicts need an explicit new slug and retained-content map; never discard them silently.
|
|
90
|
+
|
|
91
|
+
`make-docs project persona list --target-root <project> --json` reads the effective set and display-field origins without Store access or project writes. Without the CLI, use the same visible defaults and local config. Audience selection does not prove tester qualification.
|
|
92
|
+
|
|
93
|
+
Fresh setup leaves `docs/assets/` absent. Create its needed shared or audience content paths on first use, with only the root instruction filenames declared by `Asset router files:` in the always-present docs router. Do not infer a harness from your own actor identity. Missing or invalid declarations require an explicit project choice for router creation; ordinary content work can continue. `make-docs project surface ensure assets` creates or safely adopts root routers through normal Store-backed ownership review. The retained `artifacts` selector ensures that same root and reports `docs/assets/project/` as a destination; it does not create an empty child or old `docs/artifacts/`.
|
|
94
|
+
|
|
95
|
+
## Reviewed Layout Recovery
|
|
96
|
+
|
|
97
|
+
Use `make-docs project layout preview` to inspect all affected files and empty directories, exact source-to-destination choices, content identities, link repairs, and blockers. Repeated `--map <source>=<destination>` options specify bounded project-relative choices. Preview is read-only. `make-docs project layout prepare --review <digest> --mode cli|manual` rechecks the digest and saves the complete operation intent and recovery evidence in the Store before any project mutation. Preparation returns an operation ID and releases its live process lock; pending Store intent still blocks conflicting supported writes.
|
|
98
|
+
|
|
99
|
+
Use `make-docs project layout apply <operation-id>` for CLI mode. For manual mode, follow the prepared instructions yourself or through an agent, then run `make-docs project layout verify <operation-id>`. Both paths verify the recorded source, destination, and link expectations. Changed bytes, collisions, ambiguous audiences, unsafe paths, missing links, new source files, or unexplained leftovers keep the operation pending. Use `make-docs project state status` and `make-docs project state recover` for the next safe action. No local receipt, queue, marker, or second state engine is permitted.
|
|
100
|
+
|
|
101
|
+
Old artifact homes move to `docs/assets/project/`. Adopted archives move to `.make-docs/archive/`. Proved Library audiences move to their effective Persona paths; map former default `developer` to `maintainer` only with proof, never infer `agent` as `maintainer`, and review custom mappings explicitly. Retired Playbooks move to `.make-docs/archive/legacy-playbooks/` as inactive history. Remove only exactly reviewed obsolete empty directories after rechecking them; preserve current required typed system-router directories. Preserve substantive historical bytes and project ownership. Record mechanical old/new link edits and verify their targets before source cleanup. Named archival and backup exclusions must be non-active provenance, not a way to keep active old families.
|