feat: use @ for repository revisions

[jlitola]

Summary

• make provider:path@ref the only caller-facing and emitted repository revision grammar across CLI, MCP, shared formatters, Ask/read/search follow-ups, status/replay output, help, docs, public skills, and examples
• reject exact legacy repository #ref inputs with a precise @ref migration while reserving # for documentation fragments
• preserve later @ characters inside refs, scoped/package @version coordinates, repository-backed docs locators, URL fragments, and pre-existing fuzzy URL classification
• normalize typed legacy repository labels at output boundaries while documenting the required PkgSeer rollout for backend-authored labels and prose

Verification

• bun test — 4,774 passed, 16,557 assertions
• bun run typecheck
• bun run lint — no errors; eight existing non-null warnings
• bun run format
• bun run build
• bun run plugins:generate && bun run plugins:check
• bun run validate:packages
• bun run smoke:cli — 116 steps
• bun run smoke:mcp — 59 steps
• bun run smoke:cli:built — 31 steps
• bun run smoke:mcp:built — 9 steps
• post-integration focused regression suite — 897 tests, 3,032 assertions
• internal pre-flight clean; Claude Opus review clean on round 3, retained at term_975da2f2-76f3-44b0-b15f-8524d9ca2ca8

One settled-code CLI smoke attempt completed 107 steps before a second isolated auth probe returned neither live data nor auth guidance. The identical isolated probe immediately succeeded, and the complete serial rerun passed all four smoke cohorts above. During final integration, one concurrent built-CLI smoke raced package validation while it replaced dist; a serial rebuild and rerun passed all 31 built-CLI steps.

Targeted Claude and Codex agent evals produced no usable qualitative evidence: Codex reached its account usage limit before tool calls, and Claude stopped before artifacts were written. Deterministic descriptor, instruction-parity, workload, smoke, and full-suite coverage passed.

Production verification and rollout dependency

Post-deployment raw-service verification confirmed @ref in repository targetLabel, requestedTargetLabel, freshTargetLabel, and servedTargetLabel, plus unchanged @commit/file documentation locators. A no-wait indexing probe returned structured repoUrl/gitRef progress without a compact legacy target, and a missing-ref error contained no legacy compact target. Raw Agentic Ask code sources still used github:expressjs/express#<commit>, so the production Ask source producer remains the exact external dependency. This client normalizes those typed sources to @<commit> during rollout. Hosted clients receive the client-side behavior only after @githits/mcp is released, remote-mcp updates that dependency, and the hosted server is deployed.

Base note

Implementation and external review used origin/main at fe553ce. The branch then merged current origin/main at dc148c5, preserving #395's compact string-only MCP target schemas while applying the canonical @ref grammar to its descriptors, tests, plan, and pending release fragment.