phase-checkpoint

name	phase-checkpoint
description	Run checkpoint criteria after completing a phase. Use after /phase-start completes all tasks to verify quality gates before proceeding.
argument-hint	["phase-number"]
allowed-tools	Bash, Read, Edit, Glob, Grep, Task, AskUserQuestion, WebFetch, WebSearch

Phase $1 is complete. Run the checkpoint criteria from EXECUTION_PLAN.md.

AUTONOMY RULE: Never invoke skills via the Skill tool mid-checkpoint — it creates a turn boundary that breaks procedural flow. Use the Task tool (subagent) for any delegated work. Do NOT use AskUserQuestion during the checkpoint — it pauses the auto-advance chain. If something is ambiguous, use a deterministic default and report it.

Workflow

Copy this checklist and track progress:

Phase Checkpoint Progress:
- [ ] Step 1: Context detection
- [ ] Step 2: Plan status guard
- [ ] Step 3: Tool availability & config
- [ ] Step 4: Local verification (automated, optional, manual)
- [ ] Step 5: Cross-model review (Codex)
- [ ] Step 6: Production verification
- [ ] Step 7: State update
- [ ] Step 8: Generate report
- [ ] Step 9: Auto-advance check

Step 1: Context Detection

Determine working context:

1. If CWD matches */features/*:

   • PROJECT_ROOT = parent of parent of CWD
   • MODE = "feature"

2. If CWD matches */plans/greenfield*:

   • PROJECT_ROOT = parent of parent of CWD
   • MODE = "greenfield"

3. Otherwise:

   • PROJECT_ROOT = current working directory
   • MODE = "greenfield-legacy"

Directory Guard: Confirm EXECUTION_PLAN.md exists. If not, STOP and tell user to cd into the scoped directory containing the active execution plan. If plans/greenfield/EXECUTION_PLAN.md exists in the current directory, tell them to cd plans/greenfield first.

Context Check: If context is below 40% remaining, run /compact first.

Step 2: Plan Status Guard

Read PROJECT_ROOT/plans/PLAN_STATUS.md if it exists.

• Derive the current scoped path from CWD: plans/greenfield/ for greenfield mode, or features/<name>/ for feature mode.
• If CWD is under plans/archive/ or features/archive/, STOP. Archived plans are historical context only.
• If Current status is not active, STOP and report that the current plan is not implementable.
• If Current plan does not match the current scoped path, STOP. Report the current active plan path and tell the user to run /phase-checkpoint $1 from that directory instead.
• If the manifest is missing, continue with the legacy directory convention.

Step 3: Tool Availability & Config

Check which optional tools are available:

Tool	Check Method	Fallback
ExecuteAutomation Playwright	Check for mcp__playwright__*	Next in chain
Browser MCP	Check for mcp__browsermcp__*	Next in chain
Chrome DevTools MCP	mcp__chrome-devtools__list_pages	Manual verification
code-simplifier	Check if agent type available	Skip
Codex CLI	codex --version	Skip cross-model review

Browser fallback chain: ExecuteAutomation → Browser MCP → Microsoft Playwright → Chrome DevTools → Manual

Read .claude/verification-config.json from PROJECT_ROOT. If missing entirely, run /configure-verification. Omitted keys mean those checks are not configured — skip them rather than blocking.

Read .claude/settings.local.json for cross-model review config:

{
  "codexReview": {
    "enabled": true,
    "triggerOn": ["phase-checkpoint"]
  }
}

If codexReview is not configured, default to enabled: true when Codex CLI is available.

Step 4: Local Verification (Must Pass First)

IMPORTANT: All local verification must pass before production verification.

See VERIFICATION.md for detailed check procedures. See also DEFERRED_QUEUE.md for the deferred review queue format and processing rules.

Automated Checks

Run these using commands from verification-config (skip any that are not configured):

1. Tests (commands.test) — skip if not in config
2. Type Checking (commands.typecheck) — skip if not in config
3. Linting (commands.lint) — skip if not in config
4. Build (commands.build) — skip if not in config
5. Mutation Tests (commands.mutation_test) — skip if not in config
6. Dev Server (devServer.command) — skip if not in config
7. Security Scan
8. Code Quality Metrics

If commands.mutation_test is configured, treat failures as a local verification failure (it is part of the quality gate).

Optional Checks

• Code Simplification (if code-simplifier available)
• Browser Verification (if browser tools available)
• Technical Debt Check (if skill exists)

Manual Verification

1. Extract manual items from "Phase $1 Checkpoint" in EXECUTION_PLAN.md
2. Attempt automation using auto-verify skill (via Task tool, not Skill tool)
3. Classify remaining items:
   • MANUAL:DEFER → enqueue to deferred review queue (see DEFERRED_QUEUE.md)
   • MANUAL (blocking) → stop checkpoint and stop auto-advance
