scai 0.1.152 → 0.1.154

package/dist/agents/MainAgent.js

@@ -13,7 +13,9 @@ import { resolveExecutionModeStep } from "./resolveExecutionModeStep.js";
 import { fileCheckStep } from "./fileCheckStep.js";
 import { analysisPlanGenStep } from "./analysisPlanGenStep.js";
 import { readinessGateStep } from "./readinessGateStep.js";
-import { collectAnalysisEvidenceStep } from "./collectAnalysisEvidenceStep.js";
+import { scopeClassificationStep } from "./scopeClassificationStep.js";
+import { routingDecisionStep } from "./routingDecisionStep.js";
+import { evidenceVerifierStep } from "./evidenceVerifierStep.js";
 /* ───────────────────────── registry ───────────────────────── */
 const MODULE_REGISTRY = Object.fromEntries(Object.entries(builtInModules).map(([name, mod]) => [name, mod]));
 function resolveModuleForAction(action) {
@@ -82,19 +84,29 @@ export class MainAgent {
     /* ───────────── execution gates ───────────── */
     canExecutePhase(phase) {
         const mode = this.context.executionControl?.mode ?? "transform";
+        const constraints = this.context.executionControl?.constraints;
+        let allowed;
+        // If docsOnly is true, prevent any non-doc actions
+        const docsOnly = constraints?.docsOnly ?? false;
         switch (phase) {
             case "analysis":
-                return mode !== "explain"; // only analyze if not explain
+                allowed = !docsOnly && (constraints?.allowAnalysis ?? (mode !== "explain"));
+                break;
             case "planning":
-                return mode === "analyze" || mode === "transform";
+                allowed = !docsOnly && (constraints?.allowPlanning ?? (mode === "analyze" || mode === "transform"));
+                break;
             case "transform":
             case "write":
-                return mode === "transform"; // write only in transform
+                allowed = constraints?.allowFileWrites ?? (mode === "transform");
+                break;
             case "explain":
-                return mode === "explain"; // only explain mode runs explain
+                allowed = mode === "explain"; // explain is purely mode-based
+                break;
             default:
-                return false;
+                allowed = false;
         }
+        this.logLine("EXEC", "canExecutePhase", undefined, `phase=${phase}, mode=${mode}, docsOnly=${docsOnly}, allowed=${allowed}`);
+        return allowed;
     }
     /* ───────────── main run ───────────── */
     async run() {
@@ -103,54 +115,115 @@ export class MainAgent {
         this.logLine("RUN", `start #${this.runCount}`);
         logInputOutput("GlobalContext (structured)", "input", this.context);
         /* ================= BOOT ================= */
+        // AXIS 1: Capability — determine WHAT actions are allowed
+        // executionMode: "explain" | "analyze" | "transform"
+        // Controls: files may be written, code analyzed, or run text-only
+        // This step does NOT determine WHERE to act or whether enough evidence exists
         {
             const t1 = this.startTimer();
-            await understandIntentStep.run({ context: this.context });
+            await understandIntentStep.run({ context: this.context }); // Classify user intent
             this.logLine("BOOT", "understandIntent", t1());
             const t2 = this.startTimer();
-            await resolveExecutionModeStep.run(this.context);
+            await resolveExecutionModeStep.run(this.context); // Set executionMode
             this.logLine("BOOT", "resolveExecutionMode", t2(), `mode = ${this.context.executionControl?.mode}`);
-            ensureExecutionControl(this.context);
             const db = getDbForRepo();
-            this.taskId = bootTaskForRepo(this.context, db, this.logLine.bind(this));
+            this.taskId = bootTaskForRepo(this.context, db, this.logLine.bind(this)); // Persist task
         }
         /* ================= PRECHECK (INITIAL) ================= */
+        // Quick file existence check (pre-grounding)
+        // Does NOT infer relevance or scope beyond directly referenced files
         {
             const t = this.startTimer();
             await fileCheckStep(this.context);
             this.logLine("PRECHECK", "preFileSearch", t());
         }
-        /* ================= INFORMATION ACQUISITION ================= */
-        if (this.canExecutePhase("planning")) {
-            {
+        /* ───────────────────────── SCOPE & ROUTING GATE ───────────────────────── */
+        // AXIS 2: Scope — determine WHERE the agent may act
+        // scopeType: "none" | "single-file" | "multi-file" | "repo-wide"
+        // Responsible for deciding which files, repos, or modules the agent should consider
+        // Does NOT validate anchors (Axis 3) or decide allowed actions (Axis 1)
+        // ----------------- SCOPE CLASSIFICATION -----------------
+        // Responsibility:
+        //  - Determine problem coverage: none / single-file / multi-file / repo-wide
+        //  - Purely repo/file coverage decision
+        //  - Output: context.analysis.scopeType
+        // Does NOT decide allowed actions, validate evidence, or affect executionMode
+        {
+            const t1 = this.startTimer();
+            await scopeClassificationStep.run(this.context);
+            this.logLine("SCOPE", "scopeClassification", t1());
+        }
+        // ----------------- ROUTING DECISION -----------------
+        // Responsibility:
+        //  - Determine allowed actions within scope
+        //    * Can search be performed?
+        //    * Are early exits (explain) allowed?
+        //  - Output: context.analysis.routingDecision
+        // Does NOT check anchors, determine readiness, or modify scope
+        {
+            const t2 = this.startTimer();
+            await routingDecisionStep.run(this.context);
+            this.logLine("SCOPE", "routingDecision", t2());
+        }
+        /* ================= GROUNDING & READINESS LOOP ================= */
+        // AXIS 3: Certainty — do we have enough evidence to safely proceed?
+        // confidence: "high" | "medium" | "low"
+        // Controls whether we loop back to acquire more info
+        // Does NOT change executionMode (Axis 1) or scopeType (Axis 2)
+        let ready = false;
+        while (!ready && this.runCount < this.maxRuns) {
+            const routing = this.context.analysis?.routingDecision;
+            // ---------------- INFORMATION ACQUISITION ----------------
+            // Plan & execute info steps; may discover new files
+            // Does NOT guarantee readiness — anchors still need verification
+            if (this.canExecutePhase("planning") && routing?.allowInfoSteps !== false) {
                 const t = this.startTimer();
-                await infoPlanGen.run(this.context);
+                await infoPlanGen.run(this.context); // Generate info-gathering plan
                 this.logLine("PLAN", "infoPlanGen", t());
+                let stepIO = { query: this.query };
+                const infoPlan = this.context.analysis?.planSuggestion?.plan ?? { steps: [] };
+                for (const step of infoPlan.steps.filter(s => s.groups?.includes("info"))) {
+                    // Guard: skip fileSearch if routingDecision forbids repo search
+                    if (step.action === "fileSearch" && !routing?.allowSearch) {
+                        this.logLine("PLAN", "infoStepSkipped", undefined, `Step "${step.description}" skipped: file search not allowed by routingDecision`);
+                        continue;
+                    }
+                    stepIO = await this.executeStep(step, stepIO);
+                }
+                // Re-run precheck for newly discovered files
+                if (infoPlan.steps.length > 0) {
+                    const t2 = this.startTimer();
+                    await fileCheckStep(this.context);
+                    this.logLine("PRECHECK", "postFileSearch", t2());
+                }
             }
-            let stepIO = { query: this.query };
-            const infoPlan = this.context.analysis?.planSuggestion?.plan ?? { steps: [] };
-            for (const step of infoPlan.steps.filter(s => s.groups?.includes("info"))) {
-                stepIO = await this.executeStep(step, stepIO);
-            }
-            if (infoPlan.steps.length > 0) {
-                const t = this.startTimer();
-                await fileCheckStep(this.context);
-                this.logLine("PRECHECK", "postFileSearch", t());
-            }
-        }
-        /* ================= GROUNDING & READINESS GATE ================= */
-        {
+            // ---------------- DETERMINISTIC EVIDENCE VERIFICATION ----------------
+            // Verify anchors exist (filenames, paths, literals)
+            // Does NOT execute full analysis or transformations
             const t1 = this.startTimer();
-            await collectAnalysisEvidenceStep.run({ query: this.query, context: this.context });
-            this.logLine("ANALYSIS", "collectAnalysisEvidence", t1());
+            await evidenceVerifierStep.run({ query: this.query, context: this.context });
+            this.logLine("ANALYSIS", "collectAnalysisEvidence", t1(), undefined);
+            // Select grounded candidate files
+            // Does NOT update executionMode or scope classification
             const t2 = this.startTimer();
             await selectRelevantSourcesStep.run({ query: this.query, context: this.context });
-            this.logLine("ANALYSIS", "selectRelevantSources", t2());
+            this.logLine("ANALYSIS", "selectRelevantSources", t2(), undefined);
+            // ---------------- READINESS GATE ----------------
+            // Decide if we have enough info to proceed
+            // Does NOT modify info plan or transform steps
             const t3 = this.startTimer();
             await readinessGateStep.run(this.context);
-            this.logLine("HASINFO", "readinessGate", t3());
+            this.logLine("HASINFO", "readinessGate", t3(), undefined);
+            ready = this.context.analysis?.readiness?.decision === "ready";
+            if (!ready) {
+                this.runCount++;
+                this.resetInitContextForLoop();
+                this.logLine("HASINFO", "readinessGate", undefined, "Not ready, looping back to information acquisition");
+            }
         }
         /* ================= EXPLAIN (EVIDENCE EXIT) ================= */
+        // Early exit if mode=explain and routing allows it
+        // Does NOT perform analysis, transform, or write steps
         if (this.canExecutePhase("explain") &&
             this.context.analysis?.routingDecision?.decision === "has-info") {
             const explainMod = resolveModuleForAction("explain");
@@ -161,6 +234,7 @@ export class MainAgent {
                 context: this.context
             });
         }
+        // Remaining phases (ANALYSIS, TRANSFORM, FINALIZE, PERSIST) execute after loop exits
         /* ================= ANALYSIS (DEEP) ================= */
         if (this.canExecutePhase("analysis")) {
             {
@@ -300,52 +374,6 @@ export function persistTaskData(context, taskId, db, logLine) {
     db.prepare(`UPDATE tasks SET ${setClause}, updated_at = ? WHERE id = ?`).run(...Object.values(fieldsToUpdate), now, taskId);
     logLine("TASK", "persistTaskData", undefined, `task ${taskId} updated with run data`);
 }
-/**
- * Ensure executionControl exists and constraints are correctly set
- */
-export function ensureExecutionControl(context) {
-    var _a;
-    context.executionControl ?? (context.executionControl = {
-        mode: "transform",
-        rationale: "Default execution mode",
-        confidence: 1,
-        constraints: {
-            allowAnalysis: true,
-            allowPlanning: true,
-            allowFileWrites: false
-        }
-    });
-    const mode = context.executionControl.mode;
-    switch (mode) {
-        case "explain":
-            context.executionControl.constraints = {
-                allowAnalysis: false,
-                allowPlanning: false,
-                allowFileWrites: false
-            };
-            break;
-        case "analyze":
-            context.executionControl.constraints = {
-                allowAnalysis: true,
-                allowPlanning: true,
-                allowFileWrites: false
-            };
-            break;
-        case "transform":
-            context.executionControl.constraints = {
-                allowAnalysis: true,
-                allowPlanning: true,
-                allowFileWrites: true
-            };
-            break;
-        default:
-            (_a = context.executionControl).constraints ?? (_a.constraints = {
-                allowAnalysis: true,
-                allowPlanning: true,
-                allowFileWrites: false
-            });
-    }
-}
 /**
  * Ensure global_state, project, and task exist for this repo.
  * Returns the created taskId

package/dist/agents/evidenceVerifierStep.js

@@ -0,0 +1,141 @@
+// File: src/modules/evidenceVerifierStep.ts
+import fs from "fs";
+import { logInputOutput } from "../utils/promptLogHelper.js";
+/**
+ * Purpose:
+ * Deterministic evidence verification.
+ * - Scans candidate files line-by-line for exact or heuristic matches to the query.
+ * - Checks for filename matches to the query (dominant signal).
+ * - Optionally checks for top-level function/class names in query.
+ * - Populates context.analysis.fileAnalysis.
+ * - Does NOT make execution decisions, update scope, or plan transformations.
+ * - Strictly Axis 3: Certainty.
+ */
+export const evidenceVerifierStep = {
+    name: "evidenceVerifier",
+    description: "Deterministic evidence-first scan over candidate files to populate fileAnalysis, with filename dominance.",
+    groups: ["analysis"],
+    run: async (input) => {
+        var _a, _b;
+        const query = input.query ?? "";
+        const context = input.context;
+        if (!context?.analysis) {
+            throw new Error("[evidenceVerifier] context.analysis is required.");
+        }
+        (_a = context.analysis).fileAnalysis ?? (_a.fileAnalysis = {});
+        const candidatePaths = [
+            ...(context.analysis.focus?.relevantFiles ?? []),
+            ...(context.workingFiles?.map(f => f.path) ?? []),
+        ];
+        const uniquePaths = Array.from(new Set(candidatePaths));
+        if (!uniquePaths.length) {
+            console.warn("[evidenceVerifier] No candidate files to scan.");
+            return { query, data: {} };
+        }
+        const filesWithEvidence = [];
+        // ----------------- Parse query for targets -----------------
+        const sentenceRegex = /['"`](.+?)['"`]/g;
+        const sentenceTargets = [];
+        let match;
+        while ((match = sentenceRegex.exec(query)) !== null) {
+            sentenceTargets.push(match[1]);
+        }
+        const filenameTargets = query.split(/\s+/).filter(w => w.match(/\.(ts|js|tsx)$/));
+        const symbolTargets = [];
+        const symbolRegex = /\b([A-Z]\w+|[a-z]\w+)\(\)/g;
+        let symMatch;
+        while ((symMatch = symbolRegex.exec(query)) !== null) {
+            symbolTargets.push(symMatch[1]);
+        }
+        const mode = context.executionControl?.mode ?? "transform";
+        const allowAnalysis = context.executionControl?.constraints?.allowAnalysis ?? (mode !== "explain");
+        const allowWrites = context.executionControl?.constraints?.allowFileWrites ?? (mode === "transform");
+        // ----------------- Process each file -----------------
+        for (const path of uniquePaths) {
+            let code = null;
+            try {
+                code = fs.readFileSync(path, "utf-8");
+            }
+            catch (err) {
+                console.warn(`[evidenceVerifier] Failed to read ${path}: ${err.message}`);
+            }
+            const lines = code?.split("\n") ?? [];
+            const evidenceItems = [];
+            const matchedLines = [];
+            // Sentence & Symbol evidence
+            lines.forEach((line, idx) => {
+                sentenceTargets.forEach(target => {
+                    if (line.includes(target)) {
+                        evidenceItems.push({
+                            claim: `Line contains the target sentence: "${target}"`,
+                            excerpt: line,
+                            span: { startLine: idx + 1, endLine: idx + 1 },
+                            confidence: 1,
+                        });
+                        matchedLines.push(line);
+                    }
+                });
+                symbolTargets.forEach(sym => {
+                    if (line.includes(`function ${sym}`) || line.includes(`class ${sym}`)) {
+                        evidenceItems.push({
+                            claim: `Line contains target symbol: "${sym}"`,
+                            excerpt: line,
+                            span: { startLine: idx + 1, endLine: idx + 1 },
+                            confidence: 0.9,
+                        });
+                        matchedLines.push(line);
+                    }
+                });
+            });
+            // Filename-level evidence
+            const fileName = path.split("/").pop() ?? "";
+            if (filenameTargets.includes(fileName)) {
+                evidenceItems.push({
+                    claim: `Filename matches query target: "${fileName}"`,
+                    excerpt: "",
+                    span: { startLine: 0, endLine: 0 },
+                    confidence: 1,
+                });
+            }
+            // ----------------- Force focus files as relevant -----------------
+            const isFocusFile = context.analysis.focus?.relevantFiles?.includes(path) ?? false;
+            const isRelevant = isFocusFile || evidenceItems.length > 0;
+            context.analysis.fileAnalysis[path] = {
+                ...context.analysis.fileAnalysis[path],
+                intent: isRelevant ? "relevant" : "irrelevant",
+                relevance: isRelevant
+                    ? `${evidenceItems.length} evidence item(s) match the query${isFocusFile ? " (focus file forced relevant)" : ""}`
+                    : "No matching evidence found",
+                role: "primary",
+                action: { isRelevant, shouldModify: isRelevant && allowAnalysis && allowWrites },
+                proposedChanges: {
+                    summary: isRelevant ? "Evidence found in file" : "No evidence",
+                    scope: isRelevant ? "minor" : "none",
+                    targets: matchedLines,
+                    rationale: isFocusFile ? "Focus file forced relevant even without explicit evidence" : undefined,
+                },
+                risks: [],
+                evidence: evidenceItems,
+            };
+            if (isRelevant)
+                filesWithEvidence.push(path);
+        }
+        // ----------------- Update focus after processing -----------------
+        if (filesWithEvidence.length > 0) {
+            (_b = context.analysis).focus ?? (_b.focus = { relevantFiles: [] });
+            context.analysis.focus.relevantFiles = filesWithEvidence;
+            for (const path of uniquePaths) {
+                if (!filesWithEvidence.includes(path)) {
+                    context.analysis.fileAnalysis[path] = {
+                        ...context.analysis.fileAnalysis[path],
+                        intent: "irrelevant",
+                        action: { ...context.analysis.fileAnalysis[path]?.action, isRelevant: false },
+                    };
+                }
+            }
+        }
+        const output = { query, data: { fileAnalysis: context.analysis.fileAnalysis } };
+        logInputOutput("evidenceVerifier", "output", output.data);
+        return output;
+    },
+};

package/dist/agents/infoPlanGenStep.js

@@ -27,9 +27,12 @@ export const infoPlanGen = {
         const missingFiles = Array.isArray(context.analysis.focus?.missingFiles)
             ? context.analysis.focus.missingFiles
             : [];
-        if (missingFiles.length === 0) {
+        const analysis = context.analysis;
+        const needsDiscovery = analysis?.routingDecision?.decision === "needs-info" ||
+            analysis?.scopeType === "repo-wide";
+        if (!needsDiscovery && missingFiles.length === 0) {
             context.analysis.planSuggestion = { plan: { steps: [] } };
-            logInputOutput('infoPlanGen', 'output', { steps: [] });
+            logInputOutput("infoPlanGen", "output", { steps: [] });
             return;
         }
         // --------------------------------------------------

package/dist/agents/readinessGateStep.js

@@ -1,52 +1,45 @@
+// File: src/modules/readinessGateStep.ts
 import { generate } from '../lib/generate.js';
 import { logInputOutput } from '../utils/promptLogHelper.js';
-function logRoutingDecision(context) {
-    logInputOutput('readinessGateStep', 'output', {
-        routingDecision: context.analysis?.routingDecision,
-        focus: context.analysis?.focus,
-        fileAnalysis: context.analysis?.fileAnalysis,
-    });
-}
 export const readinessGateStep = {
     name: 'readinessGate',
+    description: 'Determines if there is sufficient evidence to safely proceed with analysis or transformation.',
+    groups: ['analysis'],
     requires: ['userQuery', 'intent'],
-    produces: ['analysis.routingDecision'],
+    produces: ['analysis.readiness'],
     async run(context) {
-        var _a, _b;
+        var _a, _b, _c, _d, _e;
         context.analysis || (context.analysis = {});
         (_a = context.analysis).focus || (_a.focus = { relevantFiles: [], missingFiles: [], rationale: '' });
         (_b = context.analysis).fileAnalysis || (_b.fileAnalysis = {});
+        (_c = context.analysis).readiness || (_c.readiness = { decision: 'not-ready', confidence: 0, rationale: '' });
         const focus = context.analysis.focus;
         const fileAnalysis = context.analysis.fileAnalysis;
-        // ================= CHECK EVIDENCE =================
+        // ---------------- EVIDENCE COLLECTION ----------------
         const relevantFiles = Object.entries(fileAnalysis)
             .filter(([_, fa]) => fa.intent === 'relevant')
-            .map(([path, _]) => path);
-        const irrelevantFiles = Object.entries(fileAnalysis)
-            .filter(([_, fa]) => fa.intent === 'irrelevant')
-            .map(([path, _]) => path);
+            .map(([path]) => path);
         const missingFiles = focus.missingFiles ?? [];
-        // Fast path: no relevant files, evidence indicates info is missing
+        // Deterministic short-circuit: nothing relevant or missing files
         if (relevantFiles.length === 0 || missingFiles.length > 0) {
-            context.analysis.routingDecision = {
-                decision: 'needs-info',
-                rationale: `No relevant evidence found or missing files: ${missingFiles.join(', ')}`,
-                confidence: 0.9,
+            context.analysis.readiness = {
+                decision: 'not-ready',
+                confidence: 0.95,
+                rationale: `No relevant files or missing files detected: ${missingFiles.join(', ')}`,
             };
-            logRoutingDecision(context);
+            logOutput(context);
             return;
         }
-        // Evidence-based classification
-        // Build simple summary for model
+        // ---------------- SUMMARIZE EVIDENCE FOR LLM ----------------
         const evidenceSummary = relevantFiles
             .map(path => {
             const fa = fileAnalysis[path];
             const claims = fa.evidence?.map(e => `- ${e.claim}`).join('\n') ?? '';
-            return `File: ${path}\nRole: ${fa.role}\nRelevance: ${fa.relevance}\nClaims:\n${claims}`;
+            return `File: ${path}\nRole: ${fa.role}\nClaims:\n${claims}`;
         })
             .join('\n\n');
         const prompt = `
-You are a routing classifier. Your task is to determine if the agent has sufficient evidence to answer the user's query.
+You are a focused evidence assessor. Do NOT invent new facts. Only reason about the evidence given.
 
 User query:
 ${context.initContext?.userQuery}
@@ -54,48 +47,72 @@ ${context.initContext?.userQuery}
 Evidence from analyzed files:
 ${evidenceSummary}
 
-Decide ONE of the following:
-
-HAS-INFO:
-- Sufficient evidence exists in the analyzed files.
-- All required information is present to answer the user's query.
-
-NEEDS-INFO:
-- Insufficient evidence or missing critical files.
-- Additional information acquisition must run.
+Instruction:
+- Decide whether there is sufficient evidence to proceed safely with analysis or transformation.
+- Return a JSON object EXACTLY in this format:
 
-Return ONLY the label (HAS-INFO or NEEDS-INFO) and optionally a short rationale.
+{
+  "decision": "ready" | "not-ready",
+  "confidence": 0.0-1.0,
+  "rationale": "Concise explanation based only on the evidence provided."
+}
 `.trim();
         try {
-            const genInput = {
-                query: context.initContext?.userQuery ?? '',
-                content: prompt,
-            };
+            const genInput = { query: context.initContext?.userQuery ?? '', content: prompt };
             const genOutput = await generate(genInput);
             const raw = String(genOutput.data ?? '').trim();
             logInputOutput('readinessGateStep raw', 'output', raw);
-            const extractedText = raw.replace(/^(HAS-INFO|NEEDS-INFO):?\s*/i, '').trim();
-            const modelDecision = raw.toUpperCase().startsWith('HAS-INFO') ? 'has-info' : 'needs-info';
+            // Attempt to parse JSON from LLM
+            let modelDecision;
+            try {
+                modelDecision = JSON.parse(raw);
+            }
+            catch {
+                modelDecision = {
+                    decision: 'not-ready',
+                    confidence: 0.5,
+                    rationale: 'Failed to parse model output; assuming not-ready.',
+                };
+            }
+            // Merge deterministic info with LLM summary
             const combinedRationale = [
-                `Evidence-based routing: ${relevantFiles.length} relevant files, ${irrelevantFiles.length} irrelevant files.`,
-                extractedText ? `Model: ${extractedText}` : null,
+                `Evidence-based: ${relevantFiles.length} relevant file(s).`,
+                modelDecision.rationale,
             ]
                 .filter(Boolean)
-                .join('\n');
-            context.analysis.routingDecision = {
-                decision: modelDecision,
+                .join(' ');
+            context.analysis.readiness = {
+                decision: modelDecision.decision,
+                confidence: modelDecision.confidence,
                 rationale: combinedRationale,
-                confidence: modelDecision === 'has-info' ? 0.85 : 0.9,
             };
-            logRoutingDecision(context);
+            // ---------------- DOCS-ONLY FILES ----------------
+            // If executionControl.docsOnly is true, mark relevant files as modifiable
+            const docsOnly = context.executionControl?.constraints?.docsOnly ?? false;
+            if (docsOnly && context.analysis.readiness.decision === 'ready') {
+                for (const path of relevantFiles) {
+                    (_d = context.analysis.fileAnalysis)[path] || (_d[path] = { action: {}, intent: 'relevant' });
+                    (_e = context.analysis.fileAnalysis[path]).action || (_e.action = {});
+                    context.analysis.fileAnalysis[path].action.shouldModify = true;
+                }
+            }
+            logOutput(context);
         }
         catch (err) {
             console.warn('⚠️ readinessGateStep failed:', err);
-            context.analysis.routingDecision = {
-                decision: 'needs-info',
-                rationale: 'readinessGateStep encountered an internal error.',
+            context.analysis.readiness = {
+                decision: 'not-ready',
                 confidence: 0.2,
+                rationale: 'Internal error while determining readiness.',
             };
         }
     },
 };
+// ---------------- HELPER ----------------
+function logOutput(context) {
+    logInputOutput('readinessGateStep', 'output', {
+        readiness: context.analysis?.readiness,
+        focus: context.analysis?.focus,
+        fileAnalysis: context.analysis?.fileAnalysis,
+    });
+}