opencastle 0.31.7 → 0.32.1

package/src/cli/convoy/isolation.ts

@@ -0,0 +1,165 @@
+import { normalizePath, pathsOverlap } from './partition.js'
+import type { ConvoyStore } from './store.js'
+import { listArtifacts, type ArtifactRef } from './artifacts.js'
+
+// ── Interfaces ────────────────────────────────────────────────────────────────
+
+export interface DependencyResult {
+  taskId: string
+  agent: string
+  status: string
+  summary: string | null
+  filesChanged: string[]
+  artifactRefs?: ArtifactRef[]  // filesystem artifact references
+}
+
+export interface PartitionViolation {
+  taskId: string
+  allowedFiles: string[]
+  actualFiles: string[]
+  violations: string[]
+}
+
+// ── Formatting ────────────────────────────────────────────────────────────────
+
+export function formatDependencyResults(deps: DependencyResult[]): string {
+  return deps
+    .map(dep => {
+      let text = '#### ' + dep.taskId + ' (' + dep.agent + ') \u2014 ' + dep.status + '\n'
+        + (dep.summary ?? 'No summary available.') + '\n'
+        + 'Files changed: ' + (dep.filesChanged.length > 0 ? dep.filesChanged.join(', ') : 'none')
+
+      if (dep.artifactRefs && dep.artifactRefs.length > 0) {
+        text += '\nArtifacts available:\n'
+          + dep.artifactRefs.map(r => '- ' + r.path + ' \u2014 "' + r.summary + '"').join('\n')
+          + '\n\nTo read an artifact, open the file at the path above.'
+      }
+
+      return text
+    })
+    .join('\n\n')
+}
+
+export function buildIsolationPreamble(
+  task: { id: string; description: string; prompt: string; files: string[]; agent: string },
+  dependencyResults: DependencyResult[],
+): string {
+  const objective = task.description || task.prompt.slice(0, 200)
+  const fileList = task.files.length > 0 ? task.files.map(f => '- ' + f).join('\n') : '- (none specified)'
+  const depSection = dependencyResults.length > 0
+    ? formatDependencyResults(dependencyResults)
+    : 'No dependencies \u2014 you are in the first phase.'
+
+  return [
+    '## Context Isolation Notice',
+    'You are a fresh agent with NO prior context. You have no knowledge of other tasks',
+    'in this convoy. Your only context is what follows.',
+    '',
+    '### Your Task',
+    '- **ID:** ' + task.id,
+    '- **Agent:** ' + task.agent,
+    '- **Objective:** ' + objective,
+    '',
+    '### Your File Partition',
+    'You may ONLY read and modify files within this partition:',
+    fileList,
+    '',
+    'Do NOT modify files outside this partition. If you discover a need to change files',
+    'outside your partition, note it in your output but do not make the change.',
+    '',
+    '### Dependency Results',
+    depSection,
+    '',
+    '### Project Conventions',
+    'Read `.github/instructions/general.instructions.md` for coding standards.',
+  ].join('\n')
+}
+
+// ── Partition violation detection ─────────────────────────────────────────────
+
+export function detectPartitionViolations(
+  taskId: string,
+  allowedFiles: string[],
+  actualFiles: string[],
+): PartitionViolation | null {
+  const violations: string[] = []
+
+  for (const actual of actualFiles) {
+    let isAllowed = false
+    for (const allowed of allowedFiles) {
+      try {
+        const normalizedAllowed = normalizePath(allowed)
+        const normalizedActual = normalizePath(actual)
+        if (pathsOverlap(normalizedAllowed, normalizedActual)) {
+          isAllowed = true
+          break
+        }
+      } catch {
+        // Fallback for unusual paths: exact match or directory prefix
+        const allowedDir = allowed.endsWith('/') ? allowed : allowed + '/'
+        if (actual === allowed || actual.startsWith(allowedDir)) {
+          isAllowed = true
+          break
+        }
+      }
+    }
+    if (!isAllowed) {
+      violations.push(actual)
+    }
+  }
+
+  if (violations.length === 0) return null
+
+  return { taskId, allowedFiles, actualFiles, violations }
+}
+
+// ── Dependency result resolution ──────────────────────────────────────────────
+
+export function resolveDependencyResults(
+  store: ConvoyStore,
+  convoyId: string,
+  dependsOn: string[],
+): DependencyResult[] {
+  return dependsOn
+    .map((depId) => {
+      const record = store.getTask(depId, convoyId)
+      if (!record) return null
+
+      let summary: string | null = null
+      let filesChanged: string[] = []
+
+      if (record.contract_result) {
+        try {
+          const cr = JSON.parse(record.contract_result) as {
+            valid: boolean
+            missing: string[]
+            warnings: string[]
+            data?: Record<string, unknown>
+          }
+          if (cr.data) {
+            summary = typeof cr.data['summary'] === 'string' ? cr.data['summary'] as string : null
+            const files = cr.data['files_changed']
+            if (Array.isArray(files)) {
+              filesChanged = files.filter((f): f is string => typeof f === 'string')
+            }
+          }
+        } catch { /* non-critical */ }
+      }
+
+      let artifactRefs: ArtifactRef[] | undefined
+      try {
+        const refs = listArtifacts(convoyId, depId)
+        if (refs.length > 0) artifactRefs = refs
+      } catch { /* non-critical */ }
+
+      return {
+        taskId: record.id,
+        agent: record.agent,
+        status: record.status,
+        summary,
+        filesChanged,
+        artifactRefs,
+      } as DependencyResult
+    })
+    .filter((r): r is DependencyResult => r !== null)
+}

