fraim-framework 2.0.124 → 2.0.127

package/bin/fraim.js

@@ -1,4 +1,4 @@
-#!/usr/bin/env node
+#!/usr/bin/env node
 
 /**
  * FRAIM Framework CLI Entry Point

package/dist/src/ai-hub/catalog.js

@@ -6,25 +6,48 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.summarizeProject = summarizeProject;
 exports.discoverEmployeeJobs = discoverEmployeeJobs;
 exports.discoverManagerTemplates = discoverManagerTemplates;
+exports.loadJobPhases = loadJobPhases;
+exports.loadAllJobPhaseIds = loadAllJobPhaseIds;
+exports.labelForPhaseId = labelForPhaseId;
 exports.getAiHubCategories = getAiHubCategories;
 const fs_1 = __importDefault(require("fs"));
 const path_1 = __importDefault(require("path"));
 const project_fraim_paths_1 = require("../core/utils/project-fraim-paths");
-const EMPLOYEE_CATEGORIES = {
-    marketing: {
-        id: 'marketing',
-        label: 'Marketing',
-        description: 'Content, campaign, and creative production jobs.',
-    },
-    'go-to-market': {
-        id: 'go-to-market',
-        label: 'GTM',
-        description: 'Launch, distribution, and growth execution jobs.',
-    },
-};
-const MANAGER_GROUPS = {
-    coaching: 'Coaching',
-    delegation: 'Delegation',
+// Directories scanned for employee jobs, in lowest-to-highest precedence
+// order. Later entries win on {categoryId, jobId} collision. All present
+// layers contribute their category structure.
+//
+// Each entry is `[base, ...segments]` resolved relative to the project root:
+//   - 'registry'       → <project>/registry/jobs/ai-employee/<category>/
+//                        (present in the FRAIM source repo and in dist/)
+//   - 'fraim'          → <project>/fraim/ai-employee/jobs/<category>/
+//                        (the baseline synced into a regular project via
+//                        `fraim setup` / `fraim sync`)
+//   - 'fraim'          → <project>/fraim/personalized-employee/jobs/<category>/
+//                        (per-project override layer; CLAUDE.md says it
+//                        "takes precedence over synced baseline content")
+const EMPLOYEE_JOB_LAYERS = [
+    { base: 'registry', segments: ['jobs', 'ai-employee'] },
+    { base: 'fraim', segments: ['ai-employee', 'jobs'] },
+    { base: 'fraim', segments: ['personalized-employee', 'jobs'] },
+];
+// Manager templates use the matching three-layer model.
+const MANAGER_JOB_LAYERS = [
+    { base: 'registry', segments: ['jobs', 'ai-manager'] },
+    { base: 'fraim', segments: ['ai-manager', 'jobs'] },
+    { base: 'fraim', segments: ['personalized-employee', 'manager-jobs'] },
+];
+const KNOWN_LABEL_OVERRIDES = {
+    // Project conventions where a directory name should render as a recognized
+    // short form rather than its mechanical title-case spelling.
+    'go-to-market': 'GTM',
+    gtm: 'GTM',
+    'qa': 'QA',
+    rfp: 'RFP',
+    ai: 'AI',
+    // Manager-side groups whose directory names are already idiomatic and
+    // shouldn't be split on dashes by the default humanizer.
+    '1-1': '1:1',
 };
 const sectionValue = (content, heading) => {
     const match = content.match(new RegExp(`## ${heading}\\r?\\n([\\s\\S]*?)(?:\\r?\\n## |\\r?\\n---|$)`));
@@ -36,48 +59,68 @@ const sectionValue = (content, heading) => {
         .filter(Boolean)
         .map((line) => line.replace(/^[-*]\s*/, '').trim());
 };
-const humanizeJobName = (jobName) => jobName
-    .split('-')
-    .map((part) => (part.length > 0 ? `${part[0].toUpperCase()}${part.slice(1)}` : part))
-    .join(' ');
+const humanizeName = (raw) => {
+    const lower = raw.toLowerCase();
+    if (KNOWN_LABEL_OVERRIDES[lower])
+        return KNOWN_LABEL_OVERRIDES[lower];
+    return raw
+        .split(/[-_\s]+/)
+        .filter((part) => part.length > 0)
+        .map((part) => {
+        const partLower = part.toLowerCase();
+        if (KNOWN_LABEL_OVERRIDES[partLower])
+            return KNOWN_LABEL_OVERRIDES[partLower];
+        return `${part[0].toUpperCase()}${part.slice(1).toLowerCase()}`;
+    })
+        .join(' ');
+};
 const toPosix = (value) => value.replace(/\\/g, '/');
