fraim 2.0.108 → 2.0.114

package/README.md

@@ -1,5 +1,5 @@
-# 🚀 FRAIM: Framework for Rigor-based AI Management
-**"FRAIM is a step towards the future of how we work."** - Transforming ideas into production code by converting you into an AI manager orchestrating multiple agents with enterprise-grade discipline.
+# 🚀 FRAIM — AI Workforce Infrastructure
+**"Brilliant AI isn't how industries get built. Organizations are."** — FRAIM transforms every layer of the AI-powered company at once: **AI agents** become an accountable, improving workforce; **their operators** become capable AI managers who hold the line on quality, delegation, and evidence; and **executives** gain clear optics on AI proficiency across the entire organization.
 
 
 🚀 **The Problem with AI Coding Today**
@@ -36,7 +36,7 @@ R - Retrospectives: Continuous learning from experience
 
 🤖 **Works with any AI agent** (Cursor, Claude, Windsurf) - no vendor lock-in.
 
-**The bottom line:** FRAIM isn't just about using AI—it's about managing AI teams with the same discipline you'd apply to human developers.
+**The bottom line:** FRAIM isn't just about using AI — it transforms every layer of your AI-powered company: agents become an accountable workforce, operators become capable AI managers, and executives gain clear optics on AI proficiency across the whole org.
 
 
 
@@ -448,9 +448,9 @@ gh issue edit 123 --remove-label "phase:impl" --add-label "phase:tests"
 
 ## 🎯 **The Bottom Line**
 
-**FRAIM isn't just about using AI—it's about managing AI teams with the same discipline you'd apply to human teams.**
+**FRAIM isn't just about using AI — it transforms every layer of your AI-powered company: agents become an accountable workforce, operators become capable AI managers, and executives gain clear optics on AI proficiency across the whole org.**
 
-Stop fighting with AI agents. Start orchestrating them.
+Stop fighting with AI agents. Start building your AI organization.
 
 **This is the future of how we work.**
 

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

