@llipe.com/dev-tasks 0.16.4 → 0.17.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (110) hide show
  1. package/.claude/agents/developer.md +8 -3
  2. package/.claude/agents/github-ops.md +186 -58
  3. package/.claude/agents/technical-writer.md +1 -1
  4. package/.claude/agents/verifier.md +10 -5
  5. package/.claude/commands/planner.md +109 -14
  6. package/.claude/commands/product-engineer.md +27 -3
  7. package/.claude/hooks/git-guard.sh +200 -27
  8. package/.claude/skills/activity-init/SKILL.md +4 -0
  9. package/.claude/skills/activity-publish-github/SKILL.md +84 -15
  10. package/.claude/skills/implement/SKILL.md +29 -13
  11. package/.claude/skills/memo-cli-usage/REFERENCE.md +1 -0
  12. package/.claude/skills/memo-cli-usage/SKILL.md +3 -1
  13. package/.claude/skills/plan/SKILL.md +6 -0
  14. package/.github/agents/developer.agent.md +8 -3
  15. package/.github/agents/github-ops.agent.md +181 -63
  16. package/.github/agents/planner.agent.md +122 -27
  17. package/.github/agents/product-engineer.agent.md +27 -3
  18. package/.github/agents/technical-writer.agent.md +1 -1
  19. package/.github/agents/verifier.agent.md +10 -5
  20. package/.github/instructions/implement.instructions.md +29 -13
  21. package/.github/instructions/plan.instructions.md +6 -0
  22. package/.github/skills/activity-init/SKILL.md +4 -0
  23. package/.github/skills/activity-publish-github/SKILL.md +84 -15
  24. package/.github/skills/memo-cli-usage/REFERENCE.md +1 -0
  25. package/.github/skills/memo-cli-usage/SKILL.md +3 -1
  26. package/.kiro/agents/developer.md +8 -3
  27. package/.kiro/agents/github-ops.md +181 -63
  28. package/.kiro/agents/planner.md +122 -27
  29. package/.kiro/agents/product-engineer.md +27 -3
  30. package/.kiro/agents/technical-writer.md +1 -1
  31. package/.kiro/agents/verifier.md +10 -5
  32. package/.kiro/skills/activity-init/SKILL.md +4 -0
  33. package/.kiro/skills/activity-publish-github/SKILL.md +84 -15
  34. package/.kiro/skills/memo-cli-usage/REFERENCE.md +1 -0
  35. package/.kiro/skills/memo-cli-usage/SKILL.md +3 -1
  36. package/.kiro/steering/implement.md +29 -13
  37. package/.kiro/steering/plan.md +6 -0
  38. package/AGENTS.md +2 -0
  39. package/AGENTS.md.template +2 -0
  40. package/CHANGELOG.md +31 -0
  41. package/README.md +79 -7
  42. package/TESTING.md +62 -1
  43. package/dist/bin/dev-tasks.d.ts +1 -1
  44. package/dist/bin/dev-tasks.js +126 -4
  45. package/dist/bin/dev-tasks.js.map +1 -1
  46. package/dist/bin/parse-args.d.ts +49 -1
  47. package/dist/bin/parse-args.d.ts.map +1 -1
  48. package/dist/bin/parse-args.js +132 -11
  49. package/dist/bin/parse-args.js.map +1 -1
  50. package/dist/core/checks/index.d.ts +2 -0
  51. package/dist/core/checks/index.d.ts.map +1 -1
  52. package/dist/core/checks/index.js +1 -0
  53. package/dist/core/checks/index.js.map +1 -1
  54. package/dist/core/checks/roadmap.d.ts +40 -0
  55. package/dist/core/checks/roadmap.d.ts.map +1 -0
  56. package/dist/core/checks/roadmap.js +78 -0
  57. package/dist/core/checks/roadmap.js.map +1 -0
  58. package/dist/core/migrate-projects/answers.d.ts +63 -0
  59. package/dist/core/migrate-projects/answers.d.ts.map +1 -0
  60. package/dist/core/migrate-projects/answers.js +79 -0
  61. package/dist/core/migrate-projects/answers.js.map +1 -0
  62. package/dist/core/migrate-projects/apply.d.ts +51 -0
  63. package/dist/core/migrate-projects/apply.d.ts.map +1 -0
  64. package/dist/core/migrate-projects/apply.js +828 -0
  65. package/dist/core/migrate-projects/apply.js.map +1 -0
  66. package/dist/core/migrate-projects/classify.d.ts +93 -0
  67. package/dist/core/migrate-projects/classify.d.ts.map +1 -0
  68. package/dist/core/migrate-projects/classify.js +170 -0
  69. package/dist/core/migrate-projects/classify.js.map +1 -0
  70. package/dist/core/migrate-projects/conventions.d.ts +118 -0
  71. package/dist/core/migrate-projects/conventions.d.ts.map +1 -0
  72. package/dist/core/migrate-projects/conventions.js +213 -0
  73. package/dist/core/migrate-projects/conventions.js.map +1 -0
  74. package/dist/core/migrate-projects/gh.d.ts +40 -0
  75. package/dist/core/migrate-projects/gh.d.ts.map +1 -0
  76. package/dist/core/migrate-projects/gh.js +115 -0
  77. package/dist/core/migrate-projects/gh.js.map +1 -0
  78. package/dist/core/migrate-projects/index.d.ts +61 -0
  79. package/dist/core/migrate-projects/index.d.ts.map +1 -0
  80. package/dist/core/migrate-projects/index.js +183 -0
  81. package/dist/core/migrate-projects/index.js.map +1 -0
  82. package/dist/core/migrate-projects/local-reader.d.ts +8 -0
  83. package/dist/core/migrate-projects/local-reader.d.ts.map +1 -0
  84. package/dist/core/migrate-projects/local-reader.js +30 -0
  85. package/dist/core/migrate-projects/local-reader.js.map +1 -0
  86. package/dist/core/migrate-projects/map.d.ts +36 -0
  87. package/dist/core/migrate-projects/map.d.ts.map +1 -0
  88. package/dist/core/migrate-projects/map.js +75 -0
  89. package/dist/core/migrate-projects/map.js.map +1 -0
  90. package/dist/core/migrate-projects/plan.d.ts +71 -0
  91. package/dist/core/migrate-projects/plan.d.ts.map +1 -0
  92. package/dist/core/migrate-projects/plan.js +638 -0
  93. package/dist/core/migrate-projects/plan.js.map +1 -0
  94. package/dist/core/migrate-projects/planfile.d.ts +149 -0
  95. package/dist/core/migrate-projects/planfile.d.ts.map +1 -0
  96. package/dist/core/migrate-projects/planfile.js +608 -0
  97. package/dist/core/migrate-projects/planfile.js.map +1 -0
  98. package/dist/core/migrate-projects/roadmap.d.ts +43 -0
  99. package/dist/core/migrate-projects/roadmap.d.ts.map +1 -0
  100. package/dist/core/migrate-projects/roadmap.js +54 -0
  101. package/dist/core/migrate-projects/roadmap.js.map +1 -0
  102. package/dist/core/migrate-projects/snapshot.d.ts +91 -0
  103. package/dist/core/migrate-projects/snapshot.d.ts.map +1 -0
  104. package/dist/core/migrate-projects/snapshot.js +285 -0
  105. package/dist/core/migrate-projects/snapshot.js.map +1 -0
  106. package/dist/core/migrate-projects/summary.d.ts +27 -0
  107. package/dist/core/migrate-projects/summary.d.ts.map +1 -0
  108. package/dist/core/migrate-projects/summary.js +35 -0
  109. package/dist/core/migrate-projects/summary.js.map +1 -0
  110. package/package.json +1 -1
