fraim 2.0.342 → 2.0.344

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

@@ -45,10 +45,8 @@ const config_loader_1 = require("../../core/config-loader");
 const version_utils_1 = require("../utils/version-utils");
 const script_sync_utils_1 = require("../utils/script-sync-utils");
 const git_utils_1 = require("../../core/utils/git-utils");
-const agent_adapters_1 = require("../utils/agent-adapters");
+const project_catalog_cleanup_1 = require("../utils/project-catalog-cleanup");
 const fraim_gitignore_1 = require("../utils/fraim-gitignore");
-const user_config_1 = require("../utils/user-config");
-const ide_detector_1 = require("../setup/ide-detector");
 const remote_sync_1 = require("../utils/remote-sync");
 const project_fraim_paths_1 = require("../../core/utils/project-fraim-paths");
 function resolveExplicitLocalSyncUrl() {
@@ -113,66 +111,6 @@ function removeLegacyVersionFromConfig(fraimDir) {
         console.warn(chalk_1.default.yellow('Could not remove legacy version from config.json.'));
     }
 }
-function resolveAllowedConfigTypes() {
-    const persisted = (0, user_config_1.getInstalledIdes)();
-    const liveDetected = [
-        ...(0, ide_detector_1.detectInstalledIDEs)(),
-        ...(0, ide_detector_1.detectInstalledIDEs)('cli-runnable')
-    ].map((ide) => (0, ide_detector_1.getAdapterConfigType)(ide));
-    const liveSet = [...new Set(liveDetected)];
-    if (!persisted) {
-        return liveSet.length > 0 ? liveSet : null;
-    }
-    const merged = [...new Set([...persisted, ...liveSet])];
-    return merged.length > 0 ? merged : null;
-}
-async function cleanupStaleAdapterFiles(projectRoot, allowedConfigTypes) {
-    if (!allowedConfigTypes) {
-        return;
-    }
-    (0, project_fraim_paths_1.assertWorkspaceFraimRoot)(projectRoot);
-    const { execFile } = await Promise.resolve().then(() => __importStar(require('child_process')));
-    const { promisify } = await Promise.resolve().then(() => __importStar(require('util')));
-    const execFileAsync = promisify(execFile);
-    for (const [relPath, configType] of Object.entries((0, agent_adapters_1.getAdapterConfigTypes)())) {
-        const configTypes = Array.isArray(configType) ? configType : [configType];
-        if (configTypes.includes('standard') || configTypes.some((type) => allowedConfigTypes.includes(type))) {
-            continue;
-        }
-        const fullPath = path_1.default.join(projectRoot, relPath);
-        if (!fs_1.default.existsSync(fullPath)) {
-            continue;
-        }
-        try {
-            const content = fs_1.default.readFileSync(fullPath, 'utf8');
-            if (!content.includes(remote_sync_1.SYNCED_CONTENT_BANNER_MARKER)) {
-                continue;
-            }
-        }
-        catch {
-            continue;
-        }
-        try {
-            await execFileAsync('git', ['rm', '--cached', relPath], { cwd: projectRoot });
-        }
-        catch {
-            // Not tracked or git unavailable — still clean up from disk and gitignore.
-        }
-        try {
-            (0, fraim_gitignore_1.addToFraimGitignore)(projectRoot, relPath);
-        }
-        catch {
-            // Best-effort.
-        }
-        try {
-            fs_1.default.unlinkSync(fullPath);
-            console.log(chalk_1.default.green(`Removed stale FRAIM adapter file: ${relPath}`));
-        }
-        catch {
-            // Best-effort.
-        }
-    }
-}
 function failSync(mode, message) {
     if (mode === 'throw') {
         throw new Error(message);
@@ -182,10 +120,13 @@ function failSync(mode, message) {
 const runSync = async (options) => {
     const failHard = options.failHard ?? 'exit';
     const projectRoot = options.projectRoot ? path_1.default.resolve(options.projectRoot) : process.cwd();
+    const useLocal = options.local || process.env.FRAIM_LOCAL_SYNC === '1';
     // ─── Credential resolution (before project detection) ─────────────────────
     // Order: user-level config → env var → project config (only if in a project)
-    const remoteUrl = process.env.FRAIM_REMOTE_URL || 'https://fraim.wellnessatwork.me';
-    let apiKey = loadUserApiKey() || process.env.FRAIM_API_KEY;
+    const remoteUrl = useLocal
+        ? resolveExplicitLocalSyncUrl() || `http://localhost:${process.env.FRAIM_MCP_PORT || (0, git_utils_1.getPort)()}`
+        : process.env.FRAIM_REMOTE_URL || 'https://fraim.wellnessatwork.me';
+    let apiKey = useLocal ? 'local-dev' : loadUserApiKey() || process.env.FRAIM_API_KEY;
     const hasProject = (0, project_fraim_paths_1.workspaceFraimExists)(projectRoot);
     if (!apiKey && hasProject) {
         const config = (0, config_loader_1.loadFraimConfig)((0, project_fraim_paths_1.getWorkspaceConfigPath)(projectRoot));
@@ -272,60 +213,7 @@ const runSync = async (options) => {
         }
         catch { /* reporting must never fail a sync */ }
     };
-    // ─── Local sync shortcut (dev mode) ───────────────────────────────────────
-    const useLocal = options.local || process.env.FRAIM_LOCAL_SYNC === '1';
-    if (useLocal) {
-        console.log(chalk_1.default.blue('Syncing FRAIM jobs from local server...'));
-        const localPort = process.env.FRAIM_MCP_PORT ? parseInt(process.env.FRAIM_MCP_PORT) : (0, git_utils_1.getPort)();
-        const localUrl = resolveExplicitLocalSyncUrl() || `http://localhost:${localPort}`;
-        const { syncFromRemote } = await Promise.resolve().then(() => __importStar(require('../utils/remote-sync')));
-        if (!hasProject) {
-            console.error(chalk_1.default.red('Local sync requires a FRAIM project directory (fraim/ must exist).'));
-            failSync(failHard, 'Local sync requires a project directory.');
-        }
-        const localRegistryFiles = await (0, remote_sync_1.fetchRegistryFiles)(localUrl, 'local-dev');
-        const result = await syncFromRemote({
-            remoteUrl: localUrl,
-            apiKey: 'local-dev',
-            projectRoot,
-            skipUpdates: true,
-            registryFiles: localRegistryFiles
-        });
-        if (result.success) {
-            // Local-dev sync bypasses Layer 1 (machine-level sync) below, but scripts,
-            // docs, and job stubs still need to land in ~/.fraim/ or the reported counts
-            // are a lie.
-            await (0, remote_sync_1.syncScriptsToUserDir)(localRegistryFiles);
-            await (0, remote_sync_1.syncDocsToUserDir)(localRegistryFiles);
-            await (0, remote_sync_1.syncJobsToUserDir)(localRegistryFiles);
-            const { ensureUserLevelDependencies: ensureLocalUserLevelDependencies } = await Promise.resolve().then(() => __importStar(require('../setup/user-level-sync')));
-            ensureLocalUserLevelDependencies();
-            console.log(chalk_1.default.green(`Successfully synced ${result.employeeJobsSynced} ai-employee jobs, ${result.managerJobsSynced} ai-manager jobs, ${result.skillsSynced} skills, ${result.rulesSynced} rules, ${result.scriptsSynced} scripts, and ${result.docsSynced} docs from local server`));
-            const fraimDir = (0, project_fraim_paths_1.getWorkspaceFraimDir)(projectRoot);
-            removeLegacyVersionFromConfig(fraimDir);
-            writeSyncMetadata('local', localUrl);
-            const ignoreUpdate = (0, fraim_gitignore_1.ensureFraimSyncedContentLocallyExcluded)(projectRoot);
-            if (ignoreUpdate.gitInfoExcludeUpdated) {
-                console.log(chalk_1.default.green('Updated .git/info/exclude FRAIM managed block'));
-            }
-            if (ignoreUpdate.gitignoreUpdated) {
-                console.log(chalk_1.default.green('Removed legacy FRAIM sync block from .gitignore'));
-            }
-            const allowedLocalTypes = resolveAllowedConfigTypes();
-            await cleanupStaleAdapterFiles(projectRoot, allowedLocalTypes);
-            const localAdapterUpdates = (0, agent_adapters_1.ensureAgentAdapterFiles)(projectRoot, allowedLocalTypes);
-            if (localAdapterUpdates.length > 0) {
-                console.log(chalk_1.default.green(`Updated FRAIM agent adapter files: ${localAdapterUpdates.join(', ')}`));
-            }
-            await refreshOrgCache(localUrl, 'local-dev');
-            await refreshManagerCache(localUrl, 'local-dev');
-            return;
-        }
-        console.error(chalk_1.default.red(`Local sync failed: ${result.error}`));
-        console.error(chalk_1.default.yellow('Make sure the FRAIM MCP server is running locally (npm run dev).'));
-        failSync(failHard, `Local sync failed: ${result.error}`);
-    }
-    // ─── Global install notice ────────────────────────────────────────────────
+    // Local and remote sources share the same machine-level writers.
     const isNpx = process.env.npm_config_prefix === undefined || process.env.npm_lifecycle_event === 'npx';
     const isGlobal = !isNpx && (process.env.npm_config_global === 'true' || process.env.npm_config_prefix);
     if (isGlobal && !options.skipUpdates) {
@@ -337,7 +225,7 @@ const runSync = async (options) => {
     // LAYER 1 — Machine-level sync (always runs)
     // ═══════════════════════════════════════════════════════════════════════════
     console.log(chalk_1.default.blue('Syncing machine-level FRAIM content (~/.fraim/)...'));
-    // 1a. Fetch registry files (single API call shared with Layer 2)
+    // 1a. Fetch registry files once for every machine-level writer
     let registryFiles = [];
     try {
         registryFiles = await (0, remote_sync_1.fetchRegistryFiles)(remoteUrl, apiKey);
@@ -370,6 +258,10 @@ const runSync = async (options) => {
     if (machineEmployeeJobsSynced > 0 || machineManagerJobsSynced > 0) {
         console.log(chalk_1.default.green(`  Synced ${machineEmployeeJobsSynced} ai-employee jobs and ${machineManagerJobsSynced} ai-manager jobs to ~/.fraim/`));
     }
+    const { skillsSynced, rulesSynced } = await (0, remote_sync_1.syncSkillsAndRulesToUserDir)(registryFiles);
+    if (skillsSynced > 0 || rulesSynced > 0) {
+        console.log(chalk_1.default.green(`  Synced ${skillsSynced} skills and ${rulesSynced} rules to ~/.fraim/`));
+    }
     // 1c. Refresh org home
     await refreshOrgCache(remoteUrl, apiKey);
     // 1d. Refresh manager home
@@ -389,45 +281,34 @@ const runSync = async (options) => {
     // 1f. Ensure user-level directories and runtime dependencies (Issue #1508:
     // synced scripts like the DOCX review layer require npm deps such as
     // adm-zip; a plain sync must install them, not just create directories)
-    const { ensureUserLevelDirectories, ensureUserLevelDependencies } = await Promise.resolve().then(() => __importStar(require('../setup/user-level-sync')));
-    ensureUserLevelDirectories();
-    ensureUserLevelDependencies();
+    const { syncUserLevelArtifacts } = await Promise.resolve().then(() => __importStar(require('../setup/user-level-sync')));
+    await syncUserLevelArtifacts();
     // 1g. Write sync metadata
-    writeSyncMetadata('remote', remoteUrl);
+    writeSyncMetadata(useLocal ? 'local' : 'remote', remoteUrl);
     console.log(chalk_1.default.green('✅ Machine-level sync complete.'));
     // ═══════════════════════════════════════════════════════════════════════════
-    // LAYER 2 — Project-level sync (conditional)
+    // Project maintenance only: no catalog or adapter writes.
     // ═══════════════════════════════════════════════════════════════════════════
-    if (options.global) {
-        console.log(chalk_1.default.gray('--global: skipping project-level sync.'));
-        return;
-    }
-    if (!hasProject) {
-        console.log(chalk_1.default.cyan('No FRAIM project detected at cwd. Machine-level sync complete.'));
-        console.log(chalk_1.default.cyan('Run from a project folder or pass --project-root to sync project stubs.'));
+    if (options.global || !hasProject)
         return;
-    }
-    console.log(chalk_1.default.blue('Syncing project-level FRAIM content (fraim/)...'));
-    const { syncFromRemote } = await Promise.resolve().then(() => __importStar(require('../utils/remote-sync')));
-    const config = (0, config_loader_1.loadFraimConfig)((0, project_fraim_paths_1.getWorkspaceConfigPath)(projectRoot));
-    const fraimDir = (0, project_fraim_paths_1.getWorkspaceFraimDir)(projectRoot);
-    const result = await syncFromRemote({
-        remoteUrl: config.remoteUrl || remoteUrl,
-        apiKey,
-        projectRoot,
-        skipUpdates: options.skipUpdates || false,
-        registryFiles
-    });
-    if (!result.success) {
-        console.error(chalk_1.default.red(`Project sync failed: ${result.error}`));
-        if (process.env.TEST_MODE === 'true') {
-            console.log(chalk_1.default.yellow('TEST_MODE: Continuing without project sync.'));
+    if ((0, project_catalog_cleanup_1.hasLegacyProjectCatalogs)(projectRoot)) {
+        // An empty/partial response (including TEST_MODE fetch continuation) is
+        // not evidence that all generated project content has a replacement.
+        const replacementsSynced = machineEmployeeJobsSynced > 0 && machineManagerJobsSynced > 0
+            && skillsSynced > 0 && rulesSynced > 0 && docsSynced > 0;
+        if (!replacementsSynced) {
+            console.warn(chalk_1.default.yellow('Project catalog cleanup skipped: replacement machine catalogs are incomplete. Existing catalogs and exclusions were retained.'));
+            return;
+        }
+        try {
+            (0, project_catalog_cleanup_1.removeLegacyProjectCatalogs)(projectRoot);
+        }
+        catch (error) {
+            console.warn(chalk_1.default.yellow(`Project catalog cleanup failed: ${error instanceof Error ? error.message : String(error)}. Remaining catalogs and exclusions were retained; retry sync after resolving the error.`));
             return;
         }
-        failSync(failHard, `Project sync failed: ${result.error}`);
     }
-    console.log(chalk_1.default.green(`Successfully synced ${result.employeeJobsSynced} ai-employee jobs, ${result.managerJobsSynced} ai-manager jobs, ${result.skillsSynced} skills, ${result.rulesSynced} rules, and ${result.docsSynced} docs`));
-    removeLegacyVersionFromConfig(fraimDir);
+    removeLegacyVersionFromConfig((0, project_fraim_paths_1.getWorkspaceFraimDir)(projectRoot));
     const ignoreUpdate = (0, fraim_gitignore_1.ensureFraimSyncedContentLocallyExcluded)(projectRoot);
     if (ignoreUpdate.gitInfoExcludeUpdated) {
         console.log(chalk_1.default.green('Updated .git/info/exclude FRAIM managed block'));
@@ -435,21 +316,14 @@ const runSync = async (options) => {
     if (ignoreUpdate.gitignoreUpdated) {
         console.log(chalk_1.default.green('Removed legacy FRAIM sync block from .gitignore'));
     }
-    const allowedTypes = resolveAllowedConfigTypes();
-    await cleanupStaleAdapterFiles(projectRoot, allowedTypes);
-    const adapterUpdates = (0, agent_adapters_1.ensureAgentAdapterFiles)(projectRoot, allowedTypes);
-    if (adapterUpdates.length > 0) {
-        console.log(chalk_1.default.green(`Updated FRAIM agent adapter files: ${adapterUpdates.join(', ')}`));
-    }
-    console.log(chalk_1.default.green('✅ Project-level sync complete.'));
 };
 exports.runSync = runSync;
 exports.syncCommand = new commander_1.Command('sync')
-    .description('Sync job stubs from the framework registry')
+    .description('Sync machine-level FRAIM catalogs, scripts, docs and agent integration')
     .option('-f, --force', 'Force sync even if digest matches')
     .option('--skip-updates', 'Skip checking for CLI updates (legacy)')
     .option('--local', 'Sync from local development server (port derived from git branch)')
-    .option('--global', 'Sync machine-level FRAIM content only (~/.fraim/), skip project stubs')
-    .option('--project-root <path>', 'Explicit project root (enables project-level sync from any cwd)')
-    .option('--project-adapters', 'Write legacy project-local FRAIM agent adapter files')
+    .option('--global', 'Sync machine-level FRAIM content only (~/.fraim/), skip project maintenance')
+    .option('--project-root <path>', 'Explicit project root for configuration and local exclusion maintenance')
+    .option('--project-adapters', 'Deprecated compatibility option (no effect; use machine-level FRAIM setup)')
     .action(exports.runSync);

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

@@ -68,11 +68,11 @@ function buildFraimInvocationBody(profile = 'none') {
 ${buildDeferredToolBootstrapSection(profile)}1. **Confirm FRAIM activation**:
    Use this process only when the user explicitly invokes FRAIM, names a FRAIM job, asks what FRAIM job to run, or the active surface has already selected a FRAIM job. For ordinary requests, answer or work normally; do not scan FRAIM stubs first.
 
-2. **If the user did not specify a FRAIM job or topic after activation**:
-   If local FRAIM job stubs are present in the workspace, read that jobs directory's \`INDEX.md\` first (it lists every job's name, one-line intent, and category) and match the request against it; open an individual stub only to confirm a shortlisted candidate, or fall back to scanning the stubs directly if no \`INDEX.md\` is present. Also check \`fraim/personalized-employee/jobs/\` (and its own \`INDEX.md\`, if present) for local overrides or repo-specific jobs. If local files are missing or you cannot inspect workspace files, call \`list_fraim_jobs()\` to view the full catalog, including any proxy-discoverable personalized jobs.
+2. **Discover jobs when activation did not name an exact FRAIM job**:
+   Read \`~/.fraim/ai-employee/jobs/INDEX.md\` and \`~/.fraim/ai-manager/jobs/INDEX.md\` first (each lists every job's name, one-line intent, and category) and match the request against them; open an individual stub only to confirm a shortlisted candidate, or fall back to scanning stubs in those machine directories if an index is missing or stale. Also check \`fraim/personalized-employee/jobs/INDEX.md\` (or its stubs, if no index is present) for project overrides or repo-specific jobs. Project baseline catalog directories are not required. If machine files are missing or you cannot inspect local files, call \`list_fraim_jobs()\` to view the full catalog, including any proxy-discoverable personalized jobs.
 
 3. **Find the match**:
-   If the user names an exact FRAIM job, call \`get_fraim_job({ job: "<job-name>" })\` directly. Otherwise, match the user's request to a FRAIM job from the local stub catalog, \`fraim/personalized-employee/jobs/\`, or the full \`list_fraim_jobs()\` response. If no exact or high-confidence job match exists, call \`get_fraim_job({ job: "adhoc-prompt" })\` directly and execute it with the user's instructions as the task input — no confirmation question, and do not pick the nearest catalog job.
+   If the user names an exact FRAIM job, call \`get_fraim_job({ job: "<job-name>" })\` directly. Otherwise, match the user's request to a FRAIM job from the machine stub catalog, \`fraim/personalized-employee/jobs/\` (project overrides take precedence), or the full \`list_fraim_jobs()\` response. If no exact or high-confidence job match exists, call \`get_fraim_job({ job: "adhoc-prompt" })\` directly and execute it with the user's instructions as the task input — no confirmation question, and do not pick the nearest catalog job.
 
 4. **Load the full content**:
    - For jobs, call \`get_fraim_job({ job: "<matched-job-name>" })\`.

package/dist/src/cli/setup/user-level-sync.js

@@ -49,9 +49,9 @@ exports.syncUserLevelArtifacts = syncUserLevelArtifacts;
  * - scripts/ — locally-executed scripts (synced during any fraim sync)
  * - personalized-employee/ — user-level overrides and learnings
  *
- * Job/skill/rule stubs are NOT synced to user-level. The MCP proxy serves
- * those on demand via list_fraim_jobs() and get_fraim_job(). Stubs only exist
- * at project-level (fraim/) where CLAUDE.md tells agents to scan them on disk.
+ * Sync writes machine-level job/skill/rule discovery stubs separately. These
+ * adapters route agents to those catalogs; the MCP proxy serves full executable
+ * instructions through get_fraim_job() and get_fraim_file().
  *
  * Part of: User-Level FRAIM Artifacts with Local Shadow Semantics
  */

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

@@ -52,11 +52,11 @@ function mergeCursorRule(existingContent, managedSection) {
     return `${ide_invocation_surfaces_1.CURSOR_MDC_FRONTMATTER}\n\n${mergedBody}\n`;
 }
 function getAdapterFiles(allowedConfigTypes = null) {
-    const fraimRoot = (0, project_fraim_paths_1.getWorkspaceFraimDisplayPath)().replace(/\/$/, '');
-    const employeeJobsPath = (0, project_fraim_paths_1.getWorkspaceFraimDisplayPath)('ai-employee/jobs');
-    const managerJobsPath = (0, project_fraim_paths_1.getWorkspaceFraimDisplayPath)('ai-manager/jobs');
-    const employeeSkillsPath = (0, project_fraim_paths_1.getWorkspaceFraimDisplayPath)('ai-employee/skills');
-    const employeeRulesPath = (0, project_fraim_paths_1.getWorkspaceFraimDisplayPath)('ai-employee/rules');
+    const fraimRoot = '~/.fraim';
+    const employeeJobsPath = `${fraimRoot}/ai-employee/jobs`;
+    const managerJobsPath = `${fraimRoot}/ai-manager/jobs`;
+    const employeeSkillsPath = `${fraimRoot}/ai-employee/skills`;
+    const employeeRulesPath = `${fraimRoot}/ai-employee/rules`;
     const personalizedRootPath = (0, project_fraim_paths_1.getWorkspaceFraimDisplayPath)('personalized-employee');
     const projectRulesPath = (0, project_fraim_paths_1.getWorkspaceFraimDisplayPath)('personalized-employee/rules/project_rules.md');
     const markdownBody = buildManagedSection(`
@@ -91,7 +91,7 @@ ${(0, ide_invocation_surfaces_1.buildFraimInvocationBody)('generic-tool-discover
     const copilotBody = buildManagedSection(`
 ## FRAIM
 
-- Use \`${fraimRoot}/\` as the repository's FRAIM catalog.
+- Use \`${fraimRoot}/\` as the machine-wide FRAIM catalog.
 - FRAIM jobs are the primary execution units and should be treated like first-class workflows.
 - FRAIM skills are reusable capabilities jobs compose.
 - FRAIM rules are always-on constraints and conventions.
@@ -99,19 +99,19 @@ ${(0, ide_invocation_surfaces_1.buildFraimInvocationBody)('generic-tool-discover
 - Use FRAIM when the user explicitly invokes FRAIM, names a FRAIM job, asks what FRAIM job to run, or the active surface has already selected a FRAIM job.
 - For ordinary requests, answer or work normally. Do not scan FRAIM stubs first.
 - If the user names an exact FRAIM job, fetch that full job directly with FRAIM MCP tools.
-- When FRAIM routing is active but the job is not exact, read the local jobs directory's \`INDEX.md\` first to identify which job to invoke (falling back to the individual stub files if no index is present) before fetching full content with FRAIM MCP tools.
+- When FRAIM routing is active but the job is not exact, read \`${employeeJobsPath}/INDEX.md\` and \`${managerJobsPath}/INDEX.md\` first to identify which job to invoke (falling back to their individual stub files if an index is missing or stale). Also check \`${personalizedRootPath}/jobs/INDEX.md\` or its stubs for project overrides before fetching full content with FRAIM MCP tools.
 - If no exact or high-confidence job match exists, say that no FRAIM job matches and continue with normal tools or ask one concise clarification.
 - **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_MCP_UNAVAILABLE_MANAGER_GUIDANCE}
 `);
     const fraimReadme = `# FRAIM Catalog
 
-This directory is the repository-visible FRAIM surface.
+This directory holds project-specific FRAIM content. The shared discovery catalog lives under \`~/.fraim/\`.
 
-- \`ai-employee/jobs/\`: employee job stubs (+ \`INDEX.md\`)
-- \`ai-manager/jobs/\`: manager job stubs (+ \`INDEX.md\`)
-- \`ai-employee/skills/\`: skill stubs (+ \`INDEX.md\`)
-- \`ai-employee/rules/\`: rule stubs
+- \`~/.fraim/ai-employee/jobs/\`: employee job stubs (+ \`INDEX.md\`)
+- \`~/.fraim/ai-manager/jobs/\`: manager job stubs (+ \`INDEX.md\`)
+- \`~/.fraim/ai-employee/skills/\`: skill stubs (+ \`INDEX.md\`)
+- \`~/.fraim/ai-employee/rules/\`: rule stubs
 - \`personalized-employee/\`: repo-specific overrides and learnings
 
 When FRAIM routing is active and no exact FRAIM job is named, read the \`INDEX.md\` in the relevant directory first to discover which FRAIM job, skill, or rule is relevant (falling back to scanning the individual stubs if no index is present), then load the full content through FRAIM MCP tools. If an exact FRAIM job is named, load it directly. For ordinary requests, do not scan this catalog first.

package/dist/src/cli/utils/fraim-gitignore.js

@@ -7,12 +7,11 @@ exports.ensureFraimSyncedContentLocallyExcluded = exports.removeFraimSyncedConte
 exports.addToFraimGitignore = addToFraimGitignore;
 const fs_1 = __importDefault(require("fs"));
 const path_1 = __importDefault(require("path"));
+const child_process_1 = require("child_process");
+const project_catalog_cleanup_1 = require("./project-catalog-cleanup");
 exports.FRAIM_SYNC_GITIGNORE_START = '# BEGIN FRAIM SYNCED CONTENT';
 exports.FRAIM_SYNC_GITIGNORE_END = '# END FRAIM SYNCED CONTENT';
 exports.FRAIM_SYNC_GITIGNORE_ENTRIES = [
-    'fraim/ai-employee/',
-    'fraim/ai-manager/',
-    'fraim/docs/',
     'fraim/.sync-metadata.json',
 ];
 const escapeRegExp = (value) => value.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
@@ -57,6 +56,24 @@ function resolveGitInfoExcludePath(projectRoot) {
     }
     return path_1.default.join(gitDir, 'info', 'exclude');
 }
+// info/exclude belongs to the common Git directory, so one migrated worktree
+// must not expose generated files in another worktree that has not synced yet.
+function retainSharedCatalogExclusions(projectRoot, existing) {
+    if (!/^fraim\/(?:ai-employee|ai-manager|docs)\/\r?$/m.test(existing))
+        return false;
+    try {
+        const listing = (0, child_process_1.execFileSync)('git', ['worktree', 'list', '--porcelain', '-z'], {
+            cwd: projectRoot, encoding: 'utf8', timeout: 5000, windowsHide: true, stdio: ['ignore', 'pipe', 'pipe'],
+        });
+        const roots = listing.split('\0').filter(field => field.startsWith('worktree '))
+            .map(field => field.slice('worktree '.length));
+        // Unknown worktree state is not evidence that their catalogs are gone.
+        return roots.length === 0 || roots.some(root => (0, project_catalog_cleanup_1.hasLegacyProjectCatalogs)(root));
+    }
+    catch {
+        return true;
+    }
+}
 const removeFraimSyncedContentGitignoreBlock = (projectRoot) => {
     const gitignorePath = path_1.default.join(projectRoot, '.gitignore');
     if (!fs_1.default.existsSync(gitignorePath)) {
@@ -87,6 +104,11 @@ function addToFraimGitignore(projectRoot, entry) {
     fs_1.default.writeFileSync(gitignorePath, appended, 'utf8');
 }
 const ensureFraimSyncedContentLocallyExcluded = (projectRoot) => {
+    // init-project can call this before sync. Keep both legacy exclusion blocks
+    // intact until migration succeeds, including on skipped/failed sync or cleanup.
+    if ((0, project_catalog_cleanup_1.hasLegacyProjectCatalogs)(projectRoot)) {
+        return { gitignoreUpdated: false, gitInfoExcludeUpdated: false };
+    }
     const gitignoreUpdated = (0, exports.removeFraimSyncedContentGitignoreBlock)(projectRoot);
     const excludePath = resolveGitInfoExcludePath(projectRoot);
     if (!excludePath) {
@@ -99,6 +121,9 @@ const ensureFraimSyncedContentLocallyExcluded = (projectRoot) => {
     const existingRaw = fs_1.default.existsSync(excludePath)
         ? fs_1.default.readFileSync(excludePath, 'utf8')
         : '';
+    if (retainSharedCatalogExclusions(projectRoot, existingRaw)) {
+        return { gitignoreUpdated, gitInfoExcludeUpdated: false };
+    }
     const normalized = existingRaw.replace(/\r\n/g, '\n');
     const cleaned = normalizeWithoutManagedBlock(existingRaw);
     const managedBlock = buildManagedBlock();

package/dist/src/cli/utils/pack-home.js

@@ -35,6 +35,7 @@ exports.ensurePackClone = ensurePackClone;
 const child_process_1 = require("child_process");
 const fs_1 = __importDefault(require("fs"));
 const path_1 = __importDefault(require("path"));
+const artifact_paths_1 = require("../../../registry/scripts/artifact-paths");
 const project_fraim_paths_1 = require("../../core/utils/project-fraim-paths");
 const user_config_1 = require("./user-config");
 /**
@@ -84,10 +85,19 @@ function migrateOrgFlatContent(orgRoot) {
     _migratedOrgRoots.add(orgRoot);
     const dest = path_1.default.join(orgRoot, 'personalized-employee');
     try {
+        // Root-relative output trees are authoritative, even when their names resemble legacy capabilities.
+        const artifacts = (0, artifact_paths_1.resolveArtifactPaths)(orgRoot, dest);
+        const protectedDirectories = [artifacts.evidence, artifacts.raw, artifacts.retrospectives, path_1.default.dirname(artifacts.archiveRaw)];
+        const contains = (root, target) => {
+            const relative = path_1.default.relative(root, target);
+            return relative === '' || (relative !== '..' && !relative.startsWith('..' + path_1.default.sep) && !path_1.default.isAbsolute(relative));
+        };
         for (const dir of ORG_CONTENT_DIRS) {
             const src = path_1.default.join(orgRoot, dir);
             if (!fs_1.default.existsSync(src))
                 continue;
+            if (protectedDirectories.some(directory => contains(src, directory) || contains(directory, src)))
+                continue;
             // Skip if already under personalized-employee.
             const destDir = path_1.default.join(dest, dir);
             if (fs_1.default.existsSync(destDir))

package/dist/src/cli/utils/project-catalog-cleanup.js

@@ -0,0 +1,62 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.hasLegacyProjectCatalogs = hasLegacyProjectCatalogs;
+exports.removeLegacyProjectCatalogs = removeLegacyProjectCatalogs;
+const fs_1 = __importDefault(require("fs"));
+const path_1 = __importDefault(require("path"));
+const project_fraim_paths_1 = require("../../core/utils/project-fraim-paths");
+// Only generated catalog roots are eligible; adapters and personalization are not.
+const LEGACY_PROJECT_CATALOGS = ['ai-employee', 'ai-manager', 'docs'];
+function hasLegacyProjectCatalogs(projectRoot) {
+    return LEGACY_PROJECT_CATALOGS.some(name => fs_1.default.lstatSync(path_1.default.join((0, project_fraim_paths_1.getWorkspaceFraimDir)(projectRoot), name), { throwIfNoEntry: false }) !== undefined);
+}
+function overlaps(left, right) {
+    const within = (parent, child) => {
+        const rel = path_1.default.relative(parent, child);
+        return rel === '' || (rel !== '..' && !rel.startsWith(`..${path_1.default.sep}`) && !path_1.default.isAbsolute(rel));
+    };
+    return within(left, right) || within(right, left);
+}
+/** Called only after all replacement machine catalogs have been synced. */
+function removeLegacyProjectCatalogs(projectRoot) {
+    const project = path_1.default.resolve(projectRoot);
+    const fraimDir = (0, project_fraim_paths_1.getWorkspaceFraimDir)(project);
+    if (fs_1.default.lstatSync(fraimDir).isSymbolicLink()) {
+        throw new Error('Refusing catalog cleanup through a linked fraim directory.');
+    }
+    const assertWorkspacePath = (0, project_fraim_paths_1.createWorkspaceFraimPathAsserter)(project);
+    const machineDir = fs_1.default.realpathSync((0, project_fraim_paths_1.getUserFraimDirPath)());
+    const targets = LEGACY_PROJECT_CATALOGS.map(name => ({ name, target: path_1.default.resolve(fraimDir, name) }))
+        .filter(({ target }) => fs_1.default.lstatSync(target, { throwIfNoEntry: false }) !== undefined);
+    const assertPlainTree = (entry) => {
+        const stat = fs_1.default.lstatSync(entry);
+        if (stat.isSymbolicLink())
+            throw new Error(`Refusing catalog cleanup through link: ${entry}`);
+        assertWorkspacePath(entry);
+        if (stat.isDirectory()) {
+            for (const child of fs_1.default.readdirSync(entry))
+                assertPlainTree(path_1.default.join(entry, child));
+        }
+        else if (!stat.isFile()) {
+            throw new Error(`Refusing catalog cleanup of special file: ${entry}`);
+        }
+    };
+    // Preflight every tree before deleting any: links, overlap, or unreadable paths
+    // must not turn a partial inspection into destructive cleanup.
+    for (const { name, target } of targets) {
+        assertPlainTree(target);
+        (0, project_fraim_paths_1.assertExactWorkspaceFraimPath)(project, target, name);
+        if (!fs_1.default.lstatSync(target).isDirectory() || overlaps(fs_1.default.realpathSync(target), machineDir)) {
+            throw new Error(`Refusing catalog cleanup of non-directory or machine-overlapping path: ${target}`);
+        }
+    }
+    for (const { name, target } of targets) {
+        // Recheck immediately before removal; rmSync does not recurse through links.
+        assertPlainTree(target);
+        (0, project_fraim_paths_1.assertExactWorkspaceFraimPath)(project, target, name);
+        fs_1.default.rmSync(target, { recursive: true, force: true, maxRetries: 3, retryDelay: 50 });
+    }
+}

package/dist/src/cli/utils/remote-sync.js

@@ -16,13 +16,13 @@ exports.fetchRegistryFiles = fetchRegistryFiles;
 exports.syncScriptsToUserDir = syncScriptsToUserDir;
 exports.syncDocsToUserDir = syncDocsToUserDir;
 exports.syncJobsToUserDir = syncJobsToUserDir;
+exports.syncSkillsAndRulesToUserDir = syncSkillsAndRulesToUserDir;
 exports.syncFromRemote = syncFromRemote;
 const axios_1 = __importDefault(require("axios"));
 const fs_1 = require("fs");
 const path_1 = require("path");
 const chalk_1 = __importDefault(require("chalk"));
 const script_sync_utils_1 = require("./script-sync-utils");
-const fraim_gitignore_1 = require("./fraim-gitignore");
 const capability_index_1 = require("../../core/utils/capability-index");
 const project_fraim_paths_1 = require("../../core/utils/project-fraim-paths");
 const LOCK_SYNCED_CONTENT_ENV = 'FRAIM_LOCK_SYNCED_CONTENT';
@@ -70,7 +70,9 @@ function shouldLockSyncedContent() {
     return !['0', 'false', 'off', 'no'].includes(normalized);
 }
 function getSyncedContentLockTargets(projectRoot) {
-    return fraim_gitignore_1.FRAIM_SYNC_GITIGNORE_ENTRIES
+    // This compatibility writer still materializes project catalogs. Their lock
+    // scope must not depend on the current machine-only sync exclusion policy.
+    return ['fraim/ai-employee/', 'fraim/ai-manager/', 'fraim/docs/']
         .filter((entry) => /[\\/]$/.test(entry))
         .map((entry) => entry.replace(/[\\/]+$/, ''))
         .map((entry) => (0, path_1.join)(projectRoot, entry));
@@ -288,6 +290,28 @@ async function syncJobsToUserDir(files) {
     ]);
     return { employeeJobsSynced, managerJobsSynced };
 }
+/** Keep skill and rule discovery beside the machine-level job catalogs. */
+async function syncSkillsAndRulesToUserDir(files) {
+    const counts = { skillsSynced: 0, rulesSynced: 0 };
+    for (const type of ['skill', 'rule']) {
+        const directory = `${type}s`;
+        const stubs = files.filter(file => file.type === type).map(file => ({
+            ...file,
+            path: file.path.replace(/\\/g, '/').replace(new RegExp(`^${directory}/`), ''),
+            content: applySyncedContentBanner(file),
+        }));
+        const count = await syncTypedFilesToUserDir(stubs, type, `ai-employee/${directory}`, type);
+        if (type === 'skill') {
+            counts.skillsSynced = count;
+            if (count > 0)
+                (0, capability_index_1.writeCapabilityIndex)((0, path_1.join)((0, script_sync_utils_1.getUserFraimDir)(), 'ai-employee', directory), 'skill');
+        }
+        else {
+            counts.rulesSynced = count;
+        }
+    }
+    return counts;
+}
 /**
  * Sync jobs and scripts from remote FRAIM server
  */

package/dist/src/config/persona-hiring.js

@@ -282,7 +282,13 @@ function buildPersonaAvatarUrl(personaKey) {
     return `https://api.dicebear.com/9.x/${avatar.style}/svg?${params.toString()}`;
 }
 function isPersonaHireKey(value) {
-    return value in exports.PERSONA_HIRE_CATALOG;
+    // Own properties only. `in` also answers true for every Object.prototype member,
+    // so 'constructor', 'toString', '__proto__' and friends passed this guard and then
+    // indexed the catalog to a prototype member rather than a persona. The guard is the
+    // input validation in front of the hire-checkout and entitlement reads, where the
+    // value is caller-supplied, and (issue #1925) in front of the employee-record reader,
+    // where it is file-supplied.
+    return Object.prototype.hasOwnProperty.call(exports.PERSONA_HIRE_CATALOG, value);
 }
 function getPersonaHireAmountCents(personaKey, mode) {
     const persona = exports.PERSONA_HIRE_CATALOG[personaKey];