@cluesmith/codev 3.2.3 → 3.2.4

package/dist/lib/migration-backup-audit.d.ts

@@ -0,0 +1,64 @@
+/**
+ * Migration-backup audit for `codev doctor` (issue #1239).
+ *
+ * State migrations leave copies of the pre-migration state behind and nothing
+ * ever removes them. A disk audit on 2026-07-25 found an 18 GB
+ * `~/.agent-farm.bak-*` directory still on disk three weeks after the migration
+ * that created it — a full copy of the agent-farm dir, dominated by the logs it
+ * duplicated.
+ *
+ * Two leftover families exist:
+ *
+ *  1. `~/{.,}agent-farm*bak*` — whole-directory copies of the agent-farm home,
+ *     taken by hand during the #1118 state consolidation. These are the big
+ *     ones (they include `logs/`).
+ *  2. `*.pre-merge-<timestamp>` — the source `state.db` (plus `-wal`/`-shm`
+ *     sidecars) that `db/consolidate.ts` renames rather than deletes after
+ *     merging it into `global.db`. Small, but equally unreaped.
+ *
+ * This module reports; it never deletes. These are multi-gigabyte copies of the
+ * user's own state, and the decision to remove them is the human's. Doctor
+ * prints age + size + the exact `rm -rf` command so that decision is one
+ * paste away.
+ */
+/**
+ * A leftover is only worth nagging about once the migration that produced it
+ * has demonstrably held up. Below this age it is reported informationally;
+ * at or above it, doctor counts it as a warning.
+ */
+export declare const STALE_BACKUP_AGE_DAYS = 7;
+export type MigrationBackupKind = 'home-copy' | 'pre-merge';
+export interface MigrationBackup {
+    /** Absolute path to the leftover file or directory. */
+    path: string;
+    kind: MigrationBackupKind;
+    /** Whole days since last modification. */
+    ageDays: number;
+    /** Size on disk in bytes, or null when it could not be measured. */
+    sizeBytes: number | null;
+    /** True once `ageDays >= STALE_BACKUP_AGE_DAYS`. */
+    stale: boolean;
+}
+/** Human-readable byte size, e.g. `18.0 GB`. */
+export declare function formatBytes(bytes: number): string;
+export interface FindMigrationBackupsOptions {
+    /** Home directory to scan. Defaults to the real home; overridable for tests. */
+    home?: string;
+    /** Workspace root whose `.agent-farm/` is scanned for `*.pre-merge-*`. */
+    workspaceRoot?: string | null;
+    /** Reference time for age computation. Defaults to now. */
+    now?: Date;
+}
+/**
+ * Find every migration leftover on disk, newest first.
+ *
+ * Scans the home directory for whole-directory copies, and both the agent-farm
+ * home (`~/.agent-farm/`) and the workspace's `.agent-farm/` for `*.pre-merge-*`
+ * renames. Read-only; safe to call unconditionally.
+ */
+export declare function findMigrationBackups(options?: FindMigrationBackupsOptions): MigrationBackup[];
+/** One-line doctor rendering: path, age, size. */
+export declare function formatMigrationBackup(backup: MigrationBackup): string;
+/** Total measured bytes across a set of leftovers (unmeasurable ones count 0). */
+export declare function totalBytes(backups: MigrationBackup[]): number;
+//# sourceMappingURL=migration-backup-audit.d.ts.map

package/dist/lib/migration-backup-audit.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"migration-backup-audit.d.ts","sourceRoot":"","sources":["../../src/lib/migration-backup-audit.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;GAsBG;AAOH;;;;GAIG;AACH,eAAO,MAAM,qBAAqB,IAAI,CAAC;AAEvC,MAAM,MAAM,mBAAmB,GAAG,WAAW,GAAG,WAAW,CAAC;AAE5D,MAAM,WAAW,eAAe;IAC9B,uDAAuD;IACvD,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,mBAAmB,CAAC;IAC1B,0CAA0C;IAC1C,OAAO,EAAE,MAAM,CAAC;IAChB,oEAAoE;IACpE,SAAS,EAAE,MAAM,GAAG,IAAI,CAAC;IACzB,oDAAoD;IACpD,KAAK,EAAE,OAAO,CAAC;CAChB;AAoCD,gDAAgD;AAChD,wBAAgB,WAAW,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,CASjD;AA+CD,MAAM,WAAW,2BAA2B;IAC1C,gFAAgF;IAChF,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,0EAA0E;IAC1E,aAAa,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IAC9B,2DAA2D;IAC3D,GAAG,CAAC,EAAE,IAAI,CAAC;CACZ;AAED;;;;;;GAMG;AACH,wBAAgB,oBAAoB,CAClC,OAAO,GAAE,2BAAgC,GACxC,eAAe,EAAE,CAgBnB;AAED,kDAAkD;AAClD,wBAAgB,qBAAqB,CAAC,MAAM,EAAE,eAAe,GAAG,MAAM,CAIrE;AAED,kFAAkF;AAClF,wBAAgB,UAAU,CAAC,OAAO,EAAE,eAAe,EAAE,GAAG,MAAM,CAE7D"}

