fraim 2.0.117 → 2.0.120

package/dist/src/cli/commands/add-ide.js

@@ -268,7 +268,8 @@ const listSupportedIDEs = () => {
         console.log(chalk_1.default.gray(`      Config: ${ide.configPath}\n`));
     });
     console.log(chalk_1.default.yellow('💡 Use "fraim add-ide --ide <name>" to configure a specific IDE'));
-    console.log(chalk_1.default.yellow('   Example: fraim add-ide --ide claude'));
+    console.log(chalk_1.default.yellow('   Example: fraim add-ide --ide claude-code'));
+    console.log(chalk_1.default.yellow('   Anthropic aliases: claude, claude-code, claude-desktop, claude-cowork'));
 };
 const promptForIDESelection = async (availableIDEs, tokens) => {
     console.log(chalk_1.default.green(`✅ Found ${availableIDEs.length} IDEs that can be configured:\n`));
@@ -356,7 +357,7 @@ const runAddIDE = async (options) => {
     const detectedIDEs = (0, ide_detector_1.detectInstalledIDEs)();
     if (detectedIDEs.length === 0) {
         console.log(chalk_1.default.yellow('⚠️ No supported IDEs detected on your system.'));
-        console.log(chalk_1.default.gray('Supported IDEs: Claude, Antigravity, Kiro, Cursor, VSCode, Codex, Windsurf'));
+        console.log(chalk_1.default.gray('Supported IDEs: Claude, Claude Code, Antigravity, Kiro, Cursor, VSCode, Codex, Windsurf'));
         console.log(chalk_1.default.blue('\n💡 Install an IDE and run this command again.'));
         return;
     }
@@ -420,16 +421,21 @@ const runAddIDE = async (options) => {
         });
     }
     if (results.successful.length > 0) {
+        const { describeConfiguredInvocationSurfaces } = await Promise.resolve().then(() => __importStar(require('../setup/ide-global-integration')));
+        const successfulIDEs = idesToConfigure.filter(ide => results.successful.includes(ide.name));
+        const invocationSummaries = describeConfiguredInvocationSurfaces(successfulIDEs);
         console.log(chalk_1.default.blue('\n🔄 Next steps:'));
         console.log(chalk_1.default.cyan('   1. Restart your configured IDEs'));
-        console.log(chalk_1.default.cyan('   2. In any FRAIM-enabled repo, tell your AI agent: "Onboard this project"'));
+        invocationSummaries.forEach((summary, index) => {
+            console.log(chalk_1.default.cyan(`   ${index + 2}. ${summary}`));
+        });
         console.log(chalk_1.default.blue('\n💡 Use "fraim doctor --test-mcp" to verify the configuration.'));
     }
 };
 exports.runAddIDE = runAddIDE;
 exports.addIDECommand = new commander_1.Command('add-ide')
     .description('Add FRAIM configuration to additional IDEs')
-    .option('--ide <name>', 'Configure specific IDE (claude, claude-code, antigravity, kiro, cursor, vscode, codex, windsurf)')
+    .option('--ide <name>', 'Configure specific IDE (claude, claude-code, claude-desktop, claude-cowork, antigravity, kiro, cursor, vscode, codex, windsurf)')
     .option('--all', 'Configure all detected IDEs')
     .option('--list', 'List all supported IDEs and their detection status')
     .action(exports.runAddIDE);

package/dist/src/cli/commands/setup.js