@@ -118,6 +118,7 @@ memo write \
118
118
  --entry-type decision \
119
119
  --source agent \
120
120
  --provenance "<csv of episodic entry ids this consolidates, if any>" \
121
+ --on-duplicate create-new \
121
122
  --json
122
123
  ```
123
124
 
@@ -166,7 +167,8 @@ A `semantic` entry with `--source agent` **MUST** carry `--provenance <csv>` unl
166
167
  ## Agent Mode Rules
167
168
 
168
169
  - Always pass `--json` for parseable output
169
- - Always pass `--on-duplicate consolidate` for writes
170
+ - Always pass `--on-duplicate` for writes; in `--json` mode memo-cli fails on a duplicate without it
171
+ - Pass `create-new` for distinct decisions, one entry per decision row (a feature's decision write-back); pass `consolidate` only when restating or updating the same decision, such as re-writing an entry after an amendment on the same story and commit to correct its rationale (D-78)
170
172
  - Never log API keys or secrets
171
173
  - Bulk delete is blocked in `--json` mode (safety guard)
172
174
 
@@ -123,10 +123,26 @@ When `workstream/decisions-<feature>.md` exists and was read per step 2 above:
123
123
  - If drift is detected between local and GitHub, you **MUST** reconcile immediately and report the reconciliation.
124
124
  - 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.
125
125
 
126
- ### Progress Updates
127
-
128
- - You **SHOULD** add brief issue or PR comments for major milestones or meaningful changes.
129
- - You **SHOULD** route issue/PR comment updates through `github-ops` whenever possible.
126
+ ### Status Comment
127
+
128
+ - 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.
129
+ - You **SHOULD** route the status-comment write through `github-ops` whenever possible; when delegation is unavailable, run the commands below directly.
130
+ - Procedure, for story issue `{n}` of `repos/{o}/{r}`:
131
+ 1. Find the comment by its marker: `gh api repos/{o}/{r}/issues/{n}/comments --paginate --jq '.[] | select(.body | startswith("<!-- dev-tasks:status -->")) | .id'`.
132
+ 2. Absent → create it: `gh issue comment {n} --body-file <path>`.
133
+ 3. Present → edit it in place: `gh api -X PATCH repos/{o}/{r}/issues/comments/{id} -F body=@<path>`.
134
+ 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.
135
+ 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.
136
+ - 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.
137
+
138
+ ### Wave Status Update (Main Thread Only)
139
+
140
+ - Under the `planner`, the wave's status comment belongs to the planner: report `wave_status: owned-by-planner` and do nothing further.
141
+ - 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`.
142
+ - `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`.
143
+ - 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.
144
+ - `404` → the story has no parent (published before the hierarchy convention); report `wave_status: skipped(no parent)`. This is expected, not an error.
145
+ - A refused read or write → `wave_status: failed(<reason>)`; it never blocks the sub-task.
130
146
 
131
147
  ---
132
148
 
@@ -157,19 +173,19 @@ When `workstream/decisions-<feature>.md` exists and was read per step 2 above:
157
173
  - PRs targeting **`main`**: the **user** reviews and approves.
158
174
 
159
175
  11. The PR **MUST** be merged by the authorized party (planner for integration branches, user for `main`).
160
- 12. You **MUST NOT** close the GitHub Issue until the PR is approved **AND** merged.
161
- 13. You **MUST NOT** close the issue while the PR is still in draft or pending review.
176
+ 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.
177
+ 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.
162
178
  14. You **MUST** notify the user when the PR is ready for review — explicitly inform them so they can review and merge.
163
179
 
164
180
  ---
165
181
 
166
182
  ## GitHub Execution Rules Summary
167
183
 
168
- | Phase | Rule |
169
- | ------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
170
- | **Before coding** | Confirm issue open → Create branch (`github-ops`) → First commit → Open draft PR (`github-ops`) → Sync checklists |
171
- | **During coding** | One sub-task at a time → Mark `[x]` locally + GitHub → Wait for approval |
172
- | **Before closing** | All ACs verified → Quality gates pass (test/lint/format/typecheck/audit) → migration confirmation/apply/verify (when applicable) → docs drift check clear → coverage_gate recorded → verifier audit run + summary posted (non-blocking on drift) → PR ready → Approved → Merged → Then close issue |
184
+ | Phase | Rule |
185
+ | ------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
186
+ | **Before coding** | Confirm issue open → Create branch (`github-ops`) → First commit → Open draft PR (`github-ops`) → Sync checklists |
187
+ | **During coding** | One sub-task at a time → Mark `[x]` locally + GitHub → Update the status comment (`github-ops` § Status comment) → Wait for approval |
188
+ | **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) |
173
189
 
174
190
  ---
175
191
 
@@ -182,7 +198,7 @@ When `workstream/decisions-<feature>.md` exists and was read per step 2 above:
182
198
  ## Final Instructions
183
199
 
184
200
  1. You **MUST** always respect the task list execution order.
185
- 2. You **MUST** keep the GitHub Issue updated with checklist and progress comments.
201
+ 2. You **MUST** keep the GitHub Issue updated with its checklist and its status comment.
186
202
  3. You **MUST** ensure branch, PR, and issue naming follow `github-ops` conventions.
187
203
  4. You **MUST** stop after each sub-task and request user approval.
