fraim-framework 2.0.124 → 2.0.126

package/bin/fraim.js

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

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

@@ -1,6 +1,7 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.FRAIM_INVOCATION_BODY = exports.CURSOR_MDC_FRONTMATTER = exports.FRAIM_LAUNCH_PHRASE = void 0;
+exports.FRAIM_INVOCATION_BODY = exports.FRAIM_DEFERRED_TOOL_PRELOAD = exports.CURSOR_MDC_FRONTMATTER = exports.FRAIM_LAUNCH_PHRASE = void 0;
+exports.buildFraimInvocationBody = buildFraimInvocationBody;
 exports.buildClaudeSkillContent = buildClaudeSkillContent;
 exports.buildClaudeCommandShimContent = buildClaudeCommandShimContent;
 exports.buildClaudeSlashCommandContent = buildClaudeSlashCommandContent;
@@ -14,9 +15,45 @@ exports.CURSOR_MDC_FRONTMATTER = `---
 description: FRAIM discovery and execution contract
 alwaysApply: true
 ---`;
-exports.FRAIM_INVOCATION_BODY = `Follow this process:
+exports.FRAIM_DEFERRED_TOOL_PRELOAD = [
+    'fraim_connect',
+    'list_fraim_jobs',
+    'get_fraim_job',
+    'get_fraim_file',
+    'seekMentoring'
+];
+function buildDeferredToolBootstrapSection(profile) {
+    if (profile === 'none') {
+        return '';
+    }
+    const preloadList = exports.FRAIM_DEFERRED_TOOL_PRELOAD.map((toolName) => `\`${toolName}\``).join(', ');
+    switch (profile) {
+        case 'claude-toolsearch':
+            return `0. **Preload deferred FRAIM tools when needed**:
+   - If FRAIM MCP tools are unavailable because this host lazily loads deferred tool schemas, call \`ToolSearch\` once to load ${preloadList}.
+   - Do the preload as one batched discovery step, not one search per tool.
+
+`;
+        case 'codex-tool-search':
+            return `0. **Preload deferred FRAIM tools when needed**:
+   - If FRAIM MCP tools are unavailable because this host lazily loads deferred tool schemas, call \`tool_search\` once to load ${preloadList}.
+   - Do the preload as one batched discovery step, not one search per tool.
+
+`;
+        case 'generic-tool-discovery':
+            return `0. **Preload deferred FRAIM tools when needed**:
+   - If FRAIM MCP tools are unavailable because this host lazily loads deferred tool schemas, use the host's tool discovery surface once to load ${preloadList}.
+   - Do the preload as one batched discovery step, not one search per tool.
 
-1. **If the user did not specify a FRAIM job or topic**:
+`;
+        default:
+            return '';
+    }
+}
+function buildFraimInvocationBody(profile = 'none') {
+    return `Follow this process:
+
+${buildDeferredToolBootstrapSection(profile)}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**:
@@ -27,20 +64,22 @@ exports.FRAIM_INVOCATION_BODY = `Follow this process:
    - 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.
+   - 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.
 `;
+}
+exports.FRAIM_INVOCATION_BODY = buildFraimInvocationBody();
 function buildClaudeSkillContent() {
-    return `# FRAIM
-
-${exports.FRAIM_INVOCATION_BODY}`;
+    return `# FRAIM
+
+${buildFraimInvocationBody('claude-toolsearch')}`;
 }
 function buildClaudeCommandShimContent() {
-    return `# FRAIM Compatibility Command
-
-Use the FRAIM skill when Claude exposes skills directly. This compatibility command keeps \`/fraim\` working on surfaces that still discover legacy command files.
-
-${exports.FRAIM_INVOCATION_BODY}`;
+    return `# FRAIM Compatibility Command
+
+Use the FRAIM skill when Claude exposes skills directly. This compatibility command keeps \`/fraim\` working on surfaces that still discover legacy command files.
+
+${buildFraimInvocationBody('claude-toolsearch')}`;
 }
 function buildClaudeSlashCommandContent() {
     return buildClaudeCommandShimContent();
@@ -50,23 +89,23 @@ function buildCursorMentionRuleContent() {
 
 # FRAIM
 
-${exports.FRAIM_INVOCATION_BODY}
+${buildFraimInvocationBody('generic-tool-discovery')}
 `;
 }
 function buildCodexSkillContent() {
     return `# FRAIM
 
-${exports.FRAIM_INVOCATION_BODY}`;
+${buildFraimInvocationBody('codex-tool-search')}`;
 }
 function buildWindsurfCommandContent() {
     return `# FRAIM
 
-${exports.FRAIM_INVOCATION_BODY}`;
+${buildFraimInvocationBody('generic-tool-discovery')}`;
 }
 function buildKiroCommandContent() {
     return `# FRAIM
 
-${exports.FRAIM_INVOCATION_BODY}`;
+${buildFraimInvocationBody('generic-tool-discovery')}`;
 }
 function describeInvocationSurface(ideName, invocationProfile) {
     switch (invocationProfile) {

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

@@ -74,7 +74,7 @@ This repository uses FRAIM.
     const cursorManagedBody = buildManagedSection(`
 # FRAIM
 
-${ide_invocation_surfaces_1.FRAIM_INVOCATION_BODY}
+${(0, ide_invocation_surfaces_1.buildFraimInvocationBody)('generic-tool-discovery')}
 `);
     const copilotBody = buildManagedSection(`
 ## FRAIM
@@ -101,7 +101,7 @@ Use the stubs here to discover which FRAIM job, skill, or rule is relevant, then
 `;
     const vscodePrompt = `# FRAIM
 
-${ide_invocation_surfaces_1.FRAIM_INVOCATION_BODY}`;
+${(0, ide_invocation_surfaces_1.buildFraimInvocationBody)('generic-tool-discovery')}`;
     return [
         { path: 'AGENTS.md', content: markdownBody },
         { path: 'CLAUDE.md', content: markdownBody },

package/dist/src/cli/utils/project-bootstrap.js

@@ -8,6 +8,7 @@ exports.recordPathStatus = recordPathStatus;
 exports.buildInitProjectSummary = buildInitProjectSummary;
 exports.printInitProjectSummary = printInitProjectSummary;
 const chalk_1 = __importDefault(require("chalk"));
+const ONBOARDING_VIDEO_PLAYLIST_URL = 'https://fraimworks.ai/resources.html#videos';
 function formatModeLabel(mode) {
     switch (mode) {
         case 'conversational':
@@ -21,11 +22,11 @@ function formatModeLabel(mode) {
 function getModeSpecificNextStep(mode) {
     switch (mode) {
         case 'conversational':
-            return 'The agent will focus on project context, validation commands, and durable repo rules.';
+            return `The agent will focus on project context, validation commands, and durable repo rules. For a walkthrough, watch the onboarding videos at ${ONBOARDING_VIDEO_PLAYLIST_URL}.`;
         case 'split':
-            return 'The agent will confirm the code-host and issue-tracker split, then ask only for the missing project details.';
+            return `The agent will confirm the code-host and issue-tracker split, then ask only for the missing project details. For a walkthrough, watch the onboarding videos at ${ONBOARDING_VIDEO_PLAYLIST_URL}.`;
         default:
-            return 'The agent will review the detected repo setup, then ask only for the highest-value missing project details.';
+            return `The agent will review the detected repo setup, then ask only for the highest-value missing project details. For a walkthrough, watch the onboarding videos at ${ONBOARDING_VIDEO_PLAYLIST_URL}.`;
     }
 }
 function createInitProjectResult(projectName, mode) {

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

@@ -26,7 +26,11 @@ exports.validateQualityEvidence = validateQualityEvidence;
 exports.buildQualityRejectionMessage = buildQualityRejectionMessage;
 exports.QUALITY_REGISTRY = {
     // Customer Development
-    'process-interview-notes': { stage: 'customer-development', enforced: true, telemetryKind: 'score' },
+    // review-customer-development is the sole quality emitter for this stage.
+    // process-interview-notes is retained here for stage mapping only; it does
+    // not emit (enforced: false).
+    'process-interview-notes': { stage: 'customer-development', enforced: false },
+    'review-customer-development': { stage: 'customer-development', enforced: true, telemetryKind: 'score' },
     'triage-customer-needs': { stage: 'customer-development', enforced: true, telemetryKind: 'gate' },
     'interview-preparation': { stage: 'customer-discovery', enforced: false },
     // Business Strategy
@@ -39,6 +43,7 @@ exports.QUALITY_REGISTRY = {
     'test-quality-assessment': { stage: 'test-quality', enforced: true, telemetryKind: 'score' },
     // Security
     'security-review': { stage: 'security', enforced: true, telemetryKind: 'score' },
+    'production-readiness-review': { stage: 'production-readiness', enforced: true, telemetryKind: 'score' },
     // Fundraising
     'investor-pitch-preparation': { stage: 'fundraising', enforced: false },
     // Go-to-Market
@@ -73,6 +78,7 @@ exports.STAGE_DISPLAY_NAMES = {
     'product-quality': 'Product Quality',
     'test-quality': 'Test Quality',
     'security': 'Security',
+    'production-readiness': 'Production Readiness',
     'fundraising': 'Fundraising',
     'go-to-market': 'Go-to-Market',
 };
@@ -86,6 +92,7 @@ exports.ALL_STAGE_CATEGORIES = [
     'product-quality',
     'test-quality',
     'security',
+    'production-readiness',
     'fundraising',
     'go-to-market',
 ];
@@ -114,20 +121,85 @@ const GATE_REQUIRED_FIELDS = [
 const UNIVERSAL_REQUIRED_FIELDS = [
     { path: 'composite', type: 'number' },
 ];
+const SCORE_DIMENSION_REQUIRED_FIELDS = [
+    { suffix: 'score', type: 'number' },
+    { suffix: 'rationale', type: 'string' }
+];
+const QUALITY_SCORE_DIMENSIONS = {
+    'review-customer-development': [
+        'icpCoherence',
+        'interviewCoverage',
+        'evidenceQuality',
+        'patternSaturation',
+        'signalToProduct'
+    ],
+    'review-business-strategy': [
+        'marketEvidence',
+        'competitiveRigor',
+        'unitEconomics',
+        'strategicCoherence'
+    ],
+    'branding-quality-audit': [
+        'clarity',
+        'differentiation',
+        'coherence',
+        'proof',
+        'identityExpressiveness',
+        'governanceReadiness'
+    ],
+    'code-quality-assessment': [
+        'typeSafety',
+        'errorHandling',
+        'architecture',
+        'maintainability'
+    ],
+    'test-quality-assessment': [
+        'coverage',
+        'testIntegrity',
+        'testDesign',
+        'reliability'
+    ],
+    'security-review': [
+        'findingSeverity',
+        'remediationReadiness',
+        'coverageCompleteness'
+    ],
+    'production-readiness-review': [
+        'securityPosture',
+        'availabilityResilience',
+        'backupRestore',
+        'observabilityOps',
+        'releaseSafety',
+        'governanceRunbooks'
+    ]
+};
+function requiredDimensionFields(jobName) {
+    const dimensions = QUALITY_SCORE_DIMENSIONS[jobName] ?? [];
+    return dimensions.flatMap((dimension) => SCORE_DIMENSION_REQUIRED_FIELDS.map(({ suffix, type }) => ({
+        path: `${dimension}.${suffix}`,
+        type
+    })));
+}
 /**
  * Returns the required quality fields for a given job.
- * Customer-development jobs retain the strict V1 schema.
- * All other jobs require only a composite score (principle-based, not prescriptive).
+ * Gate-only jobs use the gate schema. The strict V1 interview schema is
+ * pinned to process-interview-notes for defense-in-depth on the
+ * /api/analytics/quality-score endpoint. Scored quality review jobs require
+ * their stage-specific rubric dimensions as direct `{ score, rationale }`
+ * properties so the Quality view can render those dimensions dynamically.
  */
 function getRequiredFieldsForJob(jobName) {
     const entry = exports.QUALITY_REGISTRY[jobName];
     if (entry?.telemetryKind === 'gate') {
         return GATE_REQUIRED_FIELDS;
     }
-    if (entry?.stage === 'customer-development') {
+    if (jobName === 'process-interview-notes') {
         return CUSTOMER_DEV_REQUIRED_FIELDS;
     }
-    return UNIVERSAL_REQUIRED_FIELDS;
+    return [
+        ...UNIVERSAL_REQUIRED_FIELDS,
+        ...requiredDimensionFields(jobName)
+    ];
 }
 /**
  * @deprecated Use getRequiredFieldsForJob() for stage-aware validation.
@@ -188,6 +260,9 @@ function buildQualityRejectionMessage(jobName, currentPhase, errors) {
     const entry = exports.QUALITY_REGISTRY[jobName];
     const isGateOnly = entry?.telemetryKind === 'gate';
     const isCustomerDev = entry?.stage === 'customer-development';
+    const dimensionExamples = (QUALITY_SCORE_DIMENSIONS[jobName] ?? ['marketEvidence', 'unitEconomics'])
+        .map((dimension) => `    ${dimension}: { score: <number>, rationale: "<string>" },`)
+        .join('\n');
     const schemaExample = isGateOnly
         ? [
             '```javascript',
@@ -226,9 +301,7 @@ function buildQualityRejectionMessage(jobName, currentPhase, errors) {
                 '  quality: {',
                 '    composite: <number 0-10>,',
                 '    coaching: "<actionable recommendation>",',
-                '    marketEvidence: { score: <number>, rationale: "<string>" }, // flat, NO "dimensions" wrapper',
-                '    unitEconomics: { score: <number>, rationale: "<string>" },',
-                '    // add other sub-scores as direct properties',
+                dimensionExamples,
                 '  }',
                 '}',
                 '```'

package/dist/src/core/utils/git-utils.js

@@ -7,6 +7,18 @@ exports.determineSchema = determineSchema;
 exports.getDefaultBranch = getDefaultBranch;
 exports.sanitizeRepoIdentifier = sanitizeRepoIdentifier;
 const child_process_1 = require("child_process");
+function extractLocalFolderLabel(rawPath) {
+    const normalized = rawPath
+        .trim()
+        .replace(/^file:\/\//i, '')
+        .replace(/\\/g, '/')
+        .replace(/\/+$/, '');
+    if (!normalized)
+        return undefined;
+    const parts = normalized.split('/').filter(Boolean);
+    const candidate = parts[parts.length - 1];
+    return candidate || undefined;
+}
 /**
  * Gets a unique port based on the current git branch name (if it's an issue branch)
  * Default to 15302 if not on an issue branch
@@ -106,13 +118,14 @@ function sanitizeRepoIdentifier(repoUrl) {
         return undefined;
     }
     const trimmed = repoUrl.trim();
-    // Reject local paths (Windows and POSIX)
+    // Convert local paths to just the folder name for privacy-safe workspace labeling.
     if (trimmed.startsWith('/') ||
         trimmed.startsWith('\\') ||
-        /^[a-zA-Z]:\\/.test(trimmed) ||
+        /^[a-zA-Z]:[\\/]/.test(trimmed) ||
         trimmed.startsWith('./') ||
-        trimmed.startsWith('../')) {
-        return undefined;
+        trimmed.startsWith('../') ||
+        trimmed.startsWith('file://')) {
+        return extractLocalFolderLabel(trimmed);
     }
     // Normalize GitHub/GitLab SSH and HTTPS URLs
     // Patterns:
@@ -144,5 +157,9 @@ function sanitizeRepoIdentifier(repoUrl) {
     catch (e) {
         // Not a valid URL
     }
+    // Preserve plain folder labels that are already privacy-safe and not path-like.
+    if (!trimmed.includes('/') && !trimmed.includes('\\') && !trimmed.includes('://')) {
+        return trimmed;
+    }
     return undefined;
 }

package/dist/src/core/utils/job-aliases.js

@@ -0,0 +1,47 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.DEPRECATED_FRAIM_JOB_NAMES = void 0;
+exports.resolveFraimJobName = resolveFraimJobName;
+exports.isListableFraimJob = isListableFraimJob;
+const DEPRECATED_TO_CANONICAL_JOB_MAP = {
+    'learn-and-scale': 'upskill-employee',
+    'model-behavior': 'upskill-employee',
+    'promote-learning': 'upskill-employee',
+    'refine-jobs': 'upskill-employee',
+    'refine-skills': 'upskill-employee'
+};
+const DIRECT_JOB_ALIASES = {
+    'sleep on learnings': 'sleep-on-learnings'
+};
+exports.DEPRECATED_FRAIM_JOB_NAMES = new Set(Object.keys(DEPRECATED_TO_CANONICAL_JOB_MAP));
+function normalizeJobLookupInput(input) {
+    return input.trim().toLowerCase().replace(/[_\s]+/g, '-');
+}
+function resolveFraimJobName(input) {
+    const normalizedJobName = normalizeJobLookupInput(input);
+    const directAliasTarget = DIRECT_JOB_ALIASES[input.trim().toLowerCase()];
+    if (directAliasTarget) {
+        return {
+            requestedJobName: input,
+            normalizedJobName,
+            canonicalJobName: directAliasTarget
+        };
+    }
+    const deprecatedAliasTarget = DEPRECATED_TO_CANONICAL_JOB_MAP[normalizedJobName];
+    if (deprecatedAliasTarget) {
+        return {
+            requestedJobName: input,
+            normalizedJobName,
+            canonicalJobName: deprecatedAliasTarget,
+            deprecatedAliasTarget
+        };
+    }
+    return {
+        requestedJobName: input,
+        normalizedJobName,
+        canonicalJobName: normalizedJobName
+    };
+}
+function isListableFraimJob(jobName) {
+    return !exports.DEPRECATED_FRAIM_JOB_NAMES.has(normalizeJobLookupInput(jobName));
+}

package/dist/src/core/utils/workflow-parser.js

@@ -5,15 +5,13 @@ const fs_1 = require("fs");
 const path_1 = require("path");
 class WorkflowParser {
     static extractMetadataBlock(content) {
-        // Allow leading comments and whitespace before frontmatter
-        const frontmatterMatch = content.match(/^[\s\S]*?---\r?\n([\s\S]+?)\r?\n---/);
+        const frontmatterMatch = content.match(/^---\r?\n([\s\S]+?)\r?\n---/);
         if (frontmatterMatch) {
             try {
-                const startIndex = frontmatterMatch.index || 0;
                 return {
                     state: 'valid',
                     metadata: JSON.parse(frontmatterMatch[1]),
-                    bodyStartIndex: startIndex + frontmatterMatch[0].length
+                    bodyStartIndex: frontmatterMatch[0].length
                 };
             }
             catch {
@@ -109,7 +107,7 @@ class WorkflowParser {
             overview = contentAfterMetadata;
         }
         const phases = new Map();
-        const phaseSections = restOfContent.split(/^##\s+Phase:\s*/im);
+        const phaseSections = restOfContent.split(/^##\s+Phase:\s+/m);
         if (!metadata.phases) {
             metadata.phases = {};
         }

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

@@ -0,0 +1,114 @@
+"use strict";
+/**
+ * Static price table for converting per-agent token counters to USD.
+ *
+ * Issue #330 / R1.3 / C4 (ISO 27001 A.5.31).
+ *
+ * Each entry MUST carry `source` (a citation pointing back to the vendor's
+ * published pricing page) and `verifiedOn` (an ISO date string). The
+ * `agent-token-prices.test.ts` lint fails CI if any entry exceeds 180 days
+ * since `verifiedOn` so this table is reviewed at least quarterly.
+ *
+ * Prices are USD per million tokens.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.AGENT_TOKEN_PRICES = void 0;
+exports.lookupPrice = lookupPrice;
+exports.computeCostUsd = computeCostUsd;
+exports.AGENT_TOKEN_PRICES = [
+    // Anthropic — Claude (used by Claude Code).
+    // Note: when Claude Code emits cost via OTLP we read it directly; this
+    // table backstops cost computation for legacy/no-cost-metric snapshots
+    // and lets per-agent comparison panels report a model-attributed cost
+    // even when a snapshot lacks a costUsd field.
+    {
+        agent: 'claude-code',
+        model: 'claude-opus-4-7',
+        inputPerMTok: 15.00,
+        outputPerMTok: 75.00,
+        cacheReadPerMTok: 1.50,
+        cacheCreationPerMTok: 18.75,
+        source: 'https://www.anthropic.com/pricing',
+        verifiedOn: '2026-04-29',
+    },
+    {
+        agent: 'claude-code',
+        model: 'claude-sonnet-4-6',
+        inputPerMTok: 3.00,
+        outputPerMTok: 15.00,
+        cacheReadPerMTok: 0.30,
+        cacheCreationPerMTok: 3.75,
+        source: 'https://www.anthropic.com/pricing',
+        verifiedOn: '2026-04-29',
+    },
+    {
+        agent: 'claude-code',
+        model: 'claude-haiku-4-5',
+        inputPerMTok: 1.00,
+        outputPerMTok: 5.00,
+        cacheReadPerMTok: 0.10,
+        cacheCreationPerMTok: 1.25,
+        source: 'https://www.anthropic.com/pricing',
+        verifiedOn: '2026-04-29',
+    },
+    // OpenAI — GPT-5 Codex (used by Codex CLI).
+    {
+        agent: 'codex',
+        model: 'gpt-5-codex',
+        inputPerMTok: 5.00,
+        outputPerMTok: 15.00,
+        cacheReadPerMTok: 0.50,
+        cacheCreationPerMTok: 0,
+        source: 'https://openai.com/api/pricing/',
+        verifiedOn: '2026-04-29',
+    },
+    {
+        agent: 'codex',
+        model: 'gpt-5',
+        inputPerMTok: 5.00,
+        outputPerMTok: 15.00,
+        cacheReadPerMTok: 0.50,
+        cacheCreationPerMTok: 0,
+        source: 'https://openai.com/api/pricing/',
+        verifiedOn: '2026-04-29',
+    },
+    // Real Codex CLI 0.125.0 emits `gpt-5.5` on turn_context.payload.model.
+    // Treated as the gpt-5 family for pricing until OpenAI publishes a
+    // distinct rate card. Conservative estimate; refresh on next quarterly
+    // verification pass.
+    {
+        agent: 'codex',
+        model: 'gpt-5.5',
+        inputPerMTok: 5.00,
+        outputPerMTok: 15.00,
+        cacheReadPerMTok: 0.50,
+        cacheCreationPerMTok: 0,
+        source: 'https://openai.com/api/pricing/ (gpt-5 row, applied to gpt-5.5 as nearest published rate)',
+        verifiedOn: '2026-04-30',
+    },
+];
+/**
+ * Look up the price entry for an agent + model. Agent is matched
+ * case-insensitively. Returns null when no matching entry exists — the
+ * adapter is then expected to skip cost computation rather than guess.
+ */
+function lookupPrice(agent, model) {
+    if (!agent || !model)
+        return null;
+    const a = agent.toLowerCase();
+    return exports.AGENT_TOKEN_PRICES.find(e => e.agent === a && e.model === model) || null;
+}
+/**
+ * Compute USD cost from cumulative token counts. Returns 0 when no price
+ * entry exists for the agent/model — the caller decides whether to drop
+ * the snapshot entirely or surface a partial-coverage warning.
+ */
+function computeCostUsd(agent, model, counts) {
+    const price = lookupPrice(agent, model);
+    if (!price)
+        return 0;
+    return ((counts.inputTokens / 1_000_000) * price.inputPerMTok +
+        (counts.outputTokens / 1_000_000) * price.outputPerMTok +
+        (counts.cacheReadTokens / 1_000_000) * price.cacheReadPerMTok +
+        (counts.cacheCreationTokens / 1_000_000) * price.cacheCreationPerMTok);
+}