@llipe.com/dev-tasks 0.16.2 → 0.17.0

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 (115) hide show
  1. package/.claude/agents/developer.md +8 -3
  2. package/.claude/agents/github-ops.md +187 -59
  3. package/.claude/agents/technical-writer.md +1 -1
  4. package/.claude/agents/verifier.md +10 -5
  5. package/.claude/commands/planner.md +110 -15
  6. package/.claude/commands/product-engineer.md +27 -3
  7. package/.claude/hooks/git-guard.sh +2 -2
  8. package/.claude/skills/activity-init/SKILL.md +4 -0
  9. package/.claude/skills/activity-publish-github/SKILL.md +84 -15
  10. package/.claude/skills/git-ops/SKILL.md +6 -6
  11. package/.claude/skills/implement/SKILL.md +29 -13
  12. package/.claude/skills/memo-cli-usage/REFERENCE.md +1 -0
  13. package/.claude/skills/memo-cli-usage/SKILL.md +3 -1
  14. package/.claude/skills/plan/SKILL.md +6 -0
  15. package/.github/agents/developer.agent.md +8 -3
  16. package/.github/agents/github-ops.agent.md +182 -64
  17. package/.github/agents/planner.agent.md +123 -28
  18. package/.github/agents/product-engineer.agent.md +27 -3
  19. package/.github/agents/technical-writer.agent.md +1 -1
  20. package/.github/agents/verifier.agent.md +10 -5
  21. package/.github/instructions/implement.instructions.md +29 -13
  22. package/.github/instructions/plan.instructions.md +6 -0
  23. package/.github/skills/activity-init/SKILL.md +4 -0
  24. package/.github/skills/activity-publish-github/SKILL.md +84 -15
  25. package/.github/skills/git-ops/SKILL.md +6 -6
  26. package/.github/skills/memo-cli-usage/REFERENCE.md +1 -0
  27. package/.github/skills/memo-cli-usage/SKILL.md +3 -1
  28. package/.kiro/agents/developer.md +8 -3
  29. package/.kiro/agents/github-ops.md +182 -64
  30. package/.kiro/agents/planner.md +123 -28
  31. package/.kiro/agents/product-engineer.md +27 -3
  32. package/.kiro/agents/technical-writer.md +1 -1
  33. package/.kiro/agents/verifier.md +10 -5
  34. package/.kiro/skills/activity-init/SKILL.md +4 -0
  35. package/.kiro/skills/activity-publish-github/SKILL.md +84 -15
  36. package/.kiro/skills/git-ops/SKILL.md +6 -6
  37. package/.kiro/skills/memo-cli-usage/REFERENCE.md +1 -0
  38. package/.kiro/skills/memo-cli-usage/SKILL.md +3 -1
  39. package/.kiro/steering/implement.md +29 -13
  40. package/.kiro/steering/plan.md +6 -0
  41. package/CHANGELOG.md +42 -0
  42. package/README.md +79 -7
  43. package/TESTING.md +108 -30
  44. package/dist/bin/dev-tasks.d.ts +1 -1
  45. package/dist/bin/dev-tasks.js +126 -4
  46. package/dist/bin/dev-tasks.js.map +1 -1
  47. package/dist/bin/parse-args.d.ts +49 -1
  48. package/dist/bin/parse-args.d.ts.map +1 -1
  49. package/dist/bin/parse-args.js +132 -11
  50. package/dist/bin/parse-args.js.map +1 -1
  51. package/dist/core/checks/decision-log-format.d.ts +24 -3
  52. package/dist/core/checks/decision-log-format.d.ts.map +1 -1
  53. package/dist/core/checks/decision-log-format.js +43 -3
  54. package/dist/core/checks/decision-log-format.js.map +1 -1
  55. package/dist/core/checks/index.d.ts +2 -0
  56. package/dist/core/checks/index.d.ts.map +1 -1
  57. package/dist/core/checks/index.js +1 -0
  58. package/dist/core/checks/index.js.map +1 -1
  59. package/dist/core/checks/roadmap.d.ts +40 -0
  60. package/dist/core/checks/roadmap.d.ts.map +1 -0
  61. package/dist/core/checks/roadmap.js +78 -0
  62. package/dist/core/checks/roadmap.js.map +1 -0
  63. package/dist/core/migrate-projects/answers.d.ts +63 -0
  64. package/dist/core/migrate-projects/answers.d.ts.map +1 -0
  65. package/dist/core/migrate-projects/answers.js +79 -0
  66. package/dist/core/migrate-projects/answers.js.map +1 -0
  67. package/dist/core/migrate-projects/apply.d.ts +51 -0
  68. package/dist/core/migrate-projects/apply.d.ts.map +1 -0
  69. package/dist/core/migrate-projects/apply.js +828 -0
  70. package/dist/core/migrate-projects/apply.js.map +1 -0
  71. package/dist/core/migrate-projects/classify.d.ts +93 -0
  72. package/dist/core/migrate-projects/classify.d.ts.map +1 -0
  73. package/dist/core/migrate-projects/classify.js +170 -0
  74. package/dist/core/migrate-projects/classify.js.map +1 -0
  75. package/dist/core/migrate-projects/conventions.d.ts +118 -0
  76. package/dist/core/migrate-projects/conventions.d.ts.map +1 -0
  77. package/dist/core/migrate-projects/conventions.js +213 -0
  78. package/dist/core/migrate-projects/conventions.js.map +1 -0
  79. package/dist/core/migrate-projects/gh.d.ts +40 -0
  80. package/dist/core/migrate-projects/gh.d.ts.map +1 -0
  81. package/dist/core/migrate-projects/gh.js +115 -0
  82. package/dist/core/migrate-projects/gh.js.map +1 -0
  83. package/dist/core/migrate-projects/index.d.ts +61 -0
  84. package/dist/core/migrate-projects/index.d.ts.map +1 -0
  85. package/dist/core/migrate-projects/index.js +183 -0
  86. package/dist/core/migrate-projects/index.js.map +1 -0
  87. package/dist/core/migrate-projects/local-reader.d.ts +8 -0
  88. package/dist/core/migrate-projects/local-reader.d.ts.map +1 -0
  89. package/dist/core/migrate-projects/local-reader.js +30 -0
  90. package/dist/core/migrate-projects/local-reader.js.map +1 -0
  91. package/dist/core/migrate-projects/map.d.ts +36 -0
  92. package/dist/core/migrate-projects/map.d.ts.map +1 -0
  93. package/dist/core/migrate-projects/map.js +75 -0
  94. package/dist/core/migrate-projects/map.js.map +1 -0
  95. package/dist/core/migrate-projects/plan.d.ts +71 -0
  96. package/dist/core/migrate-projects/plan.d.ts.map +1 -0
  97. package/dist/core/migrate-projects/plan.js +638 -0
  98. package/dist/core/migrate-projects/plan.js.map +1 -0
  99. package/dist/core/migrate-projects/planfile.d.ts +149 -0
  100. package/dist/core/migrate-projects/planfile.d.ts.map +1 -0
  101. package/dist/core/migrate-projects/planfile.js +608 -0
  102. package/dist/core/migrate-projects/planfile.js.map +1 -0
  103. package/dist/core/migrate-projects/roadmap.d.ts +43 -0
  104. package/dist/core/migrate-projects/roadmap.d.ts.map +1 -0
  105. package/dist/core/migrate-projects/roadmap.js +54 -0
  106. package/dist/core/migrate-projects/roadmap.js.map +1 -0
  107. package/dist/core/migrate-projects/snapshot.d.ts +91 -0
  108. package/dist/core/migrate-projects/snapshot.d.ts.map +1 -0
  109. package/dist/core/migrate-projects/snapshot.js +285 -0
  110. package/dist/core/migrate-projects/snapshot.js.map +1 -0
  111. package/dist/core/migrate-projects/summary.d.ts +27 -0
  112. package/dist/core/migrate-projects/summary.d.ts.map +1 -0
  113. package/dist/core/migrate-projects/summary.js +35 -0
  114. package/dist/core/migrate-projects/summary.js.map +1 -0
  115. package/package.json +8 -6
@@ -132,6 +132,24 @@ Map milestone issues into the same internal story model used by Option A.
132
132
 