@@ -681,12 +681,12 @@ const runSetup = async (options) => {
     else {
         console.log(chalk_1.default.cyan('\n  Get started — open your AI tool and:'));
     }
-    // Check if Claude is among configured IDEs
-    const hasClaude = configuredIDEs.some(ide => ide.name.toLowerCase().includes('claude'));
-    if (hasClaude) {
-        console.log(chalk_1.default.white('    /fraim                           ') + chalk_1.default.gray('(Claude Code) Browse all jobs'));
-    }
-    console.log(chalk_1.default.white('    "What can FRAIM help me with?"   ') + chalk_1.default.gray('Works in any AI tool'));
+    const { describeConfiguredInvocationSurfaces } = await Promise.resolve().then(() => __importStar(require('../setup/ide-global-integration')));
+    const invocationSummaries = describeConfiguredInvocationSurfaces(configuredIDEs);
+    invocationSummaries.forEach((summary) => {
+        console.log(chalk_1.default.white(`    ${summary}`));
+    });
+    console.log(chalk_1.default.white('    "What can FRAIM help me with?"'));
     console.log(chalk_1.default.gray('\n  Just tell your AI what you need — FRAIM will find the right job.'));
     if (mode !== 'conversational') {
         console.log(chalk_1.default.cyan('\n  To set up FRAIM in a specific project:'));

package/dist/src/cli/mcp/command-resolution.js

@@ -0,0 +1,45 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.resolveManagedCommand = exports.getPortableNpxCommand = void 0;
+const fs_1 = __importDefault(require("fs"));
+const path_1 = __importDefault(require("path"));
+const project_fraim_paths_1 = require("../../core/utils/project-fraim-paths");
+const getPortableNodeRoot = () => path_1.default.join((0, project_fraim_paths_1.getUserFraimDirPath)(), 'node');
+const getPortableNpxCandidates = () => {
+    const nodeRoot = getPortableNodeRoot();
+    if (process.platform === 'win32') {
+        const candidates = [path_1.default.join(nodeRoot, 'npx.cmd')];
+        if (fs_1.default.existsSync(nodeRoot)) {
+            const extractedDirs = fs_1.default.readdirSync(nodeRoot, { withFileTypes: true })
+                .filter((entry) => entry.isDirectory() && entry.name.startsWith('node-v'))
+                .sort((a, b) => b.name.localeCompare(a.name));
+            for (const entry of extractedDirs) {
+                candidates.push(path_1.default.join(nodeRoot, entry.name, 'npx.cmd'));
+            }
+        }
+        return candidates;
+    }
+    return [
+        path_1.default.join(nodeRoot, 'bin', 'npx'),
+        path_1.default.join(nodeRoot, 'npx')
+    ];
+};
+const getPortableNpxCommand = () => {
+    for (const candidate of getPortableNpxCandidates()) {
+        if (fs_1.default.existsSync(candidate)) {
+            return candidate;
+        }
+    }
+    return null;
+};
+exports.getPortableNpxCommand = getPortableNpxCommand;
+const resolveManagedCommand = (command) => {
+    if (command !== 'npx') {
+        return command;
+    }
+    return (0, exports.getPortableNpxCommand)() || command;
+};
+exports.resolveManagedCommand = resolveManagedCommand;

package/dist/src/cli/mcp/ide-formats.js

@@ -6,6 +6,7 @@ exports.IDE_FORMATS = exports.CodexFormat = exports.WindsurfFormat = exports.Cla
 exports.getIDEFormat = getIDEFormat;
 const mcp_server_registry_1 = require("./mcp-server-registry");
 const provider_registry_1 = require("../providers/provider-registry");
+const command_resolution_1 = require("./command-resolution");
 // Standard format (Cursor, Kiro, Antigravity, etc.)
 class StandardFormat {
     constructor() {
@@ -160,7 +161,7 @@ class WindsurfFormat {
                 if (tokenEnvVar && server.headers?.Authorization) {
                     const token = server.headers.Authorization.replace('Bearer ', '');
                     mcpServers[key] = {
-                        command: 'npx',
+                        command: (0, command_resolution_1.resolveManagedCommand)('npx'),
                         args: ['-y', '@modelcontextprotocol/server-fetch', server.url],
                         env: {
                             [tokenEnvVar]: token

package/dist/src/cli/mcp/mcp-server-registry.js

@@ -9,13 +9,14 @@ exports.isProviderServer = isProviderServer;
 exports.isHTTPServer = isHTTPServer;
 exports.buildAllBaseServers = buildAllBaseServers;
 const provider_registry_1 = require("../providers/provider-registry");
+const command_resolution_1 = require("./command-resolution");
 exports.BASE_MCP_SERVERS = [
     {
         id: 'git',
         name: 'Git',
         description: 'Git repository operations (commit, branch, merge, etc.)',
         buildServer: () => ({
-            command: 'npx',
+            command: (0, command_resolution_1.resolveManagedCommand)('npx'),
             args: ['-y', '@cyanheads/git-mcp-server']
         })
     },
@@ -24,7 +25,7 @@ exports.BASE_MCP_SERVERS = [
         name: 'Playwright',
         description: 'Browser automation and testing',
         buildServer: () => ({
-            command: 'npx',
+            command: (0, command_resolution_1.resolveManagedCommand)('npx'),
             args: ['-y', '@playwright/mcp']
         })
     },
@@ -33,7 +34,7 @@ exports.BASE_MCP_SERVERS = [
         name: 'FRAIM',
         description: 'FRAIM job orchestration and mentoring',
         buildServer: (fraimKey) => ({
-            command: 'npx',
+            command: (0, command_resolution_1.resolveManagedCommand)('npx'),
             args: ['-y', 'fraim-framework@latest', 'mcp'],
             env: {
                 // Include API key for IDE configs (Codex, VSCode, etc.)
@@ -119,7 +120,7 @@ function buildStdioServer(mcpConfig, token, config) {
         }
     }
     return {
-        command: mcpConfig.command,
+        command: (0, command_resolution_1.resolveManagedCommand)(mcpConfig.command),
         args: (mcpConfig.args || []).map(resolveTemplate),
         env
     };

package/dist/src/cli/setup/auto-mcp-setup.js

@@ -55,6 +55,10 @@ const normalizePlatformTokens = (tokenInput) => {
 };
 const promptForIDESelection = async (detectedIDEs, tokenInput) => {
     const tokens = normalizePlatformTokens(tokenInput);
+    if (process.env.FRAIM_NON_INTERACTIVE) {
+        console.log(chalk_1.default.yellow(`\nℹ️  Non-interactive mode: configuring all detected IDEs (${detectedIDEs.length})`));
+        return detectedIDEs;
+    }
     console.log(chalk_1.default.green(`✅ Found ${detectedIDEs.length} IDEs that can be configured with FRAIM:\n`));
     detectedIDEs.forEach((ide, index) => {
         const configExists = fs_1.default.existsSync((0, ide_detector_1.expandPath)(ide.configPath));
@@ -253,6 +257,10 @@ const autoConfigureMCP = async (fraimKey, tokenInput, selectedIDEs, providerConf
         console.log(chalk_1.default.gray('Supported IDEs: Claude, Antigravity, Kiro, Cursor, VSCode, Codex, Windsurf'));
         console.log(chalk_1.default.blue('\n💡 You can install an IDE and run setup again later.'));
         console.log(chalk_1.default.gray('   Or continue with manual MCP configuration.'));
+        if (process.env.FRAIM_NON_INTERACTIVE) {
+            console.log(chalk_1.default.yellow('ℹ️  Non-interactive mode: skipping IDE configuration because no supported IDEs were detected.'));
+            return;
+        }
         const continueAnyway = await (0, prompts_1.default)({
             type: 'confirm',
             name: 'continue',

package/dist/src/cli/setup/ide-detector.js

@@ -60,28 +60,33 @@ exports.IDE_CONFIGS = [
         configPath: '~/.claude.json',
         configFormat: 'json',
         configType: 'claude-code',
+        invocationProfile: 'claude-slash',
         detectMethod: detectClaude,
+        aliases: ['claude-code', 'claude code', 'claude code cli', 'code tab'],
         alternativePaths: [
             '~/.claude/settings.json'
         ],
-        description: 'Anthropic Claude Code CLI tool'
+        description: 'Anthropic Claude Code local surfaces (CLI and Desktop Code tab)'
     },
     {
         name: 'Claude Desktop / Cowork',
         configPath: '~/AppData/Roaming/Claude/claude_desktop_config.json',
         configFormat: 'json',
         configType: 'claude',
+        invocationProfile: 'launch-phrase',
         detectMethod: detectClaude,
+        aliases: ['claude', 'claude-desktop', 'claude desktop', 'claude-cowork', 'cowork', 'claude cowork'],
         alternativePaths: [
             '~/Library/Application Support/Claude/claude_desktop_config.json'
         ],
-        description: 'Anthropic Claude Desktop and Cowork application'
+        description: 'Anthropic Claude Desktop chat and Cowork surfaces'
     },
     {
         name: 'Antigravity',
         configPath: '~/.gemini/antigravity/mcp_config.json',
         configFormat: 'json',
         configType: 'standard',
+        invocationProfile: 'instructions-only',
         detectMethod: () => fs_1.default.existsSync(expandPath('~/.gemini/antigravity')),
         description: 'Google Gemini Antigravity IDE'
     },
@@ -90,6 +95,7 @@ exports.IDE_CONFIGS = [
         configPath: '~/.kiro/settings/mcp.json',
         configFormat: 'json',
         configType: 'kiro',
+        invocationProfile: 'kiro-hashtag',
         detectMethod: () => fs_1.default.existsSync(expandPath('~/.kiro')),
         description: 'Kiro AI-powered IDE'
     },
@@ -98,6 +104,7 @@ exports.IDE_CONFIGS = [
         configPath: '~/.cursor/mcp.json',
         configFormat: 'json',
         configType: 'kiro',
+        invocationProfile: 'cursor-mention',
         detectMethod: detectCursor,
         alternativePaths: [
             '~/Library/Application Support/Cursor/mcp.json',
@@ -115,6 +122,7 @@ exports.IDE_CONFIGS = [
                 : '~/.config/Code/User/mcp.json',
         configFormat: 'json',
         configType: 'vscode',
+        invocationProfile: 'vscode-prompt',
         detectMethod: detectVSCode,
         alternativePaths: [
             '~/Library/Application Support/Code/User/mcp.json',
@@ -128,6 +136,7 @@ exports.IDE_CONFIGS = [
         configPath: '~/.codex/config.toml',
         configFormat: 'toml',
         configType: 'codex',
+        invocationProfile: 'codex-skill',
         detectMethod: () => fs_1.default.existsSync(expandPath('~/.codex')),
         description: 'Codex AI development environment'
     },
@@ -136,6 +145,7 @@ exports.IDE_CONFIGS = [
         configPath: '~/.codeium/windsurf/mcp_config.json',
         configFormat: 'json',
         configType: 'windsurf',
+        invocationProfile: 'windsurf-command',
         detectMethod: detectWindsurf,
         alternativePaths: [
             '~/Library/Application Support/Windsurf/mcp_config.json',
@@ -173,7 +183,9 @@ const getAllSupportedIDEs = () => {
 };
 exports.getAllSupportedIDEs = getAllSupportedIDEs;
 const findIDEByName = (name) => {
-    return exports.IDE_CONFIGS.find(ide => ide.name.toLowerCase().includes(name.toLowerCase()) ||
-        name.toLowerCase().includes(ide.name.toLowerCase()));
+    const normalized = name.toLowerCase();
+    return exports.IDE_CONFIGS.find(ide => ide.name.toLowerCase().includes(normalized) ||
+        normalized.includes(ide.name.toLowerCase()) ||
+        ide.aliases?.some(alias => alias.includes(normalized) || normalized.includes(alias)));
 };
 exports.findIDEByName = findIDEByName;

package/dist/src/cli/setup/ide-global-integration.js

@@ -3,122 +3,62 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
     return (mod && mod.__esModule) ? mod : { "default": mod };
 };
 Object.defineProperty(exports, "__esModule", { value: true });
+exports.describeConfiguredInvocationSurfaces = describeConfiguredInvocationSurfaces;
 exports.installSlashCommands = installSlashCommands;
 exports.installGlobalRules = installGlobalRules;
 /**
  * IDE Global Integration
  *
- * Installs FRAIM slash commands and global rules into user-level IDE
- * configuration directories. These enable FRAIM to be discoverable
- * in any project without requiring fraim init-project.
- *
- * Part of: User-Level FRAIM Artifacts with Local Shadow Semantics
+ * Installs user-level FRAIM invocation artifacts for supported IDEs.
+ * These surfaces make FRAIM discoverable without requiring `fraim init-project`.
  */
 const fs_1 = __importDefault(require("fs"));
-const path_1 = __importDefault(require("path"));
 const os_1 = __importDefault(require("os"));
+const path_1 = __importDefault(require("path"));
 const chalk_1 = __importDefault(require("chalk"));
-const FRAIM_SLASH_COMMAND_CONTENT = `The user wants to run FRAIM. The requested job or topic is: $ARGUMENTS
-
-Follow this process:
-
-1. **If no argument was given** (the line above ends with ": "):
-   Call \`list_fraim_jobs()\` to discover available jobs. Present the results to the user grouped by business function (the server returns jobs organized by category — use those categories as group headings). For each group, list 3-5 of the most impactful jobs with a one-line description.
-
-   After listing, suggest 2-3 starting points based on what seems most relevant:
-   - If in a code repo: suggest jobs from engineering/product-building categories
-   - If no repo context: suggest jobs from marketing, fundraising, or business categories
-
-   Ask the user which job they want to run, then proceed to step 2.
-
-2. **Find the match**: from the list returned by \`list_fraim_jobs()\`, find the job whose name matches or closely resembles the argument. If no job matches, search for a matching skill by calling \`get_fraim_file({ path: "skills/<likely-category>/<argument>.md" })\` — try common categories like \`engineering/\`, \`marketing/\`, \`business/\`, \`product-management/\`, \`ai-tools/\`. Confirm the match with the user.
-
-3. **Load the full content**:
-   - For jobs: call \`get_fraim_job({ job: "<matched-job-name>" })\` — never execute from stub content.
-   - For skills: the content from \`get_fraim_file\` is the full skill. Use it directly.
-
-4. **Execute**: for jobs, follow the phased instructions returned by \`get_fraim_job\`, using \`seekMentoring\` at phase transitions where indicated. For skills, apply the skill steps to the user's current context.
-`;
-const FRAIM_CURSOR_RULES_CONTENT = `# FRAIM Rules
-
-This workspace uses FRAIM (Framework for Rigor-based AI Management).
-
-## Discovery
-- Before acting on any user request, check if a FRAIM job matches the intent.
-- Call \`list_fraim_jobs()\` to discover available jobs.
-- Call \`get_fraim_job({ job: "<job-name>" })\` to get full phased instructions.
-
-## Execution
-- Jobs are FRAIM's primary execution units — structured, multi-phase workflows.
-- Skills are reusable capabilities that jobs compose.
-- Rules are always-on constraints and conventions.
-- Follow phased instructions and use \`seekMentoring\` at phase transitions.
-
-## Principles
-- Never execute from job stubs — always load full instructions via MCP.
-- Follow the constitution: integrity, correctness, contribution, completeness.
-`;
+const ide_invocation_surfaces_1 = require("./ide-invocation-surfaces");
+function describeConfiguredInvocationSurfaces(installedIDEs) {
+    return installedIDEs.map((ide) => (0, ide_invocation_surfaces_1.describeInvocationSurface)(ide.name, ide.invocationProfile));
+}
 /**
  * Install the FRAIM slash command for Claude Code at the user level.
- * Writes to ~/.claude/commands/fraim.md.
- * Does NOT overwrite if the file already exists.
- *
- * @param homeDir - Override for home directory (for testing)
+ * Writes to ~/.claude/commands/fraim.md and does not overwrite existing files.
  */
 async function installSlashCommands(homeDir) {
     const home = homeDir || os_1.default.homedir();
     const claudeDir = path_1.default.join(home, '.claude');
-    // Only install if Claude Code is installed (indicated by .claude/ existing)
     if (!fs_1.default.existsSync(claudeDir)) {
         return;
     }
-    const commandsDir = path_1.default.join(claudeDir, 'commands');
-    const slashCommandPath = path_1.default.join(commandsDir, 'fraim.md');
-    // Do not overwrite existing file
-    if (fs_1.default.existsSync(slashCommandPath)) {
-        console.log(chalk_1.default.gray('   Claude slash command already exists — skipping'));
-        return;
-    }
-    fs_1.default.mkdirSync(commandsDir, { recursive: true });
-    fs_1.default.writeFileSync(slashCommandPath, FRAIM_SLASH_COMMAND_CONTENT, 'utf8');
-    console.log(chalk_1.default.green('   ✅ Installed Claude slash command (~/.claude/commands/fraim.md)'));
+    installFileIfMissing(path_1.default.join(claudeDir, 'commands', 'fraim.md'), (0, ide_invocation_surfaces_1.buildClaudeSlashCommandContent)(), 'Claude slash command (~/.claude/commands/fraim.md)');
 }
 /**
- * Install FRAIM global rules/instructions for supported IDEs.
+ * Install FRAIM invocation artifacts for non-Claude IDEs.
  * Supports: Cursor, Codex, Windsurf, Kiro
- * Does NOT overwrite if files already exist.
- *
- * @param homeDir - Override for home directory (for testing)
+ * Does not overwrite existing files.
  */
 async function installGlobalRules(homeDir) {
     const home = homeDir || os_1.default.homedir();
-    // Cursor: ~/.cursor/rules/fraim-rules.md
     const cursorDir = path_1.default.join(home, '.cursor');
     if (fs_1.default.existsSync(cursorDir)) {
-        installRuleFile(path_1.default.join(cursorDir, 'rules', 'fraim-rules.md'), FRAIM_CURSOR_RULES_CONTENT, 'Cursor global rules (~/.cursor/rules/fraim-rules.md)');
+        installFileIfMissing(path_1.default.join(cursorDir, 'rules', 'fraim.mdc'), (0, ide_invocation_surfaces_1.buildCursorMentionRuleContent)(), 'Cursor FRAIM rule (~/.cursor/rules/fraim.mdc)');
     }
-    // Codex: ~/.codex/instructions.md
     const codexDir = path_1.default.join(home, '.codex');
     if (fs_1.default.existsSync(codexDir)) {
-        installRuleFile(path_1.default.join(codexDir, 'instructions.md'), FRAIM_CURSOR_RULES_CONTENT, 'Codex global instructions (~/.codex/instructions.md)');
+        installFileIfMissing(path_1.default.join(codexDir, 'skills', 'fraim', 'SKILL.md'), (0, ide_invocation_surfaces_1.buildCodexSkillContent)(), 'Codex FRAIM skill (~/.codex/skills/fraim/SKILL.md)');
     }
-    // Windsurf: ~/.codeium/windsurf/rules/fraim-rules.md
     const windsurfDir = path_1.default.join(home, '.codeium', 'windsurf');
     if (fs_1.default.existsSync(windsurfDir)) {
-        installRuleFile(path_1.default.join(windsurfDir, 'rules', 'fraim-rules.md'), FRAIM_CURSOR_RULES_CONTENT, 'Windsurf global rules (~/.codeium/windsurf/rules/fraim-rules.md)');
+        installFileIfMissing(path_1.default.join(windsurfDir, 'commands', 'fraim.md'), (0, ide_invocation_surfaces_1.buildWindsurfCommandContent)(), 'Windsurf FRAIM command (~/.codeium/windsurf/commands/fraim.md)');
     }
-    // Kiro: ~/.kiro/rules/fraim-rules.md
     const kiroDir = path_1.default.join(home, '.kiro');
     if (fs_1.default.existsSync(kiroDir)) {
-        installRuleFile(path_1.default.join(kiroDir, 'rules', 'fraim-rules.md'), FRAIM_CURSOR_RULES_CONTENT, 'Kiro global rules (~/.kiro/rules/fraim-rules.md)');
+        installFileIfMissing(path_1.default.join(kiroDir, 'commands', 'fraim.md'), (0, ide_invocation_surfaces_1.buildKiroCommandContent)(), 'Kiro FRAIM command (~/.kiro/commands/fraim.md)');
     }
 }
-/**
- * Install a rule file if it doesn't already exist.
- */
-function installRuleFile(filePath, content, displayName) {
+function installFileIfMissing(filePath, content, displayName) {
     if (fs_1.default.existsSync(filePath)) {
-        console.log(chalk_1.default.gray(`   ${displayName.split('(')[0].trim()} already exist — skipping`));
+        console.log(chalk_1.default.gray(`   ${displayName.split('(')[0].trim()} already exists — skipping`));
         return;
     }
     fs_1.default.mkdirSync(path_1.default.dirname(filePath), { recursive: true });

package/dist/src/cli/setup/ide-invocation-surfaces.js

@@ -0,0 +1,79 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.FRAIM_INVOCATION_BODY = exports.CURSOR_MDC_FRONTMATTER = exports.FRAIM_LAUNCH_PHRASE = void 0;
+exports.buildClaudeSlashCommandContent = buildClaudeSlashCommandContent;
+exports.buildCursorMentionRuleContent = buildCursorMentionRuleContent;
+exports.buildCodexSkillContent = buildCodexSkillContent;
+exports.buildWindsurfCommandContent = buildWindsurfCommandContent;
+exports.buildKiroCommandContent = buildKiroCommandContent;
+exports.describeInvocationSurface = describeInvocationSurface;
+exports.FRAIM_LAUNCH_PHRASE = 'Use FRAIM for <job or task>';
+exports.CURSOR_MDC_FRONTMATTER = `---
+description: FRAIM discovery and execution contract
+alwaysApply: true
+---`;
+exports.FRAIM_INVOCATION_BODY = `Follow this process:
+
+1. **If the user did not specify a FRAIM job or topic**:
+   Call \`list_fraim_jobs()\` to discover available jobs. Present the results grouped by the categories returned by the server. For each group, list 3-5 of the most relevant jobs with a one-line description.
+
+2. **Find the match**:
+   Match the user's request to a FRAIM job from \`list_fraim_jobs()\`. If no job matches, try a likely FRAIM skill with \`get_fraim_file({ path: "skills/<likely-category>/<argument>.md" })\` and confirm the match with the user.
+
+3. **Load the full content**:
+   - For jobs, call \`get_fraim_job({ job: "<matched-job-name>" })\`.
+   - For skills, use the content returned by \`get_fraim_file(...)\`.
+
+4. **Execute**:
+   - For jobs, follow the phased instructions and use \`seekMentoring\` when the job requires phase transitions.
+   - For skills, apply the skill steps directly to the user's current context.
+`;
+function buildClaudeSlashCommandContent() {
+    return exports.FRAIM_INVOCATION_BODY;
+}
+function buildCursorMentionRuleContent() {
+    return `${exports.CURSOR_MDC_FRONTMATTER}
+
+# FRAIM
+
+${exports.FRAIM_INVOCATION_BODY}
+`;
+}
+function buildCodexSkillContent() {
+    return `# FRAIM
+
+${exports.FRAIM_INVOCATION_BODY}`;
+}
+function buildWindsurfCommandContent() {
+    return `# FRAIM
+
+${exports.FRAIM_INVOCATION_BODY}`;
+}
+function buildKiroCommandContent() {
+    return `# FRAIM
+
+${exports.FRAIM_INVOCATION_BODY}`;
+}
+function describeInvocationSurface(ideName, invocationProfile) {
+    switch (invocationProfile) {
+        case 'claude-slash':
+            return ideName === 'Claude Code'
+                ? 'Claude Code (CLI/Desktop): /fraim'
+                : `${ideName}: /fraim`;
+        case 'launch-phrase':
+            return `${ideName}: "${exports.FRAIM_LAUNCH_PHRASE}"`;
+        case 'cursor-mention':
+            return `${ideName}: @fraim`;
+        case 'vscode-prompt':
+            return `${ideName}: /fraim via workspace prompt`;
+        case 'codex-skill':
+            return `${ideName}: /fraim, $fraim`;
+        case 'windsurf-command':
+            return `${ideName}: /fraim`;
+        case 'kiro-hashtag':
+            return `${ideName}: #fraim`;
+        case 'instructions-only':
+        default:
+            return `${ideName}: natural language`;
+    }
+}

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

@@ -6,15 +6,16 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.ensureAgentAdapterFiles = ensureAgentAdapterFiles;
 const fs_1 = __importDefault(require("fs"));
 const path_1 = __importDefault(require("path"));
+const ide_invocation_surfaces_1 = require("../setup/ide-invocation-surfaces");
 const project_fraim_paths_1 = require("../../core/utils/project-fraim-paths");
 const START_MARKER = '<!-- FRAIM_AGENT_ADAPTER_START -->';
 const END_MARKER = '<!-- FRAIM_AGENT_ADAPTER_END -->';
 const CURSOR_RULE_PATH = path_1.default.join('.cursor', 'rules', 'fraim.mdc');
 const CLAUDE_FRAIM_COMMAND_PATH = path_1.default.join('.claude', 'commands', 'fraim.md');
-const CURSOR_FRONTMATTER = `---
-description: FRAIM discovery and execution contract
-alwaysApply: true
----`;
+const VSCODE_FRAIM_PROMPT_PATH = path_1.default.join('.github', 'prompts', 'fraim.prompt.md');
+const CODEX_FRAIM_SKILL_PATH = path_1.default.join('.codex', 'skills', 'fraim', 'SKILL.md');
+const WINDSURF_FRAIM_COMMAND_PATH = path_1.default.join('.windsurf', 'commands', 'fraim.md');
+const KIRO_FRAIM_COMMAND_PATH = path_1.default.join('.kiro', 'commands', 'fraim.md');
 function buildManagedSection(body) {
     return `${START_MARKER}
 ${body.trim()}
@@ -40,7 +41,7 @@ function mergeCursorRule(existingContent, managedSection) {
     const normalized = existingContent.replace(/\r\n/g, '\n').trimStart();
     const bodyWithoutLeadingFrontmatter = normalized.replace(/^(?:---\n[\s\S]*?\n---(?:\n+)?)*/, '');
     const mergedBody = mergeManagedSection(bodyWithoutLeadingFrontmatter, managedSection).trim();
-    return `${CURSOR_FRONTMATTER}\n\n${mergedBody}\n`;
+    return `${ide_invocation_surfaces_1.CURSOR_MDC_FRONTMATTER}\n\n${mergedBody}\n`;
 }
 function getAdapterFiles() {
     const fraimRoot = (0, project_fraim_paths_1.getWorkspaceFraimDisplayPath)().replace(/\/$/, '');
@@ -70,15 +71,9 @@ This repository uses FRAIM.
 > **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(`
-Use FRAIM as the repo's execution framework.
+# FRAIM
 
-- Discover available jobs, skills, and rules under \`${fraimRoot}/\`.
-- Jobs are the primary execution units; treat them like first-class workflows.
-- Skills are reusable capability modules jobs compose.
-- Rules are always-on constraints.
-- Repo-specific overrides and learnings under \`${personalizedRootPath}/\` take precedence.
-- Choose a relevant job from the stubs, then call \`get_fraim_job(...)\` for the full phased instructions.
-- **Job stubs are for discovery only.** Never execute a job from stub content — always call \`get_fraim_job({ job: "<job-name>" })\` first.
+${ide_invocation_surfaces_1.FRAIM_INVOCATION_BODY}
 `);
     const copilotBody = buildManagedSection(`
 ## FRAIM
@@ -89,7 +84,7 @@ Use FRAIM as the repo's execution framework.
 - FRAIM rules are always-on constraints and conventions.
 - Repo-specific overrides and learnings live under \`${personalizedRootPath}/\`.
 - Use the stubs to identify which job to invoke before fetching full content with FRAIM MCP tools.
-- **Job stubs are for discovery only.** Never execute a job from stub content — always call \`get_fraim_job({ job: "<job-name>" })\` first.
+- **Job stubs are for discovery only.** Never execute a job from stub content - always call \`get_fraim_job({ job: "<job-name>" })\` first.
 `);
     const fraimReadme = `# FRAIM Catalog
 
@@ -103,25 +98,20 @@ This directory is the repository-visible FRAIM surface.
 
 Use the stubs here to discover which FRAIM job, skill, or rule is relevant, then load the full content through FRAIM MCP tools.
 `;
-    const claudeCommand = `The user wants to run FRAIM. The requested job or topic is: $ARGUMENTS
+    const vscodePrompt = `# FRAIM
 
-Follow this process:
-
-1. **If no argument was given** (the line above ends with ": "): scan all stub files under \`${employeeJobsPath}/\` and \`${managerJobsPath}/\`. List each by filename and its Intent line. Ask the user which job they want to run, then proceed to step 2.
-
-2. **Find the job**: search \`${employeeJobsPath}/\` and \`${managerJobsPath}/\` for a stub whose filename (without \`.md\`) matches or closely resembles the argument. Read the stub's Intent/Outcome to confirm it matches what the user wants.
-
-3. **Load the full job**: call \`get_fraim_job({ job: "<matched-job-name>" })\` — never execute from stub content.
-
-4. **Execute**: follow the phased instructions returned by \`get_fraim_job\`, using \`seekMentoring\` at phase transitions where indicated.
-`;
+${ide_invocation_surfaces_1.FRAIM_INVOCATION_BODY}`;
     return [
         { path: 'AGENTS.md', content: markdownBody },
         { path: 'CLAUDE.md', content: markdownBody },
         { path: path_1.default.join('.github', 'copilot-instructions.md'), content: copilotBody },
         { path: CURSOR_RULE_PATH, content: cursorManagedBody },
+        { path: VSCODE_FRAIM_PROMPT_PATH, content: vscodePrompt },
         { path: path_1.default.join(project_fraim_paths_1.WORKSPACE_FRAIM_DIRNAME, 'README.md'), content: fraimReadme },
-        { path: CLAUDE_FRAIM_COMMAND_PATH, content: claudeCommand }
+        { path: CLAUDE_FRAIM_COMMAND_PATH, content: (0, ide_invocation_surfaces_1.buildClaudeSlashCommandContent)() },
+        { path: CODEX_FRAIM_SKILL_PATH, content: (0, ide_invocation_surfaces_1.buildCodexSkillContent)() },
+        { path: WINDSURF_FRAIM_COMMAND_PATH, content: (0, ide_invocation_surfaces_1.buildWindsurfCommandContent)() },
+        { path: KIRO_FRAIM_COMMAND_PATH, content: (0, ide_invocation_surfaces_1.buildKiroCommandContent)() }
     ];
 }
 function ensureAgentAdapterFiles(projectRoot) {
@@ -135,7 +125,12 @@ function ensureAgentAdapterFiles(projectRoot) {
         const existing = fs_1.default.existsSync(fullPath) ? fs_1.default.readFileSync(fullPath, 'utf8') : '';
         const next = file.path === CURSOR_RULE_PATH
             ? mergeCursorRule(existing, file.content)
-            : file.path.endsWith('README.md') || file.path === CLAUDE_FRAIM_COMMAND_PATH
+            : file.path.endsWith('README.md')
+                || file.path === VSCODE_FRAIM_PROMPT_PATH
+                || file.path === CLAUDE_FRAIM_COMMAND_PATH
+                || file.path === CODEX_FRAIM_SKILL_PATH
+                || file.path === WINDSURF_FRAIM_COMMAND_PATH
+                || file.path === KIRO_FRAIM_COMMAND_PATH
                 ? file.content
                 : mergeManagedSection(existing, file.content);
         if (existing !== next) {

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

@@ -38,6 +38,7 @@ exports.QUALITY_REGISTRY = {
     // Business Strategy
     'review-business-strategy': { stage: 'business-strategy', enforced: true },
     'business-plan-creation': { stage: 'business-strategy', enforced: false },
+    'branding-quality-audit': { stage: 'branding', enforced: true },
     // Product Quality
     'code-quality-assessment': { stage: 'product-quality', enforced: true },
     // Test Quality
@@ -63,6 +64,7 @@ exports.STAGE_CATEGORY_MAP = Object.keys(exports.QUALITY_REGISTRY).reduce((acc,
 exports.STAGE_DISPLAY_NAMES = {
     'customer-development': 'Customer Development',
     'business-strategy': 'Business Strategy',
+    'branding': 'Branding',
     'product-quality': 'Product Quality',
     'test-quality': 'Test Quality',
     'fundraising': 'Fundraising',
@@ -74,6 +76,7 @@ exports.STAGE_DISPLAY_NAMES = {
 exports.ALL_STAGE_CATEGORIES = [
     'customer-development',
     'business-strategy',
+    'branding',
     'product-quality',
     'test-quality',
     'fundraising',

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

@@ -6,37 +6,130 @@
  * workspace root on the user's machine.
  */
 Object.defineProperty(exports, "__esModule", { value: true });
+exports.computeEffectiveScore = computeEffectiveScore;
 exports.buildLearningContextSection = buildLearningContextSection;
 const fs_1 = require("fs");
 const path_1 = require("path");
 const project_fraim_paths_1 = require("../core/utils/project-fraim-paths");
 const 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 BACKLOG_MIN = 5;
+const OLDEST_AGE_DAYS_TRIGGER = 3;
 function getLearningsBase(workspaceRoot) {
     return (0, path_1.join)(workspaceRoot, LEARNINGS_REL);
 }
-function getScoreThreshold(workspaceRoot) {
+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, learningsBase) {
+    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.
+        }
+    };
+    collect(learningsBase, (fileName) => {
+        if (!fileName.endsWith('.md') || fileName.startsWith('org-'))
+            return null;
+        const match = fileName.match(/^(.*?)-(preferences|manager-coaching|mistake-patterns)\.md$/);
+        return match ? match[1] : null;
+    });
+    collect((0, path_1.join)(learningsBase, '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) {
+    const learningsBase = getLearningsBase(workspaceRoot);
+    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)(learningsBase, `${candidate}-preferences.md`)) ? 1 : 0) +
+            ((0, fs_1.existsSync)((0, path_1.join)(learningsBase, `${candidate}-manager-coaching.md`)) ? 1 : 0) +
+            ((0, fs_1.existsSync)((0, path_1.join)(learningsBase, `${candidate}-mistake-patterns.md`)) ? 1 : 0) +
+            countMatchingFilesByPrefix((0, path_1.join)(learningsBase, '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, learningsBase);
+    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)) {
-            const config = JSON.parse((0, fs_1.readFileSync)(configPath, 'utf8'));
-            const t = config?.learning?.scoreThreshold;
-            if (typeof t === 'number' && t > 0)
-                return t;
+            return JSON.parse((0, fs_1.readFileSync)(configPath, 'utf8'));
         }
     }
     catch {
-        // Fall through to default.
+        // 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;
 }
-function computeEffectiveScore(severity, lastSeenDate, recurrences, fileType) {
+/**
+ * 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-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);
-        const now = new Date();
         daysSinceLastSeen = Math.max(0, (now.getTime() - lastSeen.getTime()) / (1000 * 60 * 60 * 24));
     }
     catch {
@@ -46,55 +139,71 @@ function computeEffectiveScore(severity, lastSeenDate, recurrences, fileType) {
     const recurrenceBoost = Math.log2(Math.max(1, recurrences) + 1);
     return baseScore * decay * recurrenceBoost;
 }
-function countMistakePatternEntries(filePath, threshold) {
+function scanMistakePatternFile(filePath, threshold, fileType = 'mistake-patterns') {
+    const empty = { active: 0, dormant: 0, agingRisk: 0 };
     if (!(0, fs_1.existsSync)(filePath))
-        return { active: 0, dormant: 0 };
+        return empty;
+    let content;
     try {
-        const content = (0, fs_1.readFileSync)(filePath, 'utf8');
-        const lines = content.split('\n');
-        let active = 0;
-        let dormant = 0;
-        let inEntry = false;
-        let currentSeverity = null;
-        let currentLastSeen = '';
-        let currentRecurrences = 1;
-        const processCurrentEntry = () => {
-            if (!currentSeverity)
-                return;
-            const score = computeEffectiveScore(currentSeverity, currentLastSeen, currentRecurrences, 'mistake-patterns');
-            if (score >= threshold)
-                active++;
-            else
-                dormant++;
-        };
-        for (const line of lines) {
-            const headerMatch = line.match(/^## \[(P-HIGH|P-MED|P-LOW)\]/);
-            if (headerMatch) {
-                processCurrentEntry();
-                inEntry = true;
-                currentSeverity = headerMatch[1];
-                currentLastSeen = '';
-                currentRecurrences = 1;
-                continue;
-            }
-            if (!inEntry)
-                continue;
-            const lastSeenMatch = line.match(/^\*\*Last seen\*\*:\s*(.+)/);
-            if (lastSeenMatch) {
-                currentLastSeen = lastSeenMatch[1].trim();
-                continue;
-            }
-            const recurrenceMatch = line.match(/^\*\*Recurrences\*\*:\s*(\d+)/);
-            if (recurrenceMatch) {
-                currentRecurrences = parseInt(recurrenceMatch[1], 10);
-            }
-        }
-        processCurrentEntry();
-        return { active, dormant };
+        content = (0, fs_1.readFileSync)(filePath, 'utf8');
     }
     catch {
-        return { active: 0, dormant: 0 };
+        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(/^## \[(P-HIGH|P-MED|P-LOW)\]/);
+        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---/);
@@ -124,28 +233,81 @@ function isUnsynthesizedRetrospective(filePath) {
         return false;
     }
 }
+/** Oldest mtime-age in days across this user's L0 signals. 0 if none. */
+function computeOldestL0AgeDays(workspaceRoot, userId) {
+    const learningsBase = getLearningsBase(workspaceRoot);
+    const now = Date.now();
+    let oldest = 0;
+    const consider = (filePath) => {
+        try {
+            const st = (0, fs_1.statSync)(filePath);
+            const ageDays = Math.floor((now - st.mtimeMs) / (1000 * 60 * 60 * 24));
+            if (ageDays > oldest)
+                oldest = ageDays;
+        }
+        catch {
+            // ignore
+        }
+    };
+    const rawDir = (0, path_1.join)(learningsBase, 'raw');
+    if ((0, fs_1.existsSync)(rawDir)) {
+        try {
+            for (const f of (0, fs_1.readdirSync)(rawDir)) {
+                if (!f.startsWith(`${userId}-`))
+                    continue;
+                consider((0, path_1.join)(rawDir, f));
+            }
+        }
+        catch {
+            // ignore
+        }
+    }
+    const retroDir = (0, path_1.join)(workspaceRoot, 'docs', 'retrospectives');
+    if ((0, fs_1.existsSync)(retroDir)) {
+        try {
+            for (const f of (0, fs_1.readdirSync)(retroDir)) {
+                if (!f.startsWith(`${userId}-`) || !f.endsWith('.md'))
+                    continue;
+                if (!isUnsynthesizedRetrospective((0, path_1.join)(retroDir, f)))
+                    continue;
+                consider((0, path_1.join)(retroDir, f));
+            }
+        }
+        catch {
+            // ignore
+        }
+    }
+    return oldest;
+}
 function buildLearningContextSection(workspaceRoot, userId, forJob) {
     const learningsBase = getLearningsBase(workspaceRoot);
+    const resolvedUserId = resolveLearningUserId(workspaceRoot, userId);
     const threshold = getScoreThreshold(workspaceRoot);
     const l2MistakePath = (0, path_1.join)(learningsBase, 'org-mistake-patterns.md');
     const l2PrefPath = (0, path_1.join)(learningsBase, 'org-preferences.md');
     const l2CoachPath = (0, path_1.join)(learningsBase, 'org-manager-coaching.md');
+    const l2ValidatedPath = (0, path_1.join)(learningsBase, 'org-validated-patterns.md');
     const l2MistakePresent = (0, fs_1.existsSync)(l2MistakePath);
     const l2PrefPresent = (0, fs_1.existsSync)(l2PrefPath);
     const l2CoachPresent = (0, fs_1.existsSync)(l2CoachPath);
-    const l2MistakeCounts = l2MistakePresent ? countMistakePatternEntries(l2MistakePath, threshold) : null;
-    const l1MistakePath = (0, path_1.join)(learningsBase, `${userId}-mistake-patterns.md`);
-    const l1PrefPath = (0, path_1.join)(learningsBase, `${userId}-preferences.md`);
-    const l1CoachPath = (0, path_1.join)(learningsBase, `${userId}-manager-coaching.md`);
+    const l2ValidatedPresent = (0, fs_1.existsSync)(l2ValidatedPath);
+    const l2MistakeStats = l2MistakePresent ? scanMistakePatternFile(l2MistakePath, threshold, 'mistake-patterns') : null;
+    const l2ValidatedStats = l2ValidatedPresent ? scanMistakePatternFile(l2ValidatedPath, threshold, 'validated-patterns') : null;
+    const l1MistakePath = (0, path_1.join)(learningsBase, `${resolvedUserId}-mistake-patterns.md`);
+    const l1PrefPath = (0, path_1.join)(learningsBase, `${resolvedUserId}-preferences.md`);
+    const l1CoachPath = (0, path_1.join)(learningsBase, `${resolvedUserId}-manager-coaching.md`);
+    const l1ValidatedPath = (0, path_1.join)(learningsBase, `${resolvedUserId}-validated-patterns.md`);
     const l1MistakePresent = (0, fs_1.existsSync)(l1MistakePath);
     const l1PrefPresent = (0, fs_1.existsSync)(l1PrefPath);
     const l1CoachPresent = (0, fs_1.existsSync)(l1CoachPath);
-    const l1MistakeCounts = l1MistakePresent ? countMistakePatternEntries(l1MistakePath, threshold) : null;
+    const l1ValidatedPresent = (0, fs_1.existsSync)(l1ValidatedPath);
+    const l1MistakeStats = l1MistakePresent ? scanMistakePatternFile(l1MistakePath, threshold, 'mistake-patterns') : null;
+    const l1ValidatedStats = l1ValidatedPresent ? scanMistakePatternFile(l1ValidatedPath, threshold, 'validated-patterns') : null;
     let l0CoachingCount = 0;
     const rawPath = (0, path_1.join)(learningsBase, 'raw');
     if ((0, fs_1.existsSync)(rawPath)) {
         try {
-            l0CoachingCount = (0, fs_1.readdirSync)(rawPath).filter(f => f.startsWith(`${userId}-`)).length;
+            l0CoachingCount = (0, fs_1.readdirSync)(rawPath).filter(f => f.startsWith(`${resolvedUserId}-`)).length;
         }
         catch {
             // Ignore read failures.
@@ -156,15 +318,15 @@ function buildLearningContextSection(workspaceRoot, userId, forJob) {
     if ((0, fs_1.existsSync)(retrospectivesPath)) {
         try {
             l0RetroCount = (0, fs_1.readdirSync)(retrospectivesPath)
-                .filter(f => f.startsWith(`${userId}-`) && f.endsWith('.md'))
+                .filter(f => f.startsWith(`${resolvedUserId}-`) && f.endsWith('.md'))
                 .filter(f => isUnsynthesizedRetrospective((0, path_1.join)(retrospectivesPath, f))).length;
         }
         catch {
             // Ignore read failures.
         }
     }
-    const hasL2 = l2MistakePresent || l2PrefPresent || l2CoachPresent;
-    const hasL1 = l1MistakePresent || l1PrefPresent || l1CoachPresent;
+    const hasL2 = l2MistakePresent || l2PrefPresent || l2CoachPresent || l2ValidatedPresent;
+    const hasL1 = l1MistakePresent || l1PrefPresent || l1CoachPresent || l1ValidatedPresent;
     const hasContent = hasL2 || hasL1 || l0CoachingCount > 0 || l0RetroCount > 0;
     if (!hasContent)
         return '';
@@ -179,51 +341,74 @@ function buildLearningContextSection(workspaceRoot, userId, forJob) {
             section += `\`${LEARNINGS_REL}/org-preferences.md\`  (all entries)\n`;
         if (l2CoachPresent)
             section += `\`${LEARNINGS_REL}/org-manager-coaching.md\`  (all entries)\n`;
-        if (l2MistakeCounts && l2MistakeCounts.dormant > 0) {
-            section += `Dormant: ${l2MistakeCounts.dormant} org pattern${l2MistakeCounts.dormant !== 1 ? 's' : ''} below threshold\n`;
+        if (l2ValidatedPresent)
+            section += `\`${LEARNINGS_REL}/org-validated-patterns.md\`  (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 (l1PrefPresent)
-            section += `\`${LEARNINGS_REL}/${userId}-preferences.md\`  (all entries)\n`;
+            section += `\`${LEARNINGS_REL}/${resolvedUserId}-preferences.md\`  (all entries)\n`;
         if (l1CoachPresent)
-            section += `\`${LEARNINGS_REL}/${userId}-manager-coaching.md\`  (all entries)\n`;
+            section += `\`${LEARNINGS_REL}/${resolvedUserId}-manager-coaching.md\`  (all entries)\n`;
         if (l1MistakePresent)
-            section += `\`${LEARNINGS_REL}/${userId}-mistake-patterns.md\`  (entries above score threshold)\n`;
-        if (l1MistakeCounts && l1MistakeCounts.dormant > 0) {
-            section += `Dormant: ${l1MistakeCounts.dormant} personal pattern${l1MistakeCounts.dormant !== 1 ? 's' : ''} below threshold\n`;
+            section += `\`${LEARNINGS_REL}/${resolvedUserId}-mistake-patterns.md\`  (entries above score threshold)\n`;
+        if (l1ValidatedPresent)
+            section += `\`${LEARNINGS_REL}/${resolvedUserId}-validated-patterns.md\`  (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) {
         section += '### L0 - Your unprocessed signals\n';
         if (l0CoachingCount > 0) {
-            section += `${l0CoachingCount} coaching moment${l0CoachingCount !== 1 ? 's' : ''} in \`${LEARNINGS_REL}/raw/${userId}-*\`\n`;
+            section += `${l0CoachingCount} coaching moment${l0CoachingCount !== 1 ? 's' : ''} in \`${LEARNINGS_REL}/raw/${resolvedUserId}-*\`\n`;
         }
         if (l0RetroCount > 0) {
-            section += `${l0RetroCount} retrospective${l0RetroCount !== 1 ? 's' : ''} in \`docs/retrospectives/${userId}-*\` with \`synthesized: false\` or missing\n`;
+            section += `${l0RetroCount} retrospective${l0RetroCount !== 1 ? 's' : ''} in \`docs/retrospectives/${resolvedUserId}-*\` with \`synthesized: false\` or missing\n`;
         }
         section += '\n';
     }
     const totalL0 = l0CoachingCount + l0RetroCount;
+    const oldestAgeDays = totalL0 > 0 ? computeOldestL0AgeDays(workspaceRoot, resolvedUserId) : 0;
+    const agingRisk = l1MistakeStats?.agingRisk ?? 0;
+    const backlogTriggered = totalL0 >= BACKLOG_MIN || (oldestAgeDays >= OLDEST_AGE_DAYS_TRIGGER && totalL0 > 0);
     if (forJob) {
         if (hasL2 || hasL1) {
             section += 'Use the relevant patterns, preferences, and coaching signals in this job.\n';
         }
-        if (totalL0 >= 5) {
+        if (backlogTriggered) {
             section += '\n';
             section += `Warning: ${totalL0} unprocessed signals pending. Consider running \`end-of-day-debrief\` before starting today's work.\n`;
+            section += renderBacklogDetail(oldestAgeDays, agingRisk);
         }
     }
     else {
         section += 'Use this synthesized learning context throughout the session.\n';
-        if (totalL0 >= 5) {
+        if (backlogTriggered) {
             section += '\n';
             section += `Warning: synthesis overdue with ${totalL0} unprocessed signals.\n`;
             section += 'Run `end-of-day-debrief` before starting today\'s work.\n';
+            section += renderBacklogDetail(oldestAgeDays, agingRisk);
         }
     }
     return section;
 }
+function renderBacklogDetail(oldestAgeDays, agingRisk) {
+    if (oldestAgeDays <= 0 && agingRisk <= 0)
+        return '';
+    const parts = [];
+    if (oldestAgeDays > 0)
+        parts.push(`oldest ${oldestAgeDays}d`);
+    parts.push('debrief takes ~3 minutes');
+    if (agingRisk > 0) {
+        parts.push(`${agingRisk} high-score pattern${agingRisk !== 1 ? 's' : ''} aging out within ${AGING_HORIZON_DAYS}d`);
+    }
+    return `Detail: ${parts.join('; ')}.\n`;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "fraim",
-  "version": "2.0.117",
+  "version": "2.0.120",
   "description": "FRAIM CLI - Framework for Rigor-based AI Management (alias for fraim-framework)",
   "main": "index.js",
   "bin": {