docs(todo-markers): record accepted branch-name-identity limitation in stale check - #289
Merged
Merged
Conversation
…n stale check The reused-branch false-STALE (a branch name reused after its first PR merged, with new work that has not opened a PR yet, resolves via the old MERGED PR and reads STALE) is now documented as an ACCEPTED limitation rather than an open backlog item. A durable fix would need a repo-bound PR identity (number/SHA) on the 🚧 marker, but the marker is written by next-todo's claim before any PR exists — so that identity would have to be back-filled by a new step in the global /ship or /merge-pr flow and kept in lockstep across four skills, all to serve this LOCAL-only advisory backstop. The false-positive window is narrow and the merged-no-open path is also the tool's primary genuine-stale signal, so it cannot be downgraded without gutting detection. Converts the script header note (a) + inline comment from a 'tracked in the backlog' framing to a recorded decision, and pins the accepted behaviour via a clarifying comment on the existing no-OPEN+MERGED test. Full cost/rarity weighing in LEARNING.md.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
Records the reused-branch false-STALE in
check-stale-todo-markers.mjsas an accepted, documented limitation rather than an open backlog item — the deferred judgement call from the cycle-2 review of the stale-marker check (Codex MEDIUM/98).The gap: a head-branch name reused after its first PR merged, whose new work has not yet opened a PR, still resolves via the old MERGED PR and reads hard-STALE (exit 1). This is fundamental to identifying a branch by name.
Changes
scripts/check-stale-todo-markers.mjs— header note (a) + the inlineresolveEntrycomment now frame the residual gap as an accepted limitation (with the cost/rarity reasoning and a pointer to LEARNING.md), replacing the prior "tracked in the TODO backlog" open-item framing.test/build/stale-todo-markers.test.ts— clarifying comment on the existingno-OPEN + MERGED → staletest marking it as the pin for the accepted behaviour (do not soften to a warning without revisiting the decision)..claude/docs/LEARNING.md(local-only, gitignored) — full decision entry under "Claude Workflow" weighing cost vs. rarity.Why accept rather than implement durable PR identity
(branch: X)marker before any PR exists (the PR is opened later by/ship). Implementing it needs a new write-back step in the global/shipor/merge-prflow, kept in lockstep across four skills — global cross-repo plumbing changed to serve one repo's local-only advisory backstop.Satisfies the TODO's Done-when via the documented-decision branch of its OR.
Related
Test Plan
pnpm exec vitest run test/build/stale-todo-markers.test.ts— 29 passedpnpm compile— exit 0pnpm exec biome checkon both changed files — clean