133
133
  Read `docs/roadmap.md` (the roadmap overview — see **Roadmap Maintenance** below). Identify the PRD and the phase/wave row this run delivers, and state it when confirming the source. If the file is missing, or no row matches this run's scope, say so and ask `product-engineer` (or the user) to add the row before Phase 4; do not invent a row's scope yourself.
134
134
 
135
+ ### Wave Issue Resolution
136
+
137
+ Resolve the wave tracking issue once per run, after the roadmap read, and record it in the state file's Run Info as `Wave issue: #N | none`; every later story reads it from there (D-59). Resolve in this order:
138
+
139
+ 1. **Plan header.** Read the task plan's `Wave issue:` line, the line after `Source:` that `plan` writes. `Wave issue: #N` resolves the wave issue.
140
+ 2. **Search.** When the header line is absent or reads `Wave issue: none`, find the wave issue by its `level: wave` label and its `[PRD-<name>] Wave <id>:` title prefix, filtered client-side with `startswith` (D-36), taking `<name>` and `<id>` from the roadmap row: `gh issue list --label "level: wave" --search "[PRD-<name>] Wave <id>: in:title" --state open --json number,title --jq 'map(select(.title | startswith("[PRD-<name>] Wave <id>:")))'`.
141
+ - Exactly one match: reuse that issue number. When the header said `Wave issue: none`, the search result wins: record it in Run Info and note in the Decisions Log that the search, not the header, resolved it.
142
+ - More than one match: stop, list the matching issue numbers, and ask the user which one is the wave issue; never pick one silently.
143
+ 3. **Skip.** When neither the header nor the search yields one, record `Wave issue: none` and report `wave_status: skipped(no wave issue)` in the run summary; the run continues without a wave issue.
144
+
145
+ ### PRD Issue Resolution
146
+
147
+ Resolve the PRD tracking issue right after the wave issue, and record it in the state file's Run Info as `PRD issue: #N | none`; the PRD status comment (see **PRD Status Comment** in Phase 4) reads it from there (D-69). Resolve in this order:
148
+
149
+ 1. **Wave parent.** When a wave issue is known, read its parent: `gh api repos/{o}/{r}/issues/{wave}/parent --jq .number`. The number returned is the PRD issue.
150
+ 2. **Search.** When Run Info reads `Wave issue: none`, or the parent read returns `404` because the wave issue has no parent, find the PRD issue by its `level: prd` label and its `[PRD-<name>]` title prefix, filtered client-side with `startswith` as `activity-publish-github` does, taking `<name>` from the roadmap row: `gh issue list --label "level: prd" --search "[PRD-<name>] in:title" --state open --json number,title --jq 'map(select(.title | startswith("[PRD-<name>]")))'`. Exactly one match: reuse it; more than one: stop, list the matching issue numbers, and ask the user which one is the PRD issue.
151
+ 3. **Skip.** When neither yields one, record `PRD issue: none`; every PRD status comment write then reports `prd_status: skipped(no PRD issue)`, and the run continues.
152
+
135
153
  Confirm source and story count before Phase 0.5.
136
154
 
137
155
  ---
@@ -144,9 +162,13 @@ Before parsing stories, check for an existing checkpoint state file.
144
162
  2. If a state file exists:
145
163
  - Read it and display the story status table.
146
164
  - Identify the next pending story from the `Current Position` section.
165
+ - If every story reads `✅ Merged` and the user reports the consolidated PR merged, do not ask to resume: run Phase 6 with the PR number the user names.
147
166
  - Ask: **"Resume from story [next-story-id]? (y/n)"**
148
167
  - If confirmed: skip Phases 1-3, load the integration branch and execution plan from the state file, and resume Phase 4 from the next pending story.
149
- - If declined: archive the old state file (rename with `-archived` suffix) and proceed with a fresh run from Phase 1.
168
+ - On resume, read the wave issue from Run Info's `Wave issue` line and reuse it; do not resolve it again. A state file written before that line existed has none: resolve the wave issue as Phase 0's **Wave Issue Resolution** does and add the line.
169
+ - On resume, read the PRD issue from Run Info's `PRD issue` line the same way; a state file without that line resolves it as Phase 0's **PRD Issue Resolution** does and gains the line.
170
+ - On resume, edit the wave status comment in place (see **Wave Status Comment** in Phase 4); never create a second one.
171
+ - If declined: move the old state file to `workstream/archive/planner-state-<plan-id>-archived.md`, the same path Phase 6 uses (`git mv` when the file is tracked, `mv` when it is not), and proceed with a fresh run from Phase 1.
150
172
  3. If no state file exists, proceed to Phase 1 normally.
151
173
 
152
174
  ### State File Format
@@ -161,8 +183,10 @@ Path: `/workstream/planner-state-<plan-id>.md`
161
183
  - Task source: <path or milestone>
162
184
  - Integration branch: <branch-name>
163
185
  - Repository: <owner/repo>
186
+ - Wave issue: #N | none
164
187
  - Started: <timestamp>
165
188
  - Last updated: <timestamp>
189
+ - PRD issue: #N | none
166
190
 
167
191
  ## Story Status
168
192
 
@@ -181,6 +205,8 @@ Path: `/workstream/planner-state-<plan-id>.md`
181
205
  ## Decisions Log
182
206
 
183
207
  - <any decisions made during the run>
208
+ - wave_status: skipped(no wave issue) | failed(<reason>) at <event>
209
+ - prd_status: written | failed(<reason>) | skipped(no PRD issue) at <event>
184
210
  ```
185
211
 
186
212
  ---
@@ -311,6 +337,12 @@ integration/<plan-id>-<short-description>
311
337
 
312
338
  Per-story branches and PRs are created by `developer` following `github-ops` conventions.
313
339
 
340
+ Run start: once the integration branch is pushed, create the wave status comment (see **Wave Status Comment** in Phase 4) with every story `pending`. Not earlier: a plan declined at Phase 2 leaves no comment behind, and `Integration HEAD` already has a value (D-70).
341
+
342
+ In the same step, edit the PRD status comment so this wave's row reads `in progress` (see **PRD Status Comment** in Phase 4), creating it when no comment carries the marker.
343
+
344
+ Then set the wave issue body's `Integration branch:` line to the pushed branch name: read the body with `gh issue view <wave> --json body --jq .body` into a file, change only that line, and write it back with `gh issue edit <wave> --body-file <path>`. With `Wave issue: none` there is no body to edit.
345
+
314
346
  ---
315
347
 
316
348
  ## Phase 4 - Delegate to developer
@@ -335,6 +367,8 @@ For each story invoke `developer` in **Execute Mode** with:
335
367
  - Test plan reference (if available): path to `/workstream/test-plan-*.md` for this story
336
368
  - Decision log (`decision_log_path`): `workstream/decisions-<feature>.md`, passed unconditionally for every story — every feature has exactly one decision log, whether or not this story's spec section cited a decision
337
369
 
370
+ Edit the wave status comment at story start, before each handoff, and at developer closeout, once the closeout payload validates (see **Wave Status Comment**); merge gate 10 checks that the closeout edit was made before the story merges (D-71).
371
+
338
372
  ### Verifier Design Mode (Pre-Implementation)
339
373
 
340
374
  Before delegating the first story, planner **SHOULD** check for existing `verifier` Design Mode test plans in `/workstream/test-plan-*.md`. If no test plan exists for the current scope:
@@ -357,6 +391,7 @@ GitHub Issue: #{{ story.issue_number }}
357
391
  Task list path: {{ story.task_file }}
358
392
  Execution mode: pre-approved autonomous sequential
359
393
  Integration target branch: {{ integration_branch }}
394
+ Wave issue: {{ wave_issue }} (`#N` or `none`, from the state file's Run Info; under the planner the wave status comment is the planner's, so report `wave_status: owned-by-planner`)
360
395
  Test-first: YES — write/update tests before implementation for each behavioral sub-task
361
396
  Test plan: {{ test_plan_path | default: "none — derive tests from acceptance criteria" }}
362
397
  Decision log: {{ decision_log_path }}
@@ -438,6 +473,36 @@ If the payload is missing or incomplete:
438
473
  1. Retry once with a narrow follow-up asking the developer to return only the missing closeout payload.
439
474
  2. If the retry still omits the payload, mark the story incomplete, write the checkpoint as blocked on missing closeout payload, and ask the user whether to continue.
440
475
 
