feat(refs): hub→hub composition, lint validation pass (#4)

[Connorrmcd6]

Summary

Resolves refs from forward-declared/inert into a validated hub-composition graph — PR1 of 2. This stage deliberately stops short of verdict propagation, per the §9.3 unlock discipline: composition compounds the granularity problem (§8/§11.3), so the validated base ships first and staleness propagation (ReferencedStale) follows in PR2.

What changed and why

surf-core

• anchor.rs — extracted parse_segment so the @N positional-collision grammar is shared rather than duplicated.
• New refs.rs — parse_ref → Ref { path, segments }. A ref is a hub path (./cli-verify.md) optionally followed by > symbol to address one claim within the target (./resolve.md > resolve_nodes), reusing the at: segment grammar. Pure parsing; exported from lib.rs.

surf-cli

• workspace.rs — resolve_ref_path normalizes a hub-relative ref to a workspace-rel path by component arithmetic (no filesystem access).
• lint.rs — the workspace loop builds a rel → &Hub index once; new lint_refs blocks a ref that is malformed, doesn't resolve to a loaded hub, points at its own hub, or names a claim the target lacks (same fail-on-typo reasoning as covers). The check verdict is untouched.

Samples + docs

• Seeded real refs: in the 5 hubs that already cross-linked in prose (hash→cli-verify; hub-format→cli-lint/cli-check; cli-workspace→cli-check/cli-lint/config; cli-check→cli-git/cli-verify; cli-git→rename).
• Reclassified the 2 doc-pointing refs (cli-reference, cli-stats) to prose links — docs aren't hubs; both already linked the doc in prose, so the refs dropped to [].
• Updated authoring-hubs.md, the hub-format hub's prose, and CHANGELOG.
• hubs/anchor.md — re-sealed the parse_anchor claim hash (the parse_segment extraction is a pure change ≠ falsification refactor; the claim's prose is unchanged). The diff is the single hash line.

Verification

All run on this branch:

• cargo fmt --all --check — clean
• cargo clippy --all-targets --all-features -- -D warnings — clean
• cargo test --all — 229 passed, 0 failed (2 pre-existing #[ignore]), incl. 4 new parse_ref + 7 new lint_refs tests
• Dogfood: surf lint → 0 errors (18 pre-existing advisory warnings), surf check → all anchored spans match

Scope

Part of #4 (does not close it). PR2 will add ReferencedStale verdict propagation — a hub flagged when a hub it refs goes stale — which completes the issue.

🤖 Generated with Claude Code