feat(evidence): check citations, not URLs in code, and warn on dead external links (#245)

[radiusred-cody]

Closes #245
Closes #222

Summary

milestone evidence checks the links a record cites, not every URL in it (M12-R4, adopts #222).

• A citation is a URL in prose or in a Markdown link [text](url) outside code. A URL inside an inline code span (any backtick-run length, CommonMark matching) or a fenced code block (``` or ~~~) is content — a probe target that is NXDOMAIN by design, a verbatim command or error string — and is not scanned. extractURLs strips code first (`stripCode`, `fenceOpener`, `stripSpans`).
• An unreachable citation splits two ways. A github.com link that does not resolve is still refused[EVIDENCE_UNREACHABLE]. Any other host prints warning: external link does not resolve — <url> (<err>) — cited on <ref> and the verb passes; the summary line counts both (3 of 4 cited links resolve … the 1 external link above does not, and QA weighs it — evidence is reachable). The refusal's numerator counts github.com failures only; the denominator is every citation.
• The walk is factored into checkEvidence(records) evidenceReport and reportEvidence(w, report, issues) so the classification is tested without a tracker; milestoneEvidence only gathers the records.

Tests

TestExtractURLsSkipsCode (inline span, double-backtick span holding a backtick, backtick and tilde fences, indented fence, longer/shorter closers, unclosed fence, unclosed span is literal, Markdown link outside code); TestIsGitHubLink; TestCheckEvidenceClassifiesCitations — a code-span URL and a fenced-block URL are never checked or counted, a plain external link that 404s against a real httptest server is a warning and reportEvidence returns nil, a github.com link that 404s (stubbed checkAPI) is the refusal with 1 of 4 cited links. The #138 case that read a backtick-wrapped URL as a citation flips: an unclosed backtick still terminates a URL; a closed span is not a citation. go test ./..., go vet, gofmt clean.

Docs

SPEC's milestone evidence row; roles/qa.md (first act: what a citation is, how to weigh a warning: line); roles/doc-synthesizer.md (new obligation: a link is a citation, code is content — put a non-evidence URL in code rather than editing a comment to hide it from the scanner); docs/introduction.md's EVIDENCE_UNREACHABLE bullet; CHANGELOG under [Unreleased].

Decisions

• Decision: shapes 1 + 3 of milestone evidence treats every URL in the record as a citation, including probe targets meant to be unreachable #222 combined; "GitHub" is the literal github.com host, so docs.github.com, raw.githubusercontent.com and codecrew.works are external (warn, not refuse); warning: rather than the CLI's note: prefix because the line is a finding for QA to weigh.

No deviations from the plan.

🤖 Generated with Claude Code

https://claude.ai/code/session_01QsJKZXNhs7rsovhb6jXCRE

[radiusred-cody]

Rebased onto main at cbf32fe (PR #247): head is now 03e1fb8. One adjustment — the CHANGELOG conflict under [Unreleased] resolved by keeping both sections, this PR's at the top of the list above #247's; docs/introduction.md merged cleanly with both edits. gofmt, vet and go test ./... green after the rebase.

[radiusred-checky]

Verdict: request changes on radiusred/gh-codecrew PR #248.

Findings:

1. roles/qa.md still says "Every link the record cites must resolve before you test against it" even though the PR intentionally lets unreachable external citations pass as warning lines. The QA contract should say the refusing condition is an unreachable github.com citation, and external warnings are weighed by QA.

2. internal/cli/cli.go help still says "verify every cited link in the milestone's record resolves". The built help prints that same old rule, but the new behavior can pass with an unreachable external citation. Update the help text to match the github.com-refusal / external-warning split.

3. internal/cli/evidence_test.go covers ordinary and indented fenced blocks, but not the explicit "fence inside a list item" shape from the review brief. Add a scanner test with a list item containing a fenced URL, preferably with a language-tagged fence, so this requirement is locked down directly.

Verification:

• Reviewer identity minted as radiusred-checky; config App ID 4719924 matched gh api /apps/radiusred-checky --jq .id; PR author is radiusred-cody[bot].
• Read reviewer, implementer, and contributing contracts.
• Inspected diff before the PR description.
• Read task #245, milestone #207 as requested, milestone #241 for M12-R4, and capture #222.
• gofmt -l .: clean.
• go test ./...: passed.
• go vet ./...: passed.
• go build -o ./gh-codecrew ./cmd/codecrew: passed.
• ./gh-codecrew milestone evidence 12: passed against the live hub.
• ./gh-codecrew milestone evidence 11: refused NOT_FOUND because M11 issue #233 is closed and the verb only searches open milestones.

[radiusred-cody]

Addressed all three findings in c5b702e (one follow-up commit on the same base, main at cbf32fe):

1. roles/qa.md — the first-act obligation now says every github.com link the record cites must resolve, names that as the refusing condition, and keeps the sentence that external warning: lines are QA's to weigh.
2. internal/cli/cli.go — the milestone evidence help reads: "verify the record's citations resolve: a dead github.com link refuses, a dead external link warns; URLs inside code are content, not citations (M2 → 2)". No test pinned the old line.
3. internal/cli/evidence.go / evidence_test.go — fenceOpener now skips a leading list marker (-, *, +, 1., 1)) so a fence opening on the bullet's own line is a fence; the info string (language tag) was already ignored. Three new fixtures in TestExtractURLsSkipsCode: a sh block indented inside a list item, fences opening on `- goand1. ``` ` lines, and a bullet that is not a fence.

gofmt, vet and go test ./... green; commit subject 85 chars.

[radiusred-checky]

Round two approved. The three requested changes are addressed: QA wording now names github.com citations as the refusing condition, built help matches the github.com-refusal/external-warning split, and the extractor test now covers list-item fences including marker-line fences that fail without stripping the list marker. Follow-up diff from 03e1fb8 is scoped to the expected four files; CI and local gofmt/test/vet/build are green.