-function parseJobStub(filePath, categoryId, projectPath) {
+function readSubdirectoryNames(dirPath) {
+    if (!fs_1.default.existsSync(dirPath))
+        return [];
+    return fs_1.default
+        .readdirSync(dirPath, { withFileTypes: true })
+        .filter((entry) => entry.isDirectory())
+        .map((entry) => entry.name)
+        .sort((a, b) => a.localeCompare(b));
+}
+function readMarkdownFileNames(dirPath) {
+    if (!fs_1.default.existsSync(dirPath))
+        return [];
+    return fs_1.default
+        .readdirSync(dirPath, { withFileTypes: true })
+        .filter((entry) => entry.isFile() && entry.name.endsWith('.md'))
+        .map((entry) => entry.name)
+        .sort((a, b) => a.localeCompare(b));
+}
+function parseJobStub(filePath, categoryId, categoryLabel, projectPath) {
     const content = fs_1.default.readFileSync(filePath, 'utf8');
     const fileName = path_1.default.basename(filePath, '.md');
     const intent = sectionValue(content, 'Intent')[0] || 'No intent summary available.';
     const outcome = sectionValue(content, 'Outcome');
     return {
         id: fileName,
-        title: humanizeJobName(fileName),
+        title: humanizeName(fileName),
         categoryId,
-        categoryLabel: EMPLOYEE_CATEGORIES[categoryId].label,
+        categoryLabel,
         intent,
         outcome,
         stubPath: toPosix(path_1.default.relative(projectPath, filePath)),
     };
 }
-function parseManagerStub(filePath, groupId, projectPath) {
+function parseManagerStub(filePath, groupId, groupLabel, projectPath) {
     const content = fs_1.default.readFileSync(filePath, 'utf8');
     const fileName = path_1.default.basename(filePath, '.md');
     const intent = sectionValue(content, 'Intent')[0] || 'No intent summary available.';
     return {
         id: fileName,
-        title: humanizeJobName(fileName),
+        title: humanizeName(fileName),
         groupId,
-        groupLabel: MANAGER_GROUPS[groupId],
+        groupLabel,
         intent,
         stubPath: toPosix(path_1.default.relative(projectPath, filePath)),
     };
 }
-const readMarkdownFiles = (dirPath) => {
-    if (!fs_1.default.existsSync(dirPath))
-        return [];
-    return fs_1.default
-        .readdirSync(dirPath, { withFileTypes: true })
-        .filter((entry) => entry.isFile() && entry.name.endsWith('.md'))
-        .map((entry) => path_1.default.join(dirPath, entry.name))
-        .sort((a, b) => a.localeCompare(b));
-};
 function summarizeProject(projectPath) {
     if (!projectPath) {
         return {
@@ -96,12 +139,16 @@ function summarizeProject(projectPath) {
         };
     }
     const fraimDir = (0, project_fraim_paths_1.getWorkspaceFraimDir)(projectPath);
-    if (!fs_1.default.existsSync(fraimDir)) {
+    const registryEmployeeDir = path_1.default.join(projectPath, 'registry', 'jobs', 'ai-employee');
+    const registryManagerDir = path_1.default.join(projectPath, 'registry', 'jobs', 'ai-manager');
+    const hasFraim = fs_1.default.existsSync(fraimDir);
+    const hasRegistry = fs_1.default.existsSync(registryEmployeeDir) || fs_1.default.existsSync(registryManagerDir);
+    if (!hasFraim && !hasRegistry) {
         return {
             path: projectPath,
             exists: true,
             hasFraim: false,
-            message: 'This folder does not contain a local fraim/ directory.',
+            message: 'This folder does not contain a local fraim/ or registry/jobs/ directory.',
         };
     }
     return {
@@ -110,22 +157,211 @@ function summarizeProject(projectPath) {
         hasFraim: true,
     };
 }
+function resolveLayerRoot(projectPath, layer) {
+    if (layer.base === 'registry') {
+        // The registry is the FRAIM source-of-truth catalog. It lives at the
+        // project root in the FRAIM source repo (this repo) and in any project
+        // that ships dist/registry alongside its source. Not under fraim/.
+        return path_1.default.join(projectPath, 'registry', ...layer.segments);
+    }
+    // 'fraim' layers live inside <projectRoot>/fraim/.
+    return path_1.default.join((0, project_fraim_paths_1.getWorkspaceFraimDir)(projectPath), ...layer.segments);
+}
+function discoverLayers(projectPath, layers) {
+    const out = [];
+    for (const layer of layers) {
+        const layerRoot = resolveLayerRoot(projectPath, layer);
+        for (const categoryName of readSubdirectoryNames(layerRoot)) {
+            out.push({
+                layerRoot,
+                categoryId: categoryName,
+                categoryDir: path_1.default.join(layerRoot, categoryName),
+            });
+        }
+    }
+    return out;
+}
 function discoverEmployeeJobs(projectPath) {
     const project = summarizeProject(projectPath);
     if (!project.exists || !project.hasFraim)
         return [];
-    const fraimDir = (0, project_fraim_paths_1.getWorkspaceFraimDir)(projectPath);
-    return Object.keys(EMPLOYEE_CATEGORIES)
-        .flatMap((categoryId) => readMarkdownFiles(path_1.default.join(fraimDir, 'ai-employee', 'jobs', categoryId)).map((filePath) => parseJobStub(filePath, categoryId, projectPath)));
+    const layers = discoverLayers(projectPath, EMPLOYEE_JOB_LAYERS);
+    // Group by categoryId so all layers contribute to the same labelled category.
+    const jobsByKey = new Map();
+    for (const layer of layers) {
+        const categoryLabel = humanizeName(layer.categoryId);
+        for (const fileName of readMarkdownFileNames(layer.categoryDir)) {
+            const filePath = path_1.default.join(layer.categoryDir, fileName);
+            const job = parseJobStub(filePath, layer.categoryId, categoryLabel, projectPath);
+            // Later layers override earlier layers on {category, jobId} collision —
+            // personalized-employee wins over the synced ai-employee baseline.
+            jobsByKey.set(`${job.categoryId}::${job.id}`, job);
+        }
+    }
+    // Stable sort: category label, then job title.
+    return [...jobsByKey.values()].sort((a, b) => {
+        if (a.categoryLabel !== b.categoryLabel)
+            return a.categoryLabel.localeCompare(b.categoryLabel);
+        return a.title.localeCompare(b.title);
+    });
 }
 function discoverManagerTemplates(projectPath) {
     const project = summarizeProject(projectPath);
     if (!project.exists || !project.hasFraim)
         return [];
-    const fraimDir = (0, project_fraim_paths_1.getWorkspaceFraimDir)(projectPath);
-    return Object.keys(MANAGER_GROUPS)
-        .flatMap((groupId) => readMarkdownFiles(path_1.default.join(fraimDir, 'ai-manager', 'jobs', groupId)).map((filePath) => parseManagerStub(filePath, groupId, projectPath)));
+    const layers = discoverLayers(projectPath, MANAGER_JOB_LAYERS);
+    const templatesByKey = new Map();
+    for (const layer of layers) {
+        const groupLabel = humanizeName(layer.categoryId);
+        for (const fileName of readMarkdownFileNames(layer.categoryDir)) {
+            const filePath = path_1.default.join(layer.categoryDir, fileName);
+            const template = parseManagerStub(filePath, layer.categoryId, groupLabel, projectPath);
+            templatesByKey.set(`${template.groupId}::${template.id}`, template);
+        }
+    }
+    return [...templatesByKey.values()].sort((a, b) => {
+        if (a.groupLabel !== b.groupLabel)
+            return a.groupLabel.localeCompare(b.groupLabel);
+        return a.title.localeCompare(b.title);
+    });
 }
-function getAiHubCategories() {
-    return Object.values(EMPLOYEE_CATEGORIES);
+// Issue #347 — load the phase list for a job, in declaration order, with
+// only the phases reachable on the active run's path. The Hub UI uses
+// this to render the pizza tracker.
+// Namespace prefixes the friendly-label formatter strips. Order matters
+// only for tie-breaking; we always pick the longest match.
+const KNOWN_PHASE_PREFIXES = [
+    'implement-',
+    'address-',
+    'spec-',
+    'design-',
+    'context-',
+];
+function friendlyPhaseLabel(phaseId, override) {
+    if (override)
+        return override;
+    let body = phaseId;
+    for (const prefix of KNOWN_PHASE_PREFIXES) {
+        if (body.startsWith(prefix) && body.length > prefix.length) {
+            body = body.slice(prefix.length);
+            break;
+        }
+    }
+    const spaced = body.replace(/-/g, ' ').trim();
+    if (spaced.length === 0)
+        return phaseId;
+    // Spec R1.2: first letter uppercase, rest lowercase.
+    return spaced[0].toUpperCase() + spaced.slice(1).toLowerCase();
+}
+function readJobFrontmatter(filePath) {
+    const raw = fs_1.default.readFileSync(filePath, 'utf8');
+    const match = raw.match(/^---\r?\n([\s\S]*?)\r?\n---/);
+    if (!match)
+        return null;
+    const block = match[1].trim();
+    if (!block.startsWith('{'))
+        return null;
+    try {
+        return JSON.parse(block);
+    }
+    catch {
+        return null;
+    }
+}
+function findJobStubPath(projectPath, jobId) {
+    // Walk the same layer set used by discoverEmployeeJobs (employee layers
+    // are first-class jobs; manager layers are templates and don't carry
+    // multi-phase frontmatter). Personalized layer wins over baseline.
+    const layers = discoverLayers(projectPath, EMPLOYEE_JOB_LAYERS);
+    let resolved = null;
+    for (const layer of layers) {
+        const candidate = path_1.default.join(layer.categoryDir, `${jobId}.md`);
+        if (fs_1.default.existsSync(candidate)) {
+            resolved = candidate; // do not break — later layers override
+        }
+    }
+    return resolved;
+}
+// Resolve a phase's `onSuccess` edge to the next phase id given the run's
+// discriminant. Returns null when the edge is absent or terminal.
+function nextPhase(edge, discriminant) {
+    if (edge == null)
+        return null;
+    if (typeof edge === 'string')
+        return edge;
+    if (typeof edge === 'object') {
+        if (typeof edge[discriminant] === 'string')
+            return edge[discriminant];
+        if (typeof edge.default === 'string')
+            return edge.default;
+    }
+    return null;
+}
+function loadJobPhases(jobId, projectPath, discriminant = 'feature') {
+    const stubPath = findJobStubPath(projectPath, jobId);
+    if (!stubPath)
+        return [];
+    const fm = readJobFrontmatter(stubPath);
+    if (!fm || !fm.initialPhase || !fm.phases)
+        return [];
+    const visited = new Set();
+    const ordered = [];
+    let cursor = fm.initialPhase;
+    // Walk onSuccess edges to compute the path; guard against cycles by
+    // tracking visited phase ids. A phase can only appear once in the path.
+    while (cursor && !visited.has(cursor)) {
+        visited.add(cursor);
+        ordered.push(cursor);
+        const phaseDef = fm.phases[cursor];
+        if (!phaseDef)
+            break;
+        cursor = nextPhase(phaseDef.onSuccess, discriminant);
+    }
+    const labels = fm.phaseLabels || {};
+    return ordered.map((id) => ({ id, label: friendlyPhaseLabel(id, labels[id]) }));
+}
+// Issue #347 — return the set of ALL phase ids declared in the job's
+// frontmatter (not just the onSuccess-reachable path). Used by
+// deriveStages to vet whether a visited phase id genuinely belongs to
+// this job before appending it to the tracker, so cross-job pollution
+// (agent calling seekMentoring for a different job mid-run) cannot
+// surface stages from elsewhere.
+function loadAllJobPhaseIds(jobId, projectPath) {
+    const stubPath = findJobStubPath(projectPath, jobId);
+    if (!stubPath)
+        return new Set();
+    const fm = readJobFrontmatter(stubPath);
+    if (!fm || !fm.phases)
+        return new Set();
+    return new Set(Object.keys(fm.phases));
+}
+// Issue #347 — public exposure of the friendly-label rule so callers
+// outside catalog.ts can render labels for phases that exist in the
+// frontmatter but weren't on the reachable path returned by loadJobPhases.
+function labelForPhaseId(phaseId, jobId, projectPath) {
+    const stubPath = findJobStubPath(projectPath, jobId);
+    if (stubPath) {
+        const fm = readJobFrontmatter(stubPath);
+        if (fm?.phaseLabels?.[phaseId])
+            return fm.phaseLabels[phaseId];
+    }
+    return friendlyPhaseLabel(phaseId);
+}
+function getAiHubCategories(projectPath) {
+    const project = summarizeProject(projectPath);
+    if (!project.exists || !project.hasFraim)
+        return [];
+    // A category is any directory found at any layer; deduplicate by id.
+    const layers = discoverLayers(projectPath, EMPLOYEE_JOB_LAYERS);
+    const seen = new Map();
+    for (const layer of layers) {
+        if (!seen.has(layer.categoryId)) {
+            seen.set(layer.categoryId, {
+                id: layer.categoryId,
+                label: humanizeName(layer.categoryId),
+                description: `${humanizeName(layer.categoryId)} jobs discovered in this project.`,
+            });
+        }
+    }
+    return [...seen.values()].sort((a, b) => a.label.localeCompare(b.label));
 }

package/dist/src/ai-hub/desktop-main.js

@@ -48,7 +48,7 @@ function stopServerOnce() {
 async function createWindow(url) {
     const { width, height } = preferredWindowSize();
     mainWindow = new electron_1.BrowserWindow({
-        title: 'Visa AI Hub',
+        title: 'AI Hub',
         width,
         height,
         minWidth: 1400,
@@ -86,7 +86,7 @@ async function launchDesktopShell(options) {
 async function bootstrap() {
     const options = parseArgs(process.argv.slice(2));
     await electron_1.app.whenReady();
-    electron_1.app.setName('Visa AI Hub');
+    electron_1.app.setName('AI Hub');
     electron_1.app.on('activate', () => {
         if (electron_1.BrowserWindow.getAllWindows().length === 0) {
             void launchDesktopShell(options);