fraim 2.0.270 → 2.0.271

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

@@ -6,12 +6,16 @@
  * workspace root on the user's machine.
  */
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.CATEGORY_TO_FILETYPE = exports.BRAIN_LEARNING_FILETYPE_TO_REGION = exports.LEARNING_PRIORITIES = void 0;
+exports.CATEGORY_TO_FILETYPE = exports.BRAIN_LEARNING_FILETYPE_TO_REGION = exports.TEAM_CONTEXT_RELATIVE_PATHS = exports.LEARNING_ENTRY_ID_REGEX = exports.LEARNING_PRIORITIES = exports.DEFAULT_THRESHOLD = void 0;
 exports.learningEntryHeadingRegex = learningEntryHeadingRegex;
+exports.learningEntryIdLineRegex = learningEntryIdLineRegex;
+exports.generateLearningEntryId = generateLearningEntryId;
 exports.getScoreThreshold = getScoreThreshold;
 exports.computeEffectiveScore = computeEffectiveScore;
 exports.mergeLearningEntriesAcrossTiers = mergeLearningEntriesAcrossTiers;
 exports.buildLearningContextSection = buildLearningContextSection;
+exports.collectOfferedLearningEntries = collectOfferedLearningEntries;
+exports.collectOfferedRuleFiles = collectOfferedRuleFiles;
 exports.buildTeamContextSection = buildTeamContextSection;
 exports.resolveTeamContextFiles = resolveTeamContextFiles;
 exports.isTeamContextKey = isTeamContextKey;
@@ -24,6 +28,7 @@ exports.readPreservedLearnings = readPreservedLearnings;
 exports.applyLearningEntryChange = applyLearningEntryChange;
 exports.isTruthyFlag = isTruthyFlag;
 const fs_1 = require("fs");
+const crypto_1 = require("crypto");
 const path_1 = require("path");
 const project_fraim_paths_1 = require("../core/utils/project-fraim-paths");
 const brand_store_1 = require("../core/brand-store");
@@ -32,8 +37,17 @@ const brand_store_1 = require("../core/brand-store");
 // cache, which silently returned nothing once that cache stopped existing.
 const pack_home_1 = require("../cli/utils/pack-home");
 const learning_domains_1 = require("../config/learning-domains");
+// Key construction only. The store's read/write path is still required lazily
+// below, because that side pulls in the retention config and a static cycle
+// through this module would be fragile.
+const learning_usage_store_1 = require("./learning-usage-store");
 const REPO_LEARNINGS_REL = (0, project_fraim_paths_1.getWorkspaceFraimDisplayPath)('personalized-employee/learnings').replace(/\/$/, '');
-const DEFAULT_THRESHOLD = 3.0;
+/**
+ * The score at or above which an entry is injected. Exported so a test asserts
+ * the boundary the runtime actually uses rather than a copy of the number, which
+ * would keep passing if this default ever changed.
+ */
+exports.DEFAULT_THRESHOLD = 3.0;
 const AGING_HORIZON_DAYS = 7;
 const MAX_ENTRIES_SCANNED = 200;
 const L0_SLEEP_ON_LEARNINGS_PROMPT_MIN = 5;
@@ -46,13 +60,44 @@ const L0_SLEEP_ON_LEARNINGS_PROMPT_MIN = 5;
 //   3. READ — the counters and the Hub (readPreservedLearnings) display them.
 // These previously drifted (each accepted a different priority set / heading
 // level), which silently dropped P-CRITICAL learnings. Everything now derives
-// from LEARNING_PRIORITIES, and a build-time contract test
-// (tests/isolated/test-learning-format-contract.ts) asserts all three sides agree.
+// from LEARNING_PRIORITIES, and a build-time contract check
+// (scripts/validate-learning-format-contract.ts, run by `npm run build`) asserts
+// all three sides agree. Issue #1103 added the `**Id**` line to the same contract.
 exports.LEARNING_PRIORITIES = ['P-CRITICAL', 'P-HIGH', 'P-MED', 'P-LOW'];
 /** Canonical entry-heading matcher: `##`..`######` + `[P-X]` + optional title. */
 function learningEntryHeadingRegex(flags = '') {
     return new RegExp(`^#{2,}\\s+\\[(${exports.LEARNING_PRIORITIES.join('|')})\\]\\s*(.*)$`, flags);
 }
