opencastle 0.31.3 → 0.31.4

package/src/cli/pipeline.ts

@@ -58,6 +58,125 @@ export function deriveComplexityPath(prdPath: string): string {
   return prdPath + '.complexity.json'
 }
 
+export function validateComplexityGroups(assessment: ComplexityAssessment): { valid: boolean; reason: string } {
+  const groups = assessment.convoy_groups
+
+  // Each group must reference at least 1 phase
+  for (const group of groups) {
+    if (group.phases.length === 0) {
+      return { valid: false, reason: `Group "${group.name}" has an empty phases array` }
+    }
+  }
+
+  // Maximum group count: ≤3 for total_tasks ≤ 15, ≤4 for total_tasks > 15
+  const maxGroups = assessment.total_tasks > 15 ? 4 : 3
+  if (groups.length > maxGroups) {
+    return { valid: false, reason: `Too many groups: ${groups.length} exceeds maximum of ${maxGroups} for total_tasks=${assessment.total_tasks}` }
+  }
+
+  // No overlapping phases
+  const seenPhases = new Map<number, string>()
+  for (const group of groups) {
+    for (const phase of group.phases) {
+      if (seenPhases.has(phase)) {
+        return { valid: false, reason: `Phase ${phase} overlap: referenced by both "${seenPhases.get(phase)}" and "${group.name}"` }
+      }
+      seenPhases.set(phase, group.name)
+    }
+  }
+
+  // Valid depends_on references
+  const groupNames = new Set(groups.map(g => g.name))
+  for (const group of groups) {
+    for (const dep of group.depends_on) {
+      if (!groupNames.has(dep)) {
+        return { valid: false, reason: `Group "${group.name}" depends_on "${dep}" which does not exist` }
+      }
+    }
+  }
+
+  // No dependency cycles (Kahn's algorithm)
+  const inDegree = new Map<string, number>()
+  const adjList = new Map<string, string[]>()
+  for (const group of groups) {
+    inDegree.set(group.name, 0)
+    adjList.set(group.name, [])
+  }
+  for (const group of groups) {
+    for (const dep of group.depends_on) {
+      adjList.get(dep)!.push(group.name)
+      inDegree.set(group.name, (inDegree.get(group.name) ?? 0) + 1)
+    }
+  }
+  const queue: string[] = []
+  for (const [name, degree] of inDegree) {
+    if (degree === 0) queue.push(name)
+  }
+  let visited = 0
+  while (queue.length > 0) {
+    const node = queue.shift()!
+    visited++
+    for (const neighbor of adjList.get(node) ?? []) {
+      const newDegree = (inDegree.get(neighbor) ?? 0) - 1
+      inDegree.set(neighbor, newDegree)
+      if (newDegree === 0) queue.push(neighbor)
+    }
+  }
+  if (visited !== groups.length) {
+    return { valid: false, reason: 'Dependency cycle detected in convoy_groups' }
+  }
+
+  // Group names must be kebab-case safe
+  const kebabCaseRegex = /^[a-z0-9]+(-[a-z0-9]+)*$/
+  for (const group of groups) {
+    if (!kebabCaseRegex.test(group.name)) {
+      return { valid: false, reason: `Group name "${group.name}" is not valid kebab-case` }
+    }
+  }
+
+  return { valid: true, reason: '' }
+}
+
+export function topologicalSortGroups(groups: ConvoyGroup[]): ConvoyGroup[] {
+  const groupMap = new Map<string, ConvoyGroup>()
+  const inDegree = new Map<string, number>()
+  const adjList = new Map<string, string[]>()
+
+  for (const group of groups) {
+    groupMap.set(group.name, group)
+    inDegree.set(group.name, 0)
+    adjList.set(group.name, [])
+  }
+  for (const group of groups) {
+    for (const dep of group.depends_on) {
+      adjList.get(dep)!.push(group.name)
+      inDegree.set(group.name, (inDegree.get(group.name) ?? 0) + 1)
+    }
+  }
+
+  const queue: string[] = []
+  for (const [name, degree] of inDegree) {
+    if (degree === 0) queue.push(name)
+  }
+
+  const sorted: ConvoyGroup[] = []
+  while (queue.length > 0) {
+    const node = queue.shift()!
+    sorted.push(groupMap.get(node)!)
+    for (const neighbor of adjList.get(node) ?? []) {
+      const newDegree = (inDegree.get(neighbor) ?? 0) - 1
+      inDegree.set(neighbor, newDegree)
+      if (newDegree === 0) queue.push(neighbor)
+    }
+  }
+
+  if (sorted.length !== groups.length) {
+    throw new Error('Cycle detected in convoy_groups dependency graph')
+  }
+
+  return sorted
+}
+
 const HELP = `
   opencastle start [options]
 
@@ -244,6 +363,12 @@ export default async function pipeline({ args, pkgRoot }: CliContext): Promise<v
     console.log(c.green(`  ✓ PRD written to ${relPath(prdPath)}\n`))
   }
 
+  // Handle --dry-run when PRD was provided externally (not generated)
+  if (opts.dryRun && opts.prd) {
+    console.log(c.dim('\n  [dry-run] Nothing to preview — PRD already provided via --prd. Remove --dry-run to continue.'))
+    return
+  }
+
   // ── Step 2: Validate PRD ──────────────────────────────────────────────────
   if (!opts.skipValidation) {
     console.log(stepLabel(2, totalSteps, 'Validating PRD…'))
@@ -400,105 +525,115 @@ export default async function pipeline({ args, pkgRoot }: CliContext): Promise<v
 
   if (complexity) {
     if (complexity.recommended_strategy === 'chain' && complexity.convoy_groups.length > 1) {
-      console.log(
-        c.cyan(`  ℹ`) +
-          ` Complexity: ${complexity.complexity} | Strategy: chain | ${complexity.convoy_groups.length} convoy groups\n`
-      )
-      console.log(`  Chain plan:`)
-      for (let i = 0; i < complexity.convoy_groups.length; i++) {
-        const g = complexity.convoy_groups[i]
-        const depStr =
-          g.depends_on.length > 0 ? ` → depends on: ${g.depends_on.join(', ')}` : ''
+      // Validate complexity groups before chain generation
+      const groupValidation = validateComplexityGroups(complexity)
+      if (!groupValidation.valid) {
+        console.log(c.yellow(`  ⚠ Complexity groups failed validation: ${groupValidation.reason}`))
+        console.log(c.yellow(`  Falling back to single convoy strategy.\n`))
+        // Fall through to single-spec generation below
+      } else {
+        // Sort groups in dependency order
+        complexity.convoy_groups = topologicalSortGroups(complexity.convoy_groups)
         console.log(
-          `    ${i + 1}. ${g.name.padEnd(20)} (phases: ${g.phases.join(', ')})${depStr}`
+          c.cyan(`  ℹ`) +
+            ` Complexity: ${complexity.complexity} | Strategy: chain | ${complexity.convoy_groups.length} convoy groups\n`
         )
-      }
-      console.log()
+        console.log(`  Chain plan:`)
+        for (let i = 0; i < complexity.convoy_groups.length; i++) {
+          const g = complexity.convoy_groups[i]
+          const depStr =
+            g.depends_on.length > 0 ? ` → depends on: ${g.depends_on.join(', ')}` : ''
+          console.log(
+            `    ${i + 1}. ${g.name.padEnd(20)} (phases: ${g.phases.join(', ')})${depStr}`
+          )
+        }
+        console.log()
 
-      const convoyDir = resolve(process.cwd(), '.opencastle', 'convoys')
-      await mkdir(convoyDir, { recursive: true })
-
-      const groupSpecPaths: string[] = []
-
-      for (let i = 0; i < complexity.convoy_groups.length; i++) {
-        const group = complexity.convoy_groups[i]
-
-        const chainGoal = [
-          complexity.original_prompt,
-          '',
-          '## Convoy Group Scope',
-          '',
-          `This is group **${i + 1} of ${complexity.convoy_groups.length}** in a convoy chain.`,
-          `Generate a convoy spec covering ONLY the phases listed below.`,
-          '',
-          `- **Group name:** ${group.name}`,
-          `- **Description:** ${group.description}`,
-          `- **Phases to include:** ${group.phases.join(', ')}`,
-          group.depends_on.length ? `- **Depends on groups:** ${group.depends_on.join(', ')}` : '',
-        ].filter(Boolean).join('\n')
-
-        const prdContent = await readFile(prdPath, 'utf8')
-        const groupSpecPath = resolve(convoyDir, `${group.name}.convoy.yml`)
-
-        const { specPath: resolvedGroupSpecPath } = await generateAndValidateSpec({
-          sharedOpts,
-          goalText: chainGoal,
-          contextText: prdContent,
-          specPath: groupSpecPath,
-          skipValidation: opts.skipValidation,
-          groupName: group.name,
-          enrichment: complexity ? deriveSpecEnrichment(complexity) : undefined,
-        })
-        groupSpecPaths.push(resolvedGroupSpecPath)
-      }
+        const convoyDir = resolve(process.cwd(), '.opencastle', 'convoys')
+        await mkdir(convoyDir, { recursive: true })
+
+        const groupSpecPaths: string[] = []
+
+        for (let i = 0; i < complexity.convoy_groups.length; i++) {
+          const group = complexity.convoy_groups[i]
+
+          const chainGoal = [
+            complexity.original_prompt,
+            '',
+            '## Convoy Group Scope',
+            '',
+            `This is group **${i + 1} of ${complexity.convoy_groups.length}** in a convoy chain.`,
+            `Generate a convoy spec covering ONLY the phases listed below.`,
+            '',
+            `- **Group name:** ${group.name}`,
+            `- **Description:** ${group.description}`,
+            `- **Phases to include:** ${group.phases.join(', ')}`,
+            group.depends_on.length ? `- **Depends on groups:** ${group.depends_on.join(', ')}` : '',
+          ].filter(Boolean).join('\n')
+
+          const prdContent = await readFile(prdPath, 'utf8')
+          const groupSpecPath = resolve(convoyDir, `${group.name}.convoy.yml`)
+
+          const { specPath: resolvedGroupSpecPath } = await generateAndValidateSpec({
+            sharedOpts,
+            goalText: chainGoal,
+            contextText: prdContent,
+            specPath: groupSpecPath,
+            skipValidation: opts.skipValidation,
+            groupName: group.name,
+            enrichment: complexity ? deriveSpecEnrichment(complexity) : undefined,
+          })
+          groupSpecPaths.push(resolvedGroupSpecPath)
+        }
 
-      // Build master pipeline spec (version 2)
-      const chainPrdContent = await readFile(prdPath, 'utf8')
-      const featureNameMatch = chainPrdContent.match(/^# (.+?)\s*(?:—|-)?\s*PRD/m)
-      const featureName = featureNameMatch
-        ? featureNameMatch[1].trim().toLowerCase().replace(/[^a-z0-9]+/g, '-')
-        : 'feature'
-
-      const branchMatch = chainPrdContent.match(/`feat\/([^`]+)`/)
-      const branch = branchMatch ? `feat/${branchMatch[1]}` : `feat/${featureName}`
-
-      const masterSpec = {
-        name: featureNameMatch ? featureNameMatch[1].trim() : 'Feature Pipeline',
-        version: 2,
-        branch,
-        on_failure: 'stop',
-        depends_on_convoy: groupSpecPaths.map(p => relPath(p)),
-      }
+        // Build master pipeline spec (version 2)
+        const chainPrdContent = await readFile(prdPath, 'utf8')
+        const featureNameMatch = chainPrdContent.match(/^# (.+?)\s*(?:—|-)?\s*PRD/m)
+        const featureName = featureNameMatch
+          ? featureNameMatch[1].trim().toLowerCase().replace(/[^a-z0-9]+/g, '-')
+          : 'feature'
+
+        const branchMatch = chainPrdContent.match(/`feat\/([^`]+)`/)
+        const branch = branchMatch ? `feat/${branchMatch[1]}` : `feat/${featureName}`
+
+        const masterSpec = {
+          name: featureNameMatch ? featureNameMatch[1].trim() : 'Feature Pipeline',
+          version: 2,
+          branch,
+          on_failure: 'stop',
+          depends_on_convoy: groupSpecPaths.map(p => relPath(p)),
+        }
 
-      const masterSpecPath = resolve(convoyDir, `${featureName}-pipeline.convoy.yml`)
-      await writeFile(masterSpecPath, stringify(masterSpec), 'utf8')
+        const masterSpecPath = resolve(convoyDir, `${featureName}-pipeline.convoy.yml`)
+        await writeFile(masterSpecPath, stringify(masterSpec), 'utf8')
 
-      console.log(c.green(`  ✓ Generated convoy chain:\n`))
-      for (const p of groupSpecPaths) {
-        console.log(`    ${relPath(p)}`)
-      }
-      console.log(`    ${relPath(masterSpecPath)} ${c.dim('(master)')}`)
-      console.log()
-      console.log(
-        `  ${c.dim('Preview:')} npx opencastle run -f ${relPath(masterSpecPath)} --dry-run\n` +
-          `  ${c.dim('Execute:')} npx opencastle run -f ${relPath(masterSpecPath)}\n`
-      )
+        console.log(c.green(`  ✓ Generated convoy chain:\n`))
+        for (const p of groupSpecPaths) {
+          console.log(`    ${relPath(p)}`)
+        }
+        console.log(`    ${relPath(masterSpecPath)} ${c.dim('(master)')}`)
+        console.log()
+        console.log(
+          `  ${c.dim('Preview:')} npx opencastle run -f ${relPath(masterSpecPath)} --dry-run\n` +
+            `  ${c.dim('Execute:')} npx opencastle run -f ${relPath(masterSpecPath)}\n`
+        )
 
-      try {
-        const shouldRun = await confirm('Run the convoy chain now?', true)
-        if (shouldRun) {
+        try {
+          const shouldRun = await confirm('Run the convoy chain now?', true)
+          if (shouldRun) {
+            closePrompts()
+            const runModule = await import('./run.js')
+            const runArgs = ['-f', masterSpecPath]
+            if (opts.adapter) runArgs.push('-a', opts.adapter)
+            if (opts.verbose) runArgs.push('--verbose')
+            await runModule.default({ args: runArgs, pkgRoot })
+          }
+        } finally {
           closePrompts()
-          const runModule = await import('./run.js')
-          const runArgs = ['-f', masterSpecPath]
-          if (opts.adapter) runArgs.push('-a', opts.adapter)
-          if (opts.verbose) runArgs.push('--verbose')
-          await runModule.default({ args: runArgs, pkgRoot })
+          await cleanupAdapters()
         }
-      } finally {
-        closePrompts()
-        await cleanupAdapters()
+        return
       }
-      return
     } else {
       console.log(
         c.cyan(`  ℹ`) + ` Complexity: ${complexity.complexity} | Strategy: single\n`

package/src/cli/plan.ts

@@ -225,10 +225,27 @@ function extractMarkdownBody(output: string): string {
 
 /**
  * Parse a validation AI response for VALID / INVALID verdict.
- * INVALID takes precedence because VALID is a substring of INVALID.
+ * Prefers structured JSON output; falls back to VALID/INVALID keyword matching.
  */
 function parseValidationResult(output: string): { isValid: boolean; errors: string } {
   const trimmed = output.trim()
+
+  // Try structured JSON first (preferred format)
+  const jsonFenceMatch = trimmed.match(/```json\s*\n([\s\S]*?)```/)
+  if (jsonFenceMatch) {
+    try {
+      const parsed = JSON.parse(jsonFenceMatch[1].trim()) as { valid?: boolean; issues?: string[] }
+      if (typeof parsed.valid === 'boolean') {
+        if (parsed.valid) return { isValid: true, errors: '' }
+        const errors = Array.isArray(parsed.issues) ? parsed.issues.join('\n') : ''
+        return { isValid: false, errors }
+      }
+    } catch {
+      // JSON parse failed — fall through to regex fallback
+    }
+  }
+
+  // Fallback: regex-based parsing for backward compatibility
   const hasInvalid = /\bINVALID\b/.test(trimmed)
   const hasValid = /\bVALID\b/.test(trimmed)
   if (hasValid && !hasInvalid) return { isValid: true, errors: '' }
@@ -364,9 +381,17 @@ export async function runPromptStep(opts: PromptStepOptions): Promise<PromptStep
   }
 
   if (outputType === 'json') {
-    // Extract JSON from a ```json fenced block only
-    const jsonFenceMatch = rawOutput.match(/```json\s*\n([\s\S]*)```/)
-    const jsonContent = jsonFenceMatch ? jsonFenceMatch[1].trim() : rawOutput.trim()
+    // Extract JSON from a ```json fenced block — fail fast if missing
+    const jsonFenceMatch = rawOutput.match(/```json\s*\n([\s\S]*?)```/)
+    if (!jsonFenceMatch) {
+      const preview = rawOutput.slice(0, 300)
+      throw new Error(
+        `Expected a fenced \`\`\`json block in the AI response but found none.\n\n` +
+        `Raw output (truncated):\n${preview}\n\n` +
+        `Tip: re-run with --verbose to see the full output.`
+      )
+    }
+    const jsonContent = jsonFenceMatch[1].trim()
 
     const outputPath = opts.outputPath ?? null
     if (outputPath) {

package/src/cli/run.ts

@@ -645,12 +645,14 @@ export default async function run({ args, pkgRoot }: CliContext): Promise<void>
       template = parseFormula(formulaPath)
     } catch (err: unknown) {
       console.error(`  ✗ ${(err as Error).message}`)
+      console.log(`\n  ${c.dim('Resume:')} npx opencastle run --formula ${opts.formula}`)
       process.exit(1)
     }
 
     const validation = validateTemplate(template)
     if (!validation.valid) {
       console.error(`  ✗ Invalid formula template:\n  • ${validation.errors.join('\n  • ')}`)
+      console.log(`\n  ${c.dim('Resume:')} npx opencastle run --formula ${opts.formula}`)
       process.exit(1)
     }
 
@@ -672,6 +674,7 @@ export default async function run({ args, pkgRoot }: CliContext): Promise<void>
       spec = substituteVariables(template, opts.setVars)
     } catch (err: unknown) {
       console.error(`  ✗ ${(err as Error).message}`)
+      console.log(`\n  ${c.dim('Resume:')} npx opencastle run --formula ${opts.formula}`)
       process.exit(1)
     }
     specText = yamlStringify(spec)