476
+ ### Wave Status Comment
477
+
478
+ The wave issue's status comment belongs to the planner. It is one comment, found by its marker and created or edited in place with implement § Status Comment's find-by-marker, create and PATCH procedure, in the shape of github-ops § Status comment's wave table; the table, its summary lines and its states are defined there and not restated here (D-33). It replaces the comment the planner once posted after every merge (D-53). Each write rebuilds the comment from the state file, with one row per story in sequence order.
479
+
480
+ Write it at these events, in this order across a run:
481
+
482
+ 1. **Run start** — Phase 3, once the integration branch is pushed: create it when no comment carries the marker; every story reads `pending`.
483
+ 2. **Resume** — Phase 0.5: find it by the marker and edit it; never create a second one.
484
+ 3. **Story start** — before each developer handoff: `Current story` names the story, which reads `in progress (sub-task n of m)`, with `n` the sub-tasks already checked in the task list and `m` their total.
485
+ 4. **Developer closeout** — once the closeout payload passes the Story completion rule's validation, before merge gate 1: the story reads `PR open` with its story PR, and `Gates` carries the payload's quality gates. This edit is never folded into the merge edit; merge gate 10 checks that it was made (D-71).
486
+ 5. **Merge** — merge rule step 13, after the checkpoint push: the story reads `merged into integration`; `Last merged PR` and `Integration HEAD` come from the pushed integration branch.
487
+ 6. **Block** — whenever a story is marked blocked: the story reads `blocked`, with the reason in the update line.
488
+ 7. **Rollup** — Phase 5 step 3: the rollup audit's human-readable summary goes in this comment.
489
+ 8. **Consolidated PR open** — Phase 5 step 7: the update line names the consolidated PR.
490
+ 9. **Close-out** — Phase 6's **Status comments** step, once the merge is verified: the update line says the wave shipped.
491
+
492
+ When Run Info reads `Wave issue: none`, every write is skipped and reports `wave_status: skipped(no wave issue)`. A refused create or PATCH (permissions, a locked issue, a network error) reports `wave_status: failed(<reason>)`; two comments carrying the marker are handled as implement § Status Comment says, editing the oldest and reporting `failed(duplicate marker)`. Every skipped or failed value goes to the state file's Decisions Log and to the run summary. A wave status comment write never blocks a merge gate, a story, or the consolidated PR handoff, with one exception: merge gate 10 holds the merge until the developer-closeout edit has been made, and a closeout edit that reported `failed(<reason>)` or `skipped(no wave issue)` satisfies it (D-71).
493
+
494
+ ### PRD Status Comment
495
+
496
+ The PRD issue's status comment is the PRD-level summary: one row per wave, with its state and its wave issue, in the shape of github-ops § Status comment's PRD table; the table and its states are defined there and not restated here (D-33). The wave status comment carries the detail. It is found by its marker and created or edited in place with implement § Status Comment's find-by-marker, create and PATCH procedure. `activity-publish-github` writes the wave's row at publish as `published`; the planner edits only this run's wave row, keeps every other row as it is, and edits an existing row in place, never adding a second one. A wave that predates the tracking-issue hierarchy keeps its row, with `—` for its wave issue (D-73). The PRD issue comes from Run Info's `PRD issue` line (see **PRD Issue Resolution** in Phase 0); when a state file written before that line existed has none, resolve it as that section does.
497
+
498
+ Write it at these events, in this order across a run:
499
+
500
+ 1. **Run start** — Phase 3, once the integration branch is pushed, beside the wave status comment: this run's wave reads `in progress`; the comment is created when no comment carries the marker.
501
+ 2. **Consolidated PR open** — Phase 5 step 7, once the PR is open: the wave reads `consolidated PR #n open`, with `n` the consolidated PR's number.
502
+ 3. **Close-out** — Phase 6's **Status comments** step, once the merge is verified: the wave reads `shipped`.
503
+
504
+ Each write reports `prd_status: written | failed(<reason>) | skipped(no PRD issue)`: `skipped(no PRD issue)` when Run Info reads `PRD issue: none`, `failed(<reason>)` for a refused create or PATCH, and `failed(duplicate marker)` when two comments carry the marker, handled as implement § Status Comment says. Every value, `written` included, goes to the state file's Decisions Log with its event and to the run summary; at close-out the state file is already archived, so the value goes to the run summary and the close-out PR body. A PRD status comment write never blocks a merge gate, a story, the consolidated PR handoff or the close-out PR.
505
+
441
506
  ### Merge management rule (planner-owned)
442
507
 
443
508
  Planner **MUST** manage merges for every completed story in sequence before delegating the next story.
@@ -453,15 +518,17 @@ For each completed story PR:
453
518
  7. For migration-bearing stories, verify explicit user confirmation was recorded before migration apply.
454
519
  8. Verify branch is up to date with integration branch (update/rebase if required by policy). Use the `git-ops` skill for rebase and conflict resolution.
455
520
  9. Detect merge conflicts before attempting merge. If conflicts are found, invoke the `git-ops` skill to resolve them.
456
- 10. **Review the PR** — planner **MUST** review the story PR (verify scope, files, test and quality-gate results) and approve it.
457
- 11. Merge PR into integration branch using one consistent strategy (default: `squash`).
521
+ 10. **Review the PR** — planner **MUST** review the story PR (verify scope, files, test and quality-gate results) and approve it. Then confirm the developer-closeout edit (see **Wave Status Comment**, event 4): re-read the wave status comment by its marker and require this story's row to read `PR open` with this story PR. When it does not, make the closeout edit now and re-read it. Merge only once the row reads `PR open`, or once the closeout edit reported `failed(<reason>)` or `skipped(no wave issue)` and that value is in the Decisions Log (D-71). A refused re-read satisfies the gate the same way: record `wave_status: failed(<reason>) at merge gate 10` and continue, so a read error never stops the run.
522
+ 11. Merge PR into integration branch using one consistent strategy (default: `merge`, a merge commit with source-branch deletion; never squash or rebase unless the user explicitly asks for it).
458
523
  12. Confirm integration branch is green after merge before moving to next story.
459
- 13. **Write checkpoint** — update the planner state file (see Phase 0.5 State File Format), mark the completed story as `✅ Merged` with its PR link and branch name, update `Current Position` to the next pending story, update the `Last updated` timestamp, and post a GitHub Issue comment on the plan/milestone issue with the current story status table.
524
+ 13. **Write checkpoint** — update the planner state file (see Phase 0.5 State File Format), mark the completed story as `✅ Merged` with its PR link and branch name, update `Current Position` to the next pending story, and update the `Last updated` timestamp. Then commit the checkpoint in the same step: `git add -f workstream/planner-state-<plan-id>.md` (forced, so a repository that ignores `workstream/` still commits it). When `git diff --cached --quiet` reports nothing staged, as when a resumed run rewrites an unchanged file, skip the commit and record `checkpoint: unchanged` in the Decisions Log; otherwise commit it on the integration branch with the message `chore(planner): checkpoint after <story> merge`. Push the integration branch in either case, so a checkpoint committed earlier but never pushed still reaches the remote. If the push is rejected, report the rejection verbatim, retry the push once, and mark the story blocked if it is rejected again; a push blocked by a hook is a decision and is never retried. After the push, edit the wave status comment (see **Wave Status Comment**): this story reads `merged into integration`, with `Last merged PR` and `Integration HEAD` taken from the pushed integration branch.
460
525
 
461
526
  If any merge gate fails, stop and report exact blocker and PR link.
462
527
 
463
528
  Planner **MUST NOT** allow multiple open story PRs to merge concurrently.
464
529
 
530
+ The planner never closes a story issue or the wave issue, and neither does any agent it delegates to. Each one closes when the consolidated PR merges to main, through the `Closes` line that PR carries (Phase 5 step 7); a story PR into the integration branch closes nothing, because GitHub honours closing keywords only on a PR whose base is the default branch (D-22, D-50, D-54).
531
+
465
532
  ### Merge authority policy
466
533
 
467
534
  | Target Branch | Reviewer & Approver | Who Merges |
@@ -481,13 +548,16 @@ After all stories are merged into integration:
481
548
 
482
549
  1. Run full integration test suite on integration branch.
483
550
  2. Invoke `qa-engineer` at **PRD scope** (all packages affected by the merged stories, all layers) for a coverage and gap rollup. Report a PRD-level `coverage_gate` that aggregates per-story gates. Scope to packages affected by the merged stories, not the entire workspace.
