TDD 0049: Touched-files extractor — single source of truth + annotation-robust

[cahenesy]

Design PR (gate = your merge). One new TDD, Status: draft. The merge is what makes it buildable via /implement. No code yet — this is the design-of-record.

What & why

Gap-closure follow-up to TDD 0048 (PR #139), addressing the two parser gaps that surfaced while landing it. Does not supersede 0048 — extends it (the repo's gap-closure pattern: 0041 extended 0019, 0033 extended 0031). PRD is unchanged (0aa1e28); this hardens the existing FR-53 / FR-54 / FR-67 mechanism, no new requirement.

• Gap 1 — annotation-robust extraction. 0048's "everything left of the em-dash" rule mis-parses an annotation between the path and the em-dash (- `src/a.txt` (post) — … → src/a.txt (post)) → a false structural-finding(a). Refined rule: prefer the first backtick token within the left-of-em-dash segment; else the first whitespace token. Handles bare, backticked, and annotated forms — and still extracts the path for the original 0044 case (bare path, backticked description right of the em-dash).
• Gap 2 — fold in the third reader. _touched_files_of_tdd (learnings.sh) still used the pre-0048 first-backtick logic with a false-parity comment. All three readers move onto a single shared scripts/lib/touched-files.sh extractor (chosen: prevent divergence by construction); the three named functions become thin delegating wrappers; the agreement cross-check extends to all three.

Scope

5 files (~210 lines): new scripts/lib/touched-files.sh; gates.sh, tdd-lint.sh, learnings.sh wired to it; tests/bounded-tdd-scope.test.sh (3-way agreement + form cases + the annotated-path membership regression). All inside bounds.

Design gate (informed review)

• Mechanical pre-pass: tl_lint rc=0, --bounds rc=0, body 302/500 lines.
• Independent design critique (design-reviewer subagent, sonnet — different model than authored): DESIGN_REVIEW: PASS. One MAJOR (the prose explaining the sourcing idiom was misleading enough to risk a subtly wrong build) — folded in: clarified that return 1 2>/dev/null || exit 1 is one idiom correct in both sourced and executed contexts. Minor/nit items (the include-guard var must not be unset; the learnings wrapper is paths-only by intent; alternatives-analysis grammar) — all addressed inline. The reviewer independently re-verified the extraction algorithm against every row of the Approach table, including the critical 0044 safety case.

Open assumptions & waivers

• fallback semantics for bare+annotation — resolved: prefer first backtick token within the left-of-em-dash segment, else first whitespace token; the 0044 bare-path/backticked-description case still extracts the path (backtick is right of the em-dash).
• 3-way agreement test signature mismatch — resolved: the agreement test stages a docs/tdd/<slug>.md under a temp repo so the <repo> <slug>-signature learnings wrapper runs on the same fixture as the file-path siblings.
• shared-lib sourcing robustness — resolved: sibling path via ${BASH_SOURCE[0]%/*}/touched-files.sh + include guard + FATAL-on-missing matching implement.sh; pinned in Verification §5 across all four sourcing contexts.
• supersede-vs-extend correctness — waived: New TDD referencing 0048 per established repo pattern; 0048 body untouched.

🤖 Generated with Claude Code