@@ -687,6 +690,7 @@ export default async function run({ args, pkgRoot }: CliContext): Promise<void>
       } else {
         console.error(`  ✗ Cannot read task spec file: ${e.message}`)
       }
+      console.log(`\n  ${c.dim('Resume:')} npx opencastle run -f ${opts.file}`)
       process.exit(1)
     }
 
@@ -694,6 +698,7 @@ export default async function run({ args, pkgRoot }: CliContext): Promise<void>
       spec = parseTaskSpecText(specText)
     } catch (err: unknown) {
       console.error(`  ✗ ${(err as Error).message}`)
+      console.log(`\n  ${c.dim('Resume:')} npx opencastle run -f ${opts.file}`)
       process.exit(1)
     }
   }
@@ -745,6 +750,7 @@ export default async function run({ args, pkgRoot }: CliContext): Promise<void>
   const available = await adapter.isAvailable()
   if (!available) {
     printAdapterError(detectionFailed, spec.adapter)
+    console.log(`\n  ${c.dim('Resume:')} npx opencastle run -f ${opts.file}`)
     process.exit(1)
   }
 
@@ -762,22 +768,45 @@ export default async function run({ args, pkgRoot }: CliContext): Promise<void>
       const { execFile: execFileCb } = await import('node:child_process')
       const { promisify } = await import('node:util')
       const execFile = promisify(execFileCb)