4. If blocking items exist: report them in the checkpoint output and stop. Do NOT use AskUserQuestion — just list the items and halt auto-advance.
5. If only deferred items: continue, report queue status
6. Update checkboxes in EXECUTION_PLAN.md

For external integrations, follow DOCS_PROTOCOL.md to fetch latest documentation.

Step 5: Cross-Model Review (Codex)

Purpose: Get a second opinion from a different AI model to catch blind spots.

When This Step Runs

This step runs if ALL of these conditions are true:

• Codex CLI is available (codex --version succeeds)
• codexReview.enabled is true (or not configured, defaulting to true)
• "phase-checkpoint" is in codexReview.triggerOn (or not configured)

Execution

IMPORTANT — Invocation Method: Do NOT invoke /codex-review via the Skill tool. The Skill tool creates a turn boundary that breaks the checkpoint's procedural flow and prevents auto-advance from continuing. Use the Task tool instead.

1. Gather phase context:

   # Identify technologies from changed files for --research flag
   # Check package.json, imports in changed files
   

2. Launch Task subagent to perform the Codex review inline:

   • subagent_type: general-purpose
   • Include in the prompt:
     • The technologies/research topics identified in step 1
     • Any focus area (e.g., security)
     • The base branch and model from config
   • Instruct the subagent to: a. Read .claude/skills/codex-review/SKILL.md and follow Steps 1-5 b. Read supporting files as needed (CODEX_INVOCATION.md, PROMPT_TEMPLATE.md, EVALUATION_PRACTICES.md) c. Return structured JSON with status, critical_issues, recommendations, positive_findings

   The Task tool returns results to the current turn, preserving checkpoint state.

3. Process results from the Task subagent:

   Codex Status	Checkpoint Action
   pass	Continue, note in report
   pass_with_notes	Auto-implement recommendations, continue
   needs_attention	Auto-implement all findings, continue
   skipped	Note unavailable, continue
   error	Note error, continue

Auto-Implement Findings

When Codex returns findings (pass_with_notes or needs_attention), implement them automatically. Do NOT ask the user — this keeps the auto-advance chain flowing.

1. Launch Task subagent to implement all findings:

   • subagent_type: general-purpose
   • Include in the prompt:
     • All critical issues with file:line locations and suggestions
     • All recommendations with file:line locations and suggestions
     • Instruct: "Implement each fix. If a suggestion is too vague to act on (no specific file/line or actionable change), skip it and note why. Do NOT use AskUserQuestion — if anything is ambiguous, skip it. Do NOT create new files unless a fix explicitly requires it."
   • The subagent edits files and returns a summary of what it changed

2. Re-run automated verification (same commands from Step 4):

   • Tests, typecheck, lint, build — whatever is configured in verification-config
   • This confirms the fixes don't break anything

3. Handle re-verification results:

   Outcome	Action
   All checks pass	Commit: git add -u && git commit -m "fix: address Codex review findings (phase $1 checkpoint)", note "{N} findings auto-fixed" in report
   Any check fails	Revert: git checkout -- ., note "fixes reverted — broke verification" in report, log findings to deferred queue

   Git safety notes:

   • Use git add -u (tracked files only) — never git add -A which can stage untracked artifacts
   • Commit only after verification passes — no commit to undo on failure
   • git checkout -- . reverts working tree changes without needing git reset --hard
   • If pre-commit hooks fail the commit, treat as "skip auto-commit" and continue

4. Continue to Step 6 regardless of outcome — Codex findings never block.

Output

Cross-Model Review (Codex):
- Status: PASS | PASS WITH NOTES | NEEDS ATTENTION | SKIPPED
- Findings: {N} critical, {M} recommendations
- Auto-implemented: {X} fixes applied, {Y} skipped (too vague)
- Verification: PASSED | REVERTED (logged to deferred queue)

Skip Conditions

Skip this step (mark as SKIPPED) if:

• Running inside Codex CLI ($CODEX_SANDBOX is set) — /codex-review detects this automatically
• Codex CLI not installed
• codexReview.enabled is explicitly false
• Phase has fewer than 3 tasks (trivial phase)
• --skip-codex flag passed to checkpoint

Step 6: Production Verification

BLOCKED until all Local Verification passes.

When local passes, verify:

• Staging/production deployment
• External integrations
• Production-only manual checks

Step 7: State Update

After checkpoint passes, update .claude/phase-state.json:

{
  "phases": [{
    "number": 1,
    "status": "CHECKPOINTED",
    "completed_at": "{ISO timestamp}",
    "checkpoint": {
      "tests_passed": true,
      "type_check_passed": true,
      "lint_passed": true,
      "security_passed": true,
      "mutation_tests_passed": true,
      "coverage_percent": 85,
      "manual_verified": true,
      "codex_review": {
        "status": "pass | pass_with_notes | needs_attention | skipped",
        "critical_issues": 0,
        "recommendations": 2,
        "auto_fixed": 2,
        "fix_skipped": 0,
        "fix_reverted": false
      }
    }
  }]
}