package/dist/lib/migration-backup-audit.js

@@ -0,0 +1,145 @@
+/**
+ * Migration-backup audit for `codev doctor` (issue #1239).
+ *
+ * State migrations leave copies of the pre-migration state behind and nothing
+ * ever removes them. A disk audit on 2026-07-25 found an 18 GB
+ * `~/.agent-farm.bak-*` directory still on disk three weeks after the migration
+ * that created it — a full copy of the agent-farm dir, dominated by the logs it
+ * duplicated.
+ *
+ * Two leftover families exist:
+ *
+ *  1. `~/{.,}agent-farm*bak*` — whole-directory copies of the agent-farm home,
+ *     taken by hand during the #1118 state consolidation. These are the big
+ *     ones (they include `logs/`).
+ *  2. `*.pre-merge-<timestamp>` — the source `state.db` (plus `-wal`/`-shm`
+ *     sidecars) that `db/consolidate.ts` renames rather than deletes after
+ *     merging it into `global.db`. Small, but equally unreaped.
+ *
+ * This module reports; it never deletes. These are multi-gigabyte copies of the
+ * user's own state, and the decision to remove them is the human's. Doctor
+ * prints age + size + the exact `rm -rf` command so that decision is one
+ * paste away.
+ */
+import { readdirSync, lstatSync, existsSync } from 'node:fs';
+import { homedir } from 'node:os';
+import { join } from 'node:path';
+import { spawnSync } from 'node:child_process';
+/**
+ * A leftover is only worth nagging about once the migration that produced it
+ * has demonstrably held up. Below this age it is reported informationally;
+ * at or above it, doctor counts it as a warning.
+ */
+export const STALE_BACKUP_AGE_DAYS = 7;
+/**
+ * Matches a hand-taken whole-directory copy of the agent-farm home.
+ *
+ * Requires BOTH an `agent-farm` prefix (so an unrelated `my-backups/` is never
+ * touched) and a backup marker. The marker spelling has varied across the
+ * migrations that produced these — `.agent-farm.bak-<ts>` and
+ * `agent-farm-db-backup-<ts>` are both real — so match `bak` and `back` alike.
+ * The live `.agent-farm` itself has no separator after the prefix and is never
+ * matched.
+ */
+function isHomeCopy(name) {
+    return /^\.?agent-farm[.-]/i.test(name) && /bac?k/i.test(name);
+}
+/** Matches the `*.pre-merge-<timestamp>` renames left by db/consolidate.ts. */
+function isPreMerge(name) {
+    return name.includes('.pre-merge-');
+}
+/**
+ * Measure a path's size on disk with `du -sk`.
+ *
+ * A recursive Node walk would stat tens of thousands of log files on exactly
+ * the multi-GB directories this audit exists to find, so shell out instead.
+ * Returns null (reported as "size unknown") when `du` is unavailable or times
+ * out — never a guessed number.
+ */
+function measureBytes(path) {
+    const result = spawnSync('du', ['-sk', path], { encoding: 'utf-8', timeout: 20000 });
+    if (result.status !== 0 || !result.stdout)
+        return null;
+    const kb = parseInt(result.stdout.trim().split(/\s+/)[0], 10);
+    return Number.isFinite(kb) ? kb * 1024 : null;
+}
+/** Human-readable byte size, e.g. `18.0 GB`. */
+export function formatBytes(bytes) {
+    const units = ['B', 'KB', 'MB', 'GB', 'TB'];
+    let value = bytes;
+    let unit = 0;
+    while (value >= 1024 && unit < units.length - 1) {
+        value /= 1024;
+        unit++;
+    }
+    return unit === 0 ? `${value} B` : `${value.toFixed(1)} ${units[unit]}`;
+}
+function inspect(path, kind, now) {
+    let stat;
+    try {
+        stat = lstatSync(path);
+    }
+    catch {
+        // Vanished between readdir and lstat — nothing to report.
+        return null;
+    }
+    const ageDays = Math.floor((now - stat.mtimeMs) / 86_400_000);
+    return {
+        path,
+        kind,
+        ageDays,
+        sizeBytes: measureBytes(path),
+        stale: ageDays >= STALE_BACKUP_AGE_DAYS,
+    };
+}
+function scanDir(dir, match, kind, now) {
+    if (!existsSync(dir))
+        return [];
+    let names;
+    try {
+        names = readdirSync(dir);
+    }
+    catch {
+        // Unreadable directory (permissions) — not something doctor should fail on.
+        return [];
+    }
+    const found = [];
+    for (const name of names) {
+        if (!match(name))
+            continue;
+        const entry = inspect(join(dir, name), kind, now);
+        if (entry)
+            found.push(entry);
+    }
+    return found;
+}
+/**
+ * Find every migration leftover on disk, newest first.
+ *
+ * Scans the home directory for whole-directory copies, and both the agent-farm
+ * home (`~/.agent-farm/`) and the workspace's `.agent-farm/` for `*.pre-merge-*`
+ * renames. Read-only; safe to call unconditionally.
+ */
+export function findMigrationBackups(options = {}) {
+    const home = options.home ?? homedir();
+    const now = (options.now ?? new Date()).getTime();
+    const backups = [
+        ...scanDir(home, isHomeCopy, 'home-copy', now),
+        ...scanDir(join(home, '.agent-farm'), isPreMerge, 'pre-merge', now),
+    ];
+    if (options.workspaceRoot) {
+        backups.push(...scanDir(join(options.workspaceRoot, '.agent-farm'), isPreMerge, 'pre-merge', now));
+    }
+    return backups.sort((a, b) => a.ageDays - b.ageDays);
+}
+/** One-line doctor rendering: path, age, size. */
+export function formatMigrationBackup(backup) {
+    const age = backup.ageDays === 1 ? '1 day old' : `${backup.ageDays} days old`;
+    const size = backup.sizeBytes === null ? 'size unknown' : formatBytes(backup.sizeBytes);
+    return `${backup.path} — ${age}, ${size}`;
+}
+/** Total measured bytes across a set of leftovers (unmeasurable ones count 0). */
+export function totalBytes(backups) {
+    return backups.reduce((sum, b) => sum + (b.sizeBytes ?? 0), 0);
+}
+//# sourceMappingURL=migration-backup-audit.js.map

