micro-models-agent 0.39.0 → 0.40.0

package/dist/modules/execution/module.js

@@ -4,29 +4,68 @@ import { PlanTracker } from "./tracker";
 import { StepVerifier } from "./verifier";
 import { StuckDetector } from "./stuck-detector";
 import { Auditor } from "./auditor";
-import { existsSync } from "fs";
+import { PlanStore } from "./plan-store";
+import { checkPlanCoverage } from "./plan-coverage";
+import { getMessageText } from "../../llm/provider";
+import { existsSync, readFileSync } from "fs";
 import { resolve } from "path";
 const STUCK_RECOVERY_COOLDOWN = 5;
+const MAX_PLAN_WARNINGS_BEFORE_BLOCK = 3;
+const FORCE_SKIP_THRESHOLD = 10;
 export class ExecutionModule {
     name = "execution";
     tracker = null;
     verifier;
     stuckDetector;
     auditor;
+    store;
     baseDir;
     lastRecoveryIteration = -STUCK_RECOVERY_COOLDOWN;
-    constructor(baseDir, stuckThreshold = 8) {
+    consecutivePlanWarnings = 0;
+    lastStepId = -1;
+    // How many times the deps-step gate has warned for each step id — used to
+    // escalate from a soft hint to a MUST-update instruction (models otherwise
+    // spin on "install dependencies" steps they invented themselves).
+    depsGateHints = new Map();
+    // Skip the first audit after restoring a plan from disk — gives the user
+    // one chance to change the subject before the audit gate locks in.
+    _auditSkipsRemaining = 0;
+    stuckNotified = false;
+    /**
+     * Deferred <system-summary> messages. Injected by onBeforeTool/onAfterTool
+     * but flushed in onBeforeThink, so they never land between an assistant
+     * tool_call message and its tool results (which breaks message pairing and
+     * buries the warnings the model should react to).
+     */
+    pendingMessages = [];
+    constructor(baseDir, stuckThreshold = 6) {
         this.baseDir = baseDir;
         this.verifier = new StepVerifier(baseDir);
         this.stuckDetector = new StuckDetector(stuckThreshold);
         this.auditor = new Auditor(baseDir);
+        this.store = new PlanStore(baseDir);
     }
     setPlan(plan) {
         this.tracker = new PlanTracker(plan);
+        this.store.saveActive(plan);
+        this._auditSkipsRemaining = 0; // plan explicitly created — arm the audit gate
+    }
+    restorePlan() {
+        const plan = this.store.loadActive();
+        if (!plan)
+            return false;
+        this.tracker = new PlanTracker(plan);
+        // Advance to the first non-done step
+        this.tracker.syncCurrentStep();
+        this._auditSkipsRemaining = 1; // restored plan — one free pass
+        return true;
     }
     getTracker() {
         return this.tracker;
     }
+    getStore() {
+        return this.store;
+    }
     getStuckDetector() {
         return this.stuckDetector;
     }
@@ -37,11 +76,15 @@ export class ExecutionModule {
     async runFinalAudit() {
         if (!this.tracker)
             return null;
+        if (this._auditSkipsRemaining > 0) {
+            this._auditSkipsRemaining--;
+            return null;
+        }
         const plan = this.tracker.getPlan();
         const audit = await this.auditor.audit(plan);
-        const pendingSteps = plan.steps
-            .filter((s) => s.status !== "done" && s.status !== "skipped")
-            .map((s) => `${s.id}. ${s.description}`);
+        const pendingSteps = plan.steps.flatMap((s) => s.status !== "done" && s.status !== "skipped"
+            ? [`${s.id}. ${s.description}`]
+            : []);
         const done = plan.steps.filter((s) => s.status === "done").length;
         const passed = audit.passed && pendingSteps.length === 0;
         return {
@@ -67,24 +110,106 @@ export class ExecutionModule {
         return [
             {
                 name: "plan",
-                description: 'Create, update, show, or abort a multi-step plan. Use "create" at the start of complex tasks. Use "update" after completing each step to track progress. Use "show" to re-print the current plan checklist.',
+                description: 'Create, update, show, abort, list, switch, or re-plan multi-step plans.\n\nActions:\n- create: Start a new plan. Previous active plan is auto-preserved: incomplete → draft, complete → archive.\n- update: Mark step status (done/failed/skipped), or rebuild plan with new steps.\n- show: Print current plan checklist.\n- abort: Archive current plan and clear active slot.\n- list: Show all plans (active, drafts, archived) with progress.\n- switch: Make a different plan active (by plan id).\n- re-plan: Iterative replanning: keep completed steps, replace remaining with new steps.\n\nWrite CONCRETE steps with exact file paths and commands:\n- Specify WHICH files to create with exact paths (e.g. "create src/components/Header.tsx with navigation and logo")\n- Specify WHICH packages to install (e.g. "run npm install react react-dom")\n- Specify WHICH CLI commands to run with exact arguments\n- Each step should include at least one file extension (.ts, .tsx, .json, etc.) or a command verb (install, create, build, run, add, init)\n- Good: "Создать src/components/Header.tsx с навигацией и логотипом"\n- Bad: "Настройка проекта" (too vague — what exactly needs to be configured?)',
                 parameters: {
                     type: "object",
                     properties: {
                         action: {
                             type: "string",
-                            enum: ["create", "update", "show", "abort"],
+                            enum: [
+                                "create",
+                                "update",
+                                "show",
+                                "abort",
+                                "list",
+                                "switch",
+                                "re-plan",
+                            ],
                         },
                         title: { type: "string" },
                         steps: { type: "array", items: { type: "string" } },
                         step: { type: "number" },
                         status: { type: "string", enum: ["done", "failed", "skipped"] },
                         note: { type: "string" },
+                        id: { type: "string", description: "Plan id (for switch action)" },
                     },
                     required: ["action"],
                 },
                 handler: async (_ctx, args) => {
                     const action = String(args.action);
+                    if (action === "list") {
+                        const metas = this.store.listAll();
+                        if (metas.length === 0) {
+                            return { success: true, output: t("plan.list_empty") };
+                        }
+                        const lines = metas.map((m) => {
+                            const icon = m.status === "active"
+                                ? "[*]"
+                                : m.status === "draft"
+                                    ? "[ ]"
+                                    : "[-]";
+                            const namePart = m.name ? ` (${m.name})` : "";
+                            return `${icon} ${m.id}${namePart} — ${m.title}  ${m.doneCount}/${m.stepCount}`;
+                        });
+                        return {
+                            success: true,
+                            output: `${t("plan.list_header")}\n${lines.join("\n")}`,
+                        };
+                    }
+                    if (action === "switch") {
+                        const planId = String(args.id || "");
+                        if (!planId) {
+                            return { success: false, output: t("plan.switch_no_id") };
+                        }
+                        const found = this.store.find(planId);
+                        if (!found) {
+                            return {
+                                success: false,
+                                output: t("plan.not_found", { id: planId }),
+                            };
+                        }
+                        this.preserveActive();
+                        if (found.status === "draft") {
+                            this.store.removeDraft(found.plan.id);
+                        }
+                        else if (found.status === "archived") {
+                            this.store.removeArchived(found.plan.id);
+                        }
+                        this.setPlan(found.plan);
+                        const display = PlanCreator.toPromptBlock(found.plan, 0);
+                        return {
+                            success: true,
+                            output: t("plan.switched", {
+                                id: found.plan.id,
+                                title: found.plan.title,
+                            }),
+                            display,
+                        };
+                    }
+                    if (action === "re-plan") {
+                        if (!this.tracker) {
+                            return { success: false, output: t("plan.no_active") };
+                        }
+                        const newSteps = Array.isArray(args.steps)
+                            ? args.steps.map(String)
+                            : [];
+                        if (newSteps.length === 0) {
+                            return { success: false, output: t("plan.replan_no_steps") };
+                        }
+                        const oldPlan = this.tracker.getPlan();
+                        const replanned = PlanCreator.replan(oldPlan, newSteps, args.title ? String(args.title) : undefined);
+                        const keptCount = replanned.steps.length - newSteps.length;
+                        this.setPlan(replanned);
+                        const display = PlanCreator.toPromptBlock(replanned, keptCount);
+                        return {
+                            success: true,
+                            output: t("plan.replanned", {
+                                kept: String(keptCount),
+                                steps: String(newSteps.length),
+                            }),
+                            display,
+                        };
+                    }
                     if (action === "create") {
                         const title = String(args.title || "Task Plan");
                         const steps = Array.isArray(args.steps)
@@ -93,13 +218,30 @@ export class ExecutionModule {
                         if (steps.length === 0) {
                             return { success: false, output: t("plan.no_steps") };
                         }
-                        const plan = PlanCreator.createPlan(title, steps);
+                        this.preserveActive();
+                        const plan = PlanCreator.createPlan(title, steps, this.baseDir);
                         this.setPlan(plan);
                         const display = PlanCreator.toPromptBlock(plan, 0);
+                        let output = t("plan.created", {
+                            title,
+                            steps: String(steps.length),
+                        });
+                        let displayOut = display;
+                        const taskText = this.getTaskText(_ctx);
+                        if (taskText) {
+                            const { missing } = checkPlanCoverage(taskText, steps);
+                            if (missing.length > 0) {
+                                const warn = t("plan.coverage_warning", {
+                                    missing: missing.join(", "),
+                                });
+                                output += `\n⚠️ ${warn}`;
+                                displayOut = `${display}\n⚠️ ${warn}`;
+                            }
+                        }
                         return {
                             success: true,
-                            output: t("plan.created", { title, steps: String(steps.length) }),
-                            display,
+                            output,
+                            display: displayOut,
                         };
                     }
                     if (action === "show") {
@@ -117,16 +259,42 @@ export class ExecutionModule {
                         this.tracker.updateStepStatus(Number(args.step), args.status || "done");
                         if (args.note)
                             this.tracker.addNote(Number(args.step), String(args.note));
+                        this.tracker.syncCurrentStep();
+                        this.store.saveActive(this.tracker.getPlan());
                         const progress = this.tracker.getProgressString();
                         const display = this.tracker.toPromptBlock();
+                        _ctx.sessionLog?.plan("step-update", `${t("plan.step_status", { step: String(args.step), status: String(args.status || "done") })} | ${progress} | current: step ${this.tracker.getCurrentStepIndex() + 1}`);
                         return {
                             success: true,
                             output: `${t("plan.step_status", { step: String(args.step), status: String(args.status || "done") })}\n${progress}`,
                             display,
                         };
                     }
+                    if (action === "update" &&
+                        Array.isArray(args.steps) &&
+                        args.steps.length > 0 &&
+                        this.tracker) {
+                        const title = String(args.title || this.tracker.getPlan().title);
+                        const steps = args.steps.map(String);
+                        const plan = PlanCreator.createPlan(title, steps, this.baseDir);
+                        this.setPlan(plan);
+                        const display = PlanCreator.toPromptBlock(plan, 0);
+                        const output = t("plan.updated", {
+                            title,
+                            steps: String(steps.length),
+                        });
+                        return {
+                            success: true,
+                            output,
+                            display,
+                        };
+                    }
                     if (action === "abort") {
+                        if (this.tracker) {
+                            this.store.archivePlan(this.tracker.getPlan());
+                        }
                         this.tracker = null;
+                        this.store.clearActive();
                         return { success: true, output: t("plan.aborted") };
                     }
                     if (!this.tracker) {
@@ -172,9 +340,20 @@ export class ExecutionModule {
                         };
                     }
                     if (action === "done") {
+                        if (!currentStep) {
+                            return { success: false, output: t("plan.step_not_found") };
+                        }
+                        this.tracker.updateStepStatus(currentStep.id, "done");
+                        this.tracker.syncCurrentStep();
+                        this.store.saveActive(this.tracker.getPlan());
+                        const display = this.tracker.toPromptBlock();
                         return {
                             success: true,
-                            output: t("todo.marked_done", { count: "1" }),
+                            output: t("plan.step_status", {
+                                step: String(currentStep.id),
+                                status: "done",
+                            }),
+                            display,
                         };
                     }
                     if (action === "list") {
@@ -224,17 +403,64 @@ export class ExecutionModule {
         return {
             name: "execution",
             onBeforeThink: (ctx) => {
-                const step = this.tracker?.getCurrentStep();
-                if (this.tracker && step) {
-                    this.stuckDetector.setCurrentStep(step.id, step.description);
-                    this.stuckDetector.recordIteration(step.id);
+                // Flush deferred <system-summary> messages first so they are visible
+                // to the next model call but never interleave tool messages.
+                if (ctx.contextManager && this.pendingMessages.length > 0) {
+                    for (const m of this.pendingMessages.splice(0)) {
+                        ctx.contextManager.addMessage(m);
+                    }
                 }
-                else {
+                if (this.tracker?.isComplete()) {
+                    // All steps done/skipped — stop counting "no progress" against the
+                    // last step and silence stuck warnings for a finished plan.
                     this.stuckDetector.reset();
+                    this.consecutivePlanWarnings = 0;
+                    this.lastStepId = -1;
+                    this.stuckNotified = false;
+                }
+                else {
+                    const step = this.tracker?.getCurrentStep();
+                    if (this.tracker && step) {
+                        if (step.id !== this.lastStepId) {
+                            this.consecutivePlanWarnings = 0;
+                            this.lastStepId = step.id;
+                            this.stuckNotified = false;
+                        }
+                        this.stuckDetector.setCurrentStep(step.id, step.description);
+                        this.stuckDetector.recordIteration(step.id);
+                    }
+                    else {
+                        this.stuckDetector.reset();
+                        this.consecutivePlanWarnings = 0;
+                        this.lastStepId = -1;
+                        this.stuckNotified = false;
+                        const iter = typeof ctx.iteration === "number" ? ctx.iteration : 0;
+                        if (iter === 3 && !this.tracker && ctx.contextManager) {
+                            ctx.contextManager.addMessage({
+                                role: "user",
+                                content: `<system-summary>You have made 3 tool calls without creating a plan. For any task that involves creating files, installing packages, or multiple steps — you MUST use plan create BEFORE continuing. Use the plan tool now with concrete steps (exact filenames, commands, deliverables). Do NOT make any more write/edit/bash calls until you have a plan.</system-summary>`,
+                            });
+                        }
+                        if (iter >= 6 && !this.tracker && ctx.contextManager) {
+                            ctx.contextManager.addMessage({
+                                role: "user",
+                                content: `<system-summary>STOP. ${iter} iterations without a plan. You MUST call plan create RIGHT NOW. No more tool calls until you create a plan.</system-summary>`,
+                            });
+                        }
+                    }
                 }
                 const stuckReason = this.stuckDetector.getStuckReason();
                 if (stuckReason) {
-                    ctx.logger?.warn(stuckReason);
+                    // Log once per stuck episode instead of spamming every iteration.
+                    const logIt = this.stuckDetector.isStuck()
+                        ? !this.stuckNotified
+                        : true;
+                    if (logIt) {
+                        ctx.logger?.warn(stuckReason);
+                        ctx.sessionLog?.plan("stuck-warning", stuckReason, typeof ctx.iteration === "number" ? ctx.iteration : undefined);
+                        if (this.stuckDetector.isStuck())
+                            this.stuckNotified = true;
+                    }
                 }
                 if (this.stuckDetector.isStuck() ||
                     this.stuckDetector.hasRepetitiveToolCalls()) {
@@ -243,22 +469,80 @@ export class ExecutionModule {
                         STUCK_RECOVERY_COOLDOWN) {
                         const recovery = this.stuckDetector.getRecoveryMessage();
                         if (recovery && ctx.contextManager) {
+                            const lastError = this.stuckDetector.getLastErrorOutput();
+                            const skillHint = lastError
+                                ? "\nIf you have relevant skills available, consider loading one with load_skill for expert guidance."
+                                : "";
+                            // Actionable hints based on actual error output
+                            const actionableHints = this.stuckDetector.getActionableHints();
+                            const actionableHintStr = actionableHints.length > 0
+                                ? `\n${t("exec.hints", { hints: actionableHints.map((h) => `- ${h}`).join("\n") })}`
+                                : "";
+                            // Tool alternative suggestion
+                            const alternative = this.stuckDetector.getToolAlternative();
+                            const altHint = alternative
+                                ? `\nTool "${this.stuckDetector.getLastFailedTool()}" is failing. Try "${alternative}" instead.`
+                                : "";
                             ctx.contextManager.addMessage({
                                 role: "user",
-                                content: `<system-summary>${recovery}</system-summary>`,
+                                content: `<system-summary>${recovery}${skillHint}${actionableHintStr}${altHint}</system-summary>`,
                             });
                         }
+                        const hints = this.stuckDetector.getHints();
+                        if (hints.length > 0 && ctx.contextManager) {
+                            const hintMsg = t("exec.hints", {
+                                hints: hints.map((h) => `- ${h}`).join("\n"),
+                            });
+                            ctx.contextManager.addMessage({
+                                role: "user",
+                                content: `<system-summary>${hintMsg}</system-summary>`,
+                            });
+                        }
+                        this.stuckDetector.recordEscalation();
                         this.lastRecoveryIteration = currentIter;
+                        if (this.stuckDetector.shouldEscalate() && ctx.onMeta) {
+                            const escalation = t("exec.escalation", {
+                                stepId: String(this.tracker?.getCurrentStep()?.id ?? "?"),
+                                description: this.tracker?.getCurrentStep()?.description ?? "",
+                            });
+                            ctx.onMeta(escalation);
+                        }
+                        // Force skip after too many iterations on the same step
+                        if (this.stuckDetector.getIterationsOnCurrentStep() >=
+                            FORCE_SKIP_THRESHOLD &&
+                            ctx.contextManager) {
+                            const step = this.tracker?.getCurrentStep();
+                            ctx.contextManager.addMessage({
+                                role: "user",
+                                content: `<system-summary>STOP. Step ${step?.id ?? "?"} ("${step?.description ?? ""}") took ${this.stuckDetector.getIterationsOnCurrentStep()} iterations with no progress. DO NOT continue this step. Immediately call: plan update step=${step?.id ?? "?"} status=done (if code works despite warnings) OR plan update step=${step?.id ?? "?"} status=skipped note="reason". Do NOT make any other tool calls before updating the plan.</system-summary>`,
+                            });
+                        }
                     }
                 }
             },
-            onBeforeTool: (ctx, call) => {
+            onBeforeTool: (_ctx, call) => {
                 const warning = this.checkPlanAlignment(call);
-                if (warning && ctx.contextManager) {
-                    ctx.contextManager.addMessage({
+                if (warning) {
+                    this.pendingMessages.push({
                         role: "user",
                         content: `<system-summary>${warning}</system-summary>`,
                     });
+                    this.consecutivePlanWarnings++;
+                    if (this.consecutivePlanWarnings >= MAX_PLAN_WARNINGS_BEFORE_BLOCK) {
+                        this.pendingMessages.push({
+                            role: "user",
+                            content: `<system-summary>${t("exec.plan_blocked", { step: String(this.tracker?.getCurrentStep()?.id ?? "?"), max: MAX_PLAN_WARNINGS_BEFORE_BLOCK })}</system-summary>`,
+                        });
+                        // Block with an explicit reason so the model sees WHY the call
+                        // was blocked (executor shows it via tool.blocked_reason).
+                        return t("exec.plan_blocked", {
+                            step: String(this.tracker?.getCurrentStep()?.id ?? "?"),
+                            max: MAX_PLAN_WARNINGS_BEFORE_BLOCK,
+                        });
+                    }
+                }
+                else {
+                    this.consecutivePlanWarnings = 0;
                 }
                 return true;
             },
@@ -271,19 +555,68 @@ export class ExecutionModule {
             },
             onAfterTool: (ctx, call, result) => {
                 if (!result.success) {
-                    this.stuckDetector.recordToolError(call.name);
+                    this.stuckDetector.recordToolError(call.name, result.output);
+                    // Immediately queue an actionable hint on failure (don't wait for
+                    // the stuck threshold). Flushed in onBeforeThink so it does not
+                    // land between tool messages.
+                    const actionableHints = this.stuckDetector.getActionableHints();
+                    const alternative = this.stuckDetector.getToolAlternative();
+                    if (actionableHints.length > 0 || alternative) {
+                        const parts = [...actionableHints];
+                        if (alternative) {
+                            parts.push(`Tool "${call.name}" crashed. Try "${alternative}" instead.`);
+                        }
+                        this.pendingMessages.push({
+                            role: "user",
+                            content: `<system-summary>${t("exec.hints", { hints: parts.map((h) => `- ${h}`).join("\n") })}</system-summary>`,
+                        });
+                    }
                 }
                 else {
                     this.stuckDetector.recordToolSuccess();
+                    // When a bash command runs code successfully, suggest marking step as done
+                    if (call.name === "bash" && result.success) {
+                        const cmd = String(call.arguments?.command ?? "");
+                        if (/node|tsx|ts-node|python|npm\s+(start|test|run)/.test(cmd)) {
+                            this.pendingMessages.push({
+                                role: "user",
+                                content: `<system-summary>The command "${cmd}" completed successfully. If this was testing your code, mark the current step as done via plan update step=N status=done.</system-summary>`,
+                            });
+                        }
+                    }
                 }
-                if (this.tracker &&
-                    result.success &&
+                if (result.success &&
                     (call.name === "write_file" || call.name === "edit_file")) {
-                    this.advancePlanIfStepComplete();
+                    const filePath = call.arguments?.path;
+                    if (filePath) {
+                        this.stuckDetector.recordFileRewrite(filePath);
+                        if (this.stuckDetector.hasExcessiveRewrites()) {
+                            const file = this.stuckDetector.getExcessiveRewriteFile();
+                            const count = this.stuckDetector.getFileRewriteCount(file);
+                            if (ctx.onMeta) {
+                                ctx.onMeta(t("exec.file_rewrite_warning", {
+                                    file: file,
+                                    count: String(count),
+                                }));
+                            }
+                        }
+                    }
+                    this.advancePlanIfStepComplete(ctx.contextManager, ctx.sessionLog);
                 }
             },
         };
     }
+    preserveActive() {
+        if (!this.tracker)
+            return;
+        const plan = this.tracker.getPlan();
+        if (plan.steps.every((s) => s.status === "done" || s.status === "skipped")) {
+            this.store.archivePlan(plan);
+        }
+        else {
+            this.store.saveDraft(plan);
+        }
+    }
     checkPlanAlignment(call) {
         if (!this.tracker)
             return null;
@@ -300,8 +633,6 @@ export class ExecutionModule {
             "grep",
             "file_info",
             "load_skill",
-            "question",
-            "approve",
         ];
         if (allowedAlways.includes(call.name))
             return null;
@@ -312,7 +643,26 @@ export class ExecutionModule {
         const callPaths = (argStr.match(/\b[\w./\\-]+\.[a-z]+/gi) || []).map((p) => p.toLowerCase());
         if (callPaths.length === 0)
             return null;
-        const offPath = callPaths.some((p) => !stepPaths.some((s) => p.includes(s) || s.includes(p)));
+        // Files that already belong to COMPLETED (done/skipped) steps are
+        // legitimate rewrite targets — the agent iterates on them while fixing
+        // LSP/type errors. Blocking those would stop normal bug-fixing.
+        const plan = this.tracker.getPlan();
+        const finishedPaths = new Set();
+        for (const s of plan.steps) {
+            if (s.status === "done" || s.status === "skipped") {
+                const ps = s.description
+                    .match(/\b[\w./\\-]+\.[a-z]+/gi)
+                    ?.map((p) => p.toLowerCase()) ?? [];
+                ps.forEach((p) => finishedPaths.add(p));
+            }
+        }
+        const offPath = callPaths.some((p) => {
+            if (finishedPaths.has(p) ||
+                [...finishedPaths].some((s) => s.includes(p))) {
+                return false;
+            }
+            return !stepPaths.some((s) => p.includes(s) || s.includes(p));
+        });
         if (!offPath)
             return null;
         return t("exec.plan_warning", {
@@ -321,17 +671,109 @@ export class ExecutionModule {
             tool: call.name,
         });
     }
-    advancePlanIfStepComplete() {
+    advancePlanIfStepComplete(contextManager, sessionLog) {
         const step = this.tracker?.getCurrentStep();
         if (!step)
             return;
+        const stepText = step.description.toLowerCase();
         const stepPaths = step.description.match(/\b[\w./\\-]+\.[a-z]+/gi) || [];
+        // Step gate: verify dependencies when mentioned — check BEFORE file paths
+        const isDepsStep = stepText.includes("install") ||
+            stepText.includes("зависим") ||
+            stepText.includes("init") ||
+            stepText.includes("инициализац");
+        if (isDepsStep) {
+            const lockFiles = [
+                "package-lock.json",
+                "bun.lockb",
+                "yarn.lock",
+                "pnpm-lock.yaml",
+                "node_modules",
+                "go.sum",
+                "Cargo.lock",
+                "Pipfile.lock",
+                "poetry.lock",
+                "requirements.txt",
+            ];
+            const hasLockFile = lockFiles.some((f) => existsSync(resolve(this.baseDir, f)));
+            if (!hasLockFile) {
+                if (contextManager) {
+                    const hints = this.depsGateHints.get(step.id) || 0;
+                    this.depsGateHints.set(step.id, hints + 1);
+                    const force = hints >= 1;
+                    const content = force
+                        ? t("exec.step_gate_deps_force", { step: String(step.id) })
+                        : t("exec.step_gate_deps", {
+                            step: String(step.id),
+                            description: step.description,
+                        });
+                    contextManager.addMessage({
+                        role: "user",
+                        content: `<system-summary>${content}</system-summary>`,
+                    });
+                }
+                return;
+            }
+        }
         if (stepPaths.length === 0)
             return;
         const allExist = stepPaths.every((p) => existsSync(resolve(this.baseDir, p)));
-        if (allExist) {
-            this.tracker?.updateStepStatus(step.id, "done");
-            this.tracker?.advance();
+        if (!allExist)
+            return;
+        // Step gate: verify files have content (not empty)
+        const emptyFiles = [];
+        for (const p of stepPaths) {
+            try {
+                const content = readFileSync(resolve(this.baseDir, p), "utf-8");
+                if (content.trim().length < 10) {
+                    emptyFiles.push(p);
+                }
+            }
+            catch {
+                // If we can't read it, rely on existsSync result
+            }
         }
+        if (emptyFiles.length > 0 && contextManager) {
+            contextManager.addMessage({
+                role: "user",
+                content: `<system-summary>${t("exec.step_gate_empty", { step: String(step.id), files: emptyFiles.join(", ") })}</system-summary>`,
+            });
+            return;
+        }
+        // All checks passed — advance
+        this.tracker?.updateStepStatus(step.id, "done");
+        const hadNext = this.tracker?.advance() ?? false;
+        if (this.tracker) {
+            this.store.saveActive(this.tracker.getPlan());
+            sessionLog?.plan("auto-advance", `Step ${step.id} auto-completed | ${this.tracker.getProgressString()} | current: step ${this.tracker.getCurrentStepIndex() + 1}`);
+        }
+        if (contextManager) {
+            const nextStep = hadNext ? this.tracker?.getCurrentStep() : null;
+            const nextMsg = nextStep
+                ? t("exec.step_gate_ok", {
+                    step: String(step.id),
+                    nextStep: String(nextStep.id),
+                    nextDesc: nextStep.description,
+                })
+                : t("exec.step_gate_last", { step: String(step.id) });
+            contextManager.addMessage({
+                role: "user",
+                content: `<system-summary>${nextMsg}</system-summary>`,
+            });
+        }
+    }
+    /**
+     * Extract the original task statement from the first user message in the
+     * conversation history. Used to validate plan coverage against requirements.
+     */
+    getTaskText(ctx) {
+        const manager = ctx?.contextManager;
+        if (!manager)
+            return "";
+        const history = manager.getActiveHistory();
+        const firstUser = history.find((m) => m.role === "user");
+        if (!firstUser)
+            return "";
+        return getMessageText(firstUser.content).trim();
     }
 }