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

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.