@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.
- package/dist/{backup-M5RBOM6F.js → backup-EBZZZL74.js} +4 -4
- package/dist/{chunk-Z4KZ4JTE.js → chunk-2Z7KRD4H.js} +2 -2
- package/dist/{chunk-OSS4NT6N.js → chunk-5XKMSGMS.js} +428 -29
- package/dist/{chunk-OSS4NT6N.js.map → chunk-5XKMSGMS.js.map} +1 -1
- package/dist/{chunk-O27AYYF3.js → chunk-ABKEBYCF.js} +3 -3
- package/dist/{chunk-B6HJRHWL.js → chunk-DZ3SA3JA.js} +70 -12
- package/dist/chunk-DZ3SA3JA.js.map +1 -0
- package/dist/{chunk-65TAUWTC.js → chunk-HZ4QLB7L.js} +3 -3
- package/dist/{chunk-YJLVHT4J.js → chunk-KKXJTVMH.js} +13 -9
- package/dist/chunk-KKXJTVMH.js.map +1 -0
- package/dist/{chunk-7AVGITZK.js → chunk-MESLJI5A.js} +2 -2
- package/dist/{chunk-5WR4D6HH.js → chunk-USVCSYS5.js} +13 -2
- package/dist/chunk-USVCSYS5.js.map +1 -0
- package/dist/{chunk-3ZFX5456.js → chunk-VCC4D5I3.js} +2 -2
- package/dist/{chunk-C67WJWVP.js → chunk-X6TAWRTO.js} +148 -127
- package/dist/chunk-X6TAWRTO.js.map +1 -0
- package/dist/index.js +41 -24
- package/dist/index.js.map +1 -1
- package/dist/{registry-7L26WFZP.js → registry-XNCQALXP.js} +7 -7
- package/dist/{self-4HOKEXBV.js → self-LDLIIKFW.js} +7 -7
- package/dist/{server-VXVGDWRY.js → server-G2UO2NOT.js} +10 -10
- package/dist/{server-VXVGDWRY.js.map → server-G2UO2NOT.js.map} +1 -1
- package/dist/{setup-system-CJESBAQ5.js → setup-system-2MZMQ3MX.js} +7 -7
- package/dist/{skills-command-YXPOHXI2.js → skills-command-VE4GRWI2.js} +53 -17
- package/dist/skills-command-VE4GRWI2.js.map +1 -0
- package/dist/{uninstall-R2QK7XPK.js → uninstall-EJF6HCYI.js} +7 -7
- package/dist/virtual_make-docs-first-party-skills-CLTQEIKC.js +11 -0
- package/dist/virtual_make-docs-first-party-skills-CLTQEIKC.js.map +1 -0
- package/package.json +1 -1
- package/template/.make-docs/system/contracts/design-contract.md +1 -1
- package/template/.make-docs/system/contracts/output-contract.md +3 -2
- package/template/.make-docs/system/prompts/designs-to-plan-change.prompt.md +2 -2
- package/template/.make-docs/system/prompts/prd-change-to-work.prompt.md +2 -2
- package/template/.make-docs/system/references/execution-workflow.md +5 -5
- package/template/.make-docs/system/references/lifecycle.md +3 -0
- package/template/.make-docs/system/references/planning-workflow.md +8 -8
- package/template/.make-docs/system/references/prd-change-management.md +2 -2
- package/template/.make-docs/system/references/wave-model.md +126 -14
- package/template/.make-docs/system/templates/plan-overview.md +17 -2
- package/template/.make-docs/system/templates/plan-prd-change.md +21 -6
- package/template/.make-docs/system/templates/plan-prd-decompose.md +17 -2
- package/template/.make-docs/system/templates/plan-prd.md +17 -2
- package/template/.make-docs/system/templates/work-index.md +15 -0
- package/template/.make-docs/system/templates/work-phase.md +3 -0
- package/template/docs/plans/AGENTS.md +1 -1
- package/template/docs/plans/CLAUDE.md +1 -1
- package/template/docs/work/AGENTS.md +1 -0
- package/template/docs/work/CLAUDE.md +1 -0
- package/dist/chunk-5WR4D6HH.js.map +0 -1
- package/dist/chunk-B6HJRHWL.js.map +0 -1
- package/dist/chunk-C67WJWVP.js.map +0 -1
- package/dist/chunk-YJLVHT4J.js.map +0 -1
- package/dist/skills-command-YXPOHXI2.js.map +0 -1
- package/dist/virtual_make-docs-first-party-skills-POWW3OI3.js +0 -11
- package/dist/virtual_make-docs-first-party-skills-POWW3OI3.js.map +0 -1
- /package/dist/{backup-M5RBOM6F.js.map → backup-EBZZZL74.js.map} +0 -0
- /package/dist/{chunk-Z4KZ4JTE.js.map → chunk-2Z7KRD4H.js.map} +0 -0
- /package/dist/{chunk-O27AYYF3.js.map → chunk-ABKEBYCF.js.map} +0 -0
- /package/dist/{chunk-65TAUWTC.js.map → chunk-HZ4QLB7L.js.map} +0 -0
- /package/dist/{chunk-7AVGITZK.js.map → chunk-MESLJI5A.js.map} +0 -0
- /package/dist/{chunk-3ZFX5456.js.map → chunk-VCC4D5I3.js.map} +0 -0
- /package/dist/{registry-7L26WFZP.js.map → registry-XNCQALXP.js.map} +0 -0
- /package/dist/{self-4HOKEXBV.js.map → self-LDLIIKFW.js.map} +0 -0
- /package/dist/{setup-system-CJESBAQ5.js.map → setup-system-2MZMQ3MX.js.map} +0 -0
- /package/dist/{uninstall-R2QK7XPK.js.map → uninstall-EJF6HCYI.js.map} +0 -0
package/package.json
CHANGED
|
@@ -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
|
|
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
|
-
|
|
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,
|
|
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.
|
|
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
|
|
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
|
|
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
|
-
|
|
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
|
|
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
|
-
-
|
|
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
|
|
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
|
-
-
|
|
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
|
|
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
|
|
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
|
|
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
|
|
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
|
|
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
|
|
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
|
-
-
|
|
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
|
|
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
|
|
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
|
|
121
|
-
- Every
|
|
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
|
|
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 |
|
|
14
|
-
| `r{R}` | Revision |
|
|
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
|
-
##
|
|
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
|
-
|
|
98
|
+
### Recording The Decision
|
|
37
99
|
|
|
38
|
-
|
|
39
|
-
|
|
40
|
-
|
|
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
|
-
|
|
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:
|
|
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:
|
|
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
|
-
-
|
|
123
|
-
- `
|
|
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,
|
|
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
|
|
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:
|
|
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:
|
|
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,
|
|
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,
|
|
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 -->
|