package/src/cli/convoy/review-stages.test.ts

@@ -0,0 +1,235 @@
+import { describe, it, expect, vi } from 'vitest'
+import {
+  buildSpecCompliancePrompt,
+  buildCodeQualityPrompt,
+  parseStageVerdict,
+  runTwoStageReview,
+} from './review-stages.js'
+import type { ReviewRunnerFn } from './review-stages.js'
+import type { TaskRecord } from './types.js'
+
+// ── Fixtures ──────────────────────────────────────────────────────────────────
+
+function makeTask(overrides: Partial<TaskRecord> = {}): TaskRecord {
+  return {
+    id: 'task-1',
+    convoy_id: 'convoy-1',
+    phase: 1,
+    prompt: 'Implement the feature.\n\n## Acceptance Criteria\n- Feature works\n- Tests pass',
+    agent: 'developer',
+    adapter: null,
+    model: null,
+    timeout_ms: 30000,
+    status: 'done',
+    worker_id: null,
+    worktree: null,
+    output: 'Done.',
+    exit_code: 0,
+    started_at: null,
+    finished_at: null,
+    retries: 0,
+    max_retries: 3,
+    files: 'src/feature.ts',
+    depends_on: null,
+    prompt_tokens: null,
+    completion_tokens: null,
+    total_tokens: null,
+    cost_usd: null,
+    gates: null,
+    on_exhausted: 'dlq',
+    injected: 0,
+    provenance: null,
+    idempotency_key: null,
+    current_step: null,
+    total_steps: null,
+    review_level: null,
+    review_verdict: null,
+    review_tokens: null,
+    review_model: null,
+    panel_attempts: 0,
+    dispute_id: null,
+    drift_score: null,
+    drift_retried: 0,
+    ...overrides,
+  } as TaskRecord
+}
+
+function makePassVerdict(stage: 'spec-compliance' | 'code-quality'): string {
+  return `Analysis done.\n<!-- REVIEW_VERDICT { "stage": "${stage}", "verdict": "pass", "issues": [] } -->`
+}
+
+function makeBlockVerdict(stage: 'spec-compliance' | 'code-quality', issues: string[]): string {
+  return `Analysis done.\n<!-- REVIEW_VERDICT { "stage": "${stage}", "verdict": "block", "issues": ${JSON.stringify(issues)} } -->`
+}
+
+// ── parseStageVerdict ─────────────────────────────────────────────────────────
+
+describe('parseStageVerdict', () => {
+  it('parses a valid pass verdict', () => {
+    const output = makePassVerdict('spec-compliance')
+    const result = parseStageVerdict(output, 'spec-compliance')
+    expect(result.stage).toBe('spec-compliance')
+    expect(result.verdict).toBe('pass')
+    expect(result.issues).toEqual([])
+  })
+
+  it('parses a valid block verdict with issues', () => {
+    const output = makeBlockVerdict('code-quality', ['Missing types', 'Unsafe cast'])
+    const result = parseStageVerdict(output, 'code-quality')
+    expect(result.stage).toBe('code-quality')
+    expect(result.verdict).toBe('block')
+    expect(result.issues).toEqual(['Missing types', 'Unsafe cast'])
+  })
+
+  it('falls back to block verdict on invalid/missing comment', () => {
+    const result = parseStageVerdict('No verdict here.', 'spec-compliance')
+    expect(result.stage).toBe('spec-compliance')
+    expect(result.verdict).toBe('block')
+    expect(result.issues).toEqual(['Failed to parse reviewer output'])
+  })
+
+  it('falls back to block verdict on malformed JSON', () => {
+    const output = '<!-- REVIEW_VERDICT { invalid json } -->'
+    const result = parseStageVerdict(output, 'code-quality')
+    expect(result.verdict).toBe('block')
+    expect(result.issues).toEqual(['Failed to parse reviewer output'])
+  })
+})
+
+// ── buildSpecCompliancePrompt ─────────────────────────────────────────────────
+
+describe('buildSpecCompliancePrompt', () => {
+  it('includes acceptance criteria context from task prompt', () => {
+    const task = makeTask()
+    const prompt = buildSpecCompliancePrompt(task)
+    expect(prompt).toContain('Acceptance Criteria')
+    expect(prompt).toContain('spec-compliance')
+    expect(prompt).toContain('REVIEW_VERDICT')
+  })
+
+  it('includes diff section when diff is provided', () => {
+    const task = makeTask()
+    const prompt = buildSpecCompliancePrompt(task, '+ added line')
+    expect(prompt).toContain('## Diff')
+    expect(prompt).toContain('+ added line')
+  })
+
+  it('includes file partition section when task has files', () => {
+    const task = makeTask({ files: 'src/feature.ts\nsrc/feature.test.ts' })
+    const prompt = buildSpecCompliancePrompt(task)
+    expect(prompt).toContain('File Partition')
+    expect(prompt).toContain('src/feature.ts')
+  })
+})
+
+// ── buildCodeQualityPrompt ────────────────────────────────────────────────────
+
+describe('buildCodeQualityPrompt', () => {
+  it('includes code quality focus areas', () => {
+    const task = makeTask()
+    const prompt = buildCodeQualityPrompt(task)
+    expect(prompt).toContain('code-quality')
+    expect(prompt).toContain('TypeScript')
+    expect(prompt).toContain('as any')
+    expect(prompt).toContain('REVIEW_VERDICT')
+  })
+
+  it('includes diff section when diff is provided', () => {
+    const task = makeTask()
+    const prompt = buildCodeQualityPrompt(task, '- old line\n+ new line')
+    expect(prompt).toContain('## Diff')
+    expect(prompt).toContain('- old line')
+  })
+})
+
+// ── runTwoStageReview ─────────────────────────────────────────────────────────
+
+describe('runTwoStageReview', () => {
+  it('Stage 1 PASS → Stage 2 runs, both stages in result', async () => {
+    const task = makeTask()
+    let callCount = 0
+    const runner: ReviewRunnerFn = vi.fn().mockImplementation((_t, _l, m) => {
+      callCount++
+      const stage = callCount === 1 ? 'spec-compliance' : 'code-quality'
+      return Promise.resolve({ verdict: 'pass' as const, feedback: makePassVerdict(stage), tokens: 50, model: m })
+    })
+
+    const result = await runTwoStageReview(task, runner, 'test-model')
+
+    expect(runner).toHaveBeenCalledTimes(2)
+    expect(result.stages).toHaveLength(2)
+    expect(result.stages[0].stage).toBe('spec-compliance')
+    expect(result.stages[0].verdict).toBe('pass')
+    expect(result.stages[1].stage).toBe('code-quality')
+    expect(result.overall_verdict).toBe('pass')
+  })
+
+  it('Stage 1 BLOCK → Stage 2 skipped, overall is block', async () => {
+    const task = makeTask()
+    const runner: ReviewRunnerFn = vi.fn().mockResolvedValue({
+      verdict: 'block' as const,
+      feedback: makeBlockVerdict('spec-compliance', ['Missing tests']),
+      tokens: 75,
+      model: 'test-model',
+    })
+
+    const result = await runTwoStageReview(task, runner, 'test-model')
+
+    expect(runner).toHaveBeenCalledTimes(1)
+    expect(result.stages).toHaveLength(1)
+    expect(result.stages[0].stage).toBe('spec-compliance')
+    expect(result.stages[0].verdict).toBe('block')
+    expect(result.overall_verdict).toBe('block')
+  })
+
+  it('Stage 1 PASS + Stage 2 BLOCK → overall BLOCK with 2 stages', async () => {
+    const task = makeTask()
+    let callCount = 0
+    const runner: ReviewRunnerFn = vi.fn().mockImplementation((_t, _l, m) => {
+      callCount++
+      if (callCount === 1) {
+        return Promise.resolve({ verdict: 'pass' as const, feedback: makePassVerdict('spec-compliance'), tokens: 60, model: m })
+      }
+      return Promise.resolve({ verdict: 'block' as const, feedback: makeBlockVerdict('code-quality', ['Uses as any']), tokens: 80, model: m })
+    })
+
+    const result = await runTwoStageReview(task, runner, 'test-model')
+
+    expect(result.stages).toHaveLength(2)
+    expect(result.stages[1].verdict).toBe('block')
+    expect(result.overall_verdict).toBe('block')
+  })
+
+  it('Stage 1 PASS + Stage 2 PASS → overall PASS (happy path)', async () => {
+    const task = makeTask()
+    let callCount = 0
+    const runner: ReviewRunnerFn = vi.fn().mockImplementation((_t, _l, m) => {
+      callCount++
+      const stage = callCount === 1 ? 'spec-compliance' : 'code-quality'
+      return Promise.resolve({ verdict: 'pass' as const, feedback: makePassVerdict(stage), tokens: 40, model: m })
+    })
+
+    const result = await runTwoStageReview(task, runner, 'test-model')
+
+    expect(result.overall_verdict).toBe('pass')
+    expect(result.stages).toHaveLength(2)
+    expect(result.stages.every(s => s.verdict === 'pass')).toBe(true)
+  })
+
+  it('total_tokens is sum of both stage tokens', async () => {
+    const task = makeTask()
+    let callCount = 0
+    const runner: ReviewRunnerFn = vi.fn().mockImplementation((_t, _l, m) => {
+      callCount++
+      const stage = callCount === 1 ? 'spec-compliance' : 'code-quality'
+      const tokens = callCount === 1 ? 100 : 150
+      return Promise.resolve({ verdict: 'pass' as const, feedback: makePassVerdict(stage), tokens, model: m })
+    })
+
+    const result = await runTwoStageReview(task, runner, 'test-model')
+
+    expect(result.total_tokens).toBe(250)
+    expect(result.stages[0].tokens_used).toBe(100)
+    expect(result.stages[1].tokens_used).toBe(150)
+  })
+})

