@hongmaple0820/scale-engine 0.48.0 → 0.50.1

package/dist/review/FreshContextVerifier.js

@@ -0,0 +1,120 @@
+// SCALE Engine — Fresh-context verifier sub-agent (P2.2)
+// An independent verification pass that judges whether a diff actually
+// satisfies the Spec, deliberately fed ONLY the declared verification surface,
+// the diff and a gate summary — and *no* build-agent conversation/history
+// (decision N1). The isolated input is what eliminates the build agent's
+// self-rationalisation bias.
+//
+// Like LlmJudge / ReflexionEngine it is env-gated (SCALE_LOCAL_MODEL) with a
+// deterministic heuristic fallback, and it is advisory only (decision O1): the
+// verdict is recorded but never blocks ship in this PR.
+import { logger } from '../core/logger.js';
+import { JsonLlmClient } from './JsonLlmClient.js';
+const SYSTEM_PROMPT = 'You are an independent verification sub-agent. You did NOT write this code and have NO access to the author\'s reasoning. ' +
+    'Using only the declared verification surface, the diff and the gate summary, decide whether the outcome is independently verifiable from the artifacts alone. ' +
+    'Do not assume intent that is not evidenced by the diff. Output strict JSON only.';
+export class FreshContextVerifier {
+    constructor(client = new JsonLlmClient()) {
+        this.client = client;
+    }
+    async verify(input) {
+        if (!this.client.isEnabled()) {
+            return this.heuristicVerdict(input);
+        }
+        try {
+            const { data, modelUsed } = await this.client.completeJson({
+                system: SYSTEM_PROMPT,
+                user: this.buildUserPrompt(input),
+            });
+            return {
+                decision: normalizeDecision(data.decision),
+                confidence: clampConfidence(data.confidence),
+                rationale: (data.rationale ?? '').slice(0, 1000) || 'No rationale provided.',
+                unmetSurfaces: Array.isArray(data.unmetSurfaces) ? data.unmetSurfaces.slice(0, 50) : [],
+                modelUsed,
+                advisory: true,
+                createdAt: Date.now(),
+            };
+        }
+        catch (err) {
+            logger.warn({ err }, 'FreshContextVerifier: LLM call failed, falling back to heuristic');
+            return this.heuristicVerdict(input);
+        }
+    }
+    buildUserPrompt(input) {
+        return [
+            `Stated outcome: ${input.outcome ?? '(not declared)'}`,
+            '',
+            'Verification surfaces (the ONLY contract you may verify against):',
+            ...(input.verificationSurface.length ? input.verificationSurface.map(s => `- ${s}`) : ['- (none declared)']),
+            '',
+            'Gate summary:',
+            input.gateSummary || '(none)',
+            '',
+            'Diff (the only evidence available to you):',
+            input.diffSummary.slice(0, 6000) || '(empty diff)',
+            '',
+            'Output JSON: { "decision": "verified|unverified|uncertain", "confidence": 0.0-1.0, "rationale": "...", "unmetSurfaces": ["..."] }',
+        ].join('\n');
+    }
+    /**
+     * Deterministic fallback. Unlike the build agent, the fresh verifier trusts
+     * only artifacts: a surface is verified iff its significant tokens appear in
+     * the diff. Any unmet surface yields "unverified"; no surface at all is
+     * "uncertain" (nothing to independently verify against).
+     */
+    heuristicVerdict(input) {
+        const haystack = input.diffSummary.toLowerCase();
+        const unmetSurfaces = input.verificationSurface.filter(surface => !surfaceMentioned(surface, haystack));
+        let decision;
+        let confidence;
+        let rationale;
+        if (input.verificationSurface.length === 0) {
+            decision = 'uncertain';
+            confidence = 0.3;
+            rationale = 'No verification surface declared; cannot independently verify the outcome from the diff.';
+        }
+        else if (unmetSurfaces.length > 0) {
+            decision = 'unverified';
+            confidence = 0.5;
+            rationale = `${unmetSurfaces.length}/${input.verificationSurface.length} verification surface(s) have no supporting evidence in the diff.`;
+        }
+        else {
+            decision = 'verified';
+            confidence = 0.5;
+            rationale = 'Every declared verification surface has supporting evidence in the diff.';
+        }
+        return {
+            decision,
+            confidence,
+            rationale,
+            unmetSurfaces,
+            modelUsed: 'heuristic',
+            advisory: true,
+            createdAt: Date.now(),
+        };
+    }
+}
+function surfaceMentioned(surface, haystackLower) {
+    const tokens = surface
+        .toLowerCase()
+        .split(/[^a-z0-9]+/i)
+        .filter(token => token.length >= 4);
+    if (tokens.length === 0)
+        return haystackLower.includes(surface.toLowerCase());
+    return tokens.some(token => haystackLower.includes(token));
+}
+function normalizeDecision(value) {
+    const normalized = (value ?? '').toLowerCase();
+    if (normalized === 'verified')
+        return 'verified';
+    if (normalized === 'unverified')
+        return 'unverified';
+    return 'uncertain';
+}
+function clampConfidence(value) {
+    if (typeof value !== 'number' || Number.isNaN(value))
+        return 0.5;
+    return Math.max(0, Math.min(1, value));
+}
+//# sourceMappingURL=FreshContextVerifier.js.map

