fraim-hub 2.0.204

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

@@ -0,0 +1,975 @@
+"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.LEARNING_PRIORITIES = void 0;
+exports.learningEntryHeadingRegex = learningEntryHeadingRegex;
+exports.computeEffectiveScore = computeEffectiveScore;
+exports.buildLearningContextSection = buildLearningContextSection;
+exports.buildTeamContextSection = buildTeamContextSection;
+exports.resolveTeamContextFiles = resolveTeamContextFiles;
+exports.isTeamContextKey = isTeamContextKey;
+exports.resolveTeamContextFile = resolveTeamContextFile;
+exports.readOrgBrand = readOrgBrand;
+exports.resolveOrgBrandWriteDir = resolveOrgBrandWriteDir;
+exports.countPreservedLearnings = countPreservedLearnings;
+exports.readPreservedLearnings = readPreservedLearnings;
+exports.applyLearningEntryChange = applyLearningEntryChange;
+exports.isTruthyFlag = isTruthyFlag;
+const fs_1 = require("fs");
+const path_1 = require("path");
+const project_fraim_paths_1 = require("../core/utils/project-fraim-paths");
+const brand_store_1 = require("../core/brand-store");
+const REPO_LEARNINGS_REL = (0, project_fraim_paths_1.getWorkspaceFraimDisplayPath)('personalized-employee/learnings').replace(/\/$/, '');
+const DEFAULT_THRESHOLD = 3.0;
+const AGING_HORIZON_DAYS = 7;
+const MAX_ENTRIES_SCANNED = 200;
+const L0_SLEEP_ON_LEARNINGS_PROMPT_MIN = 5;
+// ── Single source of truth for the learning-entry format contract (#533) ──────
+// The `## [P-…] <title>` entry format is a tight contract shared by three sides:
+//   1. EMIT — the synthesis jobs (sleep-on-learnings, organizational-learning-
+//      synthesis) instruct the agent to write entries in this shape.
+//   2. SCORE — the decay scorer below reads severity + Last seen + Recurrences to
+//      decide which learnings stay active and get injected into agent context.
+//   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.
+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);
+}
+function getLearningRoots(workspaceRoot) {
+    return {
+        globalPersonalBase: (0, project_fraim_paths_1.getConfiguredPortableLearningsDir)(workspaceRoot),
+        globalPersonalDisplayBase: (0, project_fraim_paths_1.getConfiguredPortableLearningsDisplayPath)(workspaceRoot),
+        managerCacheBase: (0, path_1.join)((0, project_fraim_paths_1.getUserFraimDirPath)(), 'manager', 'learnings'),
+        managerCacheDisplayBase: (0, project_fraim_paths_1.getUserFraimDisplayPath)('manager/learnings'),
+        repoLearningsBase: (0, project_fraim_paths_1.getWorkspaceLearningsDir)(workspaceRoot)
+    };
+}
+function resolvePersonalLearningFile(repoBase, managerCacheBase, managerCacheDisplayBase, globalBase, globalDisplayBase, fileName) {
+    const repoPath = (0, path_1.join)(repoBase, fileName);
+    if ((0, fs_1.existsSync)(repoPath)) {
+        return {
+            present: true,
+            path: repoPath,
+            displayPath: `${REPO_LEARNINGS_REL}/${fileName}`
+        };
+    }
+    const globalPath = (0, path_1.join)(globalBase, fileName);
+    if ((0, fs_1.existsSync)(globalPath)) {
+        return {
+            present: true,
+            path: globalPath,
+            displayPath: `${globalDisplayBase.replace(/\/$/, '')}/${fileName}`
+        };
+    }
+    const managerCachePath = (0, path_1.join)(managerCacheBase, fileName);
+    if ((0, fs_1.existsSync)(managerCachePath)) {
+        return {
+            present: true,
+            path: managerCachePath,
+            displayPath: `${managerCacheDisplayBase.replace(/\/$/, '')}/${fileName}`
+        };
+    }
+    return { present: false, path: globalPath, displayPath: `${globalDisplayBase.replace(/\/$/, '')}/${fileName}` };
+}
+function buildUserIdCandidates(userId) {
+    const candidates = new Set();
+    const trimmed = userId.trim();
+    if (trimmed)
+        candidates.add(trimmed);
+    const atIndex = trimmed.indexOf('@');
+    if (atIndex > 0)
+        candidates.add(trimmed.slice(0, atIndex));
+    return Array.from(candidates);
+}
+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 collectAvailableUserPrefixes(workspaceRoot, personalRoots) {
+    const prefixes = new Set();
+    const collect = (dirPath, extractor) => {
+        if (!(0, fs_1.existsSync)(dirPath))
+            return;
+        try {
+            for (const fileName of (0, fs_1.readdirSync)(dirPath)) {
+                const prefix = extractor(fileName);
+                if (prefix)
+                    prefixes.add(prefix);
+            }
+        }
+        catch {
+            // Ignore unreadable directories.
+        }
+    };
+    for (const personalRoot of personalRoots) {
+        collect(personalRoot, (fileName) => {
+            if (!fileName.endsWith('.md') || fileName.startsWith('org-'))
+                return null;
+            const match = fileName.match(/^(.*?)-(preferences|manager-coaching|mistake-patterns|validated-patterns)\.md$/);
+            return match ? match[1] : null;
+        });
+    }
+    collect((0, path_1.join)(personalRoots[0], 'raw'), (fileName) => {
+        const match = fileName.match(/^(.*?)-\d{4}-\d{2}-\d{2}-.*\.md$/);
+        return match ? match[1] : null;
+    });
+    collect((0, path_1.join)(workspaceRoot, 'docs', 'retrospectives'), (fileName) => {
+        const match = fileName.match(/^(.*?)-\d{4}-\d{2}-\d{2}-.*\.md$/);
+        return match ? match[1] : null;
+    });
+    return prefixes;
+}
+function resolveLearningUserId(workspaceRoot, userId, roots) {
+    const candidates = buildUserIdCandidates(userId);
+    let bestCandidate = candidates[0] || userId;
+    let bestScore = -1;
+    for (const candidate of candidates) {
+        const score = ((0, fs_1.existsSync)((0, path_1.join)(roots.globalPersonalBase, `${candidate}-preferences.md`)) ? 1 : 0) +
+            ((0, fs_1.existsSync)((0, path_1.join)(roots.globalPersonalBase, `${candidate}-manager-coaching.md`)) ? 1 : 0) +
+            ((0, fs_1.existsSync)((0, path_1.join)(roots.globalPersonalBase, `${candidate}-mistake-patterns.md`)) ? 1 : 0) +
+            ((0, fs_1.existsSync)((0, path_1.join)(roots.globalPersonalBase, `${candidate}-validated-patterns.md`)) ? 1 : 0) +
+            ((0, fs_1.existsSync)((0, path_1.join)(roots.managerCacheBase, `${candidate}-preferences.md`)) ? 1 : 0) +
+            ((0, fs_1.existsSync)((0, path_1.join)(roots.managerCacheBase, `${candidate}-manager-coaching.md`)) ? 1 : 0) +
+            ((0, fs_1.existsSync)((0, path_1.join)(roots.managerCacheBase, `${candidate}-mistake-patterns.md`)) ? 1 : 0) +
+            ((0, fs_1.existsSync)((0, path_1.join)(roots.managerCacheBase, `${candidate}-validated-patterns.md`)) ? 1 : 0) +
+            ((0, fs_1.existsSync)((0, path_1.join)(roots.repoLearningsBase, `${candidate}-preferences.md`)) ? 1 : 0) +
+            ((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'));
+        if (score > bestScore) {
+            bestCandidate = candidate;
+            bestScore = score;
+        }
+    }
+    if (bestScore > 0)
+        return bestCandidate;
+    const availablePrefixes = collectAvailableUserPrefixes(workspaceRoot, [roots.repoLearningsBase, roots.managerCacheBase, roots.globalPersonalBase]);
+    if (availablePrefixes.size === 1) {
+        return Array.from(availablePrefixes)[0];
+    }
+    return bestCandidate;
+}
+function readWorkspaceConfig(workspaceRoot) {
+    try {
+        const configPath = (0, project_fraim_paths_1.getWorkspaceConfigPath)(workspaceRoot);
+        if ((0, fs_1.existsSync)(configPath)) {
+            return JSON.parse((0, fs_1.readFileSync)(configPath, 'utf8'));
+        }
+    }
+    catch {
+        // Fall through.
+    }
+    return null;
+}
+function getScoreThreshold(workspaceRoot) {
+    const config = readWorkspaceConfig(workspaceRoot);
+    const t = config?.learning?.scoreThreshold;
+    if (typeof t === 'number' && t > 0)
+        return t;
+    return DEFAULT_THRESHOLD;
+}
+/**
+ * Effective score for an L1 learning entry. The aging-risk count below uses
+ * this same decay model with `now` shifted forward.
+ *
+ * @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()) {
+    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).
+    const halfLife = fileType === 'mistake-patterns' ? 90 : 180;
+    let daysSinceLastSeen = 0;
+    try {
+        const lastSeen = new Date(lastSeenDate);
+        daysSinceLastSeen = Math.max(0, (now.getTime() - lastSeen.getTime()) / (1000 * 60 * 60 * 24));
+    }
+    catch {
+        // Treat as fresh.
+    }
+    const decay = Math.pow(0.5, daysSinceLastSeen / halfLife);
+    const recurrenceBoost = Math.log2(Math.max(1, recurrences) + 1);
+    return baseScore * decay * recurrenceBoost;
+}
+function scanMistakePatternFile(filePath, threshold, fileType = 'mistake-patterns') {
+    const empty = { active: 0, dormant: 0, agingRisk: 0 };
+    if (!(0, fs_1.existsSync)(filePath))
+        return empty;
+    let content;
+    try {
+        content = (0, fs_1.readFileSync)(filePath, 'utf8');
+    }
+    catch {
+        return empty;
+    }
+    const lines = content.split(/\r?\n/);
+    const now = new Date();
+    const horizon = new Date(now.getTime() + AGING_HORIZON_DAYS * 86_400_000);
+    let active = 0;
+    let dormant = 0;
+    let agingRisk = 0;
+    let scanned = 0;
+    let inEntry = false;
+    let severity = null;
+    let lastSeen = '';
+    let recurrences = 1;
+    const flush = () => {
+        if (!severity)
+            return;
+        scanned++;
+        const today = computeEffectiveScore(severity, lastSeen, recurrences, fileType, now);
+        if (today >= threshold) {
+            active++;
+            if (lastSeen) {
+                const future = computeEffectiveScore(severity, lastSeen, recurrences, fileType, horizon);
+                if (future < threshold)
+                    agingRisk++;
+            }
+        }
+        else {
+            dormant++;
+        }
+    };
+    for (const line of lines) {
+        if (scanned >= MAX_ENTRIES_SCANNED)
+            break;
+        const headerMatch = line.match(learningEntryHeadingRegex());
+        if (headerMatch) {
+            flush();
+            inEntry = true;
+            severity = headerMatch[1];
+            lastSeen = '';
+            recurrences = 1;
+            continue;
+        }
+        if (!inEntry)
+            continue;
+        const lastSeenMatch = line.match(/^\*\*Last seen\*\*:\s*(.+)/);
+        if (lastSeenMatch) {
+            lastSeen = lastSeenMatch[1].trim();
+            continue;
+        }
+        const recurrenceMatch = line.match(/^\*\*Recurrences\*\*:\s*(\d+)/);
+        if (recurrenceMatch) {
+            recurrences = parseInt(recurrenceMatch[1], 10);
+        }
+    }
+    flush();
+    return { active, dormant, agingRisk };
+}
+function readFrontmatter(content) {
+    const match = content.match(/^---\r?\n([\s\S]*?)\r?\n---/);
+    if (!match)
+        return {};
+    const frontmatter = {};
+    for (const line of match[1].split(/\r?\n/)) {
+        const separator = line.indexOf(':');
+        if (separator === -1)
+            continue;
+        const key = line.slice(0, separator).trim();
+        const value = line.slice(separator + 1).trim();
+        if (key) {
+            frontmatter[key] = value;
+        }
+    }
+    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;
+}
+function collectPendingL0SourceFiles(workspaceRoot, resolvedUserId, roots) {
+    const sources = [];
+    const rawPath = (0, path_1.join)(roots.repoLearningsBase, 'raw');
+    if ((0, fs_1.existsSync)(rawPath)) {
+        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)
+                });
+            }
+        }
+        catch {
+            // Ignore read failures.
+        }
+    }
+    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)))
+                    continue;
+                sources.push({
+                    kind: 'retrospective',
+                    displayPath: `docs/retrospectives/${fileName}`,
+                    sortKey: pendingL0SortKey(fileName)
+                });
+            }
+        }
+        catch {
+            // Ignore read failures.
+        }
+    }
+    return sources.sort((a, b) => b.sortKey.localeCompare(a.sortKey) || a.displayPath.localeCompare(b.displayPath));
+}
+/**
+ * Resolve an L2 org-scope learning file (issue #563): a repo-local override
+ * (`fraim/personalized-employee/learnings/`) wins, then the synced org cache
+ * (`~/.fraim/org/learnings/`). Org learnings are part of the shared org pack,
+ * so a synced copy must be readable by the agent even with no repo-local copy.
+ * Mirrors the org context/rules resolution order. Returns `present:false` with
+ * the repo path/display when neither tier has the file.
+ */
+function resolveOrgLearningFile(repoLearningsBase, fileName) {
+    const repoPath = (0, path_1.join)(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, project_fraim_paths_1.getUserFraimDirPath)(), 'org', 'learnings', fileName);
+    if ((0, fs_1.existsSync)(cachePath)) {
+        return { present: true, path: cachePath, displayPath: (0, project_fraim_paths_1.getUserFraimDisplayPath)(`org/learnings/${fileName}`) };
+    }
+    return { present: false, path: repoPath, displayPath: `${REPO_LEARNINGS_REL}/${fileName}` };
+}
+function buildLearningContextSection(workspaceRoot, userId, forJob) {
+    const roots = getLearningRoots(workspaceRoot);
+    const resolvedUserId = resolveLearningUserId(workspaceRoot, userId, roots);
+    const threshold = getScoreThreshold(workspaceRoot);
+    // L2 org learnings resolve repo-local first, then the synced org cache (#563).
+    const l2Mistake = resolveOrgLearningFile(roots.repoLearningsBase, 'org-mistake-patterns.md');
+    const l2Pref = resolveOrgLearningFile(roots.repoLearningsBase, 'org-preferences.md');
+    const l2Coach = resolveOrgLearningFile(roots.repoLearningsBase, 'org-manager-coaching.md');
+    const l2Validated = resolveOrgLearningFile(roots.repoLearningsBase, 'org-validated-patterns.md');
+    const l2MistakePresent = l2Mistake.present;
+    const l2PrefPresent = l2Pref.present;
+    const l2CoachPresent = l2Coach.present;
+    const l2ValidatedPresent = l2Validated.present;
+    const l2MistakeStats = l2MistakePresent ? scanMistakePatternFile(l2Mistake.path, threshold, 'mistake-patterns') : null;
+    const l2ValidatedStats = l2ValidatedPresent ? scanMistakePatternFile(l2Validated.path, threshold, 'validated-patterns') : null;
+    const l1Mistake = resolvePersonalLearningFile(roots.repoLearningsBase, roots.managerCacheBase, roots.managerCacheDisplayBase, roots.globalPersonalBase, roots.globalPersonalDisplayBase, `${resolvedUserId}-mistake-patterns.md`);
+    const l1Pref = resolvePersonalLearningFile(roots.repoLearningsBase, roots.managerCacheBase, roots.managerCacheDisplayBase, roots.globalPersonalBase, roots.globalPersonalDisplayBase, `${resolvedUserId}-preferences.md`);
+    const l1Coach = resolvePersonalLearningFile(roots.repoLearningsBase, roots.managerCacheBase, roots.managerCacheDisplayBase, roots.globalPersonalBase, roots.globalPersonalDisplayBase, `${resolvedUserId}-manager-coaching.md`);
+    const l1Validated = resolvePersonalLearningFile(roots.repoLearningsBase, roots.managerCacheBase, roots.managerCacheDisplayBase, roots.globalPersonalBase, roots.globalPersonalDisplayBase, `${resolvedUserId}-validated-patterns.md`);
+    const l1MistakeStats = l1Mistake.present ? scanMistakePatternFile(l1Mistake.path, threshold, 'mistake-patterns') : null;
+    const l1ValidatedStats = l1Validated.present ? scanMistakePatternFile(l1Validated.path, threshold, 'validated-patterns') : null;
+    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;
+    const hasL2 = l2MistakePresent || l2PrefPresent || l2CoachPresent || l2ValidatedPresent;
+    const hasL1 = l1Mistake.present || l1Pref.present || l1Coach.present || l1Validated.present;
+    const hasContent = hasL2 || hasL1 || l0CoachingCount > 0 || l0RetroCount > 0;
+    if (!hasContent)
+        return '';
+    let section = forJob
+        ? '\n\n## Learning Context for This Job\n\n'
+        : '\n\n## Learning Context\n\n';
+    if (hasL2) {
+        section += '### L2 - Org patterns\n';
+        if (l2MistakePresent)
+            section += `\`${l2Mistake.displayPath}\`  (entries above score threshold)\n`;
+        if (l2PrefPresent)
+            section += `\`${l2Pref.displayPath}\`  (all entries)\n`;
+        if (l2CoachPresent)
+            section += `\`${l2Coach.displayPath}\`  (manager-facing; all entries)\n`;
+        if (l2ValidatedPresent)
+            section += `\`${l2Validated.displayPath}\`  (entries above score threshold)\n`;
+        const l2DormantTotal = (l2MistakeStats?.dormant || 0) + (l2ValidatedStats?.dormant || 0);
+        if (l2DormantTotal > 0) {
+            section += `Dormant: ${l2DormantTotal} org pattern${l2DormantTotal !== 1 ? 's' : ''} below threshold\n`;
+        }
+        section += '\n';
+    }
+    if (hasL1) {
+        section += '### L1 - Your patterns\n';
+        if (l1Pref.present)
+            section += `\`${l1Pref.displayPath}\`  (all entries)\n`;
+        if (l1Coach.present)
+            section += `\`${l1Coach.displayPath}\`  (manager-facing; all entries)\n`;
+        if (l1Mistake.present)
+            section += `\`${l1Mistake.displayPath}\`  (entries above score threshold)\n`;
+        if (l1Validated.present)
+            section += `\`${l1Validated.displayPath}\`  (entries above score threshold)\n`;
+        const l1DormantTotal = (l1MistakeStats?.dormant || 0) + (l1ValidatedStats?.dormant || 0);
+        if (l1DormantTotal > 0) {
+            section += `Dormant: ${l1DormantTotal} personal pattern${l1DormantTotal !== 1 ? 's' : ''} below threshold\n`;
+        }
+        section += '\n';
+    }
+    if (l0CoachingCount > 0 || l0RetroCount > 0) {
+        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`;
+        }
+        if (l0RetroCount > 0) {
+            section += `${l0RetroCount} retrospective${l0RetroCount !== 1 ? 's' : ''} in \`docs/retrospectives/${resolvedUserId}-*\` with unsynthesized or missing \`synthesized\` frontmatter\n`;
+        }
+        section += 'Pending L0 Source Files:\n';
+        for (const source of pendingL0Sources) {
+            section += `- \`${source.displayPath}\`\n`;
+        }
+        section += 'Read these pending L0 source files before continuing; they are unsynthesized learnings for the current agent.\n';
+        if (totalL0 >= L0_SLEEP_ON_LEARNINGS_PROMPT_MIN) {
+            section += `This is ${totalL0} pending L0 file${totalL0 !== 1 ? 's' : ''}; to speed up future starts, run \`sleep-on-learnings\` to synthesize or archive them.\n`;
+        }
+        section += '\n';
+    }
+    if (forJob) {
+        if (hasL2 || hasL1) {
+            section += 'Use the relevant patterns and preferences in this job.\n';
+            if (l1Coach.present || l2CoachPresent) {
+                section += 'Treat manager-coaching as feedback for how the manager should continue or improve managing AI, not as agent instruction.\n';
+            }
+        }
+    }
+    else {
+        section += 'Use this synthesized learning context throughout the session.\n';
+        if (l1Coach.present || l2CoachPresent) {
+            section += 'Manager-coaching entries are manager-facing feedback, not instructions for the AI to follow.\n';
+        }
+    }
+    return section;
+}
+/**
+ * Resolve an organization/manager-scope context file (issue #563 order, R3.1):
+ *   1. repo-local override (`fraim/personalized-employee/…`) — wins when present
+ *   2. managed org cache (`~/.fraim/org/…`) — the synced shared org layer;
+ *      eligible for org files only, never manager files (R3.3)
+ *   3. legacy machine-local (`~/.fraim/personalized-employee/…`)
+ */
+function resolveOrgContextFile(workspaceRoot, relativePath, orgCacheEligible = true) {
+    try {
+        const repoPath = (0, path_1.join)((0, project_fraim_paths_1.getWorkspaceFraimDir)(workspaceRoot), 'personalized-employee', relativePath);
+        if ((0, fs_1.existsSync)(repoPath)) {
+            return {
+                present: true,
+                displayPath: (0, project_fraim_paths_1.getWorkspaceFraimDisplayPath)(`personalized-employee/${relativePath}`)
+            };
+        }
+        if (orgCacheEligible) {
+            const cachePath = (0, path_1.join)((0, project_fraim_paths_1.getUserFraimDirPath)(), 'org', relativePath);
+            if ((0, fs_1.existsSync)(cachePath)) {
+                return {
+                    present: true,
+                    displayPath: (0, project_fraim_paths_1.getUserFraimDisplayPath)(`org/${relativePath}`)
+                };
+            }
+        }
+        if (!orgCacheEligible) {
+            const managerCachePath = (0, path_1.join)((0, project_fraim_paths_1.getUserFraimDirPath)(), 'manager', relativePath);
+            if ((0, fs_1.existsSync)(managerCachePath)) {
+                return {
+                    present: true,
+                    displayPath: (0, project_fraim_paths_1.getUserFraimDisplayPath)(`manager/${relativePath}`)
+                };
+            }
+        }
+        const userPath = (0, path_1.join)((0, project_fraim_paths_1.getUserFraimDirPath)(), 'personalized-employee', relativePath);
+        if ((0, fs_1.existsSync)(userPath)) {
+            return {
+                present: true,
+                displayPath: (0, project_fraim_paths_1.getUserFraimDisplayPath)(`personalized-employee/${relativePath}`)
+            };
+        }
+    }
+    catch {
+        // Fall through to absent.
+    }
+    return { present: false, displayPath: '' };
+}
+/**
+ * Resolve a project-scope context file. These are repo-local only — they
+ * describe a single engagement and never layer up to the user level.
+ */
+function resolveProjectContextFile(workspaceRoot, relativePath) {
+    try {
+        const repoPath = (0, path_1.join)((0, project_fraim_paths_1.getWorkspaceFraimDir)(workspaceRoot), 'personalized-employee', relativePath);
+        if ((0, fs_1.existsSync)(repoPath)) {
+            return {
+                present: true,
+                displayPath: (0, project_fraim_paths_1.getWorkspaceFraimDisplayPath)(`personalized-employee/${relativePath}`)
+            };
+        }
+    }
+    catch {
+        // Fall through to absent.
+    }
+    return { present: false, displayPath: '' };
+}
+/**
+ * Builds the team-context section pointing the agent at the org/manager/project
+ * context files that exist on disk (issue #512, three-layer Context
+ * Architecture). Mirrors `buildLearningContextSection`: pure, side-effect-free,
+ * lists only present files, and returns '' when none exist.
+ */
+function buildTeamContextSection(workspaceRoot, forJob) {
+    // Organization layer: repo override, then org cache, then legacy machine-local.
+    // Manager files are personal and never resolve from the shared org cache (R3.3).
+    const orgContext = resolveOrgContextFile(workspaceRoot, 'context/org_context.md');
+    const managerContext = resolveOrgContextFile(workspaceRoot, 'context/manager_context.md', false);
+    const orgRules = resolveOrgContextFile(workspaceRoot, 'rules/org_rules.md');
+    const managerRules = resolveOrgContextFile(workspaceRoot, 'rules/manager_rules.md', false);
+    // Project layer (repo-local only).
+    const projectContext = resolveProjectContextFile(workspaceRoot, 'context/project_context.md');
+    const projectBrief = resolveProjectContextFile(workspaceRoot, 'context/project_brief.md');
+    const projectRules = resolveProjectContextFile(workspaceRoot, 'rules/project_rules.md');
+    const projectQa = resolveProjectContextFile(workspaceRoot, 'context/project_qa.md');
+    const hasOrg = orgContext.present || managerContext.present || orgRules.present || managerRules.present;
+    const hasProject = projectContext.present || projectBrief.present || projectRules.present || projectQa.present;
+    if (!hasOrg && !hasProject)
+        return '';
+    let section = forJob
+        ? '\n\n## Team Context for This Job\n\n'
+        : '\n\n## Team Context\n\n';
+    if (hasOrg) {
+        section += '### Organization\n';
+        if (orgContext.present)
+            section += `\`${orgContext.displayPath}\`\n`;
+        if (managerContext.present)
+            section += `\`${managerContext.displayPath}\`\n`;
+        if (orgRules.present)
+            section += `\`${orgRules.displayPath}\`\n`;
+        if (managerRules.present)
+            section += `\`${managerRules.displayPath}\`\n`;
+        section += '\n';
+    }
+    if (hasProject) {
+        section += '### Project\n';
+        if (projectContext.present)
+            section += `\`${projectContext.displayPath}\`\n`;
+        if (projectBrief.present)
+            section += `\`${projectBrief.displayPath}\`\n`;
+        if (projectRules.present)
+            section += `\`${projectRules.displayPath}\`\n`;
+        if (projectQa.present)
+            section += `\`${projectQa.displayPath}\`\n`;
+        section += '\n';
+    }
+    section += 'Read the relevant context before doing work.\n';
+    return section;
+}
+/**
+ * Resolve presence + display paths for every three-layer Team Context file
+ * (org/manager/project). Reuses resolveOrgContextFile / resolveProjectContextFile
+ * so layering (repo-local shadows user-level for org/manager; project is
+ * repo-local only) matches buildTeamContextSection exactly.
+ */
+function resolveTeamContextFiles(workspaceRoot) {
+    return {
+        orgContext: resolveOrgContextFile(workspaceRoot, 'context/org_context.md'),
+        managerContext: resolveOrgContextFile(workspaceRoot, 'context/manager_context.md', false),
+        orgRules: resolveOrgContextFile(workspaceRoot, 'rules/org_rules.md'),
+        managerRules: resolveOrgContextFile(workspaceRoot, 'rules/manager_rules.md', false),
+        projectContext: resolveProjectContextFile(workspaceRoot, 'context/project_context.md'),
+        projectBrief: resolveProjectContextFile(workspaceRoot, 'context/project_brief.md'),
+        projectQa: resolveProjectContextFile(workspaceRoot, 'context/project_qa.md'),
+        projectRules: resolveProjectContextFile(workspaceRoot, 'rules/project_rules.md')
+    };
+}
+/** Map a key to its (relativePath, scope). Single source of truth. */
+const TEAM_CONTEXT_FILE_MAP = {
+    org: { relativePath: 'context/org_context.md', scope: 'org' },
+    manager: { relativePath: 'context/manager_context.md', scope: 'org' },
+    orgRules: { relativePath: 'rules/org_rules.md', scope: 'org' },
+    managerRules: { relativePath: 'rules/manager_rules.md', scope: 'org' },
+    projectContext: { relativePath: 'context/project_context.md', scope: 'project' },
+    projectBrief: { relativePath: 'context/project_brief.md', scope: 'project' },
+    projectRules: { relativePath: 'rules/project_rules.md', scope: 'project' },
+    projectQa: { relativePath: 'context/project_qa.md', scope: 'project' }
+};
+function isTeamContextKey(value) {
+    return typeof value === 'string' && Object.prototype.hasOwnProperty.call(TEAM_CONTEXT_FILE_MAP, value);
+}
+/**
+ * Resolve the read + write locations for one editable context file.
+ *
+ * - Org scope (org/manager/orgRules/managerRules): a repo-local copy under `fraim/…` wins for
+ *   both read and write when present (so the edit updates the file that actually
+ *   shadows user-level for this repo); otherwise read AND write target the
+ *   user-level `~/.fraim/…` path (where org onboarding writes).
+ * - Project scope (projectContext/projectBrief/projectRules/projectQa): repo-local only.
+ */
+function resolveTeamContextFile(workspaceRoot, key) {
+    const { relativePath, scope } = TEAM_CONTEXT_FILE_MAP[key];
+    const repoPath = (0, path_1.join)((0, project_fraim_paths_1.getWorkspaceFraimDir)(workspaceRoot), 'personalized-employee', relativePath);
+    const repoDisplay = (0, project_fraim_paths_1.getWorkspaceFraimDisplayPath)(`personalized-employee/${relativePath}`);
+    if (scope === 'project') {
+        // Repo-local only — read and write are the same path.
+        return {
+            present: (0, fs_1.existsSync)(repoPath),
+            readPath: (0, fs_1.existsSync)(repoPath) ? repoPath : '',
+            writePath: repoPath,
+            displayPath: repoDisplay,
+            scope
+        };
+    }
+    // Org scope: repo-local override wins when present.
+    if ((0, fs_1.existsSync)(repoPath)) {
+        return {
+            present: true,
+            readPath: repoPath,
+            writePath: repoPath,
+            displayPath: repoDisplay,
+            scope
+        };
+    }
+    // Synced org cache (org files only, never manager files — R3.3). Reads
+    // resolve here, but the cache is managed content: it is never a write
+    // 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, project_fraim_paths_1.getUserFraimDirPath)(), 'org', relativePath);
+        if ((0, fs_1.existsSync)(cachePath)) {
+            return {
+                present: true,
+                readPath: cachePath,
+                writePath: '',
+                displayPath: (0, project_fraim_paths_1.getUserFraimDisplayPath)(`org/${relativePath}`),
+                scope,
+                managedByOrgSync: true
+            };
+        }
+    }
+    if (key === 'manager' || key === 'managerRules') {
+        const managerCachePath = (0, path_1.join)((0, project_fraim_paths_1.getUserFraimDirPath)(), 'manager', relativePath);
+        if ((0, fs_1.existsSync)(managerCachePath)) {
+            return {
+                present: true,
+                readPath: managerCachePath,
+                writePath: '',
+                displayPath: (0, project_fraim_paths_1.getUserFraimDisplayPath)(`manager/${relativePath}`),
+                scope,
+                managedByManagerSync: true
+            };
+        }
+    }
+    const userPath = (0, path_1.join)((0, project_fraim_paths_1.getUserFraimDirPath)(), 'personalized-employee', relativePath);
+    const userDisplay = (0, project_fraim_paths_1.getUserFraimDisplayPath)(`personalized-employee/${relativePath}`);
+    return {
+        present: (0, fs_1.existsSync)(userPath),
+        readPath: (0, fs_1.existsSync)(userPath) ? userPath : '',
+        // No repo-local override exists → write to the portable user-level path,
+        // matching where org onboarding persists these files.
+        writePath: userPath,
+        displayPath: userDisplay,
+        scope
+    };
+}
+// ---------------------------------------------------------------------------
+// Issue #744 — Org brand (Hub cobranding).
+//
+// The brand descriptor (company name/logo/color) is stored ALONGSIDE company
+// info, in the SAME org context storage as org_context.md (manager directive,
+// spec R7.4), as `context/org_brand.json`. Read resolves with the same org-scope
+// layering as org context (repo-local override → synced org cache → user-level);
+// writes target the same writable location org context edits use.
+// ---------------------------------------------------------------------------
+/** Ordered directories to look for org_brand.json, mirroring org-context layering. */
+function orgBrandCandidateDirs(workspaceRoot) {
+    return [
+        (0, path_1.join)((0, project_fraim_paths_1.getWorkspaceFraimDir)(workspaceRoot), 'personalized-employee', 'context'),
+        (0, path_1.join)((0, project_fraim_paths_1.getUserFraimDirPath)(), 'org', 'context'),
+        (0, path_1.join)((0, project_fraim_paths_1.getUserFraimDirPath)(), 'personalized-employee', 'context'),
+    ];
+}
+/** Read the resolved org brand, or null when none is set on this machine. */
+function readOrgBrand(workspaceRoot) {
+    for (const dir of orgBrandCandidateDirs(workspaceRoot)) {
+        const brand = (0, brand_store_1.readBrandFromDir)(dir);
+        if (brand)
+            return brand;
+    }
+    return null;
+}
+/**
+ * Directory an org-brand edit should be written to. Mirrors org-context write
+ * resolution: the repo-local override dir when the repo carries its own org
+ * context, otherwise the portable user-level context dir (where org onboarding
+ * writes). Never the synced org cache (managed, overwritten on sync).
+ */
+function resolveOrgBrandWriteDir(workspaceRoot) {
+    const loc = resolveTeamContextFile(workspaceRoot, 'org');
+    if (loc.writePath)
+        return (0, path_1.dirname)(loc.writePath);
+    return (0, path_1.join)((0, project_fraim_paths_1.getUserFraimDirPath)(), 'personalized-employee', 'context');
+}
+/**
+ * Count the number of `## [P-...]`-style entries inside a preserved learning
+ * file. Returns 0 when the file is absent or unreadable. Counts ALL entries
+ * (not score-gated) — the Brain summary reports preserved learnings, not the
+ * subset above the auto-load threshold.
+ */
+function countLearningEntries(filePath) {
+    if (!(0, fs_1.existsSync)(filePath))
+        return 0;
+    let content;
+    try {
+        content = (0, fs_1.readFileSync)(filePath, 'utf8');
+    }
+    catch {
+        return 0;
+    }
+    let count = 0;
+    const headingRe = learningEntryHeadingRegex();
+    for (const line of content.split(/\r?\n/)) {
+        if (headingRe.test(line))
+            count++;
+    }
+    return count;
+}
+/**
+ * Count preserved learnings by scope for the Brain summary (R14). Organization
+ * = L2 org-* files; manager = the personal manager-coaching file (reverse
+ * mentoring); project = personal mistake/preferences/validated patterns. Raw =
+ * un-dismissed L0 signals still awaiting synthesis. Reuses the same root/file
+ * resolution as buildLearningContextSection so the counts line up with what the
+ * agent actually auto-loads.
+ */
+function countPreservedLearnings(workspaceRoot, userId) {
+    const roots = getLearningRoots(workspaceRoot);
+    const resolvedUserId = resolveLearningUserId(workspaceRoot, userId, roots);
+    // L2 organization-scope preserved files: repo-local override, then the
+    // synced org cache (#563), matching what buildLearningContextSection injects.
+    const organization = countLearningEntries(resolveOrgLearningFile(roots.repoLearningsBase, 'org-mistake-patterns.md').path) +
+        countLearningEntries(resolveOrgLearningFile(roots.repoLearningsBase, 'org-preferences.md').path) +
+        countLearningEntries(resolveOrgLearningFile(roots.repoLearningsBase, 'org-manager-coaching.md').path) +
+        countLearningEntries(resolveOrgLearningFile(roots.repoLearningsBase, 'org-validated-patterns.md').path);
+    const resolve = (fileName) => resolvePersonalLearningFile(roots.repoLearningsBase, roots.managerCacheBase, roots.managerCacheDisplayBase, roots.globalPersonalBase, roots.globalPersonalDisplayBase, fileName);
+    // L1 manager-facing reverse-mentoring file.
+    const manager = countLearningEntries(resolve(`${resolvedUserId}-manager-coaching.md`).path);
+    // L1 personal work patterns (project scope).
+    const project = countLearningEntries(resolve(`${resolvedUserId}-mistake-patterns.md`).path) +
+        countLearningEntries(resolve(`${resolvedUserId}-preferences.md`).path) +
+        countLearningEntries(resolve(`${resolvedUserId}-validated-patterns.md`).path);
+    // 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
+        }
+    }
+    return { organization, manager, project, rawSignals };
+}
+exports.CATEGORY_TO_FILETYPE = {
+    avoid: 'mistake-patterns',
+    preference: 'preferences',
+    repeat: 'validated-patterns',
+    coaching: 'manager-coaching',
+};
+const FILETYPE_TO_CATEGORY = {
+    'mistake-patterns': 'avoid',
+    'preferences': 'preference',
+    'validated-patterns': 'repeat',
+    'manager-coaching': 'coaching',
+};
+// Parse the `## [P-…] Title` entries (and their body prose) out of one learning
+// file. Score/Last seen/Recurrences metadata lines are dropped — the Hub shows
+// the human-readable learning, not the bookkeeping.
+function parseLearningEntries(filePath, displayPath, category, level) {
+    if (!(0, fs_1.existsSync)(filePath))
+        return [];
+    let content;
+    try {
+        content = (0, fs_1.readFileSync)(filePath, 'utf8');
+    }
+    catch {
+        return [];
+    }
+    const out = [];
+    let current = null;
+    let bodyLines = [];
+    const flush = () => {
+        if (current) {
+            current.body = bodyLines.join('\n').replace(/\n{3,}/g, '\n\n').trim();
+            out.push(current);
+        }
+        current = null;
+        bodyLines = [];
+    };
+    const headingRe = learningEntryHeadingRegex();
+    for (const line of content.split(/\r?\n/)) {
+        const header = line.match(headingRe);
+        if (header) {
+            flush();
+            current = { severity: header[1], title: header[2].trim(), body: '', source: displayPath, category, level };
+            continue;
+        }
+        if (!current)
+            continue;
+        if (line.trim() === '---') {
+            flush();
+            continue;
+        }
+        // Drop the bookkeeping lines — the Hub shows the human-readable learning,
+        // not the scoring metadata.
+        const t = line.trim();
+        if (/^\*\*(Score|Last seen|Recurrences|Technical trace|Users|First synthesized)\*\*:/i.test(t))
+            continue;
+        if (/^(First|Last) synthesized:/i.test(t))
+            continue;
+        bodyLines.push(line);
+    }
+    flush();
+    return out;
+}
+function levelDir(roots, level) {
+    if (level === 'machine') {
+        return { dir: roots.globalPersonalBase, displayBase: roots.globalPersonalDisplayBase.replace(/\/$/, '') };
+    }
+    return { dir: roots.repoLearningsBase, displayBase: REPO_LEARNINGS_REL };
+}
+function readPreservedLearnings(workspaceRoot, userId, scope, level = 'machine') {
+    const roots = getLearningRoots(workspaceRoot);
+    const out = [];
+    if (scope === 'org') {
+        for (const cat of ['avoid', 'preference', 'repeat', 'coaching']) {
+            const f = `org-${exports.CATEGORY_TO_FILETYPE[cat]}.md`;
+            out.push(...parseLearningEntries((0, path_1.join)(roots.repoLearningsBase, f), `${REPO_LEARNINGS_REL}/${f}`, cat, 'org'));
+        }
+        return out;
+    }
+    const resolvedUserId = resolveLearningUserId(workspaceRoot, userId, roots);
+    const { dir, displayBase } = levelDir(roots, level);
+    const cats = scope === 'reverse' ? ['coaching'] : ['avoid', 'preference', 'repeat'];
+    for (const cat of cats) {
+        const f = `${resolvedUserId}-${exports.CATEGORY_TO_FILETYPE[cat]}.md`;
+        out.push(...parseLearningEntries((0, path_1.join)(dir, f), `${displayBase}/${f}`, cat, level));
+    }
+    return out;
+}
+function resolveLearningFilePath(workspaceRoot, userId, ref) {
+    const roots = getLearningRoots(workspaceRoot);
+    const fileType = exports.CATEGORY_TO_FILETYPE[ref.category];
+    if (ref.scope === 'org')
+        return (0, path_1.join)(roots.repoLearningsBase, `org-${fileType}.md`);
+    const resolvedUserId = resolveLearningUserId(workspaceRoot, userId, roots);
+    const base = ref.level === 'project' ? roots.repoLearningsBase : roots.globalPersonalBase;
+    return (0, path_1.join)(base, `${resolvedUserId}-${fileType}.md`);
+}
+function titleCaseFromFileType(fileType) {
+    return fileType.split('-').map((w) => w.charAt(0).toUpperCase() + w.slice(1)).join(' ');
+}
+function applyLearningEntryChange(workspaceRoot, userId, ref, action, payload) {
+    const filePath = resolveLearningFilePath(workspaceRoot, userId, ref);
+    const existing = (0, fs_1.existsSync)(filePath) ? (0, fs_1.readFileSync)(filePath, 'utf8') : '';
+    const nl = existing.includes('\r\n') ? '\r\n' : '\n';
+    const lines = existing.length ? existing.split(/\r?\n/) : [];
+    const headingRe = learningEntryHeadingRegex();
+    const starts = [];
+    lines.forEach((l, i) => { if (headingRe.test(l))
+        starts.push(i); });
+    const write = (text) => {
+        (0, fs_1.mkdirSync)((0, path_1.dirname)(filePath), { recursive: true });
+        (0, fs_1.writeFileSync)(filePath, text.replace(/\s*$/, '') + nl, 'utf8');
+    };
+    if (action === 'add') {
+        const sev = (payload.severity || 'P-MED');
+        const title = (payload.title || '').trim() || 'Untitled learning';
+        const body = String(payload.body || '').trim();
+        const block = [`#### [${sev}] ${title}`, '', body, '', '---'].join(nl);
+        const fileType = exports.CATEGORY_TO_FILETYPE[ref.category];
+        const preamble = existing.trim()
+            ? existing.replace(/\s*$/, '')
+            : `# ${ref.scope === 'org' ? 'Org ' : ''}${titleCaseFromFileType(fileType)}`;
+        write(preamble + nl + nl + block);
+        return { ok: true, path: filePath };
+    }
+    const targetIdx = starts.findIndex((s) => {
+        const m = lines[s].match(headingRe);
+        return m && m[2].trim() === (payload.originalTitle || '').trim();
+    });
+    if (targetIdx === -1)
+        throw new Error(`Learning entry not found: "${payload.originalTitle}"`);
+    const start = starts[targetIdx];
+    const end = targetIdx + 1 < starts.length ? starts[targetIdx + 1] : lines.length;
+    if (action === 'delete') {
+        const next = [...lines.slice(0, start), ...lines.slice(end)];
+        write(next.join(nl).replace(/\n{3,}/g, '\n\n'));
+        return { ok: true, path: filePath };
+    }
+    // edit: keep the entry's metadata lines (Score/Last seen/Recurrences/...) intact,
+    // replace only the heading (priority + title) and the prose body.
+    const headerMatch = lines[start].match(headingRe);
+    const sev = (payload.severity || headerMatch[1]);
+    const title = (payload.title !== undefined ? payload.title : headerMatch[2]).trim();
+    const meta = [];
+    for (const l of lines.slice(start + 1, end)) {
+        const t = l.trim();
+        if (t === '---')
+            continue;
+        if (/^\*\*(Score|Last seen|Recurrences|Technical trace|Users|First synthesized)\*\*:/i.test(t) || /^(First|Last) synthesized:/i.test(t))
+            meta.push(l);
+    }
+    const body = String(payload.body !== undefined ? payload.body : '').trim();
+    const rebuilt = [`#### [${sev}] ${title}`, '', ...meta, ...(meta.length ? [''] : []), body, '', '---'];
+    const next = [...lines.slice(0, start), ...rebuilt, ...lines.slice(end)];
+    write(next.join(nl).replace(/\n{3,}/g, '\n\n'));
+    return { ok: true, path: filePath };
+}
+/**
+ * Interpret a frontmatter flag value (string) as a boolean. Mirrors how the
+ * synthesis jobs treat `dismissed:`/`blessed:` — only an explicit truthy value
+ * counts as set.
+ */
+function isTruthyFlag(value) {
+    if (value === undefined)
+        return false;
+    const normalized = value.trim().toLowerCase();
+    if (!normalized)
+        return false;
+    return normalized === 'true' || normalized === 'yes' || normalized === '1';
+}