agentwrangler 0.1.0

package/dist/detector/measurement.js

@@ -0,0 +1,426 @@
+/**
+ * src/detector/measurement.ts — W4 Impact Ledger measurement pass.
+ *
+ * Owns the ADOPTED → MEASURING → MEASURED_* lifecycle transitions and the
+ * pre-adoption baseline snapshot for `recommendation_effects`:
+ *
+ *   - snapshotBeforeValue(db, rec): reads the realized baseline signal
+ *     (context_inventory_history token delta for D1; session floor context for
+ *     D2; routing-adherence score for D4; cache read/creation ratio for D8 —
+ *     RI9). NEVER derives a value from recommendations.modeled_savings_u_per_wk.
+ *   - runMeasurementPass(db, now, opts?): probe-driven pass called after each
+ *     context-probe run (wired via the post-probe seam in detector-hook.ts).
+ *
+ * Honesty rails (W4 design §6):
+ *   - Realized signal = observed history-table delta, never Claude self-report.
+ *   - Every transition UPDATE is guarded on the expected predecessor state;
+ *     zero changes ⇒ log + skip, never throw.
+ *   - Warning-class recs (D5 / LIMIT) never enter MEASURING and get no effect row.
+ *   - Unknown target_metric handlers log and leave the rec in MEASURING.
+ *
+ * Injected `now: Date` everywhere — never call new Date() in this module.
+ */
+import { GLOBAL_WORKSPACE_ID } from "./context-probe.js";
+import { isD1SourceBackedRecommendation, parseD1SourceIdentity } from "./d1-source-identity.js";
+/** Wait ≥1 day after adoption before entering MEASURING. */
+export const MIN_SETTLING_DAYS = 1;
+/** After-window length: once elapsed, the pass closes the measurement and writes a verdict. */
+export const AFTER_WINDOW_DAYS = 14;
+/**
+ * Minimum interval between measurement passes (design §10 Q5): the probe can
+ * fire every ~30s while tailing; most passes are no-ops. Throttled via
+ * user_config 'last_measurement_run_at'. Bypass with opts.force (tests).
+ */
+export const MEASUREMENT_MIN_INTERVAL_MS = 60 * 60 * 1000;
+const MS_PER_DAY = 24 * 60 * 60 * 1000;
+const SIGNAL_WINDOW_DAYS = 14;
+// ---------------------------------------------------------------------------
+// Schema guards
+// ---------------------------------------------------------------------------
+function tableExists(db, name) {
+    const row = db
+        .prepare("SELECT name FROM sqlite_master WHERE type='table' AND name = ?")
+        .get(name);
+    return row !== undefined;
+}
+// ---------------------------------------------------------------------------
+// Signal queries per detector class (design §2)
+// ---------------------------------------------------------------------------
+/** Latest context_inventory_history row for one source (any time ≤ upperBoundIso). */
+function latestHistoryRow(db, workspaceId, component, fileRef, upperBoundIso) {
+    const row = db
+        .prepare(`SELECT tokens, observed_at FROM context_inventory_history
+        WHERE workspace_id = ? AND component = ? AND file_ref = ? AND observed_at <= ?
+        ORDER BY observed_at DESC, id DESC LIMIT 1`)
+        .get(workspaceId, component, fileRef, upperBoundIso);
+    return row ?? null;
+}
+/**
+ * D2 signal: avg of per-session MIN(context_tokens) (cold-cache floor proxy)
+ * over RECONCILED sessions whose last_turn_at falls in [fromIso, toIso).
+ * Returns null when there are no qualifying sessions (not enough data).
+ */
+function avgFloorContext(db, scopeWorkspaceId, fromIso, toIso) {
+    const scoped = scopeWorkspaceId !== null;
+    const row = db
+        .prepare(`SELECT COUNT(avg_floor_ctx) AS n,
+              AVG(avg_floor_ctx) AS avg_floor_ctx
+         FROM (
+           SELECT (SELECT MIN(t2.context_tokens) FROM turns t2
+                    WHERE t2.session_id = s.session_id AND t2.provisional = 0) AS avg_floor_ctx
+             FROM sessions s
+            WHERE s.last_turn_at >= ? AND s.last_turn_at < ?
+              AND s.state = 'RECONCILED'
+              ${scoped ? "AND s.workspace_id = ?" : "AND s.workspace_id != ?"}
+         )
+        WHERE avg_floor_ctx IS NOT NULL`)
+        .get(fromIso, toIso, scopeWorkspaceId ?? GLOBAL_WORKSPACE_ID);
+    if (row.n === 0 || row.avg_floor_ctx === null)
+        return null;
+    return { value: row.avg_floor_ctx, n: row.n };
+}
+/**
+ * D4 signal: routing-adherence score = ROUND(100 × (1 − premium_share)) over
+ * non-sidechain reconciled turns in [fromIso, toIso), where premium = model
+ * contains 'opus'. The data-model's "mechanical turn" classifier is not yet
+ * shipped, so all reconciled turns are the mechanical set (conservative proxy —
+ * documented in the W4 build digest).
+ */
+function routingAdherenceScore(db, scopeWorkspaceId, fromIso, toIso) {
+    const scoped = scopeWorkspaceId !== null;
+    const sql = `SELECT COUNT(*) AS n,
+                      AVG(CASE WHEN model LIKE '%opus%' THEN 1.0 ELSE 0.0 END) AS premium_share
+                 FROM turns
+                WHERE is_sidechain = 0 AND provisional = 0 AND ts >= ? AND ts < ? ${scoped ? "AND workspace_id = ?" : ""}`;
+    const params = scoped ? [fromIso, toIso, scopeWorkspaceId] : [fromIso, toIso];
+    const row = db.prepare(sql).get(...params);
+    if (row.n === 0 || row.premium_share === null)
+        return null;
+    return { value: Math.round(100 * (1 - row.premium_share)), n: row.n };
+}
+/**
+ * D8 signal (RI9 cache-churn metric): cache read-to-creation ratio =
+ * SUM(cache_read_tokens) / SUM(cache_write_5m + cache_write_1h + cache_write_other)
+ * over non-sidechain reconciled turns in [fromIso, toIso). A higher ratio means
+ * more warm reads per creation (less full-price re-write churn) → improvement.
+ * Returns null when no qualifying turns exist or total creation is zero (the
+ * ratio is undefined — "not enough data", never a divide-by-zero).
+ */
+function cacheReadToCreationRatio(db, scopeWorkspaceId, fromIso, toIso) {
+    const scoped = scopeWorkspaceId !== null;
+    const sql = `SELECT COUNT(*) AS n,
+                      SUM(cache_read_tokens) AS reads,
+                      SUM(cache_write_5m + cache_write_1h + cache_write_other) AS creation
+                 FROM turns
+                WHERE is_sidechain = 0 AND provisional = 0 AND ts >= ? AND ts < ? ${scoped ? "AND workspace_id = ?" : ""}`;
+    const params = scoped ? [fromIso, toIso, scopeWorkspaceId] : [fromIso, toIso];
+    const row = db.prepare(sql).get(...params);
+    if (row.n === 0 || row.creation === null || row.creation === 0)
+        return null;
+    return { value: (row.reads ?? 0) / row.creation, n: row.n };
+}
+/** True when a detector class has a measurement handler (design §2a–§2c; RI9 adds D8). */
+function handlerFor(rec) {
+    const tm = rec.target_metric ?? "";
+    if (isD1SourceBackedRecommendation(rec))
+        return "D1";
+    if (rec.detector_id === "D2" || tm.startsWith("CACHE_READ_TOKENS_PER_WK"))
+        return "D2";
+    if (rec.detector_id === "D4" || tm.startsWith("ROUTING_ADHERENCE_SCORE"))
+        return "D4";
+    if (rec.detector_id === "D8" || tm.startsWith("cache_read_to_creation_ratio"))
+        return "D8";
+    return null;
+}
+/** Warning-class recs (D5 / LIMIT / explicit NONE) skip the lifecycle entirely (design §2d). */
+export function isWarningClass(rec) {
+    return (rec.category === "LIMIT" ||
+        rec.target_metric === "NONE" ||
+        rec.target_metric === "forecast_margin");
+}
+// ---------------------------------------------------------------------------
+// snapshotBeforeValue — design §4c
+// ---------------------------------------------------------------------------
+/**
+ * Read the pre-adoption baseline for a rec. Returns null when no signal is
+ * available for the class (the adopt path still writes an effect row with
+ * before_value = NULL and proceeds — design §4a error handling).
+ */
+export function snapshotBeforeValue(db, rec, now) {
+    const nowIso = now.toISOString();
+    const handler = handlerFor(rec);
+    if (handler === null || isWarningClass(rec))
+        return null;
+    if (handler === "D1" && !tableExists(db, "context_inventory_history"))
+        return null;
+    if (handler === "D1") {
+        const src = parseD1SourceIdentity(rec.evidence_json);
+        if (src === null)
+            return null;
+        const workspaceId = rec.scope_workspace_id ?? GLOBAL_WORKSPACE_ID;
+        const row = latestHistoryRow(db, workspaceId, src.component, src.fileRef, nowIso);
+        if (row === null)
+            return null;
+        // History appends one row per distinct version → the snapshot grain is one
+        // observation (the latest version's token count).
+        return { value: row.tokens, from_ts: row.observed_at, n: 1 };
+    }
+    if (handler === "D2") {
+        const fromIso = new Date(now.getTime() - SIGNAL_WINDOW_DAYS * MS_PER_DAY).toISOString();
+        const r = avgFloorContext(db, rec.scope_workspace_id, fromIso, nowIso);
+        return r === null ? null : { value: r.value, from_ts: fromIso, n: r.n };
+    }
+    if (handler === "D4") {
+        const fromIso = new Date(now.getTime() - SIGNAL_WINDOW_DAYS * MS_PER_DAY).toISOString();
+        const r = routingAdherenceScore(db, rec.scope_workspace_id, fromIso, nowIso);
+        return r === null ? null : { value: r.value, from_ts: fromIso, n: r.n };
+    }
+    // D8
+    const fromIso = new Date(now.getTime() - SIGNAL_WINDOW_DAYS * MS_PER_DAY).toISOString();
+    const r = cacheReadToCreationRatio(db, rec.scope_workspace_id, fromIso, nowIso);
+    return r === null ? null : { value: r.value, from_ts: fromIso, n: r.n };
+}
+function d1Verdict(beforeValue, afterValue) {
+    if (beforeValue === null || afterValue === null || beforeValue === 0) {
+        return { delta_pct: null, verdict: "INCONCLUSIVE" };
+    }
+    const deltaPct = ((afterValue - beforeValue) / beforeValue) * 100;
+    // Threshold is exclusive: < −5% ⇒ EFFECTIVE; [−5%, 0%] too small; growth ⇒ NO_EFFECT.
+    return { delta_pct: deltaPct, verdict: deltaPct < -5 ? "EFFECTIVE" : "NO_EFFECT" };
+}
+function d2Verdict(beforeValue, afterValue) {
+    if (beforeValue === null || afterValue === null || beforeValue === 0) {
+        return { delta_pct: null, verdict: "INCONCLUSIVE" };
+    }
+    const deltaPct = ((afterValue - beforeValue) / beforeValue) * 100;
+    // Noisier signal than D1 → higher bar (−15%).
+    return { delta_pct: deltaPct, verdict: deltaPct < -15 ? "EFFECTIVE" : "NO_EFFECT" };
+}
+function d4Verdict(beforeValue, afterValue) {
+    if (beforeValue === null || afterValue === null) {
+        return { delta_pct: null, verdict: "INCONCLUSIVE" };
+    }
+    // Score units are points (0–100); "delta_pct" carries the point delta here.
+    const points = afterValue - beforeValue;
+    return { delta_pct: points, verdict: points > 10 ? "EFFECTIVE" : "NO_EFFECT" };
+}
+function d8Verdict(beforeValue, afterValue) {
+    if (beforeValue === null || afterValue === null || beforeValue === 0) {
+        return { delta_pct: null, verdict: "INCONCLUSIVE" };
+    }
+    const deltaPct = ((afterValue - beforeValue) / beforeValue) * 100;
+    // A rising read/creation ratio = warmer cache = improvement; noisy signal → +15% bar.
+    return { delta_pct: deltaPct, verdict: deltaPct > 15 ? "EFFECTIVE" : "NO_EFFECT" };
+}
+// ---------------------------------------------------------------------------
+// After-value readers for the close step
+// ---------------------------------------------------------------------------
+function d1AfterValue(db, rec, adoptedIso, deadlineIso) {
+    const src = parseD1SourceIdentity(rec.evidence_json);
+    if (src === null)
+        return null;
+    const workspaceId = rec.scope_workspace_id ?? GLOBAL_WORKSPACE_ID;
+    // History rows exist only for DISTINCT versions (append-on-hash-change), so any
+    // post-adoption row IS a change. Take the last one in-window (net final state).
+    const row = db
+        .prepare(`SELECT tokens, observed_at FROM context_inventory_history
+        WHERE workspace_id = ? AND component = ? AND file_ref = ?
+          AND observed_at > ? AND observed_at <= ?
+        ORDER BY observed_at DESC, id DESC LIMIT 1`)
+        .get(workspaceId, src.component, src.fileRef, adoptedIso, deadlineIso);
+    if (row === undefined)
+        return null;
+    return { value: row.tokens, to_ts: row.observed_at, n: 1 };
+}
+function d2AfterValue(db, rec, adoptedMs, deadlineMs) {
+    const r = avgFloorContext(db, rec.scope_workspace_id, new Date(adoptedMs).toISOString(), new Date(deadlineMs).toISOString());
+    if (r === null)
+        return null;
+    return { value: r.value, to_ts: new Date(deadlineMs).toISOString(), n: r.n };
+}
+function d4AfterValue(db, rec, adoptedMs, deadlineMs) {
+    const r = routingAdherenceScore(db, rec.scope_workspace_id, new Date(adoptedMs).toISOString(), new Date(deadlineMs).toISOString());
+    if (r === null)
+        return null;
+    return { value: r.value, to_ts: new Date(deadlineMs).toISOString(), n: r.n };
+}
+function d8AfterValue(db, rec, adoptedMs, deadlineMs) {
+    const r = cacheReadToCreationRatio(db, rec.scope_workspace_id, new Date(adoptedMs).toISOString(), new Date(deadlineMs).toISOString());
+    if (r === null)
+        return null;
+    return { value: r.value, to_ts: new Date(deadlineMs).toISOString(), n: r.n };
+}
+// ---------------------------------------------------------------------------
+// Close step — MEASURING → MEASURED_*
+// ---------------------------------------------------------------------------
+function closeMeasurement(db, rec, now, result) {
+    const adoptedMs = Date.parse(rec.adopted_at);
+    if (Number.isNaN(adoptedMs))
+        return;
+    const deadlineMs = adoptedMs + AFTER_WINDOW_DAYS * MS_PER_DAY;
+    // The after-window closes at its deadline (or now, if the pass runs later).
+    const effectiveDeadlineMs = Math.min(deadlineMs, now.getTime());
+    const adoptedIso = rec.adopted_at;
+    const deadlineIso = new Date(effectiveDeadlineMs).toISOString();
+    // Baseline row as written by adoptRecommendation(): measured_at = adopted_at.
+    const effect = db
+        .prepare("SELECT before_value FROM recommendation_effects WHERE rec_id = ? AND measured_at = ?")
+        .get(rec.rec_id, adoptedIso);
+    if (effect === undefined) {
+        console.warn(`W4: no effect row for ${rec.rec_id}; cannot close measurement — skipped`);
+        result.skipped++;
+        return;
+    }
+    const handler = handlerFor(rec);
+    let computed;
+    let afterValue = null;
+    let afterN = null;
+    let afterTo = deadlineIso;
+    if (handler === "D1") {
+        const a = d1AfterValue(db, rec, adoptedIso, deadlineIso);
+        if (a === null) {
+            // Probe ran but the source never changed within the window.
+            computed = { delta_pct: null, verdict: "INCONCLUSIVE" };
+        }
+        else {
+            afterValue = a.value;
+            afterN = a.n;
+            afterTo = a.to_ts;
+            computed = d1Verdict(effect.before_value, a.value);
+        }
+    }
+    else if (handler === "D2") {
+        const a = d2AfterValue(db, rec, adoptedMs, effectiveDeadlineMs);
+        if (a === null) {
+            computed = { delta_pct: null, verdict: "INCONCLUSIVE" };
+        }
+        else {
+            afterValue = a.value;
+            afterN = a.n;
+            afterTo = a.to_ts;
+            computed = d2Verdict(effect.before_value, a.value);
+        }
+    }
+    else if (handler === "D4") {
+        const a = d4AfterValue(db, rec, adoptedMs, effectiveDeadlineMs);
+        if (a === null) {
+            computed = { delta_pct: null, verdict: "INCONCLUSIVE" };
+        }
+        else {
+            afterValue = a.value;
+            afterN = a.n;
+            afterTo = a.to_ts;
+            computed = d4Verdict(effect.before_value, a.value);
+        }
+    }
+    else if (handler === "D8") {
+        const a = d8AfterValue(db, rec, adoptedMs, effectiveDeadlineMs);
+        if (a === null) {
+            computed = { delta_pct: null, verdict: "INCONCLUSIVE" };
+        }
+        else {
+            afterValue = a.value;
+            afterN = a.n;
+            afterTo = a.to_ts;
+            computed = d8Verdict(effect.before_value, a.value);
+        }
+    }
+    else {
+        console.info(`W4: no measurement handler for target_metric ${rec.target_metric}; staying MEASURING`);
+        result.skipped++;
+        return;
+    }
+    // Write the verdict onto the adoption-cycle effect row (guarded: only when still open).
+    const upd = db
+        .prepare(`UPDATE recommendation_effects
+          SET after_from = ?, after_to = ?, after_value = ?, after_n = ?, delta_pct = ?, verdict = ?
+        WHERE rec_id = ? AND measured_at = ? AND verdict IS NULL`)
+        .run(adoptedIso, afterTo, afterValue, afterN, computed.delta_pct, computed.verdict, rec.rec_id, adoptedIso);
+    if (upd.changes === 0) {
+        console.warn(`W4: effect row for ${rec.rec_id} already closed or missing — skipped`);
+        result.skipped++;
+        return;
+    }
+    // INCONCLUSIVE maps to the NO_EFFECT state (the state enum has no INCONCLUSIVE);
+    // the effect row's verdict column keeps the honest distinction for the ledger.
+    const nextState = computed.verdict === "EFFECTIVE" ? "MEASURED_EFFECTIVE" : "MEASURED_NO_EFFECT";
+    const trans = db
+        .prepare("UPDATE recommendations SET state = ? WHERE rec_id = ? AND state = 'MEASURING'")
+        .run(nextState, rec.rec_id);
+    if (trans.changes === 0) {
+        console.warn(`W4: rec ${rec.rec_id} not in MEASURING at close — skipped`);
+        result.skipped++;
+        return;
+    }
+    result.verdicts++;
+}
+/**
+ * Probe-driven measurement pass. Idempotent, guarded, never throws:
+ *   ADOPTED → MEASURING    when now ≥ adopted_at + MIN_SETTLING_DAYS
+ *   MEASURING → MEASURED_* when now ≥ adopted_at + AFTER_WINDOW_DAYS
+ * Warning-class recs (D5/LIMIT) are skipped entirely; unknown target_metric
+ * handlers log and stay in MEASURING.
+ */
+export function runMeasurementPass(db, now, opts) {
+    const result = { to_measuring: 0, verdicts: 0, skipped: 0 };
+    if (!tableExists(db, "context_inventory_history")) {
+        console.warn("W4: context_inventory_history not available; measurement pass skipped");
+        return result;
+    }
+    // Throttle (design §10 Q5): skip when the last run is younger than the interval.
+    if (opts?.force !== true && tableExists(db, "user_config")) {
+        const last = db
+            .prepare("SELECT value FROM user_config WHERE key = 'last_measurement_run_at'")
+            .get();
+        if (last !== undefined && last.value !== null && last.value !== "") {
+            const lastMs = Date.parse(last.value);
+            if (!Number.isNaN(lastMs) && now.getTime() - lastMs < MEASUREMENT_MIN_INTERVAL_MS) {
+                return result;
+            }
+        }
+    }
+    try {
+        const rows = db
+            .prepare(`SELECT rec_id, detector_id, category, scope_workspace_id, evidence_json,
+                target_metric, state, adopted_at
+           FROM recommendations
+          WHERE state IN ('ADOPTED', 'MEASURING') AND adopted_at IS NOT NULL
+          ORDER BY adopted_at ASC, rec_id ASC`)
+            .all();
+        for (const rec of rows) {
+            if (isWarningClass(rec))
+                continue; // D5 stays ADOPTED; no MEASURING, no effect rows
+            const adoptedMs = Date.parse(rec.adopted_at);
+            if (Number.isNaN(adoptedMs))
+                continue;
+            let state = rec.state;
+            if (state === "ADOPTED") {
+                if (now.getTime() < adoptedMs + MIN_SETTLING_DAYS * MS_PER_DAY)
+                    continue;
+                const r = db
+                    .prepare("UPDATE recommendations SET state = 'MEASURING' WHERE rec_id = ? AND state = 'ADOPTED'")
+                    .run(rec.rec_id);
+                if (r.changes === 0) {
+                    console.warn(`W4: rec ${rec.rec_id} not in ADOPTED for MEASURING transition — skipped`);
+                    result.skipped++;
+                    continue;
+                }
+                state = "MEASURING";
+                result.to_measuring++;
+            }
+            if (state !== "MEASURING")
+                continue;
+            if (now.getTime() < adoptedMs + AFTER_WINDOW_DAYS * MS_PER_DAY)
+                continue; // window still open
+            closeMeasurement(db, rec, now, result);
+        }
+    }
+    finally {
+        // Record the run regardless of partial failures so the throttle holds.
+        if (tableExists(db, "user_config")) {
+            db.prepare(`INSERT INTO user_config (key, value, updated_at) VALUES ('last_measurement_run_at', ?, ?)
+         ON CONFLICT(key) DO UPDATE SET value = excluded.value, updated_at = excluded.updated_at`).run(now.toISOString(), now.toISOString());
+        }
+    }
+    return result;
+}

