@cluesmith/codev 3.2.3 → 3.3.0

package/dist/lib/prompt-behavior-metrics.js

@@ -0,0 +1,290 @@
+/**
+ * prompt-behavior-metrics.ts — behavioural-impact measurement of prompt changes.
+ * Spec 1252, criterion M12 / Appendix D / test T14.
+ *
+ * Lives in `src/lib/` beside `protocol-drift-audit.ts` and
+ * `framework-ref-audit.ts` — same module shape (a measurement library, unit
+ * tested), and it needs this package's `js-yaml` dependency, which a root-level
+ * `scripts/` file cannot resolve in this pnpm workspace. The runnable entry
+ * point is `packages/codev/scripts/measure-prompt-behavior.ts`.
+ *
+ * ## Why this exists
+ *
+ * M6 counts words. A word reduction that degrades agent compliance is a loss,
+ * and word counts cannot see that. This script measures BEHAVIOUR: how often
+ * reviewers demand changes, how many rounds phases take, and whether scar rules
+ * are being violated.
+ *
+ * Run at Phase 1 (before any prompt content changes) to produce the baseline,
+ * and again in the post-merge verify phase to compare.
+ *
+ * ## What is deliberately NOT measured, and why
+ *
+ * Two metrics were requested and cannot be delivered from committed history.
+ * They are omitted rather than faked, because a plausible-looking zero is worse
+ * than an absent metric:
+ *
+ *   - GATE REJECTION COUNTS. Across all projects, a gate's `status` only ever
+ *     takes `approved | complete | in_progress | pending` — there is no
+ *     `rejected` state — and `requested_at` is a scalar that a re-request
+ *     OVERWRITES rather than appends to. A rejected-then-approved gate is
+ *     indistinguishable from a clean first-time approval. (Making this minable
+ *     would need porch to append gate events; out of scope here.)
+ *
+ *   - HISTORICAL CONSULT TOKENS/COST. Raw consult logs (`codev/projects/*​/*.txt`)
+ *     are gitignored, and `consult stats` is a rolling 30-day machine-local DB.
+ *     There is no historical series to baseline against, so B5 is captured as a
+ *     FORWARD snapshot only — advisory, non-deterministic, and excluded from
+ *     T14's determinism assertion and from every rollback trigger.
+ *
+ * Usage (from packages/codev):
+ *   npx tsx scripts/measure-prompt-behavior.ts [repo-root]
+ *   npx tsx scripts/measure-prompt-behavior.ts --json
+ */
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+import * as yaml from 'js-yaml';
+// ---------------------------------------------------------------------------
+// The eight ratified scar rules (decision D3) and their violation markers.
+//
+// These patterns look for the DANGEROUS COMMAND / ACT, not for the rule text.
+// That is still fuzzy: documentation *about* a rule reads much like a violation
+// of it. Hence excerpts, not just counts — a human adjudicates before the hard
+// rollback trigger fires.
+// ---------------------------------------------------------------------------
+const SCAR_PATTERNS = [
+    { rule: 'git-add-all', re: /\bgit\s+add\s+(-A\b|--all\b|\.(?:\s|$))/ },
+    { rule: 'destroy-worktree', re: /\bgit\s+worktree\s+remove\b|\bgit\s+branch\s+-D\b/ },
+    { rule: 'destructive-git', re: /\bgit\s+(reset\s+--hard|checkout\s+--\s+\.|clean\s+-[a-z]*f|stash\b)/ },
+    { rule: 'auto-approve-gate', re: /auto-?approv\w*/i },
+    { rule: 'hand-edit-status', re: /(hand|manual\w*)[- ]edit\w*\s+status\.yaml|edited?\s+status\.yaml\s+(directly|by hand)/i },
+    { rule: 'afx-from-worktree', re: /\bafx\s+spawn\b[^\n]*\bfrom\s+(inside\s+)?(a\s+)?worktree/i },
+    { rule: 'kill-shellper', re: /kill\w*\s+[^\n]{0,40}shellper/i },
+    { rule: 'restart-tower', re: /\b(restart|stop)\w*\s+tower\b/i },
+];
+/** Phrases indicating the surrounding text DESCRIBES a rule rather than reports a breach. */
+const DOCUMENTATION_MARKERS = /\b(never|do not|don'?t|must not|forbidden|prohibited|avoid|rule|policy|reminder|guard|prevent)\b/i;
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+function mean(xs) {
+    return xs.length ? xs.reduce((a, b) => a + b, 0) / xs.length : 0;
+}
+function median(xs) {
+    if (!xs.length)
+        return 0;
+    const s = [...xs].sort((a, b) => a - b);
+    const m = Math.floor(s.length / 2);
+    return s.length % 2 ? s[m] : (s[m - 1] + s[m]) / 2;
+}
+function round2(n) {
+    return Math.round(n * 100) / 100;
+}
+function walk(dir, pred) {
+    if (!fs.existsSync(dir))
+        return [];
+    const out = [];
+    for (const e of fs.readdirSync(dir, { withFileTypes: true })) {
+        const p = path.join(dir, e.name);
+        if (e.isDirectory())
+            out.push(...walk(p, pred));
+        else if (pred(p))
+            out.push(p);
+    }
+    return out;
+}
+// ---------------------------------------------------------------------------
+// Metric collection
+// ---------------------------------------------------------------------------
+/**
+ * B1/B2/B4 — CMAP verdicts and review rounds.
+ *
+ * Sample: projects whose `status.yaml` has a non-empty `history`. In practice
+ * this is SPIR (and one legacy `spider`) — porch only persists per-plan-phase
+ * review history for protocols that loop that way, so pir/bugfix/air contribute
+ * nothing. Sorted for deterministic output.
+ */
+function collectReviewMetrics(root, excludeProjects, includeProjects) {
+    const projDir = path.join(root, 'codev', 'projects');
+    const files = fs.existsSync(projDir)
+        ? fs
+            .readdirSync(projDir)
+            .filter((d) => (includeProjects ? includeProjects.includes(d) : true))
+            .filter((d) => !excludeProjects.includes(d))
+            .map((d) => path.join(projDir, d, 'status.yaml'))
+            .filter((f) => fs.existsSync(f))
+            .sort()
+        : [];
+    const verdictCounts = {};
+    const phaseRounds = [];
+    const projectRounds = [];
+    const sampleProjects = [];
+    for (const f of files) {
+        let doc;
+        try {
+            doc = yaml.load(fs.readFileSync(f, 'utf-8'));
+        }
+        catch {
+            continue; // a malformed status file must not abort the measurement
+        }
+        const history = doc?.history ?? [];
+        if (!history.length)
+            continue;
+        sampleProjects.push(path.basename(path.dirname(f)));
+        const byPhase = new Map();
+        for (const item of history) {
+            for (const r of item.reviews ?? []) {
+                const v = r.verdict ?? 'UNKNOWN';
+                verdictCounts[v] = (verdictCounts[v] ?? 0) + 1;
+            }
+            const ph = item.plan_phase ?? '__none__';
+            byPhase.set(ph, Math.max(byPhase.get(ph) ?? 0, item.iteration ?? 0));
+        }
+        const rounds = [...byPhase.values()];
+        phaseRounds.push(...rounds);
+        projectRounds.push(rounds.reduce((a, b) => a + b, 0));
+    }
+    const total = Object.values(verdictCounts).reduce((a, b) => a + b, 0);
+    return {
+        verdictCounts,
+        total,
+        rcRate: total ? (verdictCounts['REQUEST_CHANGES'] ?? 0) / total : 0,
+        phaseRounds,
+        projectRounds,
+        sampleProjects: sampleProjects.sort(),
+    };
+}
+/**
+ * B3 — candidate scar-rule violations mined from committed prose.
+ *
+ * Scans `codev/reviews/*.md` and `codev/state/*_thread.md`. Emits EXCERPTS, not
+ * just counts: the mining cannot distinguish "we violated this" from "never do
+ * this", so every hit is a candidate requiring human adjudication. Lines that
+ * look like rule documentation are filtered out to cut the obvious noise, but
+ * the filter is conservative by design — it is better to hand a human a false
+ * positive than to silently drop a real breach.
+ */
+function collectScarHits(root, excludeBasenamePrefixes) {
+    const excluded = (p) => excludeBasenamePrefixes.some((pre) => path.basename(p).startsWith(pre));
+    const targets = [
+        ...walk(path.join(root, 'codev', 'reviews'), (p) => p.endsWith('.md')),
+        ...walk(path.join(root, 'codev', 'state'), (p) => p.endsWith('_thread.md')),
+    ]
+        .filter((p) => !excluded(p))
+        .sort();
+    const hits = [];
+    for (const file of targets) {
+        const lines = fs.readFileSync(file, 'utf-8').split('\n');
+        lines.forEach((line, i) => {
+            if (DOCUMENTATION_MARKERS.test(line))
+                return; // prescriptive, not a breach report
+            for (const { rule, re } of SCAR_PATTERNS) {
+                if (re.test(line)) {
+                    hits.push({
+                        rule,
+                        file: path.relative(root, file),
+                        line: i + 1,
+                        excerpt: line.trim().slice(0, 200),
+                    });
+                    break;
+                }
+            }
+        });
+    }
+    return { hits, filesScanned: targets.length };
+}
+/** This project's own artifacts — excluded from its own baseline by default. */
+export const SELF_PROJECT_DIR = '1252-prompt-architecture-single-own';
+export const SELF_FILE_PREFIXES = ['spir-1252_', '1252-'];
+/** Collect all behavioural metrics for a repo root. Deterministic over B1–B4. */
+export function measureBehavior(root, opts = {}) {
+    const rv = collectReviewMetrics(root, opts.excludeProjects ?? [SELF_PROJECT_DIR], opts.includeProjects);
+    const scar = collectScarHits(root, opts.excludeFilePrefixes ?? SELF_FILE_PREFIXES);
+    return {
+        b1_requestChangesRate: round2(rv.rcRate * 100),
+        b1_verdictCounts: rv.verdictCounts,
+        b1_totalVerdicts: rv.total,
+        b2_roundsPerPhaseMean: round2(mean(rv.phaseRounds)),
+        b2_roundsPerPhaseMedian: median(rv.phaseRounds),
+        b2_roundsPerPhaseMax: rv.phaseRounds.length ? Math.max(...rv.phaseRounds) : 0,
+        b2_phaseCount: rv.phaseRounds.length,
+        b3_candidateHits: scar.hits,
+        b3_filesScanned: scar.filesScanned,
+        b4_roundsPerProjectMean: round2(mean(rv.projectRounds)),
+        b4_roundsPerProjectMedian: median(rv.projectRounds),
+        b4_projectCount: rv.projectRounds.length,
+        sampleProjects: rv.sampleProjects,
+    };
+}
+// ---------------------------------------------------------------------------
+// Rendering
+// ---------------------------------------------------------------------------
+/** Render metrics as the committed markdown baseline artifact. */
+export function render(m) {
+    const byRule = new Map();
+    for (const h of m.b3_candidateHits)
+        byRule.set(h.rule, (byRule.get(h.rule) ?? 0) + 1);
+    const lines = [
+        '# Behavioural metrics (Spec 1252, M12 / Appendix D)',
+        '',
+        '## B1 — CMAP verdict distribution',
+        '',
+        `Total verdicts: **${m.b1_totalVerdicts}** across ${m.b4_projectCount} projects with review history.`,
+        '',
+        '| Verdict | Count | Share |',
+        '|---|---:|---:|',
+        ...Object.entries(m.b1_verdictCounts)
+            .sort((a, b) => b[1] - a[1])
+            .map(([v, c]) => `| ${v} | ${c} | ${round2((c / Math.max(m.b1_totalVerdicts, 1)) * 100)}% |`),
+        '',
+        `**B1 REQUEST_CHANGES rate: ${m.b1_requestChangesRate}%** — the load-bearing metric.`,
+        '',
+        '## B2 — review rounds per plan phase',
+        '',
+        `mean **${m.b2_roundsPerPhaseMean}**, median ${m.b2_roundsPerPhaseMedian}, max ${m.b2_roundsPerPhaseMax} (n=${m.b2_phaseCount} phases)`,
+        '',
+        '> Advisory only. The observed range is too narrow to detect a subtle',
+        '> regression. Note also that phases advance on builder *rebuttal*, not on',
+        '> unanimous approval — 0 terminal phases in this corpus end with 3x APPROVE —',
+        '> so a "rounds to unanimity" metric would never resolve.',
+        '',
+        '## B4 — review rounds per project',
+        '',
+        `mean **${m.b4_roundsPerProjectMean}**, median ${m.b4_roundsPerProjectMedian} (n=${m.b4_projectCount} projects). Advisory.`,
+        '',
+        '## B3 — candidate scar-rule violations',
+        '',
+        `Scanned **${m.b3_filesScanned}** files (codev/reviews + codev/state threads).`,
+        `Candidate hits: **${m.b3_candidateHits.length}**`,
+        '',
+        '> **These are CANDIDATES, not findings.** Keyword mining cannot distinguish',
+        '> "we did this" from "never do this". Every hit requires human adjudication',
+        '> before the hard rollback trigger fires. B3 is the metric that matters most —',
+        '> it is the only one that would catch a compressed scar rule losing its force.',
+        '',
+    ];
+    if (byRule.size) {
+        lines.push('| Rule | Candidate hits |', '|---|---:|');
+        for (const [r, c] of [...byRule.entries()].sort((a, b) => b[1] - a[1])) {
+            lines.push(`| ${r} | ${c} |`);
+        }
+        lines.push('', '### Excerpts for adjudication', '');
+        for (const h of m.b3_candidateHits.slice(0, 50)) {
+            lines.push(`- \`${h.file}:${h.line}\` **[${h.rule}]** — ${h.excerpt}`);
+        }
+        if (m.b3_candidateHits.length > 50) {
+            lines.push(`- …and ${m.b3_candidateHits.length - 50} more (see --json for the full list)`);
+        }
+        lines.push('');
+    }
+    lines.push('## B5 — consult cost/duration', '', '**Not captured here.** `consult stats` is a rolling 30-day machine-local DB,', 'so it is not reproducible from a commit. Capture it separately as advisory', 'context; it is excluded from T14 determinism and drives no rollback trigger.', '', '## Sample provenance', '', ...m.sampleProjects.map((p) => `- ${p}`), '');
+    return lines.join('\n');
+}
+/** CLI entry, invoked by `packages/codev/scripts/measure-prompt-behavior.ts`. */
+export function runCli(argv, cwd) {
+    const json = argv.includes('--json');
+    const root = argv.find((a) => !a.startsWith('--')) ?? cwd;
+    const m = measureBehavior(path.resolve(root));
+    return json ? JSON.stringify(m, null, 2) : render(m);
+}
+//# sourceMappingURL=prompt-behavior-metrics.js.map

package/dist/lib/prompt-behavior-metrics.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"prompt-behavior-metrics.js","sourceRoot":"","sources":["../../src/lib/prompt-behavior-metrics.ts"],"names":[],"mappings":"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"}

