@qulib/core 0.2.1 → 0.3.0

package/dist/llm/cost-intelligence.js

@@ -0,0 +1,153 @@
+export function summarizeUsageQuality(records) {
+    if (records.length === 0) {
+        return { totalInputTokens: 0, totalOutputTokens: 0, dataQuality: 'none' };
+    }
+    const totalInputTokens = records.reduce((s, r) => s + r.inputTokens, 0);
+    const totalOutputTokens = records.reduce((s, r) => s + r.outputTokens, 0);
+    const qualities = new Set(records.map((r) => r.dataQuality));
+    if (qualities.size > 1) {
+        return { totalInputTokens, totalOutputTokens, dataQuality: 'mixed' };
+    }
+    const only = records[0].dataQuality;
+    return { totalInputTokens, totalOutputTokens, dataQuality: only };
+}
+export function buildBudgetWarnings(records, maxOutputTokensPerLlmCall) {
+    const warnings = [];
+    for (const r of records) {
+        if (r.dataQuality === 'none' && r.inputTokens === 0 && r.outputTokens === 0) {
+            continue;
+        }
+        const out = r.outputTokens;
+        if (out >= maxOutputTokensPerLlmCall) {
+            warnings.push(`Output tokens (${out}) reached or exceeded the configured per-completion max-output ceiling (${maxOutputTokensPerLlmCall}). Completion may be truncated; raise llmMaxOutputTokensPerCall (or legacy llmTokenBudget) or reduce testGenerationLimit.`);
+        }
+        else if (out >= Math.floor(maxOutputTokensPerLlmCall * 0.8)) {
+            warnings.push(`Output tokens (${out}) are within 80% of the per-completion max-output ceiling (${maxOutputTokensPerLlmCall}). Truncation risk on heavier prompts.`);
+        }
+    }
+    if (records.some((r) => r.dataQuality === 'estimated')) {
+        warnings.push('Some token counts are estimated (API usage missing or call failed). Treat totals as approximate until actual usage is available.');
+    }
+    return warnings;
+}
+export function findRepeatedPromptPatterns(records) {
+    const byHash = new Map();
+    for (const r of records) {
+        if (!r.promptHash)
+            continue;
+        byHash.set(r.promptHash, (byHash.get(r.promptHash) ?? 0) + 1);
+    }
+    const out = [];
+    for (const [promptHash, count] of byHash) {
+        if (count < 2)
+            continue;
+        out.push({
+            promptHash,
+            count,
+            recommendation: 'The same prompt fingerprint appeared multiple times in this run. Capture the intent as versioned Playwright/Cypress checks or shared scenario fixtures so repeat visits do not re-spend model tokens.',
+        });
+    }
+    return out;
+}
+export function buildConversionRecommendations(params) {
+    const rec = [];
+    if (params.scenarioSource === 'llm' && params.gapCount > 0) {
+        rec.push('LLM-authored scenarios are suggestions only. Promote the highest-severity paths into deterministic checks (axe, link crawl, route smoke) checked on every deploy to shrink future LLM reliance.');
+    }
+    if (params.repeatedOperations.length > 0) {
+        rec.push('Deduplicate repeated AI work: key scenarios by gap ids or route templates and reuse stored outputs where the deployment hash is unchanged.');
+    }
+    if (params.budgetWarnings.some((w) => w.includes('truncated') || w.includes('80%'))) {
+        rec.push('Tune llmMaxOutputTokensPerCall (or legacy llmTokenBudget) against real prompt sizes, or lower testGenerationLimit so each completion stays within a safe envelope.');
+    }
+    if (params.scenarioSource === 'template') {
+        rec.push('Scenarios were generated from built-in templates (no LLM). This is the lowest-cost path; keep expanding template coverage for recurring gap categories.');
+    }
+    return rec;
+}
+export function computeDeterministicMaturity(params) {
+    if (params.mode === 'auth-required') {
+        return {
+            level: 0,
+            label: 'L0 — unknown / blocked',
+            rationale: 'Authentication blocked the crawl. Release confidence and gap inventory are not representative until a deterministic auth path is configured.',
+            ceilingNote: 'L1+ require at least one authenticated or public crawl producing structured gaps.',
+        };
+    }
+    if (params.coveragePagesScanned === 0 && params.gapCount === 0) {
+        return {
+            level: 0,
+            label: 'L0 — insufficient deterministic signal',
+            rationale: 'No pages were scanned and no gaps were recorded. Treat maturity as unknown rather than high.',
+            ceilingNote: 'Re-run with reachable URLs, auth, or relaxed crawl limits.',
+        };
+    }
+    let level = 1;
+    let label = 'L1 — deterministic scan inventory';
+    let rationale = 'Structured gaps came from deterministic crawling and checks (links, console, a11y, coverage). This is the baseline Qulib release-confidence story.';
+    if (params.scenarioSource === 'llm') {
+        level = 2;
+        label = 'L2 — AI-assisted analysis layer';
+        rationale =
+            'An LLM expanded gaps into scenarios. Value is exploratory; it is not yet the same as enforced CI coverage.';
+    }
+    if (params.repeatedOperations.length > 0) {
+        level = Math.max(level, 3);
+        label = 'L3 — repeated AI surface';
+        rationale =
+            'Repeated prompt fingerprints suggest the same reasoning loop is firing more than once—strong candidates to replace with cached or deterministic checks.';
+    }
+    const ceilingNote = (params.releaseConfidence ?? 0) >= 85 && !params.requireHumanReview
+        ? 'High release confidence does not imply L4–L5. Reviewed self-healing (L4) and adaptive quality intelligence (L5) require organizational process and feedback loops outside this single scan.'
+        : 'L4 (reviewed self-healing) and L5 (adaptive quality intelligence) are not inferred from a snapshot scan. They require documented review, ownership, and sustained automation feedback.';
+    return { level, label, rationale, ceilingNote };
+}
+export function assembleCostIntelligence(params) {
+    const usageSummary = summarizeUsageQuality(params.records);
+    const budgetWarnings = buildBudgetWarnings(params.records, params.maxOutputTokensPerLlmCall);
+    const repeatedOperations = findRepeatedPromptPatterns(params.records);
+    const conversionRecommendations = buildConversionRecommendations({
+        scenarioSource: params.scenarioSource,
+        repeatedOperations,
+        budgetWarnings,
+        gapCount: params.partial.gaps.length,
+    });
+    const deterministicMaturity = computeDeterministicMaturity({
+        mode: params.partial.mode,
+        coveragePagesScanned: params.partial.coveragePagesScanned,
+        gapCount: params.partial.gaps.length,
+        scenarioSource: params.scenarioSource,
+        repeatedOperations,
+        releaseConfidence: params.partial.releaseConfidence,
+        requireHumanReview: params.requireHumanReview,
+    });
+    return {
+        maxOutputTokensPerLlmCall: params.maxOutputTokensPerLlmCall,
+        budgetRole: 'max-output-tokens-per-llm-call',
+        records: params.records,
+        budgetWarnings,
+        usageSummary,
+        repeatedOperations,
+        deterministicMaturity,
+        conversionRecommendations,
+    };
+}
+export function costIntelligenceForAuthBlocked(maxOutputTokensPerLlmCall) {
+    return {
+        maxOutputTokensPerLlmCall,
+        budgetRole: 'max-output-tokens-per-llm-call',
+        records: [],
+        budgetWarnings: [],
+        usageSummary: { totalInputTokens: 0, totalOutputTokens: 0, dataQuality: 'none' },
+        repeatedOperations: [],
+        deterministicMaturity: {
+            level: 0,
+            label: 'L0 — unknown / blocked',
+            rationale: 'Authentication blocked the crawl. No LLM usage was recorded; deterministic inventory is incomplete.',
+            ceilingNote: 'Configure auth, then re-run so gap analysis and any LLM scenario pass operate on real pages.',
+        },
+        conversionRecommendations: [
+            'Resolve authentication first (storage-state from `qulib auth init` or form-login flags). Cost intelligence for model-assisted work applies after the crawl succeeds.',
+        ],
+    };
+}

