@kinqs/brainrouter-cli 0.3.5 → 0.3.6

package/dist/cli/commands/workflow.d.ts

@@ -3,4 +3,22 @@
  * Hand-tune imports if the compiler complains.
  */
 import type { CommandContext } from './_context.js';
+/**
+ * Decide whether `/grill-me` should refuse to fire because the current
+ * workflow already has a written `spec.md`. The clarifying pass is meant to
+ * happen BEFORE the spec is committed — once a spec exists, asking again
+ * usually means we're re-litigating answers the user already gave, which
+ * wastes a turn. `--force` is the explicit escape hatch when the user
+ * genuinely wants a second clarifying pass (e.g., scope has drifted).
+ *
+ * Exported helper for unit tests so the guard logic can be exercised
+ * without standing up the whole REPL context. NOT pure: reads workflow
+ * state from disk (`getCurrentWorkflow`, `readArtifact`) and the latter
+ * may mkdirSync the workflow folder as a side effect.
+ */
+export declare function shouldSkipGrillMe(workspaceRoot: string, force: boolean, sessionKey?: string): {
+    skip: boolean;
+    slug?: string;
+    specPath?: string;
+};
 export declare function tryHandleWorkflowCommand(ctx: CommandContext): Promise<boolean>;

package/dist/cli/commands/workflow.js

@@ -7,12 +7,12 @@ import { spawn } from 'node:child_process';
 import { promisify } from 'node:util';
 import { exec } from 'node:child_process';
 import chalk from 'chalk';
-import ora from 'ora';
+import { spinner as makeSpinner } from '../spinner.js';
 import { LOCAL_TOOLS } from '../../agent/agent.js';
 import { callMcpTool } from '../../runtime/mcpUtils.js';
 import { listSessions, reconcileStale } from '../../orchestration/orchestrator.js';
-import { ARTIFACT, artifactRelativePath, createWorkflow, getCurrentWorkflow, listWorkflows, readArtifact, updateWorkflowStatus } from '../../state/workflowArtifacts.js';
-import { clearGoal, completeGoal, editGoal, GoalConflictError, GoalTooLongError, GOAL_TEXT_MAX_CHARS, pauseGoal, readGoal, resumeGoal, setGoal, setGoalBudget, setGoalTokenBudget } from '../../state/goalStore.js';
+import { ARTIFACT, artifactRelativePath, createWorkflow, getCurrentWorkflow, listWorkflows, readArtifact, setCurrentWorkflow, slugify, updateWorkflowStatus, workflowExists } from '../../state/workflowArtifacts.js';
+import { clearGoal, completeGoal, editGoal, formatBudget, GoalConflictError, GoalTooLongError, GOAL_TEXT_MAX_CHARS, pauseGoal, readGoal, resumeGoal, setGoal, setGoalBudget, setGoalTokenBudget } from '../../state/goalStore.js';
 import { askYesNo } from '../cliPrompt.js';
 import { formatPlan, readPlan, updatePlan } from '../../state/taskStore.js';
 import { getLoopState, parseInterval, startLoop, stopLoop } from '../../runtime/loopRunner.js';
@@ -20,6 +20,62 @@ import { SLASH_TO_SKILL } from '../../prompt/skillRunner.js';
 import { buildGoalKickoffPrompt, runSkillByName, runSkillCommand } from './_helpers.js';
 // Promise-flavored exec for case bodies that shell out.
 const execPromise = promisify(exec);
