fraim 2.0.270 → 2.0.272

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

@@ -0,0 +1,191 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.extractLegacyTitle = exports.parseFiringSection = void 0;
+exports.recordAttestationsFromRetrospective = recordAttestationsFromRetrospective;
+exports.runBackfill = runBackfill;
+/**
+ * Issue #1103 — turning an attestation into a usage record.
+ *
+ * The retrospective is the durable record of a firing; the usage store is derived
+ * from it (R17). So there is exactly one parser (`learning-firing-parser.ts`) and
+ * one recorder here, used by two entry points: the live attestation at the end of
+ * a job, and the backfill over the retrospectives already on disk (R15).
+ *
+ * Matching is an id or an exact title, and nothing else. R5 forbids resolving a
+ * prose reference to the closest title, and an unmatched item is reported rather
+ * than guessed at: a wrong match writes a firing onto the wrong entry, which is
+ * worse than no firing at all.
+ */
+const fs_1 = require("fs");
+const path_1 = require("path");
+const learning_usage_store_1 = require("./learning-usage-store");
+const learning_firing_parser_1 = require("./learning-firing-parser");
+const learning_context_builder_1 = require("./learning-context-builder");
+// Re-exported so callers that only need one of the two halves keep one import.
+var learning_firing_parser_2 = require("./learning-firing-parser");
+Object.defineProperty(exports, "parseFiringSection", { enumerable: true, get: function () { return learning_firing_parser_2.parseFiringSection; } });
+Object.defineProperty(exports, "extractLegacyTitle", { enumerable: true, get: function () { return learning_firing_parser_2.extractLegacyTitle; } });
+function buildEntryIndex(workspaceRoot, userId) {
+    const byId = new Map();
+    const byTitle = new Map();
+    // Every scope a firing could name: the manager's own entries, the org entries
+    // the agent also reads, and the manager-coaching family.
+    for (const scope of ['manager', 'org', 'reverse']) {
+        let entries = [];
+        try {
+            entries = (0, learning_context_builder_1.readPreservedLearnings)(workspaceRoot, userId, scope);
+        }
+        catch {
+            continue;
+        }
+        for (const entry of entries) {
+            if (entry.id && !byId.has(entry.id))
+                byId.set(entry.id, entry);
+            const key = (0, learning_usage_store_1.normalizeEntryTitle)(entry.title);
+            if (!byTitle.has(key))
+                byTitle.set(key, entry);
+        }
+    }
+    return { byId, byTitle };
+}
+function fileTypeOf(entry) {
+    return learning_context_builder_1.CATEGORY_TO_FILETYPE[entry.category] ?? 'mistake-patterns';
+}
+function retrospectiveDate(content, fallback) {
+    const match = content.match(/^date:\s*(\d{4}-\d{2}-\d{2})\s*$/m);
+    return match ? match[1] : fallback;
+}
+/**
+ * Record the firings a retrospective attests. Idempotent per (entry, source), so a
+ * re-run, or a backfill that overlaps a live attestation, cannot inflate a count.
+ */
+function recordAttestationsFromRetrospective(workspaceRoot, userId, options) {
+    const limits = options.limits ?? (0, learning_usage_store_1.resolveUsageLimits)(workspaceRoot);
+    const parsed = (0, learning_firing_parser_1.parseFiringSection)(options.content, { source: options.source, legacy: options.legacy });
+    const date = options.date ?? retrospectiveDate(options.content, new Date().toISOString().slice(0, 10));
+    const index = buildEntryIndex(workspaceRoot, userId);
+    const unmatched = [];
+    const inputs = [];
+    for (const item of parsed.items) {
+        let entry;
+        if (item.id) {
+            entry = index.byId.get(item.id);
+            if (!entry) {
+                unmatched.push({
+                    id: item.id,
+                    title: item.title,
+                    reason: `No entry carries the id ${item.id}. Reported unmatched rather than assigned to the closest title.`,
+                    raw: item.raw,
+                });
+                continue;
+            }
+        }
+        else {
+            entry = index.byTitle.get((0, learning_usage_store_1.normalizeEntryTitle)(item.title));
+            if (!entry) {
+                unmatched.push({
+                    id: null,
+                    title: item.title,
+                    reason: 'No entry has exactly this title. Exact titles match; a paraphrase is reported rather than resolved by similarity.',
+                    raw: item.raw,
+                });
+                continue;
+            }
+        }
+        const fileType = fileTypeOf(entry);
+        inputs.push({
+            key: entry.id ?? (0, learning_usage_store_1.titleUsageKey)(fileType, entry.title),
+            family: 'learning',
+            title: entry.title,
+            fileType,
+            level: entry.level,
+            outcome: item.outcome,
+            note: item.note,
+            job: options.job,
+            date,
+            agent: options.agent,
+            model: options.model,
+            source: item.format === 'legacy' ? 'backfill-legacy' : 'attested',
+            sourceRef: options.source,
+        });
+    }
+    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 });
+        applied = result.recorded;
+        alreadyRecorded = result.alreadyRecorded;
+    }
+    return {
+        source: options.source,
+        sectionState: parsed.sectionState,
+        itemsRead: parsed.items.length + parsed.rejected.length,
+        applied,
+        alreadyRecorded,
+        unmatched,
+        rejected: parsed.rejected,
+    };
+}
+function jobFromFrontmatter(content) {
+    const match = content.match(/^job:\s*(.+)$/m);
+    return match ? match[1].trim() : 'unknown';
+}
+/**
+ * Read every retrospective and apply the firings it attests.
+ *
+ * Best effort by design (R15): only an id or an exact title resolves, and the
+ * unmatched count is reported rather than resolved by fuzzy matching. A low match
+ * rate is an expected outcome to state, not a failure to hide — only a small
+ * fraction of the existing attestations name a machine-matchable identifier.
+ *
+ * A retrospective already stamped `synthesized` is still read: being synthesized
+ * for learning content is not the same as having contributed usage data.
+ */
+function runBackfill(workspaceRoot, userId, options) {
+    const limits = options.limits ?? (0, learning_usage_store_1.resolveUsageLimits)(workspaceRoot);
+    const dir = options.retrospectivesDir ?? (0, path_1.join)(workspaceRoot, 'docs', 'retrospectives');
+    const report = {
+        filesScanned: 0, filesWithSection: 0, itemsRead: 0, applied: 0,
+        alreadyRecorded: 0, unmatched: [], rejected: [], synthesizedFilesRead: 0,
+    };
+    if (!(0, fs_1.existsSync)(dir))
+        return report;
+    let files;
+    try {
+        files = (0, fs_1.readdirSync)(dir).filter((f) => f.endsWith('.md'));
+    }
+    catch {
+        return report;
+    }
+    for (const file of files) {
+        let content;
+        try {
+            content = (0, fs_1.readFileSync)((0, path_1.join)(dir, file), 'utf8');
+        }
+        catch {
+            continue;
+        }
+        report.filesScanned += 1;
+        if (/^synthesized:\s*\S/m.test(content))
+            report.synthesizedFilesRead += 1;
+        const result = recordAttestationsFromRetrospective(workspaceRoot, userId, {
+            content,
+            source: `docs/retrospectives/${file}`,
+            job: jobFromFrontmatter(content),
+            agent: options.agent,
+            model: options.model,
+            legacy: true,
+            limits,
+            now: options.now,
+            storePath: options.storePath,
+        });
+        if (result.sectionState !== 'absent')
+            report.filesWithSection += 1;
+        report.itemsRead += result.itemsRead;
+        report.applied += result.applied;
+        report.alreadyRecorded += result.alreadyRecorded;
+        report.unmatched.push(...result.unmatched);
+        report.rejected.push(...result.rejected);
+    }
+    return report;
+}

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

