writethevision 7.0.7 → 7.0.9

package/README.md

@@ -296,9 +296,34 @@ The Masterbuilder reads your vision document and coordinates the artisans.
 
 ## Vision Runner (Ralphy-Style)
 
-`wtv run` can also execute a project vision directly by generating a `PRD.md` (checklist) and iterating until all tasks are complete.
+`wtv run` (with no arguments) launches the **Vision Runner**, an autonomous loop that executes a project vision until completion.
 
-It maintains a `progress.txt` checkpoint log and, by default, creates a single git commit and pushes once at the end.
+It is designed for "Ralphy-style" execution: give it a vision, and it runs until the vision is a reality.
+
+### The Workflow
+
+1. **Pick a Vision**: WTV finds `VISION.md` (root) or files in `vision/*.md` and asks you to select one.
+2. **Generate Plan**: It prompts the engine (OpenCode, Codex, or Claude) to generate a detailed `PRD.md` with a task checklist.
+3. **Execute Loop**:
+   - Reads `PRD.md` to find the next unchecked task.
+   - Creates a focused prompt for the engine.
+   - Runs the engine to implement the task.
+   - Verifies the task was marked completed in `PRD.md`.
+   - Appends a checkpoint to `progress.txt`.
+   - Repeats until all tasks are done.
+4. **Finalize**: Creates a single git commit ("feat: complete <vision>") and pushes to remote (unless disabled).
+
+### File Contracts
+
+The Vision Runner relies on strict file conventions:
+
+- **Input**:
+  - `VISION.md` (or `vision/*.md`): The source of truth for *what* to build.
+- **Artifacts**:
+  - `PRD.md`: The execution checklist. Must use `- [ ]` for incomplete and `- [x]` for complete tasks. The runner stops when no `- [ ]` remain.
+  - `progress.txt`: An append-only log of every completed task with timestamps.
+
+### Usage
 
 ```bash
 wtv run

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "writethevision",
-  "version": "7.0.7",
+  "version": "7.0.9",
   "description": "Write The Vision (WTV): vision-driven development with the Habakkuk workflow. 10 agents + 21 skills for Claude Code, Codex CLI, and OpenCode.",
   "author": "Christopher Hogg",
   "license": "MIT",

package/src/cli.js

@@ -1256,15 +1256,23 @@ async function checkForUpdates() {
 
     try {
         const packageName = getPackageName();
+        const checkEveryRun = process.env.WTV_UPDATE_CHECK_EVERY_RUN === '1';
         const notifier = updateNotifier({
             pkg: {
                 name: packageName,
                 version: getVersion(),
             },
-            updateCheckInterval: 1000 * 60 * 60 * 24 * 7,
+            updateCheckInterval: checkEveryRun ? Number.POSITIVE_INFINITY : 1000 * 60 * 60 * 24 * 7,
             shouldNotifyInNpmScript: false,
         });
 
+        if (checkEveryRun) {
+            try {
+                notifier.update = await notifier.fetchInfo();
+            } catch {
+            }
+        }
+
         const update = notifier.update;
         if (!update) return;
 
@@ -1290,7 +1298,7 @@ Or run latest once:
             },
         });
 
-        const shouldPrompt = process.stdin.isTTY && process.env.WTV_NO_AUTO_UPDATE !== '1' && !process.env.CI;
+        const shouldPrompt = process.stdin.isTTY && process.env.WTV_NO_AUTO_UPDATE !== '1' && !process.env.CI && !checkEveryRun;
         if (!shouldPrompt) return;
 
         const isDevCheckout = existsSync(join(PACKAGE_ROOT, '.git'));
@@ -3281,13 +3289,12 @@ async function runEngine(engine, promptText) {
     throw new Error(`Unsupported engine: ${engine}`);
 }
 
-function ensureProgressHeader(progressPath, { visionPath, engine, startSha }) {
+export function ensureProgressHeader(progressPath, { visionPath, engine, startSha }) {
     if (!existsSync(progressPath)) {
         writeFileSync(progressPath, '');
     }
 
     const existing = readFileSync(progressPath, 'utf8');
-    if (existing.trim().length > 0) return;
 
     const startedAt = new Date().toISOString();
     const header = [
@@ -3296,16 +3303,19 @@ function ensureProgressHeader(progressPath, { visionPath, engine, startSha }) {
         `Vision: ${visionPath}`,
         `Engine: ${engine}`,
         startSha ? `Start SHA: ${startSha}` : `Start SHA: (not a git repo)`,
+        startSha ? `Rollback hint: git reset --hard ${startSha}` : '',
         '',
     ].join('\n');
 
-    writeFileSync(progressPath, header);
+    if (existing.trim().length > 0) {
+        writeFileSync(progressPath, existing.trimEnd() + '\n\n' + header);
+    } else {
+        writeFileSync(progressPath, header);
+    }
 }
 
-async function generatePrdFromVision({ engine, visionPath, prdPath }) {
-    const visionContent = readFileSync(visionPath, 'utf8');
-
-    const promptText = `You are generating a PRD for a software project.
+export function generatePrdPrompt(visionContent) {
+    return `You are generating a PRD for a software project.
 
 Input vision document:
 ---
@@ -3322,6 +3332,12 @@ Requirements:
 - Do NOT implement any code yet.
 - Do NOT run git commit or git push.
 - Output is the updated files on disk (PRD.md).`;
+}
+
+async function generatePrdFromVision({ engine, visionPath, prdPath }) {
+    const visionContent = readFileSync(visionPath, 'utf8');
+
+    const promptText = generatePrdPrompt(visionContent);
 
     const code = await runEngine(engine, promptText);
     if (code !== 0) {
@@ -3338,7 +3354,7 @@ Requirements:
     }
 }
 
