feat(templates): allocate FR/SC/T/CHK identifiers sparsely and treat them as permanent - #4066
Open
ira-at-work wants to merge 1 commit into
Open
feat(templates): allocate FR/SC/T/CHK identifiers sparsely and treat them as permanent#4066ira-at-work wants to merge 1 commit into
ira-at-work wants to merge 1 commit into
Conversation
…them as permanent Spec Kit identifiers are references, not labels: plans, tasks, checklists (`[Spec §FR-001]`), analyze findings, converge source-refs, the GitHub issues created by /speckit.taskstoissues, commit messages and PR comments all cite them. But the templates allocate them densely and sequentially, so any insert or delete forces a renumber -- and a renumber silently invalidates every one of those citations while burning tokens rewriting lines that did not change. github#1497 reported the failure mode concretely: deleting three tasks from a 100-task file renumbered the task lines "more or less correctly" but left the `(T009-T021, T036-T039)` summaries pointing at the wrong work. The repo already has the correct invariant -- converge.md forbids renumbering and reusing IDs -- but it applies only to convergence tasks while the surrounding templates model the opposite behaviour everywhere else. Generalise the invariant and give it room to work: - Each group (FR category, task phase, checklist category) starts at the next multiple of 1000; items step by 10 within the group. - Insert into the gap: an item between T1010 and T1020 becomes T1015. Nothing after it shifts, so document order stays ascending without a renumber. - Append at the next free multiple of 10; open a new group at the next unused multiple of 1000. Editing one group never touches another. - Removal leaves a permanent hole. Gaps are the steady state, not damage to repair, and a retired number is never re-issued. taskstoissues.md matched issue titles with `\bT\d{3}\b` -- exactly three digits -- so a title containing T1000 did not match at all and those tasks were silently neither deduplicated nor created. That is already reachable today via converge.md's `T{M+1:03d}` (a floor, not a cap; see github#3866) and unavoidable under phase blocks, so widen it to `\bT\d{3,}\b` and record the contract in converge.md so producer and consumer cannot drift apart again. Existing artifacts are not retroactively renumbered; the rule applies going forward. Refs github#4065, github#1497, github#3866
Collaborator
|
See comment in #4065 |
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
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.
Implements #4065. See that issue for the full problem statement and the alternatives that were weighed.
Description
Spec Kit identifiers are references, not labels.
plan.md,tasks.mddependency lines, checklist items ([Spec §FR-001]),analyze.mdtables,converge.mdsource-refs, the GitHub issues created by/speckit.taskstoissues, commit messages and PR comments all cite them.The templates nevertheless allocate them densely and sequentially (
tasks.md:160— "Sequential number (T001, T002, T003...)";checklist.md:258— "globally incrementing IDs starting at CHK001"). Dense + sequential means every insert or delete forces a renumber, and a renumber silently invalidates every citation elsewhere while burning tokens rewriting lines that carry no new information.#1497 reported the failure mode concretely — deleting three tasks from a 100-task file renumbered the task lines "more or less correctly" but left the
(T009-T021, T036-T039, T046-T049)summaries pointing at the wrong work. It was closed as stale, not rejected on the merits.The repo already has the right invariant:
converge.md:77forbids the agent to "rewrite, renumber, reorder, or delete any existing task" and:219says "Never reuse or renumber existing IDs." It just applies to convergence tasks only, while everything around it models the opposite behaviour. This PR generalises that invariant and gives it the room it needs to hold.What changes
Two levels of spacing, each doing a different job.
T1010andT1020becomesT1015, IDs stay ascending, nothing after it movesApplied to
FR,SC,TandCHKalike:templates/spec-template.md— FR samples grouped by category (FR-1000… /FR-2000…), SC on the same scheme, both with the rule stated in a template commenttemplates/tasks-template.md— sample tasks renumbered per phase;## Formatdocuments block, step, insert and deletetemplates/checklist-template.md—CHK1000/CHK2000per category; closing note changes from "numbered sequentially for easy reference" to "stable references — do not renumber"templates/commands/{specify,clarify,tasks,checklist,converge}.md— generation rules updated to allocate, insert into gaps, and preservedocs/concepts/complex-features.md— the one example range that would otherwise contradict the templatesConvergence phases now open their own block (next unused multiple of 1000) instead of continuing from
T{M+1:03d}, so a converge run cannot land inside a phase's range.One dependent fix.
taskstoissues.md:67matched issue titles with`\bT\d{3}\b`— exactly three digits. GivenT1000the trailing\bcannot fall between two digits, so there is no match at all and those tasks are silently neither deduplicated nor created. This is already reachable onmain(#3866) becauseconverge.md's03dis a floor rather than a cap; four-digit IDs make it unavoidable. Widened to`\bT\d{3,}\b`, with the contract recorded inconverge.mdso producer and consumer can't drift apart again.\bT\d{3}\b\bT\d{3,}\bT001T001T001T1000T1000T12345T12345ST1000T1Note the word boundaries still do their original job:
T100can never match insideT1000, because the trailing\bforces the whole digit run to be consumed.Compatibility
T+ digits,FR-+ digits). Nothing that parses the existing format breaks — unlike the hierarchicalT1.1scheme proposed in Hierarchical Task Numbering System #1497.T001-style files keep working; the rule applies to newly generated and newly edited artifacts.tests/hooks/tasks.mdis deliberately left atT001for that reason.Testing
13 failed, 6616 passed, 177 skippedmain:13 failed, 6616 passed, 177 skippedIdentical — the 13 are pre-existing failures unrelated to this change (branch-slug generation in
test_timestamp_branches.py/test_git_extension.py, and template-composition parity intest_resolve_template_python_parity.pyand friends). Verified by stashing the diff and re-running.tests/test_specify_template_numbering.py(top-level step ordinals inspecify.md) passes — that test governs markdown list numbering, which this PR does not touch.