-      const { stdout: statusOut } = await execFile('git', ['status', '--porcelain'], {
-        cwd: process.cwd(),
-      })
-      if (statusOut.trim()) {
+      let statusOut: string
+      try {
+        const result = await execFile('git', ['status', '--porcelain'], {
+          cwd: process.cwd(),
+        })
+        statusOut = result.stdout
+      } catch {
+        console.error(`  ✗ Git repository not found. A git repo is required when using the \`branch\` option.`)
+        console.error(`    Run \`git init\` to initialize a repository.`)
+        console.log(`\n  ${c.dim('Resume:')} npx opencastle run -f ${opts.file}`)
+        process.exit(1)
+      }
+      // Untracked files (??) don't block branch checkout — ignore them
+      const trackedChanges = statusOut
+        .split('\n')
+        .filter(line => line.trim() && !line.startsWith('??'))
+        .join('\n')
+      if (trackedChanges) {
         console.log(`\n  ${c.yellow('⚠')} Uncommitted changes detected.`)
         const shouldStash = await confirm('Stash changes and continue?', true)
         if (!shouldStash) {
           console.log('  Aborted. Commit or stash your changes manually, then retry.')
+          console.log(`\n  ${c.dim('Resume:')} npx opencastle run -f ${opts.file}`)
+          closePrompts()
+          process.exit(1)
+        }
+        try {
+          await execFile('git', ['stash', 'push', '-m', 'opencastle: auto-stash before pipeline'], {
+            cwd: process.cwd(),
+          })
+          pipelineDidStash = true
+          console.log(`  ${c.green('✓')} Changes stashed.`)
+        } catch {
+          console.log(`  ${c.yellow('⚠')} Could not stash changes automatically.`)
+          console.log(`  Commit or stash your changes manually, then resume:\n`)
+          console.log(`  ${c.dim('Resume:')} npx opencastle run -f ${opts.file}`)
           closePrompts()
           process.exit(1)
         }
-        await execFile('git', ['stash', 'push', '-m', 'opencastle: auto-stash before pipeline'], {
-          cwd: process.cwd(),
-        })
-        pipelineDidStash = true
-        console.log(`  ${c.green('✓')} Changes stashed.`)
       }
     }
 