@@ -637,10 +637,10 @@ const runSetup = async (options) => {
     console.log(chalk_1.default.green('\n━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━'));
     console.log(chalk_1.default.green('  FRAIM is ready!'));
     console.log(chalk_1.default.green('━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━'));
-    console.log(chalk_1.default.white('\n  FRAIM is an AI management layer that turns you into'));
-    console.log(chalk_1.default.white('  a manager of AI agents. Run multiple agents through'));
-    console.log(chalk_1.default.white('  structured jobs, get manager-style coaching, and build'));
-    console.log(chalk_1.default.white('  a learning loop where agents improve over time.'));
+    console.log(chalk_1.default.white('\n  FRAIM is AI Workforce Infrastructure. It transforms every'));
+    console.log(chalk_1.default.white('  layer of your AI-powered work at once: AI agents become an'));
+    console.log(chalk_1.default.white('  accountable workforce, you become a capable AI manager, and'));
+    console.log(chalk_1.default.white('  your leadership gains clear optics on AI proficiency.'));
     console.log(chalk_1.default.gray('\n  60+ jobs across engineering, marketing, fundraising,'));
     console.log(chalk_1.default.gray('  legal, product, hiring, customer development, and more.'));
     // Show which IDEs were configured and how to use FRAIM in each

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

@@ -0,0 +1,213 @@
+"use strict";
+/**
+ * Quality Evidence Validation (Issue #251)
+ *
+ * Pure helpers for validating the `evidence.quality` object that
+ * quality-producing FRAIM jobs must emit on their final seekMentoring
+ * completion. Lives in src/core so both the local MCP proxy and the
+ * remote server can import the same contract without cross-layer
+ * dependencies.
+ *
+ * Two call sites currently:
+ *   1. src/local-mcp-server/stdio-server.ts — enforces on local
+ *      seekMentoring completion and POSTs valid scores to the remote
+ *      via /api/analytics/quality-score.
+ *   2. src/routes/analytics.ts — defense-in-depth validation on the
+ *      /api/analytics/quality-score endpoint.
+ *
+ * A third (rare) call site lives in src/services/mcp-service.ts for
+ * the case where the local proxy falls through to the remote's own
+ * seekMentoring handler (e.g., when the local AIMentor errors).
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.REQUIRED_QUALITY_FIELDS = exports.ALL_STAGE_CATEGORIES = exports.STAGE_DISPLAY_NAMES = exports.STAGE_CATEGORY_MAP = exports.QUALITY_PRODUCING_JOBS = void 0;
+exports.getRequiredFieldsForJob = getRequiredFieldsForJob;
+exports.validateQualityEvidence = validateQualityEvidence;
+exports.buildQualityRejectionMessage = buildQualityRejectionMessage;
+/**
+ * Jobs that produce a quality assessment and MUST emit a quality score
+ * via `evidence.quality` on their final seekMentoring completion.
+ */
+exports.QUALITY_PRODUCING_JOBS = [
+    // Customer Development
+    'process-interview-notes',
+    'triage-customer-needs',
+    // Business Strategy
+    'business-plan-creation',
+    'pricing-strategy-definition',
+    'founder-market-fit-analysis',
+    'review-business-strategy',
+    // Product Quality
+    'code-quality-assessment',
+    // Test Quality
+    'test-standards-evaluation',
+    'test-coverage-evaluation',
+    'review-test-quality',
+];
+/**
+ * Maps job names to their founder journey stage category.
+ * Used to auto-populate `stageCategory` on quality score records.
+ */
+exports.STAGE_CATEGORY_MAP = {
+    'process-interview-notes': 'customer-development',
+    'triage-customer-needs': 'customer-development',
+    'business-plan-creation': 'business-strategy',
+    'pricing-strategy-definition': 'business-strategy',
+    'founder-market-fit-analysis': 'business-strategy',
+    'review-business-strategy': 'business-strategy',
+    'code-quality-assessment': 'product-quality',
+    'test-standards-evaluation': 'test-quality',
+    'test-coverage-evaluation': 'test-quality',
+    'review-test-quality': 'test-quality',
+};
+/**
+ * Human-readable stage names for dashboard display.
+ */
+exports.STAGE_DISPLAY_NAMES = {
+    'customer-development': 'Customer Development',
+    'business-strategy': 'Business Strategy',
+    'product-quality': 'Product Quality',
+    'test-quality': 'Test Quality',
+    'fundraising': 'Fundraising',
+    'go-to-market': 'Go-to-Market',
+};
+/**
+ * All known stage categories, in display order for the tile grid.
+ */
+exports.ALL_STAGE_CATEGORIES = [
+    'customer-development',
+    'business-strategy',
+    'product-quality',
+    'test-quality',
+    'fundraising',
+    'go-to-market',
+];
+/**
+ * Required fields for customer-development jobs (legacy V1 schema).
+ * These jobs require participant and evidence sub-dimensions.
+ */
+const CUSTOMER_DEV_REQUIRED_FIELDS = [
+    { path: 'composite', type: 'number' },
+    { path: 'participant.fit', type: 'number' },
+    { path: 'participant.urgency', type: 'number' },
+    { path: 'participant.authority', type: 'number' },
+    { path: 'evidence.quoteSpecificityAvg', type: 'number' }
+];
+/**
+ * Required fields for all other quality-producing jobs.
+ * Only composite and coaching are universally required — sub-dimensions
+ * vary by stage and are validated holistically, not mechanically.
+ */
+const UNIVERSAL_REQUIRED_FIELDS = [
+    { path: 'composite', type: 'number' },
+];
+/**
+ * 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).
+ */
+function getRequiredFieldsForJob(jobName) {
+    const stage = exports.STAGE_CATEGORY_MAP[jobName];
+    if (stage === 'customer-development') {
+        return CUSTOMER_DEV_REQUIRED_FIELDS;
+    }
+    return UNIVERSAL_REQUIRED_FIELDS;
+}
+/**
+ * @deprecated Use getRequiredFieldsForJob() for stage-aware validation.
+ * Kept for backward compatibility with existing imports.
+ */
+exports.REQUIRED_QUALITY_FIELDS = CUSTOMER_DEV_REQUIRED_FIELDS;
+/**
+ * Validate an `evidence.quality` object against the required fields for
+ * a given job. If no jobName is provided, falls back to the universal
+ * schema (composite only).
+ *
+ * Returns null if valid, or an array of human-readable error strings.
+ */
+function validateQualityEvidence(quality, jobName) {
+    const errors = [];
+    const isMissing = quality === undefined || quality === null;
+    if (isMissing) {
+        errors.push('evidence.quality is missing');
+    }
+    else if (typeof quality !== 'object' || Array.isArray(quality)) {
+        errors.push('evidence.quality must be an object');
+    }
+    const effective = isMissing || typeof quality !== 'object' || Array.isArray(quality)
+        ? undefined
+        : quality;
+    const requiredFields = jobName ? getRequiredFieldsForJob(jobName) : UNIVERSAL_REQUIRED_FIELDS;
+    for (const { path, type } of requiredFields) {
+        const parts = path.split('.');
+        let cursor = effective;
+        for (const part of parts) {
+            if (cursor && typeof cursor === 'object' && part in cursor) {
+                cursor = cursor[part];
+            }
+            else {
+                cursor = undefined;
+                break;
+            }
+        }
+        if (typeof cursor !== type || (type === 'number' && Number.isNaN(cursor))) {
+            const got = cursor === undefined ? 'missing' : (Number.isNaN(cursor) ? 'NaN' : typeof cursor);
+            errors.push(`evidence.quality.${path} must be a ${type} (got ${got})`);
+        }
+    }
+    return errors.length > 0 ? errors : null;
+}
+/**
+ * Build the rejection message sent back to the agent when a quality-producing
+ * job tries to complete without a valid `evidence.quality` object. The message
+ * lists the specific errors and the required minimum schema so the agent can
+ * fix everything in one round.
+ */
+function buildQualityRejectionMessage(jobName, currentPhase, errors) {
+    const errorBullets = errors.map(e => `- ${e}`).join('\n');
+    const stage = exports.STAGE_CATEGORY_MAP[jobName];
+    const isCustomerDev = stage === 'customer-development';
+    const schemaExample = isCustomerDev
+        ? [
+            '```javascript',
+            'evidence: {',
+            '  quality: {',
+            '    composite: <number 0-10>,',
+            '    participant: { fit: <number 1-10>, urgency: <number 1-10>, authority: <number 1-10> },',
+            '    evidence: {',
+            '      quoteSpecificityAvg: <number 1-10>',
+            '      // other fields are allowed and encouraged but not required',
+            '    },',
+            '    coaching: "<actionable recommendation>",',
+            '    interviewee: "<name>",',
+            '    company: "<company>"',
+            '  }',
+            '}',
+            '```'
+        ]
+        : [
+            '```javascript',
+            'evidence: {',
+            '  quality: {',
+            '    composite: <number 0-10>,',
+            '    coaching: "<actionable recommendation>",',
+            '    // include per-dimension scores with rationale fields',
+            '    // additional fields are encouraged — schema is flexible per stage',
+            '  }',
+            '}',
+            '```'
+        ];
+    return [
+        `❌ **Job completion rejected** for \`${jobName}\`.`,
+        '',
+        `This job is required to emit a quality score on its final \`seekMentoring\` call so the result is captured in \`fraim_quality_scores\` for the quality dashboard. The following problems were found in \`evidence.quality\`:`,
+        '',
+        errorBullets,
+        '',
+        `Required minimum schema for \`${stage ?? 'unknown'}\` stage:`,
+        '',
+        ...schemaExample,
+        '',
+        `You are still in phase \`${currentPhase}\`. The job is **not** marked complete. Build the \`evidence.quality\` object from your quality assessment work and resubmit this final phase.`
+    ].join('\n');
+}

package/dist/src/local-mcp-server/stdio-server.js

@@ -29,6 +29,7 @@ const provider_utils_1 = require("../core/utils/provider-utils");
 const object_utils_1 = require("../core/utils/object-utils");
 const local_registry_resolver_1 = require("../core/utils/local-registry-resolver");
 const ai_mentor_1 = require("../core/ai-mentor");
+const quality_evidence_1 = require("../core/quality-evidence");
 const project_fraim_paths_1 = require("../core/utils/project-fraim-paths");
 const usage_collector_js_1 = require("./usage-collector.js");
 const otlp_metrics_receiver_js_1 = require("./otlp-metrics-receiver.js");
@@ -1664,6 +1665,40 @@ class FraimLocalMCPServer {
                     const mentor = this.getMentor(requestSessionId);
                     const tutoringResponse = await mentor.handleMentoringRequest(args);
                     this.log(`✅ Local seekMentoring succeeded for ${args.jobName}:${args.currentPhase}`);
+                    // Quality enforcement (Issue #251).
+                    //
+                    // The local proxy owns seekMentoring for personalized-job support.
+                    // That means the server-side enforcement in mcp-service.handleSeekMentoring
+                    // rarely fires in practice, so this is the primary enforcement point.
+                    //
+                    // When a QUALITY_PRODUCING_JOBS job reaches its final phase
+                    // (nextPhase === null) with status === 'complete', the agent MUST
+                    // include a valid `evidence.quality` object. If invalid, swap the
+                    // accomplishment message for a rejection and DO NOT emit. If valid,
+                    // fire-and-forget POST to /api/analytics/quality-score so the row
+                    // lands in fraim_quality_scores.
+                    const isQualityJob = quality_evidence_1.QUALITY_PRODUCING_JOBS.includes(args.jobName);
+                    const isFinalCompletion = args.status === 'complete' &&
+                        (tutoringResponse.nextPhase === null || tutoringResponse.nextPhase === undefined);
+                    if (isQualityJob && isFinalCompletion) {
+                        const qualityErrors = (0, quality_evidence_1.validateQualityEvidence)(args.evidence?.quality, args.jobName);
+                        if (qualityErrors) {
+                            this.log(`❌ Quality enforcement rejected ${args.jobName} completion: ${qualityErrors.join('; ')}`);
+                            const rejection = (0, quality_evidence_1.buildQualityRejectionMessage)(args.jobName, args.currentPhase, qualityErrors);
+                            return await this.finalizeLocalToolTextResponse(request, requestSessionId, requestId, rejection);
+                        }
+                        // Valid payload. Emit to the remote asynchronously.
+                        this.emitQualityScoreToRemote({
+                            jobName: args.jobName,
+                            jobId: args.jobId,
+                            sessionId: requestSessionId || args.sessionId || 'unknown',
+                            quality: args.evidence.quality,
+                            artifactPath: args.evidence.quality.artifactPath
+                        }).catch((err) => {
+                            // Best-effort: log but never fail the user-facing response.
+                            this.log(`⚠️ Quality score emission failed: ${err?.message || err}`);
+                        });
+                    }
                     return await this.finalizeLocalToolTextResponse(request, requestSessionId, requestId, tutoringResponse.message);
                 }
                 catch (error) {
@@ -1971,6 +2006,33 @@ class FraimLocalMCPServer {
             this.log(`⚠️ Skipping usage collection: toolName=${toolName}, sessionId=${requestSessionId}`);
         }
     }
+    /**
+     * Emit a quality score to the remote FRAIM server (Issue #251).
+     *
+     * Called from the seekMentoring short-circuit when a QUALITY_PRODUCING_JOBS
+     * job reaches its final phase with a validated `evidence.quality` payload.
+     * Fire-and-forget from the caller's perspective: a failure here is logged
+     * but does not block the user-facing response (analytics capture is best
+     * effort, not blocking).
+     *
+     * On success the remote writes a row to the `fraim_quality_scores` MongoDB
+     * collection which powers the manager dashboard trajectory chart.
+     */
+    async emitQualityScoreToRemote(payload) {
+        const url = `${this.remoteUrl}/api/analytics/quality-score`;
+        this.log(`📊 Emitting quality score → ${url} (job=${payload.jobName}, jobId=${payload.jobId})`);
+        const response = await axios_1.default.post(url, payload, {
+            headers: {
+                'Content-Type': 'application/json',
+                'x-api-key': this.apiKey
+            },
+            timeout: 10000
+        });
+        if (response.status < 200 || response.status >= 300) {
+            throw new Error(`quality-score endpoint returned ${response.status}: ${JSON.stringify(response.data)}`);
+        }
+        this.log(`📊 ✅ Quality score accepted by remote (composite=${payload.quality.composite})`);
+    }
     /**
      * Flush collected usage data to the remote server
      */

package/package.json

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