@cluesmith/codev 3.0.0 → 3.0.2

package/dist/commands/porch/index.js

@@ -8,12 +8,14 @@ import * as fs from 'node:fs';
 import * as path from 'node:path';
 import chalk from 'chalk';
 import { globSync } from 'glob';
-import { readState, writeState, createInitialState, findStatusPath, getProjectDir, getStatusPath, resolveProjectId, resolveArtifactBaseName, } from './state.js';
+import { readState, writeStateAndCommit, createInitialState, findStatusPath, getArtifactRoot, getProjectDir, getStatusPath, resolveProjectId, resolveArtifactBaseName, } from './state.js';
 import { loadProtocol, getPhaseConfig, getNextPhase, getPhaseChecks, getPhaseGate, isPhased, isBuildVerify, getVerifyConfig, } from './protocol.js';
-import { findPlanFile, extractPhasesFromFile, getCurrentPlanPhase, getPhaseContent, allPlanPhasesComplete, } from './plan.js';
+import { findPlanFile, extractPlanPhases, getCurrentPlanPhase, getPhaseContent, allPlanPhasesComplete, } from './plan.js';
+import { getResolver, LocalResolver } from './artifacts.js';
 import { runPhaseChecks, formatCheckResults, allChecksPassed, } from './checks.js';
 import { loadCheckOverrides } from './config.js';
 import { loadConfig } from '../../lib/config.js';
+import { version } from '../../version.js';
 // ============================================================================
 // Output Helpers
 // ============================================================================
