scan-annotations: fix five silent link losses, and let @tested read in both directions

[Freshair129]

Two commits on one branch, because they are the same surface and the second depends on the first's parity test.

scan-annotations is the only thing that turns a comment into a graph edge, so everything it drops is — downstream — a link that never existed.

---

1. fix: five failures that reported nothing

Found while adopting rwang:doc-graph v2 in a repo that uses namespaced requirement ids (ZPP-*, RAG-*, TAX-*).

The main one: namespaced ids

The two scanners failed in opposite directions on the same input.

input	.sh reported	.ps1 reported	correct
@req ZPP-FR-009	FR-009	(nothing)	ZPP-FR-009

A project prefixes its ids precisely because its FR-009 is not the flat FR-009. So the .sh behaviour is not a lost prefix — it is a different requirement asserted as fact. Both now accept NS-KIND-nnn; AI-AGT-001 / AI-ETH-001 fall out of the same branch instead of needing their own enumeration.

Four more, found while verifying that one

• .ps1 skip list matched substrings of the whole path — build swallowed builder.ts, dist swallowed distance.ts. Those files reported nothing and were never listed as skipped. Now compared against path segments.
• .ps1 dropped a whole annotation when one id was unrecognised — @spec FR-093, ADR-058 lost FR-093 too, because ADR is not an enumerated kind and the pattern had to consume the line.
• .sh could not see past a UTF-8 BOM — Windows editors write one, so every ^-anchored pattern failed on line 1, which is where a file-level annotation goes. Get-Content strips it, so .ps1 never saw the problem and neither scanner looked wrong on its own machine.
• .sh crashed on a tree with no annotations — under set -euo pipefail, the grep that matched nothing ended the script before it printed anything. The count it would have printed was a doubled zero, since grep -c . both prints 0 and exits non-zero.

Two divergences also closed, moving .sh to .ps1's stricter reading: structured annotations require a comment prefix (it had been counting const s = "@req FR-999"), and unstructured references require the ids-only form.

---

2. feat: @tested reads in both directions

// src/generation.ts
// @tested __tests__/generation.test.ts::creates_generation   // already supported

// __tests__/generation.test.ts
// @tested FR-001, SDD-004                                    // new

Both assert the same verified_by relation and differ only in which end the annotated file is. A project maintains its traceability from one side or the other, and understanding only one form meant a repository that annotates its tests scanned as having no annotations at all — not a warning, a zero. On the repository this came from, tests/ read as 0 while holding 69.

Annotating from the test side is often the more durable choice: the assertion and the claim that it verifies a requirement live in one file, so deleting the test takes its claim with it.

Structured annotations now carry form — test-ref, requirement, or section. It says what the payload is rather than which keyword introduced it, which is the distinction a consumer needs: @designs already took either a section or an id.

---

Verification

Every new test fails against the previous scanners. The addition worth keeping is the cross-scanner parity check — two halves of one tool that disagree mean a graph built on Windows differs from the same graph built on Linux, and neither is wrong locally.

Measured on a real repository, both scanners now identical:

tree	structured	requirement ids	before
src/	80	76	.ps1 75/73, .sh 80/76
tests/	69	70	0 / 0 in both

scan-annotations 5/5 · validate-graph 23/23 · validate-plan 13/13 — existing suites unchanged.

Version 1.4.0 (the marketplace update signal).

🤖 Generated with Claude Code