@llipe.com/dev-tasks 0.16.4 → 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.
- package/.claude/agents/developer.md +8 -3
- package/.claude/agents/github-ops.md +186 -58
- package/.claude/agents/technical-writer.md +1 -1
- package/.claude/agents/verifier.md +10 -5
- package/.claude/commands/planner.md +109 -14
- package/.claude/commands/product-engineer.md +27 -3
- package/.claude/skills/activity-init/SKILL.md +4 -0
- package/.claude/skills/activity-publish-github/SKILL.md +84 -15
- package/.claude/skills/implement/SKILL.md +29 -13
- package/.claude/skills/memo-cli-usage/REFERENCE.md +1 -0
- package/.claude/skills/memo-cli-usage/SKILL.md +3 -1
- package/.claude/skills/plan/SKILL.md +6 -0
- package/.github/agents/developer.agent.md +8 -3
- package/.github/agents/github-ops.agent.md +181 -63
- package/.github/agents/planner.agent.md +122 -27
- package/.github/agents/product-engineer.agent.md +27 -3
- package/.github/agents/technical-writer.agent.md +1 -1
- package/.github/agents/verifier.agent.md +10 -5
- package/.github/instructions/implement.instructions.md +29 -13
- package/.github/instructions/plan.instructions.md +6 -0
- package/.github/skills/activity-init/SKILL.md +4 -0
- package/.github/skills/activity-publish-github/SKILL.md +84 -15
- package/.github/skills/memo-cli-usage/REFERENCE.md +1 -0
- package/.github/skills/memo-cli-usage/SKILL.md +3 -1
- package/.kiro/agents/developer.md +8 -3
- package/.kiro/agents/github-ops.md +181 -63
- package/.kiro/agents/planner.md +122 -27
- package/.kiro/agents/product-engineer.md +27 -3
- package/.kiro/agents/technical-writer.md +1 -1
- package/.kiro/agents/verifier.md +10 -5
- package/.kiro/skills/activity-init/SKILL.md +4 -0
- package/.kiro/skills/activity-publish-github/SKILL.md +84 -15
- package/.kiro/skills/memo-cli-usage/REFERENCE.md +1 -0
- package/.kiro/skills/memo-cli-usage/SKILL.md +3 -1
- package/.kiro/steering/implement.md +29 -13
- package/.kiro/steering/plan.md +6 -0
- package/CHANGELOG.md +12 -0
- package/README.md +79 -7
- package/TESTING.md +61 -1
- package/dist/bin/dev-tasks.d.ts +1 -1
- package/dist/bin/dev-tasks.js +126 -4
- package/dist/bin/dev-tasks.js.map +1 -1
- package/dist/bin/parse-args.d.ts +49 -1
- package/dist/bin/parse-args.d.ts.map +1 -1
- package/dist/bin/parse-args.js +132 -11
- package/dist/bin/parse-args.js.map +1 -1
- package/dist/core/checks/index.d.ts +2 -0
- package/dist/core/checks/index.d.ts.map +1 -1
- package/dist/core/checks/index.js +1 -0
- package/dist/core/checks/index.js.map +1 -1
- package/dist/core/checks/roadmap.d.ts +40 -0
- package/dist/core/checks/roadmap.d.ts.map +1 -0
- package/dist/core/checks/roadmap.js +78 -0
- package/dist/core/checks/roadmap.js.map +1 -0
- package/dist/core/migrate-projects/answers.d.ts +63 -0
- package/dist/core/migrate-projects/answers.d.ts.map +1 -0
- package/dist/core/migrate-projects/answers.js +79 -0
- package/dist/core/migrate-projects/answers.js.map +1 -0
- package/dist/core/migrate-projects/apply.d.ts +51 -0
- package/dist/core/migrate-projects/apply.d.ts.map +1 -0
- package/dist/core/migrate-projects/apply.js +828 -0
- package/dist/core/migrate-projects/apply.js.map +1 -0
- package/dist/core/migrate-projects/classify.d.ts +93 -0
- package/dist/core/migrate-projects/classify.d.ts.map +1 -0
- package/dist/core/migrate-projects/classify.js +170 -0
- package/dist/core/migrate-projects/classify.js.map +1 -0
- package/dist/core/migrate-projects/conventions.d.ts +118 -0
- package/dist/core/migrate-projects/conventions.d.ts.map +1 -0
- package/dist/core/migrate-projects/conventions.js +213 -0
- package/dist/core/migrate-projects/conventions.js.map +1 -0
- package/dist/core/migrate-projects/gh.d.ts +40 -0
- package/dist/core/migrate-projects/gh.d.ts.map +1 -0
- package/dist/core/migrate-projects/gh.js +115 -0
- package/dist/core/migrate-projects/gh.js.map +1 -0
- package/dist/core/migrate-projects/index.d.ts +61 -0
- package/dist/core/migrate-projects/index.d.ts.map +1 -0
- package/dist/core/migrate-projects/index.js +183 -0
- package/dist/core/migrate-projects/index.js.map +1 -0
- package/dist/core/migrate-projects/local-reader.d.ts +8 -0
- package/dist/core/migrate-projects/local-reader.d.ts.map +1 -0
- package/dist/core/migrate-projects/local-reader.js +30 -0
- package/dist/core/migrate-projects/local-reader.js.map +1 -0
- package/dist/core/migrate-projects/map.d.ts +36 -0
- package/dist/core/migrate-projects/map.d.ts.map +1 -0
- package/dist/core/migrate-projects/map.js +75 -0
- package/dist/core/migrate-projects/map.js.map +1 -0
- package/dist/core/migrate-projects/plan.d.ts +71 -0
- package/dist/core/migrate-projects/plan.d.ts.map +1 -0
- package/dist/core/migrate-projects/plan.js +638 -0
- package/dist/core/migrate-projects/plan.js.map +1 -0
- package/dist/core/migrate-projects/planfile.d.ts +149 -0
- package/dist/core/migrate-projects/planfile.d.ts.map +1 -0
- package/dist/core/migrate-projects/planfile.js +608 -0
- package/dist/core/migrate-projects/planfile.js.map +1 -0
- package/dist/core/migrate-projects/roadmap.d.ts +43 -0
- package/dist/core/migrate-projects/roadmap.d.ts.map +1 -0
- package/dist/core/migrate-projects/roadmap.js +54 -0
- package/dist/core/migrate-projects/roadmap.js.map +1 -0
- package/dist/core/migrate-projects/snapshot.d.ts +91 -0
- package/dist/core/migrate-projects/snapshot.d.ts.map +1 -0
- package/dist/core/migrate-projects/snapshot.js +285 -0
- package/dist/core/migrate-projects/snapshot.js.map +1 -0
- package/dist/core/migrate-projects/summary.d.ts +27 -0
- package/dist/core/migrate-projects/summary.d.ts.map +1 -0
- package/dist/core/migrate-projects/summary.js +35 -0
- package/dist/core/migrate-projects/summary.js.map +1 -0
- package/package.json +1 -1
|
@@ -141,6 +141,24 @@ Map milestone issues into the same internal story model used by Option A.
|
|
|
141
141
|
|
|
142
142
|
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.
|
|
143
143
|
|
|
144
|
+
### Wave Issue Resolution
|
|
145
|
+
|
|
146
|
+
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:
|
|
147
|
+
|
|
148
|
+
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.
|
|
149
|
+
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>:")))'`.
|
|
150
|
+
- 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.
|
|
151
|
+
- More than one match: stop, list the matching issue numbers, and ask the user which one is the wave issue; never pick one silently.
|
|
152
|
+
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.
|
|
153
|
+
|
|
154
|
+
### PRD Issue Resolution
|
|
155
|
+
|
|
156
|
+
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:
|
|
157
|
+
|
|
158
|
+
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.
|
|
159
|
+
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.
|
|
160
|
+
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.
|
|
161
|
+
|
|
144
162
|
Confirm source and story count before Phase 0.5.
|
|
145
163
|
|
|
146
164
|
---
|
|
@@ -153,9 +171,13 @@ Before parsing stories, check for an existing checkpoint state file.
|
|
|
153
171
|
2. If a state file exists:
|
|
154
172
|
- Read it and display the story status table.
|
|
155
173
|
- Identify the next pending story from the `Current Position` section.
|
|
174
|
+
- 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.
|
|
156
175
|
- Ask: **"Resume from story [next-story-id]? (y/n)"**
|
|
157
176
|
- 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.
|
|
158
|
-
-
|
|
177
|
+
- 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.
|
|
178
|
+
- 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.
|
|
179
|
+
- On resume, edit the wave status comment in place (see **Wave Status Comment** in Phase 4); never create a second one.
|
|
180
|
+
- 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.
|
|
159
181
|
3. If no state file exists, proceed to Phase 1 normally.
|
|
160
182
|
|
|
161
183
|
### State File Format
|
|
@@ -170,8 +192,10 @@ Path: `/workstream/planner-state-<plan-id>.md`
|
|
|
170
192
|
- Task source: <path or milestone>
|
|
171
193
|
- Integration branch: <branch-name>
|
|
172
194
|
- Repository: <owner/repo>
|
|
195
|
+
- Wave issue: #N | none
|
|
173
196
|
- Started: <timestamp>
|
|
174
197
|
- Last updated: <timestamp>
|
|
198
|
+
- PRD issue: #N | none
|
|
175
199
|
|
|
176
200
|
## Story Status
|
|
177
201
|
|
|
@@ -190,6 +214,8 @@ Path: `/workstream/planner-state-<plan-id>.md`
|
|
|
190
214
|
## Decisions Log
|
|
191
215
|
|
|
192
216
|
- <any decisions made during the run>
|
|
217
|
+
- wave_status: skipped(no wave issue) | failed(<reason>) at <event>
|
|
218
|
+
- prd_status: written | failed(<reason>) | skipped(no PRD issue) at <event>
|
|
193
219
|
```
|
|
194
220
|
|
|
195
221
|
---
|
|
@@ -320,6 +346,12 @@ integration/<plan-id>-<short-description>
|
|
|
320
346
|
|
|
321
347
|
Per-story branches and PRs are created by `developer` following `github-ops` conventions.
|
|
322
348
|
|
|
349
|
+
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).
|
|
350
|
+
|
|
351
|
+
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.
|
|
352
|
+
|
|
353
|
+
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.
|
|
354
|
+
|
|
323
355
|
---
|
|
324
356
|
|
|
325
357
|
## Phase 4 - Delegate to developer
|
|
@@ -344,6 +376,8 @@ For each story invoke `developer` in **Execute Mode** with:
|
|
|
344
376
|
- Test plan reference (if available): path to `/workstream/test-plan-*.md` for this story
|
|
345
377
|
- 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
|
|
346
378
|
|
|
379
|
+
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).
|
|
380
|
+
|
|
347
381
|
### Verifier Design Mode (Pre-Implementation)
|
|
348
382
|
|
|
349
383
|
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:
|
|
@@ -366,6 +400,7 @@ GitHub Issue: #{{ story.issue_number }}
|
|
|
366
400
|
Task list path: {{ story.task_file }}
|
|
367
401
|
Execution mode: pre-approved autonomous sequential
|
|
368
402
|
Integration target branch: {{ integration_branch }}
|
|
403
|
+
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`)
|
|
369
404
|
Test-first: YES — write/update tests before implementation for each behavioral sub-task
|
|
370
405
|
Test plan: {{ test_plan_path | default: "none — derive tests from acceptance criteria" }}
|
|
371
406
|
Decision log: {{ decision_log_path }}
|
|
@@ -447,6 +482,36 @@ If the payload is missing or incomplete:
|
|
|
447
482
|
1. Retry once with a narrow follow-up asking the developer to return only the missing closeout payload.
|
|
448
483
|
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.
|
|
449
484
|
|
|
485
|
+
### Wave Status Comment
|
|
486
|
+
|
|
487
|
+
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.
|
|
488
|
+
|
|
489
|
+
Write it at these events, in this order across a run:
|
|
490
|
+
|
|
491
|
+
1. **Run start** — Phase 3, once the integration branch is pushed: create it when no comment carries the marker; every story reads `pending`.
|
|
492
|
+
2. **Resume** — Phase 0.5: find it by the marker and edit it; never create a second one.
|
|
493
|
+
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.
|
|
494
|
+
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).
|
|
495
|
+
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.
|
|
496
|
+
6. **Block** — whenever a story is marked blocked: the story reads `blocked`, with the reason in the update line.
|
|
497
|
+
7. **Rollup** — Phase 5 step 3: the rollup audit's human-readable summary goes in this comment.
|
|
498
|
+
8. **Consolidated PR open** — Phase 5 step 7: the update line names the consolidated PR.
|
|
499
|
+
9. **Close-out** — Phase 6's **Status comments** step, once the merge is verified: the update line says the wave shipped.
|
|
500
|
+
|
|
501
|
+
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).
|
|
502
|
+
|
|
503
|
+
### PRD Status Comment
|
|
504
|
+
|
|
505
|
+
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.
|
|
506
|
+
|
|
507
|
+
Write it at these events, in this order across a run:
|
|
508
|
+
|
|
509
|
+
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.
|
|
510
|
+
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.
|
|
511
|
+
3. **Close-out** — Phase 6's **Status comments** step, once the merge is verified: the wave reads `shipped`.
|
|
512
|
+
|
|
513
|
+
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.
|
|
514
|
+
|
|
450
515
|
### Merge management rule (planner-owned)
|
|
451
516
|
|
|
452
517
|
Planner **MUST** manage merges for every completed story in sequence before delegating the next story.
|
|
@@ -462,15 +527,17 @@ For each completed story PR:
|
|
|
462
527
|
7. For migration-bearing stories, verify explicit user confirmation was recorded before migration apply.
|
|
463
528
|
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.
|
|
464
529
|
9. Detect merge conflicts before attempting merge. If conflicts are found, invoke the `git-ops` skill to resolve them.
|
|
465
|
-
10. **Review the PR** — planner **MUST** review the story PR (verify scope, files, test and quality-gate results) and approve it.
|
|
530
|
+
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.
|
|
466
531
|
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).
|
|
467
532
|
12. Confirm integration branch is green after merge before moving to next story.
|
|
468
|
-
13. **Verify the merge actually happened, then write checkpoint.** Before writing `✅ Merged` to the state file, confirm observed GitHub state — run `gh pr view <n> --json state,mergedAt` and require `state` to be `MERGED` and `mergedAt` to be non-null. If the check fails or errors, do **not** write `✅ Merged`; mark the story blocked, report the exact `gh pr view` output, and stop rather than guessing at the outcome. Only once this is confirmed: 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,
|
|
533
|
+
13. **Verify the merge actually happened, then write checkpoint.** Before writing `✅ Merged` to the state file, confirm observed GitHub state — run `gh pr view <n> --json state,mergedAt` and require `state` to be `MERGED` and `mergedAt` to be non-null. If the check fails or errors, do **not** write `✅ Merged`; mark the story blocked, report the exact `gh pr view` output, and stop rather than guessing at the outcome. Only once this is confirmed: 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.
|
|
469
534
|
|
|
470
535
|
If any merge gate fails, stop and report exact blocker and PR link.
|
|
471
536
|
|
|
472
537
|
Planner **MUST NOT** allow multiple open story PRs to merge concurrently.
|
|
473
538
|
|
|
539
|
+
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).
|
|
540
|
+
|
|
474
541
|
### Merge authority policy
|
|
475
542
|
|
|
476
543
|
| Target Branch | Reviewer & Approver | Who Merges |
|
|
@@ -490,13 +557,16 @@ After all stories are merged into integration:
|
|
|
490
557
|
|
|
491
558
|
1. Run full integration test suite on integration branch.
|
|
492
559
|
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.
|
|
493
|
-
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.
|
|
560
|
+
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.
|
|
561
|
+
- **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:`.
|
|
494
562
|
4. Invoke `technical-writer` for a planner-level drift/stale-doc validation pass against integrated changes; unresolved drift **MUST** block handoff.
|
|
495
|
-
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`
|
|
563
|
+
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.
|
|
496
564
|
6. **memo run outcome.** Write the per-run outcome entry described in **memo-cli Integration → Responsibilities** and record `memo_run_outcome`.
|
|
497
|
-
7. Open one consolidated PR from integration branch to `main`.
|
|
565
|
+
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**).
|
|
566
|
+
- **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`.
|
|
567
|
+
- **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.
|
|
498
568
|
8. **Do NOT merge.** Notify the user that the consolidated PR is ready for their review.
|
|
499
|
-
9. Wait for the user to approve and merge the PR into `main
|
|
569
|
+
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.
|
|
500
570
|
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.
|
|
501
571
|
11. Before final handoff, **MUST** ensure the local working branch is the integration branch used for this run:
|
|
502
572
|
|
|
@@ -508,7 +578,7 @@ After all stories are merged into integration:
|
|
|
508
578
|
- consolidated PR URL
|
|
509
579
|
- current CI/check status
|
|
510
580
|
- exact required user actions: review, approve, and merge
|
|
511
|
-
- a post-merge follow-up action
|
|
581
|
+
- 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
|
|
512
582
|
|
|
513
583
|
Consolidated PR should include:
|
|
514
584
|
|
|
@@ -517,8 +587,10 @@ Consolidated PR should include:
|
|
|
517
587
|
- Per-story changed files and test results
|
|
518
588
|
- Manual validation instructions per story
|
|
519
589
|
- Integration test summary
|
|
520
|
-
- Roadmap row(s) updated in `docs/roadmap.md` (before → after status)
|
|
590
|
+
- Roadmap row(s) updated in `docs/roadmap.md` (before → after status), with the `gh` commands that derived them quoted verbatim (step 5)
|
|
521
591
|
- Memo coverage: per-story `memo_intent` / `memo_outcome` values and `memo_run_outcome`
|
|
592
|
+
- `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)
|
|
593
|
+
- `project_observation` for In progress at consolidated PR open (step 7)
|
|
522
594
|
|
|
523
595
|
PR title **MUST** follow Conventional Commits and PR body **MUST** follow `github-ops` conventions.
|
|
524
596
|
|
|
@@ -526,14 +598,33 @@ Planner **MUST NOT** merge the consolidated PR. Only the user may approve and me
|
|
|
526
598
|
|
|
527
599
|
---
|
|
528
600
|
|
|
601
|
+
## Phase 6 - Close-out
|
|
602
|
+
|
|
603
|
+
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`.
|
|
604
|
+
|
|
605
|
+
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.
|
|
606
|
+
2. **Pull main.** Check out `main` and pull it, so every read below and the close-out branch start from the merged state.
|
|
607
|
+
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.
|
|
608
|
+
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.
|
|
609
|
+
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".
|
|
610
|
+
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`.
|
|
611
|
+
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.
|
|
612
|
+
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.
|
|
613
|
+
9. **Record the Done observation.** Write step 5's `project_observation` for "Done at consolidated PR merge" in `TESTING.md`'s DF-5 row.
|
|
614
|
+
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.
|
|
615
|
+
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.
|
|
616
|
+
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.
|
|
617
|
+
|
|
618
|
+
---
|
|
619
|
+
|
|
529
620
|
## Roadmap Maintenance
|
|
530
621
|
|
|
531
622
|
`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.
|
|
532
623
|
|
|
533
624
|
- **Read** it in Phase 0 (see **Roadmap Read**).
|
|
534
|
-
- **Update** the run's row(s) in Phase 5 step 5, in the consolidated PR
|
|
625
|
+
- **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.
|
|
535
626
|
- Change only the rows this run touched; rows for other PRDs belong to `product-engineer` and to the planner runs that deliver them.
|
|
536
|
-
- The `verifier` rollup audit (Phase 5 step 3) compares the roadmap
|
|
627
|
+
- 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.
|
|
537
628
|
|
|
538
629
|
---
|
|
539
630
|
|
|
@@ -545,7 +636,7 @@ Planner **MUST NOT** merge the consolidated PR. Only the user may approve and me
|
|
|
545
636
|
| Multiple task files | Ask user to choose |
|
|
546
637
|
| Milestone has no issues | Report and stop |
|
|
547
638
|
| Circular dependencies | Report cycle and stop |
|
|
548
|
-
| Story returns blocked | Mark blocked and ask whether to continue
|
|
639
|
+
| Story returns blocked | Mark blocked, edit the wave status comment so the story reads `blocked` with the reason, and ask whether to continue |
|
|
549
640
|
| Story PR targets wrong base | Require retargeting to integration branch before merge |
|
|
550
641
|
| Required checks pending/failing | Do not merge; report failing checks |
|
|
551
642
|
| Story PR behind integration branch | Require update/rebase before merge |
|
|
@@ -568,11 +659,12 @@ Planner **MUST NOT** merge the consolidated PR. Only the user may approve and me
|
|
|
568
659
|
- Execution is strictly sequential, one story at a time.
|
|
569
660
|
- Planner owns story PR merges into integration and enforces merge gates.
|
|
570
661
|
- `developer` runs in Execute Mode for each story.
|
|
571
|
-
- Planner **MUST
|
|
662
|
+
- 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.
|
|
572
663
|
- On restart, planner **MUST** check for existing state files and offer to resume (Phase 0.5).
|
|
573
664
|
- All GitHub outputs are in English.
|
|
574
|
-
-
|
|
665
|
+
- 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.
|
|
575
666
|
- 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.
|
|
667
|
+
- 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.
|
|
576
668
|
- Planner **MUST** invoke `qa-engineer` and `verifier` (Audit Mode) directly, scoped to each story's diff/branch/PR, before merging that story's PR into the integration branch (merge gates 5 and 6) — a story's self-reported `coverage_gate`/`verifier_audit` fields are supporting context only, never sufficient evidence on their own, and `not-run(no-delegation)`/`SKIPPED(no-delegation)` are valid, expected self-reports from the `developer` subagent, not red flags. Planner **MUST** also invoke `verifier` in `audit` mode for a PRD-level rollup audit before/alongside the consolidated PR. All these triggers are mandatory and non-skippable, and none of their drift findings block the corresponding merge/handoff.
|
|
577
669
|
|
|
578
670
|
---
|
|
@@ -588,7 +680,10 @@ For each run, return:
|
|
|
588
680
|
- Integration branch
|
|
589
681
|
- Final local branch state (checked out branch name or explicit verification result)
|
|
590
682
|
- Story PR links/status
|
|
683
|
+
- Wave status comment outcome (`wave_status` values recorded in the Decisions Log)
|
|
684
|
+
- PRD status comment outcome (`prd_status` values recorded in the Decisions Log)
|
|
591
685
|
- Consolidated PR link or blocker
|
|
592
686
|
- Current test status
|
|
593
687
|
- PR Directives (User Action Required)
|
|
688
|
+
- 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
|
|
594
689
|
- Next exact action awaiting approval or execution
|
|
@@ -80,7 +80,7 @@ If any required input is missing, you **MUST** ask concise clarifying questions.
|
|
|
80
80
|
- **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.
|
|
81
81
|
- **Fill `Issues/PRs` when stories are published** (`activity-publish-github`), and set the row to `In progress` once its first story is being implemented.
|
|
82
82
|
- **Correct it during drift reconciliation** (`activity-drift-reconciliation`) when a `verifier` roadmap-mismatch finding is confirmed.
|
|
83
|
-
- 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.
|
|
83
|
+
- 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).
|
|
84
84
|
|
|
85
85
|
Shape (one table, one row per PRD phase or wave, newest PRD first):
|
|
86
86
|
|
|
@@ -96,6 +96,29 @@ Last updated: YYYY-MM-DD
|
|
|
96
96
|
|
|
97
97
|
`Status` is exactly one of `Not started`, `In progress`, `Done`.
|
|
98
98
|
|
|
99
|
+
### Roadmap Conversion (before migration)
|
|
100
|
+
|
|
101
|
+
`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):
|
|
102
|
+
|
|
103
|
+
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.
|
|
104
|
+
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.
|
|
105
|
+
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).
|
|
106
|
+
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.
|
|
107
|
+
|
|
108
|
+
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).
|
|
109
|
+
|
|
110
|
+
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).
|
|
111
|
+
|
|
112
|
+
---
|
|
113
|
+
|
|
114
|
+
## Drift Reconciliation
|
|
115
|
+
|
|
116
|
+
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):
|
|
117
|
+
|
|
118
|
+
- **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`.
|
|
119
|
+
- **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)))'`.
|
|
120
|
+
- **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`.
|
|
121
|
+
|
|
99
122
|
---
|
|
100
123
|
|
|
101
124
|
## memo-cli Integration (When Available)
|
|
@@ -164,12 +187,13 @@ memo write \
|
|
|
164
187
|
--entry-type decision \
|
|
165
188
|
--story "<issue-or-feature-id-if-known>" \
|
|
166
189
|
--files "workstream/decisions-<feature>.md" \
|
|
167
|
-
--on-duplicate
|
|
190
|
+
--on-duplicate create-new \
|
|
168
191
|
--json
|
|
169
192
|
```
|
|
170
193
|
|
|
171
194
|
- `--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.
|
|
172
|
-
- A row that supersedes an earlier decision is written as a new entry naming the superseded ID in its rationale
|
|
195
|
+
- A row that supersedes an earlier decision is written as a new entry naming the superseded ID in its rationale.
|
|
196
|
+
- 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).
|
|
173
197
|
- **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.
|
|
174
198
|
|
|
175
199
|
`technical-writer` still owns ADR and doc-change entries, and `developer` owns per-story intent/outcome entries.
|
|
@@ -38,6 +38,10 @@ Check with `gh api repos/<owner>/<repo>/branches/<default-branch>/protection` (a
|
|
|
38
38
|
|
|
39
39
|
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.
|
|
40
40
|
|
|
41
|
+
## Repository Setup — GitHub Project (Recommended)
|
|
42
|
+
|
|
43
|
+
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.
|
|
44
|
+
|
|
41
45
|
## Document Changelog Convention
|
|
42
46
|
|
|
43
47
|
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.
|
|
@@ -13,27 +13,36 @@ Publish user stories as GitHub Issues so GitHub becomes the source of truth for
|
|
|
13
13
|
|
|
14
14
|
## Goal
|
|
15
15
|
|
|
16
|
-
Take a list of user stories and publish them as GitHub Issues using
|
|
16
|
+
Take a list of user stories and publish them as GitHub Issues using the `gh` CLI, under one PRD tracking issue and one wave tracking issue, so GitHub becomes the source of truth for execution tracking and a GitHub Project can show the hierarchy and per-wave progress with no extra work.
|
|
17
17
|
|
|
18
18
|
## Context
|
|
19
19
|
|
|
20
|
-
This activity assumes the following
|
|
20
|
+
This activity assumes the following documents exist:
|
|
21
21
|
|
|
22
22
|
- `user-stories-[prd-name].md` — The comprehensive list of user stories (produced by the **generate-stories** activity)
|
|
23
|
+
- `docs/roadmap.md` — The roadmap row for this PRD; its `Phase/Wave` cell is the wave `<id>` used in the wave tracking issue title (github-ops § Title Format)
|
|
23
24
|
|
|
24
25
|
## Process
|
|
25
26
|
|
|
26
27
|
1. **Receive Input:** User provides the reference to the user stories file and the GitHub repository target.
|
|
27
28
|
2. **Clarify Publishing Rules:** You **MUST** ask for labeling, milestones, assignees, and any issue template constraints, and you **MUST** align them with `github-ops` conventions.
|
|
28
|
-
3. **
|
|
29
|
-
|
|
30
|
-
|
|
29
|
+
3. **Find or Create the Tracking Issues:** Before any story is created, you **MUST** find or create the PRD tracking issue, then the wave tracking issue. Each is found by its `level:` label plus its title prefix (the title forms are defined by github-ops § Title Format); nothing is stored in a workstream file.
|
|
30
|
+
- PRD: `gh issue list --label "level: prd" --search "[PRD-<name>] in:title" --state open --json number,title --jq 'map(select(.title | startswith("[PRD-<name>]")))'`
|
|
31
|
+
- Wave: `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>:")))'`
|
|
32
|
+
- The `--jq` filter is applied client-side before counting, because GitHub's `in:title` search tokenises brackets and hyphens leniently and can return siblings such as `[PRD-<name>-v2]`.
|
|
33
|
+
- Exactly one match: reuse that issue number. Zero matches: create the issue with `gh issue create --title ... --label "level: prd" --body-file <path>` (or `level: wave`); tracking issues carry their `level:` label only, never `type:` or `priority:`. More than one match: stop, list the matching issue numbers, and ask the user which one to keep; never pick one silently.
|
|
34
|
+
- The PRD issue body follows the PRD tracking issue template and the wave issue body the wave tracking issue template, both under Issue Formatting Rules.
|
|
35
|
+
4. **Map Stories to Issues:** You **MUST** create one GitHub Issue per user story, labeled `level: story` plus exactly one `type:` label from the github-ops type set (`enhancement`, `bug`, `security`, `refactor`, `test`, `docs`, `chore`, `tech-debt`) and one `priority:` label. When a story fits several types, the github-ops tie-break order picks it; a story is never published with zero or two `type:` labels, and never with a retired one such as `type: other` (D-85).
|
|
36
|
+
5. **Publish to GitHub:** You **MUST** delegate issue creation and metadata application to `github-ops` whenever possible. After each story issue is created, you **MUST** attach it as a sub-issue of the wave issue (see Sub-issue Hierarchy).
|
|
37
|
+
6. **Attach and Verify the Hierarchy:** After all stories are created, attach the wave under the PRD issue if not already attached, read both `sub_issues` lists back, and record the `hierarchy:` result in the publication report.
|
|
38
|
+
7. **Write the PRD Status Comment:** After the hierarchy is verified, create or edit the PRD issue's status comment in the shape of github-ops § Status comment's PRD table, found by its marker and written with implement § Status Comment's find-by-marker, create and PATCH procedure: the published wave's row reads `published`, with its wave issue number. An existing row for this wave is edited in place, never added a second time, and every other wave's row is kept as it is. The PRD issue is the one step 3 resolved, as the report's `PRD issue` line records it; when there is none, run step 3's `level: prd` search again, and with no PRD issue, skip the write. Record `prd_status: written | failed(<reason>) | skipped(no PRD issue)` in the publication report; a refused write is `failed(<reason>)`, and a failed write never stops the publication.
|
|
39
|
+
8. **Save Output.**
|
|
31
40
|
|
|
32
41
|
Execution method rules:
|
|
33
42
|
|
|
34
|
-
-
|
|
35
|
-
-
|
|
36
|
-
- The selected method (`
|
|
43
|
+
- The `gh` CLI is the primary execution path for every call in this activity.
|
|
44
|
+
- A GitHub MCP server is optional; if one is configured in this session, it **MAY** be used instead.
|
|
45
|
+
- The selected method (`gh-cli` or `github-mcp`) **MUST** be recorded in the publication report.
|
|
37
46
|
|
|
38
47
|
If `github-ops` delegation is unavailable in the current runtime, you **MUST** apply `github-ops` issue, label, milestone, and comment conventions directly and explicitly note that fallback in your status output.
|
|
39
48
|
|
|
@@ -46,14 +55,17 @@ Attribution rules:
|
|
|
46
55
|
- "Which GitHub repository should I publish to? (`owner/repo`)"
|
|
47
56
|
- "Do you want labels, milestones, or assignees added?"
|
|
48
57
|
- "Should I use a specific issue template or format?"
|
|
49
|
-
- "Do you want a parent epic issue or project board association?"
|
|
50
58
|
- "Should I skip stories below a certain priority or size?"
|
|
51
59
|
|
|
60
|
+
The tracking-issue hierarchy is not optional, so no question asks for it.
|
|
61
|
+
|
|
52
62
|
## Issue Formatting Rules
|
|
53
63
|
|
|
54
|
-
|
|
64
|
+
### Story issues
|
|
65
|
+
|
|
66
|
+
Each story GitHub Issue **MUST** be created using:
|
|
55
67
|
|
|
56
|
-
- **Title:** `
|
|
68
|
+
- **Title:** the `PRD story` row of github-ops § Title Format
|
|
57
69
|
- **Body:**
|
|
58
70
|
- User Story (role, goal, benefit)
|
|
59
71
|
- Context
|
|
@@ -71,6 +83,53 @@ Each GitHub Issue **MUST** be created using:
|
|
|
71
83
|
|
|
72
84
|
For JS/TS projects, command examples in issues **MUST** prefer `pnpm` and canonical scripts (`pnpm run <script>`).
|
|
73
85
|
|
|
86
|
+
### PRD tracking issue body
|
|
87
|
+
|
|
88
|
+
The PRD issue body is the entry point to the whole PRD: its title line, a link to the PRD file and to its `docs/roadmap.md` row, and the list of waves. It carries no checkboxes, because progress lives in the issue's status comment (github-ops § Status comment) and in the sub-issue progress GitHub derives from the hierarchy. Each wave line is added, or its issue number filled in, by the publish run that creates that wave's tracking issue.
|
|
89
|
+
|
|
90
|
+
```markdown
|
|
91
|
+
# <PRD title>
|
|
92
|
+
|
|
93
|
+
PRD: [docs/requirements/prd-<prd-name>.md](/docs/requirements/prd-<prd-name>.md)
|
|
94
|
+
Roadmap: [docs/roadmap.md](/docs/roadmap.md)
|
|
95
|
+
|
|
96
|
+
## Waves
|
|
97
|
+
|
|
98
|
+
- Wave <id>: #<wave-issue> — <wave title>
|
|
99
|
+
```
|
|
100
|
+
|
|
101
|
+
### Wave tracking issue body
|
|
102
|
+
|
|
103
|
+
The wave issue body carries the wave's scope and its artifacts; it carries no checkboxes, because progress lives in the issue's status comment (github-ops § Status comment) and in the sub-issue progress GitHub derives from the hierarchy. `Integration branch` stays `TBD` until the planner starts the run; `Task plan` stays `pending` until the task list exists.
|
|
104
|
+
|
|
105
|
+
```markdown
|
|
106
|
+
Scope: <the wave's scope line from the PRD's delivery table>
|
|
107
|
+
Integration branch: TBD
|
|
108
|
+
|
|
109
|
+
## Artifacts
|
|
110
|
+
|
|
111
|
+
- Specification: [workstream/specification-<prd-name>.md](/workstream/specification-<prd-name>.md)
|
|
112
|
+
- Stories: [workstream/user-stories-<prd-name>.md](/workstream/user-stories-<prd-name>.md)
|
|
113
|
+
- Task plan: pending
|
|
114
|
+
|
|
115
|
+
## Stories
|
|
116
|
+
|
|
117
|
+
- S-001: <title>
|
|
118
|
+
- S-002: <title>
|
|
119
|
+
```
|
|
120
|
+
|
|
121
|
+
### Sub-issue hierarchy
|
|
122
|
+
|
|
123
|
+
Stories are sub-issues of the wave issue, and the wave issue is a sub-issue of the PRD issue. Every call is REST through `gh api` with `repo` scope:
|
|
124
|
+
|
|
125
|
+
- Child numeric id: `gh api repos/{o}/{r}/issues/{n} --jq .id` (the sub-issue endpoint takes the numeric id, not the issue number).
|
|
126
|
+
- Attach a story under the wave, immediately after the story is created: `gh api -X POST repos/{o}/{r}/issues/{wave}/sub_issues -F sub_issue_id=<id>`.
|
|
127
|
+
- Attach the wave under the PRD with the same call against `issues/{prd}/sub_issues`, if not already listed there.
|
|
128
|
+
- Verify: `gh api repos/{o}/{r}/issues/{wave}/sub_issues --jq '.[].number'` lists every story created in this run, and the PRD's list contains the wave.
|
|
129
|
+
- Report `hierarchy: verified(<n> of <n>)` when every attach is confirmed, or `hierarchy: failed(<reason>)` naming the first failed attach. A failed attach is reported, never retried silently, and never stops the remaining stories from being created.
|
|
130
|
+
|
|
131
|
+
Every issue body goes through `--body-file <path>`; inline `--body` is blocked by git-guard.
|
|
132
|
+
|
|
74
133
|
All issue formatting and metadata **MUST** conform to `github-ops` conventions.
|
|
75
134
|
|
|
76
135
|
## Output Structure
|
|
@@ -85,6 +144,13 @@ You **MUST** create a publication report:
|
|
|
85
144
|
- Repo: owner/repo
|
|
86
145
|
- Date: YYYY-MM-DD
|
|
87
146
|
|
|
147
|
+
## Tracking Issues
|
|
148
|
+
|
|
149
|
+
- PRD issue: #<number> (reused | created)
|
|
150
|
+
- Wave issue: #<number> (reused | created)
|
|
151
|
+
- Hierarchy: verified(<n> of <n>) | failed(<reason>)
|
|
152
|
+
- prd_status: written | failed(<reason>) | skipped(no PRD issue)
|
|
153
|
+
|
|
88
154
|
## Created Issues
|
|
89
155
|
|
|
90
156
|
| Story ID | Story Title | Issue URL | Labels | Milestone | Assignee |
|
|
@@ -97,7 +163,7 @@ You **MUST** create a publication report:
|
|
|
97
163
|
- Any skipped stories and why
|
|
98
164
|
- Any template or permission limitations
|
|
99
165
|
- Any manual follow-up needed
|
|
100
|
-
- Execution method used: `
|
|
166
|
+
- Execution method used: `gh-cli` or `github-mcp`
|
|
101
167
|
- Assisted-by value used for PR creation/issue closure (if applicable)
|
|
102
168
|
```
|
|
103
169
|
|
|
@@ -111,6 +177,9 @@ You **MUST** create a publication report:
|
|
|
111
177
|
|
|
112
178
|
1. You **MUST** read the user stories file.
|
|
113
179
|
2. You **MUST** ask clarifying questions and confirm the target repo.
|
|
114
|
-
3. You **MUST**
|
|
115
|
-
4. You **MUST**
|
|
116
|
-
5. You **MUST**
|
|
180
|
+
3. You **MUST** find or create the PRD and wave tracking issues before publishing any story; more than one match stops the run.
|
|
181
|
+
4. You **MUST** publish each story as a GitHub Issue by delegating to `github-ops` whenever possible, and attach it as a sub-issue of the wave issue.
|
|
182
|
+
5. You **MUST** attach the wave under the PRD issue, verify the hierarchy, and record the `hierarchy:` result.
|
|
183
|
+
6. You **MUST** create or edit the PRD issue's status comment so the wave's row reads `published`, and record `prd_status` in the publication report.
|
|
184
|
+
7. You **MUST** save the publication report with the tracking issue numbers and issue links.
|
|
185
|
+
8. You **MUST** inform the user that GitHub is now the source of truth for execution tracking.
|
|
@@ -119,10 +119,26 @@ When `workstream/decisions-<feature>.md` exists and was read per step 2 above:
|
|
|
119
119
|
- If drift is detected between local and GitHub, you **MUST** reconcile immediately and report the reconciliation.
|
|
120
120
|
- 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.
|
|
121
121
|
|
|
122
|
-
###
|
|
123
|
-
|
|
124
|
-
- You **
|
|
125
|
-
- You **SHOULD** route
|
|
122
|
+
### Status Comment
|
|
123
|
+
|
|
124
|
+
- 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.
|
|
125
|
+
- You **SHOULD** route the status-comment write through `github-ops` whenever possible; when delegation is unavailable, run the commands below directly.
|
|
126
|
+
- Procedure, for story issue `{n}` of `repos/{o}/{r}`:
|
|
127
|
+
1. Find the comment by its marker: `gh api repos/{o}/{r}/issues/{n}/comments --paginate --jq '.[] | select(.body | startswith("<!-- dev-tasks:status -->")) | .id'`.
|
|
128
|
+
2. Absent → create it: `gh issue comment {n} --body-file <path>`.
|
|
129
|
+
3. Present → edit it in place: `gh api -X PATCH repos/{o}/{r}/issues/comments/{id} -F body=@<path>`.
|
|
130
|
+
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.
|
|
131
|
+
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.
|
|
132
|
+
- 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.
|
|
133
|
+
|
|
134
|
+
### Wave Status Update (Main Thread Only)
|
|
135
|
+
|
|
136
|
+
- Under the `planner`, the wave's status comment belongs to the planner: report `wave_status: owned-by-planner` and do nothing further.
|
|
137
|
+
- 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`.
|
|
138
|
+
- `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`.
|
|
139
|
+
- 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.
|
|
140
|
+
- `404` → the story has no parent (published before the hierarchy convention); report `wave_status: skipped(no parent)`. This is expected, not an error.
|
|
141
|
+
- A refused read or write → `wave_status: failed(<reason>)`; it never blocks the sub-task.
|
|
126
142
|
|
|
127
143
|
---
|
|
128
144
|
|
|
@@ -153,19 +169,19 @@ When `workstream/decisions-<feature>.md` exists and was read per step 2 above:
|
|
|
153
169
|
- PRs targeting **`main`**: the **user** reviews and approves.
|
|
154
170
|
|
|
155
171
|
11. The PR **MUST** be merged by the authorized party (planner for integration branches, user for `main`).
|
|
156
|
-
12.
|
|
157
|
-
13. You **MUST NOT** close the issue
|
|
172
|
+
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.
|
|
173
|
+
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.
|
|
158
174
|
14. You **MUST** notify the user when the PR is ready for review — explicitly inform them so they can review and merge.
|
|
159
175
|
|
|
160
176
|
---
|
|
161
177
|
|
|
162
178
|
## GitHub Execution Rules Summary
|
|
163
179
|
|
|
164
|
-
| Phase | Rule
|
|
165
|
-
| ------------------ |
|
|
166
|
-
| **Before coding** | Confirm issue open → Create branch (`github-ops`) → First commit → Open draft PR (`github-ops`) → Sync checklists
|
|
167
|
-
| **During coding** | One sub-task at a time → Mark `[x]` locally + GitHub → Wait for approval
|
|
168
|
-
| **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 →
|
|
180
|
+
| Phase | Rule |
|
|
181
|
+
| ------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
|
182
|
+
| **Before coding** | Confirm issue open → Create branch (`github-ops`) → First commit → Open draft PR (`github-ops`) → Sync checklists |
|
|
183
|
+
| **During coding** | One sub-task at a time → Mark `[x]` locally + GitHub → Update the status comment (`github-ops` § Status comment) → Wait for approval |
|
|
184
|
+
| **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) |
|
|
169
185
|
|
|
170
186
|
---
|
|
171
187
|
|
|
@@ -178,7 +194,7 @@ When `workstream/decisions-<feature>.md` exists and was read per step 2 above:
|
|
|
178
194
|
## Final Instructions
|
|
179
195
|
|
|
180
196
|
1. You **MUST** always respect the task list execution order.
|
|
181
|
-
2. You **MUST** keep the GitHub Issue updated with checklist and
|
|
197
|
+
2. You **MUST** keep the GitHub Issue updated with its checklist and its status comment.
|
|
182
198
|
3. You **MUST** ensure branch, PR, and issue naming follow `github-ops` conventions.
|
|
183
199
|
4. You **MUST** stop after each sub-task and request user approval.
|
|
184
|
-
5. You **MUST NOT** close a GitHub Issue
|
|
200
|
+
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.
|