package/dist/lib/protocol-drift-audit.d.ts

@@ -0,0 +1,118 @@
+/**
+ * Protocol-file drift audit (#1210).
+ *
+ * Detects two silent failure modes of the four-tier resolver
+ * (`.codev/` → `codev/` → cache → installed skeleton):
+ *
+ *  1. **Shadow drift** — a project-local copy (tier-1 `.codev/` or tier-2 `codev/`)
+ *     of a framework file that ALSO ships in the installed skeleton. The resolver
+ *     serves the local copy, so a stale snapshot of an old upstream default keeps
+ *     winning forever, silently, even after the package ships a fix. This audit
+ *     diffs each local copy against its skeleton counterpart and classifies it:
+ *       - `identical` → a redundant copy that adds nothing but risk (safe to remove;
+ *         resolution then falls back to the package).
+ *       - `differs`   → "customized or stale? — adjudicate" (a human must decide;
+ *         we NEVER auto-act).
+ *
+ *  2. **Skeleton staleness** — the installed `@cluesmith/codev` package is itself a
+ *     version behind npm `latest`, so even NON-shadowed resolution serves pre-fix
+ *     framework files. Reported as an explicit `installed X; latest Y` pair
+ *     (a computed "N behind" distance is not crisply testable), best-effort and
+ *     offline-tolerant.
+ *
+ * Report-only: this module performs NO writes to disk. Adjudication stays human —
+ * local copies may be deliberate customizations (that is the resolver's whole point).
+ *
+ * Mirrors the existing doctor audit precedents: `pr-gate-audit.ts` (#943) and
+ * `framework-ref-audit.ts` (#1011) — a pure lib returning findings + formatters,
+ * consumed by `commands/doctor.ts`.
+ */
+/**
+ * The framework subtrees whose files ship in the skeleton and resolve via the
+ * four-tier resolver. Pinned scan set (per the spec) — prompts and per-protocol
+ * templates live WITHIN `protocols/`, so they are covered transitively.
+ *
+ * Maintenance point: a new top-level framework subtree must be added here (same
+ * shape as `PR_PRODUCING_PROTOCOLS` in pr-gate-audit). `codev/resources/` is
+ * deliberately EXCLUDED — those are user-evolved files (arch.md, lessons-learned.md,
+ * and their -critical companions), not framework files, and must never be flagged.
+ */
+export declare const FRAMEWORK_DRIFT_DIRS: readonly ["protocols", "consult-types", "roles"];
+/** The two project-local override roots, in resolver-precedence order (tier 1 first). */
+declare const OVERRIDE_TIERS: readonly [".codev", "codev"];
+export type OverrideTier = (typeof OVERRIDE_TIERS)[number];
+export type DriftStatus = 'identical' | 'differs';
+export interface DriftFinding {
+    /** Path relative to the skeleton/override root, e.g. `protocols/spir/protocol.md`. */
+    relativePath: string;
+    /** Which local override root holds this copy. */
+    tier: OverrideTier;
+    /** Byte-comparison result against the skeleton counterpart. */
+    status: DriftStatus;
+    /**
+     * Whether the four-tier resolver actually resolves THIS copy (i.e. it is the
+     * live one the runtime loads). A tier-2 `codev/` copy shadowed by a tier-1
+     * `.codev/` copy is still reported (it is still rot), but marked not-the-winner.
+     */
+    isResolvedWinner: boolean;
+}
+export interface StalenessResult {
+    /** Installed `@cluesmith/codev` version. */
+    installed: string;
+    /** npm `latest`, or null when the registry could not be reached. */
+    latest: string | null;
+    /** True only when a latest version was obtained AND installed < latest. */
+    behind: boolean;
+    /** Human note when latest could not be determined. */
+    note?: string;
+}
+/** Injectable seam for the npm-latest lookup so tests are deterministic (no network). */
+export type FetchLatest = () => string | null;
+/**
+ * Audit a project for shadow drift against the installed skeleton.
+ *
+ * For every framework file in the skeleton (under FRAMEWORK_DRIFT_DIRS), checks
+ * whether a local copy exists in `.codev/` and/or `codev/`; for each local copy
+ * found, byte-compares it against the skeleton file and records a finding. Returns
+ * one finding per local copy (so a file present in BOTH tiers yields two findings).
+ *
+ * @param workspaceRoot - project root (auto-detected via findWorkspaceRoot if omitted)
+ */
+export declare function auditProtocolDrift(workspaceRoot?: string): DriftFinding[];
+/**
+ * Whether the project has ANY local copy of a scanned skeleton file, in EITHER
+ * override root. Cheap existence-only scan (no hashing) used for the no-op gate:
+ * the existing `hasLocalOverride()` only checks tier-2 `codev/`, so drift detection
+ * must check both tiers itself.
+ */
+export declare function hasFrameworkShadows(workspaceRoot?: string): boolean;
+/** Bound on the npm-latest lookup (ms). The registry can't stall doctor beyond this. */
+export declare const NPM_LATEST_TIMEOUT_MS = 2500;
+/**
+ * Default npm-latest lookup: `npm view @cluesmith/codev version`. Bounded by
+ * `NPM_LATEST_TIMEOUT_MS` (spawnSync kills the child past it) and offline-tolerant —
+ * an unreachable registry, non-zero exit, missing `npm`, or unparsable output all
+ * yield `null` rather than throwing or hanging. Exported so tests can assert the
+ * real bounded/offline behavior (not just an injected stub).
+ */
+export declare function fetchLatestVersion(): string | null;
+/**
+ * Compare the installed package version against npm `latest`. Never throws and
+ * never hangs beyond the fetch timeout — an unreachable registry yields
+ * `{ latest: null, behind: false, note }` so doctor stays usable offline.
+ *
+ * @param fetchLatest - injectable latest-version source (defaults to `npm view`)
+ */
+export declare function checkSkeletonStaleness(fetchLatest?: FetchLatest): StalenessResult;
+/**
+ * Render a shadow-drift finding for doctor output.
+ *
+ * @param skeletonVersion - installed skeleton/package version; when provided it is
+ *   named in the line so the human can tell WHICH skeleton the local copy diverged
+ *   from (the spec requires the adjudication warning to name the package version).
+ */
+export declare function formatDriftFinding(f: DriftFinding, skeletonVersion?: string): string;
+/** Render the staleness result for doctor output. */
+export declare function formatStaleness(s: StalenessResult): string;
+export {};
+//# sourceMappingURL=protocol-drift-audit.d.ts.map