-async function runVisionTaskIteration({ engine, prdPath, progressPath, taskText, noTests, noLint }) {
+export async function runVisionTaskIteration({ engine, prdPath, progressPath, taskText, noTests, noLint, _runEngine }) {
     const promptText = `You are an autonomous coding agent executing a PRD.
 
 Files:
@@ -3350,7 +3366,7 @@ Task to implement (ONLY this task):
 
 Rules:
 - Implement ONLY the task above.
-- Update PRD.md: change that exact task from '- [ ]' to '- [x]'.
+- Update PRD.md: change that exact task from '- [ ]' to '- [x]' (lowercase x).
 - Append a short checkpoint entry to progress.txt.
 - Do NOT run git commit.
 - Do NOT run git push.
@@ -3366,7 +3382,25 @@ Stop after completing this one task.`;
 
     const progressBefore = existsSync(progressPath) ? readFileSync(progressPath, 'utf8') : '';
 
-    const code = await runEngine(engine, promptText);
+    const workDir = dirname(prdPath);
+    const gitProbe = spawnSync('git', ['rev-parse', '--is-inside-work-tree'], {
+        cwd: workDir,
+        encoding: 'utf8',
+        stdio: ['ignore', 'pipe', 'pipe'],
+    });
+    const hasGit = gitProbe.status === 0 && String(gitProbe.stdout || '').trim() === 'true';
+    const statusBefore = hasGit
+        ? String(
+            spawnSync('git', ['status', '--porcelain'], {
+                cwd: workDir,
+                encoding: 'utf8',
+                stdio: ['ignore', 'pipe', 'pipe'],
+            }).stdout || '',
+        )
+        : '';
+
+    const runFn = _runEngine || runEngine;
+    const code = await runFn(engine, promptText);
     if (code !== 0) {
         throw new Error(`Engine exited with code ${code}`);
     }
@@ -3374,10 +3408,61 @@ Stop after completing this one task.`;
     const afterPrd = readFileSync(prdPath, 'utf8');
     const afterUnchecked = countUncheckedPrdTasks(afterPrd);
 
-    const stillUnchecked = afterPrd.includes(`- [ ] ${taskText}`);
-    const nowChecked = afterPrd.includes(`- [x] ${taskText}`);
+    const escaped = taskText.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+    const uncheckedRe = new RegExp(`^\\s*- \\[ \\]\\s+${escaped}\\s*$`, 'm');
+    const checkedRe = new RegExp(`^\\s*- \\[[xX]\\]\\s+${escaped}\\s*$`, 'm');
+
+    let stillUnchecked = uncheckedRe.test(afterPrd);
+    let nowChecked = checkedRe.test(afterPrd);
 
     if (stillUnchecked || (!nowChecked && afterUnchecked >= beforeUnchecked)) {
+        const statusAfter = hasGit
+            ? String(
+                spawnSync('git', ['status', '--porcelain'], {
+                    cwd: workDir,
+                    encoding: 'utf8',
+                    stdio: ['ignore', 'pipe', 'pipe'],
+                }).stdout || '',
+            )
+            : '';
+
+        // Best-effort repair: if the engine changed files but forgot PRD.md, run a
+        // follow-up pass that ONLY updates PRD.md and progress.txt.
+        const hasAnyChanges = hasGit ? statusAfter !== statusBefore : false;
+        if (hasAnyChanges) {
+            const repairPrompt = `You previously completed this PRD task but did NOT update the checklist.
+
+Fix it now by editing ONLY these files:
+- PRD.md
+- progress.txt
+
+Rules:
+- Do NOT change any other files.
+- In PRD.md, find the exact checkbox line for this task and change '- [ ]' to '- [x]':
+  ${taskText}
+- Append a single new line to progress.txt: "[ISO_TIMESTAMP] Completed: ${taskText}"
+- Then stop.`;
+
+            const repairCode = await runFn(engine, repairPrompt);
+            if (repairCode !== 0) {
+                throw new Error(`Engine exited with code ${repairCode}`);
+            }
+
+            const repairedPrd = readFileSync(prdPath, 'utf8');
+            const repairedUnchecked = countUncheckedPrdTasks(repairedPrd);
+            stillUnchecked = uncheckedRe.test(repairedPrd);
+            nowChecked = checkedRe.test(repairedPrd);
+
+            if (!stillUnchecked && (nowChecked || repairedUnchecked < beforeUnchecked)) {
+                const repairedProgress = existsSync(progressPath) ? readFileSync(progressPath, 'utf8') : '';
+                if (repairedProgress === progressBefore) {
+                    const stamp = new Date().toISOString();
+                    writeFileSync(progressPath, repairedProgress + `\n[${stamp}] Completed: ${taskText}\n`);
+                }
+                return;
+            }
+        }
+
         throw new Error('PRD.md was not updated to mark the task complete');
     }
 
@@ -3388,6 +3473,71 @@ Stop after completing this one task.`;
     }
 }
 
