Skip to content

[Spec 1210] codev doctor: detect protocol-file drift - #1223

Merged
waleedkadous merged 39 commits into
mainfrom
builder/aspir-1210
Jul 22, 2026
Merged

[Spec 1210] codev doctor: detect protocol-file drift#1223
waleedkadous merged 39 commits into
mainfrom
builder/aspir-1210

Conversation

@waleedkadous

Copy link
Copy Markdown
Contributor

Summary

Adds a Framework Drift report to codev doctor that surfaces a previously-silent failure class of the four-tier resolver (.codev/codev/ → cache → skeleton):

  1. Shadow drift — a project-local copy of a framework file that also ships in the installed skeleton. identical → redundant, safe to remove (info-only); differs → "customized or stale? — adjudicate" (warning, names the file, tier, resolved-winner, and skeleton package version).
  2. Skeleton staleness — installed @cluesmith/codev version vs npm latest, reported explicitly (installed X; latest Y), best-effort, offline-tolerant, bounded (~2.5s).

Report-only — no user file is ever modified. Quiet by default — the section prints only when a shadow exists or the skeleton is behind; no overrides + up-to-date/offline is a true no-op.

Closes #1210

Changes

  • New pure lib packages/codev/src/lib/protocol-drift-audit.ts (auditProtocolDrift, hasFrameworkShadows, checkSkeletonStaleness, fetchLatestVersion, formatters). Mirrors the pr-gate-audit / framework-ref-audit precedent; reuses lib/skeleton.ts resolver primitives so the audit and runtime resolution agree on "the skeleton". Raw-byte SHA-256 compare (EOL-only diffs → differs, conservatively). Scan set: protocols/, consult-types/, roles/; resources/ excluded (user-evolved).
  • Wire a Framework Drift section into packages/codev/src/commands/doctor.ts (quiet-by-default; staleness behind is a warning, up-to-date/offline is info; header subtitle adapts to shadow vs staleness-only). Documented CODEV_DOCTOR_FAKE_LATEST env test-seam (inert in real use).

Testing

  • 20 unit tests (protocol-drift-audit.test.ts): identical/differs/no-copy, both override tiers + resolved-winner, resources/ excluded, EOL-only → differs, no-op gate, staleness behind/equal/offline/throws, real npm lookup bounded+offline-tolerant, no-mutation, scan-set integrity, formatters.
  • 4 CLI e2e tests (doctor-drift.e2e.test.ts): differing shadow → adjudicate warning w/ version; identical shadow → info-only (no adjudicate line); no overrides → no section; no overrides + behind → staleness-only section.
  • Full suite green; manually verified against this repo's real codev/ overrides.

Deferred (per spec — non-blocking)

  • Item 2 (historical-default hash detection) → follow-up; layers onto DriftFinding.
  • codev update wiring (optional) → lib is structured for it.

Spec

codev/specs/1210-codev-doctor-detect-protocol-f.md

Review

codev/reviews/1210-codev-doctor-detect-protocol-f.md

…ng; accurate staleness-only header (codex review)
…m); assert identical is info-only; explicit EOL precondition (codex/claude review)
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

codev doctor: detect protocol-file drift — local copies shadowing newer skeleton files, and stale installed skeletons

1 participant