2026-08-06 infrastructure sources audit and wiki promotion

Audited the legacy sources/ tree claim-by-claim against the virdx repos, promoted what still held into wiki/ sops, deleted the rest, and added CI formatting enforcement.

Work Done

Goal: sources/ was suspected stale. It was also load-bearing — wiki/ pages linked into it — so “clean up” meant audit, promote, relink, delete.

Mechanical audit. 31 docs under sources/{guides,investigations,incidents} were audited by parallel sub-agents (Sonnet 4.5), one JSON verdict per doc: every path/symbol/command/version/URL classified EXISTS / MOVED / GONE / UNVERIFIABLE with the command + output as evidence, checked against origin/HEAD of the real repos via the librarian checkout script. Verdicts: 8 CURRENT, 6 MOSTLY_CURRENT, 1 PARTLY_STALE, 8 STALE, 9 TIMELESS (lesson survives, code moved). The single most common cause of rot: the virdx/data-platform archive (2026-05-27) → mono (apps/api → apps/vxdata-api, apps/worker → apps/vxdata-jobs, packages/client → packages/vxdata-sdk).
Promotion. 10 new pages written from the surviving content with corrected paths: infrastructure/sops/{vxdata-sdk-and-schema-model, vxdata-jobs-ingestion, conda-packaging-and-releases, keel-auto-redeploy, coder-workspaces, dashboard-histo-tile-serving, vxconvert-dicom-to-bids, phi-safe-data-handling}, new histo/sops/{histo-preprocessing-performance, viseg-inference} (+ a histo/sops/index.md, the first one), and infrastructure/self-hosted-inference.md. Cluster/incident lessons were appended to the existing gotchas and executing-jobs SOPs instead of becoming new pages; the 12KB dashboard-metrics guide was compressed into the existing dashboard SOP.
Deletion + relink. sources/{guides,investigations,incidents} removed entirely; all inbound wiki/ links rewritten to the new locations; every internal link in the repo re-verified from scratch. sources/ now holds monthly reports only, and index.md says so.
Formatting enforcement. .lefthook.yaml (prettier 3.6.2 on staged markdown) already existed, but nothing told a new clone to run lefthook install and nothing caught --no-verify. Added .github/workflows/format.yml (prettier --check "**/*.md", same pinned version) and a lefthook install line to the README setup.

Lessons Learned: Pitfalls

sources/ was not inert legacy — wiki/ depended on it. Six wiki/ pages linked into it, including virdx/index.md pointing at the sources/*/index.md files as “where to look for more”. Deleting the tree without the relink pass would have broken navigation from the top-level orientation page. Any future prune should start with rg "sources/" wiki index.md.
Stale docs were confidently specific, which is what made them dangerous. vxdata-sdk-and-local-dev.md stated 1.0.x / pin >=1.0,<2 while both packages are at 2.1.0; vxdata-production-deployment.md asserted an ownership split (mono/apps/vxdata-api/deployments/k8s) that no longer exists — infra_k8s/current/vxdata-production/ owns all runtime manifests. Neither doc looked stale from the inside.
type: Guide + a plausible path is not evidence. Only the per-claim re-check against the repos separated the 9 TIMELESS docs (keep the lesson, throw away the paths) from the 8 STALE ones (the machinery itself is gone: buildah workflows, the local registry mirror, the ollama deployment, VALIS).
A dev bearer token had been written into a guide. The promoted page now points at principals.example.json instead. Worth grepping for token-shaped strings when promoting older material.

Lessons Learned: Improvements

Record the data-platform → mono rename map once, prominently. Nearly every stale path in the audit was mechanically derivable from three renames. It is now stated in the promoted pages; wiki/workstreams/infrastructure/index.md would be a better single home for it.
Date every claim that can rot. The pages that survived intact were the ones with a version, PR number, or “verified ” attached; the ones that rotted silently had bare present-tense assertions. New wiki pages carry “verified 2026-08-06” markers on the volatile parts — keep that habit.
sources/ should not be re-grown. index.md now says episodic material goes to inbox/ and durable knowledge to wiki/. If a future agent wants a point-in-time write-up, it belongs in inbox/ until the dreamer synthesizes it.
Two things were deliberately left alone. Monthly reports (point-in-time records that cannot go stale by definition) stay under sources/, and raycast-pi-try-launcher.md was deleted as personal tooling rather than VIRDX knowledge. Both are judgment calls a future maintainer may want to revisit.
The audit artifacts are reproducible, not saved. Per-doc JSON verdicts lived in /tmp/kb-audit/ and were not committed. If a periodic staleness sweep becomes routine, that JSON contract is the thing to formalize.