+export function finalizeVisionRun({
+    prdPath,
+    visionPath,
+    hasGit,
+    startSha,
+    noPush,
+    _runGit,
+    _readFileSync,
+    _countUncheckedPrdTasks,
+    _getCurrentBranch
+}) {
+    const runGitFn = _runGit || runGit;
+    const readFileSyncFn = _readFileSync || readFileSync;
+    const countUncheckedFn = _countUncheckedPrdTasks || countUncheckedPrdTasks;
+    const getCurrentBranchFn = _getCurrentBranch || getCurrentBranch;
+
+    if (!hasGit) {
+        console.log(`\n  ${c.green}${sym.check}${c.reset} PRD complete (no git repo detected).\n`);
+        return;
+    }
+
+    const prdFinal = readFileSyncFn(prdPath, 'utf8');
+    if (countUncheckedFn(prdFinal) > 0) {
+        console.log(`\n  ${c.yellow}${sym.warn}${c.reset} PRD still has remaining tasks; skipping commit/push.\n`);
+        return;
+    }
+
+    const visionName = basename(visionPath).replace(/\.md$/, '');
+    const commitMessage = `feat: run vision (${visionName})`;
+
+    const addRes = runGitFn(['add', '-A']);
+    if (addRes.status !== 0) {
+        console.log(`\n  ${c.red}${sym.cross}${c.reset} git add failed.\n`);
+        return;
+    }
+
+    const statusRes = runGitFn(['status', '--porcelain']);
+    if (statusRes.status === 0 && String(statusRes.stdout || '').trim().length === 0) {
+        console.log(`\n  ${c.green}${sym.check}${c.reset} Nothing to commit.\n`);
+        return;
+    }
+
+    const commitRes = runGitFn(['commit', '-m', commitMessage]);
+    if (commitRes.status !== 0) {
+        console.log(`\n  ${c.red}${sym.cross}${c.reset} git commit failed.\n`);
+        return;
+    }
+
+    if (!noPush) {
+        const pushRes = runGitFn(['push']);
+        if (pushRes.status !== 0) {
+            const branch = getCurrentBranchFn();
+            if (branch) {
+                runGitFn(['push', '-u', 'origin', branch]);
+            }
+        }
+    }
+
+    console.log(`\n  ${c.green}${sym.check}${c.reset} Vision complete.`);
+    if (startSha) {
+        console.log(`  Started from: ${c.dim}${startSha}${c.reset}`);
+    }
+    console.log('');
+}
+
 async function visionRunner(opts) {
     const config = loadConfig();
     const interactive = process.stdout.isTTY && process.stdin.isTTY;
@@ -3458,6 +3608,12 @@ async function visionRunner(opts) {
     const hasGit = isGitRepo();
     const startSha = hasGit ? getGitHeadSha() : null;
 
+    if (!hasGit) {
+        console.log(`\n  ${c.yellow}${sym.warn} Warning:${c.reset} Not a git repository. Version control features disabled.\n`);
+    } else if (startSha) {
+        console.log(`\n  ${c.blue}${sym.info} Rollback hint:${c.reset} git reset --hard ${startSha}\n`);
+    }
+
     if (hasGit && !isWorkingTreeClean() && !opts.dryRun) {
         if (!interactive) {
             console.log(`\n  ${c.red}Error:${c.reset} Working tree is not clean (non-interactive mode).\n`);
@@ -3554,53 +3710,13 @@ async function visionRunner(opts) {
         }
     }
 
-    if (!hasGit) {
-        console.log(`\n  ${c.green}${sym.check}${c.reset} PRD complete (no git repo detected).\n`);
-        return;
-    }
-
-    const prdFinal = readFileSync(prdPath, 'utf8');
-    if (countUncheckedPrdTasks(prdFinal) > 0) {
-        console.log(`\n  ${c.yellow}${sym.warn}${c.reset} PRD still has remaining tasks; skipping commit/push.\n`);
-        return;
-    }
-
-    const visionName = basename(visionPath).replace(/\.md$/, '');
-    const commitMessage = `feat: run vision (${visionName})`;
-
-    const addRes = runGit(['add', '-A']);
-    if (addRes.status !== 0) {
-        console.log(`\n  ${c.red}${sym.cross}${c.reset} git add failed.\n`);
-        return;
-    }
-
-    const statusRes = runGit(['status', '--porcelain']);
-    if (statusRes.status === 0 && String(statusRes.stdout || '').trim().length === 0) {
-        console.log(`\n  ${c.green}${sym.check}${c.reset} Nothing to commit.\n`);
-        return;
-    }
-
-    const commitRes = runGit(['commit', '-m', commitMessage]);
-    if (commitRes.status !== 0) {
-        console.log(`\n  ${c.red}${sym.cross}${c.reset} git commit failed.\n`);
-        return;
-    }
-
-    if (!opts.noPush) {
-        const pushRes = runGit(['push']);
-        if (pushRes.status !== 0) {
-            const branch = getCurrentBranch();
-            if (branch) {
-                runGit(['push', '-u', 'origin', branch]);
-            }
-        }
-    }
-
-    console.log(`\n  ${c.green}${sym.check}${c.reset} Vision complete.`);
-    if (startSha) {
-        console.log(`  Started from: ${c.dim}${startSha}${c.reset}`);
-    }
-    console.log('');
+    finalizeVisionRun({
+        prdPath,
+        visionPath,
+        hasGit,
+        startSha,
+        noPush: opts.noPush
+    });
 }
 
 // ============================================================================
@@ -4570,7 +4686,7 @@ function showHelp() {
     console.log(`${pad}  ${c.cyan}vision${c.reset}        Show VISION.md status`);
     console.log(`${pad}  ${c.cyan}log${c.reset}           Show task logs`);
     console.log(`${pad}  ${c.cyan}meet${c.reset}          Meet Paul and the Artisans`);
-    console.log(`${pad}  ${c.cyan}run${c.reset}           Run the vision (PRD loop)`);
+    console.log(`${pad}  ${c.cyan}run${c.reset}           Run the vision (Vision Runner)`);
     console.log(`${pad}  ${c.cyan}help${c.reset}          Show this help\n`);
 
     console.log(`${pad}${c.bold}Agent Commands${c.reset}`);
@@ -4581,12 +4697,17 @@ function showHelp() {
     console.log(`${pad}  ${c.cyan}agents fav${c.reset} <name>   Toggle favorite`);
     console.log(`${pad}  ${c.cyan}agents rm${c.reset} <name>    Remove agent\n`);
 
+    console.log(`${pad}${c.bold}Vision Runner${c.reset}  ${c.dim}"That he may run that readeth it"${c.reset}`);
+    console.log(`${pad}  ${c.cyan}run${c.reset}               Launch Vision Runner (interactive)`);
+    console.log(`${pad}  ${c.cyan}run${c.reset} --vision <f>  Execute specific vision file`);
+    console.log(`${pad}  ${c.cyan}run${c.reset} --resume      Resume existing PRD.md\n`);
+
     console.log(`${pad}${c.bold}Habakkuk Workflow${c.reset}  ${c.dim}"Write the vision, make it plain"${c.reset}`);
     console.log(`${pad}  ${c.cyan}board${c.reset} [--all]        Show kanban board`);
     console.log(`${pad}  ${c.cyan}cry${c.reset} "desc"          Enter a problem or need`);
     console.log(`${pad}  ${c.cyan}wait${c.reset} <id>           Move to waiting (seeking)`);
     console.log(`${pad}  ${c.cyan}vision${c.reset} <id>         Move to vision (answer received)`);
-    console.log(`${pad}  ${c.cyan}run${c.reset} [id]           Run the vision, or move item to run`);
+    console.log(`${pad}  ${c.cyan}run${c.reset} <id>            Move to run (execution started)`);
     console.log(`${pad}  ${c.cyan}worship${c.reset} <id>        Move to worship (retrospective)`);
     console.log(`${pad}  ${c.cyan}note${c.reset} <id> "text"    Add note to item`);
     console.log(`${pad}  ${c.cyan}item${c.reset} <id>           Show item details`);
@@ -4604,6 +4725,18 @@ function showHelp() {
     console.log(`${pad}  ${c.dim}--gemini${c.reset}           Target Gemini CLI`);
     console.log(`${pad}  ${c.dim}--antigravity${c.reset}      Target Antigravity\n`);
 
+    console.log(`${pad}${c.bold}Vision Runner Options${c.reset}`);
+    console.log(`${pad}  ${c.dim}--vision <file>${c.reset}    Input vision file (default: discover)`);
+    console.log(`${pad}  ${c.dim}--engine <name>${c.reset}    Execution engine (opencode|codex|claude)`);
+    console.log(`${pad}  ${c.dim}--resume${c.reset}           Resume existing PRD.md`);
+    console.log(`${pad}  ${c.dim}--regenerate-prd${c.reset}   Force regeneration of PRD.md from vision`);
+    console.log(`${pad}  ${c.dim}--max-iterations <n>${c.reset} Stop after N tasks`);
+    console.log(`${pad}  ${c.dim}--dry-run${c.reset}          Show what would happen without running`);
+    console.log(`${pad}  ${c.dim}--fast${c.reset}             Skip tests and linting`);
+    console.log(`${pad}  ${c.dim}--no-tests${c.reset}         Skip tests`);
+    console.log(`${pad}  ${c.dim}--no-lint${c.reset}          Skip linting`);
+    console.log(`${pad}  ${c.dim}--no-push${c.reset}          Skip git push at end\n`);
+
     console.log(`${pad}${c.bold}Examples${c.reset}`);
     console.log(`${pad}  ${c.green}wtv${c.reset}                          ${c.dim}# Dashboard${c.reset}`);
     console.log(`${pad}  ${c.green}wtv agents${c.reset}                   ${c.dim}# List agents${c.reset}`);

package/src/engine.js

@@ -0,0 +1,109 @@
+import { spawn } from 'child_process';
+
+/**
+ * Base class for AI CLI engine adapters.
+ */
+class EngineAdapter {
+    constructor(cwd = process.cwd()) {
+        this.cwd = cwd;
+    }
+
+    /**
+     * Get the command and arguments for the engine.
+     * @param {string} prompt - The prompt to execute.
+     * @returns {{ command: string, args: string[] }}
+     */
+    getCommand(prompt) {
+        throw new Error('getCommand must be implemented by subclass');
+    }
+
+    /**
+     * Run the engine with the given prompt.
+     * @param {string} prompt - The prompt to execute.
+     * @param {object} options - Options for spawn.
+     * @returns {Promise<number>} - Exit code.
+     */
+    async run(prompt, options = {}) {
+        const { command, args } = this.getCommand(prompt);
+        
+        console.log(`[Engine] Running: ${command} ${args.join(' ')}`);
+
+        return new Promise((resolve, reject) => {
+            const child = spawn(command, args, {
+                cwd: this.cwd,
+                stdio: 'inherit', // Stream output to parent stdout/stderr
+                shell: true,      // Use shell to resolve command paths
+                ...options
+            });
+
+            child.on('error', (err) => {
+                reject(err);
+            });
+
+            child.on('close', (code) => {
+                resolve(code);
+            });
+        });
+    }
+}
+
+/**
+ * Adapter for OpenCode CLI.
+ */
+class OpenCodeEngine extends EngineAdapter {
+    getCommand(prompt) {
+        // Assumption: opencode takes the prompt as a single argument string
+        return {
+            command: 'opencode',
+            args: [prompt]
+        };
+    }
+}
+
+/**
+ * Adapter for Codex CLI.
+ */
+class CodexEngine extends EngineAdapter {
+    getCommand(prompt) {
+        // Assumption: codex takes the prompt as a single argument string
+        return {
+            command: 'codex',
+            args: [prompt]
+        };
+    }
+}
+
+/**
+ * Adapter for Claude Code CLI.
+ */
+class ClaudeEngine extends EngineAdapter {
+    getCommand(prompt) {
+        // Assumption: claude takes the prompt as a single argument string
+        // Note: Check if it needs -p or similar flag
+        return {
+            command: 'claude',
+            args: [prompt]
+        };
+    }
+}
+
+/**
+ * Factory to create the appropriate engine adapter.
+ * @param {string} name - The name of the engine ('opencode', 'codex', 'claude').
+ * @param {string} cwd - Current working directory.
+ * @returns {EngineAdapter}
+ */
+export function createEngine(name, cwd) {
+    switch (name.toLowerCase()) {
+        case 'opencode':
+            return new OpenCodeEngine(cwd);
+        case 'codex':
+            return new CodexEngine(cwd);
+        case 'claude':
+            return new ClaudeEngine(cwd);
+        default:
+            throw new Error(`Unsupported engine: ${name}`);
+    }
+}
+
+export { EngineAdapter, OpenCodeEngine, CodexEngine, ClaudeEngine };