+/**
+ * Decide whether `/grill-me` should refuse to fire because the current
+ * workflow already has a written `spec.md`. The clarifying pass is meant to
+ * happen BEFORE the spec is committed — once a spec exists, asking again
+ * usually means we're re-litigating answers the user already gave, which
+ * wastes a turn. `--force` is the explicit escape hatch when the user
+ * genuinely wants a second clarifying pass (e.g., scope has drifted).
+ *
+ * Exported helper for unit tests so the guard logic can be exercised
+ * without standing up the whole REPL context. NOT pure: reads workflow
+ * state from disk (`getCurrentWorkflow`, `readArtifact`) and the latter
+ * may mkdirSync the workflow folder as a side effect.
+ */
+export function shouldSkipGrillMe(workspaceRoot, force, sessionKey) {
+    if (force)
+        return { skip: false };
+    // 9d-bugfix: scope the "is there an active workflow?" check to THIS
+    // session, not the workspace pointer. A fresh CLI with no session
+    // binding should not be told "plan already exists" just because a
+    // previous CLI ran `/spec` here.
+    const slug = getCurrentWorkflow(workspaceRoot, sessionKey);
+    if (!slug)
+        return { skip: false };
+    const spec = readArtifact(workspaceRoot, slug, ARTIFACT.spec);
+    if (!spec)
+        return { skip: false };
+    return {
+        skip: true,
+        slug,
+        specPath: artifactRelativePath(workspaceRoot, slug, ARTIFACT.spec),
+    };
+}
+/**
+ * Strip a `--force` token from a slash command's arg list, returning the
+ * flag's presence plus the rest. Used by /feature-dev / /spec / /review
+ * to gate Subtask 6's clobber prompt (mirrors /grill-me's --force parsing).
+ */
+function parseForceFlag(args) {
+    return { force: args.includes('--force'), rest: args.filter((a) => a !== '--force') };
+}
+/**
+ * Print the one-line confirmation banner after a successful `/workflow
+ * switch <slug>` (or a no-op switch onto the already-current workflow).
+ * Format: `Switched to workflow <slug> — goal: <status>, iteration N of cap`
+ * — or `goal: —` when no goal is bound.
+ */
+function printWorkflowSwitchConfirmation(slug, goal) {
+    if (!goal) {
+        console.log(chalk.green(`\n✓ Switched to workflow "${slug}" — goal: —.\n`));
+        return;
+    }
+    const statusLabel = goal.status.replace('_', ' ');
+    const iter = goal.budget.iterationsUsed;
+    const cap = formatBudget(goal.budget.maxIterations);
+    console.log(chalk.green(`\n✓ Switched to workflow "${slug}" — goal: ${statusLabel}, iteration ${iter} of ${cap}.\n`));
+}
 export async function tryHandleWorkflowCommand(ctx) {
     const { command, args, agent, mcpClient, config, rl, repl } = ctx;
     // 'ctx' alias to keep references to the old ReplContext name working
@@ -27,7 +83,7 @@ export async function tryHandleWorkflowCommand(ctx) {
     switch (command) {
         case '/skills':
             {
-                const spinner = ora(chalk.gray('Fetching skills...')).start();
+                const spinner = makeSpinner(chalk.gray('Fetching skills...')).start();
                 try {
                     const res = await callMcpTool(mcpClient, 'list_skills', { scope: 'all' });
                     spinner.stop();
@@ -60,7 +116,7 @@ export async function tryHandleWorkflowCommand(ctx) {
                 for (const tool of LOCAL_TOOLS) {
                     console.log(`  ${chalk.cyan(tool.name)} - ${tool.description}`);
                 }
-                const spinner = ora(chalk.gray('Fetching MCP tools...')).start();
+                const spinner = makeSpinner(chalk.gray('Fetching MCP tools...')).start();
                 try {
                     const res = await mcpClient.listTools();
                     spinner.stop();
@@ -84,13 +140,31 @@ export async function tryHandleWorkflowCommand(ctx) {
             }
         case '/plan':
             {
+                // `/plan clear` is the explicit escape hatch when stale items from a
+                // prior workflow are blocking goal_complete (the plan-honesty guard
+                // refuses to complete with open items). `/goal <text>` also
+                // auto-clears, but this lets the user reset without setting a new
+                // goal — useful mid-session if you just abandoned a workflow.
+                if (args[0] === 'clear') {
+                    const before = readPlan(agent.workspaceRoot, agent.sessionKey);
+                    const pendingCount = before.items.filter((i) => i.status !== 'completed').length;
+                    updatePlan(agent.workspaceRoot, { plan: [], explanation: 'cleared by /plan clear' }, agent.sessionKey);
+                    console.log(chalk.green(`\n✓ Plan cleared.`));
+                    if (pendingCount > 0) {
+                        console.log(chalk.gray(`  Removed ${pendingCount} pending item${pendingCount === 1 ? '' : 's'}.\n`));
+                    }
+                    else {
+                        console.log();
+                    }
+                    return true;
+                }
                 const state = readPlan(agent.workspaceRoot, agent.sessionKey);
                 console.log(chalk.bold('\nPlan:'));
                 console.log(chalk.gray(formatPlan(state)));
                 if (state.updatedAt) {
                     console.log(chalk.gray(`Updated: ${state.updatedAt}`));
                 }
-                console.log();
+                console.log(chalk.gray('\nSubcommands: /plan | /plan clear\n'));
                 return true;
             }
         case '/diff':
@@ -138,7 +212,7 @@ export async function tryHandleWorkflowCommand(ctx) {
                 // nothing to commit. The actual commit work goes through ctx.repl.runAgentTurn
                 // so it inherits the normal pipeline: isProcessing locking, goal
                 // continuation, /raw honoring, contradiction surfacing, token summary.
-                const spinner = ora(chalk.gray('Checking git status...')).start();
+                const spinner = makeSpinner(chalk.gray('Checking git status...')).start();
                 let statusOut = '';
                 let diffOut = '';
                 try {
@@ -165,12 +239,16 @@ export async function tryHandleWorkflowCommand(ctx) {
             }
         case '/feature-dev':
             {
-                const feature = args.join(' ').trim();
+                // `--force` accepted but ignored — workflows no longer carry goals,
+                // so there's nothing to "clobber" when starting a new one. Kept on
+                // the CLI for back-compat with any user muscle memory / scripts.
+                const parsed = parseForceFlag(args);
+                const feature = parsed.rest.join(' ').trim();
                 if (!feature) {
                     console.log(chalk.red('\nUsage: /feature-dev <feature description>\n'));
                     break;
                 }
-                const meta = createWorkflow(agent.workspaceRoot, { title: feature, kind: 'feature-dev' });
+                const meta = createWorkflow(agent.workspaceRoot, { title: feature, kind: 'feature-dev', sessionKey: agent.sessionKey });
                 const specPath = artifactRelativePath(agent.workspaceRoot, meta.slug, ARTIFACT.spec);
                 const tasksPath = artifactRelativePath(agent.workspaceRoot, meta.slug, ARTIFACT.tasks);
                 console.log(chalk.gray(`Workflow folder: ${path.dirname(specPath)}`));
@@ -209,14 +287,50 @@ export async function tryHandleWorkflowCommand(ctx) {
                 ].join('\n'), ctx.repl.runAgentTurn);
                 return true;
             }
+        case '/grill-me':
+            {
+                // `/grill-me` doesn't render its own picker — it just nudges the model
+                // (via the CLARIFY-mode overlay in systemPrompt.ts) to ask 2–5
+                // questions back instead of jumping to implementation tools. The
+                // picker UI lives in cliPrompt.ts and stays untouched.
+                const force = args.includes('--force');
+                const task = args.filter((a) => a !== '--force').join(' ').trim();
+                if (!task) {
+                    console.log(chalk.red('\nUsage: /grill-me [--force] <task description>\n'));
+                    return true;
+                }
+                const decision = shouldSkipGrillMe(agent.workspaceRoot, force, agent.sessionKey);
+                if (decision.skip) {
+                    console.log(chalk.yellow(`\nPlan already exists at ${chalk.cyan(decision.specPath)}.`));
+                    console.log(chalk.gray(`  Drop into it with \`/workflow switch ${decision.slug}\`, or use \`/grill-me --force\` to clarify additional details.\n`));
+                    return true;
+                }
+                // Latch activeSkill BEFORE refreshing the system prompt so the
+                // CLARIFY overlay lands in chatHistory[0]. The post-turn hook in
+                // repl.ts clears activeSkill + refreshes again, so the overlay
+                // doesn't bleed into the user's next plain prompt.
+                agent.activeSkill = 'grill-me';
+                agent.refreshSystemPrompt();
+                const prompt = [
+                    '[CLARIFY — grill-me]',
+                    '',
+                    `The user wants help with: ${task}`,
+                    '',
+                    'Before doing anything, ask 2–5 short questions back to disambiguate scope, format, and unstated assumptions. Use `ask_user_choice` for mutually-exclusive options; plain prose for free-form input. End with a one-paragraph "what I\'ll do once you answer" so the user can sanity-check your read of the request.',
+                ].join('\n');
+                ctx.repl.runAgentTurn(prompt);
+                return true;
+            }
         case '/spec':
             {
-                const feature = args.join(' ').trim();
+                // `--force` accepted but ignored — see /feature-dev for rationale.
+                const parsed = parseForceFlag(args);
+                const feature = parsed.rest.join(' ').trim();
                 if (!feature) {
                     console.log(chalk.red('\nUsage: /spec <feature title>\n'));
                     break;
                 }
-                const meta = createWorkflow(agent.workspaceRoot, { title: feature, kind: 'spec' });
+                const meta = createWorkflow(agent.workspaceRoot, { title: feature, kind: 'spec', sessionKey: agent.sessionKey });
                 const specPath = artifactRelativePath(agent.workspaceRoot, meta.slug, ARTIFACT.spec);
                 console.log(chalk.gray(`Workflow folder: ${path.dirname(specPath)}`));
                 await runSkillCommand(agent, mcpClient, '/spec', feature, [
@@ -237,8 +351,11 @@ export async function tryHandleWorkflowCommand(ctx) {
             }
         case '/review':
             {
-                const scope = args.join(' ').trim() || 'current unstaged and staged changes (git diff HEAD)';
-                const meta = createWorkflow(agent.workspaceRoot, { title: `Review: ${scope}`, kind: 'review' });
+                // `--force` accepted but ignored — see /feature-dev for rationale.
+                const parsed = parseForceFlag(args);
+                const scope = parsed.rest.join(' ').trim() || 'current unstaged and staged changes (git diff HEAD)';
+                const reviewTitle = `Review: ${scope}`;
+                const meta = createWorkflow(agent.workspaceRoot, { title: reviewTitle, kind: 'review', sessionKey: agent.sessionKey });
                 const reportPath = artifactRelativePath(agent.workspaceRoot, meta.slug, 'review.md');
                 console.log(chalk.gray(`Workflow folder: ${path.dirname(reportPath)}`));
                 await runSkillCommand(agent, mcpClient, command, scope, [
@@ -268,8 +385,8 @@ export async function tryHandleWorkflowCommand(ctx) {
                 }
                 // Attach this execution turn to the current workflow if there is one, so
                 // walkthrough.md accumulates per workflow rather than per CLI session.
-                const currentSlug = getCurrentWorkflow(agent.workspaceRoot);
-                const slug = currentSlug ?? createWorkflow(agent.workspaceRoot, { title: next.step, kind: 'implement-plan' }).slug;
+                const currentSlug = getCurrentWorkflow(agent.workspaceRoot, agent.sessionKey);
+                const slug = currentSlug ?? createWorkflow(agent.workspaceRoot, { title: next.step, kind: 'implement-plan', sessionKey: agent.sessionKey }).slug;
                 const walkPath = artifactRelativePath(agent.workspaceRoot, slug, ARTIFACT.walkthrough);
                 console.log(chalk.gray(`Workflow folder: ${path.dirname(walkPath)}`));
                 await runSkillCommand(agent, mcpClient, command, `Next plan item: "${next.step}"`, [
@@ -289,7 +406,7 @@ export async function tryHandleWorkflowCommand(ctx) {
             }
         case '/approve':
             {
-                const slug = args[0] || getCurrentWorkflow(agent.workspaceRoot);
+                const slug = args[0] || getCurrentWorkflow(agent.workspaceRoot, agent.sessionKey);
                 if (!slug) {
                     console.log(chalk.red('\nNo current workflow. Use /spec or /feature-dev first, or /approve <slug>.\n'));
                     return true;
@@ -317,6 +434,109 @@ export async function tryHandleWorkflowCommand(ctx) {
                     `6. STOP after the first task and ask whether to continue. Do not silently work through every task — the user approves slices, not the whole batch.`);
                 return true;
             }
+        case '/workflow':
+            {
+                // Subcommands: switch <slug> | pause | resume <slug>
+                // The plural `/workflows` (next case) is the list command. Singular
+                // `/workflow` carries actions on the current pointer / a named slug.
+                const sub = (args[0] ?? '').toLowerCase();
+                if (!sub) {
+                    console.log(chalk.red('\nUsage: /workflow switch <slug> | pause | resume <slug>\n'));
+                    return true;
+                }
+                if (sub === 'switch') {
+                    const rawSlug = (args[1] ?? '').trim();
+                    if (!rawSlug) {
+                        console.log(chalk.red('\nUsage: /workflow switch <slug>\n'));
+                        console.log(chalk.gray('  See /workflows for available slugs.\n'));
+                        return true;
+                    }
+                    // Canonicalize at the entry point. Without this, a user typing
+                    // `/workflow switch My Workflow` (or any title-cased / spaced
+                    // variant) would have the raw string written verbatim into the
+                    // pointer file by setCurrentWorkflow, breaking `w.slug ===
+                    // currentSlug` matching everywhere downstream (the ★ marker
+                    // on /workflows, the "already on it" no-op below, etc.).
+                    const targetSlug = slugify(rawSlug);
+                    if (!workflowExists(agent.workspaceRoot, targetSlug)) {
+                        console.log(chalk.red(`\nNo such workflow: "${rawSlug}".`));
+                        console.log(chalk.gray('  Use /workflows to see what exists, or /spec / /feature-dev to create a new one.\n'));
+                        return true;
+                    }
+                    if (getCurrentWorkflow(agent.workspaceRoot, agent.sessionKey) === targetSlug) {
+                        // Already on it — print the same banner as if we'd switched so
+                        // the user gets a consistent confirmation instead of "no-op".
+                        const g = readGoal(agent.workspaceRoot, agent.sessionKey);
+                        printWorkflowSwitchConfirmation(targetSlug, g);
+                        return true;
+                    }
+                    // Post-decoupling (`/workflow switch` is now pure navigation):
+                    // - Updates the session-scoped workflow pointer so subsequent
+                    //   `/spec` / `/feature-dev` / `/implement-plan` calls in THIS
+                    //   session land artifacts under <targetSlug>'s folder.
+                    // - Does NOT touch the session's goal. Goal is session-scoped
+                    //   runtime state, workflows are durable storage — see
+                    //   goalStore.ts:resolveGoalScope for the design rationale.
+                    // - Earlier migration / conflict prompt (planWorkflowSwitch +
+                    //   migrateSessionGoalToWorkflow + applyMigrationResolution) is
+                    //   gone with the workflow-goal storage that motivated it.
+                    setCurrentWorkflow(agent.workspaceRoot, targetSlug, agent.sessionKey);
+                    agent.refreshSystemPrompt();
+                    const sessionGoal = readGoal(agent.workspaceRoot, agent.sessionKey);
+                    printWorkflowSwitchConfirmation(targetSlug, sessionGoal);
+                    return true;
+                }
+                if (sub === 'pause') {
+                    // `/workflow pause` is now an alias for `/goal pause` — workflows
+                    // don't carry their own goal anymore, so "pause the workflow's
+                    // goal" is just "pause the session's goal" which is what
+                    // pauseGoal already does.
+                    const g = pauseGoal(agent.workspaceRoot, agent.sessionKey);
+                    if (!g) {
+                        console.log(chalk.yellow('\nNo active goal to pause. Use /goal <text> to set one.\n'));
+                        return true;
+                    }
+                    agent.refreshSystemPrompt();
+                    const titlePreview = g.text.length > 60 ? g.text.slice(0, 60) + '…' : g.text;
+                    const slug = getCurrentWorkflow(agent.workspaceRoot, agent.sessionKey);
+                    const wfLabel = slug ? ` (in workflow "${slug}")` : '';
+                    console.log(chalk.yellow(`\n⏸  Paused goal${wfLabel}: ${titlePreview}.`));
+                    console.log(chalk.gray('    /goal resume  to continue this goal later.\n'));
+                    return true;
+                }
+                if (sub === 'resume') {
+                    const rawSlug = (args[1] ?? '').trim();
+                    if (!rawSlug) {
+                        console.log(chalk.red('\nUsage: /workflow resume <slug>\n'));
+                        return true;
+                    }
+                    // Canonicalize for the same reason as /workflow switch (see above).
+                    const targetSlug = slugify(rawSlug);
+                    if (!workflowExists(agent.workspaceRoot, targetSlug)) {
+                        console.log(chalk.red(`\nNo such workflow: "${rawSlug}".\n`));
+                        return true;
+                    }
+                    // `/workflow resume <slug>` is now sugar for "switch artifacts
+                    // to <slug>'s folder, then resume the session's paused goal if
+                    // there is one." Workflows no longer carry goals; resume is a
+                    // goal-only operation that just happens to want a workflow set
+                    // first so artifact writes land in the right place.
+                    setCurrentWorkflow(agent.workspaceRoot, targetSlug, agent.sessionKey);
+                    const resumed = resumeGoal(agent.workspaceRoot, agent.sessionKey);
+                    agent.refreshSystemPrompt();
+                    if (!resumed) {
+                        console.log(chalk.green(`\n▶  Switched to workflow "${targetSlug}" — no paused session goal to resume.\n`));
+                        console.log(chalk.gray(`    Set a fresh /goal here when you're ready.\n`));
+                        return true;
+                    }
+                    console.log(chalk.green(`\n▶  Switched to workflow "${targetSlug}" and resumed goal (${resumed.budget.iterationsUsed}/${formatBudget(resumed.budget.maxIterations)} used). Firing next iteration…\n`));
+                    ctx.repl.runAgentTurn(buildGoalKickoffPrompt(resumed, 'resume'));
+                    return true;
+                }
+                console.log(chalk.red(`\nUnknown /workflow subcommand: "${sub}".`));
+                console.log(chalk.gray('  Subcommands: switch <slug> | pause | resume <slug>\n'));
+                return true;
+            }
         case '/workflows':
             {
                 const workflows = listWorkflows(agent.workspaceRoot);
@@ -325,14 +545,22 @@ export async function tryHandleWorkflowCommand(ctx) {
                     console.log(chalk.yellow('  (none yet — try /spec or /feature-dev)'));
                 }
                 else {
-                    const currentSlug = getCurrentWorkflow(agent.workspaceRoot);
+                    const currentSlug = getCurrentWorkflow(agent.workspaceRoot, agent.sessionKey);
                     for (const w of workflows) {
-                        const marker = w.slug === currentSlug ? chalk.green(' ← current') : '';
+                        // Subtask 4: current-pointer marker is now ★ (the spec's chosen
+                        // glyph). Existing column structure on the first/second lines
+                        // preserved so script readers don't break — the new goal column
+                        // lands at the right of the artifact-markers line. The ★
+                        // reflects THIS session's binding (9d-bugfix), so two CLIs in
+                        // the same workspace can each see their own bound workflow.
+                        const marker = w.slug === currentSlug ? chalk.green(' ★') : '';
                         console.log(`  ${chalk.cyan(w.slug)} [${chalk.gray(w.status)}] ${chalk.gray(w.kind)}${marker}`);
                         console.log(`    ${w.title}`);
                         const hasSpec = !!readArtifact(agent.workspaceRoot, w.slug, ARTIFACT.spec);
                         const hasTasks = !!readArtifact(agent.workspaceRoot, w.slug, ARTIFACT.tasks);
                         const hasWalk = !!readArtifact(agent.workspaceRoot, w.slug, ARTIFACT.walkthrough);
+                        // Workflows are pure artifact folders now — no goal column.
+                        // Goal state lives at session scope only; see goalStore.ts.
                         console.log(chalk.gray(`    spec.md:${hasSpec ? '✓' : '·'}  tasks.md:${hasTasks ? '✓' : '·'}  walkthrough.md:${hasWalk ? '✓' : '·'}`));
                     }
                 }
@@ -358,6 +586,13 @@ export async function tryHandleWorkflowCommand(ctx) {
         case '/goal':
             {
                 const arg = args.join(' ').trim();
+                // Eager session resolve — without this, the FIRST /goal of a new
+                // CLI session writes goal.json under the deterministic fallback
+                // sessionKey, but every later runTurn reads from the
+                // MCP-resolved UUID key. Split-brain: kickoff banner shows the
+                // new goal, the agent reads a stale one from a different file.
+                // ensureInitialized is idempotent and tolerates missing MCP.
+                await agent.ensureInitialized();
                 const ws = agent.workspaceRoot;
                 const sk = agent.sessionKey;
                 const showStatus = (g) => {
@@ -376,7 +611,7 @@ export async function tryHandleWorkflowCommand(ctx) {
                     console.log(chalk.bold('\nGoal'));
                     console.log(`  Status:     ${status}`);
                     console.log(`  Outcome:    ${chalk.cyan(g.text)}`);
-                    console.log(`  Iterations: ${g.budget.iterationsUsed}/${g.budget.maxIterations} used`);
+                    console.log(`  Iterations: ${g.budget.iterationsUsed}/${formatBudget(g.budget.maxIterations)} used`);
                     if (g.budget.maxTokens) {
                         console.log(`  Tokens:     ${(g.budget.tokensUsed ?? 0).toLocaleString()}/${g.budget.maxTokens.toLocaleString()} used`);
                     }
@@ -413,12 +648,8 @@ export async function tryHandleWorkflowCommand(ctx) {
                         console.log(chalk.yellow('\nNo goal to resume.\n'));
                         return true;
                     }
-                    // Resume from paused/blocked/usage_limited — any stale "wrap up"
-                    // steering from the previous final-budget tick must be dropped so
-                    // the resumed turn doesn't see contradictory directives.
-                    agent.removeTaggedSystemMessage('goal-budget-steering');
                     agent.refreshSystemPrompt();
-                    console.log(chalk.green(`\n▶  Goal resumed (${g.budget.iterationsUsed}/${g.budget.maxIterations} used). Starting next iteration…\n`));
+                    console.log(chalk.green(`\n▶  Goal resumed (${g.budget.iterationsUsed}/${formatBudget(g.budget.maxIterations)} used). Starting next iteration…\n`));
                     // Fire the next iteration immediately so the user doesn't have to type
                     // a "proceed" message — the whole point of /goal is autonomy.
                     ctx.repl.runAgentTurn(buildGoalKickoffPrompt(g, 'resume'));
@@ -444,13 +675,8 @@ export async function tryHandleWorkflowCommand(ctx) {
                     if (!g)
                         console.log(chalk.yellow('\nNo goal to update.\n'));
                     else {
-                        // The user just raised (or rarely lowered) the cap — any stale
-                        // wrap-up steering message from the prior tight-budget state is
-                        // now misleading. Drop it; the post-turn loop will re-inject if
-                        // the new state still puts us on a final-budget turn.
-                        agent.removeTaggedSystemMessage('goal-budget-steering');
                         agent.refreshSystemPrompt();
-                        console.log(chalk.green(`\n✓ Iteration budget set to ${g.budget.maxIterations} (${g.budget.iterationsUsed} already used).\n`));
+                        console.log(chalk.green(`\n✓ Iteration budget set to ${formatBudget(g.budget.maxIterations)} (${g.budget.iterationsUsed} already used).\n`));
                     }
                     return true;
                 }
@@ -466,10 +692,6 @@ export async function tryHandleWorkflowCommand(ctx) {
                         console.log(chalk.yellow('\nNo goal to update.\n'));
                         return true;
                     }
-                    // Clear stale wrap-up steering — the budget state just changed
-                    // and any previously-injected "this is your last turn" directive
-                    // would now be misleading.
-                    agent.removeTaggedSystemMessage('goal-budget-steering');
                     agent.refreshSystemPrompt();
                     if (n === 0) {
                         console.log(chalk.green('\n✓ Token budget cleared (iteration cap still applies).\n'));
@@ -529,10 +751,6 @@ export async function tryHandleWorkflowCommand(ctx) {
                             console.log(chalk.yellow('\nNo goal to edit. Set one first with /goal <text>.\n'));
                         }
                         else {
-                            // Any edit may have changed the budget headroom; clear stale
-                            // wrap-up steering so subsequent turns aren't told "this is
-                            // your last turn" with stale data.
-                            agent.removeTaggedSystemMessage('goal-budget-steering');
                             agent.refreshSystemPrompt();
                             console.log(chalk.green(`\n✓ Updated.\n`));
                             showStatus(g);
@@ -553,9 +771,26 @@ export async function tryHandleWorkflowCommand(ctx) {
                 // GoalConflictError and prompt the user before overwriting; a
                 // complete goal is replaced silently (the prior work is done, this
                 // is just starting fresh and the prompt would be noise).
+                //
+                // Inline budget parsing: users naturally write "/goal do X. Budget 3
+                // iterations." and expect that to set the cap. Without parsing, the
+                // goal store falls back to the default (10) and the user is
+                // confused by "Budget: 10" in the kickoff banner. We extract the
+                // first `budget[:\s]+N[\s iterations?]?` pattern from the text,
+                // strip it, and pass N as the maxIterations option.
+                let parsedBudget;
+                let cleanedText = arg;
+                const budgetMatch = arg.match(/\bbudget[:\s]+(\d+)(?:\s*(?:iterations?|turns?|rounds?))?\.?/i);
+                if (budgetMatch) {
+                    const n = Number(budgetMatch[1]);
+                    if (Number.isFinite(n) && n >= 1 && n <= 200) {
+                        parsedBudget = Math.floor(n);
+                        cleanedText = arg.replace(budgetMatch[0], '').replace(/\s{2,}/g, ' ').trim();
+                    }
+                }
                 let goal;
                 try {
-                    goal = setGoal(ws, arg, sk);
+                    goal = setGoal(ws, cleanedText, sk, parsedBudget !== undefined ? { maxIterations: parsedBudget } : undefined);
                 }
                 catch (err) {
                     if (err instanceof GoalTooLongError) {
@@ -567,15 +802,19 @@ export async function tryHandleWorkflowCommand(ctx) {
                         const existing = err.existing;
                         console.log(chalk.yellow(`\n⚠️  A goal is already ${existing.status.replace('_', ' ')}:`));
                         console.log(`     ${chalk.cyan(existing.text)}`);
-                        console.log(`     ${chalk.gray(`${existing.budget.iterationsUsed}/${existing.budget.maxIterations} iterations used`)}`);
+                        console.log(`     ${chalk.gray(`${existing.budget.iterationsUsed}/${formatBudget(existing.budget.maxIterations)} iterations used`)}`);
                         const confirmed = await askYesNo('Replace it with the new objective? (y/N) ', false);
                         if (!confirmed) {
                             console.log(chalk.gray('\nKeeping the current goal. Use `/goal edit text <new>` to change just the wording.\n'));
                             return true;
                         }
-                        // Force-replace.
+                        // Force-replace. Use the cleaned text + parsed budget so the
+                        // inline "Budget N" still applies on the second-try path.
                         try {
-                            goal = setGoal(ws, arg, sk, { force: true });
+                            goal = setGoal(ws, cleanedText, sk, {
+                                force: true,
+                                ...(parsedBudget !== undefined ? { maxIterations: parsedBudget } : {}),
+                            });
                         }
                         catch (err2) {
                             console.log(chalk.red(`\n✗ ${err2?.message ?? err2}\n`));
@@ -588,7 +827,39 @@ export async function tryHandleWorkflowCommand(ctx) {
                 }
                 agent.refreshSystemPrompt();
                 console.log(chalk.green(`\n✓ Goal set: ${chalk.cyan(goal.text)}`));
-                console.log(chalk.gray(`Budget: ${goal.budget.maxIterations} iterations. The CLI will auto-continue after each turn until the agent calls goal_complete / goal_blocked or you /goal pause | clear.`));
+                // Reconcile stale plan items from prior workflows. The plan store is
+                // sessionKey-scoped, so a leftover `[⏳]` from an abandoned
+                // /feature-dev run blocks goal_complete for an unrelated new goal —
+                // the plan-honesty guard correctly refuses, but the user is bitten
+                // by cross-contamination they didn't sign up for. Mirror what a
+                // smart agent does when context shifts: drop the orphan items and
+                // start the new objective with a fresh slate. The cleared items
+                // are printed so it's transparent, not silent.
+                try {
+                    const existingPlan = readPlan(ws, sk);
+                    const orphans = existingPlan.items.filter((i) => i.status !== 'completed');
+                    if (orphans.length > 0) {
+                        updatePlan(ws, { plan: [], explanation: `auto-cleared on new /goal: ${goal.text.slice(0, 80)}` }, sk);
+                        console.log(chalk.yellow(`⚠️  Cleared ${orphans.length} stale plan item${orphans.length === 1 ? '' : 's'} from prior work:`));
+                        for (const it of orphans.slice(0, 5)) {
+                            const mark = it.status === 'in_progress' ? '⏳' : '☐';
+                            console.log(chalk.gray(`     ${mark} ${it.step.slice(0, 100)}`));
+                        }
+                        if (orphans.length > 5)
+                            console.log(chalk.gray(`     …and ${orphans.length - 5} more.`));
+                        console.log(chalk.gray(`   The agent can rebuild a new plan for this goal via update_plan.`));
+                    }
+                }
+                catch {
+                    // Plan reconciliation is best-effort — never fatal to the /goal flow.
+                }
+                {
+                    const b = formatBudget(goal.budget.maxIterations);
+                    const budgetLine = b === 'unlimited'
+                        ? `Budget: unlimited (cap with "/goal budget N" or include "Budget N" in the goal text). The CLI auto-continues until the agent calls goal_complete / goal_blocked or you /goal pause | clear.`
+                        : `Budget: ${b} iterations. The CLI auto-continues after each turn until the agent calls goal_complete / goal_blocked or you /goal pause | clear.`;
+                    console.log(chalk.gray(budgetLine));
+                }
                 console.log(chalk.gray('Kicking off iteration 1 now — type anything to cancel.\n'));
                 // Fire the first turn immediately so /goal doesn't require a "proceed"
                 // follow-up. The post-turn continuation loop in runAgentTurn handles