188
- 5. You **MUST NOT** close a GitHub Issue without confirming the PR has been reviewed, approved, and merged.
204
+ 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.
@@ -26,8 +26,10 @@ This activity adapts to the input — it works with a user stories file (from th
26
26
  2. **Review Available Work:** You **MUST** read the source and list available stories or the issue scope.
27
27
  3. **Select Scope:** In Stories Mode, you **MUST** ask which stories to include. In Issue Mode, the scope is the single issue.
28
28
  4. **Generate Task List:** You **MUST** produce a `tasks-*.md` file in the required format.
29
+ - **Plan header:** The header carries `Source:` (the source document) and, on the next line, `Wave issue: #N`, its own line with no bold or backticks so the planner can read it at Phase 0. In Stories Mode, take the number from the publication report's `Wave issue` line (`workstream/github-publication-<prd-name>.md`, written by `activity-publish-github`). When the report predates the tracking hierarchy or has no `Wave issue` line, or in Issue Mode, write `Wave issue: none` and add a `> Note:` line under it saying the planner will search for the wave issue at Phase 0. When the plan fully resolves follow-up issues outside its story set, add a `Resolves: #N, #M` line after `Wave issue:`; the planner carries `Closes #N` for each on the consolidated PR (planner D-74). Omit the line when there are none.
29
30
  5. **Publish to GitHub:** You **MUST** update the corresponding GitHub Issue(s) with the task checklist by delegating to `github-ops` whenever possible.
30
31
  6. **Save Output.**
32
+ 7. **Set the Task Plan Line:** When the plan header reads `Wave issue: #N`, set the wave issue body's `Task plan:` line under `## Artifacts` to a root-relative link to the saved task list, after the file is saved: read the body with `gh issue view <N> --json body --jq .body` into a file, change only that line, and write it back with `gh issue edit <N> --body-file <path>`. With `Wave issue: none` there is no wave issue body to edit, and the line stays `pending` until a later plan names the wave issue.
31
33
 
32
34
  ## Package Manager and Command Standards
33
35
 
@@ -56,6 +58,9 @@ The task list **MUST** follow this structure:
56
58
  ```markdown
57
59
  # Implementation Plan - [Name]
58
60
 
61
+ Source: `[path to the user stories file or refined issue]`
62
+ Wave issue: #N
63
+
59
64
  ## Relevant Files
60
65
 
61
66
  - `path/to/file1.ts` - [Description]
@@ -184,4 +189,5 @@ If this is a **greenfield project** or a **new component**, you **MUST** include
184
189
  8. For schema/data-model changes, you **MUST** include migration lifecycle tasks and an explicit user-confirmation gate before applying migrations unless an opt-out rationale is documented.
185
190
  9. You **MUST** update the corresponding GitHub Issue(s) with the task checklist by delegating to `github-ops` whenever possible. If no issue exists, you **MUST** ask the user whether to create one first.
186
191
  10. You **MUST** save the task list file.
192
+ 10a. When the wave issue is known, you **MUST** set its body's `Task plan:` Artifacts line to the saved task list (Process step 7).
187
193
  11. You **MUST** inform the user they can now use the **implement** activity to start coding.
package/AGENTS.md CHANGED
@@ -97,6 +97,8 @@ Kiro (`.kiro/hooks/`) and Claude Code (`.claude/hooks/`, wired via `.claude/sett
97
97
 
98
98
  Hook enforcement is best-effort and fails open on unexpected errors, with one exception: if `git-guard` cannot verify a `gh pr merge`'s (or its MCP equivalent's) base branch — the `gh pr view` lookup fails (`gh` missing, unauthenticated, or a network error), or an MCP merge/auto-merge call omits enough `tool_input` to identify the PR at all — it fails **closed** and blocks the call, since an unverified base could be the default branch.
99
99
 
100
+ The Claude Code `git-guard` judges pushes, merges and tags only by commands that run: it ignores quoted-heredoc text and `printf`/`echo`/`cat` text when it can show that text is never executed, and `--body-file <path>` remains the recommended way to pass an issue or PR body.
101
+
100
102
  **Hooks are advisory, not the gate.** Every hook in this table is a best-effort, local, pattern-matching check over a command string or a structured tool-input shape — not a real parser, and not a completeness guarantee against every future command form or tool surface (a new MCP server, a future first-party tool) that could reopen the same class of gap. **GitHub branch protection on the default branch — require a PR, require ≥1 approving review, require passing status checks, disable force-push and branch deletion — is the actual, server-side, unbypassable-by-any-tool-surface control.** Hooks narrow the window and catch the common cases; they do not replace branch protection. Configure it per the README "Configure branch protection" step and `activity-init`'s Repository Setup section.
101
103
 
102
104
  ## General Agent Guidelines
