@brucewaynedecoy/make-docs 2.0.7 → 2.0.9

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (65) hide show
  1. package/dist/{backup-M5RBOM6F.js → backup-EBZZZL74.js} +4 -4
  2. package/dist/{chunk-Z4KZ4JTE.js → chunk-2Z7KRD4H.js} +2 -2
  3. package/dist/{chunk-OSS4NT6N.js → chunk-5XKMSGMS.js} +428 -29
  4. package/dist/{chunk-OSS4NT6N.js.map → chunk-5XKMSGMS.js.map} +1 -1
  5. package/dist/{chunk-O27AYYF3.js → chunk-ABKEBYCF.js} +3 -3
  6. package/dist/{chunk-B6HJRHWL.js → chunk-DZ3SA3JA.js} +70 -12
  7. package/dist/chunk-DZ3SA3JA.js.map +1 -0
  8. package/dist/{chunk-65TAUWTC.js → chunk-HZ4QLB7L.js} +3 -3
  9. package/dist/{chunk-YJLVHT4J.js → chunk-KKXJTVMH.js} +13 -9
  10. package/dist/chunk-KKXJTVMH.js.map +1 -0
  11. package/dist/{chunk-7AVGITZK.js → chunk-MESLJI5A.js} +2 -2
  12. package/dist/{chunk-5WR4D6HH.js → chunk-USVCSYS5.js} +13 -2
  13. package/dist/chunk-USVCSYS5.js.map +1 -0
  14. package/dist/{chunk-3ZFX5456.js → chunk-VCC4D5I3.js} +2 -2
  15. package/dist/{chunk-C67WJWVP.js → chunk-X6TAWRTO.js} +148 -127
  16. package/dist/chunk-X6TAWRTO.js.map +1 -0
  17. package/dist/index.js +41 -24
  18. package/dist/index.js.map +1 -1
  19. package/dist/{registry-7L26WFZP.js → registry-XNCQALXP.js} +7 -7
  20. package/dist/{self-4HOKEXBV.js → self-LDLIIKFW.js} +7 -7
  21. package/dist/{server-VXVGDWRY.js → server-G2UO2NOT.js} +10 -10
  22. package/dist/{server-VXVGDWRY.js.map → server-G2UO2NOT.js.map} +1 -1
  23. package/dist/{setup-system-CJESBAQ5.js → setup-system-2MZMQ3MX.js} +7 -7
  24. package/dist/{skills-command-YXPOHXI2.js → skills-command-VE4GRWI2.js} +53 -17
  25. package/dist/skills-command-VE4GRWI2.js.map +1 -0
  26. package/dist/{uninstall-R2QK7XPK.js → uninstall-EJF6HCYI.js} +7 -7
  27. package/dist/virtual_make-docs-first-party-skills-CLTQEIKC.js +11 -0
  28. package/dist/virtual_make-docs-first-party-skills-CLTQEIKC.js.map +1 -0
  29. package/package.json +1 -1
  30. package/template/.make-docs/system/contracts/design-contract.md +1 -1
  31. package/template/.make-docs/system/contracts/output-contract.md +3 -2
  32. package/template/.make-docs/system/prompts/designs-to-plan-change.prompt.md +2 -2
  33. package/template/.make-docs/system/prompts/prd-change-to-work.prompt.md +2 -2
  34. package/template/.make-docs/system/references/execution-workflow.md +5 -5
  35. package/template/.make-docs/system/references/lifecycle.md +3 -0
  36. package/template/.make-docs/system/references/planning-workflow.md +8 -8
  37. package/template/.make-docs/system/references/prd-change-management.md +2 -2
  38. package/template/.make-docs/system/references/wave-model.md +126 -14
  39. package/template/.make-docs/system/templates/plan-overview.md +17 -2
  40. package/template/.make-docs/system/templates/plan-prd-change.md +21 -6
  41. package/template/.make-docs/system/templates/plan-prd-decompose.md +17 -2
  42. package/template/.make-docs/system/templates/plan-prd.md +17 -2
  43. package/template/.make-docs/system/templates/work-index.md +15 -0
  44. package/template/.make-docs/system/templates/work-phase.md +3 -0
  45. package/template/docs/plans/AGENTS.md +1 -1
  46. package/template/docs/plans/CLAUDE.md +1 -1
  47. package/template/docs/work/AGENTS.md +1 -0
  48. package/template/docs/work/CLAUDE.md +1 -0
  49. package/dist/chunk-5WR4D6HH.js.map +0 -1
  50. package/dist/chunk-B6HJRHWL.js.map +0 -1
  51. package/dist/chunk-C67WJWVP.js.map +0 -1
  52. package/dist/chunk-YJLVHT4J.js.map +0 -1
  53. package/dist/skills-command-YXPOHXI2.js.map +0 -1
  54. package/dist/virtual_make-docs-first-party-skills-POWW3OI3.js +0 -11
  55. package/dist/virtual_make-docs-first-party-skills-POWW3OI3.js.map +0 -1
  56. /package/dist/{backup-M5RBOM6F.js.map → backup-EBZZZL74.js.map} +0 -0
  57. /package/dist/{chunk-Z4KZ4JTE.js.map → chunk-2Z7KRD4H.js.map} +0 -0
  58. /package/dist/{chunk-O27AYYF3.js.map → chunk-ABKEBYCF.js.map} +0 -0
  59. /package/dist/{chunk-65TAUWTC.js.map → chunk-HZ4QLB7L.js.map} +0 -0
  60. /package/dist/{chunk-7AVGITZK.js.map → chunk-MESLJI5A.js.map} +0 -0
  61. /package/dist/{chunk-3ZFX5456.js.map → chunk-VCC4D5I3.js.map} +0 -0
  62. /package/dist/{registry-7L26WFZP.js.map → registry-XNCQALXP.js.map} +0 -0
  63. /package/dist/{self-4HOKEXBV.js.map → self-LDLIIKFW.js.map} +0 -0
  64. /package/dist/{setup-system-CJESBAQ5.js.map → setup-system-2MZMQ3MX.js.map} +0 -0
  65. /package/dist/{uninstall-R2QK7XPK.js.map → uninstall-EJF6HCYI.js.map} +0 -0
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@brucewaynedecoy/make-docs",
3
- "version": "2.0.7",
3
+ "version": "2.0.9",
4
4
  "description": "Plan and maintain project docs with a CLI, MCP server, templates, and optional agent Skills.",
5
5
  "license": "MIT",