@@ -809,6 +838,7 @@ export default async function run({ args, pkgRoot }: CliContext): Promise<void>
     } catch (err) {
       if (err instanceof EngineAlreadyRunningError) {
         console.error(`  ✗ ${err.message}`)
+        console.log(`\n  ${c.dim('Resume:')} npx opencastle run -f ${opts.file} --resume`)
         process.exit(1)
       }
       throw err
@@ -829,6 +859,9 @@ export default async function run({ args, pkgRoot }: CliContext): Promise<void>
       console.log(`\n  ${c.dim('Results saved to .opencastle/convoy.db')}`)
       console.log(`  ${c.dim('Dashboard:')} ${pipelineDashboardResult.url}`)
       console.log(`\n  Press Ctrl+C to stop`)
+      if (pipelineResult.status !== 'done') {
+        console.log(`\n  ${c.dim('Resume:')} npx opencastle run -f ${opts.file} --resume`)
+      }
       const exitCode = pipelineResult.status !== 'done' ? 1 : 0
       process.on('SIGINT', () => {
         console.log('\n  Dashboard stopped.\n')
@@ -836,6 +869,9 @@ export default async function run({ args, pkgRoot }: CliContext): Promise<void>
         process.exit(exitCode)
       })
     } else {
+      if (pipelineResult.status !== 'done') {
+        console.log(`\n  ${c.dim('Resume:')} npx opencastle run -f ${opts.file} --resume`)
+      }
       process.exit(pipelineResult.status !== 'done' ? 1 : 0)
     }
     return