@@ -0,0 +1,408 @@
+"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");
+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');
+}
+// ── 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 = (0, learning_usage_store_1.readUsageStore)();
+    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')
+    .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 = node_fs_1.default.readFileSync(filePath, 'utf8');
+    const source = node_path_1.default.relative(workspaceRoot, filePath).replace(/\\/g, '/');
+    const result = (0, learning_usage_attestation_1.recordAttestationsFromRetrospective)(workspaceRoot, user, {
+        content,
+        source,
+        job: options.job ?? 'unknown',
+        agent: options.agent ?? null,
+        model: options.model ?? null,
+        legacy: Boolean(options.legacy),
+    });
+    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.
+    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 {
+        throw new Error('Pass --entry <id>, or --title <title> together with --family <family>.');
+    }
+    const store = (0, learning_usage_store_1.readUsageStore)();
+    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 = 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)(), {
+        workspaceRoot,
+        limits,
+        currentModel: options.model ?? undefined,
+        structuralSignalPath: options.detector,
+    });
+    emit(result, options.json, () => {
+        if (result.candidates.length === 0) {
+            return `No retirement candidates. Current model: ${result.currentModel ?? 'unknown'}; threshold ${result.offerThreshold} offers.`;
+        }
+        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 = 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 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 = 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)(), {
+        workspaceRoot,
+        limits,
+        windowDays: Number.parseInt(options.window, 10) || 90,
+    });
+    emit(report, options.json, () => {
+        const lines = [
+            `${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');
+            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.`));
+        }
+        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 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);
+    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')];
+    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.`,
+        `${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, () => `Pruned ${result.prunedOfferRecords} offer records and ${result.prunedFiringRecords} firing records across ${result.entries} entries. Aggregates unchanged.`);
+});
+// ── 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);

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

