@cluesmith/codev 2.0.0-rc.7 → 2.0.0-rc.70

package/dist/commands/porch/state.js

@@ -1,774 +1,195 @@
 /**
  * Porch State Management
  *
- * Handles project state persistence with:
- * - Pure YAML format (no markdown frontmatter)
- * - Atomic writes (tmp file + fsync + rename)
- * - File locking (flock advisory locking)
- * - Crash recovery
+ * Handles project state persistence with atomic writes.
+ * Fails loudly on any error - no guessing.
  */
 import * as fs from 'node:fs';
 import * as path from 'node:path';
-import { openSync, closeSync, fsyncSync, writeFileSync, renameSync, unlinkSync, readFileSync } from 'node:fs';
-// ============================================================================
-// Constants
-// ============================================================================
-/** Directory for SPIDER project state (relative to project root) */
+import * as yaml from 'js-yaml';
+/** Directory for project state (relative to project root) */
 export const PROJECTS_DIR = 'codev/projects';
-/** Directory for TICK/BUGFIX execution state (relative to project root) */
-export const EXECUTIONS_DIR = 'codev/executions';
-/** Lock timeout in milliseconds */
-const LOCK_TIMEOUT_MS = 5000;
-/** Lock retry interval in milliseconds */
-const LOCK_RETRY_MS = 100;
 // ============================================================================
 // Path Utilities
 // ============================================================================
 /**
- * Get the status file path for a SPIDER project
- */
-export function getProjectStatusPath(projectRoot, projectId, name) {
-    const projectDir = name
-        ? path.join(projectRoot, PROJECTS_DIR, `${projectId}-${name}`)
-        : path.join(projectRoot, PROJECTS_DIR, projectId);
-    return path.join(projectDir, 'status.yaml');
-}
-/**
- * Get the status file path for a TICK/BUGFIX execution
- */
-export function getExecutionStatusPath(projectRoot, protocol, id, name) {
-    const dirName = name ? `${protocol}_${id}_${name}` : `${protocol}_${id}`;
-    return path.join(projectRoot, EXECUTIONS_DIR, dirName, 'status.yaml');
-}
-/**
- * Get the project directory for a SPIDER project
+ * Get the project directory path
  */
 export function getProjectDir(projectRoot, projectId, name) {
-    return name
-        ? path.join(projectRoot, PROJECTS_DIR, `${projectId}-${name}`)
-        : path.join(projectRoot, PROJECTS_DIR, projectId);
-}
-/**
- * Get the worktree path for a protocol execution
- */
-export function getWorktreePath(projectRoot, protocol, id, name) {
-    const dirName = name ? `${protocol}_${id}_${name}` : `${protocol}_${id}`;
-    return path.join(projectRoot, 'worktrees', dirName);
-}
-/**
- * Acquire an advisory lock on a file
- * Creates a .lock file to indicate lock ownership
- */
-export async function acquireLock(filePath) {
-    const lockFile = `${filePath}.lock`;
-    const startTime = Date.now();
-    while (Date.now() - startTime < LOCK_TIMEOUT_MS) {
-        try {
-            // Try to create lock file exclusively
-            const fd = openSync(lockFile, 'wx');
-            // Write our PID for debugging
-            writeFileSync(lockFile, `${process.pid}\n`);
-            return { fd, lockFile };
-        }
-        catch (err) {
-            if (err.code === 'EEXIST') {
-                // Lock file exists, check if stale
-                try {
-                    const stat = fs.statSync(lockFile);
-                    // If lock is older than 60 seconds, consider it stale
-                    if (Date.now() - stat.mtimeMs > 60000) {
-                        unlinkSync(lockFile);
-                        continue;
-                    }
-                }
-                catch {
-                    // Lock file disappeared, retry
-                    continue;
-                }
-                // Wait and retry
-                await new Promise(r => setTimeout(r, LOCK_RETRY_MS));
-            }
-            else {
-                throw err;
-            }
-        }
-    }
-    throw new Error(`Failed to acquire lock on ${filePath} after ${LOCK_TIMEOUT_MS}ms`);
+    return path.join(projectRoot, PROJECTS_DIR, `${projectId}-${name}`);
 }
 /**
- * Release an advisory lock
+ * Get the status.yaml path for a project
  */