package/dist/lib/migration-backup-audit.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"migration-backup-audit.js","sourceRoot":"","sources":["../../src/lib/migration-backup-audit.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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"}

package/dist/lib/scaffold.d.ts

@@ -107,13 +107,20 @@ interface CopySkillsOptions {
     skipExisting?: boolean;
 }
 interface CopySkillsResult {
+    /** Project-relative provider-qualified paths, including a trailing slash. */
     copied: string[];
+    /** Project-relative provider-qualified paths, including a trailing slash. */
     skipped: string[];
-    directoryCreated: boolean;
+    /** Project-relative provider skill roots that were created. */
+    directoriesCreated: string[];
 }
+export declare const SKILL_PROVIDERS: readonly ["claude", "codex"];
 /**
- * Copy .claude/skills/ from skeleton to project root.
- * Skills are Claude Code slash commands that provide contextual guidance.
+ * Copy provider-native skill trees from the skeleton to the project root.
+ *
+ * Each skill directory is the preservation boundary: skipExisting leaves an
+ * existing skill completely untouched while still backfilling missing skills
+ * for either provider.
  */
 export declare function copySkills(targetDir: string, skeletonDir: string, options?: CopySkillsOptions): CopySkillsResult;
 interface CopyRolesOptions {

package/dist/lib/scaffold.d.ts.map

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