@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
|
@@ -72,6 +72,7 @@ If the user provides a feature description or asks to create a PRD/spec/stories
|
|
|
72
72
|
3. **Task synchronization:** Whenever a sub-task is completed, you **MUST** immediately mark `[x]` in:
|
|
73
73
|
- The local task file in `/workstream/`
|
|
74
74
|
- The GitHub Issue checklist
|
|
75
|
+
- The story's status comment on the GitHub Issue, kept current per the `implement` skill's `### Status Comment` procedure — the procedure and the `github-ops` § Status comment template are referenced by name and never restated here; report each outcome as `status_comment:` and `wave_status:` in the closeout payload
|
|
75
76
|
4. **Branch + PR discipline (before coding):** You **MUST** follow `github-ops` conventions:
|
|
76
77
|
- Create branch per `github-ops` branch naming rules (e.g., `issue/42-short-description`, `story/S-003-short-description`)
|
|
77
78
|
- Open a Draft PR against the default branch unless a base branch override is provided. A PR requires at least one commit, so open it immediately after the first commit on the branch — never before. You **MUST NOT** continue past that first commit without the Draft PR open.
|
|
@@ -79,7 +80,7 @@ If the user provides a feature description or asks to create a PRD/spec/stories
|
|
|
79
80
|
- Use the `github-ops` PR description template (What / Why / How / Testing / Checklist)
|
|
80
81
|
- Include `Closes #<issue-number>` in the PR description
|
|
81
82
|
5. **Stop-gate rule:** If mode is `step-gated`, you **MUST** stop after each sub-task and request user approval.
|
|
82
|
-
6. **Do not close issue
|
|
83
|
+
6. **Do not close the issue:** You **MUST NOT** close the issue; GitHub closes it when the consolidated PR merges to main under the `planner`, and when the story PR itself merges to the default branch in single-issue work without a planner. Either way the closing PR targets the default branch and carries `Closes #<issue-number>`, and nobody closes it by hand. A story PR into an integration branch closes nothing, because GitHub ignores closing keywords on a PR whose base is not the default branch.
|
|
83
84
|
7. **Keep scope tight:** You **MUST** work only on the selected issue/stories unless the user explicitly expands scope.
|
|
84
85
|
8. **Update Relevant Files:** You **MUST** keep the task file's Relevant Files section accurate.
|
|
85
86
|
9. **English-only outputs:** You **MUST** produce English-only output for docs, comments, and generated content.
|
|
@@ -111,7 +112,7 @@ If the user provides a feature description or asks to create a PRD/spec/stories
|
|
|
111
112
|
- If HEAD is already a valid feature branch (matching `issue/*` or `story/*`), confirm the Draft PR exists and proceed. If the branch has no commits yet, no PR can exist — open it immediately after the first commit.
|
|
112
113
|
5. **memo intent (when memo is available):** Before writing any implementation code, run the memo-cli Availability Check and write the intent entry (see **memo-cli Integration → Intent Entry**). Record `memo_intent` as `written(<id>)`, `failed(<reason>)`, or `skipped(<reason>)`.
|
|
113
114
|
6. Execute one sub-task at a time in checklist order. For each behavioral sub-task, follow **test-first**: write/update tests first, verify they fail for the right reason, then implement to make them pass.
|
|
114
|
-
7. After each completed sub-task: mark `[x]` locally and in GitHub, pause for approval if step-gated.
|
|
115
|
+
7. After each completed sub-task: mark `[x]` locally and in GitHub, update the status comment per `implement` § Status Comment, pause for approval if step-gated.
|
|
115
116
|
8. When all sub-tasks are complete:
|
|
116
117
|
- Verify all acceptance criteria.
|
|
117
118
|
|
|
@@ -312,7 +313,7 @@ Before marking a Story/Issue done:
|
|
|
312
313
|
9. `/workstream` **SHOULD** be cleaned (active artifacts retained, obsolete artifacts archived/removed).
|
|
313
314
|
10. The memo intent and outcome writes **MUST** have been attempted when memo-cli is available (`memo write --kind episodic --session ISSUE-<n> --bank developer-memory …`, before PR conversion), and `memo_intent` / `memo_outcome` **MUST** be recorded as `written(<id>)`, `failed(<reason>)`, or `skipped(<reason>)`. A `failed` or `skipped` value does not block completion; an omitted field does.
|
|
314
315
|
11. PR **MUST** be ready, approved, and merged.
|
|
315
|
-
12. You **MUST NOT** close the GitHub Issue
|
|
316
|
+
12. You **MUST NOT** close the GitHub Issue; nobody closes it by hand. It closes when a PR against the default branch carrying `Closes #N` merges: under the `planner` that is the consolidated PR, and in single-issue work without a planner it is the story PR itself (rule 6).
|
|
316
317
|
13. For multi-story implementations, you **MUST** run a checklist cross-check between GitHub Issue tasks and `/workstream/tasks-*.md` and report any mismatch resolution.
|
|
317
318
|
|
|
318
319
|
---
|
|
@@ -330,6 +331,7 @@ For each run, return a compact status report with:
|
|
|
330
331
|
- Files updated in `/docs/` and ADR path (if created)
|
|
331
332
|
- Test results for the current step
|
|
332
333
|
- Quality gate results (`test`, `lint`, `format:check`, `typecheck`, `audit`)
|
|
334
|
+
- Status comment outcome (`status_comment`, `wave_status`)
|
|
333
335
|
- Next exact sub-task awaiting approval or currently executing
|
|
334
336
|
|
|
335
337
|
When finishing a story/issue execution cycle, return a **complete closeout summary** that includes:
|
|
@@ -374,6 +376,8 @@ workstream_files:
|
|
|
374
376
|
memo_intent: written(<id>) | failed(<reason>) | skipped(<reason>)
|
|
375
377
|
memo_outcome: written(<id>) | failed(<reason>) | skipped(<reason>)
|
|
376
378
|
checklist_sync: synced | mismatch-fixed | blocked
|
|
379
|
+
status_comment: written | failed(<reason>) | skipped(<reason>)
|
|
380
|
+
wave_status: written | failed(<reason>) | skipped(<reason>) | owned-by-planner
|
|
377
381
|
verifier_audit: run | not-run(no-delegation) | blocked
|
|
378
382
|
fidelity_verdict: High | Medium | Low | none
|
|
379
383
|
highest_drift_impact: Critical | Major | Minor | None
|
|
@@ -388,6 +392,7 @@ Rules for this payload:
|
|
|
388
392
|
- Every field is required. Use `none`, `NOT RUN`, or `blocked` when a value does not exist.
|
|
389
393
|
- `memo_intent` and `memo_outcome` are always present. `skipped(<reason>)` (memo not installed, not configured, or unavailable in this session) and `failed(<reason>)` (the write was attempted and errored after one retry) are valid values that do not block the merge; `planner` treats an absent field as an incomplete story.
|
|
390
394
|
- `planner` may treat the story as incomplete if either marker or any required field is missing.
|
|
395
|
+
- `status_comment` and `wave_status` are always present; `skipped(<reason>)` is the floor, never an omission — a task list with no GitHub Issue reports `skipped(no issue)` for both (D-28). Under `planner` the wave comment belongs to the planner, so `wave_status: owned-by-planner` is the expected value in this agent's default subagent-delegation context; `written`, `skipped(no parent)` and `failed(<reason>)` come from the main-thread wave update defined in `implement`.
|
|
391
396
|
- `verifier_audit: not-run(no-delegation)` and `coverage_gate: SKIPPED(no-delegation)` are the honest, expected values in this agent's default subagent-delegation context (see Operating Context above) — `planner` treats these as a signal to run its own direct invocation, not as a red flag or an incomplete story.
|
|
392
397
|
|
|
393
398
|
Do not dump full files unless explicitly requested.
|
|
@@ -35,29 +35,33 @@ If this fails, **STOP** and ask the user to run `gh auth login` — do not attem
|
|
|
35
35
|
|
|
36
36
|
Use this table to translate each convention in this file into a `gh` invocation. When MCP is used instead, the equivalent MCP tool is listed for reference.
|
|
37
37
|
|
|
38
|
-
| Operation
|
|
39
|
-
|
|
|
40
|
-
| Create issue
|
|
41
|
-
| Update issue
|
|
42
|
-
| Comment on issue
|
|
43
|
-
| Close issue with attribution
|
|
44
|
-
| List/audit issues
|
|
45
|
-
| Search issues
|
|
46
|
-
| Create PR
|
|
47
|
-
| Update PR
|
|
48
|
-
| Comment on PR
|
|
49
|
-
| Review a PR
|
|
50
|
-
| Merge PR (integration branch only, planner-authorized)
|
|
51
|
-
| List/audit PRs
|
|
52
|
-
| Create/list labels
|
|
53
|
-
| Create/list milestones
|
|
54
|
-
| Assign milestone to issue
|
|
55
|
-
|
|
|
38
|
+
| Operation | `gh` CLI | MCP equivalent |
|
|
39
|
+
| ---------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------- |
|
|
40
|
+
| Create issue | `gh issue create --title "<title>" --body-file <path> --label "<label>" --milestone "<milestone>"` | `create_issue` |
|
|
41
|
+
| Update issue | `gh issue edit <number> --title "<title>" --body-file <path> --add-label "<label>" --milestone "<milestone>"` | `update_issue` |
|
|
42
|
+
| Comment on issue | `gh issue comment <number> --body-file <path>` | `add_issue_comment` |
|
|
43
|
+
| Close issue with attribution (never a story or wave issue) | `gh issue comment <number> --body-file <path>` (closing summary + Assisted-by line), then `gh issue close <number>` | `update_issue` (state=closed) + comment |
|
|
44
|
+
| List/audit issues | `gh issue list --state all --json number,title,labels,milestone,body,url --limit 500` | `list_issues` |
|
|
45
|
+
| Search issues | `gh search issues "<query>" --repo <owner/repo>` | `search_issues` |
|
|
46
|
+
| Create PR | `gh pr create --title "<title>" --body-file <path> --base <target-branch> --head <source-branch>` | `create_pull_request` |
|
|
47
|
+
| Update PR | `gh pr edit <number> --title "<title>" --body-file <path>` | `update_pull_request` |
|
|
48
|
+
| Comment on PR | `gh pr comment <number> --body-file <path>` | `add_issue_comment` (PRs share issue comments) |
|
|
49
|
+
| Review a PR | `gh pr review <number> --approve\|--request-changes\|--comment --body-file <path>` | `create_pull_request_review` |
|
|
50
|
+
| Merge PR (integration branch only, planner-authorized) | `gh pr merge <number> --merge --delete-branch` | `merge_pull_request` |
|
|
51
|
+
| List/audit PRs | `gh pr list --state all --json number,title,body,baseRefName,headRefName,labels --limit 500` | `list_pull_requests` |
|
|
52
|
+
| Create/list labels | `gh label create "<name>" --color "<hex>" --description "<desc>"` / `gh label list` | `create_label` / `list_labels` |
|
|
53
|
+
| Create/list milestones | `gh api repos/<owner>/<repo>/milestones -f title="<title>" -f description="<desc>" -f due_on="<ISO date>"` / `gh api repos/<owner>/<repo>/milestones` | (no dedicated MCP tool; use REST) |
|
|
54
|
+
| Assign milestone to issue | `gh issue edit <number> --milestone "<milestone>"` | `update_issue` |
|
|
55
|
+
| Add a blocking relation (issue data) | `gh api -X POST repos/{o}/{r}/issues/{blocked}/dependencies/blocked_by -F issue_id=<blocker numeric id>` | (no dedicated MCP tool; use REST) |
|
|
56
|
+
| Remove a blocking relation | `gh api -X DELETE repos/{o}/{r}/issues/{blocked}/dependencies/blocked_by/{blocker numeric id}` | (no dedicated MCP tool; use REST) |
|
|
57
|
+
| List what an issue blocks / is blocked by | `gh api repos/{o}/{r}/issues/{n}/dependencies/blocking --paginate` / `gh api repos/{o}/{r}/issues/{n}/dependencies/blocked_by --paginate` | (no dedicated MCP tool; use REST) |
|
|
58
|
+
| Create branch | `git checkout -b <branch>` (name per [Branch Naming](#branch-naming)) | n/a (local git operation) |
|
|
56
59
|
|
|
57
60
|
Notes:
|
|
58
61
|
|
|
59
62
|
- Prefer `--json` output on `gh issue list` / `gh pr list` and `gh api` for machine-parseable results — do not scrape the default human-readable table output.
|
|
60
63
|
- `gh api <endpoint>` is the fallback for anything without a dedicated subcommand (milestones, some label edge cases, reactions). See <https://cli.github.com/manual/gh_api>.
|
|
64
|
+
- **Issue dependencies are issue data an agent may write, unlike the Project.** A blocking relation lives on the blocked issue (`{blocked}`) and names its blocker by the blocker's REST numeric id, read with `gh api repos/{o}/{r}/issues/<blocker number> --jq .id`, as the sub-issue endpoint does; an issue number or a GraphQL node id is rejected. No agent writes the Project (D-22); these commands change only the two issues they name (D-83). Write a relation only when the user or the issue text names the blocked issue, and add the `**Blocks:**` line to the blocker's body in the same change (see [Labels](#labels)).
|
|
61
65
|
- `gh` respects the repository detected from the current working directory; pass `--repo <owner/repo>` explicitly when operating on a different repository than the one checked out locally.
|
|
62
66
|
- Every `gh` invocation that mutates state (create/edit/close/merge) **MUST** be reflected in the Output Contract's `Changes applied` list, exactly as an MCP-driven change would be.
|
|
63
67
|
- **MCP merge/write coverage (issue #178):** `merge_pull_request` — the MCP equivalent listed for "Merge PR" above — is not an unguarded shortcut around branch protection. `git-guard.sh`'s `PreToolUse` dispatch matches `mcp__github__merge_pull_request` (and `enable_pr_auto_merge`, `push_files`, `create_or_update_file`, `delete_file`, `create_branch`) by exact `tool_name` and enforces the same "never merge/write into the default branch" invariant on their structured `tool_input` fields that it enforces on the `gh` CLI command string. Do not treat any MCP tool call as exempt from that invariant merely because it isn't a `Bash` command — the actual durable control either way is GitHub branch protection on the remote (see `AGENTS.md` § Hooks), not this hook.
|
|
@@ -75,6 +79,7 @@ Other agents (especially `developer`) **SHOULD** delegate to `github-ops` whenev
|
|
|
75
79
|
- Assign or create milestones
|
|
76
80
|
- Write structured issue or PR comments
|
|
77
81
|
- Audit existing GitHub artifacts for consistency
|
|
82
|
+
- Migrate an existing repository to the projects-tracking conventions ([Migration Mode](#migration-mode))
|
|
78
83
|
|
|
79
84
|
---
|
|
80
85
|
|
|
@@ -86,6 +91,8 @@ Issue titles **MUST** follow one of these patterns:
|
|
|
86
91
|
|
|
87
92
|
| Context | Format | Example |
|
|
88
93
|
| ------------------- | ---------------------------------- | --------------------------------------------- |
|
|
94
|
+
| PRD tracking issue | `[PRD-<name>] <PRD title>` | `[PRD-auth] Authentication and sessions` |
|
|
95
|
+
| Wave tracking issue | `[PRD-<name>] Wave <id>: <title>` | `[PRD-auth] Wave 1: Password reset` |
|
|
89
96
|
| PRD story | `[PRD-<name>] Story <ID>: <Title>` | `[PRD-auth] Story S-003: Password reset flow` |
|
|
90
97
|
| Standalone issue | `[<scope>] <Concise description>` | `[api] Rate limiting on public endpoints` |
|
|
91
98
|
| Bug | `[bug] <What is broken>` | `[bug] Login fails on expired session token` |
|
|
@@ -96,6 +103,8 @@ Rules:
|
|
|
96
103
|
- Titles **MUST** be sentence-case after the prefix.
|
|
97
104
|
- Titles **MUST NOT** exceed 80 characters.
|
|
98
105
|
- Titles **MUST NOT** include issue numbers or PR references.
|
|
106
|
+
- In a wave tracking issue, `<id>` is the wave's `Phase/Wave` cell in `docs/roadmap.md`: a number when the PRD has numbered phases, `All` or a short wave name otherwise.
|
|
107
|
+
- A PRD tracking issue and a wave tracking issue are containers: the wave is a sub-issue of the PRD issue, and each story is a sub-issue of its wave.
|
|
99
108
|
|
|
100
109
|
### Issue Body Structure
|
|
101
110
|
|
|
@@ -122,10 +131,65 @@ Comments on issues **MUST** follow these rules:
|
|
|
122
131
|
- **Decision records** **MUST** use: `📌 Decision: <what was decided> — Reason: <why>`
|
|
123
132
|
- Every comment **MUST** include a relevant tracker reference: issue (`#<number>`) or commit (`<sha>`).
|
|
124
133
|
- Comments **MUST NOT** be empty or single-word acknowledgments (e.g., "ok", "done").
|
|
125
|
-
- Long-form
|
|
134
|
+
- Long-form comments **SHOULD** use checklists.
|
|
135
|
+
|
|
136
|
+
#### Status comment
|
|
137
|
+
|
|
138
|
+
One comment per story, wave and PRD tracking issue carries the issue's current state, so a reader sees it from the issue alone without opening the PR or the task list. This file owns the template because it owns every other comment convention; `implement`, `developer` and `planner` reference it by name and never restate it, so there is one copy across the three platform trees instead of nine.
|
|
139
|
+
|
|
140
|
+
Rules:
|
|
141
|
+
|
|
142
|
+
- There is exactly one status comment per issue. It is found by the marker `<!-- dev-tasks:status -->` on its first line: read the issue's comments (`gh api repos/<owner>/<repo>/issues/<number>/comments --paginate`) and select the one whose body starts with the marker. No comment id is stored in any file.
|
|
143
|
+
- When no comment carries the marker, create it with `gh issue comment <number> --body-file <path>`. When one does, edit it in place with `gh api -X PATCH repos/<owner>/<repo>/issues/comments/<comment-id> -F body=@<path>`. Every other comment is append-only; only the status comment is ever edited.
|
|
144
|
+
- Line one is the marker, which GitHub renders as nothing. Line two is `🔄 Update: <one-line summary> — Refs #<issue>`, so the prefix and tracker-reference rules above hold. The table for the issue's level follows.
|
|
145
|
+
- The body always goes through a file. The marker has no leading whitespace and no blank line before it, because a `startswith` match on the first line is how the comment is found; a marker on line two means a second comment gets posted.
|
|
146
|
+
|
|
147
|
+
Story issue:
|
|
148
|
+
|
|
149
|
+
```text
|
|
150
|
+
<!-- dev-tasks:status -->
|
|
151
|
+
🔄 Update: <one-line summary> — Refs #<issue>
|
|
152
|
+
|
|
153
|
+
| Sub-tasks | Current | Branch | PR | Gates | Blocker | Updated |
|
|
154
|
+
| ----------------- | ------------- | ---------- | ------------- | ------------------------------------------------------------------------------------------------------------------------------------------- | ---------------- | ---------------------- |
|
|
155
|
+
| <done> of <total> | <sub-task id> | `<branch>` | #<pr> or none | <test, lint, format, typecheck, audit: pass, fail or not run; coverage_gate: PASS, FAIL or SKIPPED; fidelity: High, Medium, Low or not run> | <none or reason> | <YYYY-MM-DD HH:MM UTC> |
|
|
156
|
+
```
|
|
157
|
+
|
|
158
|
+
Wave issue:
|
|
159
|
+
|
|
160
|
+
```text
|
|
161
|
+
<!-- dev-tasks:status -->
|
|
162
|
+
🔄 Update: <one-line summary> — Refs #<issue>
|
|
163
|
+
|
|
164
|
+
Current story: <story id> (#<issue>) or none
|
|
165
|
+
Last merged PR: #<pr> or none
|
|
166
|
+
Integration HEAD: `<sha>` or none
|
|
167
|
+
Gates: <pass, fail or not run>
|
|
168
|
+
|
|
169
|
+
| Story | State | PR | Sub-task |
|
|
170
|
+
| --------------------- | ------------------------------------------------------------------------------------- | ------------- | ----------------- |
|
|
171
|
+
| <story id> (#<issue>) | <pending, in progress (sub-task n of m), PR open, merged into integration or blocked> | #<pr> or none | <done> of <total> |
|
|
172
|
+
```
|
|
173
|
+
|
|
174
|
+
PRD issue:
|
|
175
|
+
|
|
176
|
+
```text
|
|
177
|
+
<!-- dev-tasks:status -->
|
|
178
|
+
🔄 Update: <one-line summary> — Refs #<issue>
|
|
179
|
+
|
|
180
|
+
| Wave | State | Wave issue |
|
|
181
|
+
| ---- | ------------------------------------------------------------------------- | ------------- |
|
|
182
|
+
| <id> | <not started, published, in progress, consolidated PR #n open or shipped> | #<issue> or — |
|
|
183
|
+
```
|
|
184
|
+
|
|
185
|
+
The PRD table has one row per wave, in wave order. `activity-publish-github` writes a wave's row at publish and the planner edits it at run start, consolidated PR open and close-out; an existing row is edited in place, never added a second time, and every other wave's row is kept as it is.
|
|
186
|
+
|
|
187
|
+
A wave that predates the PRD and wave tracking-issue hierarchy (published before it, so it has no wave issue) still gets a row, with `—` in the `Wave issue` column and its state read from its `docs/roadmap.md` row, for example `shipped` (D-73, RD-12). A roadmap wave not yet published reads `not started`, with `—` in the `Wave issue` column (D-107).
|
|
126
188
|
|
|
127
189
|
### Issue Closure Attribution
|
|
128
190
|
|
|
191
|
+
A story or wave tracking issue is never closed by an agent, `github-ops` included: it closes only through a `Closes` line on a PR whose base is the default branch (D-22, D-54, D-76). The attribution rule below applies to every other issue.
|
|
192
|
+
|
|
129
193
|
When closing an issue, `github-ops` **MUST** add a final closing comment that includes:
|
|
130
194
|
|
|
131
195
|
- A short closure summary (what was delivered and where)
|
|
@@ -202,6 +266,7 @@ Rules:
|
|
|
202
266
|
- The attribution line **MUST** be present when creating a PR.
|
|
203
267
|
- The attribution value **MUST** identify the assisting system and version when available (for example, `GitHub Copilot v1`, `Claude Code v3`).
|
|
204
268
|
- The `## Why` section **MUST** reference the appropriate issue (`Closes #<number>` or `Refs #<number>`). If no issue exists, it **MUST** reference the motivating commit (`Refs <sha>`).
|
|
269
|
+
- A consolidated PR from an integration branch to the default branch **MUST** carry `Closes #<number>` for every story issue it delivers, and for the wave tracking issue when it delivers every story of the wave, one keyword per issue on its own line; `Refs` is for everything else.
|
|
205
270
|
|
|
206
271
|
### Change-Record PR Shape (infra-engineer)
|
|
207
272
|
|
|
@@ -218,13 +283,22 @@ When `infra-engineer` delegates its change-record draft PR (S-001 AC-11), the PR
|
|
|
218
283
|
|
|
219
284
|
### Multi-Line Body Formatting
|
|
220
285
|
|
|
221
|
-
|
|
286
|
+
Collapsed/mangled PR and issue bodies (headings, checklists, and paragraphs all flattened into one line) are a recurring failure mode. To prevent this, the following is **mandatory**, not a preference order:
|
|
287
|
+
|
|
288
|
+
1. **`gh --body-file` only.** Agents **MUST** write the body content to a temp file using the file-write tool (not `echo`, `printf`, or a heredoc assigned to a shell variable) and pass it with `--body-file <path>`. Building the body as a shell variable and interpolating it — quoted or not — **MUST NOT** be used, because unquoted expansion word-splits on newlines/spaces and quoted expansion is still vulnerable to how the variable was assembled upstream (e.g. `tr`, `printf` without `-v`, command substitution stripping trailing newlines).
|
|
289
|
+
2. **MCP, when used instead of `gh`.** Agents **MUST** pass the body as a native multi-line string parameter to the MCP tool (`create_pull_request`, `update_pull_request`, `add_issue_comment`, `create_issue`, `update_issue`). This never touches a shell, so newlines cannot be lost or word-split.
|
|
290
|
+
3. Agents **MUST NOT** pass markdown with literal `\n` text inside double-quoted strings (e.g., `--body "## What\n\nSummary"`) — the shell does not expand `\n` in double quotes, causing the entire body to render as a single paragraph.
|
|
291
|
+
4. Inline `--body` **MUST NOT** be used for any body, a short single-line comment included; `--body-file` is the only method. On Claude Code and Kiro, `git-guard.sh` blocks an inline `--body` on `gh issue|pr create|edit|comment|review`.
|
|
292
|
+
|
|
293
|
+
#### Mandatory Verification After Write
|
|
222
294
|
|
|
223
|
-
|
|
224
|
-
2. **`$'...'` quoting** — use ANSI-C quoting so `\n` is interpreted as a real newline: `--body $'## What\n\nSummary here.\n\n## Why\n\nCloses #42'`
|
|
225
|
-
3. **`printf` piping** — `printf '## What\n\nSummary\n' | gh pr create --body-file -`
|
|
295
|
+
After every `create`/`update` operation that sets a multi-section body (PR description, issue body, structured comment), the agent **MUST** immediately read the body back (`gh pr view <number> --json body -q .body`, `gh issue view <number> --json body -q .body`, or the MCP equivalent read) and confirm:
|
|
226
296
|
|
|
227
|
-
|
|
297
|
+
- Each `## <Section>` heading appears at the start of its own line (not mid-paragraph).
|
|
298
|
+
- Checklist items render as `- [ ]` / `- [x]` on their own lines, not inline with surrounding prose.
|
|
299
|
+
- Sections are separated by blank lines.
|
|
300
|
+
|
|
301
|
+
If the read-back body is flattened or malformed, the agent **MUST** immediately re-edit it via `--body-file` (or the MCP update tool) before proceeding — it **MUST NOT** leave a malformed body in place and move on.
|
|
228
302
|
|
|
229
303
|
### PR Comments
|
|
230
304
|
|
|
@@ -242,11 +316,12 @@ Branch names **MUST** follow this pattern:
|
|
|
242
316
|
<type>/<issue-number>-<short-description>
|
|
243
317
|
```
|
|
244
318
|
|
|
245
|
-
| Type | When
|
|
246
|
-
| ------------- |
|
|
247
|
-
| `issue` | Single GitHub Issue
|
|
248
|
-
| `story` | PRD-driven user story
|
|
249
|
-
| `integration` | Multi-story consolidation branch
|
|
319
|
+
| Type | When | Example |
|
|
320
|
+
| ------------- | -------------------------------------------------- | ------------------------------------- |
|
|
321
|
+
| `issue` | Single GitHub Issue | `issue/42-rate-limiting` |
|
|
322
|
+
| `story` | PRD-driven user story | `story/S-003-password-reset` |
|
|
323
|
+
| `integration` | Multi-story consolidation branch | `integration/prd-auth-password-reset` |
|
|
324
|
+
| `chore` | Maintenance, tooling or docs work tied to an issue | `chore/306-github-ops-carve-outs` |
|
|
250
325
|
|
|
251
326
|
Rules:
|
|
252
327
|
|
|
@@ -254,11 +329,13 @@ Rules:
|
|
|
254
329
|
- Short description **MUST** be 2–5 words, hyphen-separated.
|
|
255
330
|
- Branches of type `issue` and `story` **MUST** include the issue or story number.
|
|
256
331
|
- Branches of type `integration` **MUST** identify the plan, PRD, or milestone being consolidated.
|
|
332
|
+
- Branches of type `chore` **MUST** follow the normal pattern, `chore/<issue-number>-<short-description>`. The one exception is planner Phase 6's close-out branch, `chore/<plan-id>-closeout`, keyed on the plan id (the planner state file's id) because the close-out has no issue of its own (D-76).
|
|
257
333
|
|
|
258
334
|
## Branch-Type Merge Rules
|
|
259
335
|
|
|
260
336
|
- Issue and story PRs **MUST** merge by merge commit with source-branch deletion (`--merge --delete-branch`), so the per-task commits are preserved. Squash and rebase merges are **NOT** used unless the user explicitly asks for one on a specific PR. The planner merges them into an integration branch; the user merges them into `main`.
|
|
261
337
|
- Integration PRs **MUST** merge into `main` by merge commit, and only the user may merge them.
|
|
338
|
+
- Chore PRs **MUST** target the default branch and merge by merge commit, and only the user may merge them.
|
|
262
339
|
|
|
263
340
|
---
|
|
264
341
|
|
|
@@ -272,37 +349,49 @@ The following label set **MUST** exist in every project. `github-ops` **MUST** c
|
|
|
272
349
|
|
|
273
350
|
The following tags are the canonical, most-used tags for issues and **MUST** be preferred over ad-hoc alternatives:
|
|
274
351
|
|
|
275
|
-
- Type tags: `type:
|
|
352
|
+
- Type tags: `type: security`, `type: bug`, `type: enhancement`, `type: refactor`, `type: test`, `type: docs`, `type: chore`, `type: tech-debt`
|
|
276
353
|
- Scope tags: `scope: frontend`, `scope: backend`, `scope: mobile`
|
|
277
|
-
|
|
278
|
-
|
|
279
|
-
|
|
|
280
|
-
|
|
|
281
|
-
|
|
|
282
|
-
| | `type:
|
|
283
|
-
| | `type:
|
|
284
|
-
| | `type:
|
|
285
|
-
| | `type:
|
|
286
|
-
| | `type: docs` | `#0075CA` | Documentation changes
|
|
287
|
-
| | `type:
|
|
288
|
-
|
|
|
289
|
-
|
|
|
290
|
-
| | `priority:
|
|
291
|
-
| | `priority:
|
|
292
|
-
|
|
|
293
|
-
|
|
|
294
|
-
| | `
|
|
295
|
-
| | `
|
|
296
|
-
| **
|
|
297
|
-
| | `
|
|
298
|
-
| | `
|
|
299
|
-
|
|
|
300
|
-
| | `scope:
|
|
354
|
+
- Level tags: `level: prd`, `level: wave`, `level: story`
|
|
355
|
+
|
|
356
|
+
| Category | Label | Color | Description |
|
|
357
|
+
| ------------ | -------------------------- | --------- | ------------------------------------------------------ |
|
|
358
|
+
| **Type** | `type: security` | `#B60205` | Security vulnerability, hardening, or compliance work |
|
|
359
|
+
| | `type: bug` | `#D93F0B` | Behavior that differs from the spec or intent |
|
|
360
|
+
| | `type: enhancement` | `#0E8A16` | New or changed behavior |
|
|
361
|
+
| | `type: refactor` | `#D4C5F9` | Code restructure, no behavior change |
|
|
362
|
+
| | `type: test` | `#BFDADC` | Test-only work |
|
|
363
|
+
| | `type: docs` | `#0075CA` | Documentation changes |
|
|
364
|
+
| | `type: chore` | `#FEF2C0` | Maintenance, dependencies, tooling, or CI |
|
|
365
|
+
| | `type: tech-debt` | `#5319E7` | Deferred engineering work that fits no other type |
|
|
366
|
+
| **Priority** | `priority: critical` | `#B60205` | Blocks a wave, PRD, or release from shipping |
|
|
367
|
+
| | `priority: high` | `#D93F0B` | Lands in the current wave or cycle; blocks no ship |
|
|
368
|
+
| | `priority: medium` | `#FBCA04` | Lands in the next wave or cycle |
|
|
369
|
+
| | `priority: low` | `#C5DEF5` | Backlog |
|
|
370
|
+
| **Level** | `level: prd` | `#3F51B5` | PRD tracking issue; a container for waves, not work |
|
|
371
|
+
| | `level: wave` | `#5C6BC0` | Wave tracking issue; a container for stories, not work |
|
|
372
|
+
| | `level: story` | `#7986CB` | Story issue; the unit of work |
|
|
373
|
+
| **Status** | `status: blocked` | `#E4E669` | Waiting on external dependency |
|
|
374
|
+
| | `status: needs-refinement` | `#F9D0C4` | Scope or AC unclear |
|
|
375
|
+
| | `status: deferred` | `#BFBFBF` | Parked by decision; not closed |
|
|
376
|
+
| **Scope** | `scope: frontend` | `#BFD4F2` | Frontend changes |
|
|
377
|
+
| | `scope: backend` | `#D4C5F9` | Backend changes |
|
|
378
|
+
| | `scope: mobile` | `#FAD8C7` | Mobile app or mobile-specific changes |
|
|
379
|
+
| | `scope: infra` | `#E6E6E6` | Infrastructure or CI/CD |
|
|
380
|
+
| | `scope: api` | `#C2E0C6` | API surface changes |
|
|
301
381
|
|
|
302
382
|
Rules:
|
|
303
383
|
|
|
304
|
-
- Every issue **MUST** have at least one `type:` label and one `priority:` label.
|
|
305
|
-
- `
|
|
384
|
+
- Every issue **MUST** have at least one `type:` label and one `priority:` label, except issues labeled `level: prd` or `level: wave`, which are containers and carry only their `level:` label.
|
|
385
|
+
- Every issue that is not a container carries exactly one `type:` per issue, from the eight `type:` rows above: the label names the kind of work, so a filter on it is trustworthy. When work fits several types, the first in the tie-break order wins: `security > bug > enhancement > refactor > test > docs > chore > tech-debt` (D-85).
|
|
386
|
+
- The tie-break decides a mixed case the same way every time: an issue that is both a bug and a security problem is `type: security`, and a test-only change that also touches docs is `type: test`. Suggest a type from the Conventional Commits prefix of the issue's title (`fix` → `type: bug`, `feat` → `type: enhancement`), and let the user confirm it; never re-type an issue silently.
|
|
387
|
+
- `type: other` is retired, and so are the experiment's `type: prd`, `type: wave` and `type: story`, which `level:` replaces (D-85, D-91). A retired label is never applied to an issue; its definition stays in the repository, marked retired in its description, so closed issues keep their history.
|
|
388
|
+
- Retired labels, in full: `type: other`, `type: prd`, `type: wave`, `type: story`, `status: ready`, `status: in-progress`, the retired `needs: decision`, `needs: approval` and `needs: merge` (D-15), and every `wave:` label (D-91). GitHub's default and other unprefixed labels (`bug`, `documentation`, `enhancement`, `chore`, `story`) are neither retired nor a type; an issue carrying only those is listed under "needs a type" with a suggestion taken from the label (`story` gives none) (D-100).
|
|
389
|
+
- `priority: critical` blocks a wave, PRD or release from shipping, and **MUST** name what it blocks: it carries a native `blocked by` relation from the issue it blocks plus a `**Blocks:** #N — <reason>` body line (D-84). Write the relation with the dependency commands in the Command Map.
|
|
390
|
+
- `priority: high` lands in the current wave or cycle and blocks no ship; `priority: medium` lands in the next; `priority: low` is backlog. Priority says when, not what it blocks: a `high` issue may block another issue and keeps `high` (D-102).
|
|
391
|
+
- Any issue that blocks another carries the `**Blocks:**` line whatever its priority: a `high` issue that blocks another keeps `high` and still carries the line, and the relation is written the same way.
|
|
392
|
+
- A blocking relation is never invented: add one only when the user or the issue text names the blocked issue. A `critical` issue that names none is reported, not linked (D-84).
|
|
393
|
+
- Hierarchy lives only in `level:`; `type:` keeps its meaning as the kind of work. A story issue carries `level: story` beside its `type:` and `priority:` labels.
|
|
394
|
+
- `status:` labels are flags: add one when the condition starts and drop it when it ends. `status: ready` and `status: in-progress` are retired from this taxonomy everywhere, Project or not, because the linked pull request shows that state natively on the issue (FR-7); issues created before this rule keep their labels until a migration pass.
|
|
306
395
|
- `scope:` labels are **RECOMMENDED** for multi-area projects.
|
|
307
396
|
- Custom labels **MAY** be added but **MUST** follow the `<category>: <value>` format.
|
|
308
397
|
|
|
@@ -359,7 +448,11 @@ A milestone tracks the scope of a minor version (`vX.Y`); the tag `vX.Y.0` marks
|
|
|
359
448
|
When invoked with `audit` as input, `github-ops` **MUST**:
|
|
360
449
|
|
|
361
450
|
1. Fetch all open issues and PRs from the target repository.
|
|
362
|
-
2. Check each against the conventions above
|
|
451
|
+
2. Check each against the conventions above, and report these four convention findings for every open issue (AC-16, D-102):
|
|
452
|
+
- **`critical` without a blocking relation:** a `priority: critical` issue for which `gh api repos/{o}/{r}/issues/{n}/dependencies/blocking --paginate` returns no relation, whether or not its body carries a `**Blocks:**` line (D-84, A-72). A relation to an issue that has since closed still exists, so it is not reported; lower the priority once the block is gone.
|
|
453
|
+
- **Zero or several `type:` labels:** an issue with no label from the eight-type set in [Labels](#labels), or with more than one; the retired `type: other`, `type: prd`, `type: wave` and `type: story`, and the unprefixed default labels, count as none (D-85, D-100). Issues labeled `level: prd` or `level: wave`, and tracking issues found by their title prefix (§ Title Format), are exempt, since containers carry no `type:` (A-68). Suggest the tie-break winner for a multi-type issue and the Conventional Commits title prefix's type for an untyped one; never re-type silently.
|
|
454
|
+
- **Retired label on an open issue:** any label in the retired list in [Labels](#labels) on an open issue. Report it for removal from the issue; never delete the label definition (D-91).
|
|
455
|
+
- **Blocking relation without its body line:** a `priority: critical` issue whose `.../dependencies/blocking` returns a relation but whose body has no `**Blocks:** #N — <reason>` line naming the blocked issue (D-102). Suggest the line from the relation; the relation is never removed to clear the finding.
|
|
363
456
|
3. Produce an audit report:
|
|
364
457
|
|
|
365
458
|
```markdown
|
|
@@ -373,6 +466,15 @@ Date: YYYY-MM-DD
|
|
|
373
466
|
| --- | ----- | -------------- | ------------ | -------------- | --------- |
|
|
374
467
|
| 42 | ... | type, priority | ✅ | ❌ missing AC | ❌ none |
|
|
375
468
|
|
|
469
|
+
## Conventions
|
|
470
|
+
|
|
471
|
+
| # | Title | Finding | Suggested fix |
|
|
472
|
+
| --- | ----- | ------------------------------------------------ | ------------------------------------- |
|
|
473
|
+
| 61 | ... | `critical` without a blocking relation | add the relation or lower priority |
|
|
474
|
+
| 62 | ... | `critical` relation without a `**Blocks:**` line | add the line naming the blocked issue |
|
|
475
|
+
| 64 | ... | two `type:` labels (`bug`, `security`) | keep `type: security` (tie-break) |
|
|
476
|
+
| 70 | ... | retired label `status: ready` | take the label off the issue |
|
|
477
|
+
|
|
376
478
|
## Pull Requests
|
|
377
479
|
|
|
378
480
|
| # | Title | Conv. Commit | Description | Branch Format |
|
|
@@ -398,7 +500,32 @@ Date: YYYY-MM-DD
|
|
|
398
500
|
- Labels to create: Z
|
|
399
501
|
```
|
|
400
502
|
|
|
401
|
-
4. Offer to auto-fix violations that can be corrected
|
|
503
|
+
4. Offer to auto-fix violations that can be corrected automatically (labels, title format, missing body sections).
|
|
504
|
+
|
|
505
|
+
---
|
|
506
|
+
|
|
507
|
+
## Migration Mode
|
|
508
|
+
|
|
509
|
+
When invoked with `migrate` as input, `github-ops` takes an existing repository through the projects-tracking migration. The `dev-tasks migrate projects` CLI reads the repository and makes every write; this mode is the conversation around it (D-79). The full procedure, including the Project batch and rollback by hand, is `docs/runbooks/runbook-migrate-to-projects-tracking.md`.
|
|
510
|
+
|
|
511
|
+
Before step 1, create the `chore/<issue-number>-projects-migration` branch (§ Branch Naming), where `<issue-number>` is the issue tracking the migration: step 3 edits the plan file, and step 9 commits it there. Then confirm `docs/roadmap.md` holds the canonical roadmap table. When it does not, stop and hand the conversion to `product-engineer` (Roadmap Conversion (before migration)); resume after its docs PR merges.
|
|
512
|
+
|
|
513
|
+
1. Run `dev-tasks migrate projects --plan`. It is read-only and writes `workstream/migration-projects.md` (or the path given with `--out`) with `Approved: no`. Exit `1`: a `gh` read failed; run it again. Exit `2`: the roadmap has no canonical table, or `--repo` names another repository than the working tree's; go back to the roadmap check above, or run it from the right clone. Exit `11`: `gh` is missing or unauthenticated, or `gh repo view` failed; ask the user to run `gh auth login`, then run it again. Exit `14`: the file at `--out` already holds an applied plan or is not a migration plan; keep it as the record and pass another `--out`.
|
|
514
|
+
2. Present each review item as one question with a recommendation, one question per message: an unmapped issue (`<PRD key> <Phase/Wave>`: the roadmap row's PRD link text and its `Phase/Wave` cell, such as `projects-tracking 3`; or `standalone`), an issue that needs a type (recommend the Suggested column), a `priority: critical` issue that needs a blocking link (`#<issue it blocks>` or `lower priority to high`; for a `#<issue it blocks>` answer, tell the user that `--apply` writes only the native link, so they add the issue's `**Blocks:** #N — <reason>` line themselves, D-84), and each Information note (`yes`, or blank). Report state files and roadmap notes for the user to fix by hand. Never answer a review item on the user's behalf.
|
|
515
|
+
3. Write each answer into the plan file's Answer column, exactly as the user gave it, and change nothing else in the file.
|
|
516
|
+
4. Run `dev-tasks migrate projects --plan` again. It reads the answers, rebuilds the batches from them and resets `Approved: no`; `--apply` never turns an answer into a write (A-50). When an answer is listed back as unusable, ask that question again and repeat this step.
|
|
517
|
+
5. Ask the user for explicit approval of the rebuilt plan file, after showing its batch counts and the rows of batches 1 to 6. Approval is a reply that approves this plan; silence, a question, a change request or approval of an earlier plan is not approval.
|
|
518
|
+
6. Set the header line to exactly `Approved: yes` once the user has approved, and edit no other line. Any later `--plan` run resets it, and approval is asked again.
|
|
519
|
+
7. Run `dev-tasks migrate projects --apply`. Pass `--plan-file <path>` when the plan is not at `workstream/migration-projects.md`. Exit `0`: every write applied. Exit `1`: a write is `failed`, a repository read failed, a state could not be written back, or the run was interrupted; report the failed rows and the message, and run `--apply` again once the cause is fixed: it resumes and never repeats a `done` write (D-88). Exit `14`: read the cause in its message. Another run holds the lock: wait for it to finish, then run `--apply` again; do not run `--plan`. The lock is stale (`workstream/.migration-projects.lock` left by a killed process, with no run alive): follow the runbook's Escalation. The plan is not approved: go back to step 5. A row was edited after the plan was generated (the digest no longer matches): undo the edit, or, while every row is still `pending`, run `--plan` again and go back to step 5. The plan file changed while `--apply` was starting: run `--apply` again. The repository changed while every row is still `pending`: run `--plan` again and go back to step 5. Never run `--plan` over a partly applied plan: it refuses with exit `14` (A-65), and a partly applied plan only resumes with `--apply`. Exit `2`: the plan file is unparsable or belongs to another repository. Exit `11`: as in step 1.
|
|
520
|
+
8. Hand the Project batch to the user: batch 7 of the plan file, which `--apply` prints at the end and never runs. Point the user to the runbook's Project cleanup step and to the batch 7 steps the `--apply` summary prints, which carry the exact commands and the Workflows-page steps, and have them copy each command from there, never from the plan file, whose table cells escape `|` as `\|`; do not restate them. The user runs each step with their own session and sets its State to `done`.
|
|
521
|
+
9. Commit the plan file and open the chore PR: once every batch 7 row reads `done` (the user's ticks), run `git add -f workstream/migration-projects.md` on the `chore/<issue-number>-projects-migration` branch, commit, push, and open a PR against the default branch (§ Pull Request Conventions), so the per-write states are the record of what the migration changed (D-93). Only the user merges it. A migration run inside a planner wave opens this PR against the wave's integration branch instead, where the planner merges it after its story gates, so the record ships in the consolidated PR the user merges (D-112).
|
|
522
|
+
|
|
523
|
+
Rules:
|
|
524
|
+
|
|
525
|
+
- `github-ops` **MUST NOT** run `--apply` without the user's explicit approval of the current plan file (D-80). A declined approval writes nothing and keeps the plan file.
|
|
526
|
+
- `github-ops` **MUST NOT** write the Project, in this mode or any other: the user runs batch 7 (D-22, D-81).
|
|
527
|
+
- An unmapped issue answered `standalone` gets no hierarchy write.
|
|
528
|
+
- `github-ops` **MUST NOT** edit a row's State, ID, Action, Target or Detail by hand; only the CLI writes batch 1 to 6 States, and only the user ticks batch 7.
|
|
402
529
|
|
|
403
530
|
---
|
|
404
531
|
|
|
@@ -429,6 +556,7 @@ Rules:
|
|
|
429
556
|
5. **Idempotent operations:** Running `github-ops` on an already-compliant artifact **MUST** produce no changes.
|
|
430
557
|
6. **No destructive actions without confirmation:** Renaming issues, deleting labels, or closing milestones **MUST** require explicit user approval.
|
|
431
558
|
7. **No merging into `main` without user approval:** PRs targeting `main` **MUST NOT** be merged by any agent. Only the user may approve and merge.
|
|
559
|
+
8. **No shell-interpolated multi-line bodies:** Every PR/issue body or structured comment **MUST** be created via `gh --body-file` (or, when an MCP server is used instead, its native body parameter), and **MUST** be read back and verified to render with intact headings/line breaks before the operation is considered complete (see [Multi-Line Body Formatting](#multi-line-body-formatting)).
|
|
432
560
|
|
|
433
561
|
---
|
|
434
562
|
|
|
@@ -251,12 +251,17 @@ new category. Never hold a PR on it.
|
|
|
251
251
|
|
|
252
252
|
`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.
|
|
253
253
|
|
|
254
|
-
**
|
|
254
|
+
**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.
|
|
255
255
|
|
|
256
|
-
|
|
257
|
-
|
|
258
|
-
|
|
259
|
-
|
|
256
|
+
- 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.
|
|
257
|
+
- 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.
|
|
258
|
+
|
|
259
|
+
**Trigger** (PRD-level rollup audits, and story audits whose story completes a phase or wave). Report the finding when any of these is true:
|
|
260
|
+
|
|
261
|
+
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).
|
|
262
|
+
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.
|
|
263
|
+
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.
|
|
264
|
+
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.
|
|
260
265
|
|
|
261
266
|
**Not a finding:** rows for PRDs outside the audited scope; a row left `In progress` while some of its stories are still open.
|
|
262
267
|
|