From c93f5997093121baec55eab045e7b41a17901364 Mon Sep 17 00:00:00 2001 From: Seilbek Date: Sun, 30 Aug 2026 18:16:48 +0500 Subject: [PATCH] fix(pipeline): keep the plan number in a completed plan's filename MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit The NNNN field was a per-day counter, which destroyed the only identifier a plan is cited by. After a move, nothing in the filename said which plan the file had been, so every reference to it by number — from a README index, a decision record, or another plan's dependency graph — resolved to nothing, and a project that checks for dangling plan references failed the moment a plan completed. The counter was also not an ordinal in practice. Across the projects using it, seven pairs of completed files share a YYMMDD.NNNN prefix: step 4's scan is easy to skip and nothing downstream noticed. A plan number is unique per repository by construction, needs no scan, and is the string a reader already has. Filenames written under the old rule are left as they are. Renaming history to match a new rule breaks the links that already point at it, and the rule earns its keep on the plans still to come. Also adds a collision guard the counter should always have had, a step to re-point citations after the move, and a note that whatever a plan leaves behind is written into it before this skill runs rather than during the move. What would reverse this: a project that numbers plans non-uniquely, or one that reuses numbers across a plans/history/ archive. Neither exists today. Co-Authored-By: Claude Opus 5 (1M context) Claude-Session: https://claude.ai/code/session_01XbFNCpaG9aoVaooPvjHKxv --- .../pipeline/skills/complete-plan/SKILL.md | 35 +++++++++++++++++-- 1 file changed, 32 insertions(+), 3 deletions(-) diff --git a/plugins/pipeline/skills/complete-plan/SKILL.md b/plugins/pipeline/skills/complete-plan/SKILL.md index e0778a1..6e99466 100644 --- a/plugins/pipeline/skills/complete-plan/SKILL.md +++ b/plugins/pipeline/skills/complete-plan/SKILL.md @@ -17,10 +17,39 @@ Steps: 3. **Verify the plan is honest.** Skim the plan's acceptance criteria against what was actually implemented. If implementation diverged, ask the user to update the plan file first, then re-run this skill. 4. Compute the destination filename: - `YYMMDD` = today's date in UTC (`date -u +%y%m%d`). - - `NNNN` = next zero-padded daily index: scan `plans/completed/$YYMMDD.*.md`, take highest existing + 1, else `0001`. + - `NNNN` = **the plan's own number**, zero-padded to four digits — `007-foo.md` → `0007`. A plan whose source filename carries no number takes `0000`. - `slug` = the slug portion of the source filename (after the `NNN-` prefix). - Destination: `plans/completed/$YYMMDD.$NNNN.$slug.md`. + - **If that path already exists, stop and ask.** Two plans cannot share a number, so a collision means the source was already completed under another name, or a number was reused. 5. Run `git mv ` so history is preserved. -6. Report the move and the new path. +6. **Re-point the citations.** A plan is cited by number — from other plans, from a `plans/README.md` index, from decision records, from commit bodies. Grep the repository for the number and update anything that describes it as active. If the project has a check for dangling plan references, run it. +7. Report the move and the new path. -Do not refactor or alter the plan's contents during the move. +Do not refactor or alter the plan's contents during the move. Anything the plan +leaves behind — deferred work, findings refuted rather than fixed, decisions +owed to the owner — is written into the plan **before** this skill runs, as the +last act of executing it. + +## Why `NNNN` is the plan number + +It was a per-day counter until 2026-08-30, and repositories completed under that +rule hold filenames whose `NNNN` is a small ordinal unrelated to the plan. +**Leave those alone** — renaming history to match a new rule breaks the links +that already point at it, and the rule earns its keep on the plans still to +come. + +The counter was replaced because it lost the only identifier anyone cites. After +the move, nothing in the filename said which plan the file was, so every "plan +013" reference in a README, a decision record or another plan's dependency graph +became unresolvable — and a project that checks for dangling plan references +fails the moment a plan completes. The counter also failed at being an ordinal: +across the projects using it, seven pairs of files share a `YYMMDD.NNNN` prefix, +because step 4's scan is easy to skip and nothing downstream notices. + +A plan number is unique per repository by construction, so it needs no scan, and +it is the string a reader already has in hand. + +**What would reverse this:** a project that numbers plans non-uniquely, or one +that reuses numbers across a `plans/history/` archive. Neither exists today; the +first one to appear is the argument for going back to a counter, and it would +need the collision guard in step 4 either way.