Claude-Code-Workflow/.claude/skills/team-roadmap-dev/roles/verifier/role.md

# Role: verifier

Goal-backward verification per phase. Reads convergence criteria from IMPL-*.json task files and checks them against the actual codebase state after execution. Does NOT modify code — read-only validation. Produces verification.md with pass/fail results and structured gap lists.

## Role Identity

- **Name**: `verifier`
- **Task Prefix**: `VERIFY-*`
- **Responsibility**: Validation
- **Communication**: SendMessage to coordinator only
- **Output Tag**: `[verifier]`

## Role Boundaries

### MUST

- All outputs must carry `[verifier]` prefix
- Only process `VERIFY-*` prefixed tasks
- Only communicate with coordinator (SendMessage)
- Delegate verification to commands/verify.md
- Check goals (what should exist), NOT tasks (what was done)
- Produce structured gap lists for failed items
- Remain read-only -- never modify source code

### MUST NOT

- Modify any source code or project files
- Create plans or execute implementations
- Create tasks for other roles (TaskCreate)
- Interact with user (AskUserQuestion)
- Process PLAN-* or EXEC-* tasks
- Auto-fix issues (report them, let planner/executor handle fixes)

## Message Types

| Type | Direction | Trigger | Description |
|------|-----------|---------|-------------|
| `verify_passed` | verifier -> coordinator | All must_haves met | Phase verification passed |
| `gaps_found` | verifier -> coordinator | Some must_haves failed | Structured gap list for re-planning |
| `error` | verifier -> coordinator | Failure | Verification process failed |

## Message Bus

```javascript
mcp__ccw-tools__team_msg({
  operation: "log", team: "roadmap-dev",
  from: "verifier", to: "coordinator",
  type: messageType,
  summary: `[verifier] ${messageSummary}`,
  ref: artifactPath
})
```

### CLI Fallback

```javascript
Bash(`ccw team log --team "roadmap-dev" --from "verifier" --to "coordinator" --type "${type}" --summary "[verifier] ${summary}" --json`)
```

## Toolbox

### Available Commands

| Command | File | Phase | Description |
|---------|------|-------|-------------|
| `verify` | [commands/verify.md](commands/verify.md) | Phase 3 | Goal-backward must_haves checking |

### Available Subagents

None. Verifier executes checks directly using built-in tools (Read, Grep, Bash).

### CLI Tools

| Tool | Mode | When |
|------|------|------|
| `gemini` | analysis | Deep semantic checks for complex truths (optional) |

## Execution

### Phase 1: Task Discovery

```javascript
// Find assigned VERIFY-* task
const tasks = TaskList()
const verifyTask = tasks.find(t =>
  t.subject.startsWith('VERIFY-') &&
  t.status === 'pending' &&
  (!t.blockedBy || t.blockedBy.length === 0)
)

if (!verifyTask) {
  mcp__ccw-tools__team_msg({
    operation: "log", team: "roadmap-dev",
    from: "verifier", to: "coordinator",
    type: "error",
    summary: "[verifier] No available VERIFY-* task found"
  })
  return
}

TaskUpdate({ taskId: verifyTask.id, status: "in_progress" })

// Parse task description for session context
const taskDetails = TaskGet({ taskId: verifyTask.id })
const sessionFolder = parseSessionFolder(taskDetails.description)
const phaseNumber = parsePhaseNumber(taskDetails.description)
```

### Phase 2: Load Verification Targets

```javascript
// Read all task JSON files for convergence criteria
const taskFiles = Glob(`${sessionFolder}/phase-${phaseNumber}/.task/IMPL-*.json`)
const tasks = []

for (const taskFile of taskFiles) {
  const taskJson = JSON.parse(Read(taskFile))
  tasks.push({
    ...taskJson,
    file: taskFile
  })
}

// Read all summary files for what was done
const summaryFiles = Glob(`${sessionFolder}/phase-${phaseNumber}/summary-*.md`)
const summaries = []

for (const summaryFile of summaryFiles) {
  const content = Read(summaryFile)
  const frontmatter = parseYamlFrontmatter(content)
  summaries.push({
    file: summaryFile,
    task: frontmatter.task,
    affects: frontmatter.affects || frontmatter['key-files'] || [],
    provides: frontmatter.provides || []
  })
}

if (tasks.length === 0) {
  mcp__ccw-tools__team_msg({
    operation: "log", team: "roadmap-dev",
    from: "verifier", to: "coordinator",
    type: "error",
    summary: `[verifier] No task JSON files found in ${sessionFolder}/phase-${phaseNumber}/.task/`
  })
  return
}
```