@@ -0,0 +1,79 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.buildUsageLookup = buildUsageLookup;
+exports.lookupUsage = lookupUsage;
+exports.resolveCurrentModel = resolveCurrentModel;
+/**
+ * Issue #1103 — projecting the usage record into the shapes its readers need.
+ *
+ * The store owns writing and persistence; this owns turning what is stored into
+ * what a scorer, a surface, or a report asks for. Split out because those are two
+ * jobs with different reasons to change: the record's schema changes when the
+ * privacy or retention contract changes, and these projections change when a
+ * consumer needs a different view.
+ *
+ * Nothing here writes.
+ */
+const learning_usage_store_1 = require("./learning-usage-store");
+function toLookupValue(record) {
+    return {
+        key: record.key,
+        offered: record.offered.total,
+        offeredAboveThreshold: record.offered.aboveThreshold,
+        fired: record.fired.byOutcome.prevented + record.fired.byOutcome.applied,
+        firedTotalAttestations: record.fired.total,
+        lastFired: record.fired.lastFiredAt,
+        lastOffered: record.offered.lastOfferedAt,
+        firedUnder: Object.keys(record.fired.byModel),
+        byOutcome: record.fired.byOutcome,
+        log: record.fired.log,
+    };
+}
+/**
+ * A lookup keyed by every identifier that resolves to a record: the entry id, and
+ * every title the entry has been known by. That is what lets a scorer look up an
+ * entry by whichever handle it has.
+ */
+function buildUsageLookup(store) {
+    const lookup = new Map();
+    for (const record of Object.values(store.entries)) {
+        const value = toLookupValue(record);
+        lookup.set(record.key, value);
+        if (record.fileType) {
+            for (const title of record.titles) {
+                lookup.set((0, learning_usage_store_1.titleUsageKey)(record.fileType, title), value);
+            }
+        }
+    }
+    return lookup;
+}
+/**
+ * Resolve the usage for one entry from whichever handles it has. Prefers the id,
+ * because a title is only a fallback for entries the id migration has not reached.
+ */
+function lookupUsage(lookup, id, fileType, title) {
+    if (id) {
+        const byId = lookup.get(id);
+        if (byId)
+            return byId;
+    }
+    return lookup.get((0, learning_usage_store_1.titleUsageKey)(fileType, title));
+}
+/**
+ * The model with the most recent offer. Used as "the current model" for the
+ * per-model retirement question, so it follows the agent in use rather than
+ * needing to be configured.
+ */
+function resolveCurrentModel(store) {
+    let bestDate = '';
+    let bestModel = null;
+    for (const record of Object.values(store.entries)) {
+        for (const entry of record.offered.log) {
+            if (entry.model && entry.date >= bestDate) {
+                bestDate = entry.date;
+                bestModel = entry.model;
+            }
+        }
+    }
+    return bestModel;
+}