@@ -24,6 +26,26 @@ function header(text) {
 function section(title, content) {
     return `\n${chalk.bold(title)}:\n${content}`;
 }
+/**
+ * Return a resolver scoped to `artifactRoot` when it differs from the caller's
+ * cwd-rooted resolver. The incoming `resolver` is typically built from
+ * `process.cwd()` (the main workspace), but `findStatusPath` may resolve a
+ * project to a builder worktree under `.builders/`. Checks like `plan_exists`
+ * must read from that worktree, not from the main tree (bugfix #676).
+ *
+ * For the LOCAL backend we rebuild the resolver against `artifactRoot` so file
+ * lookups point at `<artifactRoot>/codev/...`. For other backends (e.g. CLI)
+ * artifact location is already independent of the filesystem, so we keep the
+ * caller's resolver.
+ */
+function scopeResolver(workspaceRoot, artifactRoot, resolver) {
+    if (artifactRoot === workspaceRoot)
+        return resolver;
+    // Only rebuild if the existing resolver is a LocalResolver (path-dependent).
+    if (resolver && !(resolver instanceof LocalResolver))
+        return resolver;
+    return getResolver(workspaceRoot, artifactRoot);
+}
 /**
  * Log override/skip notices before running checks.
  * Only emits output when overrides are actually in use.
@@ -58,7 +80,7 @@ function logCheckOverrides(phaseCheckNames, resolvedChecks, overrides) {
  * porch status <id>
  * Shows current state and prescriptive next steps.
  */
-export async function status(workspaceRoot, projectId) {
+export async function status(workspaceRoot, projectId, resolver) {
     const statusPath = findStatusPath(workspaceRoot, projectId);
     if (!statusPath) {
         throw new Error(`Project ${projectId} not found.\nRun 'porch init' to create a new project.`);
@@ -79,7 +101,8 @@ export async function status(workspaceRoot, projectId) {
         // Status icons
         const icon = (status) => {
             switch (status) {
-                case 'complete': return chalk.green('✓');
+                case 'verified': return chalk.green('✓');
+                case 'complete': return chalk.green('✓'); // backward compat
                 case 'in_progress': return chalk.yellow('►');
                 default: return chalk.gray('○');
             }
@@ -95,11 +118,11 @@ export async function status(workspaceRoot, projectId) {
         if (currentPlanPhase) {
             console.log('');
             console.log(chalk.bold(`CURRENT: ${currentPlanPhase.id} - ${currentPlanPhase.title}`));
-            // Show phase content from plan
-            const planPath = findPlanFile(workspaceRoot, state.id, state.title);
-            if (planPath) {
-                const content = fs.readFileSync(planPath, 'utf-8');
-                const phaseContent = getPhaseContent(content, currentPlanPhase.id);
+            // Show phase content from plan (via resolver if available)
+            const planContent = resolver?.getPlanContent(state.id, state.title)
+                ?? (() => { const p = findPlanFile(workspaceRoot, state.id, state.title); return p ? fs.readFileSync(p, 'utf-8') : null; })();
+            if (planContent) {
+                const phaseContent = getPhaseContent(planContent, currentPlanPhase.id);
                 if (phaseContent) {
                     console.log(section('FROM THE PLAN', phaseContent.slice(0, 500)));
                 }
@@ -146,11 +169,16 @@ export async function status(workspaceRoot, projectId) {
  * porch check <id>
  * Runs the phase checks and reports results.
  */
-export async function check(workspaceRoot, projectId) {
+export async function check(workspaceRoot, projectId, resolver) {
     const statusPath = findStatusPath(workspaceRoot, projectId);
     if (!statusPath) {
         throw new Error(`Project ${projectId} not found.`);
     }
+    // Scope artifact reads + check cwd to the worktree that owns this status.yaml.
+    // `findStatusPath` searches `.builders/*` first; resolver/cwd must match so
+    // checks like `plan_exists` see files in the same worktree (bugfix #676).
+    const artifactRoot = getArtifactRoot(statusPath);
+    const scopedResolver = scopeResolver(workspaceRoot, artifactRoot, resolver);
     const state = readState(statusPath);
     const protocol = loadProtocol(workspaceRoot, state.protocol);
     const overrides = loadCheckOverrides(workspaceRoot);
@@ -161,7 +189,7 @@ export async function check(workspaceRoot, projectId) {
         console.log(chalk.dim('No checks defined for this phase.'));
         return;
     }
-    const checkEnv = { PROJECT_ID: state.id, PROJECT_TITLE: resolveArtifactBaseName(workspaceRoot, state.id, state.title) };
+    const checkEnv = { PROJECT_ID: state.id, PROJECT_TITLE: resolveArtifactBaseName(artifactRoot, state.id, state.title, scopedResolver) };
     console.log('');
     console.log(chalk.bold('RUNNING CHECKS...'));
     logCheckOverrides(phaseCheckNames, checks, overrides);
@@ -174,7 +202,7 @@ export async function check(workspaceRoot, projectId) {
         console.log('');
         return;
     }
-    const results = await runPhaseChecks(checks, workspaceRoot, checkEnv);
+    const results = await runPhaseChecks(checks, artifactRoot, checkEnv, undefined, scopedResolver);
     console.log(formatCheckResults(results));
     console.log('');
     if (allChecksPassed(results)) {
@@ -191,17 +219,50 @@ export async function check(workspaceRoot, projectId) {
  * porch done <id>
  * Advances to next phase if checks pass. Refuses if checks fail.
  */
-export async function done(workspaceRoot, projectId) {
+export async function done(workspaceRoot, projectId, resolver, options) {
     const statusPath = findStatusPath(workspaceRoot, projectId);
     if (!statusPath) {
         throw new Error(`Project ${projectId} not found.`);
     }
     let state = readState(statusPath);
+    // Record-only mode: --pr or --merged writes PR metadata and exits immediately.
+    // Does NOT run checks, does NOT advance the phase, does NOT mark build_complete.
+    if (options?.pr !== undefined) {
+        if (!options.branch)
+            throw new Error('--pr requires --branch <name>');
+        if (!state.pr_history)
+            state.pr_history = [];
+        state.pr_history.push({
+            phase: state.phase,
+            pr_number: options.pr,
+            branch: options.branch,
+            created_at: new Date().toISOString(),
+        });
+        await writeStateAndCommit(statusPath, state, `chore(porch): ${state.id} record PR #${options.pr}`);
+        console.log(chalk.green(`Recorded PR #${options.pr} (branch: ${options.branch}) in pr_history.`));
+        return;
+    }
+    if (options?.merged !== undefined) {
+        if (!state.pr_history)
+            throw new Error(`No PR history found for project ${projectId}`);
+        const entry = state.pr_history.find(e => e.pr_number === options.merged);
+        if (!entry)
+            throw new Error(`PR #${options.merged} not found in pr_history`);
+        entry.merged = true;
+        entry.merged_at = new Date().toISOString();
+        await writeStateAndCommit(statusPath, state, `chore(porch): ${state.id} PR #${options.merged} merged`);
+        console.log(chalk.green(`Marked PR #${options.merged} as merged.`));
+        return;
+    }
     const protocol = loadProtocol(workspaceRoot, state.protocol);
     const overrides = loadCheckOverrides(workspaceRoot);
     const phaseConfig = getPhaseConfig(protocol, state.phase);
     const phaseCheckNames = phaseConfig?.checks ?? [];
     const checks = getPhaseChecks(protocol, state.phase, overrides ?? undefined);
+    // Scope artifact reads + check cwd to the worktree that owns this status.yaml
+    // (bugfix #676 — see check() for rationale).
+    const artifactRoot = getArtifactRoot(statusPath);
+    const scopedResolver = scopeResolver(workspaceRoot, artifactRoot, resolver);
     // Run checks first — but skip if the gate was just approved (approve already ran them)
     if (phaseCheckNames.length > 0) {
         const gate = getPhaseGate(protocol, state.phase);
@@ -213,12 +274,12 @@ export async function done(workspaceRoot, projectId) {
             console.log(chalk.dim('Checks skipped (gate approved <60s ago).'));
         }
         else {
-            const checkEnv = { PROJECT_ID: state.id, PROJECT_TITLE: resolveArtifactBaseName(workspaceRoot, state.id, state.title) };
+            const checkEnv = { PROJECT_ID: state.id, PROJECT_TITLE: resolveArtifactBaseName(artifactRoot, state.id, state.title, scopedResolver) };
             console.log('');
             console.log(chalk.bold('RUNNING CHECKS...'));
             logCheckOverrides(phaseCheckNames, checks, overrides);
             if (Object.keys(checks).length > 0) {
-                const results = await runPhaseChecks(checks, workspaceRoot, checkEnv);
+                const results = await runPhaseChecks(checks, artifactRoot, checkEnv, undefined, scopedResolver);
                 console.log(formatCheckResults(results));
                 if (!allChecksPassed(results)) {
                     console.log('');
@@ -235,7 +296,7 @@ export async function done(workspaceRoot, projectId) {
     // For build_verify phases: mark build as complete for verification
     if (isBuildVerify(protocol, state.phase) && !state.build_complete) {
         state.build_complete = true;
-        writeState(statusPath, state);
+        await writeStateAndCommit(statusPath, state, `chore(porch): ${state.id} ${state.phase} build-complete`);
         console.log('');
         console.log(chalk.green('BUILD COMPLETE. Ready for verification.'));
         console.log(`\n  Run: porch next ${state.id} (to get verification tasks)`);
@@ -298,9 +359,17 @@ export async function done(workspaceRoot, projectId) {
             }
         }
     }
-    // Check for gate
+    // Check for gate — auto-request if not yet requested
     const gate = getPhaseGate(protocol, state.phase);
     if (gate && state.gates[gate]?.status !== 'approved') {
+        // Auto-request the gate if it hasn't been requested yet
+        if (!state.gates[gate]) {
+            state.gates[gate] = { status: 'pending' };
+        }
+        if (!state.gates[gate].requested_at) {
+            state.gates[gate].requested_at = new Date().toISOString();
+            await writeStateAndCommit(statusPath, state, `chore(porch): ${state.id} ${gate} gate-requested`);
+        }
         console.log('');
         console.log(chalk.yellow(`GATE REQUIRED: ${gate}`));
         console.log(`\n  Run: porch gate ${state.id}`);
@@ -320,13 +389,13 @@ export async function done(workspaceRoot, projectId) {
         }
     }
     // Advance to next protocol phase
-    advanceProtocolPhase(workspaceRoot, state, protocol, statusPath);
+    await advanceProtocolPhase(workspaceRoot, state, protocol, statusPath, scopedResolver);
 }
-function advanceProtocolPhase(workspaceRoot, state, protocol, statusPath) {
+async function advanceProtocolPhase(workspaceRoot, state, protocol, statusPath, resolver) {
     const nextPhase = getNextPhase(protocol, state.phase);
     if (!nextPhase) {
-        state.phase = 'complete';
-        writeState(statusPath, state);
+        state.phase = 'verified';
+        await writeStateAndCommit(statusPath, state, `chore(porch): ${state.id} protocol complete`);
         console.log('');
         console.log(chalk.green.bold('🎉 PROTOCOL COMPLETE'));
         console.log(`\n  Project ${state.id} has completed the ${state.protocol} protocol.`);
@@ -337,16 +406,17 @@ function advanceProtocolPhase(workspaceRoot, state, protocol, statusPath) {
     state.iteration = 1;
     // If entering a phased phase (implement), extract plan phases
     if (isPhased(protocol, nextPhase.id)) {
-        const planPath = findPlanFile(workspaceRoot, state.id, state.title);
-        if (planPath) {
-            state.plan_phases = extractPhasesFromFile(planPath);
-            // extractPhasesFromFile already marks first phase as in_progress
+        const planContent = resolver?.getPlanContent(state.id, state.title)
+            ?? (() => { const p = findPlanFile(workspaceRoot, state.id, state.title); return p ? fs.readFileSync(p, 'utf-8') : null; })();
+        if (planContent) {
+            state.plan_phases = extractPlanPhases(planContent);
+            // extractPlanPhases already marks first phase as in_progress
             if (state.plan_phases.length > 0) {
                 state.current_plan_phase = state.plan_phases[0].id;
             }
         }
     }
-    writeState(statusPath, state);
+    await writeStateAndCommit(statusPath, state, `chore(porch): ${state.id} ${nextPhase.id} phase-transition`);
     console.log('');
     console.log(chalk.green(`ADVANCING TO: ${nextPhase.id} - ${nextPhase.name}`));
     // If we just entered implement phase, show phase 1 info and the critical warning
@@ -355,11 +425,11 @@ function advanceProtocolPhase(workspaceRoot, state, protocol, statusPath) {
         const nextPlanPhase = state.plan_phases[1];
         console.log('');
         console.log(chalk.bold(`YOUR TASK: ${firstPhase.id} - "${firstPhase.title}"`));
-        // Show phase content from plan
-        const planPath = findPlanFile(workspaceRoot, state.id, state.title);
-        if (planPath) {
-            const content = fs.readFileSync(planPath, 'utf-8');
-            const phaseContent = getPhaseContent(content, firstPhase.id);
+        // Show phase content from plan (via resolver if available)
+        const planContentForDisplay = resolver?.getPlanContent(state.id, state.title)
+            ?? (() => { const p = findPlanFile(workspaceRoot, state.id, state.title); return p ? fs.readFileSync(p, 'utf-8') : null; })();
+        if (planContentForDisplay) {
+            const phaseContent = getPhaseContent(planContentForDisplay, firstPhase.id);
             if (phaseContent) {
                 console.log(section('FROM THE PLAN', phaseContent.slice(0, 800)));
             }
@@ -383,7 +453,7 @@ function advanceProtocolPhase(workspaceRoot, state, protocol, statusPath) {
  * porch gate <id>
  * Requests human approval for current gate.
  */
-export async function gate(workspaceRoot, projectId) {
+export async function gate(workspaceRoot, projectId, resolver) {
     const statusPath = findStatusPath(workspaceRoot, projectId);
     if (!statusPath) {
         throw new Error(`Project ${projectId} not found.`);
@@ -402,22 +472,22 @@ export async function gate(workspaceRoot, projectId) {
     }
     if (!state.gates[gateName].requested_at) {
         state.gates[gateName].requested_at = new Date().toISOString();
-        writeState(statusPath, state);
+        await writeStateAndCommit(statusPath, state, `chore(porch): ${state.id} ${gateName} gate-requested`);
     }
     console.log('');
     console.log(chalk.bold(`GATE: ${gateName}`));
     console.log('');
     // Show relevant artifact and open it for review
-    const artifact = getArtifactForPhase(workspaceRoot, state);
+    const artifact = getArtifactForPhase(workspaceRoot, state, resolver);
     if (artifact) {
         const fullPath = path.join(workspaceRoot, artifact);
         if (fs.existsSync(fullPath)) {
             console.log(`  Artifact: ${artifact}`);
             console.log('');
             console.log(chalk.cyan('  Opening artifact for human review...'));
-            // Use af open to display in annotation viewer
+            // Use afx open to display in annotation viewer
             const { spawn } = await import('node:child_process');
-            spawn('af', ['open', fullPath], {
+            spawn('afx', ['open', fullPath], {
                 stdio: 'inherit',
                 detached: true
             }).unref();
@@ -436,15 +506,34 @@ export async function gate(workspaceRoot, projectId) {
  * porch approve <id> <gate> --a-human-explicitly-approved-this
  * Human approves a gate. Requires explicit flag to prevent automated approvals.
  */
-export async function approve(workspaceRoot, projectId, gateName, hasHumanFlag) {
+export async function approve(workspaceRoot, projectId, gateName, hasHumanFlag, resolver) {
     const statusPath = findStatusPath(workspaceRoot, projectId);
     if (!statusPath) {
         throw new Error(`Project ${projectId} not found.`);
     }
+    // Scope artifact reads + check cwd to the worktree that owns this status.yaml
+    // (bugfix #676 — see check() for rationale).
+    const artifactRoot = getArtifactRoot(statusPath);
+    const scopedResolver = scopeResolver(workspaceRoot, artifactRoot, resolver);
     const state = readState(statusPath);
+    // Convenience: for verify-approval, auto-complete porch done if build_complete is false
+    if (gateName === 'verify-approval' && state.phase === 'verify' && !state.build_complete) {
+        state.build_complete = true;
+        await writeStateAndCommit(statusPath, state, `chore(porch): ${state.id} verify build-complete (auto)`);
+    }
+    // Auto-create gate entry for upgraded projects (e.g., verify-approval missing after upgrade)
     if (!state.gates[gateName]) {
-        const knownGates = Object.keys(state.gates).join(', ');
-        throw new Error(`Unknown gate: ${gateName}\nKnown gates: ${knownGates || 'none'}`);
+        const protocol = loadProtocol(workspaceRoot, state.protocol);
+        const phaseGate = getPhaseGate(protocol, state.phase);
+        if (phaseGate === gateName) {
+            // Gate belongs to the current phase — initialize it
+            state.gates[gateName] = { status: 'pending', requested_at: new Date().toISOString() };
+            await writeStateAndCommit(statusPath, state, `chore(porch): ${state.id} ${gateName} gate-created (upgrade)`);
+        }
+        else {
+            const knownGates = Object.keys(state.gates).join(', ');
+            throw new Error(`Unknown gate: ${gateName}\nKnown gates: ${knownGates || 'none'}`);
+        }
     }
     if (state.gates[gateName].status === 'approved') {
         console.log(chalk.yellow(`Gate ${gateName} is already approved.`));
@@ -468,12 +557,12 @@ export async function approve(workspaceRoot, projectId, gateName, hasHumanFlag)
     const phaseCheckNames = phaseConfig?.checks ?? [];
     const checks = getPhaseChecks(protocol, state.phase, overrides ?? undefined);
     if (phaseCheckNames.length > 0) {
-        const checkEnv = { PROJECT_ID: state.id, PROJECT_TITLE: resolveArtifactBaseName(workspaceRoot, state.id, state.title) };
+        const checkEnv = { PROJECT_ID: state.id, PROJECT_TITLE: resolveArtifactBaseName(artifactRoot, state.id, state.title, scopedResolver) };
         console.log('');
         console.log(chalk.bold('RUNNING CHECKS...'));
         logCheckOverrides(phaseCheckNames, checks, overrides);
         if (Object.keys(checks).length > 0) {
-            const results = await runPhaseChecks(checks, workspaceRoot, checkEnv);
+            const results = await runPhaseChecks(checks, artifactRoot, checkEnv, undefined, scopedResolver);
             console.log(formatCheckResults(results));
             if (!allChecksPassed(results)) {
                 console.log('');
@@ -488,17 +577,27 @@ export async function approve(workspaceRoot, projectId, gateName, hasHumanFlag)
     }
     state.gates[gateName].status = 'approved';
     state.gates[gateName].approved_at = new Date().toISOString();
-    writeState(statusPath, state);
+    await writeStateAndCommit(statusPath, state, `chore(porch): ${state.id} ${gateName} gate-approved`);
     console.log('');
     console.log(chalk.green(`Gate ${gateName} approved.`));
-    console.log(`\n  Run: porch done ${state.id} (to advance)`);
+    // For verify-approval: auto-advance to terminal state (convenience — one command)
+    // NOTE: The 'verified' state is committed to the builder branch, which may not
+    // be merged back to main. The closed GitHub Issue serves as the canonical "done"
+    // signal on main. State alignment (making status.yaml on main authoritative) is
+    // tracked as future work per spec 653.
+    if (gateName === 'verify-approval') {
+        await advanceProtocolPhase(workspaceRoot, state, protocol, statusPath, resolver);
+    }
+    else {
+        console.log(`\n  Run: porch done ${state.id} (to advance)`);
+    }
     console.log('');
 }
 /**
  * porch rollback <id> <phase>
  * Rewinds project to an earlier phase, clearing downstream gates and resetting build state.
  */
-export async function rollback(workspaceRoot, projectId, targetPhase) {
+export async function rollback(workspaceRoot, projectId, targetPhase, resolver) {
     const statusPath = findStatusPath(workspaceRoot, projectId);
     if (!statusPath) {
         throw new Error(`Project ${projectId} not found.`);
@@ -515,7 +614,7 @@ export async function rollback(workspaceRoot, projectId, targetPhase) {
     const currentIndex = protocol.phases.findIndex(p => p.id === state.phase);
     const targetIndex = protocol.phases.findIndex(p => p.id === targetPhase);
     // Handle completed projects (phase not in protocol phases array)
-    if (state.phase === 'complete') {
+    if (state.phase === 'verified' || state.phase === 'complete') {
         // Allow rollback from complete state to any valid phase
     }
     else if (currentIndex === -1) {
@@ -538,11 +637,12 @@ export async function rollback(workspaceRoot, projectId, targetPhase) {
     state.iteration = 1;
     state.build_complete = false;
     state.history = [];
-    // If rolling back to a phased phase, re-extract plan phases from plan file
+    // If rolling back to a phased phase, re-extract plan phases
     if (isPhased(protocol, targetPhase)) {
-        const planPath = findPlanFile(workspaceRoot, state.id, state.title);
-        if (planPath) {
-            state.plan_phases = extractPhasesFromFile(planPath);
+        const planContent = resolver?.getPlanContent(state.id, state.title)
+            ?? (() => { const p = findPlanFile(workspaceRoot, state.id, state.title); return p ? fs.readFileSync(p, 'utf-8') : null; })();
+        if (planContent) {
+            state.plan_phases = extractPlanPhases(planContent);
             if (state.plan_phases.length > 0) {
                 state.current_plan_phase = state.plan_phases[0].id;
             }
@@ -559,7 +659,7 @@ export async function rollback(workspaceRoot, projectId, targetPhase) {
         state.plan_phases = [];
         state.current_plan_phase = null;
     }
-    writeState(statusPath, state);
+    await writeStateAndCommit(statusPath, state, `chore(porch): ${state.id} rollback ${previousPhase} → ${targetPhase}`);
     console.log('');
     console.log(chalk.green(`ROLLED BACK: ${previousPhase} → ${targetPhase}`));
     console.log(`  Project: ${state.id}`);
@@ -572,7 +672,7 @@ export async function rollback(workspaceRoot, projectId, targetPhase) {
  * Initialize a new project.
  *
  * Idempotent: if status.yaml already exists, preserves it and reports
- * current state. This supports `af spawn --resume` where the builder
+ * current state. This supports `afx spawn --resume` where the builder
  * may re-run `porch init` after a session restart.
  */
 export async function init(workspaceRoot, protocolName, projectId, projectName) {
@@ -608,7 +708,7 @@ export async function init(workspaceRoot, protocolName, projectId, projectName)
         return;
     }
     const state = createInitialState(protocol, projectId, projectName, workspaceRoot);
-    writeState(statusPath, state);
+    await writeStateAndCommit(statusPath, state, `chore(porch): ${state.id} init ${protocolName}`);
     console.log('');
     console.log(chalk.green(`Project initialized: ${projectId}-${projectName}`));
     console.log(`  Protocol: ${protocolName}`);
@@ -647,8 +747,77 @@ function getNextAction(state, protocol) {
     }
     return `Complete the phase work, then run: porch done ${state.id}`;
 }
-function getArtifactForPhase(workspaceRoot, state) {
-    const baseName = resolveArtifactBaseName(workspaceRoot, state.id, state.title);
+/**
+ * porch pending
+ * List all projects with gates awaiting human approval.
+ * Scans both the local workspace and any builder worktrees under .builders/*.
+ */
+export async function pending(workspaceRoot) {
+    const seen = new Set(); // dedupe by status.yaml path
+    const results = [];
+    // Build the list of project directories to scan: main + every builder worktree.
+    const projectsDirs = [path.join(workspaceRoot, 'codev', 'projects')];
+    const buildersDir = path.join(workspaceRoot, '.builders');
+    if (fs.existsSync(buildersDir)) {
+        for (const wt of fs.readdirSync(buildersDir, { withFileTypes: true })) {
+            if (!wt.isDirectory())
+                continue;
+            projectsDirs.push(path.join(buildersDir, wt.name, 'codev', 'projects'));
+        }
+    }
+    for (const projectsDir of projectsDirs) {
+        if (!fs.existsSync(projectsDir))
+            continue;
+        for (const entry of fs.readdirSync(projectsDir, { withFileTypes: true })) {
+            if (!entry.isDirectory())
+                continue;
+            const statusPath = path.join(projectsDir, entry.name, 'status.yaml');
+            if (!fs.existsSync(statusPath))
+                continue;
+            const realPath = fs.realpathSync(statusPath);
+            if (seen.has(realPath))
+                continue;
+            seen.add(realPath);
+            let state;
+            try {
+                state = readState(statusPath);
+            }
+            catch {
+                continue; // skip corrupted status files
+            }
+            for (const [gateName, gateStatus] of Object.entries(state.gates)) {
+                if (gateStatus?.status === 'pending' && gateStatus.requested_at) {
+                    results.push({
+                        id: state.id,
+                        title: state.title,
+                        phase: state.phase,
+                        gate: gateName,
+                        requested_at: gateStatus.requested_at,
+                        statusPath,
+                    });
+                }
+            }
+        }
+    }
+    console.log('');
+    if (results.length === 0) {
+        console.log(chalk.dim('No gates pending approval.'));
+        console.log('');
+        return;
+    }
+    // Sort oldest-first so the longest-waiting gates surface at the top.
+    results.sort((a, b) => (a.requested_at ?? '').localeCompare(b.requested_at ?? ''));
+    console.log(chalk.bold(`${results.length} gate${results.length === 1 ? '' : 's'} pending approval:`));
+    console.log('');
+    for (const r of results) {
+        console.log(`  ${chalk.cyan(r.id)} ${chalk.dim('—')} ${r.title}`);
+        console.log(`    phase: ${r.phase}  gate: ${chalk.yellow(r.gate)}  requested: ${r.requested_at}`);
+        console.log(chalk.dim(`    approve: porch approve ${r.id} ${r.gate} --a-human-explicitly-approved-this`));
+        console.log('');
+    }
+}
+function getArtifactForPhase(workspaceRoot, state, resolver) {
+    const baseName = resolveArtifactBaseName(workspaceRoot, state.id, state.title, resolver);
     switch (state.phase) {
         case 'specify':
             return `codev/specs/${baseName}.md`;
@@ -665,7 +834,14 @@ function getArtifactForPhase(workspaceRoot, state) {
 // ============================================================================
 export async function cli(args) {
     const [command, ...rest] = args;
+    // Handle --version / -v before any project resolution — version output
+    // must work from any directory and never require a project context.
+    if (command === '--version' || command === '-v') {
+        console.log(version);
+        return;
+    }
     const workspaceRoot = process.cwd();
+    const resolver = getResolver(workspaceRoot);
     // Auto-detect project ID for commands that need it
     function getProjectId(provided) {
         const { id, source } = resolveProjectId(provided, process.cwd(), workspaceRoot);
@@ -679,6 +855,9 @@ export async function cli(args) {
     }
     try {
         switch (command) {
+            case 'pending':
+                await pending(workspaceRoot);
+                break;
             case 'next': {
                 const { next: porchNext } = await import('./next.js');
                 const result = await porchNext(workspaceRoot, getProjectId(rest[0]));
@@ -691,28 +870,80 @@ export async function cli(args) {
                 process.exit(1);
                 break;
             case 'status':
-                await status(workspaceRoot, getProjectId(rest[0]));
+                await status(workspaceRoot, getProjectId(rest[0]), resolver);
                 break;
             case 'check':
-                await check(workspaceRoot, getProjectId(rest[0]));
+                await check(workspaceRoot, getProjectId(rest[0]), resolver);
                 break;
-            case 'done':
-                await done(workspaceRoot, getProjectId(rest[0]));
+            case 'done': {
+                const doneOpts = {};
+                const prIdx = rest.indexOf('--pr');
+                const brIdx = rest.indexOf('--branch');
+                const mergedIdx = rest.indexOf('--merged');
+                if (prIdx !== -1) {
+                    const val = parseInt(rest[prIdx + 1], 10);
+                    if (!Number.isInteger(val) || val <= 0)
+                        throw new Error('--pr requires a positive integer PR number');
+                    doneOpts.pr = val;
+                }
+                if (brIdx !== -1) {
+                    if (!rest[brIdx + 1] || rest[brIdx + 1].startsWith('--'))
+                        throw new Error('--branch requires a branch name');
+                    doneOpts.branch = rest[brIdx + 1];
+                }
+                if (mergedIdx !== -1) {
+                    const val = parseInt(rest[mergedIdx + 1], 10);
+                    if (!Number.isInteger(val) || val <= 0)
+                        throw new Error('--merged requires a positive integer PR number');
+                    doneOpts.merged = val;
+                }
+                if (doneOpts.pr !== undefined && doneOpts.merged !== undefined) {
+                    throw new Error('--pr and --merged are mutually exclusive');
+                }
+                const hasRecordFlags = doneOpts.pr !== undefined || doneOpts.merged !== undefined;
+                // For project ID: use first positional arg, or fall back to auto-detection
+                const projectIdArg = rest[0] && !rest[0].startsWith('--') ? rest[0] : undefined;
+                await done(workspaceRoot, getProjectId(projectIdArg), resolver, hasRecordFlags ? doneOpts : undefined);
                 break;
+            }
             case 'gate':
-                await gate(workspaceRoot, getProjectId(rest[0]));
+                await gate(workspaceRoot, getProjectId(rest[0]), resolver);
                 break;
             case 'approve':
                 if (!rest[0] || !rest[1])
                     throw new Error('Usage: porch approve <id> <gate> --a-human-explicitly-approved-this');
                 const hasHumanFlag = rest.includes('--a-human-explicitly-approved-this');
-                await approve(workspaceRoot, rest[0], rest[1], hasHumanFlag);
+                await approve(workspaceRoot, rest[0], rest[1], hasHumanFlag, resolver);
                 break;
             case 'rollback':
                 if (!rest[0] || !rest[1])
                     throw new Error('Usage: porch rollback <id> <phase>');
-                await rollback(workspaceRoot, rest[0], rest[1]);
+                await rollback(workspaceRoot, rest[0], rest[1], resolver);
+                break;
+            case 'verify': {
+                const verifyProjectId = rest[0] && !rest[0].startsWith('--') ? rest[0] : undefined;
+                const skipIdx = rest.indexOf('--skip');
+                if (skipIdx === -1)
+                    throw new Error('Usage: porch verify <id> --skip "reason"');
+                const skipReason = rest[skipIdx + 1];
+                if (!skipReason || skipReason.startsWith('--'))
+                    throw new Error('--skip requires a reason');
+                const pid = getProjectId(verifyProjectId);
+                const sp = findStatusPath(workspaceRoot, pid);
+                if (!sp)
+                    throw new Error(`Project ${pid} not found.`);
+                const st = readState(sp);
+                if (st.phase !== 'verify') {
+                    throw new Error(`porch verify --skip can only be used in the verify phase (current: ${st.phase}). The PR must be merged first.`);
+                }
+                st.phase = 'verified';
+                st.context = { ...st.context, verify_skip_reason: skipReason };
+                await writeStateAndCommit(sp, st, `chore(porch): ${st.id} verify skipped: ${skipReason}`);
+                console.log('');
+                console.log(chalk.green(`VERIFIED (skipped): ${st.id}`));
+                console.log(`  Reason: ${skipReason}`);
                 break;
+            }
             case 'init':
                 if (!rest[0] || !rest[1] || !rest[2]) {
                     throw new Error('Usage: porch init <protocol> <id> <name>');
@@ -727,11 +958,18 @@ export async function cli(args) {
                 console.log('  status [id]              Show current state and instructions');
                 console.log('  check [id]               Run checks for current phase');
                 console.log('  done [id]                Signal build complete (validates checks, advances)');
+                console.log('  done [id] --pr N --branch NAME   Record PR creation (no phase advancement)');
+                console.log('  done [id] --merged N             Mark PR as merged (no phase advancement)');
                 console.log('  gate [id]                Request human approval');
+                console.log('  pending                  List all gates awaiting approval across projects');
                 console.log('  approve <id> <gate> --a-human-explicitly-approved-this');
+                console.log('  verify <id> --skip "reason"      Skip verification and mark as verified');
                 console.log('  rollback <id> <phase>    Rewind project to an earlier phase');
                 console.log('  init <protocol> <id> <name>  Initialize a new project');
                 console.log('');
+                console.log('Flags:');
+                console.log('  --version, -v            Print porch (codev) version');
+                console.log('');
                 console.log('Project ID is auto-detected from worktree path or when exactly one project exists.');
                 console.log('');
                 process.exit(command && command !== '--help' && command !== '-h' ? 1 : 0);