+/**
+ * Issue #1103 R5: the entry's stable identifier, written as a `**Id**: L-…` line.
+ *
+ * A firing record has to survive a later title edit, which a title-derived key
+ * cannot do — so the identity is persisted on the entry rather than computed at
+ * read time. Generation is deterministic from (family, original title) only so a
+ * re-run of the migration never renumbers the corpus; once written, the id never
+ * changes, including when the title does.
+ */
+/** What `generateLearningEntryId` emits: `L-` plus exactly ten hex characters. */
+exports.LEARNING_ENTRY_ID_REGEX = /^L-[0-9a-f]{10}$/;
+/**
+ * What the reader accepts. Deliberately wider than what the generator emits: a
+ * hand-written or hand-edited id must be honoured rather than silently ignored,
+ * because ignoring it would leave the entry looking un-stamped and route its
+ * firings to a title key without saying so.
+ */
+const LEARNING_ENTRY_ID_LINE = /^\*\*Id\*\*:\s*(L-[0-9A-Za-z]{6,24})\s*$/;
+function learningEntryIdLineRegex() {
+    return new RegExp(LEARNING_ENTRY_ID_LINE.source);
+}
+function generateLearningEntryId(fileType, title) {
+    // Ten hex characters: short enough for an agent to type into a retrospective
+    // by hand, wide enough that a collision across one manager's corpus is not a
+    // practical concern.
+    const digest = (0, crypto_1.createHash)('sha1')
+        .update(`${fileType}|${title.trim().replace(/\s+/g, ' ').toLowerCase()}`)
+        .digest('hex');
+    return `L-${digest.slice(0, 10)}`;
+}
 /**
  * The manager location that is NOT the portable authoring base.
  *
@@ -243,7 +288,7 @@ function getScoreThreshold(workspaceRoot) {
     const t = config?.learning?.scoreThreshold;
     if (typeof t === 'number' && t > 0)
         return t;
-    return DEFAULT_THRESHOLD;
+    return exports.DEFAULT_THRESHOLD;
 }
 /**
  * Effective score for an L1 learning entry. The aging-risk count below uses
@@ -252,7 +297,7 @@ function getScoreThreshold(workspaceRoot) {
  * @param now Optional override for "now" (for forward-looking aging-risk
  *            calculations). Defaults to the current wall clock.
  */