package/dist/llm/provider.d.ts

@@ -1,4 +1,14 @@
 import { type Gap, type NeutralScenario } from '../schemas/gap-analysis.schema.js';
-export declare function callLLM(prompt: string, tokenBudget: number): Promise<string>;
+export interface LlmCallResult {
+    text: string;
+    usage: {
+        provider: string;
+        model: string;
+        inputTokens: number;
+        outputTokens: number;
+        dataQuality: 'actual' | 'estimated';
+    } | null;
+}
+export declare function callLLM(prompt: string, tokenBudget: number): Promise<LlmCallResult>;
 export declare function generateScenariosFromTemplate(gaps: Gap[]): NeutralScenario[];
 //# sourceMappingURL=provider.d.ts.map

package/dist/llm/provider.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"provider.d.ts","sourceRoot":"","sources":["../../src/llm/provider.ts"],"names":[],"mappings":"AACA,OAAO,EAAyB,KAAK,GAAG,EAAE,KAAK,eAAe,EAAE,MAAM,mCAAmC,CAAC;AAE1G,wBAAsB,OAAO,CAC3B,MAAM,EAAE,MAAM,EACd,WAAW,EAAE,MAAM,GAClB,OAAO,CAAC,MAAM,CAAC,CA0BjB;AAED,wBAAgB,6BAA6B,CAAC,IAAI,EAAE,GAAG,EAAE,GAAG,eAAe,EAAE,CA4B5E"}
+{"version":3,"file":"provider.d.ts","sourceRoot":"","sources":["../../src/llm/provider.ts"],"names":[],"mappings":"AACA,OAAO,EAAyB,KAAK,GAAG,EAAE,KAAK,eAAe,EAAE,MAAM,mCAAmC,CAAC;AAE1G,MAAM,WAAW,aAAa;IAC5B,IAAI,EAAE,MAAM,CAAC;IACb,KAAK,EAAE;QACL,QAAQ,EAAE,MAAM,CAAC;QACjB,KAAK,EAAE,MAAM,CAAC;QACd,WAAW,EAAE,MAAM,CAAC;QACpB,YAAY,EAAE,MAAM,CAAC;QACrB,WAAW,EAAE,QAAQ,GAAG,WAAW,CAAC;KACrC,GAAG,IAAI,CAAC;CACV;AAMD,wBAAsB,OAAO,CAAC,MAAM,EAAE,MAAM,EAAE,WAAW,EAAE,MAAM,GAAG,OAAO,CAAC,aAAa,CAAC,CAwDzF;AAED,wBAAgB,6BAA6B,CAAC,IAAI,EAAE,GAAG,EAAE,GAAG,eAAe,EAAE,CAuC5E"}