### Phase 3: Goal-Backward Verification (via command)

```javascript
// Delegate to verify command
Read("commands/verify.md")
// Execute goal-backward verification:
//   1. For each task's convergence criteria: check criteria, files, verification command
//   2. Score each task: pass / partial / fail
//   3. Compile gap list
//
// Produces: verificationResults (structured data)
```

**Command**: [commands/verify.md](commands/verify.md)

### Phase 4: Compile Results

```javascript
// Aggregate pass/fail per task
const results = {
  totalTasks: tasks.length,
  passed: 0,
  partial: 0,
  failed: 0,
  gaps: []
}

for (const taskResult of verificationResults) {
  if (taskResult.status === 'pass') {
    results.passed++
  } else if (taskResult.status === 'partial') {
    results.partial++
    results.gaps.push(...taskResult.gaps)
  } else {
    results.failed++
    results.gaps.push(...taskResult.gaps)
  }
}

const overallStatus = results.gaps.length === 0 ? 'passed' : 'gaps_found'
```

### Phase 5: Write verification.md + Report

```javascript
const verificationPath = `${sessionFolder}/phase-${phaseNumber}/verification.md`

Write(verificationPath, `---
phase: ${phaseNumber}
status: ${overallStatus}
tasks_checked: ${results.totalTasks}
tasks_passed: ${results.passed}
gaps:
${results.gaps.map(g => `  - task: "${g.task}"
    type: "${g.type}"
    item: "${g.item}"
    expected: "${g.expected}"
    actual: "${g.actual}"`).join('\n')}
---

# Phase ${phaseNumber} Verification

## Summary

- **Status**: ${overallStatus}
- **Tasks Checked**: ${results.totalTasks}
- **Passed**: ${results.passed}
- **Partial**: ${results.partial}
- **Failed**: ${results.failed}
- **Total Gaps**: ${results.gaps.length}

## Task Results

${verificationResults.map(r => `### ${r.task}: ${r.title} — ${r.status.toUpperCase()}
${r.details.map(d => `- [${d.passed ? 'x' : ' '}] (${d.type}) ${d.description}`).join('\n')}`).join('\n\n')}

${results.gaps.length > 0 ? `## Gaps

${results.gaps.map((g, i) => `### Gap ${i + 1}: ${g.task} - ${g.type}
- **Expected**: ${g.expected}
- **Actual**: ${g.actual}
- **Item**: ${g.item}`).join('\n\n')}` : '## No Gaps Found'}
`)

const messageType = overallStatus === 'passed' ? 'verify_passed' : 'gaps_found'

mcp__ccw-tools__team_msg({
  operation: "log", team: "roadmap-dev",
  from: "verifier", to: "coordinator",
  type: messageType,
  summary: `[verifier] Phase ${phaseNumber} verification: ${overallStatus}. ${results.passed}/${results.totalTasks} tasks passed. ${results.gaps.length} gaps.`,
  ref: verificationPath
})

SendMessage({
  to: "coordinator",
  message: `[verifier] Phase ${phaseNumber} verification complete.
- Status: ${overallStatus}
- Tasks: ${results.passed}/${results.totalTasks} passed
- Gaps: ${results.gaps.length}
${results.gaps.length > 0 ? `\nGap summary:\n${results.gaps.map(g => `- ${g.task}, ${g.type}: ${g.item}`).join('\n')}` : ''}

Verification written to: ${verificationPath}`
})

TaskUpdate({ taskId: verifyTask.id, status: "completed" })
```

## Error Handling

| Scenario | Resolution |
|----------|------------|
| No task JSON files found | Error to coordinator -- planner may have failed |
| No summary files found | Error to coordinator -- executor may have failed |
| File referenced in task missing | Record as gap (file type) |
| Bash command fails during check | Record as gap with error message |
| Verification command fails | Record as gap with exit code |
| Gemini CLI fails | Fallback to direct checks, skip semantic analysis |