prism-mcp-server 7.3.3 → 7.5.0

package/dist/darkfactory/clawInvocation.js

@@ -30,6 +30,37 @@ RULES:
 - Do NOT use markdown code fences
 - If you cannot complete the task, return: {"actions": [], "notes": "reason"}
 `.trim();
+const PLAN_CONTRACT_SCHEMA = `
+You MUST respond with ONLY a valid JSON object matching this schema:
+{
+  "criteria": [
+    {
+      "id": "string (unique identifier, e.g. 'req-1')",
+      "description": "string (clear, testable condition)"
+    }
+  ]
+}
+`.trim();
+const EVALUATE_SCHEMA = `
+You MUST respond with ONLY a valid JSON object matching this schema:
+{
+  "pass": true | false,
+  "plan_viable": true | false,
+  "notes": "string (optional summary)",
+  "findings": [
+    {
+      "severity": "critical" | "warning" | "info",
+      "criterion_id": "string (must match a contract criterion id)",
+      "pass_fail": true | false,
+      "evidence": {
+        "file": "string",
+        "line": 42,
+        "description": "string"
+      }
+    }
+  ]
+}
+`.trim();
 /**
  * Invocation wrapper that routes payload specs to the local Claw agent model (Qwen 2.5),
  * or the active LLM provider as fallback.
@@ -49,16 +80,40 @@ export async function invokeClawAgent(spec, state, timeoutMs = 120000 // 2 min d
         : getLLMProvider();
     // Scope injection via SafetyController — single source of truth
     const systemPrompt = SafetyController.generateBoundaryPrompt(spec, state);
-    // v7.3.1: EXECUTE steps get structured JSON output instructions
-    const isExecuteStep = state.current_step === 'EXECUTE';
-    const executePrompt = isExecuteStep
-        ? `Based on the system instructions, execute the necessary actions for the current step (${state.current_step}).\n\n${EXECUTE_JSON_SCHEMA}`
-        : `Based on the system instructions, execute the necessary task for the current step (${state.current_step}). Respond with your actions and observations.`;
-    debugLog(`[ClawInvocation] Launching agent on pipeline ${state.id} step=${state.current_step} iter=${state.iteration} with ${timeoutMs}ms limit.${isExecuteStep ? ' (JSON mode)' : ''}`);
+    // Inject the appropriate JSON schema according to the step
+    let stepPrompt = `Based on the system instructions, execute the necessary task for the current step (${state.current_step}). Respond with your actions and observations.`;
+    let isJsonMode = false;
+    if (state.current_step === 'EXECUTE') {
+        let revisionContext = '';
+        // If we are retrying after an EVALUATE failure, state.notes holds the serialized evaluator critique.
+        // Inject it so the Generator knows exactly what to fix rather than retrying blindly.
+        if (state.eval_revisions && state.eval_revisions > 0) {
+            revisionContext = `\n\n=== EVALUATOR CRITIQUE (revision ${state.eval_revisions}) ===\n${state.notes || 'Fix previous errors.'}\n\nYou MUST correct all issues listed above before submitting.`;
+        }
+        stepPrompt = `Based on the system instructions, execute the necessary actions for the current step (${state.current_step}).${revisionContext}\n\n${EXECUTE_JSON_SCHEMA}`;
+        isJsonMode = true;
+    }
+    else if (state.current_step === 'PLAN_CONTRACT') {
+        stepPrompt = `Based on the system instructions from the PLAN phase, formulate a strict, boolean-testable contract rubric.\n\n${PLAN_CONTRACT_SCHEMA}`;
+        isJsonMode = true;
+    }
+    else if (state.current_step === 'EVALUATE') {
+        stepPrompt = `Based on the system instructions, evaluate the GENERATOR's execution against the PLAN_CONTRACT rubric. BE STRICT.
+    
+=== GENERATOR'S ACTIONS ===
+${state.notes || 'No notes provided'}
+
+=== CONTRACT RUBRIC ===
+${state.contract_payload ? JSON.stringify(state.contract_payload.criteria, null, 2) : '(See contract_rubric.json on disk)'}
+
+${EVALUATE_SCHEMA}`;
+        isJsonMode = true;
+    }
+    debugLog(`[ClawInvocation] Launching agent on pipeline ${state.id} step=${state.current_step} iter=${state.iteration} with ${timeoutMs}ms limit.${isJsonMode ? ' (JSON mode)' : ''}`);
     try {
         // Timeout Promise to ensure the runner thread does not block indefinitely
         const timeboundExecution = Promise.race([
-            llm.generateText(executePrompt, systemPrompt),
+            llm.generateText(stepPrompt, systemPrompt),
             new Promise((_, reject) => setTimeout(() => reject(new Error('LLM_EXECUTION_TIMEOUT')), timeoutMs))
         ]);
         const result = await timeboundExecution;

package/dist/darkfactory/runner.js

@@ -191,25 +191,21 @@ async function emitExperienceEvent(pipeline, eventType, outcome) {
  *
  * @internal Exported for unit testing only. Not part of the public API.
  */
-export function parseExecuteOutput(raw) {
+function extractJsonFromLlmOutput(raw) {
     if (!raw || typeof raw !== 'string' || raw.trim() === '') {
-        return { parsed: null, error: 'JSON Parse Error: empty or non-string input' };
+        return { json: null, error: 'JSON Parse Error: empty or non-string input' };
     }
     const cleaned = raw.trim();
     let jsonCandidate = null;
-    // Strategy 1: Try raw trimmed input as-is
     if (cleaned.startsWith('{')) {
         jsonCandidate = cleaned;
     }
-    // Strategy 2: Strip markdown code fences
     if (!jsonCandidate) {
-        // Match ```json or ``` blocks anywhere in the text (not just start/end of string)
         const fenceMatch = cleaned.match(/```(?:json)?\s*\n?([\s\S]*?)\n?\s*```/);
         if (fenceMatch) {
             jsonCandidate = fenceMatch[1].trim();
         }
     }
-    // Strategy 3: Brace extraction — find first { to last }
     if (!jsonCandidate) {
         const firstBrace = cleaned.indexOf('{');
         const lastBrace = cleaned.lastIndexOf('}');
@@ -218,17 +214,21 @@ export function parseExecuteOutput(raw) {
         }
     }
     if (!jsonCandidate) {
-        return { parsed: null, error: 'JSON Parse Error: no JSON object found in LLM output' };
+        return { json: null, error: 'JSON Parse Error: no JSON object found in LLM output' };
     }
-    // Attempt JSON parse
+    return { json: jsonCandidate, error: null };
+}
+export function parseExecuteOutput(raw) {
+    const ext = extractJsonFromLlmOutput(raw);
+    if (ext.error || !ext.json)
+        return { parsed: null, error: ext.error };
     let parsed;
     try {
-        parsed = JSON.parse(jsonCandidate);
+        parsed = JSON.parse(ext.json);
     }
     catch {
         return { parsed: null, error: 'JSON Parse Error: LLM output is not valid JSON' };
     }
-    // Shape validation: must be an object with an 'actions' array
     if (!parsed || typeof parsed !== 'object' || Array.isArray(parsed)) {
         return { parsed: null, error: 'Shape Error: output is not a JSON object' };
     }
@@ -236,7 +236,6 @@ export function parseExecuteOutput(raw) {
         return { parsed: null, error: 'Shape Error: output missing required "actions" array' };
     }
     const result = parsed;
-    // Validate each action in the array
     for (let i = 0; i < result.actions.length; i++) {
         const action = result.actions[i];
         if (!action || typeof action !== 'object' || Array.isArray(action)) {
@@ -251,6 +250,62 @@ export function parseExecuteOutput(raw) {
     }
     return { parsed: result, error: null };
 }
+export function parseContractOutput(raw) {
+    const ext = extractJsonFromLlmOutput(raw);
+    if (ext.error || !ext.json)
+        return { parsed: null, error: ext.error };
+    let parsed;
+    try {
+        parsed = JSON.parse(ext.json);
+    }
+    catch {
+        return { parsed: null, error: 'JSON Parse Error: LLM output is not valid JSON' };
+    }
+    if (!parsed || typeof parsed !== 'object' || !Array.isArray(parsed.criteria)) {
+        return { parsed: null, error: 'Shape Error: output missing required "criteria" array' };
+    }
+    // Validate each criterion element has the required string fields
+    for (let i = 0; i < parsed.criteria.length; i++) {
+        const c = parsed.criteria[i];
+        if (!c || typeof c !== 'object' || typeof c.id !== 'string' || typeof c.description !== 'string') {
+            return { parsed: null, error: `Shape Error: criteria[${i}] must have string "id" and "description"` };
+        }
+    }
+    return { parsed: parsed, error: null };
+}
+export function parseEvaluationOutput(raw) {
+    const ext = extractJsonFromLlmOutput(raw);
+    if (ext.error || !ext.json)
+        return { parsed: null, error: ext.error };
+    let parsed;
+    try {
+        parsed = JSON.parse(ext.json);
+    }
+    catch {
+        return { parsed: null, error: 'JSON Parse Error: LLM output is not valid JSON' };
+    }
+    if (!parsed || typeof parsed !== 'object' || typeof parsed.pass !== 'boolean') {
+        return { parsed: null, error: 'Shape Error: output missing required "pass" boolean' };
+    }
+    const p = parsed;
+    if (p.findings !== undefined) {
+        if (!Array.isArray(p.findings)) {
+            return { parsed: null, error: 'Shape Error: "findings" must be an array when present' };
+        }
+        // Fix #3: Each failing finding must supply an evidence object so the
+        // Evaluator cannot submit bare severity claims without evidence pointers.
+        for (let i = 0; i < p.findings.length; i++) {
+            const f = p.findings[i];
+            if (!f || typeof f !== 'object') {
+                return { parsed: null, error: `Shape Error: findings[${i}] must be an object` };
+            }
+            if (f.pass_fail === false && (!f.evidence || typeof f.evidence !== 'object')) {
+                return { parsed: null, error: `Shape Error: findings[${i}] is missing required "evidence" object for failure` };
+            }
+        }
+    }
+    return { parsed: parsed, error: null };
+}
 // ─── Step Execution ────────────────────────────────────────────
 /**
  * Execute a single step of the pipeline.
@@ -273,8 +328,8 @@ async function executeStep(pipeline, spec) {
         // - BYOM model override
         // - Timeout enforcement
         const { success, resultText } = await invokeClawAgent(spec, pipeline);
-        // For non-EXECUTE steps, return as-is (free-form text)
-        if (step !== 'EXECUTE') {
+        // For non-JSON steps, return as-is (free-form text)
+        if (step !== 'EXECUTE' && step !== 'PLAN_CONTRACT' && step !== 'EVALUATE') {
             return {
                 iteration: pipeline.iteration,
                 step,
@@ -284,7 +339,6 @@ async function executeStep(pipeline, spec) {
                 notes: resultText.slice(0, 2000),
             };
         }
-        // ── v7.3.1: EXECUTE step — parse and validate structured output ──
         if (!success) {
             // LLM invocation itself failed (timeout, error, etc.)
             return {
@@ -296,7 +350,59 @@ async function executeStep(pipeline, spec) {
                 notes: `LLM invocation failed: ${resultText.slice(0, 500)}`,
             };
         }
-        // Parse the structured JSON output
+        // Parse appropriate JSON output depending on step
+        if (step === 'PLAN_CONTRACT') {
+            const { parsed, error: parseError } = parseContractOutput(resultText);
+            if (parseError || !parsed) {
+                debugLog(`[DarkFactory] PLAN_CONTRACT output parse failure: ${parseError}`);
+                return {
+                    iteration: pipeline.iteration,
+                    step,
+                    started_at: stepStart,
+                    completed_at: new Date().toISOString(),
+                    success: false,
+                    notes: parseError || 'Unknown parse error',
+                };
+            }
+            return {
+                iteration: pipeline.iteration,
+                step,
+                started_at: stepStart,
+                completed_at: new Date().toISOString(),
+                success: true,
+                notes: `Contract accepted with ${parsed.criteria.length} criteria.`,
+                contractPayload: parsed, // Passthrough for runner to write to disk
+            };
+        }
+        if (step === 'EVALUATE') {
+            const { parsed, error: parseError } = parseEvaluationOutput(resultText);
+            if (parseError || !parsed) {
+                debugLog(`[DarkFactory] EVALUATE output parse failure: ${parseError}`);
+                return {
+                    iteration: pipeline.iteration,
+                    step,
+                    started_at: stepStart,
+                    completed_at: new Date().toISOString(),
+                    success: false,
+                    notes: parseError || 'Unknown parse error',
+                };
+            }
+            // Fix #2: Serialize findings array into notes so the Generator's retry
+            // prompt receives the full line-by-line critique, not just a summary string.
+            const findingsText = parsed.findings && parsed.findings.length > 0
+                ? '\nFindings:\n' + parsed.findings.map((f) => `- [${f.severity}] Criterion ${f.criterion_id}: ${f.evidence?.description || 'Failed'} (${f.evidence?.file || 'unknown'}:${f.evidence?.line ?? '?'})`).join('\n')
+                : '';
+            return {
+                iteration: pipeline.iteration,
+                step,
+                started_at: stepStart,
+                completed_at: new Date().toISOString(),
+                success: parsed.pass,
+                notes: (parsed.notes || `Evaluation complete: ${parsed.pass ? 'PASS' : 'FAIL'}`) + findingsText,
+                evaluationPayload: parsed, // Passthrough for orchestrator logic
+            };
+        }
+        // EXECUTE
         const { parsed, error: parseError } = parseExecuteOutput(resultText);
         if (parseError || !parsed) {
             debugLog(`[DarkFactory] EXECUTE output parse failure: ${parseError}`);
@@ -582,10 +688,57 @@ async function runnerTick() {
                 }
             }
         }
-        // Determine next step based on result
-        const nextStep = SafetyController.getNextStep(currentStep, pipeline.iteration, spec, result.success // For VERIFY step: success means tests passed
-        );
-        if (nextStep === null || currentStep === 'FINALIZE') {
+        if (currentStep === 'PLAN_CONTRACT' && spec.workingDirectory && result.success && result.contractPayload) {
+            const contractPath = path.join(path.resolve(spec.workingDirectory), 'contract_rubric.json');
+            try {
+                fs.writeFileSync(contractPath, JSON.stringify(result.contractPayload, null, 2), 'utf8');
+                debugLog(`[DarkFactory] contract_rubric.json written to ${contractPath}`);
+            }
+            catch (writeErr) {
+                // Disk/permissions error — fail the pipeline immediately so it doesn't
+                // loop on PLAN_CONTRACT forever (each tick would re-attempt the write).
+                debugLog(`[DarkFactory] Failed to write contract_rubric.json: ${writeErr.message}`);
+                try {
+                    await storage.savePipeline({
+                        ...pipeline,
+                        status: 'FAILED',
+                        error: `PLAN_CONTRACT failed: could not write contract_rubric.json — ${writeErr.message}`,
+                    });
+                }
+                catch { /* status guard */ }
+                await emitExperienceEvent(pipeline, 'failure', `contract_rubric.json write failed: ${writeErr.message}`);
+                return;
+            }
+        }
+        if (currentStep === 'EVALUATE' && result.evaluationPayload) {
+            // Emit ML learning event for evaluation outcome.
+            // Using 'learning' (valid LedgerEntry event type) rather than
+            // a non-existent 'evaluation_result' to avoid runtime cast issues.
+            try {
+                await storage.saveLedger({
+                    project: pipeline.project,
+                    conversation_id: `dark-factory-${pipeline.id}`,
+                    user_id: pipeline.user_id,
+                    event_type: 'learning',
+                    summary: `[EVALUATE] ${result.success ? 'PASS' : 'FAIL'} on iter ${pipeline.iteration} rev ${pipeline.eval_revisions ?? 0}`,
+                    keywords: ['dark-factory', 'evaluation', pipeline.project],
+                    importance: result.success ? 3 : 1,
+                    confidence_score: result.success ? 90 : 50,
+                });
+            }
+            catch { /* advisory — never block execution */ }
+        }
+        // ─── Determine plan_viable from evaluation payload ───
+        // Default to false (conservative): a parse failure or missing payload means
+        // we don't know if the plan is viable, so escalate to PLAN re-planning
+        // rather than burning eval_revisions on more EXECUTE retries.
+        let evalPlanViable = false;
+        if (currentStep === 'EVALUATE' && result.evaluationPayload) {
+            // plan_viable defaults false if null/missing (same conservative principle)
+            evalPlanViable = result.evaluationPayload.plan_viable ?? false;
+        }
+        const nextStepInfo = SafetyController.getNextStep(pipeline, spec, result.success, evalPlanViable);
+        if (nextStepInfo === null || currentStep === 'FINALIZE') {
             // Pipeline complete — determine final status
             const finalStatus = result.success ? 'COMPLETED' : 'FAILED';
             const finalError = result.success ? null : `Pipeline ended at step=${currentStep}: ${result.notes?.slice(0, 500)}`;
@@ -613,13 +766,25 @@ async function runnerTick() {
             debugLog(`[DarkFactory] Pipeline ${pipeline.id} finished: ${finalStatus}`);
         }
         else {
-            // Advance to next step
             try {
+                const updatedPayload = currentStep === 'PLAN_CONTRACT' && result.contractPayload
+                    ? result.contractPayload
+                    : pipeline.contract_payload;
+                // Forward the most informative notes available:
+                // EXECUTE notes = what the generator did
+                // EVALUATE notes = what the evaluator found
+                // Other steps: preserve existing notes
+                const updatedNotes = (currentStep === 'EXECUTE' || currentStep === 'EVALUATE') && result.notes
+                    ? result.notes
+                    : pipeline.notes;
                 await storage.savePipeline({
                     ...pipeline,
-                    current_step: nextStep.step,
-                    iteration: nextStep.iteration,
+                    current_step: nextStepInfo.step,
+                    iteration: nextStepInfo.iteration,
+                    eval_revisions: nextStepInfo.eval_revisions,
                     last_heartbeat: new Date().toISOString(),
+                    contract_payload: updatedPayload,
+                    notes: updatedNotes,
                 });
             }
             catch (err) {
@@ -630,7 +795,7 @@ async function runnerTick() {
                 }
                 throw err;
             }
-            debugLog(`[DarkFactory] Pipeline ${pipeline.id} advanced: ${currentStep} → ${nextStep.step} (iter ${nextStep.iteration})`);
+            debugLog(`[DarkFactory] Pipeline ${pipeline.id} advanced: ${currentStep} → ${nextStepInfo.step} (iter ${nextStepInfo.iteration}, rev ${nextStepInfo.eval_revisions ?? 0})`);
         }
     }
     catch (err) {

package/dist/darkfactory/safetyController.js

@@ -1,4 +1,4 @@
-import { VALID_ACTION_TYPES } from './schema.js';
+import { VALID_ACTION_TYPES, DEFAULT_MAX_REVISIONS } from './schema.js';
 import { PRISM_DARK_FACTORY_MAX_RUNTIME_MS } from '../config.js';
 import { debugLog } from '../utils/logger.js';
 import path from 'path';
@@ -31,13 +31,6 @@ export class SafetyController {
         'COMPLETED': [], // Terminal — no exits
         'FAILED': ['RUNNING'], // Allow retry from failed state
     };
-    /**
-     * Legal step transitions for the pipeline execution state machine.
-     * FINALIZE is entered from VERIFY when iteration == maxIterations or success.
-     */
-    static STEP_ORDER = [
-        'INIT', 'PLAN', 'EXECUTE', 'VERIFY', 'FINALIZE'
-    ];
     /**
      * Prevents runaway LLM invocation loops by enforcing the max iteration envelope.
      */
@@ -147,8 +140,15 @@ export class SafetyController {
      * Used by clawInvocation.ts instead of inline prompt construction.
      */
     static generateBoundaryPrompt(spec, state) {
+        let modeDescription = 'an autonomous code agent';
+        if (state.current_step === 'PLAN_CONTRACT' || state.current_step === 'EVALUATE') {
+            modeDescription = 'an ADVERSARIAL EVALUATOR enforcing strict quality constraints against a generated output';
+        }
+        else if (state.current_step === 'EXECUTE') {
+            modeDescription = 'a GENERATOR executing code constrained by a strict rubric';
+        }
         const lines = [
-            `You are Prism Dark Factory, operating in the background as an autonomous code agent.`,
+            `You are Prism Dark Factory, operating in the background as ${modeDescription}.`,
             `You are strictly limited to code actions within the defined scope.`,
             ``,
             `── Operational Boundaries ──`,
@@ -156,6 +156,7 @@ export class SafetyController {
             `Project: ${state.project}`,
             `Current Step: ${state.current_step}`,
             `Iteration: ${state.iteration} / ${spec.maxIterations}`,
+            `Revision: ${state.eval_revisions ?? 0} / ${spec.maxRevisions ?? DEFAULT_MAX_REVISIONS}`,
             `Restricted Workspace: ${spec.workingDirectory || '(unrestricted)'}`,
         ];
         if (spec.contextFiles && spec.contextFiles.length > 0) {
@@ -164,29 +165,54 @@ export class SafetyController {
         lines.push(``, `── Objective ──`, spec.objective, ``, `── Safety Rules ──`, `1. Do NOT modify files outside the Restricted Workspace.`, `2. Do NOT make network requests unless the objective explicitly requires it.`, `3. Do NOT execute destructive operations (rm -rf, DROP TABLE, etc.).`, `4. Respond ONLY with actions relevant to the current step.`, `5. If you cannot complete the step, explain why and stop.`);
         return lines.join('\n');
     }
-    /**
-     * Determine the next step in the pipeline execution sequence.
-     * Returns null if the pipeline should terminate (FINALIZE reached or iteration exceeded).
-     */
-    static getNextStep(currentStep, iteration, spec, verifyPassed) {
+    static getNextStep(state, spec, stepPassed, planViable = true) {
+        const currentStep = state.current_step;
+        const iteration = state.iteration;
+        const eval_revisions = state.eval_revisions ?? 0;
         switch (currentStep) {
             case 'INIT':
-                return { step: 'PLAN', iteration };
+                return { step: 'PLAN', iteration, eval_revisions };
             case 'PLAN':
-                return { step: 'EXECUTE', iteration };
+                return { step: 'PLAN_CONTRACT', iteration, eval_revisions };
+            case 'PLAN_CONTRACT':
+                return { step: 'EXECUTE', iteration, eval_revisions };
             case 'EXECUTE':
-                return { step: 'VERIFY', iteration };
+                return { step: 'EVALUATE', iteration, eval_revisions };
+            case 'EVALUATE':
+                if (stepPassed) {
+                    // Contract passed, move to VERIFY
+                    return { step: 'VERIFY', iteration, eval_revisions: 0 };
+                }
+                // Contract failed.
+                if (planViable) {
+                    // Fall back to EXECUTE but increment revision counter
+                    const nextRevision = eval_revisions + 1;
+                    const maxRev = spec.maxRevisions ?? DEFAULT_MAX_REVISIONS;
+                    if (nextRevision >= maxRev) {
+                        // Exceeded max revisions — pipeline fails
+                        return null;
+                    }
+                    return { step: 'EXECUTE', iteration, eval_revisions: nextRevision };
+                }
+                else {
+                    // Fall back all the way to PLAN
+                    const nextIteration = iteration + 1;
+                    if (!SafetyController.validateIterationLimit(nextIteration, spec)) {
+                        return null;
+                    }
+                    return { step: 'PLAN', iteration: nextIteration, eval_revisions: 0 };
+                }
             case 'VERIFY':
-                if (verifyPassed) {
-                    return { step: 'FINALIZE', iteration };
+                if (stepPassed) {
+                    return { step: 'FINALIZE', iteration, eval_revisions };
                 }
                 // Verification failed — loop back to PLAN with incremented iteration
-                const nextIteration = iteration + 1;
-                if (!SafetyController.validateIterationLimit(nextIteration, spec)) {
+                const nextIterationVerify = iteration + 1;
+                if (!SafetyController.validateIterationLimit(nextIterationVerify, spec)) {
                     // Exceeded max iterations — force finalize with failure
                     return null;
                 }
-                return { step: 'PLAN', iteration: nextIteration };
+                return { step: 'PLAN', iteration: nextIterationVerify, eval_revisions: 0 };
             case 'FINALIZE':
                 return null; // Terminal step
             default:

package/dist/darkfactory/schema.js

@@ -2,3 +2,5 @@
 export const VALID_ACTION_TYPES = [
     'READ_FILE', 'WRITE_FILE', 'PATCH_FILE', 'RUN_TEST'
 ];
+/** Default max adversarial revisions per EXECUTE phase (used when spec.maxRevisions is unset). */
+export const DEFAULT_MAX_REVISIONS = 3;

package/dist/dashboard/intentHealth.js

@@ -0,0 +1,62 @@
+export function computeIntentHealth(ctx, staleThresholdDays = 30, nowMs = Date.now()) {
+    if (!Number.isFinite(staleThresholdDays) || staleThresholdDays <= 0)
+        staleThresholdDays = 30; // Guard against NaN / zero / negative
+    // 2. Compute staleness (Days since last session)
+    let stalenessDays = 0;
+    if (ctx.recent_sessions && ctx.recent_sessions.length > 0) {
+        const lastTimestamp = ctx.recent_sessions[0].created_at ? new Date(ctx.recent_sessions[0].created_at).getTime() : NaN;
+        stalenessDays = isNaN(lastTimestamp) ? 0 : Math.max(0, (nowMs - lastTimestamp) / (1000 * 60 * 60 * 24));
+    }
+    // 3. Count TODOs and Decisions
+    const todoCount = ctx.pending_todo?.length || 0;
+    const hasDecisions = ctx.recent_sessions?.some((s) => Array.isArray(s.decisions) && s.decisions.length > 0) ?? false;
+    // 4. Execute Intent Debt Scoring Algorithm
+    // Staleness (50 points): Linear decay until threshold
+    const stalenessScore = Math.max(0, 50 - (stalenessDays / staleThresholdDays) * 50);
+    // Open TODOs (30 points)
+    let todoScore = 30;
+    if (todoCount >= 10)
+        todoScore = 0;
+    else if (todoCount >= 7)
+        todoScore = 5;
+    else if (todoCount >= 4)
+        todoScore = 15;
+    else if (todoCount >= 1)
+        todoScore = 25;
+    // Decisions (20 points): 70% of max if missing
+    const decisionScore = hasDecisions ? 20 : 14;
+    const totalScore = Math.min(100, Math.round(stalenessScore + todoScore + decisionScore));
+    // 5. Generate Actionable Signals
+    const signals = [];
+    if (stalenessDays > staleThresholdDays) {
+        signals.push({ type: "staleness", message: `Stale: Last updated ${Math.round(stalenessDays)} days ago`, severity: "critical" });
+    }
+    else if (stalenessDays > staleThresholdDays / 2) {
+        signals.push({ type: "staleness", message: `Aging: Last updated ${Math.round(stalenessDays)} days ago`, severity: "warn" });
+    }
+    else {
+        signals.push({ type: "staleness", message: `Fresh: Last updated ${Math.round(stalenessDays)} days ago`, severity: "ok" });
+    }
+    if (todoCount >= 10) {
+        signals.push({ type: "todos", message: `${todoCount} TODOs pending (Overwhelming)`, severity: "critical" });
+    }
+    else if (todoCount >= 4) {
+        signals.push({ type: "todos", message: `${todoCount} TODOs pending`, severity: "warn" });
+    }
+    else {
+        signals.push({ type: "todos", message: `${todoCount} TODOs pending`, severity: "ok" });
+    }
+    if (hasDecisions) {
+        signals.push({ type: "decisions", message: "Active decisions captured", severity: "ok" });
+    }
+    else {
+        signals.push({ type: "decisions", message: "No active decisions documented", severity: "warn" });
+    }
+    return {
+        score: totalScore,
+        staleness_days: Math.round(stalenessDays),
+        open_todo_count: todoCount,
+        has_active_decisions: hasDecisions,
+        signals: signals
+    };
+}

package/dist/dashboard/server.js

@@ -23,7 +23,8 @@ import * as fs from "fs";
 import { getStorage } from "../storage/index.js";
 import { PRISM_USER_ID, SERVER_CONFIG } from "../config.js";
 import { renderDashboardHTML } from "./ui.js";
-import { getAllSettings, setSetting, getSetting } from "../storage/configStorage.js";
+import { computeIntentHealth } from "./intentHealth.js";
+import { getAllSettings, setSetting, getSetting, getSettingSync } from "../storage/configStorage.js";
 import { compactLedgerHandler } from "../tools/compactionHandler.js";
 import { getLLMProvider } from "../utils/llm/factory.js";
 import { buildVaultDirectory } from "../utils/vaultExporter.js";
@@ -1095,6 +1096,39 @@ self.addEventListener('message', (e) => {
                 });
                 return res.end(Buffer.from(pngBase64, "base64"));
             }
+            // ─── API: Intent Health (Feature A) ───
+            // GET /api/intent-health?project=xxx
+            if (url.pathname === "/api/intent-health" && req.method === "GET") {
+                const project = url.searchParams.get("project");
+                if (!project) {
+                    res.writeHead(400, { "Content-Type": "application/json" });
+                    return res.end(JSON.stringify({ error: "project is required" }));
+                }
+                try {
+                    const storage = await getStorageSafe();
+                    if (!storage) {
+                        res.writeHead(503, { "Content-Type": "application/json" });
+                        return res.end(JSON.stringify({ error: "Storage initializing..." }));
+                    }
+                    // Load 'standard' context to get active_decisions and recent_sessions
+                    // Note: API MUST use "standard" level (deep skips recent_sessions, which breaks staleness).
+                    const ctx = await storage.loadContext(project, "standard", PRISM_USER_ID);
+                    if (!ctx) {
+                        res.writeHead(404, { "Content-Type": "application/json" });
+                        return res.end(JSON.stringify({ error: "Project not found" }));
+                    }
+                    // 1. Fetch configurable threshold (default 30 days, avoiding 7-day panic)
+                    const staleThresholdDays = parseInt(getSettingSync("intent_health_stale_threshold_days", "30"), 10) || 30;
+                    const healthResult = computeIntentHealth(ctx, staleThresholdDays);
+                    res.writeHead(200, { "Content-Type": "application/json" });
+                    return res.end(JSON.stringify(healthResult));
+                }
+                catch (err) {
+                    console.error("[intent-health] Error computing intent health:", err);
+                    res.writeHead(500, { "Content-Type": "application/json" });
+                    return res.end(JSON.stringify({ error: "Failed to compute intent health" }));
+                }
+            }
             // ─── 404 ───
             res.writeHead(404, { "Content-Type": "text/plain" });
             res.end("Not found");