fraim 2.0.346 → 2.0.349

package/dist/src/local-mcp-server/learning-usage-command.js

@@ -1,518 +0,0 @@
-"use strict";
-var __importDefault = (this && this.__importDefault) || function (mod) {
-    return (mod && mod.__esModule) ? mod : { "default": mod };
-};
-Object.defineProperty(exports, "__esModule", { value: true });
-exports.learningUsageCommand = void 0;
-/**
- * Issue #1103 - command surface used by the learning-usage script.
- *
- * The read and analysis side of the usage record. The write side of an offer is the
- * proxy (no agent involvement, R2); the write side of a firing is an attestation in
- * a retrospective, which `record-firings` reads back.
- */
-const commander_1 = require("commander");
-const node_fs_1 = __importDefault(require("node:fs"));
-const node_path_1 = __importDefault(require("node:path"));
-const learning_context_builder_1 = require("./learning-context-builder");
-const learning_usage_analysis_1 = require("./learning-usage-analysis");
-const learning_usage_store_1 = require("./learning-usage-store");
-const learning_usage_attestation_1 = require("./learning-usage-attestation");
-const learning_usage_verify_1 = require("./learning-usage-verify");
-const pack_home_1 = require("../cli/utils/pack-home");
-/**
- * Preserve checkpointed history and distinguish backup recovery from attestation backfill.
- * Backfill supplements older firings; it cannot reconstruct missing offers.
- */
-const REBUILD_NOTE = "Keep `learning-usage.json`, its `.checkpoint` backup, `events/` and any conflict copies. After consolidation, the snapshot and checkpoint backup preserve lifetime counters and already-counted source markers; the remaining journal cannot rebuild that history. A missing or torn snapshot is read from its checkpoint backup automatically. Restore matching checkpoint and journal files from backup if both copies are damaged. Inspect split identities and conflict copies before repairing them; do not delete the snapshot to clear a warning. Separately, `learning-usage backfill` can recover older firings from retrospectives; raw learnings and retrospectives cannot restore runtime offers.";
-function resolveWorkspaceRoot(options) {
-    return node_path_1.default.resolve(options.workspaceRoot || options.root || process.cwd());
-}
-function resolveUser(options) {
-    const email = options.user || process.env.FRAIM_ACTIVE_USER_EMAIL || '';
-    if (!email.trim()) {
-        throw new Error('Missing active user email. Pass --user <email> or set FRAIM_ACTIVE_USER_EMAIL.');
-    }
-    return email.trim();
-}
-function emit(payload, json, text) {
-    process.stdout.write(json ? `${JSON.stringify(payload, null, 2)}\n` : `${text()}\n`);
-}
-function addCommonOptions(command) {
-    return command
-        .option('--workspace-root <path>', 'Workspace root containing fraim/config.json')
-        .option('--root <path>', 'Alias for --workspace-root')
-        .option('--user <email>', 'Active user email')
-        .option('--json', 'Print JSON');
-}
-/**
- * Issue #1752 C1: every command that draws a per-model conclusion takes the model
- * from its caller. It is never inferred from the record, because the record is
- * shared by concurrent sessions from more than one agent on more than one
- * machine, so inference reports whichever wrote last.
- */
-function addModelOption(command) {
-    return command.option('--model <model>', 'The model you are running under. Falls back to FRAIM_ACTIVE_MODEL, then reports unknown');
-}
-/**
- * Issue #1752 B: the offer and firing log bounds are applied when the event log is
- * folded, so a read states the bounds it wants rather than inheriting whatever the
- * last writer used.
- */
-function readStore(workspaceRoot) {
-    return (0, learning_usage_store_1.readUsageStore)(undefined, { limits: (0, learning_usage_store_1.resolveUsageLimits)(workspaceRoot) });
-}
-// ── offers ───────────────────────────────────────────────────────────────────
-const offersCommand = addCommonOptions(new commander_1.Command('offers'))
-    .description('List the learning entries and rule files the runtime delivered, so an attestation is written against the record rather than memory')
-    .option('--job <name>', 'The job whose context was loaded', 'unknown')
-    .option('--domain <domain>', 'Learning domain the job resolved to')
-    .option('--session', 'Use the session frame rather than the job frame')
-    .action((options) => {
-    const workspaceRoot = resolveWorkspaceRoot(options);
-    const user = resolveUser(options);
-    const forJob = !options.session;
-    // Prefer what the runtime recorded for this job, because that is what was
-    // actually delivered. Re-deriving from the files on disk answers a subtly
-    // different question — what would be delivered now — and the two diverge if a
-    // learning file changed during the job.
-    const store = readStore(workspaceRoot);
-    const recorded = Object.values(store.entries)
-        .filter((entry) => entry.offered.log.some((offer) => offer.job === options.job))
-        .map((entry) => {
-        const last = [...entry.offered.log].reverse().find((offer) => offer.job === options.job);
-        return {
-            key: entry.key,
-            family: entry.family,
-            id: entry.key.startsWith('L-') ? entry.key : null,
-            title: entry.titles[entry.titles.length - 1] ?? entry.key,
-            fileType: entry.fileType ?? 'unknown',
-            level: entry.level ?? 'unknown',
-            displayPath: '',
-            severity: null,
-            aboveThreshold: last.aboveThreshold,
-        };
-    });
-    const source = recorded.length > 0 ? 'offer-record' : 'derived';
-    const offered = recorded.length > 0
-        ? recorded
-        : [
-            ...(0, learning_context_builder_1.collectOfferedLearningEntries)(workspaceRoot, user, forJob, options.domain ?? null),
-            ...(0, learning_context_builder_1.collectOfferedRuleFiles)(workspaceRoot, forJob),
-        ];
-    const payload = { job: options.job, forJob, source, offered };
-    emit(payload, options.json, () => {
-        if (payload.offered.length === 0) {
-            return `No offer record and nothing resolves for job ${options.job}. Do not attest any firing for this job.`;
-        }
-        const rows = payload.offered.map((o) => `| ${o.id ?? '(no id)'} | ${o.title} | ${o.fileType} | ${o.aboveThreshold ? 'yes' : 'no'} |`);
-        const header = source === 'offer-record'
-            ? `Entries offered for job ${options.job}, from the offer record:`
-            : `No offer record exists for job ${options.job} yet, so this is what would be delivered now. Say so when you attest against it.`;
-        return [
-            header,
-            '',
-            '| Id | Title | Family | Above threshold |',
-            '|---|---|---|---|',
-            ...rows,
-        ].join('\n');
-    });
-});
-// ── record-firings ───────────────────────────────────────────────────────────
-const recordFiringsCommand = addCommonOptions(new commander_1.Command('record-firings'))
-    .description('Read the firing section of a retrospective and write the attested firings into the usage record')
-    .requiredOption('--retrospective <path>', 'Retrospective file to read')
-    .option('--job <name>', 'The job that produced the retrospective')
-    .option('--agent <name>', 'Agent that attested')
-    .option('--model <model>', 'Model that attested')
-    .option('--legacy', 'Also accept the pre-#1103 prose form')
-    .option('--force', 'Record the firings even when they violate the scoped integrity invariant, flagging the entry instead of refusing. Use when the offers are known to be stranded in an unmerged store copy or an unsynced machine log')
-    .action((options) => {
-    const workspaceRoot = resolveWorkspaceRoot(options);
-    const user = resolveUser(options);
-    const filePath = node_path_1.default.resolve(options.retrospective);
-    if (!node_fs_1.default.existsSync(filePath)) {
-        throw new Error(`Retrospective not found: ${filePath}`);
-    }
-    const { content, record } = (0, learning_usage_attestation_1.readRetrospectiveForAttestation)(workspaceRoot, user, filePath);
-    const source = record.usageIdentity;
-    const result = (0, learning_usage_attestation_1.recordAttestationsFromRetrospective)(workspaceRoot, user, {
-        content,
-        source,
-        job: record.job,
-        date: record.date,
-        agent: options.agent ?? null,
-        model: options.model ?? null,
-        legacy: Boolean(options.legacy),
-        integrityMode: options.force ? 'flag' : 'throw',
-    });
-    emit(result, options.json, () => {
-        const lines = [
-            `Section state: ${result.sectionState}`,
-            `Items read: ${result.itemsRead}`,
-            `Recorded: ${result.applied}`,
-            `Already recorded: ${result.alreadyRecorded}`,
-            `Unmatched: ${result.unmatched.length}`,
-            `Rejected: ${result.rejected.length}`,
-        ];
-        for (const item of result.unmatched)
-            lines.push(`  unmatched: ${item.title} — ${item.reason}`);
-        for (const item of result.rejected)
-            lines.push(`  rejected: ${item.reason}`);
-        return lines.join('\n');
-    });
-});
-// ── classify ─────────────────────────────────────────────────────────────────
-const classifyCommand = addCommonOptions(new commander_1.Command('classify'))
-    .description('Say whether a recurrence was ignored (the entry was in context) or not-offered (it never reached the agent), because the two need different fixes')
-    .option('--entry <id>', 'The entry id, for an entry that carries one')
-    .option('--title <title>', 'The exact entry title, for an entry with no id yet. Use with --family')
-    .option('--family <family>', 'The entry family: mistake-patterns, preferences, validated-patterns, or manager-coaching')
-    .requiredOption('--job <name>', 'The job the recurrence happened in')
-    .requiredOption('--date <YYYY-MM-DD>', 'The date the mistake recurred')
-    .option('--window <days>', 'How far back an offer still counts as in-context', '30')
-    .action((options) => {
-    const workspaceRoot = resolveWorkspaceRoot(options);
-    // `--title` plus `--family` exists so a caller never has to build the composite
-    // title key by hand. An entry title is corpus content and can contain any
-    // character, so an agent assembling `T:<family>:<title>` into a shell command
-    // would be interpolating untrusted text into a command line. Passing the title
-    // as its own argument keeps it a single argv entry.
-    if (!options.entry && !(options.title && options.family)) {
-        throw new Error('Pass --entry <id>, or --title <title> together with --family <family>.');
-    }
-    // #1752 A1: the same identity function the offer and firing paths use, so
-    // the CLI cannot ask about a key neither of them would have written.
-    const key = (0, learning_usage_store_1.resolveEntryIdentity)({
-        id: options.entry ? String(options.entry) : null,
-        fileType: options.family ? String(options.family) : null,
-        title: options.title ? String(options.title) : null,
-    }).key;
-    const store = readStore(workspaceRoot);
-    const diagnosis = (0, learning_usage_analysis_1.classifyRecurrence)(store, {
-        key,
-        job: options.job,
-        date: options.date,
-        windowDays: Number.parseInt(options.window, 10) || 30,
-    });
-    void workspaceRoot;
-    emit(diagnosis, options.json, () => [
-        `Classification: ${diagnosis.classification}`,
-        `Diagnosis: ${diagnosis.diagnosis}`,
-        `Recommendation: ${diagnosis.recommendation}`,
-        `Raise the recurrence count: ${diagnosis.recurrenceBump ? 'yes' : 'no'}`,
-    ].join('\n'));
-});
-// ── candidates ───────────────────────────────────────────────────────────────
-const candidatesCommand = addModelOption(addCommonOptions(new commander_1.Command('candidates')))
-    .description('List retirement candidates: offered often under the current model with no firing under it, paired with a structural signal')
-    .option('--detector <path>', 'Path to the corpus hygiene detector that provides the structural signal')
-    .action((options) => {
-    const workspaceRoot = resolveWorkspaceRoot(options);
-    const limits = (0, learning_usage_store_1.resolveUsageLimits)(workspaceRoot);
-    const result = (0, learning_usage_analysis_1.findRetirementCandidates)(readStore(workspaceRoot), {
-        workspaceRoot,
-        limits,
-        currentModel: options.model ?? undefined,
-        structuralSignalPath: options.detector,
-    });
-    emit(result, options.json, () => {
-        if (result.candidates.length === 0) {
-            const lines = [`No retirement candidates. Current model: ${result.currentModel ?? 'unknown'}; threshold ${result.offerThreshold} offers.`];
-            if (result.reason)
-                lines.push('', result.reason);
-            const unknownAttribution = result.notCandidates.filter((c) => /attribution is unknown/i.test(c.reason));
-            if (unknownAttribution.length > 0) {
-                lines.push('', `${unknownAttribution.length} entr${unknownAttribution.length === 1 ? 'y was' : 'ies were'} held back because their firings carry no model, so how hard they are working under this model cannot be measured.`);
-            }
-            return lines.join('\n');
-        }
-        const lines = [`Current model: ${result.currentModel ?? 'unknown'}. Threshold: ${result.offerThreshold} offers.`, ''];
-        for (const c of result.candidates) {
-            const earlier = c.firedUnderEarlierModels.map((m) => `${m.count} under ${m.model}`).join(', ') || 'none under any earlier model';
-            lines.push(`- ${c.title}`, `  Offered ${c.offeredUnderCurrentModel} times under the current model, fired ${c.firedUnderCurrentModel}. Earlier: ${earlier}.`, `  Structural signal: ${c.structural}. ${c.structuralDetail}`, `  Recommendation: ${c.recommendation}`);
-        }
-        return lines.join('\n');
-    });
-});
-// ── standing ─────────────────────────────────────────────────────────────────
-const standingCommand = addModelOption(addCommonOptions(new commander_1.Command('standing')))
-    .description('Assess each entry as promoted, standard or demoted from its usage record, and list the ones whose standing should change')
-    .option('--changes-only', 'Print only the entries whose standing should change')
-    .action((options) => {
-    const workspaceRoot = resolveWorkspaceRoot(options);
-    const limits = (0, learning_usage_store_1.resolveUsageLimits)(workspaceRoot);
-    const report = (0, learning_usage_analysis_1.assessStanding)(readStore(workspaceRoot), { limits });
-    const payload = options.changesOnly ? { ...report, assessments: report.changes } : report;
-    emit(payload, options.json, () => {
-        const rows = (options.changesOnly ? report.changes : report.assessments);
-        if (rows.length === 0) {
-            return options.changesOnly
-                ? 'No standing changes. Every measured entry is already where the record says it belongs.'
-                : 'No entry has a usage record yet, so there is nothing to assess.';
-        }
-        const lines = [];
-        if (report.changes.length > 0) {
-            lines.push(`${report.changes.length} entr${report.changes.length === 1 ? 'y' : 'ies'} should change standing.`, '');
-        }
-        for (const a of rows) {
-            lines.push(`- ${a.title}`);
-            lines.push(`  ${a.standing}${a.recommendation ? ` (recommend: ${a.recommendation})` : ''}. ${a.reason}`);
-        }
-        lines.push('', 'Nothing is applied here. Run sleep-on-learnings to decide.');
-        return lines.join('\n');
-    });
-});
-// ── report ───────────────────────────────────────────────────────────────────
-const reportCommand = addModelOption(addCommonOptions(new commander_1.Command('report')))
-    .description('Answer which learnings are still earning their place, from the record rather than from memory')
-    .option('--window <days>', 'Reporting window', '90')
-    .action((options) => {
-    const workspaceRoot = resolveWorkspaceRoot(options);
-    const limits = (0, learning_usage_store_1.resolveUsageLimits)(workspaceRoot);
-    const report = (0, learning_usage_analysis_1.buildUsageReport)(readStore(workspaceRoot), {
-        workspaceRoot,
-        limits,
-        windowDays: Number.parseInt(options.window, 10) || 90,
-        currentModel: options.model ?? undefined,
-    });
-    emit(report, options.json, () => {
-        const lines = [
-            report.totals.entriesOffered === null ? 'Corpus totals are unavailable; listed entries have independent usable evidence.'
-                : `${report.totals.entriesOffered} entries were offered. ${report.totals.entriesWithFirings} fired. ${report.totals.entriesNeverFired} have never fired.`,
-        ];
-        if (report.workingHardest.length) {
-            lines.push('', 'Working hardest');
-            report.workingHardest.forEach((e, i) => lines.push(`${i + 1}. ${e.title}. Offered ${e.offered} times, fired ${e.fired}. Last fired ${e.lastFired ?? 'never'}.`));
-        }
-        if (report.neverFired.length) {
-            lines.push('', 'Never fired');
-            report.neverFired.forEach((e, i) => lines.push(`${i + 1}. ${e.title}. Offered ${e.offered} times, never fired.`));
-        }
-        if (report.ignoredWhileInContext.length) {
-            lines.push('', 'Ignored while in context');
-            // #1752 defect 8: this section selects on the `ignored` count, so it
-            // prints that count. Printing only the clock-advancing one made the
-            // section contradict its own evidence column.
-            report.ignoredWhileInContext.forEach((e, i) => lines.push(`${i + 1}. ${e.title}. Attested ignored ${e.ignored} time${e.ignored === 1 ? '' : 's'} (fired ${e.fired}). In context and the work went against it, so the entry needs work rather than another recurrence.`));
-        }
-        if (report.integrityFlagged > 0) {
-            lines.push('', `${report.integrityFlagged} entries were excluded from usage conclusions. Run \`learning-usage verify\` for diagnostic details.`);
-        }
-        lines.push('', 'Nothing is retired from this view. Run sleep-on-learnings to decide.');
-        return lines.join('\n');
-    });
-});
-// ── backfill ─────────────────────────────────────────────────────────────────
-const backfillCommand = addCommonOptions(new commander_1.Command('backfill'))
-    .description('Read the firings already attested in existing retrospectives, matching only on an id or an exact title, and report what could not be matched')
-    .option('--agent <name>', 'Agent to attribute the backfilled records to', 'backfill')
-    .option('--model <model>', 'Model to attribute the backfilled records to')
-    .action((options) => {
-    const workspaceRoot = resolveWorkspaceRoot(options);
-    const user = resolveUser(options);
-    const report = (0, learning_usage_attestation_1.runBackfill)(workspaceRoot, user, {
-        agent: options.agent ?? 'backfill',
-        model: options.model ?? null,
-    });
-    emit(report, options.json, () => [
-        `Files scanned: ${report.filesScanned} (${report.filesWithSection} carry the section, ${report.synthesizedFilesRead} already synthesized)`,
-        `Items read: ${report.itemsRead}`,
-        `Applied: ${report.applied}`,
-        `Already recorded: ${report.alreadyRecorded}`,
-        `Unmatched: ${report.unmatched.length}`,
-        `Rejected: ${report.rejected.length}`,
-        '',
-        'Only an id or an exact title resolves. A low match rate is expected on retrospectives written before entries carried ids, and is reported rather than resolved by similarity matching.',
-    ].join('\n'));
-});
-/**
- * Add the `**Id**` line to entries that do not have one.
- *
- * This is a format migration, not a change to any lesson: it inserts one
- * identifier line per entry and touches nothing else. R19 forbids a new write path
- * into the corpus for usage data, and this is not one — it writes no usage data,
- * and it is run explicitly by the manager rather than by any automatic path.
- */
-function stampFile(filePath, fileType, apply) {
-    const content = node_fs_1.default.readFileSync(filePath, 'utf8');
-    const eol = content.includes('\r\n') ? '\r\n' : '\n';
-    const lines = content.split(/\r?\n/);
-    const headingRe = (0, learning_context_builder_1.learningEntryHeadingRegex)();
-    const idRe = (0, learning_context_builder_1.learningEntryIdLineRegex)();
-    const out = [];
-    let stamped = 0;
-    let alreadyStamped = 0;
-    for (let i = 0; i < lines.length; i++) {
-        const line = lines[i];
-        out.push(line);
-        const header = line.match(headingRe);
-        if (!header)
-            continue;
-        // Look ahead to the next entry heading for an existing id line.
-        let hasId = false;
-        for (let j = i + 1; j < lines.length; j++) {
-            if (headingRe.test(lines[j]))
-                break;
-            if (idRe.test(lines[j].trim())) {
-                hasId = true;
-                break;
-            }
-        }
-        if (hasId) {
-            alreadyStamped++;
-            continue;
-        }
-        const title = header[2].trim();
-        if (!title)
-            continue;
-        // Insert immediately after the heading, keeping the blank line that usually
-        // follows it so the file's shape is unchanged.
-        if (lines[i + 1] !== undefined && lines[i + 1].trim() === '') {
-            out.push('');
-            out.push(`**Id**: ${(0, learning_context_builder_1.generateLearningEntryId)(fileType, title)}`);
-            i++;
-        }
-        else {
-            out.push(`**Id**: ${(0, learning_context_builder_1.generateLearningEntryId)(fileType, title)}`);
-        }
-        stamped++;
-    }
-    if (apply && stamped > 0) {
-        node_fs_1.default.writeFileSync(filePath, out.join(eol), 'utf8');
-    }
-    return { file: filePath, entriesStamped: stamped, entriesAlreadyStamped: alreadyStamped };
-}
-const FILE_TYPES = ['mistake-patterns', 'preferences', 'validated-patterns', 'manager-coaching'];
-function defaultStampDirs(workspaceRoot) {
-    const dirs = [node_path_1.default.join(workspaceRoot, 'fraim', 'personalized-employee', 'learnings')];
-    for (const level of ['org', 'manager']) {
-        try {
-            dirs.push(node_path_1.default.join((0, pack_home_1.resolvePackHome)(level, { migrateLegacy: false }).contentRoot, 'learnings'));
-        }
-        catch {
-            // A pack home that does not resolve is simply not stamped. Reported by the
-            // filesScanned count rather than failing the command.
-        }
-    }
-    return [...new Set(dirs)];
-}
-function fileTypeFromName(fileName) {
-    for (const type of FILE_TYPES) {
-        if (fileName.includes(type))
-            return type;
-    }
-    return null;
-}
-const stampIdsCommand = addCommonOptions(new commander_1.Command('stamp-ids'))
-    .description('Add the stable Id line to learning entries that do not have one. A format migration: it inserts one identifier line per entry and changes no lesson text')
-    .option('--dir <path>', 'Learning directory to stamp (repeatable)', (value, previous) => [...previous, value], [])
-    .option('--apply', 'Write the changes. Without this flag the command reports what it would do')
-    .action((options) => {
-    const workspaceRoot = resolveWorkspaceRoot(options);
-    // #1752 A3: the default set is every tier the context reader merges, not
-    // the repo alone. `stamp-ids` never reaching the org and manager pack homes
-    // is half of defect 4: one lesson stamped in one tier and unstamped in the
-    // other resolved to two usage keys. Still opt-in behind --apply, and still a
-    // format migration that inserts one identifier line and touches no lesson text.
-    const dirs = options.dir.length
-        ? options.dir.map((d) => node_path_1.default.resolve(d))
-        : defaultStampDirs(workspaceRoot);
-    const results = [];
-    for (const dir of dirs) {
-        if (!node_fs_1.default.existsSync(dir))
-            continue;
-        for (const fileName of node_fs_1.default.readdirSync(dir)) {
-            if (!fileName.endsWith('.md'))
-                continue;
-            const fileType = fileTypeFromName(fileName);
-            if (!fileType)
-                continue;
-            results.push(stampFile(node_path_1.default.join(dir, fileName), fileType, Boolean(options.apply)));
-        }
-    }
-    const payload = {
-        apply: Boolean(options.apply),
-        filesScanned: results.length,
-        entriesStamped: results.reduce((sum, r) => sum + r.entriesStamped, 0),
-        entriesAlreadyStamped: results.reduce((sum, r) => sum + r.entriesAlreadyStamped, 0),
-        files: results,
-    };
-    emit(payload, options.json, () => [
-        `${payload.apply ? 'Stamped' : 'Would stamp'} ${payload.entriesStamped} entries across ${payload.filesScanned} files in ${dirs.length} director${dirs.length === 1 ? 'y' : 'ies'}:`,
-        ...dirs.map((d) => `  ${d}`),
-        `${payload.entriesAlreadyStamped} entries already carry an id.`,
-        payload.apply ? '' : 'Re-run with --apply to write the changes.',
-    ].filter(Boolean).join('\n'));
-});
-// ── prune ────────────────────────────────────────────────────────────────────
-const pruneCommand = addCommonOptions(new commander_1.Command('prune'))
-    .description('Apply the configured retention window and log bounds to the usage record. Aggregate counters are never pruned')
-    .action((options) => {
-    const workspaceRoot = resolveWorkspaceRoot(options);
-    const limits = (0, learning_usage_store_1.resolveUsageLimits)(workspaceRoot);
-    const result = (0, learning_usage_store_1.pruneUsageStore)(limits);
-    emit({ ...result, storePath: (0, learning_usage_store_1.resolveUsageStorePath)(), limits }, options.json, () => result.maintenanceStatus === 'deferred' ? `Maintenance deferred; history unchanged. ${result.evidence?.observations.join(', ') ?? ''}`
-        : `Pruned ${result.prunedOfferRecords} offer records and ${result.prunedFiringRecords} firing records across ${result.entries} entries. Aggregates unchanged.`);
-});
-function mb(bytes) {
-    return `${(bytes / (1024 * 1024)).toFixed(1)} MB`;
-}
-// ── verify ───────────────────────────────────────────────────────────────────
-const verifyCommand = addModelOption(addCommonOptions(new commander_1.Command('verify')))
-    .description('Report the integrity of the usage record in one output: split identities, impossible counters, split model buckets, unmerged store copies, and how far each snapshot checkpoint is behind its log')
-    .action((options) => {
-    const workspaceRoot = resolveWorkspaceRoot(options);
-    const report = (0, learning_usage_verify_1.buildVerifyReport)({
-        snapshotPath: (0, learning_usage_store_1.resolveUsageStorePath)(),
-        limits: (0, learning_usage_store_1.resolveUsageLimits)(workspaceRoot),
-        currentModel: options.model ?? undefined,
-    });
-    emit(report, options.json, () => {
-        const lines = [
-            `Usage record: ${report.entries} entries at ${report.snapshotPath}`,
-            `Current model: ${report.currentModel ?? 'unknown'}`,
-            '',
-        ];
-        const finding = (count, singular, plural, remedy) => count === 0 ? `  none: ${singular}` : `  ${count} ${count === 1 ? singular : plural}. ${remedy}`;
-        if (report.evidence)
-            lines.push(`Evidence: ${report.evidence.status}. ${report.evidence.observations.join(', ')}.`, ...(report.evidence.recovery ? [`Recovered from ${report.evidence.recovery}; primary replacement was not persisted by this read.`] : []), '');
-        lines.push('Identity', finding(report.twinPairs.length, 'lesson tracked under two keys', 'lessons tracked under two keys', 'Its offers and its firings are on different records, so every count about it is partial.'), report.unmatchedTitleKeys.length
-            ? `  ${report.unmatchedTitleKeys.length} title-keyed record${report.unmatchedTitleKeys.length === 1 ? ' has' : 's have'} no id twin. Expected for entries no tier has stamped; run \`stamp-ids\` to reduce it.`
-            : '  every title-keyed record has been matched or has no twin', '', 'Counters', finding(report.invariantViolations.length, 'entry holds more attested firings than recorded offers', 'entries hold more attested firings than recorded offers', 'The counts are inconsistent. This observation does not establish their cause.'), finding(report.caseVariantModelBuckets.length, 'model bucket differs only by case', 'model buckets differ only by case', 'One model spelled two ways splits its own denominator, so every per-model conclusion about it is computed on a fraction of its traffic.'), finding(report.unknownModelAttribution.length, 'entry has incomplete model attribution', 'entries have incomplete model attribution', 'Affected model conclusions are withheld. The cause is not established; unknown historical attribution cannot be inferred from the current model.'), '', 'Storage');
-        if (report.storeCopies.length === 0) {
-            lines.push('  one store file, no unmerged copies');
-        }
-        else {
-            lines.push(`  ${report.storeCopies.length} unmerged store cop${report.storeCopies.length === 1 ? 'y' : 'ies'} beside the canonical snapshot:`);
-            for (const copy of report.storeCopies) {
-                lines.push(`    ${copy.path}: ${copy.readable ? `${copy.entries} entries, ${copy.offers} offers, ${copy.firings} firings` : `unreadable (${copy.error ?? 'unknown error'})`}`);
-            }
-            lines.push('    Nothing reads these. Preserve them and the checkpoint backup for inspection; do not delete snapshots to clear this warning.');
-        }
-        lines.push(`  event logs folded: ${report.eventLogs.length === 0 ? 'none' : report.eventLogs.map((l) => `${l.machineId} (${l.bytes} bytes)`).join(', ')}`);
-        for (const [machineId, lag] of Object.entries(report.checkpointLag)) {
-            lines.push(`  checkpoint lag for ${machineId}: ${lag} bytes${lag > 0 ? ' behind the log head' : ''}`);
-        }
-        lines.push(report.compactionAdvised
-            ? `  log size ${mb(report.totalLogBytes)} is past the ${mb(report.compactionAdvisoryBytes)} point where a cold fold stops fitting the context-injection budget. Run \`learning-usage prune\` to consolidate processed events into the snapshot and checkpoint backup, then clear them independently of retention.`
-            : `  log size ${mb(report.totalLogBytes)} of ${mb(report.compactionAdvisoryBytes)} before compaction is worth running.`);
-        if (report.rebuildAdvised)
-            lines.push('', REBUILD_NOTE);
-        lines.push('', 'Nothing here blocks anything. This is what the record can and cannot currently prove.');
-        return lines.join('\n');
-    });
-});
-// ── root ─────────────────────────────────────────────────────────────────────
-exports.learningUsageCommand = new commander_1.Command('learning-usage')
-    .description('Read and analyse the learning and rule usage record (issue #1103)')
-    .addCommand(offersCommand)
-    .addCommand(recordFiringsCommand)
-    .addCommand(classifyCommand)
-    .addCommand(candidatesCommand)
-    .addCommand(standingCommand)
-    .addCommand(reportCommand)
-    .addCommand(backfillCommand)
-    .addCommand(stampIdsCommand)
-    .addCommand(pruneCommand)
-    .addCommand(verifyCommand);