check-ticket-archaeology scans whole file, not the staged diff

Context

The check-ticket-archaeology pre-commit guard (buildScripts/util/check-ticket-archaeology.mjs, wired via lint-staged on staged *.mjs) reads the full file and flags every decay-prone ticket ref in durable comments — including pre-existing refs the committer never touched. Empirical 2026-06-02 (while driving #12331): a 2-line os.tmpdir() fix to daemon.spec.mjs was blocked by 6 pre-existing refs in unrelated comments — including a dense, genuinely load-bearing empirical-validation block (#10664/#10663/#10661 provenance) — forcing the author to either damage that provenance or mark lines they did not write.

The Problem

Same class as the check-shorthand whole-file trailing-ws scan: touching a file forces cleanup of unrelated pre-existing debt → scope creep, and here pressure to damage load-bearing comments or rewrite another author's prose (PR §10 authorship-respect). The guard's intent — don't let an author ADD decay-prone refs — is fully satisfied by checking only the author's added lines.

The Fix

Add an --added-only mode: when set (commit-time / lint-staged), flag refs only on lines added in the current staged diff. findTicketRefs still scans the whole file (needed for correct block-comment context + accurate line numbers); a new pure parseAddedLines(diffText) maps git diff --cached --unified=0 → the added new-file line numbers, and main() filters hits to those lines. Default-dir / manual mode (no --added-only) keeps the full-file audit. lint-staged passes --added-only.

The Architectural Reality

• buildScripts/util/check-ticket-archaeology.mjs — main() read readFileSync(file) + findTicketRefs(content) over the whole file. Adds exported pure parseAddedLines, getStagedAddedLines(file, gitRoot), and the --added-only filter (no change to findTicketRefs/extractComment).
• package.json lint-staged *.mjs → check-ticket-archaeology.mjs --added-only.
• Self-test test/playwright/unit/ai/buildScripts/util/check-ticket-archaeology.spec.mjs — extended with parseAddedLines coverage.

Acceptance Criteria

• AC1 — --added-only flags only refs on staged-diff-added lines; pre-existing refs in a merely-touched file are not flagged.
• AC2 — Default mode (no --added-only) keeps the whole-file audit unchanged.
• AC3 — parseAddedLines unit-tested (added-line mapping, removal handling, +++/--- header skipping, empty diff).
• AC4 — lint-staged passes --added-only.

Out of Scope

• The check-shorthand whole-file trailing-ws scan (sibling friction, same fix shape — its own follow-up if pursued).

Related

• Surfaced while driving #12331 (unit-test store isolation) — the blocked commit.

Origin Session ID: da9a6007-1250-4363-8c15-dff69eccb3be Retrieval Hint: "check-ticket-archaeology added-only staged diff scope whole-file friction"