package/dist/lib/protocol-drift-audit.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"protocol-drift-audit.d.ts","sourceRoot":"","sources":["../../src/lib/protocol-drift-audit.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;AASH;;;;;;;;;GASG;AACH,eAAO,MAAM,oBAAoB,kDAAmD,CAAC;AAKrF,yFAAyF;AACzF,QAAA,MAAM,cAAc,8BAA+B,CAAC;AACpD,MAAM,MAAM,YAAY,GAAG,CAAC,OAAO,cAAc,CAAC,CAAC,MAAM,CAAC,CAAC;AAE3D,MAAM,MAAM,WAAW,GAAG,WAAW,GAAG,SAAS,CAAC;AAElD,MAAM,WAAW,YAAY;IAC3B,sFAAsF;IACtF,YAAY,EAAE,MAAM,CAAC;IACrB,iDAAiD;IACjD,IAAI,EAAE,YAAY,CAAC;IACnB,+DAA+D;IAC/D,MAAM,EAAE,WAAW,CAAC;IACpB;;;;OAIG;IACH,gBAAgB,EAAE,OAAO,CAAC;CAC3B;AAED,MAAM,WAAW,eAAe;IAC9B,4CAA4C;IAC5C,SAAS,EAAE,MAAM,CAAC;IAClB,oEAAoE;IACpE,MAAM,EAAE,MAAM,GAAG,IAAI,CAAC;IACtB,2EAA2E;IAC3E,MAAM,EAAE,OAAO,CAAC;IAChB,sDAAsD;IACtD,IAAI,CAAC,EAAE,MAAM,CAAC;CACf;AAED,yFAAyF;AACzF,MAAM,MAAM,WAAW,GAAG,MAAM,MAAM,GAAG,IAAI,CAAC;AAkB9C;;;;;;;;;GASG;AACH,wBAAgB,kBAAkB,CAAC,aAAa,CAAC,EAAE,MAAM,GAAG,YAAY,EAAE,CAoCzE;AAED;;;;;GAKG;AACH,wBAAgB,mBAAmB,CAAC,aAAa,CAAC,EAAE,MAAM,GAAG,OAAO,CAUnE;AAoBD,wFAAwF;AACxF,eAAO,MAAM,qBAAqB,OAAO,CAAC;AAE1C;;;;;;GAMG;AACH,wBAAgB,kBAAkB,IAAI,MAAM,GAAG,IAAI,CAelD;AAED;;;;;;GAMG;AACH,wBAAgB,sBAAsB,CACpC,WAAW,GAAE,WAAgC,GAC5C,eAAe,CAYjB;AAED;;;;;;GAMG;AACH,wBAAgB,kBAAkB,CAAC,CAAC,EAAE,YAAY,EAAE,eAAe,CAAC,EAAE,MAAM,GAAG,MAAM,CAQpF;AAED,qDAAqD;AACrD,wBAAgB,eAAe,CAAC,CAAC,EAAE,eAAe,GAAG,MAAM,CAQ1D"}