package/dist/review/FreshContextVerifier.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"FreshContextVerifier.js","sourceRoot":"","sources":["../../src/review/FreshContextVerifier.ts"],"names":[],"mappings":"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"}

package/dist/review/JsonLlmClient.d.ts

@@ -0,0 +1,37 @@
+export interface JsonLlmRequest {
+    system: string;
+    user: string;
+    /** Soft cap for the completion. Defaults to 600. */
+    maxTokens?: number;
+    /** Sampling temperature. Defaults to 0.2 (judges want low variance). */
+    temperature?: number;
+    /** Abort the request after this many ms. Defaults to 20000. */
+    timeoutMs?: number;
+}
+export interface JsonLlmResult<T> {
+    data: T;
+    modelUsed: string;
+    tokensUsed: number;
+}
+/**
+ * Enabled only when a local model is explicitly configured. We intentionally
+ * gate on SCALE_LOCAL_MODEL (and not the defaulted base URL/api key) so the
+ * default developer + CI flow never attempts a network call.
+ */
+export declare function isLlmEnabled(): boolean;
+export declare class JsonLlmClient {
+    private readonly enabledOverride?;
+    constructor(enabledOverride?: boolean | undefined);
+    isEnabled(): boolean;
+    /**
+     * Call the model and parse its reply as JSON. Throws on any failure
+     * (disabled, network error, non-2xx, non-JSON reply) so the caller can fall
+     * back to a deterministic heuristic — exactly like ReflexionEngine does.
+     */
+    completeJson<T>(request: JsonLlmRequest): Promise<JsonLlmResult<T>>;
+}
+/**
+ * Best-effort JSON extraction: accepts a bare JSON object or one wrapped in a
+ * ```json fenced block (a common local-model habit). Returns null on failure.
+ */
+export declare function parseJsonReply<T>(content: string): T | null;

package/dist/review/JsonLlmClient.js

