Phase 45 (doc-drift detection + context7 integration) was mostly
already shipped in prior sessions: DocRef struct, doc_drift module,
/doc_drift/check + /doc_drift/resolve endpoints, mcp-server's
context7_bridge.ts, boost exclusion in compute_boost_for_filtered
_with_role. The two missing pieces this commit lands:
1. POST /vectors/playbook_memory/doc_drift/scan — batch scan across
ALL active playbooks. Iterates the snapshot, filters out retired
+ already-flagged + no-doc_refs, runs check_all_refs on the rest,
flags drifted entries via PlaybookMemory::flag_doc_drift.
2. Per-detection write to data/_kb/doc_drift_corrections.jsonl. One
row per drifted playbook with playbook_id + scanned_at +
drifted_tools[] + per_tool[] + recommended_action. Downstream
consumers (overview model, operator dashboard, scrum_master
prompt enrichment) read this file to surface "this playbook
compounded the wrong way" signals to humans.
Idempotent by design:
- Already-flagged entries with no resolved_at are counted as
`already_flagged` and skipped (no double-flag, no duplicate row).
- Re-scanning after resolve_doc_drift() unflags an entry brings it
back into the eligible set on the next scan.
Aggregate response shape:
{
"scanned": N, // playbooks with doc_refs we checked
"newly_flagged": N, // drift detected this scan
"already_flagged": N, // skipped (still under review)
"skipped_retired": N,
"skipped_no_refs": N, // pre-Phase-45 playbooks
"drifted_by_tool": {tool: count},
"corrections_written": N,
}
Verified live:
POST /doc_drift/scan
→ scanned=4, newly_flagged=4, drifted_by_tool={docker:4, terraform:1},
corrections_written=4
POST /doc_drift/scan (re-run)
→ scanned=0, newly_flagged=0, already_flagged=6 (idempotent)
data/_kb/doc_drift_corrections.jsonl
→ 5 rows total (existing seed + this scan)
Phase 45 closure status:
DocRef + PlaybookEntry.doc_refs ✅ prior session
doc_drift module + check_all_refs ✅ prior session
/doc_drift/check + /resolve ✅ prior session
mcp-server/context7_bridge.ts ✅ prior session
boost exclusion in compute_boost_* ✅ prior session
/doc_drift/scan + corrections.jsonl ✅ THIS COMMIT
The 0→85% thesis stays valid against external doc drift. Popular
playbooks can no longer compound the wrong way as Docker / Terraform
/ React / etc. patch their docs — the scan flags drift, the boost
filter excludes the playbook, the operator reviews the corrections
.jsonl, and a revise call (Phase 27) supersedes the stale entry
with corrected operation/approach.
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
6cafa7ec0e