@@ -857,22 +893,45 @@ export default async function run({ args, pkgRoot }: CliContext): Promise<void>
       const { execFile: execFileCb } = await import('node:child_process')
       const { promisify } = await import('node:util')
       const execFile = promisify(execFileCb)
-      const { stdout: statusOut } = await execFile('git', ['status', '--porcelain'], {
-        cwd: process.cwd(),
-      })
-      if (statusOut.trim()) {
+      let statusOut: string
+      try {
+        const result = await execFile('git', ['status', '--porcelain'], {
+          cwd: process.cwd(),
+        })
+        statusOut = result.stdout
+      } catch {
+        console.error(`  ✗ Git repository not found. A git repo is required when using the \`branch\` option.`)
+        console.error(`    Run \`git init\` to initialize a repository.`)
+        console.log(`\n  ${c.dim('Resume:')} npx opencastle run -f ${opts.file}`)
+        process.exit(1)
+      }
+      // Untracked files (??) don't block branch checkout — ignore them
+      const trackedChanges = statusOut
+        .split('\n')
+        .filter(line => line.trim() && !line.startsWith('??'))
+        .join('\n')
+      if (trackedChanges) {
         console.log(`\n  ${c.yellow('⚠')} Uncommitted changes detected.`)
         const shouldStash = await confirm('Stash changes and continue?', true)
         if (!shouldStash) {
           console.log('  Aborted. Commit or stash your changes manually, then retry.')
+          console.log(`\n  ${c.dim('Resume:')} npx opencastle run -f ${opts.file}`)
+          closePrompts()
+          process.exit(1)
+        }
+        try {
+          await execFile('git', ['stash', 'push', '-m', 'opencastle: auto-stash before convoy'], {
+            cwd: process.cwd(),
+          })
+          didStash = true
+          console.log(`  ${c.green('✓')} Changes stashed.`)
+        } catch {
+          console.log(`  ${c.yellow('⚠')} Could not stash changes automatically.`)
+          console.log(`  Commit or stash your changes manually, then resume:\n`)
+          console.log(`  ${c.dim('Resume:')} npx opencastle run -f ${opts.file}`)
           closePrompts()
           process.exit(1)
         }
-        await execFile('git', ['stash', 'push', '-m', 'opencastle: auto-stash before convoy'], {
-          cwd: process.cwd(),
-        })
-        didStash = true
-        console.log(`  ${c.green('✓')} Changes stashed.`)
       }
     }
 