@@ -0,0 +1,94 @@
+// SCALE Engine — JSON LLM client (P1.4 / P2.2)
+// A thin, env-gated wrapper around an OpenAI-compatible /chat/completions
+// endpoint that returns parsed JSON. Mirrors the proven pattern in
+// src/cortex/ReflexionEngine.ts: callers stay deterministic and offline by
+// default (isEnabled() === false ⇒ they use their own heuristic fallback), and
+// only reach the network when a local model is explicitly configured.
+import { logger } from '../core/logger.js';
+import { resolveLocalModelConfig } from '../routing/LocalModelProvider.js';
+/**
+ * Enabled only when a local model is explicitly configured. We intentionally
+ * gate on SCALE_LOCAL_MODEL (and not the defaulted base URL/api key) so the
+ * default developer + CI flow never attempts a network call.
+ */
+export function isLlmEnabled() {
+    return Boolean(process.env.SCALE_LOCAL_MODEL);
+}
+export class JsonLlmClient {
+    constructor(enabledOverride) {
+        this.enabledOverride = enabledOverride;
+    }
+    isEnabled() {
+        return this.enabledOverride ?? isLlmEnabled();
+    }
+    /**
+     * Call the model and parse its reply as JSON. Throws on any failure
+     * (disabled, network error, non-2xx, non-JSON reply) so the caller can fall
+     * back to a deterministic heuristic — exactly like ReflexionEngine does.
+     */
+    async completeJson(request) {
+        if (!this.isEnabled()) {
+            throw new Error('JsonLlmClient is disabled (set SCALE_LOCAL_MODEL to enable)');
+        }
+        const config = resolveLocalModelConfig();
+        const response = await fetch(`${config.baseUrl}/chat/completions`, {
+            method: 'POST',
+            headers: {
+                'Content-Type': 'application/json',
+                Authorization: `Bearer ${config.apiKey}`,
+            },
+            body: JSON.stringify({
+                model: config.name,
+                messages: [
+                    { role: 'system', content: request.system },
+                    { role: 'user', content: request.user },
+                ],
+                temperature: request.temperature ?? 0.2,
+                max_tokens: request.maxTokens ?? 600,
+            }),
+            signal: AbortSignal.timeout(request.timeoutMs ?? 20000),
+        });
+        if (!response.ok) {
+            throw new Error(`LLM endpoint returned ${response.status}`);
+        }
+        const payload = (await response.json());
+        const content = payload.choices?.[0]?.message?.content ?? '';
+        const data = parseJsonReply(content);
+        if (data === null) {
+            throw new Error('LLM reply was not valid JSON');
+        }
+        return {
+            data,
+            modelUsed: config.name,
+            tokensUsed: payload.usage?.total_tokens ?? 0,
+        };
+    }
+}
+/**
+ * Best-effort JSON extraction: accepts a bare JSON object or one wrapped in a
+ * ```json fenced block (a common local-model habit). Returns null on failure.
+ */
+export function parseJsonReply(content) {
+    const trimmed = content.trim();
+    const candidates = [];
+    const fenced = trimmed.match(/```(?:json)?\s*([\s\S]*?)```/i);
+    if (fenced)
+        candidates.push(fenced[1].trim());
+    candidates.push(trimmed);
+    const firstBrace = trimmed.indexOf('{');
+    const lastBrace = trimmed.lastIndexOf('}');
+    if (firstBrace >= 0 && lastBrace > firstBrace) {
+        candidates.push(trimmed.slice(firstBrace, lastBrace + 1));
+    }
+    for (const candidate of candidates) {
+        try {
+            return JSON.parse(candidate);
+        }
+        catch {
+            continue;
+        }
+    }
+    logger.debug({ content: trimmed.slice(0, 200) }, 'JsonLlmClient: failed to parse JSON reply');
+    return null;
+}
+//# sourceMappingURL=JsonLlmClient.js.map

package/dist/review/JsonLlmClient.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"JsonLlmClient.js","sourceRoot":"","sources":["../../src/review/JsonLlmClient.ts"],"names":[],"mappings":"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"}

package/dist/review/LlmJudge.d.ts