484
- 3. Invoke `verifier` in `audit` mode for a **PRD-level rollup audit** against the full integrated scope (all merged stories on the integration branch, cross-checked against the source PRD/spec/milestone). This is mandatory and non-skippable — it runs whether or not any story-level drift was previously reported. Post the resulting human-readable summary to the plan/milestone issue via `github-ops` comment conventions. Rollup drift findings **MUST NOT** block the consolidated PR handoff; Unintended/Intended drift routes to `product-engineer`'s `activity-drift-reconciliation` flow.
551
+ 3. Invoke `verifier` in `audit` mode for a **PRD-level rollup audit** against the full integrated scope (all merged stories on the integration branch, cross-checked against the source PRD/spec/milestone). Pass Run Info's `Wave issue: #N` line (or `Wave issue: none`) in the handoff, so the audit's Roadmap-Mismatch comparison uses that wave issue instead of searching for it. This is mandatory and non-skippable — it runs whether or not any story-level drift was previously reported. Record the resulting human-readable summary in the wave status comment, edited in place (see **Wave Status Comment**), never as a new comment; with no wave issue, carry it in the consolidated PR body. Rollup drift findings **MUST NOT** block the consolidated PR handoff; Unintended/Intended drift routes to `product-engineer`'s `activity-drift-reconciliation` flow.
552
+ - **Fidelity report line.** Once the rollup audit has written its fidelity report, set the wave issue body's `Fidelity report:` line under `## Artifacts` to a root-relative link to that report, adding the line after `Task plan:` when the body has none: read the body with `gh issue view <wave> --json body --jq .body` into a file, change only that line, and write it back with `gh issue edit <wave> --body-file <path>`. With `Wave issue: none` there is no body to edit. When no report file exists, the line's value stays `pending`: an existing `Fidelity report: pending` line is left as it is, and a body without the line gets it added after `Task plan:`.
485
553
  4. Invoke `technical-writer` for a planner-level drift/stale-doc validation pass against integrated changes; unresolved drift **MUST** block handoff.
486
- 5. **Roadmap update (mandatory).** Update the run's row(s) in `docs/roadmap.md` on the integration branch, so the change ships in the consolidated PR itself: set `Status` (`Done` when every story in the phase/wave merged, otherwise `In progress`), fill `Issues/PRs` with the story issues and the consolidated PR, rewrite `What's missing` to the remaining scope (`—` when none), and set the `Last updated` date. A consolidated PR without this roadmap change is incomplete. See **Roadmap Maintenance** below.
554
+ 5. **Roadmap update (mandatory).** Update the run's row(s) in `docs/roadmap.md` on the integration branch, so the change ships in the consolidated PR itself, deriving every cell from `gh` output, never from memory: set `Status` to `In progress`, because only Phase 6 sets `Done`, after the merge; build `Issues/PRs` from the wave issue, its story issues and their states, read with `gh api --paginate repos/{o}/{r}/issues/{wave}/sub_issues --jq '.[] | {number,state}'` (when Run Info reads `Wave issue: none`, fall back to `gh issue list --search "[PRD-<name>] in:title" --state all --limit 500 --json number,state` and keep only the issues in the state table, since the title search also returns the PRD issue and other waves' stories), and the story PRs, read with `gh pr list --base <integration branch> --state merged --limit 500 --json number`; write `What's missing` as "consolidated PR to `main`", followed by any story that did not merge; and set the `Last updated` date. Quote every command you ran verbatim in the consolidated PR body's Roadmap section, so a reviewer can re-run it. A consolidated PR without this roadmap change is incomplete. See **Roadmap Maintenance** below.
487
555
  6. **memo run outcome.** Write the per-run outcome entry described in **memo-cli Integration → Responsibilities** and record `memo_run_outcome`.
