docs: brief for the ledger counting only stack issue numbers (#1665, P19 372, row 7 follow-up)

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

@@ -0,0 +1,51 @@
+# 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 floor. `issueNumbers` drops any number below 1495. Name the floor as a constant with a
+   comment that cites #1495. This handles the bare and range forms on its own.
+2. A tracker-name skip. `issueNumbers` 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.
+3. Change it in `issueNumbers` itself so all three callers get it. Update the existing test at
+   `packages/ledger/tests/ledger.test.mjs:235`, which uses `#1` and `#2`, to numbers at or
+   above the floor, and keep what it checks (dedupe, `abc#3`, `#0`, `#4x`).
+4. `packages/ledger/README.md` says in one sentence which numbers the ledger counts.
+
+## Acceptance
+
+- One test per form listed above, each asserting the exact array `issueNumbers` returns. A
+  `readCommits` test on a stand-in repo with a mixed subject shows only the stack issue.
+- 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`, its tests and the ledger README.