@@ -0,0 +1,61 @@
+import { JsonLlmClient } from './JsonLlmClient.js';
+export type JudgeDecision = 'pass' | 'fail' | 'uncertain';
+export interface JudgeVerdict {
+    /** Advisory call on whether the diff meets the Spec outcome. */
+    decision: JudgeDecision;
+    /** 0..1 self-reported confidence. */
+    confidence: number;
+    rationale: string;
+    /** verificationSurface entries with no corresponding evidence in the diff. */
+    unmetSurfaces: string[];
+    /** Model name, or 'heuristic' when the LLM path was not taken. */
+    modelUsed: string;
+    /** Versioned prompt identifier, e.g. "spec-conformance.v1". */
+    promptVersion: string;
+    /** Always true — kept explicit so consumers never gate on this verdict. */
+    advisory: true;
+    createdAt: number;
+}
+export interface JudgeInput {
+    outcome?: string;
+    verificationSurface: string[];
+    /** Pre-trimmed diff summary (changed files + salient added lines). */
+    diffSummary: string;
+    reviewFindings: {
+        critical: number;
+        high: number;
+        medium: number;
+        low: number;
+    };
+}
+interface JudgePromptRecord {
+    id: string;
+    version: string;
+    system: string;
+    rubric: string;
+    createdAt: number;
+}
+/**
+ * Loads/persists the versioned judge prompt under `.scale/judges/<id>.json`
+ * (decision L1) so the rubric is auditable and can drift independently of code.
+ */
+export declare class JudgePromptStore {
+    private readonly dir;
+    constructor(scaleDir?: string);
+    load(id?: string): JudgePromptRecord;
+    private write;
+}
+export declare class LlmJudge {
+    private readonly client;
+    private readonly promptStore;
+    constructor(client?: JsonLlmClient, promptStore?: JudgePromptStore);
+    judge(input: JudgeInput): Promise<JudgeVerdict>;
+    private buildUserPrompt;
+    /**
+     * Deterministic fallback: a surface is "unmet" when none of its significant
+     * tokens appear in the diff summary; any unmet surface or any critical/high
+     * review finding turns the advisory verdict negative.
+     */
+    private heuristicVerdict;
+}
+export {};

package/dist/review/LlmJudge.js