@@ -921,6 +980,7 @@ export default async function run({ args, pkgRoot }: CliContext): Promise<void>
     } catch (err) {
       if (err instanceof EngineAlreadyRunningError) {
         console.error(`  ✗ ${err.message}`)
+        console.log(`\n  ${c.dim('Resume:')} npx opencastle run -f ${opts.file} --resume`)
         process.exit(1)
       }
       throw err
@@ -941,6 +1001,9 @@ export default async function run({ args, pkgRoot }: CliContext): Promise<void>
       console.log(`\n  ${c.dim('Results saved to .opencastle/convoy.db')}`)
       console.log(`  ${c.dim('Dashboard:')} ${dashboardResult.url}`)
       console.log(`\n  Press Ctrl+C to stop`)
+      if (result.status !== 'done') {
+        console.log(`\n  ${c.dim('Resume:')} npx opencastle run -f ${opts.file} --resume`)
+      }
       const exitCode = result.status !== 'done' ? 1 : 0
       process.on('SIGINT', () => {
         console.log('\n  Dashboard stopped.\n')
@@ -948,6 +1011,9 @@ export default async function run({ args, pkgRoot }: CliContext): Promise<void>
         process.exit(exitCode)
       })
     } else {
+      if (result.status !== 'done') {
+        console.log(`\n  ${c.dim('Resume:')} npx opencastle run -f ${opts.file} --resume`)
+      }
       process.exit(result.status !== 'done' ? 1 : 0)
     }
   }