package/dist/llm/provider.js

@@ -1,9 +1,13 @@
 import { randomUUID } from 'node:crypto';
 import { NeutralScenarioSchema } from '../schemas/gap-analysis.schema.js';
+function estimateTokensFromChars(chars) {
+    return Math.max(0, Math.ceil(chars / 4));
+}
 export async function callLLM(prompt, tokenBudget) {
     const apiKey = process.env.ANTHROPIC_API_KEY;
     if (!apiKey)
         throw new Error('ANTHROPIC_API_KEY is not set');
+    const model = 'claude-sonnet-4-20250514';
     const response = await fetch('https://api.anthropic.com/v1/messages', {
         method: 'POST',
         headers: {
@@ -12,7 +16,7 @@ export async function callLLM(prompt, tokenBudget) {
             'content-type': 'application/json',
         },
         body: JSON.stringify({
-            model: 'claude-sonnet-4-20250514',
+            model,
             max_tokens: tokenBudget,
             messages: [{ role: 'user', content: prompt }],
         }),
@@ -21,9 +25,32 @@ export async function callLLM(prompt, tokenBudget) {
         const text = await response.text();
         throw new Error(`LLM call failed: ${response.status} ${text}`);
     }
-    const data = await response.json();
+    const data = (await response.json());
     const text = data.content.find((b) => b.type === 'text')?.text ?? '';
-    return text;
+    const inTok = data.usage?.input_tokens;
+    const outTok = data.usage?.output_tokens;
+    if (typeof inTok === 'number' && typeof outTok === 'number') {
+        return {
+            text,
+            usage: {
+                provider: 'anthropic',
+                model: data.model ?? model,
+                inputTokens: inTok,
+                outputTokens: outTok,
+                dataQuality: 'actual',
+            },
+        };
+    }
+    return {
+        text,
+        usage: {
+            provider: 'anthropic',
+            model: data.model ?? model,
+            inputTokens: estimateTokensFromChars(prompt.length),
+            outputTokens: estimateTokensFromChars(text.length),
+            dataQuality: 'estimated',
+        },
+    };
 }
 export function generateScenariosFromTemplate(gaps) {
     return gaps.map((gap) => {
@@ -41,7 +68,19 @@ export function generateScenariosFromTemplate(gaps) {
         else if (gap.category === 'broken-link') {
             steps.push({ action: 'assert-visible', description: 'Assert all links resolve correctly' });
         }
-        const adapter = gap.category === 'a11y' ? 'accessibility' : 'playwright';
+        else if (gap.category === 'auth-surface') {
+            steps.push({
+                action: 'assert-visible',
+                description: 'Verify sign-in surface accessibility and SSO affordances',
+            });
+        }
+        else if (gap.category === 'coverage') {
+            steps.push({
+                action: 'assert-visible',
+                description: 'Resolve authentication and re-run full deployment scan',
+            });
+        }
+        const adapter = gap.category === 'a11y' || gap.category === 'auth-surface' ? 'accessibility' : 'playwright';
         return NeutralScenarioSchema.parse({
             id: randomUUID(),
             title: `[${gap.severity.toUpperCase()}] ${gap.category} — ${gap.path}`,

package/dist/phases/act.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"act.d.ts","sourceRoot":"","sources":["../../src/phases/act.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,6BAA6B,CAAC;AACjE,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,mCAAmC,CAAC;AAIrE,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,2BAA2B,CAAC;AAErE,wBAAsB,GAAG,CACvB,QAAQ,EAAE,WAAW,EACrB,MAAM,EAAE,aAAa,EACrB,SAAS,GAAE,mBAA8C,GACxD,OAAO,CAAC,IAAI,CAAC,CA0Cf"}
+{"version":3,"file":"act.d.ts","sourceRoot":"","sources":["../../src/phases/act.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,6BAA6B,CAAC;AACjE,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,mCAAmC,CAAC;AAIrE,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,2BAA2B,CAAC;AAErE,wBAAsB,GAAG,CACvB,QAAQ,EAAE,WAAW,EACrB,MAAM,EAAE,aAAa,EACrB,SAAS,GAAE,mBAA8C,GACxD,OAAO,CAAC,IAAI,CAAC,CA+Cf"}

package/dist/phases/act.js

@@ -27,7 +27,10 @@ export async function act(analysis, config, artifacts = { writeArtifacts: true }
     log('\n[qulib] Analysis complete');
     log(`  Gaps found:          ${analysis.gaps.length}`);
     log(`  Scenarios generated: ${analysis.scenarios.length}`);
-    log(`  Release confidence:  ${analysis.releaseConfidence}/100`);
+    log(`  Release confidence:  ${analysis.releaseConfidence === null ? '— (null)' : `${analysis.releaseConfidence}/100`}`);
+    if (analysis.costIntelligence?.budgetWarnings.length) {
+        log(`  Cost warnings:       ${analysis.costIntelligence.budgetWarnings.length} (see report.md Cost Intelligence)`);
+    }
     if (config.requireHumanReview) {
         log('\n[qulib] Human review required before applying any generated output.');
         if (artifacts.writeArtifacts) {

package/dist/phases/observe.js

@@ -8,7 +8,7 @@ export async function observe(baseUrl, repoPath, config, artifacts = { writeArti
     const explorer = createExplorer(config.explorer);
     const stateManager = new StateManager();
     const logOpts = { persist: artifacts.writeArtifacts, memory: artifacts.decisionMemory };
-    const rawRoutes = await explorer.explore(baseUrl, config);
+    const rawRoutes = await explorer.explore(baseUrl, config, artifacts);
     const routes = RouteInventorySchema.parse(rawRoutes);
     if (artifacts.writeArtifacts) {
         await stateManager.writeState('discovered-routes.json', routes, RouteInventorySchema);

package/dist/phases/think-finalize.d.ts

@@ -0,0 +1,6 @@
+import { type HarnessConfig } from '../schemas/config.schema.js';
+import { type GapAnalysis } from '../schemas/gap-analysis.schema.js';
+import type { RunArtifactsOptions } from '../harness/run-options.js';
+export type GapAnalysisDraft = Omit<GapAnalysis, 'scenarios' | 'generatedTests' | 'costIntelligence'>;
+export declare function finalizeGapAnalysisFromDraft(draft: GapAnalysisDraft, config: HarnessConfig, artifacts?: RunArtifactsOptions, costContext?: Pick<GapAnalysis, 'mode' | 'coveragePagesScanned' | 'releaseConfidence' | 'gaps'>): Promise<GapAnalysis>;
+//# sourceMappingURL=think-finalize.d.ts.map

package/dist/phases/think-finalize.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"think-finalize.d.ts","sourceRoot":"","sources":["../../src/phases/think-finalize.ts"],"names":[],"mappings":"AAAA,OAAO,EAAoC,KAAK,aAAa,EAAE,MAAM,6BAA6B,CAAC;AACnG,OAAO,EAA4C,KAAK,WAAW,EAAwB,MAAM,mCAAmC,CAAC;AAQrI,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,2BAA2B,CAAC;AAErE,MAAM,MAAM,gBAAgB,GAAG,IAAI,CAAC,WAAW,EAAE,WAAW,GAAG,gBAAgB,GAAG,kBAAkB,CAAC,CAAC;AAEtG,wBAAsB,4BAA4B,CAChD,KAAK,EAAE,gBAAgB,EACvB,MAAM,EAAE,aAAa,EACrB,SAAS,GAAE,mBAA8C,EACzD,WAAW,CAAC,EAAE,IAAI,CAAC,WAAW,EAAE,MAAM,GAAG,sBAAsB,GAAG,mBAAmB,GAAG,MAAM,CAAC,GAC9F,OAAO,CAAC,WAAW,CAAC,CAwKtB"}

package/dist/phases/think-finalize.js

@@ -0,0 +1,164 @@
+import { resolveMaxOutputTokensPerLlmCall } from '../schemas/config.schema.js';
+import { GapAnalysisSchema, NeutralScenarioSchema } from '../schemas/gap-analysis.schema.js';
+import { StateManager } from '../harness/state-manager.js';
+import { logDecision } from '../harness/decision-logger.js';
+import { callLLM, generateScenariosFromTemplate } from '../llm/provider.js';
+import { buildGapPrompt } from '../llm/context-builder.js';
+import { assembleCostIntelligence } from '../llm/cost-intelligence.js';
+import { hashForCostIntelligence } from '../llm/content-hash.js';
+export async function finalizeGapAnalysisFromDraft(draft, config, artifacts = { writeArtifacts: true }, costContext) {
+    const stateManager = new StateManager();
+    const logOpts = { persist: artifacts.writeArtifacts, memory: artifacts.decisionMemory };
+    const partialAnalysis = GapAnalysisSchema.parse({
+        ...draft,
+        scenarios: [],
+        generatedTests: [],
+    });
+    let scenarioSource = 'template';
+    let generatedScenarios = [];
+    const llmRecords = [];
+    const maxOut = resolveMaxOutputTokensPerLlmCall(config);
+    if (!config.enableLlmScenarios) {
+        await logDecision({
+            timestamp: new Date().toISOString(),
+            phase: 'think',
+            decision: 'llm-scenarios-disabled',
+            reason: 'enableLlmScenarios is false; using template scenarios only',
+        }, logOpts);
+        generatedScenarios = generateScenariosFromTemplate(partialAnalysis.gaps);
+        llmRecords.push({
+            provider: 'none',
+            model: 'none',
+            inputTokens: 0,
+            outputTokens: 0,
+            operationType: 'scenario-generation',
+            timestamp: new Date().toISOString(),
+            dataQuality: 'none',
+            notes: 'No LLM call: enableLlmScenarios is false in harness config.',
+        });
+    }
+    else if (!process.env.ANTHROPIC_API_KEY) {
+        await logDecision({
+            timestamp: new Date().toISOString(),
+            phase: 'think',
+            decision: 'llm-scenarios-skipped',
+            reason: 'Skipped LLM scenario generation because ANTHROPIC_API_KEY is not set',
+        }, logOpts);
+        generatedScenarios = generateScenariosFromTemplate(partialAnalysis.gaps);
+        llmRecords.push({
+            provider: 'none',
+            model: 'none',
+            inputTokens: 0,
+            outputTokens: 0,
+            operationType: 'scenario-generation',
+            timestamp: new Date().toISOString(),
+            dataQuality: 'none',
+            notes: 'No LLM call: ANTHROPIC_API_KEY not set; template scenarios only.',
+        });
+    }
+    else {
+        const prompt = buildGapPrompt(partialAnalysis.gaps, config.testGenerationLimit);
+        const promptHash = hashForCostIntelligence(prompt);
+        try {
+            const llmResult = await callLLM(prompt, maxOut);
+            const resultHash = hashForCostIntelligence(llmResult.text);
+            const usage = llmResult.usage;
+            llmRecords.push({
+                provider: usage?.provider ?? 'unknown',
+                model: usage?.model ?? 'unknown',
+                inputTokens: usage?.inputTokens ?? 0,
+                outputTokens: usage?.outputTokens ?? 0,
+                operationType: 'scenario-generation',
+                timestamp: new Date().toISOString(),
+                promptHash,
+                resultHash,
+                dataQuality: usage?.dataQuality ?? 'estimated',
+                notes: usage?.dataQuality === 'estimated'
+                    ? 'Token counts estimated (API usage block missing).'
+                    : undefined,
+            });
+            try {
+                const parsed = JSON.parse(llmResult.text);
+                const candidates = Array.isArray(parsed) ? parsed : [];
+                for (const item of candidates) {
+                    const validated = NeutralScenarioSchema.safeParse(item);
+                    if (validated.success) {
+                        generatedScenarios.push(validated.data);
+                    }
+                }
+                if (generatedScenarios.length === 0) {
+                    generatedScenarios = generateScenariosFromTemplate(partialAnalysis.gaps);
+                    scenarioSource = 'template';
+                    const last = llmRecords[llmRecords.length - 1];
+                    if (last) {
+                        last.notes = [last.notes, 'Model returned no valid scenarios; template scenarios used.']
+                            .filter(Boolean)
+                            .join(' ');
+                    }
+                }
+                else {
+                    scenarioSource = 'llm';
+                }
+            }
+            catch {
+                generatedScenarios = generateScenariosFromTemplate(partialAnalysis.gaps);
+                scenarioSource = 'template';
+                const last = llmRecords[llmRecords.length - 1];
+                if (last) {
+                    last.notes = [last.notes, 'Response was not valid JSON; template scenarios used.']
+                        .filter(Boolean)
+                        .join(' ');
+                }
+            }
+        }
+        catch (err) {
+            generatedScenarios = generateScenariosFromTemplate(partialAnalysis.gaps);
+            scenarioSource = 'template';
+            const msg = err instanceof Error ? err.message : String(err);
+            llmRecords.push({
+                provider: 'unavailable',
+                model: 'unknown',
+                inputTokens: Math.max(0, Math.ceil(prompt.length / 4)),
+                outputTokens: 0,
+                operationType: 'scenario-generation',
+                timestamp: new Date().toISOString(),
+                promptHash,
+                dataQuality: 'estimated',
+                notes: `LLM call failed; template scenarios used. ${msg.slice(0, 240)}`,
+            });
+        }
+    }
+    await logDecision({
+        timestamp: new Date().toISOString(),
+        phase: 'think',
+        decision: 'scenario-generation-complete',
+        reason: `Generated ${generatedScenarios.length} scenarios via ${scenarioSource}`,
+        metadata: {
+            source: scenarioSource,
+            scenarioCount: generatedScenarios.length,
+        },
+    }, logOpts);
+    const costPartial = costContext ?? partialAnalysis;
+    const costIntelligence = assembleCostIntelligence({
+        maxOutputTokensPerLlmCall: maxOut,
+        records: llmRecords,
+        partial: {
+            mode: costPartial.mode,
+            coveragePagesScanned: costPartial.coveragePagesScanned,
+            releaseConfidence: costPartial.releaseConfidence ?? 0,
+            gaps: costPartial.gaps,
+        },
+        scenarioSource,
+        requireHumanReview: config.requireHumanReview,
+    });
+    const completeAnalysis = GapAnalysisSchema.parse({
+        ...partialAnalysis,
+        scenarios: generatedScenarios,
+        generatedTests: [],
+        costIntelligence,
+    });
+    if (artifacts.writeArtifacts) {
+        await stateManager.writeState('gap-analysis.json', completeAnalysis, GapAnalysisSchema);
+    }
+    return completeAnalysis;
+}

package/dist/phases/think.d.ts

@@ -3,4 +3,6 @@ import { type GapAnalysis } from '../schemas/gap-analysis.schema.js';
 import type { ObserveResult } from './observe.js';
 import type { RunArtifactsOptions } from '../harness/run-options.js';
 export declare function think(observed: ObserveResult, config: HarnessConfig, artifacts?: RunArtifactsOptions): Promise<GapAnalysis>;
+export { finalizeGapAnalysisFromDraft } from './think-finalize.js';
+export type { GapAnalysisDraft } from './think-finalize.js';
 //# sourceMappingURL=think.d.ts.map

package/dist/phases/think.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"think.d.ts","sourceRoot":"","sources":["../../src/phases/think.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,6BAA6B,CAAC;AACjE,OAAO,EAA4C,KAAK,WAAW,EAAwB,MAAM,mCAAmC,CAAC;AACrI,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,cAAc,CAAC;AAMlD,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,2BAA2B,CAAC;AAErE,wBAAsB,KAAK,CACzB,QAAQ,EAAE,aAAa,EACvB,MAAM,EAAE,aAAa,EACrB,SAAS,GAAE,mBAA8C,GACxD,OAAO,CAAC,WAAW,CAAC,CA6FtB"}
+{"version":3,"file":"think.d.ts","sourceRoot":"","sources":["../../src/phases/think.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,6BAA6B,CAAC;AACjE,OAAO,EAAqB,KAAK,WAAW,EAAE,MAAM,mCAAmC,CAAC;AACxF,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,cAAc,CAAC;AAGlD,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,2BAA2B,CAAC;AAGrE,wBAAsB,KAAK,CACzB,QAAQ,EAAE,aAAa,EACvB,MAAM,EAAE,aAAa,EACrB,SAAS,GAAE,mBAA8C,GACxD,OAAO,CAAC,WAAW,CAAC,CAqCtB;AAED,OAAO,EAAE,4BAA4B,EAAE,MAAM,qBAAqB,CAAC;AACnE,YAAY,EAAE,gBAAgB,EAAE,MAAM,qBAAqB,CAAC"}

package/dist/phases/think.js

@@ -1,85 +1,36 @@
-import { GapAnalysisSchema, NeutralScenarioSchema } from '../schemas/gap-analysis.schema.js';
+import { GapAnalysisSchema } from '../schemas/gap-analysis.schema.js';
 import { analyzeGaps } from '../tools/gap-engine.js';
-import { StateManager } from '../harness/state-manager.js';
 import { logDecision } from '../harness/decision-logger.js';
-import { callLLM, generateScenariosFromTemplate } from '../llm/provider.js';
-import { buildGapPrompt } from '../llm/context-builder.js';
+import { finalizeGapAnalysisFromDraft } from './think-finalize.js';
 export async function think(observed, config, artifacts = { writeArtifacts: true }) {
     const mode = observed.repo ? 'url-repo' : 'url-only';
-    const stateManager = new StateManager();
     const logOpts = { persist: artifacts.writeArtifacts, memory: artifacts.decisionMemory };
+    const gapBlock = analyzeGaps(observed.routes, observed.repo, mode, config);
+    const draft = {
+        analyzedAt: gapBlock.analyzedAt,
+        mode: gapBlock.mode,
+        releaseConfidence: gapBlock.releaseConfidence,
+        coveragePagesScanned: gapBlock.coveragePagesScanned,
+        coverageBudgetExceeded: gapBlock.coverageBudgetExceeded,
+        coverageWarning: gapBlock.coverageWarning,
+        gaps: gapBlock.gaps,
+    };
     const partialAnalysis = GapAnalysisSchema.parse({
-        ...analyzeGaps(observed.routes, observed.repo, mode, config),
+        ...draft,
         scenarios: [],
         generatedTests: [],
     });
-    if (artifacts.writeArtifacts) {
-        await stateManager.writeState('gap-analysis.json', partialAnalysis, GapAnalysisSchema);
-    }
     await logDecision({
         timestamp: new Date().toISOString(),
         phase: 'think',
         decision: 'gap-analysis-complete',
-        reason: `Computed ${partialAnalysis.gaps.length} gaps with release confidence ${partialAnalysis.releaseConfidence}`,
+        reason: `Computed ${partialAnalysis.gaps.length} gaps with release confidence ${String(partialAnalysis.releaseConfidence)}`,
         metadata: {
             mode,
             gapCount: partialAnalysis.gaps.length,
             releaseConfidence: partialAnalysis.releaseConfidence,
         },
     }, logOpts);
-    let scenarioSource = 'template';
-    let generatedScenarios = [];
-    if (!process.env.ANTHROPIC_API_KEY) {
-        await logDecision({
-            timestamp: new Date().toISOString(),
-            phase: 'think',
-            decision: 'llm-scenarios-skipped',
-            reason: 'Skipped LLM scenario generation because ANTHROPIC_API_KEY is not set',
-        }, logOpts);
-        generatedScenarios = generateScenariosFromTemplate(partialAnalysis.gaps);
-    }
-    else {
-        try {
-            const prompt = buildGapPrompt(partialAnalysis.gaps, config.testGenerationLimit);
-            const response = await callLLM(prompt, config.llmTokenBudget);
-            const parsed = JSON.parse(response);
-            const candidates = Array.isArray(parsed) ? parsed : [];
-            for (const item of candidates) {
-                const validated = NeutralScenarioSchema.safeParse(item);
-                if (validated.success) {
-                    generatedScenarios.push(validated.data);
-                }
-            }
-            if (generatedScenarios.length === 0) {
-                generatedScenarios = generateScenariosFromTemplate(partialAnalysis.gaps);
-                scenarioSource = 'template';
-            }
-            else {
-                scenarioSource = 'llm';
-            }
-        }
-        catch {
-            generatedScenarios = generateScenariosFromTemplate(partialAnalysis.gaps);
-            scenarioSource = 'template';
-        }
-    }
-    await logDecision({
-        timestamp: new Date().toISOString(),
-        phase: 'think',
-        decision: 'scenario-generation-complete',
-        reason: `Generated ${generatedScenarios.length} scenarios via ${scenarioSource}`,
-        metadata: {
-            source: scenarioSource,
-            scenarioCount: generatedScenarios.length,
-        },
-    }, logOpts);
-    const completeAnalysis = GapAnalysisSchema.parse({
-        ...partialAnalysis,
-        scenarios: generatedScenarios,
-        generatedTests: [],
-    });
-    if (artifacts.writeArtifacts) {
-        await stateManager.writeState('gap-analysis.json', completeAnalysis, GapAnalysisSchema);
-    }
-    return completeAnalysis;
+    return finalizeGapAnalysisFromDraft(draft, config, artifacts);
 }
+export { finalizeGapAnalysisFromDraft } from './think-finalize.js';

package/dist/reporters/markdown-reporter.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"markdown-reporter.d.ts","sourceRoot":"","sources":["../../src/reporters/markdown-reporter.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,mCAAmC,CAAC;AAErE,wBAAsB,mBAAmB,CAAC,QAAQ,EAAE,WAAW,EAAE,SAAS,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CA6CjG"}
+{"version":3,"file":"markdown-reporter.d.ts","sourceRoot":"","sources":["../../src/reporters/markdown-reporter.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,mCAAmC,CAAC;AAErE,wBAAsB,mBAAmB,CAAC,QAAQ,EAAE,WAAW,EAAE,SAAS,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAkEjG"}

package/dist/reporters/markdown-reporter.js

@@ -2,19 +2,38 @@ import { writeFile, mkdir } from 'node:fs/promises';
 import { join } from 'node:path';
 export async function writeMarkdownReport(analysis, outputDir) {
     await mkdir(outputDir, { recursive: true });
-    const recommendation = analysis.releaseConfidence >= 80 ? 'READY' :
-        analysis.releaseConfidence >= 50 ? 'CONDITIONAL' : 'NOT READY';
+    const rc = analysis.releaseConfidence;
+    const recommendation = rc === null
+        ? 'NOT SCORED (blocked or insufficient surface)'
+        : rc >= 80
+            ? 'READY'
+            : rc >= 50
+                ? 'CONDITIONAL'
+                : 'NOT READY';
     const gapRows = analysis.gaps
         .map((g) => `| ${g.path} | ${g.category} | ${g.severity} | ${g.reason} |`)
         .join('\n');
     const scenarioBlocks = analysis.scenarios
         .map((s) => `### ${s.title}\n${s.description}\n\nSteps:\n${s.steps.map((step) => `- ${step.description}`).join('\n')}\n\nRecommended adapters: ${s.recommendations.map((r) => r.adapter).join(', ')}`)
         .join('\n\n---\n\n');
+    const ci = analysis.costIntelligence;
+    const costSection = ci
+        ? `## Cost Intelligence
+
+- **Per-completion LLM output ceiling:** ${ci.maxOutputTokensPerLlmCall} (${ci.budgetRole.replace(/-/g, ' ')})
+- **Meaning:** this caps **one** model completion per scenario-generation call; it is **not** a multi-step or multi-run token budget.
+- **Usage (this run):** input ${ci.usageSummary.totalInputTokens}, output ${ci.usageSummary.totalOutputTokens} tokens — _${ci.usageSummary.dataQuality}_
+- **Budget warnings:** ${ci.budgetWarnings.length ? ci.budgetWarnings.map((w) => `\n  - ${w}`).join('') : '_none_'}
+- **Repeated AI patterns:** ${ci.repeatedOperations.length ? ci.repeatedOperations.map((r) => `\n  - \`${r.promptHash}\` ×${r.count}: ${r.recommendation}`).join('') : '_none detected in this run_'}
+- **Deterministic maturity:** **${ci.deterministicMaturity.label}** (level ${ci.deterministicMaturity.level}/5) — ${ci.deterministicMaturity.rationale}${ci.deterministicMaturity.ceilingNote ? `\n  - _${ci.deterministicMaturity.ceilingNote}_` : ''}
+- **Conversion recommendations:**${ci.conversionRecommendations.length ? ci.conversionRecommendations.map((c) => `\n  - ${c}`).join('') : '\n  - _none_'}
+`
+        : '';
     const md = `# Qulib Quality Gap Report
 
 **Generated:** ${analysis.analyzedAt}
 **Mode:** ${analysis.mode}
-**Release confidence:** ${analysis.releaseConfidence}/100 — ${recommendation}
+**Release confidence:** ${rc === null ? '—' : `${rc}/100`} — ${recommendation}
 
 ## Coverage
 
@@ -22,6 +41,7 @@ export async function writeMarkdownReport(analysis, outputDir) {
 - Scan budget exhausted (unfinished queue): ${analysis.coverageBudgetExceeded ? 'yes' : 'no'}
 ${analysis.coverageWarning ? `- Warning: **${analysis.coverageWarning}**` : '- Warning: none'}
 
+${costSection}
 ## Coverage gaps (${analysis.gaps.length})
 
 | Path | Category | Severity | Reason |