@@ -0,0 +1,167 @@
+// SCALE Engine — LLM-as-Judge (P1.4)
+// Independent, advisory check of whether a diff actually satisfies the Spec's
+// declared outcome / verificationSurface. The verdict is written into the
+// review record as *advisory* evidence (decision K1): it never participates in
+// the pass/fail decision and never blocks ship.
+//
+// Like ReflexionEngine, the judge runs an env-gated LLM when SCALE_LOCAL_MODEL
+// is configured and otherwise falls back to a deterministic heuristic, so the
+// default developer + CI flow stays offline, free and reproducible.
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { logger } from '../core/logger.js';
+import { JsonLlmClient } from './JsonLlmClient.js';
+const DEFAULT_PROMPT = {
+    id: 'spec-conformance',
+    version: 'v1',
+    system: 'You are an independent code-review judge. Decide only whether the diff actually achieves the stated outcome and exercises every declared verification surface. ' +
+        'You are advisory: do not approve work that lacks evidence. Output strict JSON only.',
+    rubric: 'pass = every verification surface is plausibly addressed by the diff and no critical/high review finding contradicts the outcome. ' +
+        'fail = the diff clearly does not achieve the outcome or leaves a declared surface unaddressed. ' +
+        'uncertain = evidence is insufficient to decide.',
+    createdAt: 0,
+};
+/**
+ * Loads/persists the versioned judge prompt under `.scale/judges/<id>.json`
+ * (decision L1) so the rubric is auditable and can drift independently of code.
+ */
+export class JudgePromptStore {
+    constructor(scaleDir = process.env.SCALE_DIR ?? '.scale') {
+        this.dir = join(scaleDir, 'judges');
+    }
+    load(id = DEFAULT_PROMPT.id) {
+        const file = join(this.dir, `${id}.json`);
+        if (existsSync(file)) {
+            try {
+                return JSON.parse(readFileSync(file, 'utf-8'));
+            }
+            catch {
+                logger.warn({ file }, 'JudgePromptStore: corrupt prompt file, using bundled default');
+            }
+        }
+        else if (id === DEFAULT_PROMPT.id) {
+            this.write({ ...DEFAULT_PROMPT, createdAt: Date.now() });
+        }
+        return { ...DEFAULT_PROMPT, createdAt: DEFAULT_PROMPT.createdAt || Date.now() };
+    }
+    write(record) {
+        if (!existsSync(this.dir))
+            mkdirSync(this.dir, { recursive: true });
+        writeFileSync(join(this.dir, `${record.id}.json`), JSON.stringify(record, null, 2), 'utf-8');
+    }
+}
+export class LlmJudge {
+    constructor(client = new JsonLlmClient(), promptStore = new JudgePromptStore()) {
+        this.client = client;
+        this.promptStore = promptStore;
+    }
+    async judge(input) {
+        const prompt = this.promptStore.load();
+        const promptVersion = `${prompt.id}.${prompt.version}`;
+        if (!this.client.isEnabled()) {
+            return this.heuristicVerdict(input, promptVersion);
+        }
+        try {
+            const { data, modelUsed } = await this.client.completeJson({
+                system: `${prompt.system}\n\nRubric: ${prompt.rubric}`,
+                user: this.buildUserPrompt(input),
+            });
+            return {
+                decision: normalizeDecision(data.decision),
+                confidence: clampConfidence(data.confidence),
+                rationale: (data.rationale ?? '').slice(0, 1000) || 'No rationale provided.',
+                unmetSurfaces: Array.isArray(data.unmetSurfaces) ? data.unmetSurfaces.slice(0, 50) : [],
+                modelUsed,
+                promptVersion,
+                advisory: true,
+                createdAt: Date.now(),
+            };
+        }
+        catch (err) {
+            logger.warn({ err }, 'LlmJudge: LLM call failed, falling back to heuristic');
+            return this.heuristicVerdict(input, promptVersion);
+        }
+    }
+    buildUserPrompt(input) {
+        return [
+            `Outcome: ${input.outcome ?? '(not declared)'}`,
+            '',
+            'Verification surfaces (each must be addressed):',
+            ...(input.verificationSurface.length ? input.verificationSurface.map(s => `- ${s}`) : ['- (none declared)']),
+            '',
+            'Review findings:',
+            `critical=${input.reviewFindings.critical} high=${input.reviewFindings.high} medium=${input.reviewFindings.medium} low=${input.reviewFindings.low}`,
+            '',
+            'Diff summary:',
+            input.diffSummary.slice(0, 6000) || '(empty diff)',
+            '',
+            'Output JSON: { "decision": "pass|fail|uncertain", "confidence": 0.0-1.0, "rationale": "...", "unmetSurfaces": ["..."] }',
+        ].join('\n');
+    }
+    /**
+     * Deterministic fallback: a surface is "unmet" when none of its significant
+     * tokens appear in the diff summary; any unmet surface or any critical/high
+     * review finding turns the advisory verdict negative.
+     */
+    heuristicVerdict(input, promptVersion) {
+        const haystack = input.diffSummary.toLowerCase();
+        const unmetSurfaces = input.verificationSurface.filter(surface => !surfaceMentioned(surface, haystack));
+        const blockingFindings = input.reviewFindings.critical + input.reviewFindings.high;
+        let decision;
+        let confidence;
+        let rationale;
+        if (blockingFindings > 0) {
+            decision = 'fail';
+            confidence = 0.6;
+            rationale = `${blockingFindings} critical/high review finding(s) contradict a "done" claim.`;
+        }
+        else if (input.verificationSurface.length === 0) {
+            decision = 'uncertain';
+            confidence = 0.3;
+            rationale = 'No verification surface declared; cannot judge conformance from the diff alone.';
+        }
+        else if (unmetSurfaces.length > 0) {
+            decision = 'uncertain';
+            confidence = 0.4;
+            rationale = `${unmetSurfaces.length}/${input.verificationSurface.length} verification surface(s) have no matching evidence in the diff.`;
+        }
+        else {
+            decision = 'pass';
+            confidence = 0.5;
+            rationale = 'All declared verification surfaces appear in the diff and no critical/high findings were raised.';
+        }
+        return {
+            decision,
+            confidence,
+            rationale,
+            unmetSurfaces,
+            modelUsed: 'heuristic',
+            promptVersion,
+            advisory: true,
+            createdAt: Date.now(),
+        };
+    }
+}
+function surfaceMentioned(surface, haystackLower) {
+    const tokens = surface
+        .toLowerCase()
+        .split(/[^a-z0-9]+/i)
+        .filter(token => token.length >= 4);
+    if (tokens.length === 0)
+        return haystackLower.includes(surface.toLowerCase());
+    return tokens.some(token => haystackLower.includes(token));
+}
+function normalizeDecision(value) {
+    const normalized = (value ?? '').toLowerCase();
+    if (normalized === 'pass')
+        return 'pass';
+    if (normalized === 'fail')
+        return 'fail';
+    return 'uncertain';
+}
+function clampConfidence(value) {
+    if (typeof value !== 'number' || Number.isNaN(value))
+        return 0.5;
+    return Math.max(0, Math.min(1, value));
+}
+//# sourceMappingURL=LlmJudge.js.map