@@ -97,6 +97,8 @@ Kiro (`.kiro/hooks/`) and Claude Code (`.claude/hooks/`, wired via `.claude/sett
97
97
 
98
98
  Hook enforcement is best-effort and fails open on unexpected errors, with one exception: if `git-guard` cannot verify a `gh pr merge`'s (or its MCP equivalent's) base branch — the `gh pr view` lookup fails (`gh` missing, unauthenticated, or a network error), or an MCP merge/auto-merge call omits enough `tool_input` to identify the PR at all — it fails **closed** and blocks the call, since an unverified base could be the default branch.
99
99
 
100
+ The Claude Code `git-guard` judges pushes, merges and tags only by commands that run: it ignores quoted-heredoc text and `printf`/`echo`/`cat` text when it can show that text is never executed, and `--body-file <path>` remains the recommended way to pass an issue or PR body.
101
+
100
102
  **Hooks are advisory, not the gate.** Every hook in this table is a best-effort, local, pattern-matching check over a command string or a structured tool-input shape — not a real parser, and not a completeness guarantee against every future command form or tool surface (a new MCP server, a future first-party tool) that could reopen the same class of gap. **GitHub branch protection on the default branch — require a PR, require ≥1 approving review, require passing status checks, disable force-push and branch deletion — is the actual, server-side, unbypassable-by-any-tool-surface control.** Hooks narrow the window and catch the common cases; they do not replace branch protection. Configure it per the README "Configure branch protection" step and `activity-init`'s Repository Setup section.
101
103
 
102
104
  ## General Agent Guidelines
package/CHANGELOG.md CHANGED
@@ -5,6 +5,37 @@ All notable changes to this project will be documented in this file.
5
5
  The format is based on [Keep a Changelog](https://keepachangelog.com/),
6
6
  and this project adheres to [Semantic Versioning](https://semver.org/).
7
7
 
8
+ ## [0.17.1] - 2026-11-03
9
+
10
+ ### Fixed
11
+
12
+ - fix(hooks): treat an escaped redirect character as literal in git-guard
13
+ - fix(hooks): judge git-guard pushes by executed commands, not heredoc text
14
+ - fix(release): attach the bundle to an existing release; record 0.17.0 (#337)
15
+
16
+ ### Changed
17
+
18
+ - Merge pull request #344 from llipe/chore/pre-release-format
19
+ - chore: apply prettier to docs and archived planner state
20
+ - Merge pull request #341 from llipe/issue/339-git-guard-heredoc-push
21
+ - test(hooks): isolate each executed-view trigger and document the runbook
22
+ - test(hooks): pin git-guard executed-view cases for #339
23
+ - Merge pull request #336 from llipe/chore/projects-tracking-phase-3-closeout
24
+ - Merge pull request #338 from llipe/chore/337-release-bundle-existing-release
25
+ - chore(roadmap): close out projects-tracking-phase-3
26
+
27
+ ## [0.17.0] - 2026-10-27
28
+
29
+ ### Added
30
+
31
+ - feat(cli): `dev-tasks migrate projects --plan` writes a reviewable, read-only projects-tracking migration plan (#320)
32
+ - feat(cli): `dev-tasks migrate projects --apply` runs an approved migration plan's batches 1 to 6, records each write's state in the plan file and resumes from it; it never runs the Project batch, deletes nothing and refuses an unapproved, edited, locked or stale plan with exit `14` (#322)
33
+
34
+ ### Changed
35
+
36
+ - fix(cli): `migrate projects --plan` exits `2` with a pointer to product-engineer's roadmap conversion when `docs/roadmap.md` has no canonical table, instead of writing a plan with a roadmap note (#321)
37
+ - fix(cli): every command now exits `2` on an unknown flag, naming it, and on a value flag given without a value (`--profile`, `--pin`, `--repo`, `--out`, `--plan-file`, including an empty `--flag=`), instead of silently ignoring it; `dev-tasks migrate --plan`/`--apply` without the `projects` sub-verb exits `2` with a hint and never runs the legacy migration. A value that starts with `-` is given as `--flag=value` (#320)
38
+
8
39
  ## [0.16.4] - 2026-10-06
9
40
 
10
41
  ### Changed
package/README.md CHANGED
@@ -116,13 +116,13 @@ dev-tasks status # compare installed vs latest version
116
116
 
117
117
  ### Exit codes
118
118
 
119
- | Code | Meaning |
120
- | ---- | --------------------------------------- |
121
- | 0 | Success |
122
- | 1 | Unexpected error |
123
- | 2 | Incorrect usage |
124
- | 11 | Dependency check failed (`doctor`) |
125
- | 14 | Reconciliation conflict (edited fields) |
119
+ | Code | Meaning |
120
+ | ---- | ---------------------------------------------------------------------------------------------------------------------- |
121
+ | 0 | Success |
122
+ | 1 | Unexpected error, or a write that failed (`migrate projects --apply`) |
123
+ | 2 | Incorrect usage, no canonical `docs/roadmap.md` table, or an unparsable or foreign migration plan (`migrate projects`) |
124
+ | 11 | Dependency check failed (`doctor`), or `gh` missing or unauthenticated (`migrate projects`) |
125
+ | 14 | Reconciliation conflict (edited fields; an unapproved, edited, locked, changing or stale migration plan) |
126
126
 
127
127
  Full contract, including retirement history for codes no longer in use: [`core/exit-codes.ts`](core/exit-codes.ts).
128
128
 
@@ -139,6 +139,8 @@ dev-tasks unpin # Remove the version pin
139
139
  dev-tasks doctor # Check Node ≥24, git ≥2.37, cache writable
140
140
  dev-tasks migrate # Migrate from legacy shell-script install
141
141
  dev-tasks migrate docs [--force] # Rename the foundation docs to their current names
142
+ dev-tasks migrate projects --plan # Write a reviewable projects-tracking migration plan (read-only)
143
+ dev-tasks migrate projects --apply # Apply an approved migration plan, recording every write
142
144
  ```
143
145
 
144
146
  ### Version Pinning
@@ -196,6 +198,76 @@ Files you own are yours to update. The command reports which of them still
196
198
  name the old documents; it does not edit them, and neither does
197
199
  `dev-tasks update`.
198
200
 
201
+ ### Projects-Tracking Migration Plan
202
+
203
+ `dev-tasks migrate projects --plan` reads an existing repository through `gh`
204
+ and writes a migration plan to `workstream/migration-projects.md`: the lists
205
+ that need your answer (stories it could not map to a wave, issues that need
206
+ a `type:`, `priority: critical` issues with no blocking link, planner state
207
+ files without a `Wave issue:` line, roadmap notes) and the write batches the
208
+ projects-tracking scope rules permit, from labels to the PRD status comment,
209
+ ending with the Project cleanup steps you run yourself. It is **read-only**:
210
+ nothing on GitHub changes, and the plan file holds issue numbers, titles and
211
+ label names, never issue bodies.
212
+
213
+ A story maps to its wave by its `**Story:**` body line, then by a `phase:`
214
+ label within the PRD named in its `[PRD-<name>]` title prefix; anything else
215
+ is listed for you, never guessed. Answer in the plan's Answer columns and run
216
+ `--plan` again: it reads your answers, rebuilds the batches and resets
217
+ `Approved: no`.
218
+
219
+ ```bash
220
+ dev-tasks migrate projects --plan # Plan for the current repository
221
+ dev-tasks migrate projects --plan --out /tmp/plan.md # Write the plan elsewhere
222
+ dev-tasks migrate projects --plan --json # Summary as JSON
223
+ ```
224
+
225
+ It needs `gh` authenticated to github.com with the `repo` scope, checked
226
+ first (exit `11` with the `gh auth login` hint otherwise), and it must run
227
+ inside a clone of the repository: `--repo` may only confirm it (exit `2`
228
+ otherwise). It exits `2` when `docs/roadmap.md` has no canonical table:
229
+ run product-engineer's roadmap conversion first. It refuses with exit `14`
230
+ to overwrite a plan file that already records applied writes.
231
+
232
+ `dev-tasks migrate projects --apply [--plan-file <path>] [--json]` applies the
233
+ plan once you have reviewed it and set its header to exactly `Approved: yes`.
234
+ It runs batches 1 to 6 in order and records each write's state in the plan
235
+ file after its call (`done`, `done(#N)` for a created issue,
236
+ `failed(<reason>)`, `skipped(already applied)`, `skipped(depends on W-NNN)`),
237
+ so an interrupted or failed run is resumed by running it again: it never
238
+ repeats a `done` write, and it checks each write's target first, so a write
239
+ that landed without being recorded is found, not made twice. The target
240
+ check reads the repository as the run's start-of-run snapshot plus the run's
241
+ own writes; a status comment, a sub-issue parent and a blocking list are
242
+ read live just before their write. It exits `2` for a plan file that is
243
+ missing or unparsable (a plan with no `Approved:` header at all, such as a
244
+ lower-case `approved: yes`, is unparsable), for a repository other than the
245
+ plan's, or when `docs/roadmap.md` lost its canonical table. It refuses with
246
+ exit `14`, writing nothing, when the header is not exactly one
247
+ `Approved: yes` line, when a row was edited after the plan was generated
248
+ (`Plan digest:`), when another run holds `workstream/.migration-projects.lock`,
249
+ when the plan file changes while `--apply` is starting, or, before any write
250
+ is recorded, when the repository changed since the plan (regenerate it with
251
+ `--plan`). It exits `1` when any write failed or the run was interrupted
252
+ (`SIGINT`, `SIGTERM` and `SIGHUP` kill the `gh` call in flight, release the
253
+ lock and keep the states so far).
254
+
255
+ If the very first write lands but its state cannot be written back (a full
256
+ disk, a killed process), every row still reads `pending`, so the next
257
+ `--apply` sees a changed repository and exits `14`. Run `--plan` again,
258
+ approve the new plan, and run `--apply`: the new plan does not propose the
259
+ write that landed, so no write is repeated. It never runs batch 7, never makes a
260
+ Project call, never deletes a label or anything else, and never writes a
261
+ title or a Status: it prints batch 7's steps for you to run. Answers in the
262
+ review tables become writes only through a fresh `--plan`.
263
+
264
+ The whole procedure, from the roadmap check to the committed plan file and
265
+ rollback by hand, is
266
+ [`docs/runbooks/runbook-migrate-to-projects-tracking.md`](docs/runbooks/runbook-migrate-to-projects-tracking.md).
267
+ github-ops' migration mode walks you through it: it asks one question per
268
+ review item, writes your answers into the plan, runs `--apply` only after you
269
+ approve, and leaves the Project batch to you.
270
+
199
271
  **Note the asymmetry with the bare `migrate` command.** `dev-tasks migrate`
200
272
  (no sub-verb) migrates a legacy shell-script install and applies its change
201
273
  immediately. `dev-tasks migrate docs` proposes by default. The difference is
package/TESTING.md CHANGED
@@ -1,5 +1,5 @@
1
1
  ---
2
- version: 1.0
2
+ version: 1.13
3
3
  name: Testing Standard
4
4
  description: Canonical testing contract for dev-tasks — declares test layers, runners, commands, fixtures, and coverage policy.
5
5
  status: filled
@@ -123,6 +123,8 @@ When coverage cannot be measured, report `coverage_gate: SKIPPED(<non-empty reas
123
123
 
124
124
  Tests primarily use deterministic fixture repositories under `test/fixtures/`, temporary directories rooted in the OS temp directory, and subprocess execution for CLI entry points. Fixture projects that intentionally model harness defects are excluded from Vitest collection. No duplicated token builders or client mocks were detected, and no global `fetch`/timer stubs were detected. Any future global stub must be restored explicitly.
125
125
 
126
+ `migrate projects` (`core/migrate-projects/`) is tested against an in-memory GitHub model (`test/unit/migrate-projects/helpers/fake-github.ts`) served through an injected `GhRunner`, never the network. Its read-only guarantee is checked by a write classifier written in the test (`helpers/is-write.ts`), never imported from production, so the property is not checked by the code it checks. The Layer 2 CLI tests run the real binary and the real `execFile("gh")` runner against a fake `gh` (`test/fixtures/migrate-projects/fake-gh/gh`) placed alone with a `node` symlink in a purpose-built `PATH` directory, with the clock injected through `DEV_TASKS_NOW`. Property tests use a seeded PRNG (`helpers/prng.ts`, seed from `MIGRATE_SEED`, printed in every failure message), not a property-testing dependency. The model also serves issue comments, for the PRD status-comment marker, and `helpers/model-apply.ts` replays a plan's batch 1 to 6 rows onto it from the documented Detail grammar, on the test side, so "re-planning after the writes proposes none" (RT-12) is not checked by the planner itself. The AC-11 expected plan in `ac11-fixture.test.ts` is written by hand, never regenerated from the code (RV-3). For `--apply`, `helpers/fake-github-writes.ts` is the model's write half, written from what `gh` and GitHub do with each write argv rather than from `apply.ts`, so the `apply-*.test.ts` files assert the resulting repository state; it throws on a call `--apply` must never make (a Project call, `label delete`, a title edit, an inline `--body`), and its `Intercept` answers a write with a failure, an interruption before it, or an interruption after it landed. `helpers/apply-run.ts` runs `--apply` in process with an in-memory plan store and lock, and `helpers/random-repo.ts` feeds the RT-11 walk. The CLI tests build an `--apply` scenario by running it in process over a copy of the model and replaying the answers through the fake `gh`, which keys a body-file path as `<file>` and can slow each answer (`FAKE_GH_DELAY_MS`) so a test interrupts a run between calls. `apply-writeback.test.ts` wraps `node:fs` with `vi.mock` so a write stops half-way and the rename fails, the way a killed process would, to show the plan file is old or new and never truncated (EC-140).
127
+
126
128
  Gold or generated fixture files must record their source and regeneration path where applicable. Generated catalog outputs are test artifacts, not coverage evidence, and must not be used as durable validation without freshness and scope checks.
127
129
 
128
130
  ## Security-Negative Tests
@@ -143,3 +145,62 @@ The test suite runs to completion, and its only known intermittent failure is th
143
145
  3. CI/deploy wiring: the pull request half is resolved by #248 — `validate.yml` runs `pnpm run validate` on every pull request. Still open: no deploy workflow invokes the aggregate test command, and the pull request check is not yet a _required_ status check in branch protection (a manual repository setting, see `docs/runbooks/runbook-configure-branch-protection.md`). Expected state: every CI test job and deploy quality gate runs `pnpm run test` or `pnpm run validate`, and the pull request check is required.
144
146
  4. Runtime alignment: `validate.yml` and `publish-npm.yml` use Node 24 while local development uses Node 26. Both runtimes pass the full test suite (the HEAD-dependent test in item 5 aside, which is not runtime-related), so there is no blocker to release. Future work may align these to a single supported range or explicitly document the tested range in the engine constraint.
145
147
  5. HEAD-dependent test: `test/unit/infra-script-contract.test.ts`, case `deploy.sh prod — ref rules (AC-4) > refuses when the ref is not an annotated tag on main`, expects a refusal and fails when `HEAD` is the tagged release commit. It was observed failing intermittently during the quality-gate-hardening batch (#245–#248). The pull request runbook (`docs/runbooks/runbook-diagnose-pr-validate.md`) tells a reader to re-run the job once when it is the only failure. Expected state: the test's result does not depend on which commit is checked out.
148
+
149
+ ## Known limitations
150
+
151
+ **Regex parity tests prove presence, not meaning.** The prompt parity suites (for example `test/unit/projects-tracking-parity.test.ts`) prove that each required sentence is present, appears in the required order, and is identical across the `.claude`, `.github` and `.kiro` trees. They cannot prove that nearby text does not contradict, qualify or weaken those sentences: an added "unless", a synonym, or a conflicting rule elsewhere in the same prompt passes every assertion. Wave 2 of projects-tracking closed with 8 such synonym and qualifier probes still surviving after hardening; chasing them with more patterns has diminishing returns. Meaning-level fidelity therefore rests on the `verifier` audit (Audit Mode fidelity reports) and on the dogfood reads in the Dogfood checks table, not on the test suite. A green parity suite is evidence of presence only.
152
+
153
+ ## Dogfood checks
154
+
155
+ Behavioural acceptance criteria of the projects-tracking PRD cannot run inside Vitest: a mocked `gh` would test the mock, not the agent (D-39). Each is verified by reading GitHub after a real event, using the `DF-*` rows of `workstream/test-plan-projects-tracking-phase-1.md`, and recorded here with the satisfying issue number. `pending` means the event has not happened yet; `n/a (pre-rule)` marks the two wave 1 stories that ran before S-003's status-comment rule existed in the loaded prompt (D-42).
156
+
157
+ | Criterion | Event | Issue | Status |
158
+ | ----------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
159
+ | PRD AC-1 — publish creates the PRD/wave/story hierarchy | Wave 2 publish by `product-engineer` (DF-1, zero-match path) | #289, #290, #291 to #296 | observed 2026-10-21: wave 2 publish created the PRD and wave tracking issues and attached six stories, hierarchy verified(7 of 7) |
160
+ | PRD AC-2 (live half) — tracking issues carry `level:` only | Wave 2 publish (DF-1) | #289, #290 | observed 2026-10-21: both tracking issues carry their `level:` label only |
161
+ | PRD AC-3 (b) — story status comment, S-001 | `/developer` on #270 (DF-2) | #270 | n/a (pre-rule) |
162
+ | PRD AC-3 (b) — story status comment, S-002 | `/developer` on #271 (DF-2) | #271 | n/a (pre-rule) |
163
+ | PRD AC-3 (b) — story status comment, S-003 | `/developer` on #272 (DF-2) | #272 | observed 2026-10-20: one marked comment (id 6302983274), edited in place; comment created at sub-task 3.2a, after the draft PR, because the rule did not exist before 3.2 (S-003 DR-2) |
164
+ | PRD AC-3 (b) — story status comment, S-004 | `/developer` on #273 (DF-2) | #273 | observed 2026-10-20: one marked comment (id 6303270800), edited in place |
165
+ | PRD AC-3 (b) — story status comment, S-005 | `/developer` on #274 (DF-2) | #274 | observed 2026-10-20: one marked comment (id 6303586826), edited in place |
166
+ | PRD AC-3 (b) — story status comment, S-006 | `/developer` on #275 (DF-2) | #275 | observed 2026-10-21: one marked comment (id 6305768927), edited in place |
167
+ | PRD AC-3 (a, live half) — Project Status written only by automations | Consolidated PR to main opens with `Closes #N` (Status → In progress) and merges (→ Done); story PRs into the integration branch move nothing (D-50) (DF-5) | #270 to #275; #285, #290 to #296 | observed: wave 1 Done after PR #282 merged; wave 2 In progress for all eight issues at 20:39Z 2026-10-22 after consolidated PR #312 opened, read with `projectItems`, no agent write; Done for all eight at 21:00Z after PR #312 merged, `project_observation: observed` Wave 3: In progress at consolidated PR #335 open (observed 2026-10-27 12:50Z, #317 and #318) and Done at its merge (observed 2026-10-27 13:01Z, #317 to #323). |
168
+ | FR-24 — wave update, no-parent path (404) | Any wave 1 story's `/developer` run (DF-3) | #272, #273, #274, #275 | observed: `gh api …/parent` returns 404; closeout carries `wave_status: skipped(no parent)` |
169
+ | FR-24 — wave update, success path (200) | First main-thread `/developer` run on a wave 2 story: parent found, wave comment edited (DF-3) | pending | pending |
170
+ | D-36 — second publish reuses the PRD issue (one-match path) | Wave 3 publish (DF-1b) | #289, #317 | observed 2026-10-24: the wave 3 publish found exactly one open `[PRD-projects-tracking]` issue and reused #289, then created wave #317 under it (`workstream/github-publication-projects-tracking-phase-3.md`). |
171
+ | PRD AC-5 (live half) — runbook exercise (DF-4) | Owner follows `docs/runbooks/runbook-configure-github-project.md` on `llipe/dev-tasks` | #274 (Project 5) | observed 2026-10-21: Project 5 created from the Team planning template; seven shipped workflows enabled; auto-add `is:issue`; fields kept by decision D-48 |
172
+ | Wave 2 DF-6 — checkpoint committed after every merge | `/planner` wave 2 run (S-008 rule) | integration/projects-tracking-phase-2 | observed 2026-10-22, hand-applied (rule merged at S-008): six `chore(planner): checkpoint after S-0xx merge` commits, each after its merge |
173
+ | Wave 2 DF-7 — state file carries `Wave issue` and `PRD issue` | `/planner` wave 2 run (S-008, S-018 rules) | #290, #289 | observed 2026-10-22, hand-applied |
174
+ | Wave 2 DF-8 — one wave status comment, edited in place | `/planner` wave 2 run (S-009 rule) | #290 | partly observed 2026-10-22, hand-applied: one marker comment edited at run start and every merge; never edited at a story's PR-ready closeout, so no story showed `PR open` (rollup RD-1) |
175
+ | Wave 2 DF-9 — no per-merge table comments | `/planner` wave 2 run (S-009 rule) | #290 to #296 | observed 2026-10-22 |
176
+ | Wave 2 DF-11 — consolidated PR carries `Closes` for every merged story and the wave | Consolidated PR open (S-010 rule) | #312 | observed 2026-10-22: `Closes` for #291 to #296, #290 and #285 under `## Why`; GitHub links all eight |
177
+ | Wave 2 DF-15 — close-out runs from the merged prompt | Phase 6 in a fresh session on `main` (S-011 rule) | close-out PR | observed 2026-10-22: Phase 6 run from the merged prompt on `main` |
178
+ | Wave 2 DF-16 — PRD status comment at run start, PR open and close-out | `/planner` wave 2 run (S-018 rule) | #289 | run start hand-applied; PR open and shipped observed 2026-10-22 from the merged prompt |
179
+ | DF-21 — S-016 roadmap check is a no-op on a canonical roadmap | Wave 3 migration, before `--plan` | #323 | observed 2026-10-25: `roadmap-parity` 28/28; this repository's roadmap was already canonical, so no conversion PR. |
180
+ | DF-22 — `--plan` is read-only (FR-17) | Wave 3 migration, `--plan` | #323 | observed 2026-10-26: labels and open issues identical before and after a `--plan` run (qa-engineer, PR #332). |
181
+ | DF-23 — Migration Mode asks one question per review item (S-017/AC-2) | Wave 3 migration review walk | #323 | observed 2026-10-25 (planner attestation): nine items asked one per message; the owner overrode two recommendations (#108, #262). |
182
+ | DF-24 — `Approved: yes` set only on explicit approval (D-80) | Before `--apply` | #323 | observed 2026-10-25 (planner attestation): set after the owner wrote "approved"; one `Approved: yes` line; Plan digest recomputes to the header. |
183
+ | DF-25 — `--apply` records every write (S-015/AC-3, AC-8) | Wave 3 migration, `--apply` | #323 | observed 2026-10-25: exit 0, 14 done, 0 skipped, 0 failed; every row matches GitHub. |
184
+ | DF-26 — the Project batch is the owner's (PRD AC-12, D-81) | Owner runs batch 7 | #323 | observed 2026-10-26: four steps ticked by the owner (screenshot: auto-add `is:issue`, Item closed and Pull request merged on); Project 5 holds 48 issue items, 0 pull requests. |
185
+ | DF-27 — re-plan after apply proposes nothing | After `--apply` | #323 | observed 2026-10-26: fresh `--plan --out <scratch>` has 0 rows in batches 1 to 6. |
186
+ | DF-28 — the record ships in the consolidated PR (D-93, D-112) | Record PR | #323 | observed 2026-10-26: PR #332 (`chore/323-projects-migration` into the integration branch) carries `workstream/migration-projects.md`; the consolidated PR references #332. |
187
+ | DF-29 — PRD AC-12, FR-19, FR-20 on live data | After `--apply` | #323 | observed 2026-10-26: no D-91 retired label defined; #317 under #289 with #318 to #323; one marker comment on #289; titles unchanged. |
188
+
189
+ ## Changelog
190
+
191
+ | Version | Date | Change | Author |
192
+ | ------- | ---------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------ |
193
+ | 1.13 | 2026-10-27 | DF-5: wave 3 In progress at consolidated PR #335 open and Done at its merge, both observed with no agent Project write. | planner |
194
+ | 1.12 | 2026-10-27 | Dogfood checks: wave 3 rows DF-21 to DF-29 observed (#323, PR #332); the D-36 one-match publish row observed on the wave 3 publish (#289 reused). | planner |
195
+ | 1.11 | 2026-10-24 | Fixtures and Mocking: the `node:fs` crash mock for EC-140 (S-015 task 5.22, #322). | developer |
196
+ | 1.10 | 2026-10-24 | Fixtures and Mocking: the `--apply` harness (the model's write half, `apply-run.ts`, `random-repo.ts`, the fake `gh`'s `<file>` keys and delay) (S-015, #322). | developer |
197
+ | 1.9 | 2026-10-24 | Fixtures and Mocking: the model serves issue comments; `helpers/model-apply.ts` replays a plan onto it for RT-12; the AC-11 expected plan is hand-written (S-014, #321). | developer |
198
+ | 1.8 | 2026-10-24 | Fixtures and Mocking: the `migrate projects` harness (fake GitHub model, test-side write oracle, fake `gh` on a purpose-built `PATH`, `DEV_TASKS_NOW`, seeded PRNG) (S-013, #320). | developer |
199
+ | 1.7 | 2026-10-22 | DF-5 Done observed after PR #312 merged; wave 2 DF-15 and DF-16 observed from the merged prompt (Phase 6). | planner |
200
+ | 1.6 | 2026-10-22 | DF-5 (PRD AC-3 a) and wave 2 DF-11 observed on consolidated PR #312: GitHub moved all eight linked issues to In progress (#285). | planner |
201
+ | 1.5 | 2026-10-22 | Known limitations section: regex parity tests prove presence, not meaning (wave 2 decision). PRD AC-1 row observed; wave 2 dogfood rows DF-6 to DF-16 added (hand-applied, Design Mode A-25). | planner |
202
+ | 1.4 | 2026-10-22 | Changelog rows 1.2 and 1.3 moved out of the Test Layers table into this section (A-38); no content change. | developer |
203
+ | 1.3 | 2026-10-21 | DF-1 rows observed on the wave 2 publish (#289, #290, #291 to #296); DF-1b reuse path still pending. | product-engineer |
204
+ | 1.2 | 2026-10-21 | DF-5 row observed: Project Status reached Done for #270 to #275 through GitHub's own automation when PR #282 merged (D-50); the row's Criterion cell, overwritten on 2026-10-21, restored. | planner |
205
+ | 1.1 | 2026-10-21 | Dogfood checks table added for the projects-tracking wave 1 behavioural criteria (D-39, D-42): PRD AC-1 pending wave 2's publish, PRD AC-3 rows per story, FR-24 and D-36 paths, DF-4. | @llipe / developer |
206
+ | 1.0 | 2026-08-18 | Initial testing standard. | qa-engineer |
@@ -1,7 +1,7 @@
1
1
  #!/usr/bin/env node
2
2
  /**
3
3
  * dev-tasks CLI — bootstrap binary.
4
- * Commands: install, update, status, pin, unpin, doctor
4
+ * Commands: install, update, status, pin, unpin, doctor, migrate
5
5
  */
6
6
  export {};
7
7
  //# sourceMappingURL=dev-tasks.d.ts.map
@@ -1,11 +1,12 @@
1
1
  #!/usr/bin/env node
2
2
  /**
3
3
  * dev-tasks CLI — bootstrap binary.
4
- * Commands: install, update, status, pin, unpin, doctor
4
+ * Commands: install, update, status, pin, unpin, doctor, migrate
5
5
  */
6
- import { readFileSync } from "node:fs";
7
- import { resolve } from "node:path";
8
- import { parseArgs } from "./parse-args.js";
6
+ import { mkdtempSync, readFileSync, rmSync } from "node:fs";
7
+ import { tmpdir } from "node:os";
8
+ import { join, resolve } from "node:path";
9
+ import { parseArgs, parseMigrateProjectsArgs, validateGlobalArgs, MIGRATE_PROJECTS_USAGE, } from "./parse-args.js";
9
10
  import { ExitCode } from "#core/exit-codes.js";
10
11
  import { installFiles } from "#core/distribution/install.js";
11
12
  import { isValidProfile, VALID_PROFILES } from "#core/distribution/profiles.js";
@@ -15,6 +16,7 @@ import { getStatus } from "#core/distribution/status.js";
15
16
  import { runDoctor } from "#core/distribution/doctor.js";
16
17
  import { runMigration } from "#core/distribution/migrate.js";
17
18
  import { runDocsMigration, formatDocsMigration } from "#core/distribution/migrate-docs.js";
19
+ import { createGhRunner, createLocalReader, createLockFile, killRunningGh, createPlanFileStore, formatMigrationApplySummary, formatMigrationPlanSummary, MIGRATION_APPLY_LOCK, migrationApplyJson, migrationPlanJson, runMigrationApply, runMigrationPlan, } from "#core/migrate-projects/index.js";
18
20
  const COMMANDS = ["install", "update", "status", "pin", "unpin", "doctor", "migrate"];
19
21
  function getVersion() {
20
22
  // Walk up from bin/ (source) or dist/bin/ (compiled) to find package.json
@@ -84,6 +86,14 @@ Sub-commands:
84
86
  (docs/product-context.md -> docs/product.md,
85
87
  docs/technical-guidelines.md -> docs/tech.md).
86
88
  Report-only; --force applies it, backing up first.
89
+ migrate projects --plan [--repo <owner/repo>] [--out <path>] [--json]
90
+ Read the repository through gh and write a reviewable
91
+ migration plan (default workstream/migration-projects.md).
92
+ Read-only: nothing on GitHub changes.
93
+ migrate projects --apply [--plan-file <path>] [--json]
94
+ Run an approved plan (\`Approved: yes\`): batches 1 to 6 in
95
+ order, each write's state recorded in the plan file, so a
96
+ re-run resumes. Never runs the Project batch.
87
97
 
88
98
  Options:
89
99
  --profile <p> Platform profile: copilot, claude, kiro, both, all (default: all)
@@ -115,6 +125,14 @@ async function main() {
115
125
  printUsage();
116
126
  process.exit(ExitCode.InvalidUsage);
117
127
  }
128
+ // Every command refuses an unknown flag or a value flag with no value
129
+ // before doing anything, so a typo never changes what it does.
130
+ const usageError = validateGlobalArgs(args);
131
+ if (usageError !== null) {
132
+ process.stderr.write(`dev-tasks ${args.command}: ${usageError}\n\n`);
133
+ printUsage();
134
+ process.exit(ExitCode.InvalidUsage);
135
+ }
118
136
  const targetDir = process.cwd();
119
137
  const packageRoot = getPackageRoot();
120
138
  const currentVersion = getVersion();
@@ -315,6 +333,10 @@ async function main() {
315
333
  // is deliberately left as it was: it is detect-and-apply, while
316
334
  // this sub-verb proposes by default (D-52). Changing the legacy
317
335
  // default would alter a shipped command's behavior.
336
+ if (args.positional[0] === "projects") {
337
+ await migrateProjects(args, targetDir);
338
+ break;
339
+ }
318
340
  if (args.positional[0] === "docs") {
319
341
  const docsResult = await runDocsMigration(targetDir, { apply: args.flags.force });
320
342
  if (args.flags.json) {
@@ -370,6 +392,106 @@ async function main() {
370
392
  }
371
393
  }
372
394
  }
395
+ /**
396
+ * `migrate projects --plan` (S-013, D-79). Read-only: the plan file is the
397
+ * only thing written. Exit codes come from `core/exit-codes.ts` (A-64):
398
+ * 0 success, 1 a failed read, 2 bad usage or a `--repo` that is not the
399
+ * working tree, 11 `gh` missing or unauthenticated, 14 refusing to
400
+ * overwrite an applied plan file.
401
+ *
402
+ * `migrate projects --apply` (S-015): 0 every write applied, 1 a write
403
+ * `failed` or the run was interrupted, 2 a missing or unparsable plan
404
+ * file, 11 `gh` missing or unauthenticated, 14 not approved, an edited
405
+ * plan, another run's lock, or a stale snapshot.
406
+ */
407
+ async function migrateProjects(args, targetDir) {
408
+ const parsed = parseMigrateProjectsArgs(args);
409
+ if (!parsed.ok) {
410
+ process.stderr.write(`migrate projects: ${parsed.error}\n${MIGRATE_PROJECTS_USAGE}\n`);
411
+ process.exit(ExitCode.InvalidUsage);
412
+ }
413
+ if (parsed.mode === "apply") {
414
+ await migrateProjectsApply(parsed.planFile, parsed.json, targetDir);
415
+ return;
416
+ }
417
+ // DEV_TASKS_NOW injects the clock for tests (A-85); an unreadable value is refused.
418
+ const nowEnv = process.env.DEV_TASKS_NOW;
419
+ const fixed = nowEnv === undefined || nowEnv === "" ? undefined : new Date(nowEnv);
420
+ if (fixed !== undefined && Number.isNaN(fixed.getTime())) {
421
+ process.stderr.write(`migrate projects: DEV_TASKS_NOW is not a date: ${nowEnv}\n`);
422
+ process.exit(ExitCode.InvalidUsage);
423
+ }
424
+ const result = await runMigrationPlan({
425
+ runner: createGhRunner({ cwd: targetDir }),
426
+ reader: createLocalReader(targetDir),
427
+ repo: parsed.repo,
428
+ out: parsed.out,
429
+ now: () => fixed ?? new Date(),
430
+ store: createPlanFileStore((p) => resolve(targetDir, p)),
431
+ });
432
+ if (parsed.json) {
433
+ process.stdout.write(JSON.stringify(migrationPlanJson(result), null, 2) + "\n");
434
+ if (result.error !== undefined)
435
+ process.stderr.write(`migrate projects: ${result.error}\n`);
436
+ }
437
+ else if (result.exitCode === ExitCode.Success) {
438
+ process.stdout.write(formatMigrationPlanSummary(result) + "\n");
439
+ }
440
+ else {
441
+ process.stderr.write(`migrate projects: ${result.error ?? "failed"}\n`);
442
+ }
443
+ process.exit(result.exitCode);
444
+ }
445
+ /**
446
+ * `migrate projects --apply`. A signal releases the lock and removes the
447
+ * body files before exiting; the plan file already holds every state
448
+ * recorded so far, so the next run resumes (A-80).
449
+ */
450
+ async function migrateProjectsApply(planFile, json, targetDir) {
451
+ const lock = createLockFile(resolve(targetDir, MIGRATION_APPLY_LOCK));
452
+ const tmpDir = mkdtempSync(join(tmpdir(), "dev-tasks-migrate-"));
453
+ const cleanup = () => {
454
+ lock.release();
455
+ rmSync(tmpDir, { recursive: true, force: true });
456
+ };
457
+ const onSignal = (signal) => {
458
+ // D-111: the gh call in flight dies first, so no write lands once the lock is gone.
459
+ killRunningGh();
460
+ cleanup();
461
+ process.stderr.write(`migrate projects: interrupted by ${signal}; the states so far are in ${planFile}: run --apply again to resume\n`);
462
+ // CT-34 and the user manual: an interrupted run exits GeneralError (1), whatever the signal.
463
+ process.exit(ExitCode.GeneralError);
464
+ };
465
+ // Installed before the first await, so before any gh call: a signal is
466
+ // handled only between event-loop turns, and none passes before this line (5.25).
467
+ process.once("SIGINT", onSignal);
468
+ process.once("SIGTERM", onSignal);
469
+ process.once("SIGHUP", onSignal);
470
+ let result;
471
+ try {
472
+ result = await runMigrationApply({
473
+ runner: createGhRunner({ cwd: targetDir }),
474
+ reader: createLocalReader(targetDir),
475
+ planFile,
476
+ store: createPlanFileStore((p) => resolve(targetDir, p)),
477
+ lock,
478
+ tmpDir,
479
+ });
480
+ }
481
+ finally {
482
+ cleanup();
483
+ }
484
+ const ran = result.exitCode === ExitCode.Success || result.exitCode === ExitCode.GeneralError;
485
+ if (json) {
486
+ process.stdout.write(JSON.stringify(migrationApplyJson(result), null, 2) + "\n");
487
+ }
488
+ else if (ran && result.summary !== null) {
489
+ process.stdout.write(formatMigrationApplySummary(result) + "\n");
490
+ }
491
+ if (result.error !== undefined)
492
+ process.stderr.write(`migrate projects: ${result.error}\n`);
493
+ process.exit(result.exitCode);
494
+ }
373
495
  main().catch((err) => {
374
496
  process.stderr.write(`Fatal error: ${err instanceof Error ? err.message : String(err)}\n`);
375
497
  process.exit(ExitCode.GeneralError);