package/dist/detector/practice-registry.js

@@ -0,0 +1,259 @@
+/**
+ * src/detector/practice-registry.ts — BM1 published-best-practice scorecard.
+ *
+ * The registry is DATA, not a code path: a typed list of the published Claude
+ * Code best practices, each carrying its own citation (source_url + source_date)
+ * so a practice that drifts with harness versions is visibly stale and updating
+ * one is a data edit. Status is COMPUTED on request from existing aggregates
+ * (turns / sessions / context_inventory / recommendations / detector statuses)
+ * and is never stored.
+ *
+ * §0.5 tier compliance: this is a measurement surface, not a rec — it emits zero
+ * new advice sentences. ATTENTION rows deep-link to an existing artifact via
+ * `artifact_link` (null when none exists); the UI renders status + citation only.
+ *
+ * SEC-101: every entry field is static public metadata (URLs, dates, numbers)
+ * and every computed input is an existing count/ratio — no transcript content.
+ *
+ * Excluded from v1 (spec §BM1): the effort/thinking practice (spec-prohibited
+ * advisory — spec-d11-effort-mismatch.md:8-10); prompt structural-ordering (not
+ * observable locally); "agent teams use 7× tokens" (no local lever).
+ */
+import { readFileSync } from "node:fs";
+import { getOffloadShare } from "../query/api/offload-share.js";
+import { getDetectorStatuses } from "./index.js";
+// ── Thresholds (registry-declared; UNVALIDATED defaults, tooltip-surfaced) ────
+/** P1: ATTENTION when this week's cache-read ratio is this many points below the trailing-median. */
+const P1_ATTENTION_DROP_PTS = 10;
+/** P1: minimum priced-input volume (input + cache_read tokens) for the current week to be judged. */
+const P1_MIN_WEEK_VOLUME_TOKENS = 50_000;
+/** P1: minimum number of prior weeks with data before a median comparison is trustworthy. */
+const P1_MIN_PRIOR_WEEKS = 4;
+/** P2: ATTENTION when more than this fraction of non-trivial sessions switched models. */
+const P2_ATTENTION_FRACTION = 0.2;
+/** P2: a session is "non-trivial" at or above this many non-sidechain turns in the window. */
+const P2_MIN_SESSION_TURNS = 5;
+/** P5: official CLAUDE.md line ceiling (Source C, code.claude.com/docs/en/costs). */
+const P5_MAX_CLAUDE_MD_LINES = 200;
+const WEEK_MS = 7 * 24 * 60 * 60 * 1000;
+// ── Editorial registry (authored direct — statements + citations) ─────────────
+/**
+ * Static half of each entry. `status` is filled by getPractices; the literal
+ * "NO_DATA" here is a placeholder that is always overwritten before return.
+ */
+const REGISTRY = [
+    {
+        practice_id: "P1",
+        statement: "Watch cache-read health — a few points of cache-miss rate dramatically affect cost and latency.",
+        source_url: "https://claude.com/blog/lessons-from-building-claude-code-prompt-caching-is-everything",
+        source_date: "2026-04-30",
+        threshold: {
+            value: P1_ATTENTION_DROP_PTS,
+            rationale: "Trend-only (no published absolute threshold): ATTENTION when this week's cache-read ratio is >10 points below the trailing-8-week median; NO_DATA under minimum weekly volume.",
+        },
+        signal: "cache_read_ratio_wk",
+        artifact_link: null,
+    },
+    {
+        practice_id: "P2",
+        statement: "Don't switch models mid-session — switching forces a cache rebuild.",
+        source_url: "https://claude.com/blog/lessons-from-building-claude-code-prompt-caching-is-everything",
+        source_date: "2026-04-30",
+        threshold: {
+            value: P2_ATTENTION_FRACTION * 100,
+            rationale: "ATTENTION when >20% of the week's non-trivial sessions (≥5 non-sidechain turns) used more than one model.",
+        },
+        signal: "distinct_model_per_session_wk",
+        artifact_link: null,
+    },
+    {
+        practice_id: "P3",
+        statement: "Respect the cache-TTL cadence — an idle gap longer than the TTL re-writes the whole context at base price.",
+        source_url: "https://claude.com/blog/lessons-from-building-claude-code-prompt-caching-is-everything",
+        source_date: "2026-04-30",
+        threshold: {
+            value: null,
+            rationale: "Detector-owned threshold: status follows the D8 CACHE_WRITE_CHURN detector, which flags TTL-crossing cache-write spikes (subscription TTL 1h / API 5m).",
+        },
+        signal: "D8",
+        artifact_link: "/settings",
+    },
+    {
+        practice_id: "P4",
+        statement: "Use /clear between tasks — stale context bills on every subsequent message.",
+        source_url: "https://code.claude.com/docs/en/costs",
+        source_date: "2026-09-02",
+        threshold: {
+            value: null,
+            rationale: "Binary: ATTENTION whenever the D2 SESSION_LONG_FULL_CONTEXT detector is firing in-window.",
+        },
+        signal: "D2",
+        artifact_link: "/recommendations",
+    },
+    {
+        practice_id: "P5",
+        statement: "Keep CLAUDE.md lean — the docs recommend under 200 lines; it loads into context every session.",
+        source_url: "https://code.claude.com/docs/en/costs",
+        source_date: "2026-09-02",
+        threshold: {
+            value: P5_MAX_CLAUDE_MD_LINES,
+            rationale: "PASS at or below the official 200-line CLAUDE.md ceiling (Source C), ATTENTION above it.",
+        },
+        signal: "claude_md_line_count",
+        artifact_link: null,
+    },
+    {
+        practice_id: "P6",
+        statement: "Right-size the model — Opus costs ~5× more than Sonnet per token; reserve it for complex tasks.",
+        source_url: "https://code.claude.com/docs/en/costs",
+        source_date: "2026-09-02",
+        threshold: {
+            value: null,
+            rationale: "Binary: ATTENTION whenever the D4 MODEL_MISMATCH detector is firing in-window.",
+        },
+        signal: "D4",
+        artifact_link: "/recommendations",
+    },
+    {
+        practice_id: "P7",
+        statement: "Offload to subagents — specialized subagents return 1–2k-token summaries despite consuming tens of thousands internally.",
+        source_url: "https://www.anthropic.com/engineering/effective-context-engineering-for-ai-agents",
+        source_date: "2025-09-29",
+        threshold: {
+            value: null,
+            rationale: "Trend-only: the source gives a shape, not a target, so no threshold is claimed — the observed offload share is rendered alongside the citation (PASS when observable, NO_DATA otherwise).",
+        },
+        signal: "getOffloadShare",
+        artifact_link: null,
+    },
+    {
+        practice_id: "P8",
+        statement: "Keep the tool catalog stable and small — any tool-set change invalidates the cache.",
+        source_url: "https://claude.com/blog/lessons-from-building-claude-code-prompt-caching-is-everything",
+        source_date: "2026-04-30",
+        threshold: {
+            value: null,
+            rationale: "Partial: status is computed from the installed tool-catalog footprint only (D10 CATALOG_FOOTPRINT, config-state); the loaded-vs-installed gap is a UI tooltip disclosure.",
+        },
+        signal: "D10",
+        artifact_link: null,
+    },
+];
+// ── Status computation ────────────────────────────────────────────────────────
+/** Map a live detector status to a practice status. */
+export function detectorPracticeStatus(kind) {
+    if (kind === "ACTIVE")
+        return "ATTENTION";
+    if (kind === "INACTIVE")
+        return "PASS";
+    return "NO_DATA"; // NOT_EVALUATED | BLOCKED | absent
+}
+/** Cache-read ratio and its priced-input volume over [fromIso, toIso). */
+function cacheReadRatio(db, fromIso, toIso) {
+    const row = db
+        .prepare(`SELECT COALESCE(SUM(cache_read_tokens),0) AS read,
+              COALESCE(SUM(input_tokens + cache_read_tokens),0) AS base
+         FROM turns
+        WHERE ts >= ? AND ts < ? AND provisional = 0`)
+        .get(fromIso, toIso);
+    return { ratio: row.base === 0 ? null : row.read / row.base, volume: row.base };
+}
+/** P1: current-week cache-read ratio vs trailing-8-week median. */
+function computeP1(db, toIso) {
+    const end = new Date(toIso).getTime();
+    const current = cacheReadRatio(db, new Date(end - WEEK_MS).toISOString(), toIso);
+    if (current.ratio === null || current.volume < P1_MIN_WEEK_VOLUME_TOKENS)
+        return "NO_DATA";
+    const priors = [];
+    for (let i = 1; i <= 8; i++) {
+        const wTo = new Date(end - i * WEEK_MS).toISOString();
+        const wFrom = new Date(end - (i + 1) * WEEK_MS).toISOString();
+        const r = cacheReadRatio(db, wFrom, wTo);
+        if (r.ratio !== null)
+            priors.push(r.ratio);
+    }
+    if (priors.length < P1_MIN_PRIOR_WEEKS)
+        return "NO_DATA";
+    priors.sort((a, b) => a - b);
+    const mid = Math.floor(priors.length / 2);
+    const median = priors.length % 2 === 0
+        ? ((priors[mid - 1] ?? 0) + (priors[mid] ?? 0)) / 2
+        : (priors[mid] ?? 0);
+    const dropPts = (median - current.ratio) * 100;
+    return dropPts > P1_ATTENTION_DROP_PTS ? "ATTENTION" : "PASS";
+}
+/** P2: fraction of non-trivial sessions in-window that used more than one model. */
+function computeP2(db, fromIso, toIso) {
+    const rows = db
+        .prepare(`SELECT session_id, COUNT(DISTINCT model) AS mc, COUNT(*) AS tc
+         FROM turns
+        WHERE ts >= ? AND ts < ? AND provisional = 0 AND is_sidechain = 0
+        GROUP BY session_id
+       HAVING tc >= ?`)
+        .all(fromIso, toIso, P2_MIN_SESSION_TURNS);
+    if (rows.length === 0)
+        return "NO_DATA";
+    const switched = rows.filter((r) => r.mc > 1).length;
+    return switched / rows.length > P2_ATTENTION_FRACTION ? "ATTENTION" : "PASS";
+}
+/** P5: line count of the most-recently-probed CLAUDE.md against the 200-line ceiling. */
+function computeP5(db) {
+    const row = db
+        .prepare(`SELECT file_ref
+         FROM context_inventory
+        WHERE component = 'CLAUDE_MD'
+        ORDER BY probed_at DESC
+        LIMIT 1`)
+        .get();
+    if (!row)
+        return "NO_DATA";
+    try {
+        // Structural read only: the line count leaves this surface, never the content (SEC-101).
+        const text = readFileSync(row.file_ref, "utf8");
+        const lines = text.length === 0 ? 0 : text.split("\n").length;
+        return lines <= P5_MAX_CLAUDE_MD_LINES ? "PASS" : "ATTENTION";
+    }
+    catch {
+        return "NO_DATA";
+    }
+}
+/** P7: offload share is observable → PASS (trend-only), else NO_DATA. No ATTENTION line. */
+function computeP7(db, fromIso, toIso) {
+    const share = getOffloadShare(db, { workspaceId: null, from: fromIso, to: toIso }).data
+        ?.offload_share;
+    return share === null || share === undefined ? "NO_DATA" : "PASS";
+}
+/**
+ * Compute the practice scorecard over [from, to). Detector-backed practices
+ * (P3/P4/P6/P8) read the live detector statuses anchored at `to`; the rest read
+ * existing aggregates directly.
+ */
+export function getPractices(db, opts) {
+    const { from, to } = opts;
+    const detectorStatus = new Map();
+    for (const s of getDetectorStatuses(db, { now: new Date(to) })) {
+        detectorStatus.set(s.detector_id, s.status);
+    }
+    const practices = REGISTRY.map((entry) => {
+        let status;
+        switch (entry.practice_id) {
+            case "P1":
+                status = computeP1(db, to);
+                break;
+            case "P2":
+                status = computeP2(db, from, to);
+                break;
+            case "P5":
+                status = computeP5(db);
+                break;
+            case "P7":
+                status = computeP7(db, from, to);
+                break;
+            default:
+                // P3→D8, P4→D2, P6→D4, P8→D10 (signal is the detector id).
+                status = detectorPracticeStatus(detectorStatus.get(entry.signal));
+        }
+        return { ...entry, status };
+    });
+    return { practices, window: { from, to } };
+}