014 — Full numbers under numbered headings (#36)

Status: shipped (v0.9.0)

Why

Story 012 made a numbered heading an item and read the list items beneath it as relative to it: **1.1** under ## 2 is 2.1.1. Restructuring gobank's roadmap into numbered epics showed the model wrong (#36, second comment): its frozen **1.1** sits under ## 1 Transition … and must still read as 1.1, not 1.1.1. Relative numbers also make a citation mean different things inside and outside a section, which is exactly what a frozen number is meant to prevent. With full numbers the heading is simply the parent, and every number means one thing wherever it is written or cited. task-plus's own roadmap, still unnumbered, is the first file restructured under the corrected model.

What changes

  • A list item's number is always written in full. A numbered heading is the parent of the items in its scope: ## 1 Transition … then - **1.1** …, - **1.6a.2** …. Nothing in a file that already writes full numbers changes.
  • A list item or nested numbered heading inside a numbered heading's scope that does not descend from the heading is misplaced, a structural finding like an orphan. A heading's number repeated as a list line (- **1 Title** — under ## 1 Title) is a duplicate, so that line goes and its prose moves under the heading.
  • renumber writes a changed number in full on every line it changes, carrying a renumbered heading down to its descendants' text as any parent is carried; the relative-citation scan goes, and other occurrences are the full number anywhere.
  • Scope and transparency are as story 012: to the next heading of the same or a higher level, unnumbered lower headings transparent.
  • docs/roadmap.md rewritten for the model; ROADMAP.md here becomes four numbered epics, the MVP-era items left as prose before them.

Acceptance

File tp roadmap check
## 2 Phase 2, **2.1 Title**, **2.1.1** [x] (v0.4.0), **2.2**, ## 3 Phase 3, **3.1** passes: items are 2, 2.1, 2.1.1, 2.2, 3, 3.1
## 2 Phase 2, **2.1**, **2.3** gap: 2.2 missing; 2.3 should be 2.2
## 2 Phase 2, **1** misplaced: 1 under heading 2
## 1 A, ## 2 B, **1.1** misplaced: 1.1 under heading 2
## 1 Transition, **1 Transition** — … duplicate: 1 already at line 1
## 2, **2.1**, ### To Do, **2.2** passes: the unnumbered heading is transparent
## 2, **2.1**, ## Telemetry, **3**, ## 4, **4.1** passes: 3 is outside any scope
## 2, ### 2.1 Sub, **2.1.1** passes: 2, 2.1, 2.1.1
## 2, ### 3.1 Sub misplaced: 3.1 under heading 2
## 2, ## 4 gap: 3 missing; 4 should be 3
## 2 [x] (v1.0) Phase 2 not a numbered heading: the tick is text
no numbered heading exactly as story 009
tp roadmap renumber on Result
## 2, **2.1**, **2.3**, **2.3.1**, ## 4, **4.1** **2.2**, **2.2.1**, ## 3, **3.1**; changes 2.3 → 2.2, 2.3.1 → 2.2.1, 4 → 3, 4.1 → 3.1
prose anywhere says "see 2.3.1" or "after 2.3" listed, not changed
## 3, **3.3**, ## 4, **4.1**, **4.1.1** [x] (v1.0) nothing changes: ## 4 is frozen, 3.3 is a first sibling

Out of scope

  • Editing gobank's roadmap: its - **N Title** — epic lines become duplicates once this ships and go in gobank's own commit.
  • Ticking or stamping a heading (as story 012).

Decisions

None recorded as an ADR. The fork was relative versus full numbers; story 012 chose relative to keep gobank's lines unchanged, and gobank's restructure showed that full numbers keep them unchanged too, while relative numbers break the one-number-one-meaning rule that freezing exists for.

Done when

  • tests express the acceptance tables and pass
  • docs/roadmap.md updated
  • roadmap ticked and stamped; changelog entry
  • issue closed with a link to the release