fraim 2.0.108 → 2.0.109

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

@@ -0,0 +1,121 @@
+"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.QUALITY_PRODUCING_JOBS = void 0;
+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 = [
+    'process-interview-notes',
+    'triage-customer-needs'
+];
+/**
+ * Required numeric fields inside `evidence.quality` for QUALITY_PRODUCING_JOBS.
+ * The schema is intentionally lenient beyond these — extra fields are
+ * allowed so per-job assessment can evolve — but these five gate completion.
+ */
+exports.REQUIRED_QUALITY_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' }
+];
+/**
+ * Validate an `evidence.quality` object against REQUIRED_QUALITY_FIELDS.
+ * Returns null if valid, or an array of human-readable error strings.
+ *
+ * Design note: when `quality` is entirely missing we still walk every
+ * required field and emit a per-field error, so the agent sees the
+ * complete schema in one round rather than being told only that
+ * `quality` itself is missing.
+ */
+function validateQualityEvidence(quality) {
+    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;
+    for (const { path, type } of exports.REQUIRED_QUALITY_FIELDS) {
+        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');
+    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 manager dashboard. The following problems were found in \`evidence.quality\`:`,
+        '',
+        errorBullets,
+        '',
+        'Required minimum schema:',
+        '',
+        '```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',
+        '    },',
+        '    interviewee: "<name>",',
+        '    company: "<company>",',
+        '    artifactPath: "docs/customer-development/<slug>-interview.md"',
+        '  }',
+        '}',
+        '```',
+        '',
+        `You are still in phase \`${currentPhase}\`. The job is **not** marked complete. Build the \`evidence.quality\` object from your Phase 4 (\`conversation-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);
+                        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.109",
   "description": "FRAIM CLI - Framework for Rigor-based AI Management (alias for fraim-framework)",
   "main": "index.js",
   "bin": {