package/dist/review/LlmJudge.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"LlmJudge.js","sourceRoot":"","sources":["../../src/review/LlmJudge.ts"],"names":[],"mappings":"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"}

package/dist/runtime/AiOsRuntime.d.ts

@@ -9,6 +9,7 @@ import { type GovernanceRoiSummary } from '../workflow/GovernanceRoi.js';
 import { type EvolutionShadowReport } from '../workflow/EvolutionShadowPromoter.js';
 import { type LearningEntry } from '../evolution/SessionLearnings.js';
 import { type SessionPreamble } from '../workflow/SessionPreamble.js';
+import { type AgentLoopReadinessReport } from '../workflow/AgentLoopReadiness.js';
 export interface AiOsRuntimeInput {
     projectDir?: string;
     scaleDir?: string;
@@ -412,7 +413,7 @@ export interface AiOsStatusReport {
     nextActions: string[];
     warnings: string[];
 }
-export type AiOsIntelligenceSignalId = 'memory-recall' | 'context-savings' | 'skill-routing' | 'evaluator-intelligence' | 'tool-strategy' | 'adaptive-workflow' | 'evolution-shadow' | 'benchmark-intelligence';
+export type AiOsIntelligenceSignalId = 'memory-recall' | 'context-savings' | 'skill-routing' | 'evaluator-intelligence' | 'tool-strategy' | 'adaptive-workflow' | 'evolution-shadow' | 'agent-loop-readiness' | 'benchmark-intelligence';
 export interface AiOsIntelligenceSignal {
     id: AiOsIntelligenceSignalId;
     status: AiOsClosedLoopStatus;
@@ -432,6 +433,7 @@ export interface AiOsIntelligenceReport {
         contextQuality: AiOsContextQualitySummary;
         evaluatorQuality: AiOsEvaluatorQualitySummary;
         toolStrategyQuality: AiOsToolStrategyQualitySummary;
+        agentLoopQuality: AiOsAgentLoopQualitySummary;
         evolutionQuality: AiOsEvolutionQualitySummary;
         estimatedTokenSavings: number;
         skillSteps: number;
@@ -467,6 +469,17 @@ export interface AiOsToolStrategyQualitySummary {
     estimatedCostUnits: number;
     fallbackCoverage: number;
 }
+export interface AiOsAgentLoopQualitySummary {
+    status: AgentLoopReadinessReport['status'];
+    score: number;
+    readySignals: number;
+    warningSignals: number;
+    missingSignals: number;
+    loopRecoveryRate: number | null;
+    guardrailCoverage: number | null;
+    budgetControlled: boolean | null;
+    terminationEvidence: boolean | null;
+}
 export interface AiOsEvolutionQualitySummary {
     proposals: number;
     shadowRules: number;