validating

Forge: Validate

Overview

Run a comprehensive pre-flight check on the session plan before execution. This catches errors that would otherwise waste agent tokens and time. Can be run standalone via forge validate or is called automatically as Step 1 of forge execute.

Session

Session Resolution

1. From $ARGUMENTS: If the first token is a number or short identifier, use it as the session ID.
2. Auto-detect existing sessions:

   ls .forge/sessions/ 2>/dev/null | sort
   

   • 0 sessions → error: "No forge sessions found. Run forge plan first."
   • 1 session → use it automatically; print "Validating session <id>"
   • 2+ sessions → list them, AskQuestion "Which session to validate?"

SESSION_DIR = .forge/sessions/<id>/ — all file paths in this skill are relative to this directory.

Git namespace for this session: branches forge/s<id>/*, tags forge/checkpoint/s<id>/*.

Validation Checks

Run ALL checks and collect results. Do not stop at the first failure — report everything at once.

1. Plan Exists and Parses

• $SESSION_DIR/plan.md exists
• File contains a ## Tasks section
• At least one task is defined (### T<n>:)
• Each task has: Status, Category, Depends on, Files, Complexity, Description

2. DAG Validity

• All dependency references (e.g., "Depends on: T1, T2") point to tasks that exist
• Dependencies form a DAG — no cycles
• Every task is reachable (no orphans disconnected from the graph)

3. File Conflict Check

• No two tasks in the SAME parallel batch share any file
• If two tasks share a file, they must be in different batches or the batch must be sequential

4. Execution Batches Consistency

• An ## Execution Batches table exists
• All tasks appear in exactly one batch
• Batch ordering respects dependencies (a task's dependencies must all be in earlier batches)
• No batch has more than 4 parallel tasks

5. File Existence

For each task, check if the listed files exist:

• Existing files (to modify): Must exist on disk. Flag missing files as errors.
• New files (to create): Parent directory should exist. Flag if the parent directory doesn't exist.

Heuristic: If a file path doesn't exist AND the task description says "create" or "new", treat it as a new file (not an error). Otherwise, flag it.

6. Git State

• Working tree is clean (git status --porcelain returns empty or only untracked files in .forge/)
• Current branch is not detached HEAD
• No uncommitted changes that would conflict with plan files

7. Worktree Cleanliness

• No leftover worktrees in $SESSION_DIR/worktrees/ from previous runs
• No stale forge branches for this session (git branch --list "forge/s<id>/*")
• If stale worktrees/branches found: report them and suggest forge abort <id> to clean up

8. Checkpoint State

• Check for existing forge checkpoint tags for this session (git tag -l "forge/checkpoint/s<id>/*")
• If tags exist from a previous run, warn the user (they might want to forge rollback <id> first)

Output Format

## Forge Validation Report (session <id>)

### ✅ Passed
- Plan parses correctly (N tasks, M batches)
- DAG is valid (no cycles)
- No file conflicts in parallel batches
- Git working tree is clean

### ⚠️ Warnings
- Stale forge branch found: `forge/s<id>/batch-2-1708300000` — run `forge abort <id>` to clean up
- Checkpoint tags from previous run found — consider `forge rollback <id>` if needed

### ❌ Errors
- T5 references `src/missing-file.ts` which does not exist
- T3 depends on T99 which is not defined in the plan
- Batch 2 has T4 and T6 sharing `src/shared.ts` with strategy=parallel

### Verdict: READY | NOT READY

Rules

• This is a READ-ONLY operation — do not modify any files
• Report ALL issues, not just the first one
• Distinguish between errors (blocking) and warnings (informational)
• Verdict is READY only if there are zero errors (warnings are okay)
• If called from forge execute, return the verdict so execution can proceed or abort