fraim 2.0.342 → 2.0.344

package/dist/src/local-mcp-server/artifact-retention-cleanup.js

@@ -12,6 +12,10 @@ const node_crypto_1 = __importDefault(require("node:crypto"));
 const node_child_process_1 = require("node:child_process");
 const node_path_1 = __importDefault(require("node:path"));
 const project_fraim_paths_1 = require("../core/utils/project-fraim-paths");
+const learning_source_record_1 = require("./learning-source-record");
+const artifact_paths_1 = require("../../registry/scripts/artifact-paths");
+const completion_state_1 = require("../../registry/scripts/learning/completion-state");
+const pack_home_1 = require("../cli/utils/pack-home");
 exports.ARTIFACT_RETENTION_CATEGORIES = [
     'learning_archive',
     'retrospectives',
@@ -191,6 +195,40 @@ function evidenceEligibilityDate(workspaceRoot, absolutePath, gitDates) {
     const relativePath = normalizeRelative(workspaceRoot, absolutePath);
     return gitDates.get(relativePath) ?? fileMtime(absolutePath);
 }
+/** Only typed future evidence opts into the combined retention contract. */
+function evidenceMarker(body) {
+    const header = body.match(/^(?:\uFEFF)?---\r?\n([\s\S]*?)\r?\n---(?:\r?\n|$)/);
+    const fields = header?.[1] ?? body;
+    if (!/^\s*["']?artifactKind["']?\s*:/m.test(fields))
+        return { typed: false, valid: false };
+    // Unsupported spellings still participate in ambiguity detection. Otherwise
+    // a quoted or indented second key could silently shorten feedback retention.
+    const kindKeys = [...fields.matchAll(/^[ \t]*["']?artifactKind["']?[ \t]*:/gm)];
+    const feedbackKeys = [...fields.matchAll(/^[ \t]*["']?containsFeedback["']?[ \t]*:/gm)];
+    const kinds = [...fields.matchAll(/^artifactKind:[ \t]*([^\r\n]*)/gm)];
+    const feedback = [...fields.matchAll(/^containsFeedback:[ \t]*([^\r\n]*)/gm)];
+    const valid = !!header && kindKeys.length === 1 && feedbackKeys.length === 1
+        && kinds.length === 1 && kinds[0][1].trim() === 'work-evidence'
+        && feedback.length === 1 && /^(true|false)$/.test(feedback[0][1].trim());
+    return { typed: true, valid, ...(valid ? { feedback: feedback[0][1].trim() === 'true' } : {}) };
+}
+const recordHash = (body) => node_crypto_1.default.createHash('sha256').update(body).digest('hex');
+const pathKey = (file) => process.platform === 'win32' ? node_path_1.default.resolve(file).toLowerCase() : node_path_1.default.resolve(file);
+function reservedSources(workspaceRoot) {
+    // A Manager run can reserve an input owned by this project. These reads only
+    // protect exact paths; they never apply this workspace's policy to other homes.
+    const content = contentRoot(workspaceRoot);
+    const packs = [(0, pack_home_1.resolvePackHome)('manager', { migrateLegacy: false }), (0, pack_home_1.resolvePackHome)('org', { migrateLegacy: false })];
+    const homes = [{ root: workspaceRoot, contentRoot: content }, { root: node_path_1.default.dirname(content), contentRoot: content }, ...packs];
+    return new Set((0, completion_state_1.readSourceReservations)(homes.map(home => (0, artifact_paths_1.resolveRunJournalDirectory)(home.root))).map(pathKey));
+}
+function matchesConfiguredLocation(workspaceRoot, candidate) {
+    const content = contentRoot(workspaceRoot);
+    const paths = (0, artifact_paths_1.resolveArtifactPaths)(workspaceRoot, content);
+    const directory = candidate.category === 'evidence' ? paths.evidence : node_path_1.default.dirname(paths.archiveRaw);
+    const relative = node_path_1.default.relative(directory, candidate.absolutePath);
+    return candidate.configuredDirectory === pathKey(directory) && Boolean(relative) && relative !== '..' && !relative.startsWith('..' + node_path_1.default.sep) && !node_path_1.default.isAbsolute(relative);
+}
 function collectCandidates(workspaceRoot, options) {
     const { activeUserEmail } = options;
     const candidates = [];
@@ -205,12 +243,28 @@ function collectCandidates(workspaceRoot, options) {
         });
     };
     const content = contentRoot(workspaceRoot);
-    const archiveDir = node_path_1.default.join(content, 'learnings', 'archive');
+    const reserved = reservedSources(workspaceRoot);
+    const artifactPaths = (0, artifact_paths_1.resolveArtifactPaths)(workspaceRoot, content);
+    const archiveDir = node_path_1.default.dirname(artifactPaths.archiveRaw);
     for (const filePath of listFiles(archiveDir)) {
         const fileName = node_path_1.default.basename(filePath);
-        if (!fileName.endsWith('.md') || !userScoped(filePath, activeUserEmail))
+        if (!fileName.endsWith('.md'))
+            continue;
+        const body = node_fs_1.default.readFileSync(filePath, 'utf8');
+        const parsed = (0, learning_source_record_1.parseLearningSourceRecord)(body, filePath, workspaceRoot, content, artifactPaths);
+        if (parsed.status === 'valid' && parsed.record.author !== activeUserEmail)
             continue;
-        add('learning_archive', filePath, true, 'Archived learning source for active user.', fileMtime(filePath));
+        if (parsed.status === 'unsupported' && !userScoped(filePath, activeUserEmail))
+            continue;
+        const newArchive = /^(raw|retrospectives)\//.test(node_path_1.default.relative(archiveDir, filePath).replace(/\\/g, '/'));
+        if (parsed.status !== 'unsupported' || newArchive) {
+            const valid = parsed.status === 'valid' && parsed.record.state === 'archived';
+            add('learning_archive', filePath, valid && !reserved.has(pathKey(filePath)), reserved.has(pathKey(filePath)) ? 'Learning source reserved by unfinished synthesis.'
+                : valid ? 'Learning archive dated by successful processing.' : 'Invalid new learning archive metadata; retained.', valid ? parseDate(parsed.record.synthesized || undefined) : undefined);
+            Object.assign(candidates[candidates.length - 1], { recordHash: recordHash(body), configuredDirectory: pathKey(archiveDir) });
+        }
+        else
+            add('learning_archive', filePath, !reserved.has(pathKey(filePath)), 'Archived learning source for active user.', fileMtime(filePath));
     }
     const retrospectives = new Set([
         node_path_1.default.join(workspaceRoot, 'docs', 'retrospectives'),
@@ -227,8 +281,8 @@ function collectCandidates(workspaceRoot, options) {
         else
             add('retrospectives', filePath, false, 'Retrospective has no synthesized frontmatter.');
     }
-    const evidenceDir = node_path_1.default.join(workspaceRoot, 'docs', 'evidence');
-    const evidenceGitDates = loadGitLastChangeDates(workspaceRoot, 'docs/evidence');
+    const evidenceDir = artifactPaths.evidence;
+    const evidenceGitDates = loadGitLastChangeDates(workspaceRoot, node_path_1.default.relative(workspaceRoot, evidenceDir).replace(/\\/g, '/'));
     for (const filePath of listFiles(evidenceDir)) {
         const fileName = node_path_1.default.basename(filePath);
         // A surviving run journal is unfinished recovery; completion removes it.
@@ -239,6 +293,17 @@ function collectCandidates(workspaceRoot, options) {
         const isMarkdown = fileName.endsWith('.md');
         const isJson = fileName.endsWith('.json');
         const eligibilityDate = evidenceEligibilityDate(workspaceRoot, filePath, evidenceGitDates);
+        if (isMarkdown) {
+            const body = node_fs_1.default.readFileSync(filePath, 'utf8');
+            const marker = evidenceMarker(body);
+            if (marker.typed) {
+                const mtime = fileMtime(filePath);
+                const latest = eligibilityDate && mtime ? new Date(Math.max(eligibilityDate.getTime(), mtime.getTime())) : eligibilityDate ?? mtime;
+                add('evidence', filePath, marker.valid, marker.valid ? 'Typed work evidence.' : 'Ambiguous new evidence classification; retained.', latest);
+                Object.assign(candidates[candidates.length - 1], { containsFeedback: marker.feedback, recordHash: recordHash(body), configuredDirectory: pathKey(evidenceDir) });
+                continue;
+            }
+        }
         if (fileName.includes('cleanup-manifest') || fileName.includes('cleanup_manifest')) {
             if (isMarkdown || isJson) {
                 add('cleanup_manifests', filePath, true, 'Cleanup manifest file.', eligibilityDate);
@@ -368,7 +433,10 @@ function runArtifactCleanup(workspaceRoot, options) {
         items: [],
     };
     for (const candidate of candidates) {
-        const retentionValue = retention.values[candidate.category];
+        const categoryValue = retention.values[candidate.category];
+        const retentionValue = candidate.containsFeedback
+            ? categoryValue === -1 || retention.values.feedback === -1 ? -1 : Math.max(categoryValue, retention.values.feedback)
+            : categoryValue;
         let decision = shouldDelete(candidate, retentionValue, now);
         let action;
         let error;
@@ -383,6 +451,11 @@ function runArtifactCleanup(workspaceRoot, options) {
         }
         else {
             try {
+                if (candidate.recordHash && (!matchesConfiguredLocation(workspaceRoot, candidate) || !isConfinedRegularFile(workspaceRoot, candidate.absolutePath)
+                    || recordHash(node_fs_1.default.readFileSync(candidate.absolutePath, 'utf8')) !== candidate.recordHash
+                    || reservedSources(workspaceRoot).has(pathKey(candidate.absolutePath)))) {
+                    decision = { delete: false, reason: 'Record changed or reserved after enumeration; retained for a later cleanup.' };
+                }
                 if (candidate.category === 'hub_event_logs' && candidate.hubArchive) {
                     const prior = candidate.hubArchive;
                     const current = readHubArchiveState(prior.root, candidate.absolutePath);

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

@@ -1,10 +1,4 @@
 "use strict";
-/**
- * LearningContextBuilder builds the learning context section for a user.
- *
- * Lives in the local proxy so learning files are always read from the correct
- * workspace root on the user's machine.
- */
 Object.defineProperty(exports, "__esModule", { value: true });
 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;
@@ -12,6 +6,8 @@ exports.learningEntryIdLineRegex = learningEntryIdLineRegex;
 exports.generateLearningEntryId = generateLearningEntryId;
 exports.getScoreThreshold = getScoreThreshold;
 exports.computeEffectiveScore = computeEffectiveScore;
+exports.getLearningInputHomes = getLearningInputHomes;
+exports.readLearningSourceFile = readLearningSourceFile;
 exports.mergeLearningEntriesAcrossTiers = mergeLearningEntriesAcrossTiers;
 exports.buildLearningContextSection = buildLearningContextSection;
 exports.collectOfferedLearningEntries = collectOfferedLearningEntries;
@@ -29,9 +25,18 @@ exports.readPreservedLearnings = readPreservedLearnings;
 exports.normalizeLearningDomain = normalizeLearningDomain;
 exports.applyLearningEntryChange = applyLearningEntryChange;
 exports.isTruthyFlag = isTruthyFlag;
+const artifact_paths_1 = require("../../registry/scripts/artifact-paths");
+/**
+ * LearningContextBuilder builds the learning context section for a user.
+ *
+ * Lives in the local proxy so learning files are always read from the correct
+ * workspace root on the user's machine.
+ */
 const fs_1 = require("fs");
 const crypto_1 = require("crypto");
 const path_1 = require("path");
+const learning_source_record_1 = require("./learning-source-record");
+const completion_state_1 = require("../../registry/scripts/learning/completion-state");
 const project_fraim_paths_1 = require("../core/utils/project-fraim-paths");
 const brand_store_1 = require("../core/brand-store");
 // Issue #1043 round 2: org and manager content lives at one home named by
@@ -111,14 +116,14 @@ function generateLearningEntryId(fileType, title) {
  * therefore contributes no tier, matching the behavior before round 2.
  */
 function managerSecondaryLearningsBase() {
-    const home = (0, pack_home_1.resolvePackHome)('manager');
+    const home = (0, pack_home_1.resolvePackHome)('manager', { migrateLegacy: false });
     if (home.synced)
         return (0, path_1.join)(home.contentRoot, 'learnings');
     // pack-home-exempt: deliberate historical secondary location, see above.
     return (0, path_1.join)((0, project_fraim_paths_1.getUserFraimDirPath)(), 'manager', 'learnings');
 }
 function getLearningRoots(workspaceRoot) {
-    const managerHome = (0, pack_home_1.resolvePackHome)('manager');
+    const managerHome = (0, pack_home_1.resolvePackHome)('manager', { migrateLegacy: false });
     const managerHomeBase = (0, path_1.join)(managerHome.contentRoot, 'learnings');
     const managerCacheBase = managerSecondaryLearningsBase();
     // Derive the display base from the actual cache path relative to ~/.fraim so
@@ -141,7 +146,7 @@ function sameResolvedPath(a, b) {
     return (0, path_1.resolve)(a) === (0, path_1.resolve)(b);
 }
 function portablePersonalBaseIsLive(globalBase) {
-    return sameResolvedPath((0, path_1.join)((0, pack_home_1.resolvePackHome)('manager').contentRoot, 'learnings'), globalBase)
+    return sameResolvedPath((0, path_1.join)((0, pack_home_1.resolvePackHome)('manager', { migrateLegacy: false }).contentRoot, 'learnings'), globalBase)
         || !sameResolvedPath(globalBase, (0, project_fraim_paths_1.getUserFraimLearningsDir)());
 }
 function resolvePersonalLearningFile(repoBase, managerCacheBase, managerCacheDisplayBase, globalBase, globalDisplayBase, fileName) {
@@ -272,16 +277,6 @@ function buildUserIdCandidates(userId) {
         candidates.add(trimmed.slice(0, atIndex));
     return Array.from(candidates).filter(isPathSafeUserIdCandidate);
 }
-function countMatchingFilesByPrefix(dirPath, matcher) {
-    if (!(0, fs_1.existsSync)(dirPath))
-        return 0;
-    try {
-        return (0, fs_1.readdirSync)(dirPath).filter(matcher).length;
-    }
-    catch {
-        return 0;
-    }
-}
 function resolveLearningUserId(workspaceRoot, userId, roots) {
     const candidates = buildUserIdCandidates(userId);
     // Issue #754: falling back to the raw `userId` here would route every rejected
@@ -305,8 +300,7 @@ function resolveLearningUserId(workspaceRoot, userId, roots) {
             ((0, fs_1.existsSync)((0, path_1.join)(roots.repoLearningsBase, `${candidate}-manager-coaching.md`)) ? 1 : 0) +
             ((0, fs_1.existsSync)((0, path_1.join)(roots.repoLearningsBase, `${candidate}-mistake-patterns.md`)) ? 1 : 0) +
             ((0, fs_1.existsSync)((0, path_1.join)(roots.repoLearningsBase, `${candidate}-validated-patterns.md`)) ? 1 : 0) +
-            countMatchingFilesByPrefix((0, path_1.join)(roots.repoLearningsBase, 'raw'), (fileName) => fileName.startsWith(`${candidate}-`)) +
-            countMatchingFilesByPrefix((0, path_1.join)(workspaceRoot, 'docs', 'retrospectives'), (fileName) => fileName.startsWith(`${candidate}-`) && fileName.endsWith('.md'));
+            collectPendingL0SourceFiles(workspaceRoot, candidate, roots).length;
         if (score > bestScore) {
             bestCandidate = candidate;
             bestScore = score;
@@ -558,28 +552,6 @@ function readFrontmatter(content) {
     }
     return frontmatter;
 }
-function isRetrospectiveSynthesized(value) {
-    if (value === undefined)
-        return false;
-    const normalized = value.trim().toLowerCase();
-    if (!normalized)
-        return false;
-    return normalized !== 'false' && normalized !== 'no' && normalized !== '0' && normalized !== 'null';
-}
-function isUnsynthesizedRetrospective(filePath) {
-    try {
-        const content = (0, fs_1.readFileSync)(filePath, 'utf8');
-        const frontmatter = readFrontmatter(content);
-        return !isRetrospectiveSynthesized(frontmatter.synthesized);
-    }
-    catch {
-        return false;
-    }
-}
-function pendingL0SortKey(fileName) {
-    const timestamp = fileName.match(/\d{4}-\d{2}-\d{2}(?:T\d{2}-\d{2}-\d{2})?/);
-    return timestamp?.[0] || fileName;
-}
 /**
  * Issue #1857 R11: how many proposals are waiting for the manager's review.
  *
@@ -608,42 +580,82 @@ function countPendingProposals(roots, resolvedUserId) {
     }
     return total;
 }
-function collectPendingL0SourceFiles(workspaceRoot, resolvedUserId, roots) {
+/** Configured owning homes only; discovery never provisions or infers a home. */
+function getLearningInputHomes(workspaceRoot) {
+    const homes = [{ root: workspaceRoot, contentRoot: (0, path_1.dirname)((0, project_fraim_paths_1.getWorkspaceLearningsDir)(workspaceRoot)) },
+        (0, pack_home_1.resolvePackHome)('manager', { migrateLegacy: false }), (0, pack_home_1.resolvePackHome)('org', { migrateLegacy: false })];
+    const seen = new Set();
+    return homes.filter(home => {
+        const key = (0, learning_source_record_1.normalizeLearningSourcePath)(home.root) + ':' + (0, learning_source_record_1.normalizeLearningSourcePath)(home.contentRoot);
+        if (seen.has(key))
+            return false;
+        seen.add(key);
+        return true;
+    });
+}
+/** Guard the physical owner boundary before reading any input bytes. */
+function readLearningSourceFile(filePath, homeRoot, contentRoot) {
+    try {
+        if (!(0, fs_1.lstatSync)(filePath).isFile() || (0, fs_1.lstatSync)(filePath).isSymbolicLink()) {
+            return { status: 'invalid', reason: 'Learning source must be a regular file' };
+        }
+        const rel = (0, path_1.relative)((0, fs_1.realpathSync)(homeRoot), (0, fs_1.realpathSync)(filePath));
+        if (rel === '..' || rel.startsWith('..' + path_1.sep) || (0, path_1.isAbsolute)(rel)) {
+            return { status: 'invalid', reason: 'Learning source escapes configured home' };
+        }
+        const content = (0, fs_1.readFileSync)(filePath, 'utf8');
+        return { ...(0, learning_source_record_1.parseLearningSourceRecord)(content, filePath, homeRoot, contentRoot), content };
+    }
+    catch {
+        return { status: 'invalid', reason: 'Learning source unavailable' };
+    }
+}
+function collectPendingL0SourceFiles(workspaceRoot, resolvedUserId, _roots) {
+    if (!resolvedUserId)
+        return [];
     const sources = [];
-    const rawPath = (0, path_1.join)(roots.repoLearningsBase, 'raw');
-    if ((0, fs_1.existsSync)(rawPath)) {
+    const homes = getLearningInputHomes(workspaceRoot);
+    let reservations;
+    try {
+        reservations = new Set((0, completion_state_1.readSourceReservations)(homes.flatMap(home => {
+            const roots = home.root === workspaceRoot ? [home.root, (0, path_1.dirname)(home.contentRoot)] : [home.root];
+            return roots.map(root => (0, artifact_paths_1.resolveRunJournalDirectory)(root));
+        })));
+    }
+    catch {
+        return [];
+    }
+    for (const home of homes) {
+        let paths;
         try {
-            for (const fileName of (0, fs_1.readdirSync)(rawPath)) {
-                if (!fileName.startsWith(`${resolvedUserId}-`))
-                    continue;
-                sources.push({
-                    kind: 'coaching-moment',
-                    displayPath: `${REPO_LEARNINGS_REL}/raw/${fileName}`,
-                    sortKey: pendingL0SortKey(fileName)
-                });
-            }
+            paths = (0, artifact_paths_1.resolveLearningPaths)(home.root, home.contentRoot);
         }
         catch {
-            // Ignore read failures.
+            continue;
         }
-    }
-    const retrospectivesPath = (0, path_1.join)(workspaceRoot, 'docs', 'retrospectives');
-    if ((0, fs_1.existsSync)(retrospectivesPath)) {
-        try {
-            for (const fileName of (0, fs_1.readdirSync)(retrospectivesPath)) {
-                if (!fileName.startsWith(`${resolvedUserId}-`) || !fileName.endsWith('.md'))
-                    continue;
-                if (!isUnsynthesizedRetrospective((0, path_1.join)(retrospectivesPath, fileName)))
+        for (const directory of [paths.raw, paths.retrospectives]) {
+            try {
+                if ((0, fs_1.lstatSync)(directory).isSymbolicLink())
                     continue;
-                sources.push({
-                    kind: 'retrospective',
-                    displayPath: `docs/retrospectives/${fileName}`,
-                    sortKey: pendingL0SortKey(fileName)
-                });
+                for (const name of (0, fs_1.readdirSync)(directory)) {
+                    if (!name.endsWith('.md'))
+                        continue;
+                    const file = (0, path_1.join)(directory, name);
+                    if (reservations.has((0, learning_source_record_1.normalizeLearningSourcePath)(file)))
+                        continue;
+                    const result = readLearningSourceFile(file, home.root, home.contentRoot);
+                    if (result.status !== 'valid' || result.record.author !== resolvedUserId
+                        || result.record.state !== 'pending' || result.record.synthesized
+                        || isTruthyFlag(readFrontmatter(result.content).dismissed))
+                        continue;
+                    sources.push({
+                        kind: result.record.kind === 'raw' ? 'coaching-moment' : 'retrospective',
+                        displayPath: (0, path_1.resolve)(file).replace(/\\/g, '/'),
+                        sortKey: result.record.date,
+                    });
+                }
             }
-        }
-        catch {
-            // Ignore read failures.
+            catch { /* Missing or unavailable homes do not block startup. */ }
         }
     }
     return sources.sort((a, b) => b.sortKey.localeCompare(a.sortKey) || a.displayPath.localeCompare(b.displayPath));
@@ -656,7 +668,7 @@ function collectPendingL0SourceFiles(workspaceRoot, resolvedUserId, roots) {
  * it cannot drift from the read path again.
  */
 function orgCacheDisplayPath(fileName) {
-    const cachePath = (0, path_1.join)((0, pack_home_1.resolvePackHome)('org').contentRoot, 'learnings', fileName);
+    const cachePath = (0, path_1.join)((0, pack_home_1.resolvePackHome)('org', { migrateLegacy: false }).contentRoot, 'learnings', fileName);
     return userFraimDisplayPathFor(cachePath);
 }
 function userFraimDisplayPathFor(absolutePath) {
@@ -679,7 +691,7 @@ function resolveOrgLearningFile(repoLearningsBase, fileName) {
     if ((0, fs_1.existsSync)(repoPath)) {
         return { present: true, path: repoPath, displayPath: `${REPO_LEARNINGS_REL}/${fileName}` };
     }
-    const cachePath = (0, path_1.join)((0, pack_home_1.resolvePackHome)('org').contentRoot, 'learnings', fileName);
+    const cachePath = (0, path_1.join)((0, pack_home_1.resolvePackHome)('org', { migrateLegacy: false }).contentRoot, 'learnings', fileName);
     if ((0, fs_1.existsSync)(cachePath)) {
         return { present: true, path: cachePath, displayPath: orgCacheDisplayPath(fileName) };
     }
@@ -692,7 +704,7 @@ function resolveOrgLearningFile(repoLearningsBase, fileName) {
  */
 function resolveOrgLearningFileTiers(repoLearningsBase, fileName) {
     const tiers = [];
-    const cachePath = (0, path_1.join)((0, pack_home_1.resolvePackHome)('org').contentRoot, 'learnings', fileName);
+    const cachePath = (0, path_1.join)((0, pack_home_1.resolvePackHome)('org', { migrateLegacy: false }).contentRoot, 'learnings', fileName);
     if ((0, fs_1.existsSync)(cachePath)) {
         tiers.push({
             level: 'org',
@@ -847,7 +859,7 @@ function buildLearningContextSection(workspaceRoot, userId, forJob, domain) {
     });
     const l2Files = resolved.l2.map(toListed);
     const l1Files = resolved.l1.map(toListed);
-    const pendingL0Sources = collectPendingL0SourceFiles(workspaceRoot, resolvedUserId, roots);
+    const pendingL0Sources = collectPendingL0SourceFiles(workspaceRoot, userId.trim(), roots);
     const l0CoachingCount = pendingL0Sources.filter(source => source.kind === 'coaching-moment').length;
     const l0RetroCount = pendingL0Sources.filter(source => source.kind === 'retrospective').length;
     const hasL2 = l2Files.length > 0;
@@ -880,10 +892,10 @@ function buildLearningContextSection(workspaceRoot, userId, forJob, domain) {
         const totalL0 = pendingL0Sources.length;
         section += '### L0 - Your unprocessed signals\n';
         if (l0CoachingCount > 0) {
-            section += `${l0CoachingCount} coaching moment${l0CoachingCount !== 1 ? 's' : ''} in \`${REPO_LEARNINGS_REL}/raw/${resolvedUserId}-*\`\n`;
+            section += `${l0CoachingCount} coaching moment${l0CoachingCount !== 1 ? 's' : ''} across configured learning homes\n`;
         }
         if (l0RetroCount > 0) {
-            section += `${l0RetroCount} retrospective${l0RetroCount !== 1 ? 's' : ''} in \`docs/retrospectives/${resolvedUserId}-*\` with unsynthesized or missing \`synthesized\` frontmatter\n`;
+            section += `${l0RetroCount} retrospective${l0RetroCount !== 1 ? 's' : ''} across configured learning homes awaiting synthesis\n`;
         }
         section += 'Pending L0 Source Files:\n';
         for (const source of pendingL0Sources) {
@@ -1123,7 +1135,7 @@ function resolveOrgContextFile(workspaceRoot, relativePath, orgCacheEligible = t
             };
         }
         if (orgCacheEligible) {
-            const cachePath = (0, path_1.join)((0, pack_home_1.resolvePackHome)('org').contentRoot, relativePath);
+            const cachePath = (0, path_1.join)((0, pack_home_1.resolvePackHome)('org', { migrateLegacy: false }).contentRoot, relativePath);
             if ((0, fs_1.existsSync)(cachePath)) {
                 return {
                     present: true,
@@ -1132,7 +1144,7 @@ function resolveOrgContextFile(workspaceRoot, relativePath, orgCacheEligible = t
             }
         }
         if (!orgCacheEligible) {
-            const managerHome = (0, pack_home_1.resolvePackHome)('manager');
+            const managerHome = (0, pack_home_1.resolvePackHome)('manager', { migrateLegacy: false });
             const managerCachePath = (0, path_1.join)(managerHome.contentRoot, relativePath);
             if ((0, fs_1.existsSync)(managerCachePath)) {
                 // Derive the display path relative to ~/.fraim. For the standard
@@ -1312,7 +1324,7 @@ function resolveTeamContextFile(workspaceRoot, key, options = {}) {
     // destination (R5.1), so writePath stays empty and the caller must route
     // edits through the org backend's propose-and-approve flow.
     if (key === 'org' || key === 'orgRules') {
-        const cachePath = (0, path_1.join)((0, pack_home_1.resolvePackHome)('org', options).contentRoot, relativePath);
+        const cachePath = (0, path_1.join)((0, pack_home_1.resolvePackHome)('org', { migrateLegacy: false, ...options }).contentRoot, relativePath);
         if ((0, fs_1.existsSync)(cachePath)) {
             const fraimDir = (0, project_fraim_paths_1.getUserFraimDirPath)();
             const orgDisplayPath = cachePath.startsWith(fraimDir)
@@ -1329,7 +1341,7 @@ function resolveTeamContextFile(workspaceRoot, key, options = {}) {
         }
     }
     if (key === 'manager' || key === 'managerRules') {
-        const managerHome = (0, pack_home_1.resolvePackHome)('manager', options);
+        const managerHome = (0, pack_home_1.resolvePackHome)('manager', { migrateLegacy: false, ...options });
         const managerCachePath = (0, path_1.join)(managerHome.contentRoot, relativePath);
         if ((0, fs_1.existsSync)(managerCachePath)) {
             const fraimDir = (0, project_fraim_paths_1.getUserFraimDirPath)();
@@ -1371,7 +1383,7 @@ function resolveTeamContextFile(workspaceRoot, key, options = {}) {
 function orgBrandCandidateDirs(workspaceRoot) {
     return [
         (0, path_1.join)((0, project_fraim_paths_1.getWorkspaceFraimDir)(workspaceRoot), 'personalized-employee', 'context'),
-        (0, path_1.join)((0, pack_home_1.resolvePackHome)('org').contentRoot, 'context'),
+        (0, path_1.join)((0, pack_home_1.resolvePackHome)('org', { migrateLegacy: false }).contentRoot, 'context'),
         (0, path_1.join)((0, project_fraim_paths_1.getUserFraimDirPath)(), 'personalized-employee', 'context'),
     ];
 }
@@ -1520,24 +1532,8 @@ function countPreservedLearnings(workspaceRoot, userId) {
         const domainCoach = countPersonalFamilyByLevel(`${resolvedUserId}-${domain}-manager-coaching.md`);
         reverseMentoring += domainCoach.manager + domainCoach.project;
     }
-    // L0 raw signals still awaiting synthesis (not dismissed).
-    let rawSignals = 0;
-    const rawDir = (0, path_1.join)(roots.repoLearningsBase, 'raw');
-    if ((0, fs_1.existsSync)(rawDir)) {
-        try {
-            for (const fileName of (0, fs_1.readdirSync)(rawDir)) {
-                if (!fileName.endsWith('.md'))
-                    continue;
-                const fm = readFrontmatter((0, fs_1.readFileSync)((0, path_1.join)(rawDir, fileName), 'utf8'));
-                if (isTruthyFlag(fm.dismissed))
-                    continue;
-                rawSignals++;
-            }
-        }
-        catch {
-            // ignore unreadable raw dir
-        }
-    }
+    // Pending counts and Brain/context use exactly the same typed input selection.
+    const rawSignals = collectPendingL0SourceFiles(workspaceRoot, userId.trim(), roots).length;
     return {
         organization,
         manager,
@@ -1683,7 +1679,7 @@ function resolveBrainUsageProjector() {
 function collectBrainLearningDots(workspaceRoot, userId) {
     const roots = getLearningRoots(workspaceRoot);
     const resolvedUserId = resolveLearningUserId(workspaceRoot, userId, roots);
-    const pendingSignals = collectPendingL0SourceFiles(workspaceRoot, resolvedUserId, roots).map((s) => ({
+    const pendingSignals = collectPendingL0SourceFiles(workspaceRoot, userId.trim(), roots).map((s) => ({
         type: s.kind,
         typeLabel: PENDING_KIND_LABEL[s.kind],
         fileName: s.displayPath.split('/').pop() || s.displayPath,
@@ -1975,8 +1971,8 @@ function readPreservedLearnings(workspaceRoot, userId, scope, level = 'machine')
             // #806: domain-scoped org learnings — union from both locations.
             const allDomainFiles = [
                 ...listDomainLearningFiles(roots.repoLearningsBase, 'org', fileType).map((d) => ({ ...d, base: roots.repoLearningsBase })),
-                ...listDomainLearningFiles((0, path_1.join)((0, pack_home_1.resolvePackHome)('org').contentRoot, 'learnings'), 'org', fileType)
-                    .map((d) => ({ ...d, base: (0, path_1.join)((0, pack_home_1.resolvePackHome)('org').contentRoot, 'learnings') })),
+                ...listDomainLearningFiles((0, path_1.join)((0, pack_home_1.resolvePackHome)('org', { migrateLegacy: false }).contentRoot, 'learnings'), 'org', fileType)
+                    .map((d) => ({ ...d, base: (0, path_1.join)((0, pack_home_1.resolvePackHome)('org', { migrateLegacy: false }).contentRoot, 'learnings') })),
             ];
             const seenDomainFile = new Set();
             for (const { fileName, domain, base } of allDomainFiles) {
@@ -2065,7 +2061,7 @@ function resolveLearningFilePath(workspaceRoot, userId, ref) {
         // Write org entries to the org pack home — same location share-with-others uses.
         // The Hub read path already merges pack home + repo-local, so edits land where
         // the agent reads them without needing a repo commit.
-        return (0, path_1.join)((0, pack_home_1.resolvePackHome)('org').contentRoot, 'learnings', learningFileName('org', fileType, ref.domain));
+        return (0, path_1.join)((0, pack_home_1.resolvePackHome)('org', { migrateLegacy: false }).contentRoot, 'learnings', learningFileName('org', fileType, ref.domain));
     }
     const resolvedUserId = resolveLearningUserId(workspaceRoot, userId, roots);
     // Issue #1070: for the 'machine' level use the configured manager home.

package/dist/src/local-mcp-server/learning-source-record.js

@@ -0,0 +1,122 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.normalizeLearningSourcePath = normalizeLearningSourcePath;
+exports.parseLearningSourceRecord = parseLearningSourceRecord;
+/** Metadata and configured location contract for future learning inputs. */
+const node_path_1 = __importDefault(require("node:path"));
+const artifact_paths_1 = require("../../registry/scripts/artifact-paths");
+function normalizeLearningSourcePath(value) {
+    const normalized = node_path_1.default.resolve(value).replace(/\\/g, '/');
+    return process.platform === 'win32' ? normalized.toLowerCase() : normalized;
+}
+function validDate(value) {
+    if (!/^\d{4}-\d{2}-\d{2}(?:T\d{2}:\d{2}:\d{2}(?:\.\d{1,3})?Z)?$/.test(value))
+        return false;
+    const date = new Date(value);
+    return Number.isFinite(date.getTime()) && date.toISOString().slice(0, 10) === value.slice(0, 10);
+}
+function safePart(value) {
+    return Boolean(value) && value !== '.' && value !== '..' && !/[\\/:*?"<>|\x00-\x1f]/.test(value)
+        && value.trim() === value && !/[. ]$/.test(value);
+}
+/** Explicit paths keep parsing pure; otherwise resolve the owning configuration. Callers guard physical source containment. */
+function parseLearningSourceRecord(content, filePath, homeRoot, contentRoot, configuredPaths) {
+    const invalid = (reason) => ({ status: 'invalid', reason });
+    const normalized = content.replace(/^\uFEFF/, '');
+    const fm = /^---\r?\n([\s\S]*?)\r?\n---(?:\r?\n|$)/.exec(normalized);
+    if (!fm) {
+        // Diagnose interrupted new records only in the leading metadata block.
+        // Never search document bodies for a marker that could be an example.
+        if (/^---\r?\n/.test(normalized)) {
+            for (const line of normalized.split(/\r?\n/).slice(1)) {
+                if (!line.trim())
+                    continue;
+                if (!/^[ \t]*["']?[A-Za-z][A-Za-z0-9]*["']?[ \t]*:/.test(line))
+                    break;
+                if (/^[ \t]*["']?artifactKind["']?[ \t]*:[ \t]*["']?learning-(?:raw|retrospective)["']?[ \t]*(?:#.*)?$/.test(line)) {
+                    return invalid('Unclosed typed learning frontmatter');
+                }
+            }
+        }
+        return { status: 'unsupported', reason: 'No typed learning frontmatter' };
+    }
+    const fields = {};
+    const duplicates = new Set();
+    let malformedField = false;
+    for (const line of fm[1].split(/\r?\n/)) {
+        const match = /^([A-Za-z][A-Za-z0-9]*):[ \t]*(.*)$/.exec(line);
+        if (!match) {
+            if (/^\s*["']?(artifactKind|author|date|job|runId|usageSourceRef|synthesized)["']?\s*:/.test(line))
+                malformedField = true;
+            continue;
+        }
+        if (Object.prototype.hasOwnProperty.call(fields, match[1]))
+            duplicates.add(match[1]);
+        let value = match[2].trim();
+        if (!value.startsWith('"') && !value.startsWith("'"))
+            value = value.replace(/(?:^|\s+)#.*$/, '').trim();
+        if ((value.startsWith('"') && value.endsWith('"')) || (value.startsWith("'") && value.endsWith("'"))) {
+            value = value.slice(1, -1);
+        }
+        fields[match[1]] = value;
+    }
+    if (!fields.artifactKind)
+        return malformedField || Object.prototype.hasOwnProperty.call(fields, 'artifactKind')
+            ? invalid('Unsupported metadata key spelling')
+            : { status: 'unsupported', reason: 'No typed learning artifactKind' };
+    if (fields.artifactKind !== 'learning-raw' && fields.artifactKind !== 'learning-retrospective') {
+        return fields.artifactKind.startsWith('learning')
+            ? invalid('Invalid learning artifactKind')
+            : { status: 'unsupported', reason: 'Unsupported artifactKind' };
+    }
+    if (malformedField)
+        return invalid('Unsupported metadata key spelling');
+    if (duplicates.size)
+        return invalid(`Duplicate metadata: ${[...duplicates].join(', ')}`);
+    for (const field of ['author', 'date', 'job', 'runId', 'usageSourceRef', 'synthesized']) {
+        if (!Object.prototype.hasOwnProperty.call(fields, field))
+            return invalid(`Missing metadata: ${field}`);
+    }
+    if (![fields.author, fields.job, fields.runId].every(safePart))
+        return invalid('Unsafe or empty author, job or runId');
+    if (!validDate(fields.date) || (fields.synthesized && !validDate(fields.synthesized)))
+        return invalid('Invalid date or synthesized date');
+    if (!node_path_1.default.isAbsolute(homeRoot) || !node_path_1.default.isAbsolute(contentRoot) || !node_path_1.default.isAbsolute(filePath))
+        return invalid('Absolute configured root and source path required');
+    const kind = fields.artifactKind === 'learning-raw' ? 'raw' : 'retrospective';
+    const basename = node_path_1.default.basename(filePath);
+    const prefix = `${fields.author}-${fields.runId}-`;
+    const nameKey = (value) => process.platform === 'win32' ? value.toLowerCase() : value;
+    if (!nameKey(basename).startsWith(nameKey(prefix)) || !basename.endsWith('.md') || basename.length <= prefix.length + 3
+        || (kind === 'retrospective' && nameKey(basename) !== nameKey(`${prefix}${fields.job}-retrospective.md`))) {
+        return invalid('Filename does not match recorded author, runId and kind');
+    }
+    let paths;
+    try {
+        paths = configuredPaths ?? (0, artifact_paths_1.resolveLearningPaths)(homeRoot, contentRoot);
+    }
+    catch (error) {
+        return invalid(error instanceof Error ? error.message : 'Invalid artifact configuration');
+    }
+    const pendingPath = node_path_1.default.resolve(kind === 'raw' ? paths.raw : paths.retrospectives, basename).replace(/\\/g, '/');
+    const archivePath = node_path_1.default.resolve(kind === 'raw' ? paths.archiveRaw : paths.archiveRetrospectives, basename).replace(/\\/g, '/');
+    const current = normalizeLearningSourcePath(filePath);
+    const state = current === normalizeLearningSourcePath(pendingPath) ? 'pending'
+        : current === normalizeLearningSourcePath(archivePath) ? 'archived' : null;
+    if (!state)
+        return invalid('Source is outside its configured learning location');
+    if (state === 'archived' && !fields.synthesized)
+        return invalid('Archive has no successful processing date');
+    if (!node_path_1.default.isAbsolute(fields.usageSourceRef) || /[\x00-\x1f]/.test(fields.usageSourceRef)
+        || fields.usageSourceRef.includes('\\')
+        || fields.usageSourceRef !== node_path_1.default.resolve(fields.usageSourceRef).replace(/\\/g, '/')
+        || normalizeLearningSourcePath(fields.usageSourceRef) !== normalizeLearningSourcePath(pendingPath)) {
+        return invalid('usageSourceRef must be the normalized absolute original pending path');
+    }
+    return { status: 'valid', record: { artifactKind: fields.artifactKind, kind, author: fields.author,
+            date: fields.date, job: fields.job, runId: fields.runId, usageSourceRef: fields.usageSourceRef,
+            synthesized: fields.synthesized, pendingPath, archivePath, state } };
+}