-function computeEffectiveScore(severity, lastSeenDate, recurrences, fileType, now = new Date()) {
+function computeEffectiveScore(severity, lastSeenDate, recurrences, fileType, now = new Date(), lastFiredDate) {
     const baseScore = severity === 'P-CRITICAL' ? 10 : severity === 'P-HIGH' ? 8 : severity === 'P-MED' ? 5 : 3;
     // Mistake patterns decay faster (90d) — they're tied to environments that change.
     // Preferences, manager-coaching, and validated-patterns express durable judgment (180d half-life).
@@ -265,11 +310,55 @@ function computeEffectiveScore(severity, lastSeenDate, recurrences, fileType, no
     catch {
         // Treat as fresh.
     }
-    const decay = Math.pow(0.5, daysSinceLastSeen / halfLife);
+    // Issue #1103 R8: the clock is max(last_seen, last_fired). `Last seen` only
+    // advances when the same signal recurs, which for a mistake pattern means the
+    // mistake happened again — so an entry that fires and prevents its mistake
+    // generates no signal and decays *because* it worked. Reading the newer of the
+    // two dates fixes that inversion with one changed input: no new term, the same
+    // half-lives, the same threshold. The newer date is the smaller elapsed time,
+    // hence min() here. An absent or unparseable firing date contributes nothing,
+    // so it can never silently resurrect a dormant entry, and an entry with no
+    // usage record at all scores exactly as it did before.
+    let daysSinceClock = daysSinceLastSeen;
+    const lastFiredMs = parseClockDate(lastFiredDate);
+    if (lastFiredMs > 0 && !isImplausiblyFuture(lastFiredMs, now)) {
+        const daysSinceFired = Math.max(0, (now.getTime() - lastFiredMs) / (1000 * 60 * 60 * 24));
+        daysSinceClock = Number.isNaN(daysSinceClock) ? daysSinceFired : Math.min(daysSinceClock, daysSinceFired);
+    }
+    const decay = Math.pow(0.5, daysSinceClock / halfLife);
     const recurrenceBoost = Math.log2(Math.max(1, recurrences) + 1);
     return baseScore * decay * recurrenceBoost;
 }
-function scanMistakePatternFile(filePath, threshold, fileType = 'mistake-patterns') {
+/** Clock skew tolerance for a firing date, in milliseconds. */
+const FUTURE_FIRING_TOLERANCE_MS = 24 * 60 * 60 * 1000;
+/**
+ * Is this firing date far enough ahead of now to be untrustworthy?
+ *
+ * `lastFiredAt` is stamped by whichever machine ran the job, and the usage store
+ * lives in the manager home, which is commonly a folder synced across machines.
+ * A machine running fast therefore writes a date another machine reads as the
+ * future, and elapsed time clamps to zero, so decay stops and the entry stays at
+ * full score indefinitely. That is the opposite of a decay model.
+ *
+ * A day of tolerance absorbs ordinary skew, where treating the firing as "just
+ * now" is right anyway. Beyond that the date is not believable, so it is ignored
+ * exactly as an unparseable one is, leaving the recurrence date in charge.
+ */
+function isImplausiblyFuture(timestampMs, now) {
+    return timestampMs - now.getTime() > FUTURE_FIRING_TOLERANCE_MS;
+}
+/**
+ * Parse one side of the decay clock. An absent or unparseable date contributes
+ * nothing, so a malformed `last fired` can never silently resurrect a dormant
+ * entry: it just leaves the recurrence date in charge.
+ */
+function parseClockDate(value) {
+    if (!value)
+        return 0;
+    const parsed = new Date(value).getTime();
+    return Number.isNaN(parsed) ? 0 : parsed;
+}
+function scanMistakePatternFile(filePath, threshold, fileType = 'mistake-patterns', usageClock) {
     const empty = { active: 0, dormant: 0, agingRisk: 0 };
     if (!(0, fs_1.existsSync)(filePath))
         return empty;
@@ -289,17 +378,20 @@ function scanMistakePatternFile(filePath, threshold, fileType = 'mistake-pattern
     let scanned = 0;
     let inEntry = false;
     let severity = null;
+    let title = '';
+    let entryId = null;
     let lastSeen = '';
     let recurrences = 1;
     const flush = () => {
         if (!severity)
             return;
         scanned++;
-        const today = computeEffectiveScore(severity, lastSeen, recurrences, fileType, now);
+        const lastFired = usageClock ? usageClock(entryId, fileType, title) : null;
+        const today = computeEffectiveScore(severity, lastSeen, recurrences, fileType, now, lastFired);
         if (today >= threshold) {
             active++;
             if (lastSeen) {
-                const future = computeEffectiveScore(severity, lastSeen, recurrences, fileType, horizon);
+                const future = computeEffectiveScore(severity, lastSeen, recurrences, fileType, horizon, lastFired);
                 if (future < threshold)
                     agingRisk++;
             }
@@ -316,12 +408,19 @@ function scanMistakePatternFile(filePath, threshold, fileType = 'mistake-pattern
             flush();
             inEntry = true;
             severity = headerMatch[1];
+            title = headerMatch[2].trim();
+            entryId = null;
             lastSeen = '';
             recurrences = 1;
             continue;
         }
         if (!inEntry)
             continue;
+        const idMatch = line.trim().match(LEARNING_ENTRY_ID_LINE);
+        if (idMatch) {
+            entryId = idMatch[1];
+            continue;
+        }
         const lastSeenMatch = line.match(/^\*\*Last seen\*\*:\s*(.+)/);
         if (lastSeenMatch) {
             lastSeen = lastSeenMatch[1].trim();
@@ -335,6 +434,30 @@ function scanMistakePatternFile(filePath, threshold, fileType = 'mistake-pattern
     flush();
     return { active, dormant, agingRisk };
 }
+/**
+ * Build the usage clock from the store, or return undefined when there is no
+ * usage data at all. Returning undefined rather than an always-null function is
+ * deliberate: it keeps the "no usage record" path identical to pre-#1103
+ * behaviour instead of merely equivalent.
+ */
+function resolveUsageClock(workspaceRoot) {
+    try {
+        // Required lazily: the store imports the retention config, which imports the
+        // workspace path helpers, and a cycle through this module would be fragile.
+        const store = require('./learning-usage-store');
+        const projection = require('./learning-usage-projection');
+        const loaded = store.readUsageStore();
+        if (Object.keys(loaded.entries).length === 0)
+            return undefined;
+        const lookup = projection.buildUsageLookup(loaded);
+        return (id, fileType, title) => projection.lookupUsage(lookup, id, fileType, title)?.lastFired ?? null;
+    }
+    catch {
+        // Usage data is derived and optional. A failure here must never change what
+        // the agent is given.
+        return undefined;
+    }
+}
 function readFrontmatter(content) {
     const match = content.match(/^---\r?\n([\s\S]*?)\r?\n---/);
     if (!match)
@@ -488,16 +611,22 @@ function mergeLearningEntriesAcrossTiers(tiers) {
     }
     return [...byTitle.values()];
 }
-function buildLearningContextSection(workspaceRoot, userId, forJob, domain) {
-    const roots = getLearningRoots(workspaceRoot);
-    const resolvedUserId = resolveLearningUserId(workspaceRoot, userId, roots);
-    const threshold = getScoreThreshold(workspaceRoot);
-    const CAT = {
-        mistake: { ft: 'mistake-patterns', gated: true, label: '(entries above score threshold)' },
-        pref: { ft: 'preferences', gated: false, label: '(all entries)' },
-        coach: { ft: 'manager-coaching', gated: false, label: '(manager-facing; all entries)' },
-        validated: { ft: 'validated-patterns', gated: true, label: '(entries above score threshold)' },
-    };
+const CONTEXT_CATEGORIES = {
+    mistake: { ft: 'mistake-patterns', gated: true, label: '(entries above score threshold)' },
+    pref: { ft: 'preferences', gated: false, label: '(all entries)' },
+    coach: { ft: 'manager-coaching', gated: false, label: '(manager-facing; all entries)' },
+    validated: { ft: 'validated-patterns', gated: true, label: '(entries above score threshold)' },
+};
+/**
+ * Resolve exactly the files the injected context block lists, in the order it lists
+ * them.
+ *
+ * Extracted from `buildLearningContextSection` for issue #1103: the block renders
+ * these as text, and the offer recorder enumerates their entries. Both have to see
+ * the identical set, so there is one resolution and two consumers rather than two
+ * resolutions that can drift.
+ */
+function resolveContextLearningFiles(workspaceRoot, resolvedUserId, roots, forJob, domain) {
     // Domain axis (issue #806): session startup stays broad enough for stable
     // preferences plus L0, while job contexts load the full global set and may
     // append the current job's domain files below the global files.
@@ -507,69 +636,86 @@ function buildLearningContextSection(workspaceRoot, userId, forJob, domain) {
     const l2Cats = forJob ? jobL2Cats : sessionCats;
     const l1Cats = forJob ? jobL1Cats : sessionCats;
     const activeDomain = forJob && domain ? domain : null;
-    const dormantOf = (meta, filePath) => meta.gated ? scanMistakePatternFile(filePath, threshold, meta.ft).dormant : 0;
-    // Issue #1002 R4: same shape as resolveTier below, but a family may resolve to
-    // MORE THAN ONE file (one per level that holds it), so each is listed.
-    const resolveTierMulti = (cats, resolveFiles) => {
-        const global = [];
+    let multiTier = false;
+    let coachPresent = false;
+    // Issue #1002 R4: resolve every tier holding each family, not just the winner,
+    // so a promoted entry never hides the rest of its family. `multiTier` is true
+    // when at least one family exists at more than one level, which is when the
+    // collision rule needs stating.
+    const collect = (cats, tiersFor, fallbackLevel) => {
+        const globalFiles = [];
         const domainFiles = [];
-        let coachPresent = false;
-        for (const key of cats) {
-            const meta = CAT[key];
-            for (const g of resolveFiles(meta.ft)) {
-                global.push({ displayPath: g.displayPath, label: meta.label, dormant: dormantOf(meta, g.path), isCoach: key === 'coach' });
+        const push = (into, key, tiers) => {
+            if (tiers.length > 1)
+                multiTier = true;
+            const meta = CONTEXT_CATEGORIES[key];
+            for (const tier of tiers) {
+                into.push({
+                    path: tier.path,
+                    displayPath: tier.displayPath,
+                    fileType: meta.ft,
+                    gated: meta.gated,
+                    label: meta.label,
+                    isCoach: key === 'coach',
+                    level: tier.level ?? fallbackLevel,
+                });
                 if (key === 'coach')
                     coachPresent = true;
             }
-            if (activeDomain) {
-                for (const d of resolveFiles(meta.ft, activeDomain)) {
-                    domainFiles.push({ displayPath: d.displayPath, label: meta.label, dormant: dormantOf(meta, d.path), isCoach: key === 'coach' });
-                    if (key === 'coach')
-                        coachPresent = true;
-                }
-            }
-        }
-        return { global, domain: domainFiles, coachPresent };
-    };
-    // Resolve one tier (L2 org or L1 personal) into ordered global + domain files.
-    const resolveTier = (cats, resolveFile) => {
-        const global = [];
-        const domainFiles = [];
-        let coachPresent = false;
+        };
         for (const key of cats) {
-            const meta = CAT[key];
-            const g = resolveFile(meta.ft);
-            if (g.present) {
-                global.push({ displayPath: g.displayPath, label: meta.label, dormant: dormantOf(meta, g.path), isCoach: key === 'coach' });
-                if (key === 'coach')
-                    coachPresent = true;
-            }
-            if (activeDomain) {
-                const d = resolveFile(meta.ft, activeDomain);
-                if (d.present) {
-                    domainFiles.push({ displayPath: d.displayPath, label: meta.label, dormant: dormantOf(meta, d.path), isCoach: key === 'coach' });
-                    if (key === 'coach')
-                        coachPresent = true;
-                }
-            }
+            const meta = CONTEXT_CATEGORIES[key];
+            push(globalFiles, key, tiersFor(meta.ft));
+            if (activeDomain)
+                push(domainFiles, key, tiersFor(meta.ft, activeDomain));
         }
-        return { global, domain: domainFiles, coachPresent };
+        return [...globalFiles, ...domainFiles];
     };
-    // Issue #1002 R4: resolve every tier holding each family, not just the winner,
-    // so a promoted entry never hides the rest of its family. `multiTier` is true
-    // when at least one family exists at more than one level, which is when the
-    // collision rule needs stating.
-    let multiTier = false;
-    const resolveTiersFor = (tiersFor) => (ft, dom) => {
-        const tiers = tiersFor(ft, dom);
-        if (tiers.length > 1)
-            multiTier = true;
-        return tiers.map((t) => ({ present: true, path: t.path, displayPath: t.displayPath }));
-    };
-    const l2 = resolveTierMulti(l2Cats, resolveTiersFor((ft, dom) => resolveOrgLearningFileTiers(roots.repoLearningsBase, dom ? `org-${dom}-${ft}.md` : `org-${ft}.md`)));
-    const l1 = resolveTierMulti(l1Cats, resolveTiersFor((ft, dom) => resolvePersonalLearningFileTiers(roots.repoLearningsBase, roots.managerCacheBase, roots.managerCacheDisplayBase, roots.globalPersonalBase, roots.globalPersonalDisplayBase, dom ? `${resolvedUserId}-${dom}-${ft}.md` : `${resolvedUserId}-${ft}.md`)));
-    const l2Files = [...l2.global, ...l2.domain];
-    const l1Files = [...l1.global, ...l1.domain];
+    const l2 = collect(l2Cats, (ft, dom) => resolveOrgLearningFileTiers(roots.repoLearningsBase, dom ? `org-${dom}-${ft}.md` : `org-${ft}.md`), 'org');
+    const l1 = collect(l1Cats, (ft, dom) => resolvePersonalLearningFileTiers(roots.repoLearningsBase, roots.managerCacheBase, roots.managerCacheDisplayBase, roots.globalPersonalBase, roots.globalPersonalDisplayBase, dom ? `${resolvedUserId}-${dom}-${ft}.md` : `${resolvedUserId}-${ft}.md`), 'manager');
+    return { l2, l1, multiTier, coachPresent };
+}
+/**
+ * Report how many entries have been demoted, without naming the file they live in.
+ *
+ * Issue #861 keeps demoted entries out of the injected context, and #1103 keeps it
+ * that way after trying the alternative. Naming the `.cold.md` path here was
+ * considered and reverted: the path states a family (`…-mistake-patterns.cold.md`)
+ * and not a subject, so an instruction to "read it if this job touches its
+ * subject" is one the agent has no basis to follow. It degrades to reading the
+ * file every job, which is the token cost #861 removed, or never, which makes the
+ * line noise.
+ *
+ * Recovery for a demoted entry is a synthesis-time concern, not a runtime one.
+ * `sleep-on-learnings` reads both tiers when deciding whether a signal is a
+ * recurrence, so an entry that becomes relevant again is found, updated and
+ * promoted there. See that job's gather-signals and analyze phases.
+ */
+function renderDemotedLine(listed, label) {
+    const total = listed.reduce((sum, f) => sum + f.dormant, 0);
+    if (total === 0)
+        return '';
+    return total === 1
+        ? `Demoted: 1 ${label} pattern has gone quiet and is not listed above.\n`
+        : `Demoted: ${total} ${label} patterns have gone quiet and are not listed above.\n`;
+}
+function buildLearningContextSection(workspaceRoot, userId, forJob, domain) {
+    const roots = getLearningRoots(workspaceRoot);
+    const resolvedUserId = resolveLearningUserId(workspaceRoot, userId, roots);
+    const threshold = getScoreThreshold(workspaceRoot);
+    const usageClock = resolveUsageClock(workspaceRoot);
+    const resolved = resolveContextLearningFiles(workspaceRoot, resolvedUserId, roots, forJob, domain);
+    const multiTier = resolved.multiTier;
+    const toListed = (f) => ({
+        displayPath: f.displayPath,
+        label: f.label,
+        dormant: f.gated
+            ? scanMistakePatternFile(f.path, threshold, f.fileType, usageClock).dormant
+            : 0,
+        isCoach: f.isCoach,
+    });
+    const l2Files = resolved.l2.map(toListed);
+    const l1Files = resolved.l1.map(toListed);
     const pendingL0Sources = collectPendingL0SourceFiles(workspaceRoot, resolvedUserId, roots);
     const l0CoachingCount = pendingL0Sources.filter(source => source.kind === 'coaching-moment').length;
     const l0RetroCount = pendingL0Sources.filter(source => source.kind === 'retrospective').length;
@@ -585,20 +731,14 @@ function buildLearningContextSection(workspaceRoot, userId, forJob, domain) {
         section += '### L2 - Org patterns\n';
         for (const f of l2Files)
             section += `\`${f.displayPath}\`  ${f.label}\n`;
-        const l2DormantTotal = l2Files.reduce((sum, f) => sum + f.dormant, 0);
-        if (l2DormantTotal > 0) {
-            section += `Dormant: ${l2DormantTotal} org pattern${l2DormantTotal !== 1 ? 's' : ''} below threshold\n`;
-        }
+        section += renderDemotedLine(l2Files, 'org');
         section += '\n';
     }
     if (hasL1) {
         section += '### L1 - Your patterns\n';
         for (const f of l1Files)
             section += `\`${f.displayPath}\`  ${f.label}\n`;
-        const l1DormantTotal = l1Files.reduce((sum, f) => sum + f.dormant, 0);
-        if (l1DormantTotal > 0) {
-            section += `Dormant: ${l1DormantTotal} personal pattern${l1DormantTotal !== 1 ? 's' : ''} below threshold\n`;
-        }
+        section += renderDemotedLine(l1Files, 'personal');
         section += '\n';
     }
     if (l0CoachingCount > 0 || l0RetroCount > 0) {
@@ -620,7 +760,7 @@ function buildLearningContextSection(workspaceRoot, userId, forJob, domain) {
         }
         section += '\n';
     }
-    const coachPresent = l1.coachPresent || l2.coachPresent;
+    const coachPresent = resolved.coachPresent;
     if (forJob) {
         if (hasL2 || hasL1) {
             section += 'Read the listed synthesized learning files before continuing, then apply the relevant patterns and preferences in this job.\n';
@@ -643,6 +783,146 @@ function buildLearningContextSection(workspaceRoot, userId, forJob, domain) {
     }
     return section;
 }
+/** Enumerate one learning file's entries with their above-threshold state. */
+function enumerateFileEntries(file, threshold, usageClock, now) {
+    if (!(0, fs_1.existsSync)(file.path))
+        return [];
+    let content;
+    try {
+        content = (0, fs_1.readFileSync)(file.path, 'utf8');
+    }
+    catch {
+        return [];
+    }
+    const out = [];
+    const headingRe = learningEntryHeadingRegex();
+    let current = null;
+    const flush = () => {
+        if (!current)
+            return;
+        // A non-gated family (preferences, manager-coaching) is delivered whole, so
+        // every entry in it is active guidance. A gated family delivers only entries
+        // at or above threshold; the rest are the dormant rollup.
+        let aboveThreshold = true;
+        if (file.gated) {
+            if (current.lastSeen) {
+                const lastFired = usageClock ? usageClock(current.id, file.fileType, current.title) : null;
+                aboveThreshold = computeEffectiveScore(current.severity, current.lastSeen, current.recurrences, file.fileType, now, lastFired) >= threshold;
+            }
+            // No date metadata: parseLearningEntries treats that as fresh and injects it,
+            // so the offer record has to agree.
+        }
+        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),
+            family: 'learning',
+            id: current.id,
+            title: current.title,
+            fileType: file.fileType,
+            level: file.level,
+            displayPath: file.displayPath,
+            severity: current.severity,
+            aboveThreshold,
+        });
+        current = null;
+    };
+    for (const line of content.split(/\r?\n/)) {
+        const header = line.match(headingRe);
+        if (header) {
+            flush();
+            current = { severity: header[1], title: header[2].trim(), id: null, lastSeen: '', recurrences: 1 };
+            continue;
+        }
+        if (!current)
+            continue;
+        const trimmed = line.trim();
+        const idMatch = trimmed.match(LEARNING_ENTRY_ID_LINE);
+        if (idMatch) {
+            current.id = idMatch[1];
+            continue;
+        }
+        const lastSeenMatch = trimmed.match(/^\*\*Last seen\*\*:\s*(.+)/i);
+        if (lastSeenMatch) {
+            current.lastSeen = lastSeenMatch[1].trim();
+            continue;
+        }
+        const recurrenceMatch = trimmed.match(/^\*\*Recurrences\*\*:\s*(\d+)/i);
+        if (recurrenceMatch) {
+            current.recurrences = parseInt(recurrenceMatch[1], 10) || 1;
+        }
+    }
+    flush();
+    return out;
+}
+/**
+ * Issue #1103 R1 and R2: every learning entry the runtime just delivered.
+ *
+ * "Delivered" is file-level, because the injected block lists file paths rather
+ * than entry titles: an entry is offered when it sat inside a file the block
+ * 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.
+ */
+function collectOfferedLearningEntries(workspaceRoot, userId, forJob, domain) {
+    const roots = getLearningRoots(workspaceRoot);
+    const resolvedUserId = resolveLearningUserId(workspaceRoot, userId, roots);
+    const threshold = getScoreThreshold(workspaceRoot);
+    const usageClock = resolveUsageClock(workspaceRoot);
+    const now = new Date();
+    const resolved = resolveContextLearningFiles(workspaceRoot, resolvedUserId, roots, forJob, domain);
+    const byKey = new Map();
+    for (const file of [...resolved.l2, ...resolved.l1]) {
+        for (const entry of enumerateFileEntries(file, threshold, usageClock, now)) {
+            byKey.set(entry.key, entry);
+        }
+    }
+    return [...byKey.values()];
+}
+/**
+ * Issue #1103 R3: the auto-loaded Team Context rule files.
+ *
+ * These are the most influential instructions in the system and produce no usage
+ * signal today, because the agent reads them with its own file tool and the proxy
+ * never sees a `get_fraim_file` call for them. Recording the offer at composition
+ * time closes that gap. A rule is unconditional, so it is always above threshold.
+ */
+function collectOfferedRuleFiles(workspaceRoot, forJob) {
+    const resolved = resolveTeamContextFiles(workspaceRoot);
+    // The three rule files by name, not by path sniffing: these are the ones R3
+    // names, and the other Team Context files are context rather than instruction,
+    // so recording them as offered guidance would misreport what they are.
+    const ruleFiles = [
+        { presence: resolved.orgRules, level: 'org' },
+        { presence: resolved.managerRules, level: 'manager' },
+        { presence: resolved.projectRules, level: 'project' },
+    ];
+    const out = [];
+    for (const { presence, level } of ruleFiles) {
+        if (!presence.present || !presence.displayPath)
+            continue;
+        const displayPath = presence.displayPath.replace(/\\/g, '/');
+        out.push({
+            key: (0, learning_usage_store_1.ruleUsageKey)(displayPath),
+            family: 'rule',
+            id: null,
+            title: displayPath.split('/').pop() ?? displayPath,
+            fileType: 'rules',
+            level,
+            displayPath,
+            severity: null,
+            aboveThreshold: true,
+        });
+    }
+    // `forJob` is accepted so both injection points call this identically; the Team
+    // Context block lists the same rule files in either frame.
+    void forJob;
+    return out;
+}
 /**
  * Resolve an organization/manager-scope context file (issue #563 order, R3.1):
  *   1. repo-local override (`fraim/personalized-employee/…`) — wins when present
@@ -799,6 +1079,15 @@ const TEAM_CONTEXT_FILE_MAP = {
     projectRules: { relativePath: 'rules/project_rules.md', scope: 'project' },
     projectQa: { relativePath: 'context/project_qa.md', scope: 'project' }
 };
+/**
+ * The pack-relative paths of every Team Context file, which is the set an agent
+ * receives with nothing referencing it. Exported because `registry/scripts/fraim/`
+ * is standalone CommonJS and cannot import from here, so `instruction-hygiene.js`
+ * carries a copy; `scripts/validate-team-context-contract.ts` compares the two and
+ * fails the build if they diverge.
+ */
+exports.TEAM_CONTEXT_RELATIVE_PATHS = Object.values(TEAM_CONTEXT_FILE_MAP)
+    .map((entry) => entry.relativePath);
 function isTeamContextKey(value) {
     return typeof value === 'string' && Object.prototype.hasOwnProperty.call(TEAM_CONTEXT_FILE_MAP, value);
 }
@@ -1095,10 +1384,12 @@ const PENDING_KIND_LABEL = {
 };
 /** Filename infix that separates hot (.md) from cold-tier (.cold.md) learning files (#861). */
 const COLD_FILE_SUFFIX = '.cold';
+/** R11's "fired recently" window. */
+const FIRED_RECENT_DAYS = 30;
 // Parse `## [P-…] Title` entries out of a learning file WITH their effective
 // score + last-seen (unlike parseLearningEntries, which drops that bookkeeping
 // for the Hub text display). Used only by the brain-dot projection.
-function parseBrainLearningEntries(filePath, fileType) {
+function parseBrainLearningEntries(filePath, fileType, usage) {
     if (!(0, fs_1.existsSync)(filePath))
         return [];
     let content;
@@ -1115,14 +1406,17 @@ function parseBrainLearningEntries(filePath, fileType) {
     const flush = () => {
         if (!current)
             return;
+        const projected = usage ? usage(current.id, fileType, current.title) : undefined;
         const rawScore = current.lastSeen
-            ? computeEffectiveScore(current.severity, current.lastSeen, current.recurrences, fileType, now)
+            ? computeEffectiveScore(current.severity, current.lastSeen, current.recurrences, fileType, now, projected?.lastFired ?? null)
             : null;
         out.push({
             title: current.title,
             severity: current.severity,
             score: rawScore === null ? null : Math.round(rawScore * 10) / 10,
             lastSeen: current.lastSeen || null,
+            id: current.id,
+            ...(projected ?? {}),
         });
         current = null;
     };
@@ -1130,11 +1424,16 @@ function parseBrainLearningEntries(filePath, fileType) {
         const header = line.match(headingRe);
         if (header) {
             flush();
-            current = { severity: header[1], title: header[2].trim(), lastSeen: '', recurrences: 1 };
+            current = { severity: header[1], title: header[2].trim(), id: null, lastSeen: '', recurrences: 1 };
             continue;
         }
         if (!current)
             continue;
+        const idMatch = line.trim().match(LEARNING_ENTRY_ID_LINE);
+        if (idMatch) {
+            current.id = idMatch[1];
+            continue;
+        }
         const lastSeenMatch = line.match(/^\*\*Last seen\*\*:\s*(.+)/);
         if (lastSeenMatch) {
             current.lastSeen = lastSeenMatch[1].trim();
@@ -1148,6 +1447,46 @@ function parseBrainLearningEntries(filePath, fileType) {
     flush();
     return out;
 }
+/**
+ * Project the store into the shape the Brain overlay reads (R11). Returns
+ * undefined for an entry with no usage record, which is what keeps the detail
+ * panel from showing counts that were never measured.
+ */
+function resolveBrainUsageProjector() {
+    try {
+        const store = require('./learning-usage-store');
+        const projection = require('./learning-usage-projection');
+        const loaded = store.readUsageStore();
+        if (Object.keys(loaded.entries).length === 0)
+            return undefined;
+        const lookup = projection.buildUsageLookup(loaded);
+        const now = Date.now();
+        return (id, fileType, title) => {
+            const value = projection.lookupUsage(lookup, id, fileType, title);
+            if (!value)
+                return undefined;
+            let usageState;
+            if (value.lastFired) {
+                const ageDays = (now - new Date(value.lastFired).getTime()) / 86_400_000;
+                usageState = ageDays <= FIRED_RECENT_DAYS ? 'fired-recent' : 'fired-aging';
+            }
+            else {
+                usageState = 'never-fired';
+            }
+            return {
+                offered: value.offered,
+                fired: value.fired,
+                lastFired: value.lastFired,
+                firedUnder: value.firedUnder,
+                fireLog: value.log.map((l) => ({ date: l.date, outcome: l.outcome, job: l.job, note: l.note })),
+                usageState,
+            };
+        };
+    }
+    catch {
+        return undefined;
+    }
+}
 /**
  * Build the brain learning-dot projection (issue #833) for one user: pending L0
  * signals + processed L1 (personal) and L2 (org) learnings grouped by file type
@@ -1163,6 +1502,8 @@ function collectBrainLearningDots(workspaceRoot, userId) {
         fileName: s.displayPath.split('/').pop() || s.displayPath,
         displayPath: s.displayPath,
     }));
+    // Issue #1103 R11: one store read serves every dot in this projection.
+    const usageProjector = resolveBrainUsageProjector();
     const resolvePersonal = (fileName) => resolvePersonalLearningFile(roots.repoLearningsBase, roots.managerCacheBase, roots.managerCacheDisplayBase, roots.globalPersonalBase, roots.globalPersonalDisplayBase, fileName);
     const processed = [];
     const fileTypes = ['mistake-patterns', 'preferences', 'validated-patterns', 'manager-coaching'];
@@ -1171,14 +1512,14 @@ function collectBrainLearningDots(workspaceRoot, userId) {
         const typeLabel = BRAIN_LEARNING_FILETYPE_LABEL[fileType];
         // L1 personal (hot file)
         const personal = resolvePersonal(`${resolvedUserId}-${fileType}.md`);
-        const personalEntries = parseBrainLearningEntries(personal.path, fileType);
+        const personalEntries = parseBrainLearningEntries(personal.path, fileType, usageProjector);
         if (personalEntries.length) {
             processed.push({ type: fileType, typeLabel, region, scope: 'personal', displayPath: personal.displayPath, entries: personalEntries });
         }
         // L1 cold sibling — only emitted when the .cold.md file exists alongside the hot file
         const coldFileName = `${resolvedUserId}-${fileType}${COLD_FILE_SUFFIX}.md`;
         const coldResolved = resolvePersonal(coldFileName);
-        const coldEntries = parseBrainLearningEntries(coldResolved.path, fileType);
+        const coldEntries = parseBrainLearningEntries(coldResolved.path, fileType, usageProjector);
         if (coldEntries.length) {
             processed.push({ type: fileType, typeLabel, region, scope: 'cold', displayPath: coldResolved.displayPath, entries: coldEntries });
         }
@@ -1187,7 +1528,7 @@ function collectBrainLearningDots(workspaceRoot, userId) {
         const orgTiers = resolveOrgLearningFileTiers(roots.repoLearningsBase, `org-${fileType}.md`);
         if (orgTiers.length > 0) {
             // Merge entries across tiers; deduplicate by title (last tier wins = repo-local wins).
-            const allOrgEntries = orgTiers.flatMap(t => parseBrainLearningEntries(t.path, fileType));
+            const allOrgEntries = orgTiers.flatMap(t => parseBrainLearningEntries(t.path, fileType, usageProjector));
             const byTitle = new Map();
             for (const e of allOrgEntries)
                 byTitle.set(e.title.trim().toLowerCase(), e);
@@ -1236,7 +1577,7 @@ function listDomainLearningFiles(dir, prefix, fileType) {
 // threshold: entries with score >= threshold (or in a non-gated category) are
 //   marked injected:true. Callers that don't need scoring pass Infinity so
 //   all entries are injected.
-function parseLearningEntries(filePath, displayPath, category, level, domain = 'global', tier, threshold = DEFAULT_THRESHOLD) {
+function parseLearningEntries(filePath, displayPath, category, level, domain = 'global', tier, threshold = exports.DEFAULT_THRESHOLD, usageClock) {
     if (!(0, fs_1.existsSync)(filePath))
         return [];
     let content;
@@ -1260,7 +1601,8 @@ function parseLearningEntries(filePath, displayPath, category, level, domain = '
             current.body = bodyLines.join('\n').replace(/\n{3,}/g, '\n\n').trim();
             if (isScoreGated) {
                 if (curLastSeen !== null) {
-                    const s = computeEffectiveScore(current.severity, curLastSeen, curRecurrences, fileType);
+                    const lastFired = usageClock ? usageClock(current.id, fileType, current.title) : null;
+                    const s = computeEffectiveScore(current.severity, curLastSeen, curRecurrences, fileType, new Date(), lastFired);
                     current.score = s;
                     current.injected = s >= threshold;
                 }
@@ -1289,6 +1631,7 @@ function parseLearningEntries(filePath, displayPath, category, level, domain = '
             const entry = {
                 severity: header[1],
                 title: header[2].trim(),
+                id: null,
                 body: '', source: displayPath, category, level, domain,
                 score: null, injected: true,
             };
@@ -1305,6 +1648,11 @@ function parseLearningEntries(filePath, displayPath, category, level, domain = '
         }
         const t = line.trim();
         // Capture scoring metadata but exclude from body.
+        const idMatch = t.match(LEARNING_ENTRY_ID_LINE);
+        if (idMatch) {
+            current.id = idMatch[1];
+            continue;
+        }
         const lastSeenMatch = t.match(/^\*\*Last seen\*\*:\s*(.+)/i);
         if (lastSeenMatch) {
             curLastSeen = lastSeenMatch[1].trim();
@@ -1315,7 +1663,9 @@ function parseLearningEntries(filePath, displayPath, category, level, domain = '
             curRecurrences = parseInt(recurrencesMatch[1], 10) || 1;
             continue;
         }
-        if (/^\*\*(Score|Technical trace|Users|First synthesized)\*\*:/i.test(t))
+        // `Id` is listed here as well as matched above so a malformed id line is still
+        // treated as bookkeeping rather than leaking into the displayed lesson.
+        if (/^\*\*(Id|Score|Technical trace|Users|First synthesized)\*\*:/i.test(t))
             continue;
         if (/^(First|Last) synthesized:/i.test(t))
             continue;
@@ -1327,12 +1677,15 @@ function parseLearningEntries(filePath, displayPath, category, level, domain = '
 function readPreservedLearnings(workspaceRoot, userId, scope, level = 'machine') {
     const roots = getLearningRoots(workspaceRoot);
     const threshold = getScoreThreshold(workspaceRoot);
+    // Issue #1103 R8: the Hub's injected flag must agree with the loader's, so both
+    // read the same clock. One store read serves the whole call.
+    const usageClock = resolveUsageClock(workspaceRoot);
     const out = [];
     // Helper: parse + merge a list of tier paths for one file family.
     // ResolvedLearningTier uses 'manager' to mean machine-level personal; map it to 'machine'.
     const tierLevel = (t) => t.level === 'manager' ? 'machine' : t.level;
     const parseTiers = (tiers, cat, tierVal, domainVal) => mergeLearningEntriesAcrossTiers(tiers.map((t) => ({
-        entries: parseLearningEntries(t.path, t.displayPath, cat, tierLevel(t), domainVal ?? 'global', tierVal, threshold),
+        entries: parseLearningEntries(t.path, t.displayPath, cat, tierLevel(t), domainVal ?? 'global', tierVal, threshold, usageClock),
     })));
     if (scope === 'org') {
         for (const cat of ['avoid', 'preference', 'repeat', 'coaching']) {