package/src/cli/convoy/review-stages.ts

@@ -0,0 +1,166 @@
+import type { TaskRecord } from './types.js'
+import type { ReviewStage, StageVerdict, TwoStageReviewResult } from './types.js'
+import type { ReviewLevel, ReviewResult } from './engine.js'
+
+export type ReviewRunnerFn = (
+  task: TaskRecord,
+  level: ReviewLevel,
+  model: string,
+) => Promise<ReviewResult>
+
+// ── Stage prompt builders ─────────────────────────────────────────────────────
+
+export function buildSpecCompliancePrompt(task: TaskRecord, diff?: string): string {
+  const diffSection = diff ? `\n\n## Diff\n\`\`\`\n${diff}\n\`\`\`` : ''
+  const filesSection = task.files ? `\n\n## File Partition\n${task.files}` : ''
+
+  return `You are a spec-compliance reviewer. Your job is to verify the implementation matches the original specification.
+
+## Task Prompt
+${task.prompt}
+${filesSection}${diffSection}
+
+## Review Criteria (Stage 1 — Spec Compliance)
+
+1. Does the implementation match ALL acceptance criteria from the task prompt?
+2. Are all required deliverables present and complete?
+3. Do tests exist for all new functionality?
+4. Is the change confined to the assigned file partition (no out-of-scope files modified)?
+
+Respond with a single HTML comment containing a JSON verdict. Do not include any other text after the verdict comment.
+
+<!-- REVIEW_VERDICT { "stage": "spec-compliance", "verdict": "pass", "issues": [] } -->
+
+Use "block" if ANY criterion fails, and list the specific issues. Example:
+
+<!-- REVIEW_VERDICT { "stage": "spec-compliance", "verdict": "block", "issues": ["Missing tests for edge case X", "File src/other.ts is outside the partition"] } -->`
+}
+
+export function buildCodeQualityPrompt(task: TaskRecord, diff?: string): string {
+  const diffSection = diff ? `\n\n## Diff\n\`\`\`\n${diff}\n\`\`\`` : ''
+
+  return `You are a code-quality reviewer. The implementation has already passed spec compliance. Now review for code quality.
+
+## Task Prompt
+${task.prompt}
+${diffSection}
+
+## Review Criteria (Stage 2 — Code Quality)
+
+1. Is the code idiomatic for the project conventions (TypeScript-first, no \`as any\`, proper types)?
+2. Are there type safety issues (missing types, unsafe casts, untyped props)?
+3. Are there obvious bugs, race conditions, or error handling gaps?
+4. Are there DRY violations, dead code, or unnecessary complexity?
+
+Respond with a single HTML comment containing a JSON verdict. Do not include any other text after the verdict comment.
+
+<!-- REVIEW_VERDICT { "stage": "code-quality", "verdict": "pass", "issues": [] } -->
+
+Use "block" if ANY criterion fails, and list the specific issues. Example:
+
+<!-- REVIEW_VERDICT { "stage": "code-quality", "verdict": "block", "issues": ["Uses 'as any' cast on line 42", "Swallowed exception in catch block"] } -->`
+}
+
+// ── Verdict parser ────────────────────────────────────────────────────────────
+
+export function parseStageVerdict(output: string, expectedStage: ReviewStage): StageVerdict {
+  const fallback: StageVerdict = {
+    stage: expectedStage,
+    verdict: 'block',
+    issues: ['Failed to parse reviewer output'],
+    tokens_used: 0,
+  }
+
+  const match = output.match(/<!--\s*REVIEW_VERDICT\s*(\{[\s\S]*?\})\s*-->/)
+  if (!match) return fallback
+
+  let parsed: unknown
+  try {
+    parsed = JSON.parse(match[1])
+  } catch {
+    return fallback
+  }
+
+  if (
+    typeof parsed !== 'object' ||
+    parsed === null ||
+    !('stage' in parsed) ||
+    !('verdict' in parsed) ||
+    !('issues' in parsed)
+  ) {
+    return fallback
+  }
+
+  const p = parsed as Record<string, unknown>
+  const verdict = p['verdict'] === 'pass' ? 'pass' : 'block'
+  const issues = Array.isArray(p['issues'])
+    ? (p['issues'] as unknown[]).filter((i): i is string => typeof i === 'string')
+    : []
+
+  return {
+    stage: expectedStage,
+    verdict,
+    issues,
+    tokens_used: 0,
+  }
+}
+
+// ── Two-stage runner ──────────────────────────────────────────────────────────
+
+export async function runTwoStageReview(
+  task: TaskRecord,
+  reviewRunner: ReviewRunnerFn,
+  reviewerModel: string,
+): Promise<TwoStageReviewResult> {
+  // Stage 1: spec compliance
+  const stage1Result = await reviewRunner(task, 'fast', reviewerModel)
+  // Use ReviewResult.verdict as authoritative gate; parseStageVerdict extracts issues only on successful parse
+  const stage1Parsed = parseStageVerdict(stage1Result.feedback, 'spec-compliance')
+  const stage1Issues = resolveIssues(stage1Parsed, stage1Result)
+  const stage1Verdict: StageVerdict = {
+    stage: 'spec-compliance',
+    verdict: stage1Result.verdict,
+    issues: stage1Issues,
+    tokens_used: stage1Result.tokens,
+  }
+
+  if (stage1Verdict.verdict === 'block') {
+    return {
+      stages: [stage1Verdict],
+      overall_verdict: 'block',
+      total_tokens: stage1Verdict.tokens_used,
+    }
+  }
+
+  // Stage 2: code quality (only runs if stage 1 passes)
+  const stage2Result = await reviewRunner(task, 'fast', reviewerModel)
+  const stage2Parsed = parseStageVerdict(stage2Result.feedback, 'code-quality')
+  const stage2Issues = resolveIssues(stage2Parsed, stage2Result)
+  const stage2Verdict: StageVerdict = {
+    stage: 'code-quality',
+    verdict: stage2Result.verdict,
+    issues: stage2Issues,
+    tokens_used: stage2Result.tokens,
+  }
+
+  return {
+    stages: [stage1Verdict, stage2Verdict],
+    overall_verdict: stage2Verdict.verdict,
+    total_tokens: stage1Verdict.tokens_used + stage2Verdict.tokens_used,
+  }
+}
+
+/**
+ * Resolve issues from stage verdict, falling back to raw feedback when
+ * structured parsing failed (e.g. legacy reviewers or test mocks).
+ */
+function resolveIssues(parsed: StageVerdict, raw: ReviewResult): string[] {
+  if (
+    parsed.issues.length === 1 &&
+    parsed.issues[0] === 'Failed to parse reviewer output' &&
+    raw.feedback
+  ) {
+    return [raw.feedback]
+  }
+  return parsed.issues
+}