Write checkpoint report to .claude/verification/phase-$1.md and append to .claude/verification-log.jsonl.

Step 8: Report

Phase $1 Checkpoint Results
===========================

Tool Availability:
- ExecuteAutomation Playwright: ✓ | ✗
- Browser MCP: ✓ | ✗
- Chrome DevTools MCP: ✓ | ✗
- code-simplifier: ✓ | ✗
- Codex CLI: ✓ | ✗

## Local Verification

Automated Checks:
- Tests: PASSED | FAILED
- Type Check: PASSED | FAILED | SKIPPED
- Linting: PASSED | FAILED | SKIPPED
- Build: PASSED | FAILED | SKIPPED
- Mutation Tests: PASSED | FAILED | SKIPPED
- Security: PASSED | FAILED

Optional Checks:
- Browser Verification: PASSED | SKIPPED
  - Target: {URL}
- Tech Debt: PASSED | NOTES | SKIPPED

Manual Checks:
- Automated: {X} items
- Blocking manual: {Y} items
- Deferred: {Z} items (queued for later review)
- Total deferred queue: {M} items across {P} phases

Local Verification: ✓ PASSED | ✗ FAILED

---

## Cross-Model Review (Codex)

Status: PASS | PASS WITH NOTES | NEEDS ATTENTION | SKIPPED
{If not skipped}
- Findings: {N} critical, {M} recommendations
- Auto-implemented: {X} fixes applied, {Y} skipped (too vague)
- Verification: PASSED | REVERTED (logged to deferred queue)
{If reverted}
- Reverted fixes logged to deferred queue for later review
{/If}
{/If}

---

## Production Verification
{items or "Blocked: Complete local verification first"}

---

Overall: Ready to proceed | Issues to address

Step 9: Auto-Advance

See AUTO_ADVANCE.md for auto-advance logic.

Summary: If all checks pass and no blocking manual items remain, automatically invoke /phase-prep {N+1}. MANUAL:DEFER items are queued and do not block.

Codex review and auto-advance: Codex findings are auto-implemented inline. If fixes pass re-verification they are committed; if they fail, they are reverted and logged to the deferred queue. Either way, auto-advance is never blocked.

Error Handling

Situation	Action
EXECUTION_PLAN.md not found in working directory	STOP and tell user to cd into the project directory containing EXECUTION_PLAN.md
verification-config.json missing entirely	Run /configure-verification to auto-detect; omitted keys in an existing config are intentional and should be skipped
Automated check command fails to execute (e.g., npm not found)	Mark that specific check as FAILED (not SKIPPED), continue remaining checks, and report tool failure in summary
Codex CLI times out or returns an error	Mark cross-model review as SKIPPED with reason, do NOT block checkpoint, suggest manual /codex-review afterward
Auto-implemented Codex fixes break re-verification	Revert changes with git checkout -- ., log findings to deferred queue, and continue without blocking

---

When Checkpoint Cannot Pass

If both local AND production verification fail:

• Report all failures clearly, separated by category
• Do NOT suggest skipping checks
• Prioritize: Fix local failures first (they often cause production failures)
• Suggest: Run /phase-start $1 to address failing tasks before re-running checkpoint

If blocking manual verification items remain after auto-verify:

• Stop the checkpoint and report which items blocked it
• Do NOT use AskUserQuestion — just halt and list the items
• The user can re-run /phase-checkpoint $1 after manual resolution
• Note: Blocking items prevent auto-advance (this is by design)

If verification config file is missing entirely:

• Run /configure-verification to auto-detect
• Omitted keys in an existing config are intentional — skip those checks

If auto-advance chain should stop:

• Report: "Auto-advance stopped at Phase $1 checkpoint"
• List specific blocking items
• Provide: "Run /phase-checkpoint $1 again after resolving issues"

If a tool consistently fails mid-checkpoint:

• Mark that specific check as FAILED (not SKIPPED)
• Continue with remaining checks
• Report tool failure in final summary
• Suggest troubleshooting steps for the failing tool

If Codex review times out or errors:

• Mark as SKIPPED with reason
• Do NOT block checkpoint progress
• Note in report: "Cross-model review unavailable: {reason}"
• Suggest: Re-run /codex-review manually after checkpoint if desired

If Codex finds critical issues:

• Auto-implement all findings (see "Auto-Implement Findings" in Step 5)
• If fixes pass re-verification, commit with git add -u and continue
• If fixes break re-verification, revert with git checkout -- . and log to deferred queue
• Continue without pausing — cross-model review never blocks
• Do NOT use AskUserQuestion — this breaks auto-advance

---

REMINDER: Local verification must pass before production verification. If any local check fails, stop and report — do not proceed to production checks.