-export function releaseLock(lock) {
-    try {
-        closeSync(lock.fd);
-        unlinkSync(lock.lockFile);
-    }
-    catch {
-        // Ignore errors during cleanup
-    }
+export function getStatusPath(projectRoot, projectId, name) {
+    return path.join(getProjectDir(projectRoot, projectId, name), 'status.yaml');
 }
 // ============================================================================
-// YAML Serialization
+// State Operations
 // ============================================================================
 /**
- * Simple YAML serializer for project state
- * Handles our specific data structures without external dependencies
+ * Read project state from status.yaml
+ * Fails loudly if file is missing or corrupted.
  */
-export function serializeState(state) {
-    const lines = [];
-    // Basic fields
-    lines.push(`id: "${state.id}"`);
-    lines.push(`title: "${state.title}"`);
-    lines.push(`protocol: "${state.protocol}"`);
-    lines.push(`state: "${state.current_state}"`);
-    if (state.worktree) {
-        lines.push(`worktree: "${state.worktree}"`);
-    }
-    lines.push('');
-    // Gates
-    lines.push('gates:');
-    if (state.gates && Object.keys(state.gates).length > 0) {
-        for (const [gateId, gateStatus] of Object.entries(state.gates)) {
-            const status = gateStatus.status || 'pending';
-            const requestedAt = gateStatus.requested_at ? `, requested_at: "${gateStatus.requested_at}"` : '';
-            const approvedAt = gateStatus.approved_at ? `, approved_at: "${gateStatus.approved_at}"` : '';
-            lines.push(`  ${gateId}: { status: ${status}${requestedAt}${approvedAt} }`);
-        }
-    }
-    else {
-        lines.push('  # No gates defined');
-    }
-    lines.push('');
-    // Phases (for phased implementation)
-    lines.push('phases:');
-    if (state.phases && Object.keys(state.phases).length > 0) {
-        for (const [phaseId, phaseStatus] of Object.entries(state.phases)) {
-            if (typeof phaseStatus === 'object' && phaseStatus !== null) {
-                const ps = phaseStatus;
-                const status = ps.status || 'pending';
-                const title = ps.title ? `, title: "${ps.title}"` : '';
-                lines.push(`  ${phaseId}: { status: ${status}${title} }`);
-            }
-        }
-    }
-    else {
-        lines.push('  # No phases extracted yet');
-    }
-    lines.push('');
-    // Plan phases (extracted from plan.md)
-    if (state.plan_phases && state.plan_phases.length > 0) {
-        lines.push('plan_phases:');
-        for (const phase of state.plan_phases) {
-            lines.push(`  - id: "${phase.id}"`);
-            lines.push(`    title: "${phase.title}"`);
-            if (phase.description) {
-                lines.push(`    description: "${phase.description.replace(/"/g, '\\"')}"`);
-            }
-        }
-        lines.push('');
+export function readState(statusPath) {
+    if (!fs.existsSync(statusPath)) {
+        throw new Error(`Project not found: ${statusPath}\nRun 'porch init' to create a new project.`);
     }
-    // Consultation attempts (for tracking retries across iterations)
-    if (state.consultation_attempts && Object.keys(state.consultation_attempts).length > 0) {
-        lines.push('consultation_attempts:');
-        for (const [stateKey, count] of Object.entries(state.consultation_attempts)) {
-            lines.push(`  "${stateKey}": ${count}`);
-        }
-        lines.push('');
-    }
-    // Metadata
-    lines.push(`iteration: ${state.iteration || 0}`);
-    lines.push(`started_at: "${state.started_at || new Date().toISOString()}"`);
-    lines.push(`last_updated: "${new Date().toISOString()}"`);
-    lines.push('');
-    // Log
-    lines.push('log:');
-    if (state.log && state.log.length > 0) {
-        for (const entry of state.log) {
-            if (typeof entry === 'string') {
-                lines.push(`  - "${entry}"`);
-            }
-            else if (typeof entry === 'object' && entry !== null) {
-                const logEntry = entry;
-                const ts = logEntry.ts || new Date().toISOString();
-                const event = logEntry.event || 'unknown';
-                let entryLine = `  - ts: "${ts}"`;
-                lines.push(entryLine);
-                lines.push(`    event: "${event}"`);
-                if (logEntry.from)
-                    lines.push(`    from: "${logEntry.from}"`);
-                if (logEntry.to)
-                    lines.push(`    to: "${logEntry.to}"`);
-                if (logEntry.signal)
-                    lines.push(`    signal: "${logEntry.signal}"`);
-            }
-        }
-    }
-    return lines.join('\n') + '\n';
-}
-/**
- * Parse YAML status file into ProjectState
- */
-export function parseState(content) {
-    const state = {
-        gates: {},
-        phases: {},
-        log: [],
-        consultation_attempts: {},
-    };
-    const lines = content.split('\n');
-    let currentSection = '';
-    let currentArrayItem = null;
-    for (const line of lines) {
-        // Skip comments and empty lines
-        if (line.trim().startsWith('#') || line.trim() === '') {
-            continue;
-        }
-        // Reset section if we hit a non-indented line (top-level field)
-        if (currentSection && !line.startsWith(' ') && !line.startsWith('\t')) {
-            // If we have a pending array item, push it before leaving the section
-            if (currentArrayItem) {
-                if (currentSection === 'plan_phases') {
-                    state.plan_phases.push(currentArrayItem);
-                }
-                else if (currentSection === 'log') {
-                    state.log.push(currentArrayItem);
-                }
-                currentArrayItem = null;
-            }
-            currentSection = '';
-        }
-        // Detect section headers
-        if (line.match(/^gates:\s*$/)) {
-            currentSection = 'gates';
-            continue;
-        }
-        if (line.match(/^phases:\s*$/)) {
-            currentSection = 'phases';
-            continue;
-        }
-        if (line.match(/^plan_phases:\s*$/)) {
-            currentSection = 'plan_phases';
-            state.plan_phases = [];
-            continue;
-        }
-        if (line.match(/^log:\s*$/)) {
-            currentSection = 'log';
-            continue;
-        }
-        if (line.match(/^consultation_attempts:\s*$/)) {
-            currentSection = 'consultation_attempts';
-            continue;
-        }
-        // Parse based on section
-        if (currentSection === 'gates') {
-            // Parse: gate_id: { status: pending, requested_at: "..." }
-            const match = line.match(/^\s+(\w+):\s*\{\s*status:\s*(\w+)(?:,\s*requested_at:\s*"([^"]*)")?(?:,\s*approved_at:\s*"([^"]*)")?\s*\}/);
-            if (match) {
-                const [, gateId, status, requestedAt, approvedAt] = match;
-                state.gates[gateId] = {
-                    status: status,
-                    ...(requestedAt && { requested_at: requestedAt }),
-                    ...(approvedAt && { approved_at: approvedAt }),
-                };
-            }
-            continue;
-        }
-        if (currentSection === 'phases') {
-            // Parse: phase_id: { status: pending, title: "..." }
-            const match = line.match(/^\s+(\w+):\s*\{\s*status:\s*(\w+)(?:,\s*title:\s*"([^"]*)")?\s*\}/);
-            if (match) {
-                const [, phaseId, status, title] = match;
-                state.phases[phaseId] = {
-                    status: status,
-                    ...(title && { title }),
-                };
-            }
-            continue;
-        }
-        if (currentSection === 'plan_phases') {
-            // Parse array items
-            if (line.match(/^\s+-\s+id:/)) {
-                if (currentArrayItem) {
-                    state.plan_phases.push(currentArrayItem);
-                }
-                currentArrayItem = {};
-                const idMatch = line.match(/id:\s*"([^"]*)"/);
-                if (idMatch)
-                    currentArrayItem.id = idMatch[1];
-            }
-            else if (line.match(/^\s+title:/)) {
-                const titleMatch = line.match(/title:\s*"([^"]*)"/);
-                if (titleMatch && currentArrayItem)
-                    currentArrayItem.title = titleMatch[1];
-            }
-            else if (line.match(/^\s+description:/)) {
-                const descMatch = line.match(/description:\s*"([^"]*)"/);
-                if (descMatch && currentArrayItem)
-                    currentArrayItem.description = descMatch[1];
-            }
-            continue;
-        }
-        if (currentSection === 'consultation_attempts') {
-            // Parse: "state:key": count
-            const match = line.match(/^\s+"([^"]+)":\s*(\d+)/);
-            if (match) {
-                const [, stateKey, count] = match;
-                state.consultation_attempts[stateKey] = parseInt(count, 10);
-            }
-            continue;
-        }
-        if (currentSection === 'log') {
-            // Parse log entries - simplified
-            if (line.match(/^\s+-\s+ts:/)) {
-                if (currentArrayItem) {
-                    state.log.push(currentArrayItem);
-                }
-                currentArrayItem = {};
-                const tsMatch = line.match(/ts:\s*"([^"]*)"/);
-                if (tsMatch)
-                    currentArrayItem.ts = tsMatch[1];
-            }
-            else if (line.match(/^\s+event:/)) {
-                const eventMatch = line.match(/event:\s*"([^"]*)"/);
-                if (eventMatch && currentArrayItem)
-                    currentArrayItem.event = eventMatch[1];
-            }
-            else if (line.match(/^\s+from:/)) {
-                const fromMatch = line.match(/from:\s*"([^"]*)"/);
-                if (fromMatch && currentArrayItem)
-                    currentArrayItem.from = fromMatch[1];
-            }
-            else if (line.match(/^\s+to:/)) {
-                const toMatch = line.match(/to:\s*"([^"]*)"/);
-                if (toMatch && currentArrayItem)
-                    currentArrayItem.to = toMatch[1];
-            }
-            else if (line.match(/^\s+signal:/)) {
-                const signalMatch = line.match(/signal:\s*"([^"]*)"/);
-                if (signalMatch && currentArrayItem)
-                    currentArrayItem.signal = signalMatch[1];
-            }
-            else if (line.match(/^\s+-\s*"[^"]*"/)) {
-                // Simple string log entry
-                const strMatch = line.match(/^\s+-\s*"([^"]*)"/);
-                if (strMatch)
-                    state.log.push(strMatch[1]);
-            }
-            continue;
+    try {
+        const content = fs.readFileSync(statusPath, 'utf-8');
+        const state = yaml.load(content);
+        // Basic validation
+        if (!state || typeof state !== 'object') {
+            throw new Error('Invalid state file: not an object');
         }
-        // Top-level fields
-        const kvMatch = line.match(/^(\w+):\s*"?([^"\n]*)"?$/);
-        if (kvMatch) {
-            const [, key, value] = kvMatch;
-            switch (key) {
-                case 'id':
-                    state.id = value;
-                    break;
-                case 'title':
-                    state.title = value;
-                    break;
-                case 'protocol':
-                    state.protocol = value;
-                    break;
-                case 'state':
-                    state.current_state = value;
-                    break;
-                case 'worktree':
-                    state.worktree = value;
-                    break;
-                case 'iteration':
-                    state.iteration = parseInt(value, 10);
-                    break;
-                case 'started_at':
-                    state.started_at = value;
-                    break;
-                case 'last_updated':
-                    state.last_updated = value;
-                    break;
-            }
+        if (!state.id || !state.protocol || !state.phase) {
+            throw new Error('Invalid state file: missing required fields (id, protocol, phase)');
         }
+        return state;
     }
