fraim 2.0.338 → 2.0.339

package/dist/src/local-mcp-server/learning-context-builder.js

@@ -890,8 +890,9 @@ function enumerateFileEntries(file, threshold, usageClock, now) {
         out.push({
             // The store owns key construction. Building the composite key by hand here
             // would be a second definition of what an entry's identity is, and the two
-            // would drift the first time normalization changed.
-            key: current.id ?? (0, learning_usage_store_1.titleUsageKey)(file.fileType, current.title),
+            // would drift the first time normalization changed. Issue #1752 A1 made
+            // that one function rather than four copies of the same expression.
+            key: (0, learning_usage_store_1.resolveEntryIdentity)({ id: current.id, fileType: file.fileType, title: current.title }).key,
             family: 'learning',
             id: current.id,
             title: current.title,
@@ -939,9 +940,27 @@ function enumerateFileEntries(file, threshold, usageClock, now) {
  * listed. `aboveThreshold` is what separates active guidance from the dormant
  * rollup. Nothing here depends on the agent reading anything.
  *
- * Deduplicated by key with the later tier winning, matching how
- * `mergeLearningEntriesAcrossTiers` resolves a title collision across levels, so
- * one lesson is one offer even when two levels hold it.
+ * ## Issue #1752 A2 — one lesson, one offer, stamped or not
+ *
+ * This deduped by usage key, which sounds like the same thing as the context
+ * reader's rule and is not. `resolveOrgLearningFileTiers` deliberately returns
+ * both the org pack copy and the repo-local copy of an org family, because #1002
+ * R4 requires that a promoted entry not hide the rest of its family. The context
+ * reader then merges those tiers with `mergeLearningEntriesAcrossTiers`, keyed on
+ * the normalized title, so the agent sees one lesson. Keying the offer record on
+ * `id ?? titleUsageKey(...)` instead meant that a lesson carrying an `**Id**` line
+ * in one tier and not the other produced two keys, and both were recorded.
+ *
+ * That is defect 4 in #1752, and it is why `standing --changes-only` could
+ * recommend promoting and demoting the same lesson in one response: the
+ * title-keyed twin collected the offers while the id-keyed one collected the
+ * firings (the firing path never split, because `buildEntryIndex` dedups by
+ * identity first-wins). Measured live: five titles emitting two keys each in a
+ * single derived offer batch.
+ *
+ * So group by the same normalized title the context reader groups by, resolve one
+ * identity per group preferring whichever tier carries an id, and let the later
+ * tier win on content exactly as before.
  */
 function collectOfferedLearningEntries(workspaceRoot, userId, forJob, domain) {
     const roots = getLearningRoots(workspaceRoot);
@@ -950,13 +969,35 @@ function collectOfferedLearningEntries(workspaceRoot, userId, forJob, domain) {
     const usageClock = resolveUsageClock(workspaceRoot);
     const now = new Date();
     const resolved = resolveContextLearningFiles(workspaceRoot, resolvedUserId, roots, forJob, domain);
-    const byKey = new Map();
+    // Grouped by family plus normalized title, which is what `titleUsageKey`
+    // already computes. Two families holding the same title are two lessons, and
+    // that is the existing rule rather than a new one.
+    const byLesson = new Map();
     for (const file of [...resolved.l2, ...resolved.l1]) {
         for (const entry of enumerateFileEntries(file, threshold, usageClock, now)) {
-            byKey.set(entry.key, entry);
+            const lessonKey = (0, learning_usage_store_1.titleUsageKey)(entry.fileType, entry.title);
+            const group = byLesson.get(lessonKey);
+            if (group)
+                group.push(entry);
+            else
+                byLesson.set(lessonKey, [entry]);
         }
     }
-    return [...byKey.values()];
+    const out = [];
+    for (const group of byLesson.values()) {
+        // Later tier wins for content, unchanged precedence.
+        const winner = group[group.length - 1];
+        // The id comes from whichever tier carries one, because `stamp-ids` has not
+        // reached the org and manager pack homes for every corpus yet. Latest wins
+        // when more than one tier is stamped.
+        const id = group.reduce((found, entry) => entry.id ?? found, null);
+        out.push({
+            ...winner,
+            id,
+            key: (0, learning_usage_store_1.resolveEntryIdentity)({ id, fileType: winner.fileType, title: winner.title }).key,
+        });
+    }
+    return out;
 }
 /**
  * Issue #1103 R3: the auto-loaded Team Context rule files.

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

@@ -81,6 +81,20 @@ function classifyRecurrence(store, options) {
         : null;
     const historyComplete = record.offered.log.length === record.offered.total
         || (oldestRetained !== null && new Date(oldestRetained).getTime() <= windowStartMs);
+    // #1752 D2, the issue's suggested fix 4. `report` selects an entry into
+    // `ignoredWhileInContext` on `byOutcome.ignored > 0`, which asserts the entry
+    // was in context; `classify` was answering `not-offered` for the same entry,
+    // which asserts the opposite, with no hedge. The #1740 postmortem states in
+    // first-hand prose that L-abc958f241 "was above threshold and in context".
+    // When the two halves of one record disagree, neither is evidence.
+    const ignoredInWindow = record.fired.log.filter((firing) => firing.outcome === 'ignored' && daysBetween(firing.date, options.date) <= options.windowDays);
+    // #1752 D1. Absence of an offer for this job is only evidence when the record
+    // can resolve this job at all. Measured: 2067 of 2354 retained offer records
+    // carry `session` or `__freeform__`, because `fraim_connect` writes one offer
+    // per entry per session and a plain newest-N bound evicted the job-labelled
+    // ones within about a day. Asking about a job the store has never retained an
+    // offer for is a gap in the record, not a delivery failure.
+    const jobCoverage = Object.values(store.entries).some((entry) => entry.offered.log.some((offer) => offer.job === options.job && daysBetween(offer.date, options.date) <= options.windowDays));
     if (matchingOffers.length > 0) {
         return {
             ...base,
@@ -91,6 +105,26 @@ function classifyRecurrence(store, options) {
             targetOfFix: 'entry',
         };
     }
+    if (ignoredInWindow.length > 0) {
+        return {
+            ...base,
+            classification: 'undetermined',
+            diagnosis: `The two halves of this entry's record disagree: it carries ${ignoredInWindow.length} attested \`ignored\` outcome${ignoredInWindow.length === 1 ? '' : 's'} inside the window, which says it was in context and the work went against it, while the offer log holds no matching offer for ${options.job}, which says it was never delivered. Both cannot be true.`,
+            recommendation: 'Do not act on either reading. An `ignored` attestation and an empty offer log are contradictory evidence about the same event, so the record cannot say whether the entry or the delivery is at fault. Run `learning-usage verify` to see whether this entry carries an integrity flag, and treat the recurrence on its own terms until the record agrees with itself.',
+            recurrenceBump: true,
+            targetOfFix: 'none',
+        };
+    }
+    if (!jobCoverage) {
+        return {
+            ...base,
+            classification: 'undetermined',
+            diagnosis: `No offer anywhere in the record carries the job label ${options.job} inside this window, so the per-job offer record has no resolution for that job and cannot say whether this entry was in context for it.`,
+            recommendation: 'The offer record cannot answer this question for this job, so absence of a match is not evidence of absence. Do not conclude a delivery problem. Re-ask once the job has run with offer recording in place, or widen the window to one the record covers.',
+            recurrenceBump: true,
+            targetOfFix: 'none',
+        };
+    }
     if (!historyComplete) {
         return {
             ...base,
@@ -179,6 +213,26 @@ function firingsUnderModel(record, model) {
         return 0;
     return record.fired.byModel[model] ?? 0;
 }
+/**
+ * #1752 C4 - is this entry's per-model attribution unknown, as opposed to zero?
+ *
+ * All 781 retained firing records in the live store carry `agent: null,
+ * model: null`, because `attest-learning-firings.md` invoked `record-firings`
+ * with no `--agent` or `--model`. `firedUnderCurrentModel` was therefore
+ * structurally 0 for every entry, which is why `candidates` proposed 31
+ * retirements: every entry clearing the offer threshold became one, however hard
+ * it was working. Fixing the `currentModel` resolution alone would not have
+ * changed a single one of them.
+ *
+ * The predicate is deliberately narrower than "fired at all". An entry whose only
+ * outcomes are `ignored` or `not-applicable` has an empty `byModel` because those
+ * outcomes correctly do not bucket by model; that is information, not a gap. Only
+ * a clock-advancing firing that produced no bucket means the model went
+ * unrecorded.
+ */
+function modelAttributionUnknown(record) {
+    return firedCount(record) > 0 && Object.keys(record.fired.byModel).length === 0;
+}
 function earlierModelFirings(record, currentModel) {
     return Object.entries(record.fired.byModel)
         .filter(([model]) => model !== currentModel)
@@ -189,9 +243,22 @@ function latestTitle(record) {
     return record.titles[record.titles.length - 1] ?? record.key;
 }
 function findRetirementCandidates(store, options) {
-    const currentModel = options.currentModel ?? (0, learning_usage_projection_1.resolveCurrentModel)(store);
+    const currentModel = (0, learning_usage_projection_1.resolveCurrentModel)(options.currentModel);
     const threshold = options.limits.retirementOfferThreshold;
     const probe = options.structuralProbe ?? resolveStructuralProbe(options.structuralSignalPath);
+    // #1752 C1: retirement candidacy is computed per model, so with no model there
+    // is no question to answer. An empty list with the reason stated is the honest
+    // answer; computing against a null bucket is how defect 3 produced 31
+    // proposals nobody could act on.
+    if (!currentModel) {
+        return {
+            currentModel: null,
+            offerThreshold: threshold,
+            candidates: [],
+            notCandidates: [],
+            reason: 'The current model did not resolve, so no per-model conclusion can be drawn. Pass --model <model>, or set FRAIM_ACTIVE_MODEL. The current model is never inferred from the usage record, because the record is shared by concurrent sessions from more than one agent and would report whichever wrote last.',
+        };
+    }
     const candidates = [];
     const notCandidates = [];
     for (const record of Object.values(store.entries)) {
@@ -204,6 +271,14 @@ function findRetirementCandidates(store, options) {
             notCandidates.push({ key: record.key, title, reason: `It fired ${fired} time${fired === 1 ? '' : 's'} under the current model, so it is still earning its place.` });
             continue;
         }
+        if (modelAttributionUnknown(record)) {
+            notCandidates.push({
+                key: record.key,
+                title,
+                reason: `Per-model attribution is unknown for this entry: it fired ${firedCount(record)} time${firedCount(record) === 1 ? '' : 's'} and no firing carries a model, so how hard it is working under ${currentModel} cannot be measured. Held back rather than counted as zero.`,
+            });
+            continue;
+        }
         if (offered < threshold) {
             notCandidates.push({
                 key: record.key,
@@ -297,6 +372,7 @@ function toReportEntry(record) {
         title: latestTitle(record),
         offered: record.offered.total,
         fired: firedCount(record),
+        ignored: record.fired.byOutcome.ignored,
         lastFired: record.fired.lastFiredAt,
         firedUnder: Object.keys(record.fired.byModel),
         recentLog: record.fired.log,
@@ -320,7 +396,8 @@ function buildUsageReport(store, options) {
     return {
         generatedAt: now.toISOString(),
         windowDays: options.windowDays,
-        currentModel: (0, learning_usage_projection_1.resolveCurrentModel)(store),
+        currentModel: (0, learning_usage_projection_1.resolveCurrentModel)(options.currentModel),
+        integrityFlagged: learningRecords.filter((r) => Boolean(r.integrity)).length,
         totals: {
             entriesOffered: offered.length,
             entriesWithFirings: fired.length,

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

@@ -48,7 +48,9 @@ function buildEntryIndex(workspaceRoot, userId) {
         for (const entry of entries) {
             const fileType = fileTypeOf(entry);
             const attestable = {
-                key: entry.id ?? (0, learning_usage_store_1.titleUsageKey)(fileType, entry.title),
+                // #1752 A1: one definition of what an entry is, shared with the offer
+                // path. These two disagreeing is defect 4.
+                key: (0, learning_usage_store_1.resolveEntryIdentity)({ id: entry.id, fileType, title: entry.title }).key,
                 family: 'learning',
                 title: entry.title,
                 fileType,
@@ -142,7 +144,9 @@ function recordAttestationsFromRetrospective(workspaceRoot, userId, options) {
     let applied = 0;
     let alreadyRecorded = 0;
     if (inputs.length > 0) {
-        const result = (0, learning_usage_store_1.recordFirings)(inputs, { limits, now: options.now, storePath: options.storePath });
+        const result = (0, learning_usage_store_1.recordFirings)(inputs, {
+            limits, now: options.now, storePath: options.storePath, integrityMode: options.integrityMode,
+        });
         applied = result.recorded;
         alreadyRecorded = result.alreadyRecorded;
     }
@@ -208,6 +212,9 @@ function runBackfill(workspaceRoot, userId, options) {
             limits,
             now: options.now,
             storePath: options.storePath,
+            // A backfill reconciles hundreds of retrospectives at once, so a single
+            // stranded-offer entry must not refuse the whole run.
+            integrityMode: 'flag',
         });
         if (result.sectionState !== 'absent')
             report.filesWithSection += 1;

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

@@ -18,6 +18,18 @@ 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");
+/**
+ * The repair for a usage record that has gone wrong.
+ *
+ * The record is derived (#1103 R17), so the fix is to rebuild it rather than to
+ * reconcile it in place. Measured on a 733-file retrospective corpus: a rebuild
+ * lands with zero split identities and one model bucket, because the identity
+ * resolution and the model normalization fix the causes and a rebuilt store
+ * carries no legacy shape.
+ */
+const REBUILD_NOTE = 'Delete the `usage/` directory and run `learning-usage backfill` to rebuild the record from the retrospectives. The record is derived: every firing is also written in the retrospective that attested it, so a rebuild restores one identity per lesson and one bucket per model. It costs the offer history, which rebuilds itself from live traffic.';
 function resolveWorkspaceRoot(options) {
     return node_path_1.default.resolve(options.workspaceRoot || options.root || process.cwd());
 }
@@ -38,6 +50,23 @@ function addCommonOptions(command) {
         .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')
@@ -52,7 +81,7 @@ const offersCommand = addCommonOptions(new commander_1.Command('offers'))
     // 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 = (0, learning_usage_store_1.readUsageStore)();
+    const store = readStore(workspaceRoot);
     const recorded = Object.values(store.entries)
         .filter((entry) => entry.offered.log.some((offer) => offer.job === options.job))
         .map((entry) => {
@@ -102,6 +131,7 @@ const recordFiringsCommand = addCommonOptions(new commander_1.Command('record-fi
     .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);
@@ -118,6 +148,7 @@ const recordFiringsCommand = addCommonOptions(new commander_1.Command('record-fi
         agent: options.agent ?? null,
         model: options.model ?? null,
         legacy: Boolean(options.legacy),
+        integrityMode: options.force ? 'flag' : 'throw',
     });
     emit(result, options.json, () => {
         const lines = [
@@ -151,17 +182,17 @@ const classifyCommand = addCommonOptions(new commander_1.Command('classify'))
     // 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.
-    let key;
-    if (options.entry) {
-        key = String(options.entry);
-    }
-    else if (options.title && options.family) {
-        key = (0, learning_usage_store_1.titleUsageKey)(String(options.family), String(options.title));
-    }
-    else {
+    if (!options.entry && !(options.title && options.family)) {
         throw new Error('Pass --entry <id>, or --title <title> together with --family <family>.');
     }
-    const store = (0, learning_usage_store_1.readUsageStore)();
+    // #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,
@@ -177,14 +208,13 @@ const classifyCommand = addCommonOptions(new commander_1.Command('classify'))
     ].join('\n'));
 });
 // ── candidates ───────────────────────────────────────────────────────────────
-const candidatesCommand = addCommonOptions(new commander_1.Command('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('--model <model>', 'Override the current model (defaults to the most recently offered-to model)')
     .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)((0, learning_usage_store_1.readUsageStore)(), {
+    const result = (0, learning_usage_analysis_1.findRetirementCandidates)(readStore(workspaceRoot), {
         workspaceRoot,
         limits,
         currentModel: options.model ?? undefined,
@@ -192,7 +222,14 @@ const candidatesCommand = addCommonOptions(new commander_1.Command('candidates')
     });
     emit(result, options.json, () => {
         if (result.candidates.length === 0) {
-            return `No retirement candidates. Current model: ${result.currentModel ?? 'unknown'}; threshold ${result.offerThreshold} offers.`;
+            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) {
@@ -203,13 +240,13 @@ const candidatesCommand = addCommonOptions(new commander_1.Command('candidates')
     });
 });
 // ── standing ─────────────────────────────────────────────────────────────────
-const standingCommand = addCommonOptions(new commander_1.Command('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)((0, learning_usage_store_1.readUsageStore)(), { limits });
+    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);
@@ -231,16 +268,17 @@ const standingCommand = addCommonOptions(new commander_1.Command('standing'))
     });
 });
 // ── report ───────────────────────────────────────────────────────────────────
-const reportCommand = addCommonOptions(new commander_1.Command('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)((0, learning_usage_store_1.readUsageStore)(), {
+    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 = [
@@ -256,7 +294,13 @@ const reportCommand = addCommonOptions(new commander_1.Command('report'))
         }
         if (report.ignoredWhileInContext.length) {
             lines.push('', 'Ignored while in context');
-            report.ignoredWhileInContext.forEach((e, i) => lines.push(`${i + 1}. ${e.title}. In context and the work went against it, so the entry needs work rather than another recurrence.`));
+            // #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} entr${report.integrityFlagged === 1 ? 'y has' : 'ies have'} an integrity flag: more attested firings than recorded offers. Run \`learning-usage verify\` before acting on anything below.`);
         }
         lines.push('', 'Nothing is retired from this view. Run sleep-on-learnings to decide.');
         return lines.join('\n');
@@ -343,6 +387,19 @@ function stampFile(filePath, fileType, apply) {
     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).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))
@@ -356,9 +413,14 @@ const stampIdsCommand = addCommonOptions(new commander_1.Command('stamp-ids'))
     .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))
-        : [node_path_1.default.join(workspaceRoot, 'fraim', 'personalized-employee', 'learnings')];
+        : defaultStampDirs(workspaceRoot);
     const results = [];
     for (const dir of dirs) {
         if (!node_fs_1.default.existsSync(dir))
@@ -380,7 +442,8 @@ const stampIdsCommand = addCommonOptions(new commander_1.Command('stamp-ids'))
         files: results,
     };
     emit(payload, options.json, () => [
-        `${payload.apply ? 'Stamped' : 'Would stamp'} ${payload.entriesStamped} entries across ${payload.filesScanned} files.`,
+        `${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'));
@@ -394,6 +457,52 @@ const pruneCommand = addCommonOptions(new commander_1.Command('prune'))
     const result = (0, learning_usage_store_1.pruneUsageStore)(limits);
     emit({ ...result, storePath: (0, learning_usage_store_1.resolveUsageStorePath)(), limits }, options.json, () => `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}`;
+        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', 'An entry cannot fire without being offered, so one of the two counters is wrong. History stranded in a store copy nothing reads is the usual 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 fired with no model recorded', 'entries fired with no model recorded', 'Per-model retirement cannot be answered for these, and they are held back rather than counted as zero. These were attested before record-firings carried --agent and --model, so the model was never recorded against them and a rebuild cannot invent it; attestations recorded from now on carry both.'), '', '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. Their history is recoverable only through a rebuild.');
+        }
+        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 compact it to the configured retention window.`
+            : `  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)')
@@ -405,4 +514,5 @@ exports.learningUsageCommand = new commander_1.Command('learning-usage')
     .addCommand(reportCommand)
     .addCommand(backfillCommand)
     .addCommand(stampIdsCommand)
-    .addCommand(pruneCommand);
+    .addCommand(pruneCommand)
+    .addCommand(verifyCommand);