Files
stack/docs/plans/2026-10-19_ledger-stack-refs.md

65 lines
3.6 KiB
Markdown

# Brief: the ledger counts only stack issue numbers
Follow-up to row 7 (weekly ledger run, #1508), Vikunja P19 372, Gitea #1665. Sage found it in
the 2026-10-11 to 10-17 run (#1508 comments 29070 and 29089).
Owner Sage, reviewer Dewey, gate owner Sage. Ledger only. Nothing live reads the ledger, and
the change needs no window.
## The defect
`issueNumbers` (`packages/ledger/src/ledger.mjs:29`) takes every `#N` it finds. It has three
callers: commit subjects in `readCommits` (:42), user messages in pi sessions (:165) and T3
messages (`packages/ledger/src/t3.mjs:116`). Commit subjects and messages also cite other
trackers, and the ledger reads those numbers as mosaicstack/stack issues. Old v1 issues still
hold the numbers below #1495 in this repo, so the foreign refs land on them and inflate the
table.
In the 10-11 week, 34 of 131 table rows were #19 to #287. The forms in the refactor log since
2026-09-07:
- a tracker name then the number: `Vikunja #259`, `P19 #252`, `Vikunja P19 #232`,
`SetSpark #35`, `Launchpad #36`
- a range after a tracker name: `P19 #219-#222` (the second number has no name before it)
- a bare foreign number: `#237 proxy`, `#225`, `Q61a #19`
- a stack issue after a name that stays counted: `Gitea #1578`, `#1603, Vikunja #259`
Every stack issue cited since the conversion is #1495 (the conversion issue) or above.
## The fix
1. A tracker-name skip, in `issueNumbers` so all three callers get it. It drops a `#N` when
the word right before it is `Vikunja`, `P19`, `SetSpark` or `Launchpad`, case-insensitive,
with one space between. This covers a Vikunja task id that someday reaches 1495.
`Gitea #N` and `issue #N` stay counted. The existing test at
`packages/ledger/tests/ledger.test.mjs:235` keeps passing unchanged.
2. A floor, applied once in `cli.mjs` `main` after the reads and before `summarize`: one
helper in `ledger.mjs` drops numbers below the floor from each commit's issues (a commit
left with none drops out of the commit total, as an untagged commit does) and from the
session mentions. Issues Gitea lists as closed in range are Gitea's own data and are not
filtered. This handles the bare and range forms.
3. The floor is a new option, `--first-issue N`, a positive integer, default 1495, with a
comment that cites #1495. Most CLI fixtures use `#1` and `#2`, so their runs pass
`--first-issue 1` and keep testing what they test now. The weekly routine command doesn't
change.
4. `packages/ledger/README.md` replaces the "no attempt to remap" sentence in Counting rules
with which numbers the ledger counts, and the usage line lists the option.
Amended 2026-10-19 by Sage before the build started: the first version put the floor inside
`issueNumbers`, which would have broken every fixture that uses a small number.
## Acceptance
- One test per form listed above, each asserting the exact array `issueNumbers` returns. A CLI
run on the fixture repo with the default floor shows only stack issues in the table, the
commit total and the seat mentions. `--first-issue` with a missing, zero or non-integer
value refuses.
- Two mutants, each failing at least one new test: remove the floor, and remove the
tracker-name skip.
- The ledger suite and every `scripts/test-*.sh` green on Sage's gate. Dewey approves the
candidate manifest.
- After landing, Sage reruns the 10-11 week and posts the corrected totals on #1508. They must
match the read-only recompute in 29089 (97 rows, 557 commits, 5.3 follow-ups per issue).
- The diff touches only `packages/ledger/src/ledger.mjs`, `packages/ledger/src/cli.mjs`,
`packages/ledger/tests/ledger.test.mjs` and the ledger README.