package/src/dashboard/node_modules/.vite/deps/_metadata.json

@@ -1,25 +1,25 @@
 {
-  "hash": "cbfbf8fa",
+  "hash": "dcf92252",
   "configHash": "30f8ea04",
-  "lockfileHash": "4d248ba7",
-  "browserHash": "45b21a68",
+  "lockfileHash": "afb56fd1",
+  "browserHash": "6d49cf21",
   "optimized": {
     "astro > cssesc": {
       "src": "../../../../../node_modules/cssesc/cssesc.js",
       "file": "astro___cssesc.js",
-      "fileHash": "2a8eea79",
+      "fileHash": "53e7f26d",
       "needsInterop": true
     },
     "astro > aria-query": {
       "src": "../../../../../node_modules/aria-query/lib/index.js",
       "file": "astro___aria-query.js",
-      "fileHash": "16cb4c63",
+      "fileHash": "4d0f70f0",
       "needsInterop": true
     },
     "astro > axobject-query": {
       "src": "../../../../../node_modules/axobject-query/lib/index.js",
       "file": "astro___axobject-query.js",
-      "fileHash": "95262852",
+      "fileHash": "26bf71c8",
       "needsInterop": true
     }
   },

package/src/orchestrator/prompts/validate-convoy.prompt.md

@@ -65,20 +65,23 @@ The overall plan must make engineering sense.
 
 ## Output Format
 
-If all checks pass:
+Your entire response must be a single fenced JSON block — no text before or after:
 
+```json
+{
+  "valid": true
+}
 ```
-VALID
-```
-
-If any check fails:
 
-```
-INVALID
+Or if any check fails:
 
-Errors:
-- [Check category] / [task id if applicable]: [Specific problem] — Fix: [How to correct it]
-- [Check category] / [task id if applicable]: [Another problem] — Fix: [How to correct it]
+```json
+{
+  "valid": false,
+  "issues": [
+    "[Section name]: [Specific problem] — Fix: [What to change]"
+  ]
+}
 ```
 
-List only real failures. Do not list passing checks. Be specific — name the task id, the field, and the exact value that violates the rule.
+List only real failures in `issues`. Do not list items that passed.