package/dist/lib/protocol-drift-audit.js

@@ -0,0 +1,217 @@
+/**
+ * Protocol-file drift audit (#1210).
+ *
+ * Detects two silent failure modes of the four-tier resolver
+ * (`.codev/` → `codev/` → cache → installed skeleton):
+ *
+ *  1. **Shadow drift** — a project-local copy (tier-1 `.codev/` or tier-2 `codev/`)
+ *     of a framework file that ALSO ships in the installed skeleton. The resolver
+ *     serves the local copy, so a stale snapshot of an old upstream default keeps
+ *     winning forever, silently, even after the package ships a fix. This audit
+ *     diffs each local copy against its skeleton counterpart and classifies it:
+ *       - `identical` → a redundant copy that adds nothing but risk (safe to remove;
+ *         resolution then falls back to the package).
+ *       - `differs`   → "customized or stale? — adjudicate" (a human must decide;
+ *         we NEVER auto-act).
+ *
+ *  2. **Skeleton staleness** — the installed `@cluesmith/codev` package is itself a
+ *     version behind npm `latest`, so even NON-shadowed resolution serves pre-fix
+ *     framework files. Reported as an explicit `installed X; latest Y` pair
+ *     (a computed "N behind" distance is not crisply testable), best-effort and
+ *     offline-tolerant.
+ *
+ * Report-only: this module performs NO writes to disk. Adjudication stays human —
+ * local copies may be deliberate customizations (that is the resolver's whole point).
+ *
+ * Mirrors the existing doctor audit precedents: `pr-gate-audit.ts` (#943) and
+ * `framework-ref-audit.ts` (#1011) — a pure lib returning findings + formatters,
+ * consumed by `commands/doctor.ts`.
+ */
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+import { createHash } from 'node:crypto';
+import { spawnSync } from 'node:child_process';
+import { getSkeletonDir, listSkeletonFiles, resolveCodevFile, findWorkspaceRoot } from './skeleton.js';
+import { version as installedVersion } from '../version.js';
+/**
+ * The framework subtrees whose files ship in the skeleton and resolve via the
+ * four-tier resolver. Pinned scan set (per the spec) — prompts and per-protocol
+ * templates live WITHIN `protocols/`, so they are covered transitively.
+ *
+ * Maintenance point: a new top-level framework subtree must be added here (same
+ * shape as `PR_PRODUCING_PROTOCOLS` in pr-gate-audit). `codev/resources/` is
+ * deliberately EXCLUDED — those are user-evolved files (arch.md, lessons-learned.md,
+ * and their -critical companions), not framework files, and must never be flagged.
+ */
+export const FRAMEWORK_DRIFT_DIRS = ['protocols', 'consult-types', 'roles'];
+/** Only these extensions are framework files worth diffing. */
+const FRAMEWORK_EXTS = new Set(['.md', '.json']);
+/** The two project-local override roots, in resolver-precedence order (tier 1 first). */
+const OVERRIDE_TIERS = ['.codev', 'codev'];
+/** SHA-256 of a file's raw bytes (no text decoding — EOL/trailing-newline sensitive). */
+function hashBytes(filePath) {
+    return createHash('sha256').update(fs.readFileSync(filePath)).digest('hex');
+}
+/**
+ * Skeleton-relative framework files under a scan-set subtree, filtered to
+ * framework extensions. Enumerated via the resolver's own `listSkeletonFiles`
+ * (over `getSkeletonDir()`) so this audit and runtime resolution agree on exactly
+ * what the skeleton is. Returned paths (e.g. `protocols/spir/protocol.md`) are
+ * both the skeleton-relative and the override-relative path.
+ */
+function skeletonFrameworkFiles(sub) {
+    return listSkeletonFiles(sub).filter((rel) => FRAMEWORK_EXTS.has(path.extname(rel)));
+}
+/**
+ * Audit a project for shadow drift against the installed skeleton.
+ *
+ * For every framework file in the skeleton (under FRAMEWORK_DRIFT_DIRS), checks
+ * whether a local copy exists in `.codev/` and/or `codev/`; for each local copy
+ * found, byte-compares it against the skeleton file and records a finding. Returns
+ * one finding per local copy (so a file present in BOTH tiers yields two findings).
+ *
+ * @param workspaceRoot - project root (auto-detected via findWorkspaceRoot if omitted)
+ */
+export function auditProtocolDrift(workspaceRoot) {
+    const root = workspaceRoot ?? findWorkspaceRoot();
+    const skeletonDir = getSkeletonDir();
+    const findings = [];
+    for (const sub of FRAMEWORK_DRIFT_DIRS) {
+        for (const rel of skeletonFrameworkFiles(sub)) {
+            const skeletonPath = path.join(skeletonDir, rel);
+            let skeletonHash;
+            try {
+                skeletonHash = hashBytes(skeletonPath);
+            }
+            catch {
+                continue; // unreadable skeleton file — nothing to diff against
+            }
+            // Which copy does the resolver actually pick? (absolute path or null)
+            const resolved = resolveCodevFile(rel, root);
+            const resolvedAbs = resolved ? path.resolve(resolved) : null;
+            for (const tier of OVERRIDE_TIERS) {
+                const localPath = path.join(root, tier, rel);
+                if (!fs.existsSync(localPath) || !fs.statSync(localPath).isFile())
+                    continue;
+                const status = hashBytes(localPath) === skeletonHash ? 'identical' : 'differs';
+                findings.push({
+                    relativePath: rel,
+                    tier,
+                    status,
+                    isResolvedWinner: resolvedAbs === path.resolve(localPath),
+                });
+            }
+        }
+    }
+    return findings;
+}
+/**
+ * Whether the project has ANY local copy of a scanned skeleton file, in EITHER
+ * override root. Cheap existence-only scan (no hashing) used for the no-op gate:
+ * the existing `hasLocalOverride()` only checks tier-2 `codev/`, so drift detection
+ * must check both tiers itself.
+ */
+export function hasFrameworkShadows(workspaceRoot) {
+    const root = workspaceRoot ?? findWorkspaceRoot();
+    for (const sub of FRAMEWORK_DRIFT_DIRS) {
+        for (const rel of skeletonFrameworkFiles(sub)) {
+            for (const tier of OVERRIDE_TIERS) {
+                if (fs.existsSync(path.join(root, tier, rel)))
+                    return true;
+            }
+        }
+    }
+    return false;
+}
+/** Parse a dotted version into numeric parts; non-numeric segments → 0. */
+function parseVersion(v) {
+    return v.split('.').map((p) => parseInt(p.replace(/[^0-9]/g, ''), 10) || 0);
+}
+/** True if `a` is strictly older than `b` (semver-ish, major.minor.patch). */
+function versionLt(a, b) {
+    const pa = parseVersion(a);
+    const pb = parseVersion(b);
+    for (let i = 0; i < Math.max(pa.length, pb.length); i++) {
+        const x = pa[i] || 0;
+        const y = pb[i] || 0;
+        if (x < y)
+            return true;
+        if (x > y)
+            return false;
+    }
+    return false;
+}
+/** Bound on the npm-latest lookup (ms). The registry can't stall doctor beyond this. */
+export const NPM_LATEST_TIMEOUT_MS = 2500;
+/**
+ * Default npm-latest lookup: `npm view @cluesmith/codev version`. Bounded by
+ * `NPM_LATEST_TIMEOUT_MS` (spawnSync kills the child past it) and offline-tolerant —
+ * an unreachable registry, non-zero exit, missing `npm`, or unparsable output all
+ * yield `null` rather than throwing or hanging. Exported so tests can assert the
+ * real bounded/offline behavior (not just an injected stub).
+ */
+export function fetchLatestVersion() {
+    try {
+        const r = spawnSync('npm', ['view', '@cluesmith/codev', 'version'], {
+            encoding: 'utf-8',
+            timeout: NPM_LATEST_TIMEOUT_MS,
+            stdio: 'pipe',
+        });
+        if (r.status === 0 && r.stdout) {
+            const v = r.stdout.trim();
+            return /^\d+\.\d+\.\d+/.test(v) ? v : null;
+        }
+        return null;
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Compare the installed package version against npm `latest`. Never throws and
+ * never hangs beyond the fetch timeout — an unreachable registry yields
+ * `{ latest: null, behind: false, note }` so doctor stays usable offline.
+ *
+ * @param fetchLatest - injectable latest-version source (defaults to `npm view`)
+ */
+export function checkSkeletonStaleness(fetchLatest = fetchLatestVersion) {
+    const installed = installedVersion;
+    let latest = null;
+    try {
+        latest = fetchLatest();
+    }
+    catch {
+        latest = null;
+    }
+    if (!latest) {
+        return { installed, latest: null, behind: false, note: 'could not check (offline?)' };
+    }
+    return { installed, latest, behind: versionLt(installed, latest) };
+}
+/**
+ * Render a shadow-drift finding for doctor output.
+ *
+ * @param skeletonVersion - installed skeleton/package version; when provided it is
+ *   named in the line so the human can tell WHICH skeleton the local copy diverged
+ *   from (the spec requires the adjudication warning to name the package version).
+ */
+export function formatDriftFinding(f, skeletonVersion) {
+    const loc = `${f.tier}/${f.relativePath}`;
+    const ver = skeletonVersion ? ` v${skeletonVersion}` : '';
+    if (f.status === 'identical') {
+        return `${loc} — byte-identical redundant copy of the installed skeleton${ver}; safe to remove (resolution then falls back to the package)`;
+    }
+    const winner = f.isResolvedWinner ? ' [resolved — this copy is live]' : '';
+    return `${loc} — differs from installed skeleton${ver}; customized or stale? — adjudicate${winner}`;
+}
+/** Render the staleness result for doctor output. */
+export function formatStaleness(s) {
+    if (s.latest === null) {
+        return `installed ${s.installed}; latest: ${s.note ?? 'unknown'}`;
+    }
+    if (s.behind) {
+        return `installed ${s.installed}; latest ${s.latest} — behind (run: codev update)`;
+    }
+    return `installed ${s.installed}; latest ${s.latest} (up to date)`;
+}
+//# sourceMappingURL=protocol-drift-audit.js.map

package/dist/lib/protocol-drift-audit.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"protocol-drift-audit.js","sourceRoot":"","sources":["../../src/lib/protocol-drift-audit.ts"],"names":[],"mappings":"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"}