fraim-hub 2.0.204

package/dist/src/core/brand-store.js

@@ -0,0 +1,232 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.MAX_LOGO_BYTES = exports.ORG_BRAND_FILENAME = void 0;
+exports.resolveBrandColor = resolveBrandColor;
+exports.relativeLuminance = relativeLuminance;
+exports.contrastRatio = contrastRatio;
+exports.hasSufficientContrast = hasSufficientContrast;
+exports.sanitizeSvg = sanitizeSvg;
+exports.sanitizeLogo = sanitizeLogo;
+exports.normalizeBrand = normalizeBrand;
+exports.serializeBrand = serializeBrand;
+exports.parseBrand = parseBrand;
+exports.readBrandFromDir = readBrandFromDir;
+exports.writeBrandToDir = writeBrandToDir;
+/**
+ * Org brand store — Issue #744 (Hub cobranding).
+ *
+ * Deterministic, dependency-free, AI-free logic (architecture-standards §1/§3):
+ * the org brand descriptor (company name, color, logo) is stored ALONGSIDE
+ * company info, in the same org context storage as `org_context.md`
+ * (manager directive, spec R7.4), as a single `org_brand.json` file.
+ *
+ * Security: a manager-supplied logo is a stored-XSS vector. `sanitizeSvg` uses a
+ * strict element/attribute allowlist (not a denylist) and drops scripts, event
+ * handlers, external references, styles, and any non-graphical element, so the
+ * stored logo is safe to inline in the Hub (spec Compliance: SOC2/ISO27001).
+ */
+const fs_1 = __importDefault(require("fs"));
+const path_1 = __importDefault(require("path"));
+/** File name of the brand descriptor, stored next to org_context.md. */
+exports.ORG_BRAND_FILENAME = 'org_brand.json';
+/** Max stored logo size (sanitized SVG markup or data: URI), in bytes. */
+exports.MAX_LOGO_BYTES = 512 * 1024;
+// ── Color ───────────────────────────────────────────────────────────────────
+/**
+ * Normalize a hex color to lowercase `#rrggbb`, expanding `#rgb`. Returns null
+ * for anything that is not a valid 3- or 6-digit hex (named colors, functions,
+ * and injection attempts are rejected).
+ */
+function resolveBrandColor(input) {
+    if (typeof input !== 'string')
+        return null;
+    const raw = input.trim().replace(/^#/, '').toLowerCase();
+    if (/^[0-9a-f]{3}$/.test(raw)) {
+        return '#' + raw.split('').map((c) => c + c).join('');
+    }
+    if (/^[0-9a-f]{6}$/.test(raw)) {
+        return '#' + raw;
+    }
+    return null;
+}
+function hexToRgb(hex) {
+    const norm = resolveBrandColor(hex);
+    if (!norm)
+        return null;
+    const n = norm.slice(1);
+    return [parseInt(n.slice(0, 2), 16), parseInt(n.slice(2, 4), 16), parseInt(n.slice(4, 6), 16)];
+}
+/** WCAG relative luminance of an sRGB color. */
+function relativeLuminance(hex) {
+    const rgb = hexToRgb(hex);
+    if (!rgb)
+        return 0;
+    const [r, g, b] = rgb.map((v) => {
+        const s = v / 255;
+        return s <= 0.03928 ? s / 12.92 : Math.pow((s + 0.055) / 1.055, 2.4);
+    });
+    return 0.2126 * r + 0.7152 * g + 0.0722 * b;
+}
+/** WCAG contrast ratio between two colors (1..21). */
+function contrastRatio(a, b) {
+    const la = relativeLuminance(a);
+    const lb = relativeLuminance(b);
+    const lighter = Math.max(la, lb);
+    const darker = Math.min(la, lb);
+    return (lighter + 0.05) / (darker + 0.05);
+}
+/**
+ * True when `color` is readable as a UI accent against `background`. Uses the
+ * WCAG 3:1 threshold for graphical/large UI objects (the accent is used on
+ * filled buttons and tab underlines, not as body text). Guards R2.3 so an
+ * unreadable brand color never ships; callers fall back to the FRAIM accent.
+ */
+function hasSufficientContrast(color, background, min = 3.0) {
+    if (!resolveBrandColor(color) || !resolveBrandColor(background))
+        return false;
+    return contrastRatio(color, background) >= min;
+}
+// ── SVG sanitization (allowlist) ──────────────────────────────────────────────
+/** Only these elements survive sanitization. */
+const ALLOWED_SVG_TAGS = new Set([
+    'svg', 'g', 'path', 'rect', 'circle', 'ellipse', 'line', 'polyline', 'polygon',
+    'text', 'tspan', 'defs', 'lineargradient', 'radialgradient', 'stop', 'title', 'desc',
+]);
+/** Only these attributes survive; everything else (incl. on*, href, style) is dropped. */
+const ALLOWED_SVG_ATTRS = new Set([
+    'viewbox', 'xmlns', 'width', 'height', 'fill', 'fill-rule', 'fill-opacity', 'stroke',
+    'stroke-width', 'stroke-linecap', 'stroke-linejoin', 'stroke-dasharray', 'stroke-opacity',
+    'opacity', 'd', 'points', 'x', 'y', 'x1', 'y1', 'x2', 'y2', 'cx', 'cy', 'r', 'rx', 'ry',
+    'transform', 'offset', 'stop-color', 'stop-opacity', 'gradientunits', 'gradienttransform',
+    'font-family', 'font-size', 'font-weight', 'text-anchor', 'letter-spacing',
+]);
+/**
+ * Sanitize an SVG string via a strict allowlist. Returns safe SVG markup, or ''
+ * if the input is not an <svg> document. Removes: <script>, <foreignObject>,
+ * <image>, <use>, <a>, comments/PIs/DOCTYPE, all event handlers, all href /
+ * xlink:href, inline styles, and any element or attribute not on the allowlist.
+ */
+function sanitizeSvg(input) {
+    if (typeof input !== 'string')
+        return '';
+    // Bound the work up front so a pathological logo can't drive the tag-walk
+    // regex into catastrophic backtracking (DoS guard).
+    if (input.length > exports.MAX_LOGO_BYTES)
+        return '';
+    let s = input.trim();
+    if (!/^<svg[\s>]/i.test(s))
+        return '';
+    // Drop comments, CDATA, processing instructions, and DOCTYPE outright.
+    s = s.replace(/<!--[\s\S]*?-->/g, '');
+    s = s.replace(/<!\[CDATA\[[\s\S]*?\]\]>/g, '');
+    s = s.replace(/<\?[\s\S]*?\?>/g, '');
+    s = s.replace(/<!DOCTYPE[\s\S]*?>/gi, '');
+    // Drop dangerous elements and their entire content.
+    s = s.replace(/<(script|style|foreignObject|iframe|use|image|a)\b[\s\S]*?<\/\1\s*>/gi, '');
+    // Drop self-closing / unclosed variants of the same dangerous elements.
+    s = s.replace(/<(script|style|foreignObject|iframe|use|image|a)\b[^>]*\/?>/gi, '');
+    // Walk every remaining tag; drop non-allowlisted elements and attributes.
+    s = s.replace(/<\/?([a-zA-Z][\w:-]*)((?:[^>"']|"[^"]*"|'[^']*')*)>/g, (full, rawName, rawAttrs) => {
+        const name = rawName.toLowerCase().replace(/^svg:/, '');
+        if (!ALLOWED_SVG_TAGS.has(name))
+            return '';
+        const isClose = /^<\//.test(full);
+        if (isClose)
+            return `</${name}>`;
+        const selfClose = /\/>$/.test(full);
+        const attrs = [];
+        const attrRe = /([a-zA-Z_:][\w:.-]*)\s*=\s*("([^"]*)"|'([^']*)')/g;
+        let m;
+        while ((m = attrRe.exec(rawAttrs)) !== null) {
+            const attr = m[1].toLowerCase().replace(/^xml:/, '');
+            const value = m[3] !== undefined ? m[3] : m[4] || '';
+            if (!ALLOWED_SVG_ATTRS.has(attr))
+                continue;
+            // Defense in depth: never allow url()/javascript:/data: sneaking through a value.
+            if (/javascript:|url\s*\(|data:|expression\s*\(|<|>/i.test(value))
+                continue;
+            attrs.push(`${attr}="${value.replace(/"/g, '&quot;')}"`);
+        }
+        const attrStr = attrs.length ? ' ' + attrs.join(' ') : '';
+        return `<${name}${attrStr}${selfClose ? '/' : ''}>`;
+    });
+    // If sanitization emptied the root, treat as invalid.
+    if (!/^<svg[\s>]/i.test(s.trim()))
+        return '';
+    return s.trim();
+}
+/** Accept only png/jpeg data URIs (sanitized SVG is handled separately). */
+function isSafeRasterDataUri(s) {
+    return /^data:image\/(png|jpe?g);base64,[a-z0-9+/=\s]+$/i.test(s);
+}
+/** Sanitize a logo value: SVG markup -> sanitized SVG; png/jpeg data URI -> kept; else ''. */
+function sanitizeLogo(input) {
+    if (typeof input !== 'string' || !input.trim())
+        return '';
+    const s = input.trim();
+    if (/^<svg[\s>]/i.test(s)) {
+        const clean = sanitizeSvg(s);
+        return clean.length <= exports.MAX_LOGO_BYTES ? clean : '';
+    }
+    if (isSafeRasterDataUri(s)) {
+        return s.length <= exports.MAX_LOGO_BYTES ? s : '';
+    }
+    return '';
+}
+// ── Serialize / parse ─────────────────────────────────────────────────────────
+/** Normalize + sanitize a brand into its safe stored form. */
+function normalizeBrand(brand) {
+    const out = {};
+    if (typeof brand.name === 'string' && brand.name.trim()) {
+        out.name = brand.name.trim().slice(0, 120);
+    }
+    const color = resolveBrandColor(brand.color);
+    if (color)
+        out.color = color;
+    const logo = sanitizeLogo(brand.logo);
+    if (logo)
+        out.logo = logo;
+    return out;
+}
+function serializeBrand(brand) {
+    return JSON.stringify(normalizeBrand(brand), null, 2);
+}
+/** Parse a brand JSON string into a normalized OrgBrand, or null on any error. */
+function parseBrand(json) {
+    if (typeof json !== 'string' || !json.trim())
+        return null;
+    let obj;
+    try {
+        obj = JSON.parse(json);
+    }
+    catch {
+        return null;
+    }
+    if (!obj || typeof obj !== 'object')
+        return null;
+    const norm = normalizeBrand(obj);
+    return Object.keys(norm).length ? norm : null;
+}
+// ── Directory read / write ─────────────────────────────────────────────────────
+/** Read + normalize the brand from `<dir>/org_brand.json`, or null when absent/invalid. */
+function readBrandFromDir(dir) {
+    try {
+        const file = path_1.default.join(dir, exports.ORG_BRAND_FILENAME);
+        if (!fs_1.default.existsSync(file))
+            return null;
+        return parseBrand(fs_1.default.readFileSync(file, 'utf8'));
+    }
+    catch {
+        return null;
+    }
+}
+/** Sanitize + normalize a brand and write it to `<dir>/org_brand.json`. Returns the stored brand. */
+function writeBrandToDir(dir, brand) {
+    const normalized = normalizeBrand(brand);
+    fs_1.default.mkdirSync(dir, { recursive: true });
+    fs_1.default.writeFileSync(path_1.default.join(dir, exports.ORG_BRAND_FILENAME), JSON.stringify(normalized, null, 2), 'utf8');
+    return normalized;
+}

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

@@ -0,0 +1,331 @@
+"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_GATE_JOBS = exports.QUALITY_SCORE_JOBS = exports.QUALITY_PRODUCING_JOBS = exports.QUALITY_REGISTRY = void 0;
+exports.getRequiredFieldsForJob = getRequiredFieldsForJob;
+exports.validateQualityEvidence = validateQualityEvidence;
+exports.buildQualityRejectionMessage = buildQualityRejectionMessage;
+exports.QUALITY_REGISTRY = {
+    // Customer Development
+    // 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
+    'review-business-strategy': { stage: 'business-strategy', enforced: true, telemetryKind: 'score' },
+    'business-plan-creation': { stage: 'business-strategy', enforced: false },
+    'branding-quality-audit': { stage: 'branding', enforced: true, telemetryKind: 'score' },
+    // Product Quality
+    'code-quality-assessment': { stage: 'product-quality', enforced: true, telemetryKind: 'score' },
+    // Test Quality
+    '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
+    'marketing-strategy-definition': { stage: 'go-to-market', enforced: false },
+};
+/**
+ * @deprecated Use QUALITY_REGISTRY for new code.
+ * Derived enforcement list for backward compatibility.
+ */
+exports.QUALITY_PRODUCING_JOBS = Object.keys(exports.QUALITY_REGISTRY).filter((job) => exports.QUALITY_REGISTRY[job].enforced);
+/**
+ * Jobs that write scored review rows used by the Quality tab scorecards.
+ * Gate-only telemetry jobs (for example `triage-customer-needs`) are excluded.
+ */
+exports.QUALITY_SCORE_JOBS = Object.keys(exports.QUALITY_REGISTRY).filter((job) => exports.QUALITY_REGISTRY[job].enforced && exports.QUALITY_REGISTRY[job].telemetryKind !== 'gate');
+/**
+ * Jobs that emit gate-style telemetry without a composite score.
+ */
+exports.QUALITY_GATE_JOBS = Object.keys(exports.QUALITY_REGISTRY).filter((job) => exports.QUALITY_REGISTRY[job].enforced && exports.QUALITY_REGISTRY[job].telemetryKind === 'gate');
+/**
+ * @deprecated Use QUALITY_REGISTRY for new code.
+ * Derived stage mappings for backward compatibility.
+ */
+exports.STAGE_CATEGORY_MAP = Object.keys(exports.QUALITY_REGISTRY).reduce((acc, job) => ({ ...acc, [job]: exports.QUALITY_REGISTRY[job].stage }), {});
+/**
+ * Human-readable stage names for dashboard display.
+ */
+exports.STAGE_DISPLAY_NAMES = {
+    'customer-development': 'Customer Development',
+    'business-strategy': 'Business Strategy',
+    'branding': 'Branding',
+    'product-quality': 'Product Quality',
+    'test-quality': 'Test Quality',
+    'security': 'Security',
+    'production-readiness': 'Production Readiness',
+    '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',
+    'branding',
+    'product-quality',
+    'test-quality',
+    'security',
+    'production-readiness',
+    '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' }
+];
+/**
+ * Gate-only customer development jobs emit a decision without a composite score.
+ */
+const GATE_REQUIRED_FIELDS = [
+    { path: 'gateDecision', type: 'string' }
+];
+/**
+ * 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' },
+];
+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.
+ * 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 (jobName === 'process-interview-notes') {
+        return CUSTOMER_DEV_REQUIRED_FIELDS;
+    }
+    return [
+        ...UNIVERSAL_REQUIRED_FIELDS,
+        ...requiredDimensionFields(jobName)
+    ];
+}
+/**
+ * @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})`);
+        }
+    }
+    // Strict schema enforcement: No nested wrappers (Issue 255)
+    if (effective && effective.dimensions) {
+        errors.push('evidence.quality.dimensions is forbidden. Use a flat schema where all scores are direct properties of the quality object.');
+    }
+    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 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',
+            'evidence: {',
+            '  artifactPath: "<project-relative quality artifact path>",',
+            '  quality: {',
+            '    gateDecision: "<pass|flag|fail>",',
+            '    interviewsAnalyzed: <number>,',
+            '    distinctPainPatterns: <number>,',
+            '    gaps: ["<gap summary>"],',
+            '    coaching: "<actionable recommendation>"',
+            '  }',
+            '}',
+            '```'
+        ]
+        : isCustomerDev
+            ? [
+                '```javascript',
+                'evidence: {',
+                '  artifactPath: "<project-relative quality artifact path>",',
+                '  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: {',
+                '  artifactPath: "<project-relative quality artifact path>",',
+                '  quality: {',
+                '    composite: <number 0-10>,',
+                '    coaching: "<actionable recommendation>",',
+                dimensionExamples,
+                '  }',
+                '}',
+                '```'
+            ];
+    const importantNote = [
+        '',
+        '> [!IMPORTANT]',
+        '> **Enforcement Notice**: Quality scores MUST follow a flat schema. Do NOT nest sub-dimension scores under a `dimensions` property. All sub-dimension objects must be direct properties of the `quality` object.',
+        ''
+    ];
+    return [
+        `❌ **Job completion rejected** for \`${jobName}\`.`,
+        '',
+        `This job is required to emit quality evidence on its final \`seekMentoring\` call so the result is captured in \`fraim_quality_scores\` for the quality dashboard. The following problems were found:`,
+        '',
+        errorBullets,
+        ...importantNote,
+        `Required minimum schema for \`${entry?.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');
+}