@cluesmith/codev 3.0.0-rc.1 → 3.0.0-rc.11

package/dist/commands/porch/index.js

@@ -8,11 +8,13 @@ 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';
 // ============================================================================
 // Output Helpers
 // ============================================================================
@@ -23,12 +25,32 @@ 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.
  * @param phaseCheckNames - original check names from the protocol phase
  * @param resolvedChecks - checks after applying overrides (skipped ones absent)
- * @param overrides - raw override map from af-config.json (null if not configured)
+ * @param overrides - raw override map from .codev/config.json (null if not configured)
  */
 function logCheckOverrides(phaseCheckNames, resolvedChecks, overrides) {
     if (!overrides)
@@ -38,7 +60,7 @@ function logCheckOverrides(phaseCheckNames, resolvedChecks, overrides) {
         if (!override)
             continue;
         if (override.skip) {
-            console.log(chalk.yellow(`  ⚠ Check "${name}" skipped (af-config.json)`));
+            console.log(chalk.yellow(`  ⚠ Check "${name}" skipped (.codev/config.json)`));
         }
         else if (override.command || override.cwd) {
             const parts = [];
@@ -57,7 +79,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.`);
@@ -78,7 +100,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('○');
             }
@@ -94,11 +117,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)));
                 }
@@ -145,11 +168,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);
@@ -160,20 +188,20 @@ 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);
     console.log('');
     if (Object.keys(checks).length === 0) {
-        console.log(chalk.dim('  (all checks skipped via af-config.json)'));
+        console.log(chalk.dim('  (all checks skipped via .codev/config.json)'));
         console.log('');
         console.log(chalk.green('RESULT: ALL CHECKS PASSED'));
         console.log(`\n  Run: porch done ${state.id} (to advance)`);
         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)) {
@@ -190,17 +218,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);
@@ -212,12 +273,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('');
@@ -227,44 +288,87 @@ export async function done(workspaceRoot, projectId) {
                 }
             }
             else {
-                console.log(chalk.dim('  (all checks skipped via af-config.json)'));
+                console.log(chalk.dim('  (all checks skipped via .codev/config.json)'));
             }
         }
     }
     // 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)`);
         return;
     }
-    // Enforce 3-way verification for build_verify phases
+    // Enforce verification for build_verify phases (config-aware)
     const verifyConfig = getVerifyConfig(protocol, state.phase);
     if (verifyConfig) {
-        const projectDir = getProjectDir(workspaceRoot, state.id, state.title);
-        const phase = state.current_plan_phase || state.phase;
-        const missingModels = [];
-        for (const model of verifyConfig.models) {
-            // Look for any review file for this model+phase (any iteration)
-            const pattern = path.join(projectDir, `${state.id}-${phase}-iter*-${model}.txt`);
-            const matches = globSync(pattern);
-            if (matches.length === 0) {
-                missingModels.push(model);
+        // Resolve effective models from config (overrides protocol defaults)
+        let effectiveModels = verifyConfig.models;
+        let consultMode = 'normal';
+        try {
+            const config = loadConfig(workspaceRoot);
+            const configModels = config.porch?.consultation?.models;
+            if (configModels !== undefined) {
+                if (configModels === 'none') {
+                    consultMode = 'none';
+                }
+                else if (configModels === 'parent') {
+                    consultMode = 'parent';
+                }
+                else if (Array.isArray(configModels)) {
+                    effectiveModels = configModels;
+                }
+                else if (typeof configModels === 'string') {
+                    effectiveModels = [configModels];
+                }
             }
         }
-        if (missingModels.length > 0) {
-            console.log('');
-            console.log(chalk.red('VERIFICATION REQUIRED'));
-            console.log(`\n  3-way review not completed. Missing: ${missingModels.join(', ')}`);
-            console.log(`\n  Run: porch next ${state.id} (to trigger verification)`);
-            process.exit(1);
+        catch {
+            // Config load failed — use protocol defaults
+        }
+        // "none" mode: skip verification
+        if (consultMode === 'none') {
+            console.log(chalk.dim('  (consultation skipped — configured: none)'));
+        }
+        else if (consultMode === 'parent') {
+            // "parent" mode: verification is handled by architect gate, not review files
+            console.log(chalk.dim('  (consultation delegated to architect — configured: parent)'));
+        }
+        else {
+            // Normal mode: check for review files from effective models
+            const projectDir = getProjectDir(workspaceRoot, state.id, state.title);
+            const phase = state.current_plan_phase || state.phase;
+            const missingModels = [];
+            for (const model of effectiveModels) {
+                // Look for any review file for this model+phase (any iteration)
+                const pattern = path.join(projectDir, `${state.id}-${phase}-iter*-${model}.txt`);
+                const matches = globSync(pattern);
+                if (matches.length === 0) {
+                    missingModels.push(model);
+                }
+            }
+            if (missingModels.length > 0) {
+                console.log('');
+                console.log(chalk.red('VERIFICATION REQUIRED'));
+                console.log(`\n  ${effectiveModels.length}-way review not completed. Missing: ${missingModels.join(', ')}`);
+                console.log(`\n  Run: porch next ${state.id} (to trigger verification)`);
+                process.exit(1);
+            }
         }
     }
-    // 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}`);
@@ -284,13 +388,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.`);
@@ -301,16 +405,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
@@ -319,11 +424,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)));
             }
@@ -347,7 +452,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.`);
@@ -366,22 +471,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();
@@ -400,15 +505,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.`));
@@ -432,12 +556,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('');
@@ -447,22 +571,32 @@ export async function approve(workspaceRoot, projectId, gateName, hasHumanFlag)
             }
         }
         else {
-            console.log(chalk.dim('  (all checks skipped via af-config.json)'));
+            console.log(chalk.dim('  (all checks skipped via .codev/config.json)'));
         }
     }
     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.`);
@@ -479,7 +613,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) {
@@ -502,11 +636,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;
             }
@@ -523,7 +658,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}`);
@@ -536,7 +671,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) {
@@ -572,7 +707,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}`);
@@ -611,8 +746,8 @@ 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);
+function getArtifactForPhase(workspaceRoot, state, resolver) {
+    const baseName = resolveArtifactBaseName(workspaceRoot, state.id, state.title, resolver);
     switch (state.phase) {
         case 'specify':
             return `codev/specs/${baseName}.md`;
@@ -630,6 +765,7 @@ function getArtifactForPhase(workspaceRoot, state) {
 export async function cli(args) {
     const [command, ...rest] = args;
     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);
@@ -655,28 +791,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>');
@@ -691,8 +879,11 @@ 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('  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('');