/validate-chunk

name: validate-chunk
description: "Enforcement layer for chunk and story validation. Invokes the chunk-validator agent (haiku), enforces the verdict, routes failures to refine-chunk or test-fix, captures CLI learnings. The orchestrator invokes this skill — never the agent directly."
version: 4.0.0
allowed-tools: ["Read", "Bash", "Glob", "Grep", "Task", "Skill"]

Validate Chunk Skill

You are the **enforcement layer** — the single gateway between the orchestrator and validation. You invoke the chunk-validator agent, enforce the verdict, route failures, and capture learnings. The orchestrator never interprets raw validation output — it only sees your structured result.

CRITICAL: FAILED Means FAILED

⛔ **A FAILED verdict is NEVER overridden.** You do not:

• Dismiss test failures as "unrelated to this story"
• Skip re-validation because "the fix is obvious"
• Let the orchestrator proceed past a FAILED result

**WARN means WARN — not a failure.** Warnings are informational on non-final chunks. They appear in the report but do NOT trigger refine-chunk routing. The agent promotes WARNs to FAILs on the final chunk automatically.

**ALL tests must pass before a chunk or story completes. No exceptions.**

When This Activates

• Orchestrator invokes after implementer completes a chunk (per-chunk mode)
• Orchestrator invokes after all chunks complete (story-final mode)
• User asks to "validate", "check", "verify" (manual mode — same behavior)

Orchestrator Context

The orchestrator passes enriched args with labeled fields:

• `CHUNK:` "N/total: chunk title" — which chunk to validate
• `FILES_CHANGED:` comma-separated paths — files the chunk touched
• `PM:` package manager (pnpm/npm/yarn/bun)
• `PROJECT_ROOT:` absolute path to the project
• `STORY_FILE:` absolute path to the story markdown file
• `MODE:` "per-chunk" (default) or "story-final"

**Fallback:** Args may be just a file path. Detect mode and gather context from state files.

Phase 1: Invoke Validation Agent

Launch the **chunk-validator** agent using the Task tool. The agent runs quality checks and returns a structured report.

Task tool:
  subagent_type: "craft:chunk-validator"
  model: "haiku"
  description: "Validate chunk [CHUNK]"
  prompt: "Run validation checks on this project.

    CHUNK: [CHUNK value]
    FILES_CHANGED: [FILES_CHANGED value]
    PROJECT_ROOT: [PROJECT_ROOT value]
    PM: [PM value]
    STORY_FILE: [STORY_FILE value]
    MODE: per-chunk
    PLUGIN_ROOT: [resolved ${CLAUDE_PLUGIN_ROOT} - the subagent cannot resolve the variable itself]"

**For story-final mode**, set CHUNK to "final":

Task tool:
  subagent_type: "craft:chunk-validator"
  model: "haiku"
  description: "Validate story-final"
  prompt: "Run story-final validation checks on this project.

    CHUNK: final
    FILES_CHANGED: [all files in story, or empty]
    PROJECT_ROOT: [PROJECT_ROOT value]
    PM: [PM value]
    STORY_FILE: [STORY_FILE value]
    MODE: story-final
    PLUGIN_ROOT: [resolved ${CLAUDE_PLUGIN_ROOT} - the subagent cannot resolve the variable itself]"

**NEVER use `run_in_background: true`.** Validation must run synchronously — wait for the agent to complete.

Phase 2: Parse Output

The agent outputs structured markdown. Parse these fields:

| Field | Format | Example | |-------|--------|---------| | Status | `**Status:** PASSED\|FAILED\|PARTIAL` | `**Status:** FAILED` | | Chunk | `**Chunk:** [value]` | `**Chunk:** 2/4: API routes` | | Mode | `**Mode:** per-chunk\|story-final` | `**Mode:** per-chunk` | | Fix count | `**Fix count:** N` | `**Fix count:** 0` | | Errors | `**Errors:**` section with structured error blocks | See below | | Warnings | `**Warnings:**` section with structured warning blocks | See below |

**Error block format** (may have multiple):

- **Check:** [check name]
- **Type:** [type-error|lint-error|build-error|test-failure|verified-gate-error]
- **File:** [file path]
- **Line:** [line number or -]
- **Message:** [error message]
- **Pattern:** [generalized pattern]

**Warning block format** (may have multiple):

- **Check:** [check name]
- **Type:** [lint-warning|any-type-warning|token-warning|verified-gate-warning|rot-warning]
- **File:** [file path]
- **Line:** [line number or -]
- **Message:** [warning message]

Phase 3 and Phase 4: Independent Concerns

Phase 3 (verdict routing) and Phase 4 (CLI error detection) run independently - order doesn't matter. Phase 4 never changes the verdict. Phase 5 (event emission) always runs last.

Phase 3: Enforce Verdict and Route

If PASSED

**Gate reconcile beat (both per-chunk branches):** Read `${CLAUDE_PLUGIN_ROOT}/commands/references/gate-reconcile.md` and run it inline (NOT via the Skill tool) BEFORE complete-chunk.sh. Steady state (Gates row `full coverage`, no rot-warnings) exits silently; an uncovered undecided signal gets the offer AskUserQuestion (accept wires it; decline is risk-confirmed then permanently silent; no answer stays pending for the next attended PASS). Never fires on FAILED.

Per-chunk mode (non-final):

• Run complete-chunk.sh: `bash ${CLAUDE_PLUGIN_ROOT}/hooks/scripts/complete-chunk.sh`
• Emit validation event (Phase 5)
• **Write a continuation breadcrumb** before outputting the summary. This protects the "continue to next chunk" step - if the agent stops after outputting the summary, the Stop hook catches it:

cat > "${CRAFT_PROJECT_ROOT:-.}/.craft/.continuation" << CRUMB
ACTION: Continue implementation loop - checkpoint, then implementer for next chunk, then validate-chunk
SKILL: craft:craft-story-implement
ARGS: Continue from chunk ${CHUNK} - next chunk ready
WRITTEN_BY: validate-chunk
TIMESTAMP: $(date -u +%Y-%m-%dT%H:%M:%S)
CRUMB

• Output validation summary with `>>> NEXT ACTION:` directive, then execute it immediately
• The breadcrumb is cleaned up at the START of the next validation cycle (not this one)

Per-chunk mode (final chunk):

• Run complete-chunk.sh: `bash ${CLAUDE_