phase-checkpoint

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

Workflow

Copy this checklist and track progress:

Phase Checkpoint Progress:
- [ ] Step 1: Context detection
- [ ] Step 2: Tool availability & config
- [ ] Step 3: Local verification (automated, optional, manual)
- [ ] Step 4: Cross-model review (Codex)
- [ ] Step 5: Production verification
- [ ] Step 6: State update
- [ ] Step 7: Generate report
- [ ] Step 8: 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. •Otherwise:
   • •PROJECT_ROOT = current working directory
   • •MODE = "greenfield"

Directory Guard: Confirm EXECUTION_PLAN.md exists. If not, STOP and tell user to cd into their project directory.

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

Step 2: Tool Availability & Config

Check which optional tools are available:

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

Read .claude/verification-config.json from PROJECT_ROOT. If missing or incomplete, run /configure-verification first.

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 3: Local Verification (Must Pass First)

IMPORTANT: All local verification must pass before production verification.

See VERIFICATION.md for detailed check procedures.

Automated Checks

Run these using commands from verification-config:

1. •Tests (commands.test)
2. •Type Checking (commands.typecheck)
3. •Linting (commands.lint)
4. •Build (commands.build)
5. •Dev Server (devServer.command)
6. •Security Scan
7. •Code Quality Metrics

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
3. •Generate detailed verification guide for remaining items
4. •Ask human for batch confirmation
5. •Update checkboxes in EXECUTION_PLAN.md

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

Step 4: 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

1. •

   Gather phase context:

   bash

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

2. •

   Invoke /codex-review with appropriate flags:

   code

   /codex-review --research "{technologies}" security
   

   The /codex-review skill handles:

   • •Branch diff gathering
   • •Prompt generation with research instructions
   • •Codex CLI invocation
   • •Result parsing
3. •

   Process results:

   Codex Status	Checkpoint Action
   pass	Continue, note in report
   pass_with_notes	Show recommendations, continue
   needs_attention	Show critical issues, ask user how to proceed
   skipped	Note unavailable, continue
   error	Note error, continue

4. •

   For needs_attention status:

   • •Display critical issues from Codex
   • •Ask user: "Address Codex findings before proceeding?"
     • •Yes → List issues to fix, pause checkpoint
     • •No → Continue, note as accepted risk
   • •Critical issues do NOT auto-block (user decides)

Output

Cross-Model Review (Codex):
- Status: PASS | PASS WITH NOTES | NEEDS ATTENTION | SKIPPED
- Critical Issues: {N}
- Recommendations: {N}
{If issues}
- Top Issue: {description}
{/If}

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 5: Production Verification

BLOCKED until all Local Verification passes.

When local passes, verify:

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

Step 6: 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,
      "coverage_percent": 85,
      "manual_verified": true,
      "codex_review": {
        "status": "pass | pass_with_notes | needs_attention | skipped",
        "critical_issues": 0,
        "recommendations": 2,
        "user_accepted_risks": []
      }
    }
  }]
}

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

Step 7: 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
- Security: PASSED | FAILED

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

Manual Checks:
- Automated: {X} items
- Truly manual: {Y} items

Local Verification: ✓ PASSED | ✗ FAILED

---

## Cross-Model Review (Codex)

Status: PASS | PASS WITH NOTES | NEEDS ATTENTION | SKIPPED
{If not skipped}
- Critical Issues: {N}
- Recommendations: {N}
{If needs_attention}
- User Action: Addressed | Accepted as risk
{/If}
{/If}

{If has recommendations}
Top Recommendations:
1. {recommendation}
2. {recommendation}
{/If}

---

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

---

Overall: Ready to proceed | Issues to address

Step 8: Auto-Advance

See AUTO_ADVANCE.md for auto-advance logic.

Summary: If all checks pass and no manual items remain, automatically invoke /phase-prep {N+1}.

Codex review and auto-advance: Codex findings do NOT block auto-advance unless user explicitly chooses to address them. The review is advisory.

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 manual verification items cannot be completed:

• •Ask user: "Skip this item and document reason?" vs "Block until complete"
• •If skipping: Record in DEFERRED.md with reason and timestamp
• •Note: Skipped items don't count as PASSED for auto-advance

If verification config is missing critical commands:

• •STOP and run /configure-verification
• •Do NOT substitute or guess commands
• •Report which commands are missing

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:

• •Present issues to user with context
• •Ask: "Address before proceeding or accept as noted risk?"
• •If user chooses to proceed: Log as "accepted risk" in state
• •Do NOT auto-block — cross-model review is advisory

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