verify-acceptance-criteria

What this skill does

# Verify Acceptance Criteria

Mechanically checks all acceptance criteria from an implementation plan against the actual codebase. Delegates verification to the `task-verifier` agent and reports results.

**Announce at start:** "Running verify-acceptance-criteria to check implementation against the plan."

## When to Use

- After implementing one or more tasks from a plan
- Before claiming work is complete
- Before committing or creating a PR

## Optional Args (used when invoked from orchestrator dispatch)

When invoked as a Pattern B consolidator subagent (per #251 Wave 3 phase 4), the orchestrator passes these arguments so the skill can skip the hoisted task-verifier dispatch and write its structured return contract back to a tmp JSON file:

- `verifier_report_path: <absolute-path-to-report-md>` — when set, the skill skips Step 3's `task-verifier` dispatch (the orchestrator has already executed it) and reads the pre-written verification report from this Markdown file. The report follows the format defined in `agents/task-verifier.md` Step 4.
- `write_contract_to: <absolute-path-to-json>` — when set, writes the structured return contract directly to this JSON file path after Step 4 (Present Results) completes (see Step 6 below). **Unlike `design-document`, this is a plain JSON file path, not a state-file YAML path.** verify-acceptance-criteria does not own a `phase_summaries` bucket — see "Why no state-file write" below.

Both args are optional. If `verifier_report_path` is absent, Step 3 dispatches the task-verifier as before. If `write_contract_to` is absent, Step 6 is skipped — the skill behaves identically to its inline-invocation form.

**Why no state-file write:** the four `phase_summaries` buckets (`brainstorm`, `design`, `plan`, `implementation`) are all claimed by phase-boundary writes. Verify-acceptance-criteria is a verification step within the implementation phase, not a phase that owns a bucket; reusing `implementation.return_contract` would collide with the future Phase 6 (`subagent-driven-development`) Pattern B contract. The contract is consumed once by the orchestrator's validator and discarded — no cross-compaction reader needs it from the state file.

## Format Detection

Before extracting criteria, determine which format the plan file uses.

See `references/xml-plan-format.md` for the canonical schema. See `references/xml-plan-format-runtime.md` for the detection algorithm, error handling rules, and edge cases. Summary:

1. Read the first 50 lines of the plan file
2. Track code-fence state: toggle `in_fence` on each line that starts with ` ``` `
3. For each non-fenced line: check if it matches `/^<plan version="/`
4. If match found → XML mode
5. Before committing to XML mode: scan the full file for `</plan>`. If absent → log warning
   "plan appears truncated — treating as prose" and use Prose mode
6. If no match in first 50 lines → Prose mode (existing behavior unchanged)

### XML Extraction

For XML plans:

1. Extract `<task id="N" status="...">` blocks
2. **Duplicate ID check:** If any `id=` value appears more than once → announce
   "XML structure invalid — falling back to prose parser" and use prose mode.
3. For each task:
   - Task status: read `status=` attribute (`pending`/`in-progress`/`done`) — replaces Progress
     Index comment parsing. Missing or unexpected `status=` → treat as `pending`.
   - Criteria: extract `<criterion>` elements from `<criteria>` block:
     - Structured: `{what, how, command}` from `<what>/<how>/<command>` children — no regex needed
     - Manual: `type="manual"` attribute → treat as `[MANUAL]` (CANNOT_VERIFY)
4. Pass the extracted flat criterion list to Step 3 (task-verifier) — same format as prose path

**Malformed XML:** the following conditions trigger full prose fallback (see reference doc for
per-criterion flags that don't trigger fallback):
- `</plan>` absent → "plan appears truncated — treating as prose"
- `<task>` unclosed → "malformed task block at id N — falling back to prose"
- `<criteria>` unclosed → "malformed criteria block in task N — falling back to prose"
- Duplicate task IDs → "duplicate task ID N — plan is invalid, falling back to prose"

**Prose mode:** existing Step 1-5 logic runs unchanged.

## Process

### Step 0: Check for Existing PR

Before doing any work, check if a PR already exists for the current branch:

```bash
gh pr view --json url,state 2>/dev/null
```

**If a PR exists:** Announce "A PR already exists for this branch. Verification runs before PR creation in the standard workflow. Skipping." Exit gracefully — do not launch the task-verifier agent.

**If no PR exists:** Continue with Step 1.

### Step 1: Find the Plan File

**If `plan_file` is provided in ARGUMENTS** (e.g., `plan_file: /abs/path/to/plan.md`): Parse the value and attempt to read that path. If the file exists, use it directly — skip the Glob and user confirmation, and announce: "Using provided plan file: [path]". If the file does not exist, announce: "Provided plan_file not found: [path]. Falling back to discovery." and continue with the Otherwise branch below.

**Otherwise, look for the plan file:**
1. If the user specified a path, use it
2. Otherwise, find the most recently modified `.md` file in the plans directory:

```
Glob: docs/plans/*.md
```

If no `docs/plans/` directory exists, check for plan files in common locations:
- `plans/*.md`
- `docs/*.md` (look for files with "plan" or "implementation" in the name)

Pick the most recent file. Confirm with the user: "Verifying against plan: `[path]`. Is this correct?"

**Split plan detection:** After the plan file is found, read it and check for the presence of `## Phase Manifest`. If found, it is a split plan:
1. Parse the `## Phase Manifest` table to extract all phase file paths. (The table has at minimum a File column containing relative paths like `docs/plans/YYYY-MM-DD-feature-plan-phase-1.md`.)
2. Read each phase file.
3. Treat the combined content of all phase files as the plan content for Step 2's criteria extraction.

If `## Phase Manifest` is absent, proceed with the single plan file content as before — existing behavior is unchanged.

### Step 2: Extract Acceptance Criteria

**XML plans:** Use the XML Extraction algorithm from the Format Detection section above. Build
the same flat criterion list (task number, title, criterion items) as the prose path produces —
the task-verifier in Step 3 receives an identical input regardless of source format.

**Prose plans (existing behavior):**

**Note for split plans:** If the plan was detected as a split plan in Step 1, extract acceptance criteria from all phase files (not the index file). Label each task's criteria with its source phase file for traceability in the verification report (e.g., `Task 1 [from phase-1]`). When constructing the Step 3 verifier prompt, use `Task N [from phase-N]: [Title]` as the task identifier for each task from a phase file.

Read the plan file(s) identified in Step 1 (for split plans, this means all phase files; for single-file plans, this means the plan file directly) and extract all `**Acceptance Criteria:**` sections.

For each task, collect:
- Task number and title
- All criteria items (lines starting with `- [ ]`)
- Note any `[MANUAL]` prefixed criteria (these will be flagged for human review)

If a specific task was requested, only extract criteria for that task.

### Step 3: Delegate to Task Verifier

**Pattern B consolidator-mode early exit:** If `verifier_report_path` is set in ARGUMENTS, the orchestrator has already dispatched the task-verifier and written its detailed Markdown report to that path. Read the file, treat its content as the verification report produced by Step 3, and skip the `Task()` dispatch below. Jump directly to Step 4 (Present Results) using the loaded report. This branch exists for the Pattern B subagent dispatch wired in `skills/start/SKILL.md` — see "Verify Acceptance Criteria — Pattern B Dispatch" in that file.

Use the Task t