6
6
  "repository": {
@@ -48,7 +48,7 @@ Required prompt targets:
48
48
  - `baseline-plan` → `[designs-to-plan.prompt.md](../prompts/designs-to-plan.prompt.md)`
49
49
  - `change-plan` → `[designs-to-plan-change.prompt.md](../prompts/designs-to-plan-change.prompt.md)`
50
50
 
51
- For `change-plan` designs, include `Coordinate Handoff` whenever the design revises, reworks, corrects, standardizes, or finishes earlier wave work. The handoff should identify the prior coordinate, the recommended downstream coordinate, and the basis for treating the work as a revision rather than a new wave. If the coordinate cannot be resolved from the request or repository history, write `Coordinate Handoff: unresolved; planner must resolve before writing.`
51
+ For `change-plan` designs, include `Coordinate Handoff` whenever the design changes an outcome that an earlier wave promised. Apply the `## Decision Procedure` in `.make-docs/system/references/wave-model.md`. The handoff should identify the prior coordinate, the recommended downstream coordinate or in-place amendment, and the test that decided it: the outcome test for a new wave, or the revision Wave test for a revision Wave. If the coordinate cannot be resolved from the request or repository history, write `Coordinate Handoff: unresolved; planner must resolve before writing.`
52
52
 
53
53
  ## Optional Design Lineage
54
54
 
@@ -34,7 +34,7 @@ The governing PRD invariant is:
34
34
 
35
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
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.
37
+ Change-oriented work uses the lineage wave's existing plan and work directories unless `.make-docs/system/references/wave-model.md` selects a new wave or a revision Wave. For a new directory, carry the distinguishing context in the `<slug>` (for example `...-auth-recovery-change`) rather than in the directory structure. Every plan and every work backlog uses the same W/R directory shape.
38
38
 
39
39
  ## PRD Lifecycle Rules
40
40
 
@@ -258,7 +258,8 @@ Use `## Source Anchors` to aggregate the most important files that shaped the do
258
258
  - Organize phases and stages by dependency order, not by implementation convenience.
259
259
  - Include markdown task-list items and plain-bullet acceptance criteria in every stage.
260
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.
261
+ - For PRD authority-maintenance work, amend the lineage wave's work backlog in place or add a revision Phase. Create a new dated work directory only for a new wave or a revision Wave, as `.make-docs/system/references/wave-model.md` decides.
262
+ - After a plan or work backlog's first commit, record each scope edit in its `## Change History`, using the entry shape in `wave-model.md`. Progress updates need no entry.
262
263
  - 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
264
  - Every phase file must include `## Source PRD Docs`.
264
265
  - 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.
@@ -13,6 +13,6 @@ Read `make-docs://system/contract/human-experience-contract.md`, `make-docs://sy
13
13
 
14
14
  Then inspect the active PRD namespace in `docs/prd/` and create a detailed PRD authority-maintenance plan in `docs/plans/`. Follow the instructions, references, and templates in the `docs` directory, especially `.make-docs/system/references/wave-model.md` and `.make-docs/system/references/prd-change-management.md`.
15
15
 
16
- Resolve the plan coordinate before writing. Source lineage from the user request, design handoff, prior plans, prior work backlogs, and history records takes precedence over the highest existing wave. If the change revises, reworks, corrects, standardizes, or finishes work delivered in an earlier wave, keep that wave and use the next unused revision.
16
+ Resolve the plan coordinate before writing, with the `## Decision Procedure` in `.make-docs/system/references/wave-model.md`. Source lineage from the user request, design handoff, prior plans, prior work backlogs, and history records takes precedence over the highest existing wave. Stop at the owner gates that the procedure lists. When the change amends a lineage wave's committed plan in place, record it in that plan's `## Change History` instead of writing a new plan directory.
17
17
 
18
- For every candidate requirement, select `update-existing`, `create`, `link-only`, or `none`. The plan must list existing PRD owners to update; genuinely new product PRDs, if any; required non-normative `## Requirement History` entries; and affected links, risks, plans, and work artifacts. Record the plan coordinate and state whether a scoped delta backlog is sufficient. Do not plan standalone PRDs whose subject is an editorial operation.
18
+ For every candidate requirement, select `update-existing`, `create`, `link-only`, or `none`. The plan must list existing PRD owners to update; genuinely new product PRDs, if any; required non-normative `## Requirement History` entries; and affected links, risks, plans, and work artifacts. Record the plan coordinate, its classification, and whether the work amends the lineage backlog or needs a new one. Do not plan standalone PRDs whose subject is an editorial operation.
@@ -1,6 +1,6 @@
1
1
  ___
2
2
  name: PRD Authority Maintenance to Work Backlog
3
- description: Instructs the agent to generate a dated delta backlog from the updated authoritative PRDs and their governing maintenance plan.
3
+ description: Instructs the agent to amend the lineage work backlog, or create a new one, from the updated authoritative PRDs and their governing maintenance plan.
4
4
  ___
5
5
 
6
6
  When generating or materially rewriting make-docs documents, include PRD 23 YAML frontmatter: common `title`, `kind`, and `status`; add `coordinate`, `persona`, `source`, `lifecycle`, and `follow_on` only when their conditions apply; omit unknown coordinate levels rather than inserting placeholders.
@@ -11,4 +11,4 @@ Then review the updated or genuinely new authoritative PRDs that own the resulti
11
11
 
12
12
  Read `make-docs://system/contract/human-experience-contract.md`, `make-docs://system/reference/human-experience.md`, and `make-docs://system/reference/lifecycle.md` through valid local bodies or `make-docs resource read`. For each applicable current PRD outcome or preserved boundary, create work tasks and observable acceptance criteria that retain the intended human outcome, owning requirement, affected surface, source design and plan lineage, and W/R coordinate. Name the evidence source or current testing decision and its selected executor when current authority has selected one. Route accepted deferral through the current obligation contract. Do not copy the full design intent or Human Experience Standard into the backlog. Do not add Human Experience frontmatter.
13
13
 
14
- Generate a dated delta backlog in `docs/work/`. Follow the instructions, references, and templates in the `docs` directory, especially `.make-docs/system/references/prd-change-management.md`. The backlog should stay scoped to the requested maintenance, remain dependency-ordered, and cite the updated authoritative PRDs in each phase's source-traceability section. Use the maintenance plan for sequencing and scope provenance only. Treat current normative PRD sections as product authority; do not treat requirement-history entries or retired change records as effective requirements.
14
+ Apply the `## Decision Procedure` in `.make-docs/system/references/wave-model.md`. Amend the lineage wave's work backlog in place or add a revision Phase, recording each scope edit to a committed backlog in its `## Change History`. Create a dated backlog in `docs/work/` only for a new wave or a revision Wave. Follow the instructions, references, and templates in the `docs` directory, especially `.make-docs/system/references/prd-change-management.md`. The backlog should stay scoped to the requested maintenance, remain dependency-ordered, and cite the updated authoritative PRDs in each phase's source-traceability section. Use the maintenance plan for sequencing and scope provenance only. Treat current normative PRD sections as product authority; do not treat requirement-history entries or retired change records as effective requirements.
@@ -112,7 +112,7 @@ Apply this gate only in `authoritative PRD maintenance` mode:
112
112
  2. Confirm candidate decisions, existing owner PRDs, and any genuinely new product subjects.
113
113
  3. Route surgical current-requirement updates and requirement-history entries to existing-owner workers.
114
114
  4. Route genuinely new product PRDs and shared index/risk updates to disjoint authoring or assembly workers when possible.
115
- 5. Route delta backlog generation to a dedicated worker.
115
+ 5. Route work backlog updates to a dedicated worker.
116
116
  6. Route product-authority, status, link, and traceability validation to a dedicated validation worker.
117
117
  7. Keep the coordinator focused on status, blockers, and final reporting.
118
118
 
@@ -132,7 +132,7 @@ For authoritative PRD maintenance, prefer these separate write scopes when possi
132
132
  - existing owner PRD updates and requirement history
133
133
  - genuinely new product-authority PRDs
134
134
  - PRD index, risk register, and shared-doc status updates
135
- - delta backlog generation
135
+ - work backlog updates
136
136
  - validation and fix-up
137
137
 
138
138
  ## Existing Documentation Rule
@@ -158,7 +158,7 @@ If a fallback source is used, record which fallback was used and why.
158
158
  ## Backlog Rules
159
159
 
160
160
  - Work is always a directory in v2. Full-set generation writes `docs/work/YYYY-MM-DD-w{W}-r{R}-<slug>/` containing `00-index.md` plus `0N-<phase>.md` phase files.
161
- - Authoritative PRD maintenance writes `docs/work/YYYY-MM-DD-w{W}-r{R}-<slug>/` as a delta backlog directory containing `00-index.md` plus `0N-<phase>.md` phase files.
161
+ - Authoritative PRD maintenance puts its work into the lineage wave's backlog, as an in-place edit or a revision Phase, under the `## Decision Procedure` in `wave-model.md`. It creates a new `docs/work/YYYY-MM-DD-w{W}-r{R}-<slug>/` directory only for a new wave or a revision Wave. After a backlog's first commit, record each scope edit in its `## Change History`.
162
162
  - Plans use the same form: `docs/plans/YYYY-MM-DD-w{W}-r{R}-<slug>/` containing `00-overview.md` plus `0N-<phase>.md` phase files.
163
163
  - Keep backlog phases dependency-ordered across the `0N-<phase>.md` files.
164
164
  - In every stage, write `### Tasks` as markdown task list items using phase-local task IDs (`- [ ] t1: ...`, `- [x] t1: ...`) and write `### Acceptance criteria` as plain unordered bullets only.
@@ -171,7 +171,7 @@ If a fallback source is used, record which fallback was used and why.
171
171
  - Make performance phase gates reject missing, expired, invalid, non-comparable, adjacent-mode, or unrun required evidence. Record `pass`, `fail`, `revise`, `blocked`, or `waived` only. Treat a waiver as bounded risk acceptance, not success. Reuse unchanged evidence, rerun only affected checks after material change, and stop when the authorized budget or diminishing-return rule ends.
172
172
  - Reject acceptance such as `UX is good`, `easy to use`, or `intuitive`. Replace it with a result that a reviewer can observe on the named surface or in evidence tied to the stated indirect effect.
173
173
  - When deferred-obligation or Unassisted Goal Testing routing is active, include applicable `O-###`, `NUAT-###`, and finding traceability plus phase and capability closeout language. Do not invent an ID for `not-needed-now`.
174
- - Delta backlogs cite the updated or genuinely new authoritative PRDs that constrain implementation. Maintenance plans provide sequencing and history provides provenance; neither replaces current PRD authority.
174
+ - Every new or amended backlog phase cites the updated or genuinely new authoritative PRDs that constrain implementation. Maintenance plans provide sequencing and history provides provenance; neither replaces current PRD authority.
175
175
 
176
176
  ## Final Validation
177
177
 
@@ -180,7 +180,7 @@ Before closing the task:
180
180
  1. Resolve broken links, missing core docs, missing required headings, or misplaced backlog files.
181
181
  2. Confirm the PRD index reflects the final catalog, status, and lineage.
182
182
  3. Confirm the backlog links to the relevant PRD docs.
183
- 4. For authoritative PRD maintenance, confirm current requirements are inline, history is non-normative, every new PRD is a coherent product authority, and delta backlog traceability points to current PRDs rather than retired change records.
183
+ 4. For authoritative PRD maintenance, confirm current requirements are inline, history is non-normative, every new PRD is a coherent product authority, and backlog traceability points to current PRDs rather than retired change records.
184
184
  5. When deferred-obligation or Unassisted Goal Testing routing is in scope, confirm closeout records separate testing decisions, any applicable `O-###` disposition, any activated `NUAT-###` scenario, evidence references, and explicit phase versus capability status. Record `not-needed-now` without creating a scenario or obligation.
185
185
  6. Confirm each accepted Human Experience promise reaches current PRD authority, work, and suitable evidence or an accepted obligation. For `none`, confirm the backlog records and proves the preserved human boundary.
186
186
  7. Confirm acceptance is observable. It must let a reviewer determine the subject, relationship, state, next action, recovery path, useful level of detail, or goal completion without relying on an unexplained internal identifier when one of those outcomes is promised.
@@ -121,6 +121,9 @@ When the current request is ambiguous, prefer the next step implied by that
121
121
  chain.
122
122
  If a work backlog already exists, treat it as the implementation authority for
123
123
  phase work unless the user directs a different source of truth.
124
+ When an approved plan or backlog must change, use the `## Decision Procedure`
125
+ in `wave-model.md`, and record each scope edit to a committed plan or backlog in
126
+ its `## Change History`.
124
127
 
125
128
  ## Straddle Rule
126
129
 
@@ -23,7 +23,7 @@ Inspect:
23
23
  - the impact and Human Experience Intent in each applicable source design, using the [Human Experience Contract](../contracts/human-experience-contract.md) and [Human Experience Reference](human-experience.md)
24
24
  - any `Coordinate Handoff` or source-lineage notes in referenced designs
25
25
  - any existing plans, PRD docs, and work backlogs
26
- - any history records for prior phases that the request revises, reworks, corrects, standardizes, or finishes
26
+ - any history records for prior phases whose outcomes the request changes
27
27
  - whether `docs/prd/` already contains active content (archives live under `.make-docs/archive/prds/YYYY-MM-DD/`)
28
28
  - whether the user request is best classified as baseline generation, decomposition, or authoritative PRD maintenance
29
29
 
@@ -34,7 +34,7 @@ requirements, and similar source material as artifacts.
34
34
  Use `docs/assets/project/` as the optional input home; do not create or require an
35
35
  architecture-specific seed directory name.
36
36
 
37
- Resolve the W/R coordinate using `.make-docs/system/references/wave-model.md` before writing. Explicit user guidance and source lineage from designs, prior plans, prior work backlogs, and history records take precedence over the highest existing wave. If source lineage points to an earlier wave but later unrelated waves exist, keep the lineage wave and increment its revision.
37
+ Resolve the W/R coordinate with the `## Decision Procedure` in `.make-docs/system/references/wave-model.md` before writing. Explicit user guidance comes first. New work, decided by the outcome test, gets a new wave. A change to a lineage wave's unfinished work amends that wave's plan and backlog in place. A change to completed work becomes a revision Phase, or a revision Wave only when the revision Wave test passes. Stop at the owner gates listed there. Later unrelated waves never move work to a new wave.
38
38
 
39
39
  If the request is ambiguous, infer the likely mode from the repo, prompt, and explicit design handoff. Ask the user only when the ambiguity materially changes the output shape.
40
40
 
@@ -62,7 +62,7 @@ For authoritative PRD maintenance, the plan should also settle:
62
62
  - the genuinely new capability, subsystem, or product-boundary PRDs to create, if any
63
63
  - the standardized, non-normative requirement-history entries to add
64
64
  - the affected links, risks, plans, work artifacts, and downstream source-authority relationships
65
- - whether a scoped delta backlog is sufficient or the user explicitly wants a regenerated full backlog
65
+ - whether the work amends the lineage wave's backlog in place, rebuilds its unfinished Phases from the PRD (owner approval required), or needs a new backlog because it is a new wave or a revision Wave
66
66
  - any deferred-obligation dispositions, material current human-experience uncertainties, proposed `NUAT-###` ownership for activated tests, and `not-needed-now` reasons needed before implementation
67
67
 
68
68
  ## Human Experience Planning
@@ -89,7 +89,7 @@ Ask the user only when the answer affects the output shape or execution style. T
89
89
  - whether reference-style docs should stay separate from subsystem docs
90
90
  - whether maintenance should stay a scoped delta or requires coordinated updates across several existing PRD owners
91
91
  - whether an apparent new subject is coherent enough for its own product PRD or belongs in an existing owner
92
- - whether the backlog directory should be scoped to a delta or regenerated as a full backlog
92
+ - whether to rebuild a lineage backlog's unfinished Phases from the PRD, which needs owner approval under `wave-model.md`
93
93
  - whether the user explicitly wants to forbid delegation and force single-agent execution despite the default
94
94
 
95
95
  Do not ask questions that can be answered by repo inspection. Do not ask the user which planning route to use when the referenced design docs already declare `## Intended Follow-On`, unless the user is explicitly reconsidering that route.
@@ -106,7 +106,7 @@ Start from the relevant template in `.make-docs/system/templates/`:
106
106
 
107
107
  Every plan should cover:
108
108
 
109
- - coordinate decision, including whether the plan is a new wave or a revision and the evidence used
109
+ - coordinate decision, including `Classification: new-wave` or `revision-wave` and the evidence used (explicit guidance, the outcome test, or the revision Wave test)
110
110
  - repo summary
111
111
  - output contract
112
112
  - execution mode and PRD lifecycle handling
@@ -125,7 +125,7 @@ PRD authority-maintenance plans should additionally cover:
125
125
  - genuinely new product PRDs, if any
126
126
  - requirement-history entries
127
127
  - affected links, risks, plans, and work artifacts
128
- - delta backlog scope and downstream authority links
128
+ - work backlog placement (lineage backlog amendment or a new backlog) and downstream authority links
129
129
  - obligation routing, current-uncertainty planning, and separate testing decisions when Unassisted Goal Testing is implicated
130
130
  - canonical performance-profile ownership, execution-packet ownership, evidence reuse, expiry, and phase-gate consumption when Performance Testing is implicated
131
131
 
@@ -161,7 +161,7 @@ Do not imply that approving the plan automatically authorizes execution. If the
161
161
 
162
162
  For authoritative PRD maintenance:
163
163
 
164
- - keep existing-owner updates, genuinely new product PRDs, shared index/risk updates, and delta backlog generation as separate write scopes whenever practical
164
+ - keep existing-owner updates, genuinely new product PRDs, shared index/risk updates, and work backlog updates as separate write scopes whenever practical
165
165
  - route cross-doc status updates and backlink validation to assembly or validation workers rather than the coordinator
166
166
 
167
167
  ## Flat Vs Nested Decision
@@ -190,7 +190,7 @@ Before leaving planning mode, make the execution prerequisites explicit:
190
190
  - execution should use the delegation ladder by default: parallel agents, then subagents, then single-agent fallback
191
191
  - if delegation is available, the coordinator write scope is `none`
192
192
  - if the task is full-set replacement and `docs/prd/` already has active content, archival approval is required before execution can write the new PRD set
193
- - if the task is authoritative PRD maintenance, the plan names existing owners, any genuinely new product PRDs, requirement-history entries, affected links/risks/plans/work, and delta backlog scope
193
+ - if the task is authoritative PRD maintenance, the plan names existing owners, any genuinely new product PRDs, requirement-history entries, affected links/risks/plans/work, and the work backlog placement
194
194
  - workstreams are disjoint
195
195
  - validation is mandatory
196
196
  - the plan keeps each accepted Human Experience promise or preserved boundary traceable to current PRD authority, work, evidence, and any accepted obligation
@@ -117,8 +117,8 @@ Changes that activate, defer, narrow, cancel, or supersede user-observable accep
117
117
  - History records preserve execution provenance and completed maintenance activity.
118
118
  - Downstream work reads the updated authoritative PRDs for product requirements. It may read the governing plan for sequencing and the history record for provenance, but neither overrides the current PRD body.
119
119
  - Plans and backlogs are always directories: `docs/plans/YYYY-MM-DD-w{W}-r{R}-<slug>/` and `docs/work/YYYY-MM-DD-w{W}-r{R}-<slug>/`.
120
- - A scoped maintenance effort normally produces a dated delta backlog rather than rewriting an earlier backlog.
121
- - Every delta backlog phase cites the updated or genuinely new authoritative PRDs that constrain implementation.
120
+ - Maintenance work goes into the lineage wave's work backlog, as an in-place edit or a revision Phase, under the `## Decision Procedure` in `.make-docs/system/references/wave-model.md`. A new work backlog exists only for a new wave or a revision Wave. After a backlog's first commit, each scope edit adds a `## Change History` entry that records its PRD decision.
121
+ - Every new or amended backlog phase cites the updated or genuinely new authoritative PRDs that constrain implementation.
122
122
  - For `direct` or `indirect` Human Experience impact, the plan and backlog map each accepted promise to its owning PRD, affected surface or effect, work phase, evidence source or selected testing type, and any accepted obligation. For `none` Human Experience impact, they name the preserved human boundary and its proof. These links carry the accepted outcome forward without making the plan or backlog a second product authority.
123
123
 
124
124
  ## Validation Checklist
@@ -2,19 +2,28 @@
2
2
 
3
3
  ## Purpose
4
4
 
5
- This file is the single source of truth for the Wave/Revision/Phase (W/R/P) encoding used across `make-docs` v2.
5
+ This file is the single source of truth for the Wave/Revision/Phase (W/R/P) encoding used across `make-docs` v2 plans, work backlogs, and history records. It also defines how an agent selects a coordinate and how a committed plan or work backlog changes.
6
6
 
7
- Every other reference file, template, and router links here instead of restating these rules. The encoding was piloted in `.make-docs/system/contracts/history-record-contract.md` and is extended to designs, plans, and work in v2. PRDs are exempt; see `## PRD Exemption`.
7
+ Every other reference file, template, and router links here instead of restating these rules. The encoding was piloted in `.make-docs/system/contracts/history-record-contract.md`. PRDs and designs are exempt; see `## PRD Exemption` and `## Design Exemption`.
8
8
 
9
9
  ## Terms
10
10
 
11
11
  | Token | Name | Meaning |
12
12
  | --- | --- | --- |
13
- | `w{W}` | Wave | One end-to-end iteration: design to plan to work. Wave 1 is the initial wave. A new wave begins when the user starts a new end-to-end initiative. |
14
- | `r{R}` | Revision | Revision within a wave. `r0` is the initial revision. `r1+` are meaningful redos of that wave's artifacts (for example a redesigned design or a re-planned plan after feedback). |
13
+ | `w{W}` | Wave | A self-contained unit of work. The Wave is the scope. It can be a full build, one domain slice, or one change request. Its plan is the statement of work. Wave 1 is the initial wave. |
14
+ | `r{R}` | Revision | `r0` is the base revision of every Wave. `r1+` is a revision Wave: a change order that revisits or rearchitects a substantial part of the Wave's completed work. A revision Wave has its own plan and work backlog. |
15
15
  | `p{P}` | Phase | Phase within a plan or work backlog. Appears in inner phase files, phase-scoped history filenames, and history record `coordinate` frontmatter. `p{P}` does not appear in the top-level names of designs, plans, or work directories. Stage/task detail stays in `coordinate` only. |
16
16
  | `t{T}` | Task | Task within one work backlog phase file. Task IDs appear on `### Tasks` checkbox items as phase-local ordinals (`t1`, `t2`, etc.) and are referenced externally as `w{W} r{R} p{P} t{T}` by inferring W/R from the work directory and P from the phase file. |
17
17
 
18
+ Related terms:
19
+
20
+ | Term | Meaning |
21
+ | --- | --- |
22
+ | Phase complete | The Phase work is done, closed out, and committed. Deployment is extra evidence only: work that is deployed but not committed is not complete. Work that is done but not committed is not complete; edit or undo it in place. |
23
+ | Revision Phase | The next unused `P` in the same W/R that changes the result of a completed Phase. It carries no other coordinate marker. |
24
+ | Lineage Wave | The existing Wave whose plan promised the outcome that a request changes. |
25
+ | PRD | The product authority. A plan or work backlog never overrides it, and a work backlog can be rebuilt from it. |
26
+
18
27
  ## Naming Patterns
19
28
 
20
29
  | Artifact | Required path |
@@ -31,24 +40,127 @@ Every other reference file, template, and router links here instead of restating
31
40
 
32
41
  `<slug>` is lowercase, hyphens only, no special characters.
33
42
 
34
- ## Resolution Rules
43
+ ## Decision Procedure
44
+
45
+ Use this procedure before writing a new plan or work directory, and before changing a committed plan or work backlog. Apply the steps in order. Steps 1 and 2 can decide the coordinate, but the significant deviation test and the owner gates still apply before you change any plan or backlog.
46
+
47
+ 1. **Honor explicit guidance.** If the user states the coordinate (for example "this is wave 2" or "make this a revision wave"), use it. Still apply the significant deviation test and the owner gates to the change.
48
+ 2. **Outcome test.** Does the request add an outcome that no Wave's plan promised? An outcome can be a new capability or an enhancement. Decide by outcome, not by code area.
49
+ - If yes, the request is new work. Scan `docs/plans/`, `docs/work/`, and their archives for the highest `W`. Use the highest `W` plus one, with `r0`. If the scan finds no plan or work entries, use `w1-r0`. A Wave can be small.
50
+ - A PRD `create` decision is strong evidence of new work, but it does not decide the result alone.
51
+ - If an unfinished Wave could also absorb the outcome, ask the owner whether to extend that Wave or start a new one.
52
+ 3. **Lineage Wave.** Otherwise the request changes an outcome that an existing Wave promised. Inspect the user request, referenced designs, design lineage, coordinate handoffs, prior plans, prior work backlogs, and history records to find that lineage Wave.
53
+ - **Archived lineage first.** If the lineage Wave's plan and work are archived, ask the owner before any other decision. After approval, restore them to the working set under their existing names, then continue with this step.
54
+ - **Not complete** (unstarted, in progress, or done but not committed): if the change does not significantly deviate from the plan, edit the existing backlog in place. If it does significantly deviate, ask the owner to choose:
55
+ - **Pivot:** amend the same plan and backlog in place, at the same W/R.
56
+ - **Finish first:** complete the Wave, then open a revision Wave.
57
+ - **Complete:** add a revision Phase at the next unused `P` of the same W/R, unless the revision Wave test passes. If it passes, open a revision Wave at the next unused `R` of the lineage Wave.
58
+ 4. **No drift to newer Waves.** Do not assign a new Wave only because newer, unrelated Waves exist. The highest-wave scan is for new work only.
59
+
60
+ ### Significant Deviation Test
61
+
62
+ A change significantly deviates from the plan when it does one of these:
63
+
64
+ - changes the plan's goal, scope, or non-goals;
65
+ - replaces the approach or architecture that the plan chose;
66
+ - adds a product capability that the plan does not name.
67
+
68
+ These changes are not significant:
69
+
70
+ - adding, splitting, or reordering Phases or tasks inside the stated scope;
71
+ - fixing defects;
72
+ - adjusting tests or evidence.
73
+
74
+ ### Revision Wave Test
75
+
76
+ A change to completed work is a revision Wave when at least one of these is true:
77
+
78
+ 1. It reverses an approach or architecture choice in the plan, so the plan must be rewritten, not extended.
79
+ 2. It must redo the results of two or more completed Phases.
80
+ 3. The fix needs its own design, or a plan with several Phases.
81
+
82
+ Deployment alone does not make a change a revision Wave. Otherwise, the change is a revision Phase.
83
+
84
+ ### Owner Gates
85
+
86
+ | Action | Agent decides alone | Ask the owner first |
87
+ | --- | --- | --- |
88
+ | Edit unfinished work that fits the plan | Yes | No |
89
+ | Add a revision Phase | Yes. State the choice and the reason. | When a revision Wave test result is borderline |
90
+ | Make a significant plan change on an unfinished Wave | No | Yes |
91
+ | Create a revision Wave | No | Yes |
92
+ | Create a new Wave when an existing Wave could absorb the work | No | Yes |
93
+ | Rebuild a work backlog from the PRD | No | Yes |
94
+ | Restore an archived Wave | No | Yes |
95
+
96
+ An owner question names the choice, the reason, and the effect, and follows the user action request rules in `.make-docs/system/contracts/human-experience-contract.md`. For a choice the agent makes alone, its reply names the chosen coordinate and the reason. Never select a coordinate silently.
35
97
 
36
- When writing a new plan directory or work directory, determine `W` and `R` in this order:
98
+ ### Recording The Decision
37
99
 
38
- 1. **Honor explicit guidance.** If the user has stated the wave or revision (for example "this is wave 2" or "redo the design as r1"), use those values.
39
- 2. **Resolve source lineage before scanning for the highest wave.** Inspect the user request, referenced designs, design lineage, intended follow-on coordinate handoff, prior plans, prior work backlogs, and history records for an existing W/R/P coordinate. If the new work revises, reworks, corrects, standardizes, or finishes something already delivered in a known wave, keep that `W` and use the next unused `R` for that wave. This lineage rule wins even when later unrelated waves already exist.
40
- 3. **Scan the target directory only after lineage is resolved** (`docs/plans/` or `docs/work/`) for existing entries matching `w{W}-r{R}`. Parse the highest `W` and the existing revisions for any lineage-selected wave.
41
- 4. **Decide W and R when no source lineage applies:**
42
- - If the user is revising an existing artifact in the highest relevant wave, keep `W` and use the next unused `R`.
43
- - If the user is starting a new end-to-end initiative, increment the highest existing `W` and reset `R` to `0`.
44
- 5. **If no prior entries exist**, default to `w1-r0`.
100
+ - Every plan records its `## Coordinate Decision` with `Classification: new-wave` or `revision-wave` and the evidence: the explicit guidance, the outcome test, or the revision Wave test that applied. The legacy value `revision` means `revision-wave`.
101
+ - A revision Wave's plan names the completed Phases it changes. The prior work backlog's `## Change History` records a `revision-wave` entry that links to the new W/R.
102
+ - A revision Phase names the Phase it changes in a `Revises:` line under its `## Purpose`. When it opens new work in a completed Wave, set the work index status back to `active`.
45
103
 
46
- Do not assign a new wave solely because newer unrelated waves exist. The highest-wave scan is a fallback for genuinely new initiatives, not evidence that a revision to older work belongs to a newer wave.
104
+ ## Change History
105
+
106
+ A plan or work backlog that has been committed at least once records each later scope change in a `## Change History` section.
107
+
108
+ - In a work backlog, the section goes at the end of `00-index.md`.
109
+ - In a plan, the section goes at the end of `00-overview.md`, when the plan changes.
110
+ - A scope edit adds, removes, or rewrites tasks, acceptance criteria, or Phases. Each scope edit needs an entry.
111
+ - Progress updates never need an entry. Progress updates are checked tasks, status changes, closeout notes, and evidence links.
112
+ - Before its first commit, a plan or work backlog is a draft and needs no entries.
113
+
114
+ The entry shape mirrors the PRD `## Requirement History` contract in `.make-docs/system/references/prd-change-management.md`. Use one dated `###` entry per coherent change, newest entry last. Use the most specific coordinate the change affects, for example `W28 R0 P3`, or `W28 R0` when the change affects more than one Phase.
115
+
116
+ ```md
117
+ ## Change History
118
+
119
+ ### {{DATE}} — {{COORDINATE}}
120
+
121
+ - Kind: `{{EDIT_REVISION_PHASE_PIVOT_REBUILD_OR_REVISION_WAVE}}`
122
+ - Affected scope: {{PHASES_OR_TASKS}}
123
+ - Previous scope: {{PREVIOUS_SCOPE}}
124
+ - Replacement scope: {{REPLACEMENT_SCOPE}}
125
+ - Rationale: {{RATIONALE}}
126
+ - PRD decision: `{{UPDATE_EXISTING_CREATE_LINK_ONLY_OR_NONE}}` — {{REASON_WHEN_NONE}}
127
+ - Owner approval: {{APPROVAL_SOURCE_OR_NOT_REQUIRED}}
128
+ - Source: [{{SOURCE_LABEL}}]({{RELATIVE_SOURCE_PATH}})
129
+ ```
130
+
131
+ `Kind` is one of `edit`, `revision-phase`, `pivot`, `rebuild`, or `revision-wave`. `PRD decision` is one of `update-existing`, `create`, `link-only`, or `none`; give the reason when it is `none`.
132
+
133
+ ## Plans, PRDs, And Work
134
+
135
+ - The PRD decision (`update-existing`, `create`, `link-only`, or `none`) is separate from the coordinate decision. When a change alters product requirements, update the owning PRD first, then the plan or work backlog.
136
+ - PRD maintenance work goes into the lineage Wave's work backlog, as an in-place edit or a revision Phase. Create a new work backlog only for a new Wave or a revision Wave.
137
+ - Write a plan before execution. After its first commit, amend it in place, with `## Change History`, when the owner approves a pivot or when a revision Phase changes plan-level scope. An amended plan keeps its W/R.
138
+
139
+ ## Rebuild From The PRD
140
+
141
+ A work backlog can be rebuilt from the current PRD set after the owner approves.
142
+
143
+ - Keep the same W/R and the same record location. Do not create a duplicate record.
144
+ - Keep completed Phases unchanged, including their tasks, checkboxes, and closeout notes.
145
+ - Rebuild only the unfinished Phases.
146
+ - Add a `## Change History` entry of kind `rebuild`.
147
+
148
+ History keeps the prior version. These rules describe outcomes, not a storage mechanism, so they hold wherever a project keeps its history and archive.
149
+
150
+ ## Breadcrumbs And Tasks
47
151
 
48
152
  For breadcrumb records, store any known W/R/P/S/T position in the `coordinate` frontmatter field described by `.make-docs/system/contracts/history-record-contract.md`. Include W/R/P in the filename when all three are known. Include W/R when only those two are known. Keep stage and task detail only in `coordinate`.
49
153
 
50
154
  For work backlog tasks, number task IDs ordinally across the entire phase file, not within each stage. Start the first task at `t1`, continue through later `### Tasks` sections without resetting, and do not renumber existing task IDs when inserting or completing work. Use unordered markdown task syntax (`- [ ] t1: ...` or `- [x] t1: ...`) so checkbox rendering stays reliable.
51
155
 
156
+ ## Adoption
157
+
158
+ These rules govern coordinates selected and records changed from their adoption forward. Existing plan and work records keep their coordinates. Do not renumber or rewrite an older record to match these rules. Older records may use a revision for a fix or an add-on that these rules would now treat as a revision Phase.
159
+
160
+ ## Deterministic Support
161
+
162
+ Coordinate selection is agent judgment: the outcome test, the significant deviation test, and the revision Wave test need it. When the CLI is available, `make-docs run work backlog snapshot` reports supporting facts: whether each phase file is committed, whether its closeout notes are present, whether a record is archived, each record's next free `P`, each Wave's revisions and next free `R`, and the highest `W`. It also checks the shape of a work backlog's `## Change History`. It never selects a coordinate. Treat an unknown fact as unknown, never as false. The `committed` fact describes the current working tree. A completed phase with a later uncommitted progress edit reads `false`, so the agent decides from history whether the phase was completed and committed earlier.
163
+
52
164
  ## PRD Exemption
53
165
 
54
166
  PRDs are intentionally exempt from W/R/P. The PRD namespace is maintained in place as the current product authority rather than iterating in waves.
@@ -46,8 +46,8 @@ For current performance candidates, read `make-docs://system/contract/performanc
46
46
  ## Coordinate Decision
47
47
 
48
48
  - Coordinate: `W{{W}} R{{R}}`
49
- - Classification: `new-wave` or `revision`
50
- - Evidence: Explain the explicit user guidance, design handoff, source lineage, prior plan/work/history records, or highest-wave fallback used to choose this coordinate.
49
+ - Classification: `new-wave` or `revision-wave` (the legacy value `revision` means `revision-wave`)
50
+ - Evidence: Name the explicit user guidance, the outcome test result for a new wave, or the revision Wave test that passed, with the design handoff, source lineage, and prior plan/work/history records used. Apply the `## Decision Procedure` in `.make-docs/system/references/wave-model.md`. An in-place amendment of a committed plan keeps this section and records the change in `## Change History`.
51
51
 
52
52
  ## Phase Map
53
53
 
@@ -74,3 +74,18 @@ This handoff is advisory-default-but-overridable: it is authoritative unless the
74
74
  - Next step: Generate or update the PRD set from this plan.
75
75
  - Why: The plan should become the product or documentation contract before work backlog generation.
76
76
  - Coordinate Handoff: Carry `W{{W}} R{{R}}` into the downstream PRD and work backlog lineage, or explain the coordinate question that must be resolved before writing.
77
+
78
+ ## Change History
79
+
80
+ <!-- Optional. Add this section only after this plan has been committed and its scope changes. One entry per coherent scope edit, newest last. Progress updates need no entry. See the `## Change History` section of `.make-docs/system/references/wave-model.md`. `PRD decision` is `update-existing`, `create`, `link-only`, or `none`. `Source` is a relative Markdown link to the governing design, plan, work, history, owner decision, or evidence. Remove this comment and the example entry when the section is not needed. -->
81
+
82
+ ### {{DATE}} — {{COORDINATE}}
83
+
84
+ - Kind: `{{EDIT_REVISION_PHASE_PIVOT_REBUILD_OR_REVISION_WAVE}}`
85
+ - Affected scope: {{PHASES_OR_TASKS}}
86
+ - Previous scope: {{PREVIOUS_SCOPE}}
87
+ - Replacement scope: {{REPLACEMENT_SCOPE}}
88
+ - Rationale: {{RATIONALE}}
89
+ - PRD decision: `{{PRD_DECISION}}` — {{REASON_WHEN_NONE}}
90
+ - Owner approval: {{APPROVAL_SOURCE_OR_NOT_REQUIRED}}
91
+ - Source: {{RELATIVE_SOURCE_REFERENCE}}
@@ -31,8 +31,8 @@ Implementation sequencing, migration actions, reconciliation work, and editorial
31
31
  ## Coordinate Decision
32
32
 
33
33
  - Coordinate: `W{{W}} R{{R}}`
34
- - Classification: `new-wave` or `revision`
35
- - Evidence: Explain the explicit user guidance, design handoff, source lineage, prior plan/work/history records, or highest-wave fallback used to choose this coordinate.
34
+ - Classification: `new-wave` or `revision-wave` (the legacy value `revision` means `revision-wave`)
35
+ - Evidence: Name the explicit user guidance, the outcome test result for a new wave, or the revision Wave test that passed, with the design handoff, source lineage, and prior plan/work/history records used. Apply the `## Decision Procedure` in `.make-docs/system/references/wave-model.md`. An in-place amendment of a committed plan keeps this section and records the change in `## Change History`.
36
36
 
37
37
  The coordinate identifies this maintenance plan. Product PRDs do not use W/R/P as document identity; carry the coordinate into requirement-history entries and source links only.
38
38
 
@@ -119,15 +119,15 @@ List material prior contracts that should be preserved after the current normati
119
119
  - Genuinely new authoritative PRDs, if any: {{NEW_PRD_TARGETS}}
120
120
  - Requirement-history entries: {{HISTORY_ENTRY_TARGETS}}
121
121
  - Shared PRD surfaces: {{INDEX_AND_RISK_TARGETS}}
122
- - Delta backlog:
123
- - `docs/work/{{DATE}}-w{{W}}-r{{R}}-{{MAINTENANCE_SLUG}}/`
122
+ - Work backlog (lineage amendment or new):
123
+ - `{{LINEAGE_OR_NEW_WORK_DIRECTORY}}`
124
124
 
125
125
  ## Worker Ownership
126
126
 
127
127
  List delegated workers, their scopes, write scopes, dependencies, and deliverables.
128
128
 
129
129
  - Assign every output-writing task to a worker when delegation is available.
130
- - Keep existing-owner updates, genuinely new product PRDs, shared index/risk maintenance, delta backlog generation, and validation as separate write scopes whenever practical.
130
+ - Keep existing-owner updates, genuinely new product PRDs, shared index/risk maintenance, work backlog updates, and validation as separate write scopes whenever practical.
131
131
  - Include a dedicated validation or fix worker when the harness can support it.
132
132
  - The coordinator should not appear as the owner of any document-writing task when delegation is available.
133
133
 
@@ -151,5 +151,20 @@ Explain how execution will validate the outputs. Validation should confirm:
151
151
  - every material prior contract is preserved only in a standardized, non-normative `## Requirement History` entry
152
152
  - `docs/prd/00-index.md` uses product-oriented kinds and current-authority links
153
153
  - removals and deprecations are expressed as current scope, non-goal, limitation, status, or boundary statements before history is recorded
154
- - the delta backlog cites updated authoritative PRDs, not retired change records
154
+ - the new or amended backlog phases cite updated authoritative PRDs, not retired change records
155
155
  - no existing PRD was renumbered or broadly rewritten without an ownership-based reason
156
+
157
+ ## Change History
158
+
159
+ <!-- Optional. Add this section only after this plan has been committed and its scope changes. One entry per coherent scope edit, newest last. Progress updates need no entry. See the `## Change History` section of `.make-docs/system/references/wave-model.md`. `PRD decision` is `update-existing`, `create`, `link-only`, or `none`. `Source` is a relative Markdown link to the governing design, plan, work, history, owner decision, or evidence. Remove this comment and the example entry when the section is not needed. -->
160
+
161
+ ### {{DATE}} — {{COORDINATE}}
162
+
163
+ - Kind: `{{EDIT_REVISION_PHASE_PIVOT_REBUILD_OR_REVISION_WAVE}}`
164
+ - Affected scope: {{PHASES_OR_TASKS}}
165
+ - Previous scope: {{PREVIOUS_SCOPE}}
166
+ - Replacement scope: {{REPLACEMENT_SCOPE}}
167
+ - Rationale: {{RATIONALE}}
168
+ - PRD decision: `{{PRD_DECISION}}` — {{REASON_WHEN_NONE}}
169
+ - Owner approval: {{APPROVAL_SOURCE_OR_NOT_REQUIRED}}
170
+ - Source: {{RELATIVE_SOURCE_REFERENCE}}
@@ -25,8 +25,8 @@ State what the decomposition should preserve, who the outputs are for, and what
25
25
  ## Coordinate Decision
26
26
 
27
27
  - Coordinate: `W{{W}} R{{R}}`
28
- - Classification: `new-wave` or `revision`
29
- - Evidence: Explain the explicit user guidance, design handoff, source lineage, prior plan/work/history records, or highest-wave fallback used to choose this coordinate.
28
+ - Classification: `new-wave` or `revision-wave` (the legacy value `revision` means `revision-wave`)
29
+ - Evidence: Name the explicit user guidance, the outcome test result for a new wave, or the revision Wave test that passed, with the design handoff, source lineage, and prior plan/work/history records used. Apply the `## Decision Procedure` in `.make-docs/system/references/wave-model.md`. An in-place amendment of a committed plan keeps this section and records the change in `## Change History`.
30
30
 
31
31
  ## Output Contract
32
32
 
@@ -78,3 +78,18 @@ List the delegated workers, their scopes, write scopes, dependencies, and delive
78
78
  ## Validation
79
79
 
80
80
  Explain how the execution step will validate the generated outputs and which review pass happens at the end.
81
+
82
+ ## Change History
83
+
84
+ <!-- Optional. Add this section only after this plan has been committed and its scope changes. One entry per coherent scope edit, newest last. Progress updates need no entry. See the `## Change History` section of `.make-docs/system/references/wave-model.md`. `PRD decision` is `update-existing`, `create`, `link-only`, or `none`. `Source` is a relative Markdown link to the governing design, plan, work, history, owner decision, or evidence. Remove this comment and the example entry when the section is not needed. -->
85
+
86
+ ### {{DATE}} — {{COORDINATE}}
87
+
88
+ - Kind: `{{EDIT_REVISION_PHASE_PIVOT_REBUILD_OR_REVISION_WAVE}}`
89
+ - Affected scope: {{PHASES_OR_TASKS}}
90
+ - Previous scope: {{PREVIOUS_SCOPE}}
91
+ - Replacement scope: {{REPLACEMENT_SCOPE}}
92
+ - Rationale: {{RATIONALE}}
93
+ - PRD decision: `{{PRD_DECISION}}` — {{REASON_WHEN_NONE}}
94
+ - Owner approval: {{APPROVAL_SOURCE_OR_NOT_REQUIRED}}
95
+ - Source: {{RELATIVE_SOURCE_REFERENCE}}
@@ -25,8 +25,8 @@ State what the PRD set should capture, who the outputs are for, and what counts
25
25
  ## Coordinate Decision
26
26
 
27
27
  - Coordinate: `W{{W}} R{{R}}`
28
- - Classification: `new-wave` or `revision`
29
- - Evidence: Explain the explicit user guidance, design handoff, source lineage, prior plan/work/history records, or highest-wave fallback used to choose this coordinate.
28
+ - Classification: `new-wave` or `revision-wave` (the legacy value `revision` means `revision-wave`)
29
+ - Evidence: Name the explicit user guidance, the outcome test result for a new wave, or the revision Wave test that passed, with the design handoff, source lineage, and prior plan/work/history records used. Apply the `## Decision Procedure` in `.make-docs/system/references/wave-model.md`. An in-place amendment of a committed plan keeps this section and records the change in `## Change History`.
30
30
 
31
31
  ## Design Inputs
32
32
 
@@ -148,3 +148,18 @@ Explain how the execution step will validate the generated outputs. Validation s
148
148
  - Cross-references between docs are consistent and resolvable.
149
149
 
150
150
  Describe which review pass happens at the end and who approves the final output set.
151
+
152
+ ## Change History
153
+
154
+ <!-- Optional. Add this section only after this plan has been committed and its scope changes. One entry per coherent scope edit, newest last. Progress updates need no entry. See the `## Change History` section of `.make-docs/system/references/wave-model.md`. `PRD decision` is `update-existing`, `create`, `link-only`, or `none`. `Source` is a relative Markdown link to the governing design, plan, work, history, owner decision, or evidence. Remove this comment and the example entry when the section is not needed. -->
155
+
156
+ ### {{DATE}} — {{COORDINATE}}
157
+
158
+ - Kind: `{{EDIT_REVISION_PHASE_PIVOT_REBUILD_OR_REVISION_WAVE}}`
159
+ - Affected scope: {{PHASES_OR_TASKS}}
160
+ - Previous scope: {{PREVIOUS_SCOPE}}
161
+ - Replacement scope: {{REPLACEMENT_SCOPE}}
162
+ - Rationale: {{RATIONALE}}
163
+ - PRD decision: `{{PRD_DECISION}}` — {{REASON_WHEN_NONE}}
164
+ - Owner approval: {{APPROVAL_SOURCE_OR_NOT_REQUIRED}}
165
+ - Source: {{RELATIVE_SOURCE_REFERENCE}}
@@ -56,3 +56,18 @@ This handoff is advisory-default-but-overridable: it is authoritative unless the
56
56
  - Next step: Start with the first applicable phase in this backlog and continue phase-by-phase.
57
57
  - Why: The backlog is the implementation queue derived from the plan and PRD contract.
58
58
  - Coordinate Handoff: Carry this backlog's W/R coordinate into phase history records and commits, adding the active P coordinate for each phase.
59
+
60
+ ## Change History
61
+
62
+ <!-- Optional. Add this section only after this work backlog has been committed and its scope changes. One entry per coherent scope edit, newest last. Progress updates need no entry. See the `## Change History` section of `.make-docs/system/references/wave-model.md`. `PRD decision` is `update-existing`, `create`, `link-only`, or `none`. `Source` is a relative Markdown link to the governing design, plan, work, history, owner decision, or evidence. Remove this comment and the example entry when the section is not needed. -->
63
+
64
+ ### {{DATE}} — {{COORDINATE}}
65
+
66
+ - Kind: `{{EDIT_REVISION_PHASE_PIVOT_REBUILD_OR_REVISION_WAVE}}`
67
+ - Affected scope: {{PHASES_OR_TASKS}}
68
+ - Previous scope: {{PREVIOUS_SCOPE}}
69
+ - Replacement scope: {{REPLACEMENT_SCOPE}}
70
+ - Rationale: {{RATIONALE}}
71
+ - PRD decision: `{{PRD_DECISION}}` — {{REASON_WHEN_NONE}}
72
+ - Owner approval: {{APPROVAL_SOURCE_OR_NOT_REQUIRED}}
73
+ - Source: {{RELATIVE_SOURCE_REFERENCE}}
@@ -16,6 +16,9 @@ coordinate: "W{{W}} R{{R}} P{{PHASE_NUMBER}}"
16
16
 
17
17
  Explain why this phase exists and what foundation it depends on.
18
18
 
19
+ <!-- For a revision Phase only, keep the next line and replace the token with a relative Markdown link to the completed Phase it changes. Otherwise remove it. See `.make-docs/system/references/wave-model.md`. -->
20
+ Revises: {{REVISED_PHASE_REFERENCE}}
21
+
19
22
  ## Overview
20
23
 
21
24
  Explain the work covered by this phase and the value it unlocks.
@@ -22,6 +22,6 @@ Pattern: `YYYY-MM-DD-w{W}-r{R}-<slug>/`
22
22
  - PRD authority-maintenance plans list existing PRD owners to update, genuinely new product PRDs if any, requirement-history entries, and affected links, risks, plans, and work artifacts. Editorial change and revision language belongs here, not in `docs/prd/`.
23
23
  - Always create the plan as a directory; even single-phase plans use the same shape with one `0N-<phase>.md` file.
24
24
  - Apply the date-slug-W/R naming; do not backdate plans.
25
- - Plans are written before execution, not retroactively.
25
+ - Plans are written before execution. After a plan's first commit, amend it in place under the `## Decision Procedure` in `.make-docs/system/references/wave-model.md`, and record each scope edit in its `## Change History`.
26
26
  - Archived plans live in `.make-docs/archive/plans/`. Before first use, run `make-docs project surface ensure archive`. Never archive unless explicitly asked.
27
27
  <!-- make-docs:end -->
@@ -22,6 +22,6 @@ Pattern: `YYYY-MM-DD-w{W}-r{R}-<slug>/`
22
22
  - PRD authority-maintenance plans list existing PRD owners to update, genuinely new product PRDs if any, requirement-history entries, and affected links, risks, plans, and work artifacts. Editorial change and revision language belongs here, not in `docs/prd/`.
23
23
  - Always create the plan as a directory; even single-phase plans use the same shape with one `0N-<phase>.md` file.
24
24
  - Apply the date-slug-W/R naming; do not backdate plans.
25
- - Plans are written before execution, not retroactively.
25
+ - Plans are written before execution. After a plan's first commit, amend it in place under the `## Decision Procedure` in `.make-docs/system/references/wave-model.md`, and record each scope edit in its `## Change History`.
26
26
  - Archived plans live in `.make-docs/archive/plans/`. Before first use, run `make-docs project surface ensure archive`. Never archive unless explicitly asked.
27
27
  <!-- make-docs:end -->