488
- 7. Open one consolidated PR from integration branch to `main`.
556
+ 7. Open one consolidated PR from integration branch to `main`. Then edit the wave status comment so its update line names the consolidated PR, and edit the PRD status comment so this wave's row reads `consolidated PR #n open` (see **PRD Status Comment**).
557
+ - **Closes lines.** Generate them from the state table and write them under the PR body's `## Why`, as github-ops's PR template names it: `Closes #N` for every story whose state-table row is `✅ Merged`; `Refs #N` with the reason for every story that is not merged (blocked or skipped), never `Closes`; `Closes #<wave>` for the wave issue only when every story in the state table merged, otherwise `Refs #<wave>` naming the unmerged stories. When Run Info reads `Wave issue: none` there is no `Closes #<wave>` line, and the body says no wave issue was found. Write one keyword per issue, each on its own line: a comma list such as `Closes #1, #2` closes only the first issue. A follow-up issue listed on the task plan's `Resolves:` header line gets `Closes #N` as well, so GitHub closes it at the merge as it does the stories (D-74). Every other reference (the PRD issue, related issues) is `Refs #N`.
558
+ - **Project Status observation (read only).** Once the PR is open, read one merged story's Project Status with `gh issue view <n> --json projectItems --jq '.projectItems[].status.name'`; the same read tells whether a Project tracks the issue, so no Project number is needed, and nothing is ever written to the Project. The read works only with the token's `read:project` scope, which the `project` scope includes and a default `gh` login lacks (RD-6). An empty result means no Project: `not observed(no project)`. `In progress` records `observed`. Any other value (`Backlog` while GitHub's automation catches up) is re-read once after a short wait and then recorded as `not observed(automation pending at <time>)`; a refused read records `not observed(<reason>)`, `not observed(missing read:project scope)` when the token lacks that scope, and never asks for more access. Record the result as `project_observation: observed | not observed(<reason>)` for "In progress at consolidated PR open" in the PR body and in `TESTING.md`'s DF-5 row, committed on the integration branch so the open PR picks it up.
489
559
  8. **Do NOT merge.** Notify the user that the consolidated PR is ready for their review.
490
- 9. Wait for the user to approve and merge the PR into `main`.
560
+ 9. Wait for the user to approve and merge the PR into `main`, then run Phase 6 when the user reports the merge; the run is not complete until Phase 6 has run.
491
561
  10. **Post-integration deploy handoff (conditional).** When the merged scope includes deployable changes and the repository declares environments in `infra/environments.yaml`, planner **MUST** hand the deploy off to `infra-engineer` rather than running any platform write or deploy command itself. This handoff is conditional — it applies only when infrastructure/deploy scope is present; a docs- or test-only integration triggers no deploy. Planner names `infra-engineer` as the owner of the post-integration deploy (dev on merge to `main`, production behind the protected-environment reviewer on the release tag via the `deploy-ops` workflow templates) and never invokes `deploy.sh`, `release.sh`, `flyctl`, `aws`, or `supabase` directly.
492
562
  11. Before final handoff, **MUST** ensure the local working branch is the integration branch used for this run:
493
563
 
@@ -499,7 +569,7 @@ After all stories are merged into integration:
499
569
  - consolidated PR URL
500
570
  - current CI/check status
501
571
  - exact required user actions: review, approve, and merge
502
- - a post-merge follow-up action (for example, delete integration branch or run a verification command)
572
+ - a post-merge follow-up action: report the merge to the planner, in this session or a fresh one on `main`, naming the consolidated PR number and the plan id, so it runs Phase 6
503
573
 
504
574
  Consolidated PR should include:
505
575
 
@@ -508,8 +578,10 @@ Consolidated PR should include:
508
578
  - Per-story changed files and test results
509
579
  - Manual validation instructions per story
510
580
  - Integration test summary
511
- - Roadmap row(s) updated in `docs/roadmap.md` (before → after status)
581
+ - Roadmap row(s) updated in `docs/roadmap.md` (before → after status), with the `gh` commands that derived them quoted verbatim (step 5)
512
582
  - Memo coverage: per-story `memo_intent` / `memo_outcome` values and `memo_run_outcome`
583
+ - `Closes #N` for every merged story and `Closes #<wave>` when every story merged, `Refs` for the rest, one per line under `## Why`, generated from the state table (step 7)
584
+ - `project_observation` for In progress at consolidated PR open (step 7)
513
585
 
514
586
  PR title **MUST** follow Conventional Commits and PR body **MUST** follow `github-ops` conventions.
515
587
 
@@ -517,33 +589,52 @@ Planner **MUST NOT** merge the consolidated PR. Only the user may approve and me
517
589
 
518
590
  ---
519
591
 
592
+ ## Phase 6 - Close-out
593
+
594
+ Run this phase when the user reports that the consolidated PR merged into `main`. It may start in any session, including a fresh one on `main`, which is recommended so the merged planner prompt drives it: the user names the merged consolidated PR number `<n>` and the plan id, and the planner reads `workstream/planner-state-<plan-id>.md`, which the checkpoint commits carried into `main`. Steps 1 to 5 only read. Steps 6 to 9 and 11 change files and commit them on the close-out branch only; step 10 edits GitHub comments through the API, which touches no branch; step 12 deletes the integration branch last. Phase 6 never merges anything and never pushes to `main`.
595
+
596
+ 1. **Verify the merge.** Run `gh pr view <n> --json state,mergedAt` and require `state` to be `MERGED` and `mergedAt` to be non-null. Anything else (`OPEN`, `CLOSED` without a merge, an error) means stop: report the exact output, write nothing, and wait for the user.
597
+ 2. **Pull main.** Check out `main` and pull it, so every read below and the close-out branch start from the merged state.
598
+ 3. **Confirm the issues closed.** Read the wave issue's story issues and their states with `gh api --paginate repos/{o}/{r}/issues/{wave}/sub_issues --jq '.[] | {number,state}'` and the wave issue's own state with `gh issue view <wave> --json state`; when Run Info reads `Wave issue: none`, read each story issue in the state table with `gh issue view <n> --json state`. Confirm that every story issue, the wave issue and every follow-up issue the consolidated PR carried under `Closes` reads closed: GitHub closed them through the consolidated PR's `Closes` lines, and the wave issue stays open by design when the PR carried `Refs #<wave>` because a story did not merge. A story or follow-up issue still open after the merge is reported in the run summary with its number and left for the user; Phase 6 never closes it by hand.
599
+ 4. **Read the story PRs.** Read the story PRs merged into the integration branch with `gh pr list --base <integration branch> --state merged --limit 500 --json number` now, while the integration branch still exists.
600
+ 5. **Read the Project Status (read only).** For every story issue and the wave issue, read `gh issue view <n> --json projectItems --jq '.projectItems[].status.name'` and confirm `Done`. An empty result means no Project tracks the issues and records `not observed(no project)`; any other value is re-read once after a short wait and then recorded as `not observed(automation pending at <time>)`; a refused read records `not observed(<reason>)`, `not observed(missing read:project scope)` when the token lacks that scope, and never asks for more access. The Project is read, never written. Record the result as `project_observation: observed | not observed(<reason>)` for "Done at consolidated PR merge".
601
+ 6. **Create the close-out branch.** From the pulled `main`, create `chore/<plan-id>-closeout`; every file change in steps 7 to 9 is committed on this branch, never on `main`.
602
+ 7. **Roadmap row.** In `docs/roadmap.md`, set the run's row from what steps 1 to 4 observed, never from memory. When every story in the state table reads `✅ Merged`, every story issue from step 3 reads closed and the wave issue, when there is one, reads closed, set `Status` to `Done` and `What's missing` to `—`; this is the completeness rule of the verifier's Roadmap-Mismatch trigger 1. Otherwise keep `Status` at `In progress`, list the unmerged stories and every story issue still open in `What's missing` (a merged story whose issue stayed open reads `#N open (missed Closes keyword)`), and say so in the close-out PR body; the run summary names each such issue as a `product-engineer` follow-up, and once it reads closed, `product-engineer` sets the row to `Done` at its session-start roadmap read (D-72). In both cases set `Issues/PRs` to the wave issue and the story issues from step 3, the story PRs from step 4 and the consolidated PR `#<n>`, and set the `Last updated` date. When the row is absent, leave `docs/roadmap.md` unchanged, report it, and ask the user to have `product-engineer` add the row; never invent one.
603
+ 8. **Archive the state file.** Move `workstream/planner-state-<plan-id>.md` to `workstream/archive/planner-state-<plan-id>-archived.md` with `git mv`, so the next run starts fresh; it is the same path Phase 0.5 uses for a declined resume.
604
+ 9. **Record the Done observation.** Write step 5's `project_observation` for "Done at consolidated PR merge" in `TESTING.md`'s DF-5 row.
605
+ 10. **Status comments.** Edit the PRD issue's status comment so the wave's row reads `shipped`, found by its marker and edited in place per implement § Status Comment (see **PRD Status Comment**), and record the resulting `prd_status` in the run summary and the close-out PR body, since step 8 already archived the state file; then edit the wave status comment so its update line says the wave shipped (see **Wave Status Comment**). A failed write is reported in the run summary and never blocks the close-out PR.
606
+ 11. **Open one `chore(roadmap)` PR to `main`.** Commit steps 7 to 9 on `chore/<plan-id>-closeout` with the message `chore(roadmap): close out <plan-id>`, push the branch, and open one PR to `main` with the same title, its body written to a file per github-ops's PR template, with `Refs #<wave>` under `## Why`. The planner never merges it: the user reviews and merges it.
607
+ 12. **Delete the integration branch, last.** Delete the integration branch locally and remotely only after the close-out PR is open: check out `main`, then `git branch -d <integration branch>` and `git push origin --delete <integration branch>`. A branch that is already gone, locally or on the remote (for example, removed by GitHub's automatic branch deletion), counts as deleted: report it and continue. Then report the run summary: each step's result, any issue still open, `project_observation`, and the close-out PR URL. The run is complete only after this step.
608
+
609
+ ---
610
+
520
611
  ## Roadmap Maintenance
521
612
 
522
613
  `docs/roadmap.md` is the one-page overview of every PRD's phases or waves: what is done, what is in progress, and what is missing. It is an index over the PRDs, GitHub issues, and merged PRs — when they disagree, they win and the roadmap is corrected.
523
614
 
524
615
  - **Read** it in Phase 0 (see **Roadmap Read**).
525
- - **Update** the run's row(s) in Phase 5 step 5, in the consolidated PR. Never leave the roadmap claiming `In progress` for a phase this run finished, or `Done` for one it did not.
616
+ - **Update** the run's row(s) twice, each time from `gh` output, never from memory: to `In progress` in Phase 5 step 5, in the consolidated PR, and again in Phase 6 step 7, in the `chore(roadmap)` PR, once the merge is verified: `Done` when every story in the state table reads `✅ Merged`, every story issue reads closed and the wave issue, when there is one, reads closed; otherwise keep `In progress` and list the unmerged stories and the open story issues in `What's missing` (D-72). Never leave the roadmap claiming `Done` for a phase whose consolidated PR has not merged or whose stories did not all merge.
526
617
  - Change only the rows this run touched; rows for other PRDs belong to `product-engineer` and to the planner runs that deliver them.
527
- - The `verifier` rollup audit (Phase 5 step 3) compares the roadmap against merged work and reports a mismatch as an advisory finding.
618
+ - The `verifier` rollup audit (Phase 5 step 3) compares the roadmap with the delivered work, as its Roadmap-Mismatch Finding describes, and reports a mismatch as an advisory finding.
528
619
 
529
620
  ---
530
621
 
531
622
  ## Error Handling
532
623
 
533
- | Situation | Action |
534
- | ---------------------------------- | ------------------------------------------------------------------------------------------ |
535
- | No `/workstream` task file | Ask for file path or milestone |
536
- | Multiple task files | Ask user to choose |
537
- | Milestone has no issues | Report and stop |
538
- | Circular dependencies | Report cycle and stop |
539
- | Story returns blocked | Mark blocked and ask whether to continue |
540
- | Story PR targets wrong base | Require retargeting to integration branch before merge |
541
- | Required checks pending/failing | Do not merge; report failing checks |
542
- | Story PR behind integration branch | Require update/rebase before merge |
543
- | Merge conflict | Invoke `git-ops` skill to resolve; if resolution fails, report conflicting files and pause |
544
- | Integration tests fail | Report failures and ask whether to proceed or fix first |
545
- | Consolidated PR creation fails | Return generated title/body and ask to retry |
546
- | Story payload base mismatch | Mark story blocked; require retargeting PR base to integration branch before merge |
624
+ | Situation | Action |
625
+ | ---------------------------------- | -------------------------------------------------------------------------------------------------------------------- |
626
+ | No `/workstream` task file | Ask for file path or milestone |
627
+ | Multiple task files | Ask user to choose |
628
+ | Milestone has no issues | Report and stop |
629
+ | Circular dependencies | Report cycle and stop |
630
+ | Story returns blocked | Mark blocked, edit the wave status comment so the story reads `blocked` with the reason, and ask whether to continue |
631
+ | Story PR targets wrong base | Require retargeting to integration branch before merge |
632
+ | Required checks pending/failing | Do not merge; report failing checks |
633
+ | Story PR behind integration branch | Require update/rebase before merge |
634
+ | Merge conflict | Invoke `git-ops` skill to resolve; if resolution fails, report conflicting files and pause |
635
+ | Integration tests fail | Report failures and ask whether to proceed or fix first |
636
+ | Consolidated PR creation fails | Return generated title/body and ask to retry |
637
+ | Story payload base mismatch | Mark story blocked; require retargeting PR base to integration branch before merge |
547
638
 
548
639
  ---
549
640
 
@@ -558,11 +649,12 @@ Planner **MUST NOT** merge the consolidated PR. Only the user may approve and me
558
649
  - Execution is strictly sequential, one story at a time.
559
650
  - Planner owns story PR merges into integration and enforces merge gates.
560
651
  - `developer` runs in Execute Mode for each story.
561
- - Planner **MUST** write a checkpoint state file after every story merge and post a GitHub comment with status.
652
+ - Planner **MUST**, after every story merge, write the checkpoint state file, commit the state file (force-added and pushed to the integration branch) and edit the wave status comment.
562
653
  - On restart, planner **MUST** check for existing state files and offer to resume (Phase 0.5).
563
654
  - All GitHub outputs are in English.
564
- - Final user-facing local branch state **MUST** be the integration branch for the current run, or planner **MUST** explicitly report verification failure and provide the exact checkout command.
655
+ - At the Phase 5 handoff, the final user-facing local branch state **MUST** be the integration branch for the current run, or planner **MUST** explicitly report verification failure and provide the exact checkout command. After Phase 6 deletes the integration branch, the final local branch is `main`, or the close-out branch until its PR is open.
565
656
  - Planner **MUST** end a successful run with explicit PR directives for the user (review/approve/merge) and **MUST NOT** mark the run complete before that handoff is emitted.
657
+ - The run is complete only after Phase 6 - Close-out: the merge is verified, the roadmap row is set as Phase 6 step 7 says (`Done` when every story in the state table reads `✅ Merged`, every story issue reads closed and the wave issue, when there is one, reads closed; otherwise keep `In progress` and list the unmerged stories and the open story issues in `What's missing`), the state file is archived, the `chore(roadmap)` PR is open and the integration branch is deleted.
566
658
  - Planner **MUST** verify `verifier_audit: run` in every story's closeout payload before merging that story's PR into the integration branch, and **MUST** invoke `verifier` in `audit` mode for a PRD-level rollup audit before/alongside the consolidated PR — both triggers are mandatory and non-skippable, and neither trigger's drift findings block the corresponding merge/handoff.
567
659
 
568
660
  ---
@@ -578,7 +670,10 @@ For each run, return:
578
670
  - Integration branch
579
671
  - Final local branch state (checked out branch name or explicit verification result)
580
672
  - Story PR links/status
673
+ - Wave status comment outcome (`wave_status` values recorded in the Decisions Log)
674
+ - PRD status comment outcome (`prd_status` values recorded in the Decisions Log)
581
675
  - Consolidated PR link or blocker
582
676
  - Current test status
583
677
  - PR Directives (User Action Required)
678
+ - Close-out (Phase 6): each step's result, any issue still open, `project_observation` and the `chore(roadmap)` PR link; the run is complete only after Phase 6
584
679
  - Next exact action awaiting approval or execution
@@ -70,7 +70,7 @@ If any required input is missing, you **MUST** ask concise clarifying questions.
70
70
  - **Add rows when a PRD is created or changed** (`activity-refine`): one row per delivery phase or wave the PRD defines, or a single `All` row when it defines none, each `Not started`. A PRD changelog that adds, removes, or re-scopes a phase updates its rows in the same change.
71
71
  - **Fill `Issues/PRs` when stories are published** (`activity-publish-github`), and set the row to `In progress` once its first story is being implemented.
72
72
  - **Correct it during drift reconciliation** (`activity-drift-reconciliation`) when a `verifier` roadmap-mismatch finding is confirmed.
73
- - Never mark a row `Done` yourself on the strength of a plan; `Done` requires merged work, and `planner` sets it in the consolidated PR that delivers it.
73
+ - Never mark a row `Done` yourself on the strength of a plan; `Done` requires merged work, and `planner` sets it in the consolidated PR that delivers it. The first exception is a row the planner's close-out left `In progress` with `#N open (missed Closes keyword)` in `What's missing`: at the session-start read, check each issue it names, and once every one reads closed, set the row to `Done` and `What's missing` to `—`, since the merge was already verified (planner D-72). The second exception is the roadmap conversion below, which writes `Done` only on merged evidence it confirmed on GitHub (D-104).
74
74
 
75
75
  Shape (one table, one row per PRD phase or wave, newest PRD first):
76
76
 
@@ -86,6 +86,29 @@ Last updated: YYYY-MM-DD
86
86
 
87
87
  `Status` is exactly one of `Not started`, `In progress`, `Done`.
88
88
 
89
+ ### Roadmap Conversion (before migration)
90
+
91
+ `dev-tasks migrate projects --plan` maps issues to waves through the canonical table in `docs/roadmap.md`: the six-column header of the shape above, its separator, then the rows, as `roadmap-parity.test.ts` checks it. Check for the table at the session-start read and whenever the user prepares a migration. A partial table, the canonical header with at least one row, already counts as canonical: skip the conversion and let migration read it. When `docs/roadmap.md` has no canonical table (a narrative roadmap), convert it before migration runs, in this order (FR-21, D-86):
92
+
93
+ 1. **Draft the canonical table** in the shape above: one row per PRD phase or wave, a one-line scope, `Status` from the fixed set, and `Issues/PRs` taken from the narrative. Two narrative sections that describe one wave give one row citing both.
94
+ 2. **Keep the existing narrative verbatim below the table**, never instead of it; the table is added above the narrative, which keeps its wording, diagrams and history.
95
+ 3. **Flag every translated Status for the user:** list each row whose `Status` was translated from narrative wording, with the original word, for the user to confirm or correct; for example, a narrative "paused" translates to `Not started` and is flagged. A Status without merged evidence is never upgraded to `Done` by the conversion; a `Done` row cites the merged PR or closed issue behind it. Before writing `Done`, confirm on GitHub that the cited PR merged or the issue closed (`gh pr view <n> --json state` / `gh issue view <n> --json state`); otherwise keep the translated Status and flag it (D-104).
96
+ 4. **Ship it as its own docs PR before migration runs:** the user approves the draft, and the conversion merges as its own docs PR before `dev-tasks migrate projects --plan` is run, never inside the migration's own PR.
97
+
98
+ Migration depends on this step: `dev-tasks migrate projects --plan` refuses to run without the canonical table, and it maps `phase: X` only to a row whose `Phase/Wave` cell equals `X` exactly, among the rows of the PRD named in the story's `[PRD-<name>]` title prefix (D-98). A label that matches no row is listed as unmapped for the user, never fuzzy-matched (D-86).
99
+
100
+ Migration edits no `workstream/planner-state-*.md` file: `--plan` lists each active state file that lacks a `Wave issue:` line as information, and the planner's resume adds the missing `Wave issue:` line (D-89; PRD AC-13 as amended by D-99).
101
+
102
+ ---
103
+
104
+ ## Drift Reconciliation
105
+
106
+ Drift findings from a mandatory `verifier` audit route through `activity-drift-reconciliation` (rule 9 below). When reconciling them, or when the owner asks what is left to fix or ship, aggregate standalone issues and follow-ups with these three queries; they read labels, body lines and native issue dependencies only, and no new label category exists for them (D-83):
107
+
108
+ - **Post-wave follow-ups:** issues whose body carries the `Follow-up to #N` line that `activity-drift-reconciliation` writes for a closed scope: `gh issue list --state open --search '"Follow-up to #<N>" in:body' --json number,title,labels --limit 1000`.
109
+ - **Bugs to fix:** `type: bug` without `level:`, so story and tracking issues never count: `gh issue list --state open --label "type: bug" --json number,title,labels --limit 1000 --jq 'map(select(all(.labels[]; .name | startswith("level:") | not)))'`.
110
+ - **Release blockers:** `priority: critical`, each naming what it blocks in its `**Blocks:**` line and its native `blocked by` relation (github-ops § Labels): `gh issue list --state open --label "priority: critical" --json number,title,body --limit 1000`.
111
+
89
112
  ---
90
113
 
91
114
  ## memo-cli Integration (When Available)
@@ -163,12 +186,13 @@ memo write \
163
186
  --entry-type decision \
164
187
  --story "<issue-or-feature-id-if-known>" \
165
188
  --files "workstream/decisions-<feature>.md" \
166
- --on-duplicate consolidate \
189
+ --on-duplicate create-new \
167
190
  --json
168
191
  ```
169
192
 
170
193
  - `--manual` is correct here: the decision was made by the user in conversation, so it has no episodic provenance, and memo-cli rejects an agent-sourced semantic entry without one.
171
- - A row that supersedes an earlier decision is written as a new entry naming the superseded ID in its rationale; `--on-duplicate consolidate` merges near-duplicates.
194
+ - A row that supersedes an earlier decision is written as a new entry naming the superseded ID in its rationale.
195
+ - Each distinct decision row is written with `--on-duplicate create-new`, one entry per row, so memo-cli never merges two decisions into one record; pass `consolidate` only when restating or updating the same decision (D-78: on 2026-10-20 `consolidate` merged 26 distinct decisions into one `kb` record).
172
196
  - **Write results are recorded, never swallowed.** Report the written ids (or `skipped(<reason>)`) in the phase's completion summary. On failure, fix the command if the error names a flag or value you supplied and retry once; then report `failed(<error>)`. A failed write never blocks the phase.
173
197
 
174
198
  `technical-writer` still owns ADR and doc-change entries, and `developer` owns per-story intent/outcome entries.
@@ -381,7 +381,7 @@ memo write \
381
381
  --commit "$(git rev-parse HEAD)" \
382
382
  --story "<issue-or-story-id-if-known>" \
383
383
  --files "<path/to/doc.md>,<path/to/adr.md>" \
384
- --on-duplicate consolidate \
384
+ --on-duplicate create-new \
385
385
  --json
386
386
  ```
387
387
 
@@ -249,12 +249,17 @@ new category. Never hold a PR on it.
249
249
 
250
250
  `docs/roadmap.md` is the one-page index of every PRD's phases or waves and their status. It goes stale silently unless something compares it with what actually merged, so that comparison lives here as a finding.
251
251
 
252
- **Trigger** (PRD-level rollup audits, and story audits whose story completes a phase or wave). Report the finding when any of these hold:
252
+ **Comparison target** (FR-16, D-57). When the wave has a tracking issue, compare the row with that wave issue and its sub-issues, the authoritative story list. Use the wave issue the caller names (the planner passes Run Info's `Wave issue: #N`); otherwise find it by its `level: wave` label and `[PRD-<name>] Wave <id>:` title prefix, filtered client-side with `startswith` (D-36): `gh issue list --label "level: wave" --search "[PRD-<name>] Wave <id>: in:title" --state all --json number,title,state --jq 'map(select(.title | startswith("[PRD-<name>] Wave <id>:")))'`. The search uses `--state all` because an audit can run after the wave ships and must still find a closed wave issue; publish and the planner's Phase 0 use `--state open` because they look for the active wave. Read the sub-issue numbers and states from `GET /repos/{o}/{r}/issues/{wave}/sub_issues`, paginated: `gh api --paginate repos/{o}/{r}/issues/{wave}/sub_issues --jq '.[] | {number,state}'`. Without a wave issue, the existing comparison stands: compare the row with the merged story PRs, read with `gh pr list --base <integration branch> --state merged --json number`. Name in the finding, or in its "no finding" line, the wave issue and the sub-issue states you read, or that you used the fallback.
253
253
 
254
- 1. The audited work completes a PRD phase or wave, and its roadmap row is not `Done` in the delivered tree.
255
- 2. A roadmap row is `Done`, but the audited scope shows that phase's stories unmerged or its acceptance criteria unmet.
256
- 3. The audited PRD defines a phase or wave with no roadmap row, or `docs/roadmap.md` is missing while `docs/requirements/` holds a PRD.
257
- 4. A row's `Issues/PRs` or `What's missing` contradicts the audited issues and PRs.
254
+ - When the search returns more than one wave issue, report the matching issue numbers in the finding and compare with neither; never pick one silently.
255
+ - When the wave issue has zero sub-issues, fall back to the merged story PRs and note in the finding that the wave issue had no sub-issues.
256
+
257
+ **Trigger** (PRD-level rollup audits, and story audits whose story completes a phase or wave). Report the finding when any of these is true:
258
+
259
+ 1. The audited work completes a PRD phase or wave, and its roadmap row is not `Done` in the delivered tree. With a wave issue, the wave is complete only when every sub-issue's `state` reads `closed` and the wave issue itself reads `closed`, as the planner's Phase 6 requires before it sets `Done`; without one, when every story PR has merged and every story issue reads `closed` (planner D-72).
260
+ 2. A roadmap row is `Done`, but the audited scope shows that phase's stories unmerged (with a wave issue, a sub-issue still `open`) or its acceptance criteria unmet.
261
+ 3. The audited PRD defines a phase or wave with no roadmap row, or `docs/roadmap.md` is missing while `docs/requirements/` contains a PRD.
262
+ 4. A row's `Issues/PRs` or `What's missing` contradicts the audited issues and PRs: with a wave issue, the sub-issue numbers and states read above (a sub-issue missing from `Issues/PRs`, or a closed one still named in `What's missing`); without one, the merged story PRs.
258
263
 
259
264
  **Not a finding:** rows for PRDs outside the audited scope; a row left `In progress` while some of its stories are still open.
260
265
 
@@ -118,10 +118,26 @@ When `workstream/decisions-<feature>.md` exists and was read per step 2 above:
118
118
  - If drift is detected between local and GitHub, you **MUST** reconcile immediately and report the reconciliation.
119
119
  - If schema/data-model changes are in scope, migration artifacts **MUST** be tracked in the task list unless an explicit opt-out rationale is documented.
120
120
 
121
- ### Progress Updates
122
-
123
- - You **SHOULD** add brief issue or PR comments for major milestones or meaningful changes.
124
- - You **SHOULD** route issue/PR comment updates through `github-ops` whenever possible.
121
+ ### Status Comment
122
+
123
+ - You **MUST** keep the story's status comment current per `github-ops` § Status comment: create it at the first sub-task completion, edit it in place at every later sub-task completion, at PR open, at each gate recorded, and on block. The template (marker, prefix line, story table) lives in `github-ops` and is never restated here.
124
+ - You **SHOULD** route the status-comment write through `github-ops` whenever possible; when delegation is unavailable, run the commands below directly.
125
+ - Procedure, for story issue `{n}` of `repos/{o}/{r}`:
126
+ 1. Find the comment by its marker: `gh api repos/{o}/{r}/issues/{n}/comments --paginate --jq '.[] | select(.body | startswith("<!-- dev-tasks:status -->")) | .id'`.
127
+ 2. Absent → create it: `gh issue comment {n} --body-file <path>`.
128
+ 3. Present → edit it in place: `gh api -X PATCH repos/{o}/{r}/issues/comments/{id} -F body=@<path>`.
129
+ 4. Two or more comments carry the marker → edit the oldest (lowest id), never post another, and report `status_comment: failed(duplicate marker)` so a human removes the extra one.
130
+ 5. The marker is the first byte of the body file — no leading blank line, whitespace or BOM — because the `startswith` match on line one is how the comment is found; a marker on line two means a second comment gets posted. The body always goes through a file, never inline.
131
+ - Each write is reported as `status_comment: written | failed(<reason>) | skipped(no issue)`. A task list with no GitHub Issue skips the comment and reports `skipped(no issue)`; a refused write (permissions, locked issue) reports `failed(<reason>)`. A failed write never blocks the sub-task — it is reported, never dropped silently.
132
+
133
+ ### Wave Status Update (Main Thread Only)
134
+
135
+ - Under the `planner`, the wave's status comment belongs to the planner: report `wave_status: owned-by-planner` and do nothing further.
136
+ - In the main thread with no planner (the interactive `/developer` command), after PR open and at PR ready you **MUST** look up the story's parent: `gh api repos/{o}/{r}/issues/{n}/parent`.
137
+ - `200` → edit this story's row (state, PR, sub-task count) in the wave issue's status comment, found and edited by the same marker procedure above, and report `wave_status: written`. If the wave issue has no status comment yet, create it from the wave table in `github-ops` § Status comment and report `wave_status: written`.
138
+ - Header lines on this path, which has no integration branch (D-75, RD-17): `Current story` names this story; `Last merged PR` and `Integration HEAD` keep the existing comment's values when editing it and read `none` when creating the comment; `Gates` carries this story's gates.
139
+ - `404` → the story has no parent (published before the hierarchy convention); report `wave_status: skipped(no parent)`. This is expected, not an error.
140
+ - A refused read or write → `wave_status: failed(<reason>)`; it never blocks the sub-task.
125
141
 
126
142
  ---
127
143
 
@@ -152,19 +168,19 @@ When `workstream/decisions-<feature>.md` exists and was read per step 2 above:
152
168
  - PRs targeting **`main`**: the **user** reviews and approves.
153
169
 
154
170
  11. The PR **MUST** be merged by the authorized party (planner for integration branches, user for `main`).
155
- 12. You **MUST NOT** close the GitHub Issue until the PR is approved **AND** merged.
156
- 13. You **MUST NOT** close the issue while the PR is still in draft or pending review.
171
+ 12. Nobody closes the GitHub Issue: not the implementing agent, not the `planner`. It closes when a PR against the default branch carrying `Closes #N` merges: under the `planner` that is the consolidated PR, and in a main-thread run with no planner (the interactive `/developer` command) it is the story PR itself. A story PR into an integration branch closes nothing, because GitHub ignores closing keywords on a PR whose base is not the default branch.
172
+ 13. You **MUST NOT** close the issue by hand at any point, before or after the merge; if it is still open after the closing PR merged, report that instead of closing it.
157
173
  14. You **MUST** notify the user when the PR is ready for review — explicitly inform them so they can review and merge.
158
174
 
159
175
  ---
160
176
 
161
177
  ## GitHub Execution Rules Summary
162
178
 
163
- | Phase | Rule |
164
- | ------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
165
- | **Before coding** | Confirm issue open → Create branch (`github-ops`) → First commit → Open draft PR (`github-ops`) → Sync checklists |
166
- | **During coding** | One sub-task at a time → Mark `[x]` locally + GitHub → Wait for approval |
167
- | **Before closing** | All ACs verified → Quality gates pass (test/lint/format/typecheck/audit) → migration confirmation/apply/verify (when applicable) → docs drift check clear → coverage_gate recorded → verifier audit run + summary posted (non-blocking on drift) → PR ready → Approved → Merged → Then close issue |
179
+ | Phase | Rule |
180
+ | ------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
181
+ | **Before coding** | Confirm issue open → Create branch (`github-ops`) → First commit → Open draft PR (`github-ops`) → Sync checklists |
182
+ | **During coding** | One sub-task at a time → Mark `[x]` locally + GitHub → Update the status comment (`github-ops` § Status comment) → Wait for approval |
183
+ | **Before closing** | All ACs verified → Quality gates pass (test/lint/format/typecheck/audit) → migration confirmation/apply/verify (when applicable) → docs drift check clear → coverage_gate recorded → verifier audit run + summary posted (non-blocking on drift) → PR ready → Approved → Merged → GitHub closes the issue (`Closes #N` on a default-branch PR) |
168
184
 
169
185
  ---
170
186
 
@@ -177,7 +193,7 @@ When `workstream/decisions-<feature>.md` exists and was read per step 2 above:
177
193
  ## Final Instructions
178
194
 
179
195
  1. You **MUST** always respect the task list execution order.
180
- 2. You **MUST** keep the GitHub Issue updated with checklist and progress comments.
196
+ 2. You **MUST** keep the GitHub Issue updated with its checklist and its status comment.
181
197
  3. You **MUST** ensure branch, PR, and issue naming follow `github-ops` conventions.
182
198
  4. You **MUST** stop after each sub-task and request user approval.
183
- 5. You **MUST NOT** close a GitHub Issue without confirming the PR has been reviewed, approved, and merged.
199
+ 5. You **MUST NOT** close a GitHub Issue by hand: nobody closes it; it closes when a PR against the default branch carrying `Closes #N` merges.
@@ -25,8 +25,10 @@ This activity adapts to the input — it works with a user stories file (from th
25
25
  2. **Review Available Work:** You **MUST** read the source and list available stories or the issue scope.
26
26
  3. **Select Scope:** In Stories Mode, you **MUST** ask which stories to include. In Issue Mode, the scope is the single issue.
27
27
  4. **Generate Task List:** You **MUST** produce a `tasks-*.md` file in the required format.
28
+ - **Plan header:** The header carries `Source:` (the source document) and, on the next line, `Wave issue: #N`, its own line with no bold or backticks so the planner can read it at Phase 0. In Stories Mode, take the number from the publication report's `Wave issue` line (`workstream/github-publication-<prd-name>.md`, written by `activity-publish-github`). When the report predates the tracking hierarchy or has no `Wave issue` line, or in Issue Mode, write `Wave issue: none` and add a `> Note:` line under it saying the planner will search for the wave issue at Phase 0. When the plan fully resolves follow-up issues outside its story set, add a `Resolves: #N, #M` line after `Wave issue:`; the planner carries `Closes #N` for each on the consolidated PR (planner D-74). Omit the line when there are none.
28
29
  5. **Publish to GitHub:** You **MUST** update the corresponding GitHub Issue(s) with the task checklist by delegating to `github-ops` whenever possible.
29
30
  6. **Save Output.**
31
+ 7. **Set the Task Plan Line:** When the plan header reads `Wave issue: #N`, set the wave issue body's `Task plan:` line under `## Artifacts` to a root-relative link to the saved task list, after the file is saved: read the body with `gh issue view <N> --json body --jq .body` into a file, change only that line, and write it back with `gh issue edit <N> --body-file <path>`. With `Wave issue: none` there is no wave issue body to edit, and the line stays `pending` until a later plan names the wave issue.
30
32
 
31
33
  ## Package Manager and Command Standards
32
34
 
@@ -55,6 +57,9 @@ The task list **MUST** follow this structure:
55
57
  ```markdown
56
58
  # Implementation Plan - [Name]
57
59
 
60
+ Source: `[path to the user stories file or refined issue]`
61
+ Wave issue: #N
62
+
58
63
  ## Relevant Files
59
64
 
60
65
  - `path/to/file1.ts` - [Description]
@@ -183,4 +188,5 @@ If this is a **greenfield project** or a **new component**, you **MUST** include
183
188
  8. For schema/data-model changes, you **MUST** include migration lifecycle tasks and an explicit user-confirmation gate before applying migrations unless an opt-out rationale is documented.
184
189
  9. You **MUST** update the corresponding GitHub Issue(s) with the task checklist by delegating to `github-ops` whenever possible. If no issue exists, you **MUST** ask the user whether to create one first.
185
190
  10. You **MUST** save the task list file.
191
+ 10a. When the wave issue is known, you **MUST** set its body's `Task plan:` Artifacts line to the saved task list (Process step 7).
186
192
  11. You **MUST** inform the user they can now use the **implement** activity to start coding.
@@ -33,6 +33,10 @@ Check with `gh api repos/<owner>/<repo>/branches/<default-branch>/protection` (a
33
33
 
34
34
  See the README "Configure branch protection" step for the exact `gh api` invocation. You **MUST NOT** proceed to treat the project as fully initialized while branch protection remains unconfigured without the user's explicit acknowledgment.
35
35
 
36
+ ## Repository Setup — GitHub Project (Recommended)
37
+
38
+ Alongside branch protection, recommend one GitHub Project per repository, so the PRD, wave and story issues that `activity-publish-github` creates appear on a board that GitHub keeps current without any agent writing to it. Setup is a one-time human step: `docs/runbooks/runbook-configure-github-project.md` keeps the template's Status options and GitHub's default workflows, narrows auto-add to `is:issue`, and names the three views to create by hand. No agent ever writes Project Status; a linked pull request and the issue closing at ship are what move it. Skipping this step changes nothing else in the workflow.
39
+
36
40
  ## Document Changelog Convention
37
41
 
38
42
  Every document produced by this activity **MUST** include a **Changelog** table as the **first section** after the document title. The changelog tracks the version history of the document.