fraim-framework 2.0.160 → 2.0.162

package/dist/src/cli/commands/init-project.js

@@ -235,7 +235,13 @@ const runInitProject = async (options = {}) => {
         }
         result.warnings.push(`${configDisplayPath} was not created by init-project. The manager \`project-onboarding\` job is the only supported config-writing path.`);
     }
-    ['jobs', 'ai-employee/jobs', 'ai-employee/skills', 'ai-manager/jobs', 'personalized-employee'].forEach((dir) => {
+    [
+        'jobs',
+        'ai-employee/jobs',
+        'ai-employee/skills',
+        'ai-manager/jobs',
+        'personalized-employee',
+    ].forEach((dir) => {
         const dirPath = path_1.default.join(fraimDir, dir);
         if (!fs_1.default.existsSync(dirPath)) {
             fs_1.default.mkdirSync(dirPath, { recursive: true });

package/dist/src/cli/utils/agent-adapters.js

@@ -71,7 +71,7 @@ This repository uses FRAIM.
 - When users ask for next step recommendations, use recommend-next-job skill under \`${employeeSkillsPath}/\` to gather context before suggesting jobs.
 
 > [!IMPORTANT]
-> **Job stubs are for discovery only.** When a user @mentions or references any file under \`${employeeJobsPath}/\` or \`${managerJobsPath}/\`, do NOT attempt to execute the job from the stub content. The stub only shows intent and phase names. Always call \`get_fraim_job({ job: "<job-name>" })\` first to get the full phased instructions before doing any work.
+> **Job stubs are for discovery only.** When a user mentions or references any file under \`${employeeJobsPath}/\` or \`${managerJobsPath}/\`, do NOT attempt to execute the job from the stub content. The stub only shows intent and phase names. Always call \`get_fraim_job({ job: "<job-name>" })\` first to get the full phased instructions before doing any work.
 `);
     const cursorManagedBody = buildManagedSection(`
 # FRAIM

package/dist/src/core/fraim-config-schema.generated.js

@@ -349,6 +349,51 @@ exports.FRAIM_CONFIG_SCHEMA = {
                                 }
                             }
                         },
+                        "playbooks": {
+                            "kind": "object",
+                            "properties": {
+                                "directory": {
+                                    "kind": "string"
+                                },
+                                "decisionCommand": {
+                                    "kind": "string"
+                                },
+                                "decisionTimeoutMs": {
+                                    "kind": "number"
+                                }
+                            }
+                        },
+                        "actionAdapters": {
+                            "kind": "record",
+                            "value": {
+                                "kind": "object",
+                                "properties": {
+                                    "type": {
+                                        "kind": "enum",
+                                        "values": [
+                                            "command",
+                                            "manual",
+                                            "handoff"
+                                        ]
+                                    },
+                                    "command": {
+                                        "kind": "string"
+                                    },
+                                    "timeoutMs": {
+                                        "kind": "number"
+                                    },
+                                    "targetSystem": {
+                                        "kind": "string"
+                                    },
+                                    "targetIdentityProvider": {
+                                        "kind": "string"
+                                    },
+                                    "instructions": {
+                                        "kind": "string"
+                                    }
+                                }
+                            }
+                        },
                         "queue": {
                             "kind": "object",
                             "properties": {
@@ -407,17 +452,6 @@ exports.FRAIM_CONFIG_SCHEMA = {
                                         "requireApprovalState": {
                                             "kind": "string"
                                         },
-                                        "selector": {
-                                            "kind": "object",
-                                            "properties": {
-                                                "shortDescriptionContains": {
-                                                    "kind": "array",
-                                                    "element": {
-                                                        "kind": "string"
-                                                    }
-                                                }
-                                            }
-                                        },
                                         "microsoftPasswordReset": {
                                             "kind": "object",
                                             "properties": {
@@ -564,6 +598,11 @@ exports.SUPPORTED_FRAIM_CONFIG_PATHS = [
     "automation.support.contextResolver.scriptPath",
     "automation.support.contextResolver.arguments",
     "automation.support.contextResolver.timeoutMs",
+    "automation.support.playbooks",
+    "automation.support.playbooks.directory",
+    "automation.support.playbooks.decisionCommand",
+    "automation.support.playbooks.decisionTimeoutMs",
+    "automation.support.actionAdapters",
     "automation.support.queue",
     "automation.support.queue.provider",
     "automation.support.queue.table",
@@ -579,8 +618,6 @@ exports.SUPPORTED_FRAIM_CONFIG_PATHS = [
     "automation.support.requestTypes.password_reset",
     "automation.support.requestTypes.password_reset.mode",
     "automation.support.requestTypes.password_reset.requireApprovalState",
-    "automation.support.requestTypes.password_reset.selector",
-    "automation.support.requestTypes.password_reset.selector.shortDescriptionContains",
     "automation.support.requestTypes.password_reset.microsoftPasswordReset",
     "automation.support.requestTypes.password_reset.microsoftPasswordReset.resetType",
     "automation.support.requestTypes.password_reset.microsoftPasswordReset.providedPasswordEnvVar",

package/dist/src/core/quality-evidence.js

@@ -267,6 +267,7 @@ function buildQualityRejectionMessage(jobName, currentPhase, errors) {
         ? [
             '```javascript',
             'evidence: {',
+            '  artifactPath: "<project-relative quality artifact path>",',
             '  quality: {',
             '    gateDecision: "<pass|flag|fail>",',
             '    interviewsAnalyzed: <number>,',
@@ -281,6 +282,7 @@ function buildQualityRejectionMessage(jobName, currentPhase, errors) {
             ? [
                 '```javascript',
                 'evidence: {',
+                '  artifactPath: "<project-relative quality artifact path>",',
                 '  quality: {',
                 '    composite: <number 0-10>,',
                 '    participant: { fit: <number 1-10>, urgency: <number 1-10>, authority: <number 1-10> },',
@@ -298,6 +300,7 @@ function buildQualityRejectionMessage(jobName, currentPhase, errors) {
             : [
                 '```javascript',
                 'evidence: {',
+                '  artifactPath: "<project-relative quality artifact path>",',
                 '  quality: {',
                 '    composite: <number 0-10>,',
                 '    coaching: "<actionable recommendation>",',
@@ -315,7 +318,7 @@ function buildQualityRejectionMessage(jobName, currentPhase, errors) {
     return [
         `❌ **Job completion rejected** for \`${jobName}\`.`,
         '',
-        `This job is required to emit a quality score on its final \`seekMentoring\` call so the result is captured in \`fraim_quality_scores\` for the quality dashboard. The following problems were found in \`evidence.quality\`:`,
+        `This job is required to emit quality evidence on its final \`seekMentoring\` call so the result is captured in \`fraim_quality_scores\` for the quality dashboard. The following problems were found:`,
         '',
         errorBullets,
         ...importantNote,

package/dist/src/local-mcp-server/agent-token-prices.js

@@ -86,6 +86,29 @@ exports.AGENT_TOKEN_PRICES = [
         source: 'https://openai.com/api/pricing/ (gpt-5 row, applied to gpt-5.5 as nearest published rate)',
         verifiedOn: '2026-04-30',
     },
+    // Google — Gemini CLI. Standard paid-tier text/image/video token rates.
+    // Context caching maps to cache reads; the published storage-hour price
+    // cannot be derived from the CLI token stats and is intentionally omitted.
+    {
+        agent: 'gemini',
+        model: 'gemini-3.1-flash-lite',
+        inputPerMTok: 0.25,
+        outputPerMTok: 1.50,
+        cacheReadPerMTok: 0.025,
+        cacheCreationPerMTok: 0,
+        source: 'https://ai.google.dev/gemini-api/docs/pricing',
+        verifiedOn: '2026-06-02',
+    },
+    {
+        agent: 'gemini',
+        model: 'gemini-3-flash-preview',
+        inputPerMTok: 0.50,
+        outputPerMTok: 3.00,
+        cacheReadPerMTok: 0.05,
+        cacheCreationPerMTok: 0,
+        source: 'https://ai.google.dev/gemini-api/docs/pricing',
+        verifiedOn: '2026-06-02',
+    },
 ];
 /**
  * Look up the price entry for an agent + model. Agent is matched

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

@@ -6,8 +6,18 @@
  * 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.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");
@@ -17,6 +27,22 @@ const AGING_HORIZON_DAYS = 7;
 const MAX_ENTRIES_SCANNED = 200;
 const BACKLOG_MIN = 5;
 const OLDEST_AGE_DAYS_TRIGGER = 3;
+// ── 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),
@@ -152,7 +178,7 @@ function getScoreThreshold(workspaceRoot) {
  *            calculations). Defaults to the current wall clock.
  */
 function computeEffectiveScore(severity, lastSeenDate, recurrences, fileType, now = new Date()) {
-    const baseScore = severity === 'P-HIGH' ? 8 : severity === 'P-MED' ? 5 : 3;
+    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;
@@ -210,7 +236,7 @@ function scanMistakePatternFile(filePath, threshold, fileType = 'mistake-pattern
     for (const line of lines) {
         if (scanned >= MAX_ENTRIES_SCANNED)
             break;
-        const headerMatch = line.match(/^## \[(P-HIGH|P-MED|P-LOW)\]/);
+        const headerMatch = line.match(learningEntryHeadingRegex());
         if (headerMatch) {
             flush();
             inEntry = true;
@@ -438,6 +464,416 @@ function buildLearningContextSection(workspaceRoot, userId, forJob) {
     }
     return section;
 }
+/**
+ * Resolve an organization/manager-scope context file. These are user-level and
+ * portable across repos, but a repo-local copy (under `fraim/…`) wins when
+ * present — mirroring how personal learnings layer (repo-local shadows
+ * user-level) in `resolvePersonalLearningFile`.
+ */
+function resolveOrgContextFile(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}`)
+            };
+        }
+        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 (user-level, portable; repo-local override wins).
+    const orgContext = resolveOrgContextFile(workspaceRoot, 'context/org_context.md');
+    const managerContext = resolveOrgContextFile(workspaceRoot, 'context/manager_context.md');
+    const orgRules = resolveOrgContextFile(workspaceRoot, 'rules/org_rules.md');
+    const managerRules = resolveOrgContextFile(workspaceRoot, 'rules/manager_rules.md');
+    // 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'),
+        orgRules: resolveOrgContextFile(workspaceRoot, 'rules/org_rules.md'),
+        managerRules: resolveOrgContextFile(workspaceRoot, 'rules/manager_rules.md'),
+        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
+        };
+    }
+    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
+    };
+}
+/**
+ * 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 org-* files).
+    const organization = countLearningEntries((0, path_1.join)(roots.repoLearningsBase, 'org-mistake-patterns.md')) +
+        countLearningEntries((0, path_1.join)(roots.repoLearningsBase, 'org-preferences.md')) +
+        countLearningEntries((0, path_1.join)(roots.repoLearningsBase, 'org-manager-coaching.md')) +
+        countLearningEntries((0, path_1.join)(roots.repoLearningsBase, 'org-validated-patterns.md'));
+    const resolve = (fileName) => resolvePersonalLearningFile(roots.repoLearningsBase, 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';
+}
 function renderBacklogDetail(oldestAgeDays, agingRisk) {
     if (oldestAgeDays <= 0 && agingRisk <= 0)
         return '';