-    // Push final array item if exists
-    if (currentArrayItem) {
-        if (currentSection === 'plan_phases') {
-            state.plan_phases.push(currentArrayItem);
-        }
-        else if (currentSection === 'log') {
-            state.log.push(currentArrayItem);
+    catch (err) {
+        if (err instanceof yaml.YAMLException) {
+            throw new Error(`Invalid state file: YAML parse error\n${err.message}`);
         }
+        throw err;
     }
-    return state;
 }
-// ============================================================================
-// State Operations
-// ============================================================================
 /**
- * Read project state from status file
+ * Write project state atomically (tmp file + rename)
  */
-export function readState(statusFilePath) {
-    // Check for crash recovery - .tmp file exists
-    const tmpPath = `${statusFilePath}.tmp`;
-    if (fs.existsSync(tmpPath)) {
-        try {
-            const tmpContent = readFileSync(tmpPath, 'utf-8');
-            const tmpState = parseState(tmpContent);
-            // tmp file is valid, use it and clean up
-            renameSync(tmpPath, statusFilePath);
-            console.log('[porch] Recovered state from interrupted write');
-            return tmpState;
-        }
-        catch {
-            // tmp file is corrupt, delete it
-            unlinkSync(tmpPath);
-        }
-    }
-    if (!fs.existsSync(statusFilePath)) {
-        return null;
-    }
-    const content = readFileSync(statusFilePath, 'utf-8');
-    return parseState(content);
-}
-/**
- * Write project state atomically
- * Uses tmp file + fsync + rename for crash safety
- */
-export async function writeState(statusFilePath, state) {
-    const lock = await acquireLock(statusFilePath);
-    try {
-        const content = serializeState(state);
-        const tmpPath = `${statusFilePath}.tmp`;
-        const dir = path.dirname(statusFilePath);
-        // Ensure directory exists
-        fs.mkdirSync(dir, { recursive: true });
-        // Write to temp file
-        const fd = openSync(tmpPath, 'w');
-        writeFileSync(fd, content);
-        fsyncSync(fd);
-        closeSync(fd);
-        // Atomic rename
-        renameSync(tmpPath, statusFilePath);
-    }
-    finally {
-        releaseLock(lock);
-    }
+export function writeState(statusPath, state) {
+    const dir = path.dirname(statusPath);
+    const tmpPath = `${statusPath}.tmp`;
+    // Ensure directory exists
+    fs.mkdirSync(dir, { recursive: true });
+    // Update timestamp
+    state.updated_at = new Date().toISOString();
+    // Write to temp file then rename (atomic)
+    const content = yaml.dump(state, {
+        indent: 2,
+        lineWidth: 120,
+        noRefs: true,
+    });
+    fs.writeFileSync(tmpPath, content, 'utf-8');
+    fs.renameSync(tmpPath, statusPath);
 }
 /**
- * Create initial project state
+ * Create initial state for a new project.
+ *
+ * Always starts at the first protocol phase. If artifacts (spec, plan)
+ * already exist with approval metadata (YAML frontmatter), the run loop
+ * will detect this and skip those phases automatically.
  */
-export function createInitialState(protocol, projectId, title, worktreePath) {
+export function createInitialState(protocol, projectId, title, _projectRoot) {
     const now = new Date().toISOString();
-    // Extract gates from protocol
+    // Initialize gates from protocol
     const gates = {};
     for (const phase of protocol.phases) {
         if (phase.gate) {
-            const gateId = `${phase.id}_approval`;
-            gates[gateId] = { status: 'pending' };
+            gates[phase.gate] = { status: 'pending' };
         }
     }
+    const initialPhase = protocol.phases[0]?.id || 'specify';
     return {
         id: projectId,
         title,
         protocol: protocol.name,
-        current_state: protocol.initial || `${protocol.phases[0]?.id}:draft`,
-        worktree: worktreePath,
-        gates,
-        phases: {},
+        phase: initialPhase,
         plan_phases: [],
-        iteration: 0,
+        current_plan_phase: null,
+        gates,
+        iteration: 1,
+        build_complete: false,
+        history: [],
         started_at: now,
-        last_updated: now,
-        log: [{
-                ts: now,
-                event: 'state_change',
-                from: null,
-                to: protocol.initial || `${protocol.phases[0]?.id}:draft`,
-            }],
-    };
-}
-/**
- * Update state with a new current state
- */
-export function updateState(state, newState, options = {}) {
-    const now = new Date().toISOString();
-    const logEntry = {
-        ts: now,
-        event: 'state_change',
-        from: state.current_state,
-        to: newState,
-    };
-    if (options.signal) {
-        logEntry.signal = options.signal;
-    }
-    return {
-        ...state,
-        current_state: newState,
-        iteration: state.iteration + 1,
-        last_updated: now,
-        log: [...state.log, logEntry],
-    };
-}
-/**
- * Approve a gate in state
- */
-export function approveGate(state, gateId) {
-    const now = new Date().toISOString();
-    return {
-        ...state,
-        gates: {
-            ...state.gates,
-            [gateId]: {
-                ...state.gates[gateId],
-                status: 'passed',
-                approved_at: now,
-            },
-        },
-        last_updated: now,
-        log: [...state.log, {
-                ts: now,
-                event: 'gate_approved',
-                gate: gateId,
-            }],
-    };
-}
-/**
- * Request a gate approval (mark as pending with timestamp)
- */
-export function requestGateApproval(state, gateId) {
-    const now = new Date().toISOString();
-    return {
-        ...state,
-        gates: {
-            ...state.gates,
-            [gateId]: {
-                status: 'pending',
-                requested_at: now,
-            },
-        },
-        last_updated: now,
-        log: [...state.log, {
-                ts: now,
-                event: 'gate_requested',
-                gate: gateId,
-            }],
-    };
-}
-/**
- * Update phase status
- */
-export function updatePhaseStatus(state, phaseId, status) {
-    const now = new Date().toISOString();
-    return {
-        ...state,
-        phases: {
-            ...state.phases,
-            [phaseId]: {
-                ...state.phases[phaseId],
-                status,
-            },
-        },
-        last_updated: now,
-        log: [...state.log, {
-                ts: now,
-                event: 'phase_status_change',
-                phase: phaseId,
-                status,
-            }],
-    };
-}
-/**
- * Set plan phases extracted from plan.md
- */
-export function setPlanPhases(state, phases) {
-    const now = new Date().toISOString();
-    // Initialize phase status for each extracted phase
-    const phaseStatus = {};
-    for (const phase of phases) {
-        phaseStatus[phase.id] = { status: 'pending', title: phase.title };
-    }
-    return {
-        ...state,
-        plan_phases: phases,
-        phases: phaseStatus,
-        last_updated: now,
-        log: [...state.log, {
-                ts: now,
-                event: 'plan_phases_extracted',
-                count: phases.length,
-            }],
+        updated_at: now,
     };
 }
 // ============================================================================
 // Discovery
 // ============================================================================
 /**
- * Find all SPIDER projects
+ * Find status.yaml by project ID (searches for NNNN-* directories)
  */
-export function findProjects(projectRoot) {
+export function findStatusPath(projectRoot, projectId) {
     const projectsDir = path.join(projectRoot, PROJECTS_DIR);
     if (!fs.existsSync(projectsDir)) {
-        return [];
+        return null;
     }
     const entries = fs.readdirSync(projectsDir, { withFileTypes: true });
-    const projects = [];
     for (const entry of entries) {
-        if (entry.isDirectory()) {
+        if (entry.isDirectory() && entry.name.startsWith(`${projectId}-`)) {
             const statusPath = path.join(projectsDir, entry.name, 'status.yaml');
             if (fs.existsSync(statusPath)) {
-                // Extract project ID from directory name (format: NNNN-name or just NNNN)
-                const idMatch = entry.name.match(/^(\d+)/);
-                if (idMatch) {
-                    projects.push({
-                        id: idMatch[1],
-                        path: statusPath,
-                    });
-                }
+                return statusPath;
             }
         }
     }
-    return projects;
+    return null;
 }
 /**
- * Find all executions (TICK, BUGFIX, etc.)
+ * Detect project ID from the current working directory if inside a builder worktree.
+ * Works from any subdirectory within the worktree.
+ * Returns the porch project ID (e.g. "bugfix-237" or "0073"), or null if not in a recognized worktree.
  */
-export function findExecutions(projectRoot) {
-    const executionsDir = path.join(projectRoot, EXECUTIONS_DIR);
-    if (!fs.existsSync(executionsDir)) {
-        return [];
+export function detectProjectIdFromCwd(cwd) {
+    const normalized = path.resolve(cwd).split(path.sep).join('/');
+    const match = normalized.match(/\/\.builders\/(bugfix-(\d+)|(\d{4}))(\/|$)/);
+    if (!match)
+        return null;
+    // Bugfix worktrees use "bugfix-N" as the porch project ID
+    if (match[2])
+        return `bugfix-${match[2]}`;
+    // Spec worktrees use zero-padded numeric IDs
+    return match[3];
+}
+/**
+ * Resolve project ID using the priority chain:
+ * 1. Explicit CLI argument (highest priority)
+ * 2. CWD worktree detection
+ * 3. Filesystem scan fallback
+ * 4. Error if none succeed
+ */
+export function resolveProjectId(provided, cwd, projectRoot) {
+    // 1. Explicit CLI argument (highest priority)
+    if (provided)
+        return { id: provided, source: 'explicit' };
+    // 2. CWD worktree detection
+    const fromCwd = detectProjectIdFromCwd(cwd);
+    if (fromCwd)
+        return { id: fromCwd, source: 'cwd' };
+    // 3. Filesystem scan fallback
+    const detected = detectProjectId(projectRoot);
+    if (detected)
+        return { id: detected, source: 'filesystem' };
+    // 4. Error — none of the detection methods succeeded
+    throw new Error('Cannot determine project ID. Provide it explicitly or run from a builder worktree.');
+}
+/**
+ * Auto-detect project ID when only one project exists.
+ * Returns null if zero or multiple projects found.
+ */
+export function detectProjectId(projectRoot) {
+    const projectsDir = path.join(projectRoot, PROJECTS_DIR);
+    if (!fs.existsSync(projectsDir)) {
+        return null;
     }
-    const entries = fs.readdirSync(executionsDir, { withFileTypes: true });
-    const executions = [];
+    const entries = fs.readdirSync(projectsDir, { withFileTypes: true });
+    const projects = [];
     for (const entry of entries) {
         if (entry.isDirectory()) {
-            const statusPath = path.join(executionsDir, entry.name, 'status.yaml');
-            if (fs.existsSync(statusPath)) {
-                // Parse directory name (format: protocol_id_name)
-                const match = entry.name.match(/^(\w+)_(\w+)/);
-                if (match) {
-                    executions.push({
-                        protocol: match[1],
-                        id: match[2],
-                        path: statusPath,
-                    });
-                }
-            }
-        }
-    }
-    return executions;
-}
-/**
- * Find status file for a project by ID
- */
-export function findStatusFile(projectRoot, projectId) {
-    // Check projects directory first
-    const projectsDir = path.join(projectRoot, PROJECTS_DIR);
-    if (fs.existsSync(projectsDir)) {
-        const entries = fs.readdirSync(projectsDir);
-        for (const entry of entries) {
-            if (entry.startsWith(projectId)) {
-                const statusPath = path.join(projectsDir, entry, 'status.yaml');
-                if (fs.existsSync(statusPath)) {
-                    return statusPath;
-                }
-            }
-        }
-    }
-    // Check executions directory
-    const executionsDir = path.join(projectRoot, EXECUTIONS_DIR);
-    if (fs.existsSync(executionsDir)) {
-        const entries = fs.readdirSync(executionsDir);
-        for (const entry of entries) {
-            if (entry.includes(`_${projectId}`)) {
-                const statusPath = path.join(executionsDir, entry, 'status.yaml');
+            // Extract project ID from directory name
+            // Matches: "0076-skip-close" -> "0076", "bugfix-237-fix-name" -> "bugfix-237"
+            const match = entry.name.match(/^(bugfix-\d+|\d{4})-/);
+            if (match) {
+                const statusPath = path.join(projectsDir, entry.name, 'status.yaml');
                 if (fs.existsSync(statusPath)) {
-                    return statusPath;
-                }
-            }
-        }
-    }
-    return null;
-}
-// ============================================================================
-// Consultation Attempt Tracking
-// ============================================================================
-/**
- * Get the number of consultation attempts for a given state
- */
-export function getConsultationAttempts(state, stateKey) {
-    return state.consultation_attempts?.[stateKey] ?? 0;
-}
-/**
- * Increment consultation attempts for a given state
- */
-export function incrementConsultationAttempts(state, stateKey) {
-    const now = new Date().toISOString();
-    const currentAttempts = getConsultationAttempts(state, stateKey);
-    return {
-        ...state,
-        consultation_attempts: {
-            ...state.consultation_attempts,
-            [stateKey]: currentAttempts + 1,
-        },
-        last_updated: now,
-        log: [...state.log, {
-                ts: now,
-                event: 'consultation_attempt',
-                phase: stateKey,
-                count: currentAttempts + 1,
-            }],
-    };
-}
-/**
- * Reset consultation attempts for a given state (e.g., after gate approval)
- */
-export function resetConsultationAttempts(state, stateKey) {
-    const newAttempts = { ...state.consultation_attempts };
-    delete newAttempts[stateKey];
-    return {
-        ...state,
-        consultation_attempts: newAttempts,
-        last_updated: new Date().toISOString(),
-    };
-}
-// ============================================================================
-// Discovery
-// ============================================================================
-/**
- * Find all status files with pending gates
- */
-export function findPendingGates(projectRoot) {
-    const pending = [];
-    // Check projects
-    for (const { id, path: statusPath } of findProjects(projectRoot)) {
-        const state = readState(statusPath);
-        if (state && state.gates) {
-            for (const [gateId, gateStatus] of Object.entries(state.gates)) {
-                if (gateStatus.status === 'pending' && gateStatus.requested_at) {
-                    pending.push({
-                        projectId: id,
-                        gateId,
-                        requestedAt: gateStatus.requested_at,
-                        statusPath,
-                    });
-                }
-            }
-        }
-    }
-    // Check executions
-    for (const { id, path: statusPath } of findExecutions(projectRoot)) {
-        const state = readState(statusPath);
-        if (state && state.gates) {
-            for (const [gateId, gateStatus] of Object.entries(state.gates)) {
-                if (gateStatus.status === 'pending' && gateStatus.requested_at) {
-                    pending.push({
-                        projectId: id,
-                        gateId,
-                        requestedAt: gateStatus.requested_at,
-                        statusPath,
-                    });
+                    projects.push(match[1]);
                 }
             }
         }
     }
-    return pending;
+    // Only return if exactly one project
+    return projects.length === 1 ? projects[0] : null;
 }
 //# sourceMappingURL=state.js.map